@saasicat/core 1.0.0-rc.0

package/dist/index.d.cts

@@ -0,0 +1,4809 @@
+/** Start of day (00:00 UTC) of the moment — for day-inclusive date comparisons. */
+declare function startOfUtcDay(date: Date): Date;
+/** `<=` upper bound for a date (structurally Prisma-compatible). */
+interface DateAtOrBefore {
+    lte: Date;
+}
+/** `>=` lower bound (day-inclusive) for a date (structurally Prisma-compatible). */
+interface DateAtOrAfter {
+    gte: Date;
+}
+/** `>` upper bound (exclusive, timestamp) for a date. */
+interface DateAfter {
+    gt: Date;
+}
+/** `OR` block of the validity window; exactly one date field per variant. */
+type ValidityWindowClause = {
+    validFrom: DateAtOrBefore | null;
+} | {
+    validUntil: DateAtOrAfter | null;
+};
+/** Optional `OR` block for models with `endsAt` (precise admin termination). */
+type EndsAtClause = {
+    endsAt: DateAfter | null;
+};
+/**
+ * Structural counterpart to the `*PlanVersionWhereInput` excerpt for models
+ * without `endsAt` (e.g. `CatalogPlanVersion`).
+ */
+interface ActivePlanVersionWhere {
+    publishedAt: {
+        not: null;
+    };
+    AND: Array<{
+        OR: ValidityWindowClause[];
+    }>;
+}
+/** Like {@link ActivePlanVersionWhere}, additionally with `endsAt` clause. */
+interface ActivePlanVersionWhereWithEndsAt {
+    publishedAt: {
+        not: null;
+    };
+    AND: Array<{
+        OR: Array<ValidityWindowClause | EndsAtClause>;
+    }>;
+}
+/**
+ * Builds the time-window WHERE for the PlanVersion active at `asOf`:
+ *   `publishedAt IS NOT NULL`
+ *   `(validFrom IS NULL OR validFrom <= asOf)`
+ *   `(validUntil IS NULL OR validUntil >= startOfUtcDay(asOf))`  // day-inclusive
+ *   with `withEndsAt`: additionally `(endsAt IS NULL OR endsAt > asOf)`.  // precise
+ *
+ * `planId` stays with the caller (repo-specific type). Matching Prisma
+ * `orderBy` for PostgreSQL:
+ * `[{ validFrom: { sort: 'desc', nulls: 'last' } }, { version: 'desc' }]`.
+ */
+declare function buildActivePlanVersionWhere(asOf: Date, options?: {
+    withEndsAt?: false;
+}): ActivePlanVersionWhere;
+declare function buildActivePlanVersionWhere(asOf: Date, options: {
+    withEndsAt: true;
+}): ActivePlanVersionWhereWithEndsAt;
+/**
+ * Model-neutral name for {@link ActivePlanVersionWhere}. Bundle- and
+ * PlanVersion repositories share the same published validity-window rules.
+ */
+type ActiveVersionWhere = ActivePlanVersionWhere;
+/** Model-neutral counterpart that additionally checks an `endsAt` timestamp. */
+type ActiveVersionWhereWithEndsAt = ActivePlanVersionWhereWithEndsAt;
+/**
+ * Model-neutral alias for {@link buildActivePlanVersionWhere}. The original
+ * export remains available for backwards compatibility.
+ */
+declare const buildActiveVersionWhere: typeof buildActivePlanVersionWhere;
+
+type FeatureKey = string;
+type PlanId = string;
+type QuotaKey = string;
+interface FeatureDef {
+    key: FeatureKey;
+    label?: string;
+    icon?: string;
+    /** CORE / ADVANCED / PRO / BUSINESS / ENTERPRISE_ONLY — convention. */
+    tier?: string;
+    plannedOnly?: boolean;
+}
+interface PlanDef {
+    id: PlanId;
+    name?: string;
+    tagline?: string;
+    /** false = not selectable in self-service onboarding. Default: true. */
+    marketed?: boolean;
+    /** Highlighted card in onboarding (max. 1 per catalog). */
+    popular?: boolean;
+    /** Net monthly price. null = on request. */
+    monthlyNet?: number | null;
+    /** Net total amount per year. null = monthly only. */
+    yearlyNet?: number | null;
+    /** Map quotaKey → max value. -1 = unlimited. */
+    quotas: Record<QuotaKey, number>;
+    features: FeatureKey[];
+}
+/** App-wide marketing configuration. */
+interface PlanCatalogMarketing {
+    /**
+     * Allowed language pool that the app may market. First = default
+     * locale. From it, the SuperAdmin activates a subset in the marketing
+     * catalog (LocaleManager).
+     */
+    availableLocales: string[];
+}
+/**
+ * App identity block for branding + version. Consumed by the `AdminPublicBootController`
+ * and the `AdminManifestConfigFactory`; the SuperAdmin UI (platform
+ * LoginPage, AdminLayout brand block) reads the same fields via PublicBoot.
+ *
+ * `name` = brand display name (e.g. "DemoApp", "ClubApp").
+ * `label` = tag/subtitle in the brand block (e.g. "SuperAdmin").
+ * `version` = app version string (build info).
+ * `icon` = 2-character abbreviation for the logo badge (e.g. "ma", "da").
+ * `logoUrl` = optional URL to a PNG/SVG; if set, the UI renders an <img>
+ *             instead of the initials badge.
+ */
+interface PlanCatalogApp {
+    name: string;
+    label?: string;
+    version?: string;
+    icon?: string;
+    logoUrl?: string;
+}
+interface PlanCatalog {
+    schemaVersion: 1;
+    projectKey: string;
+    /** App identity (branding + version), see PlanCatalogApp. Optional. */
+    app?: PlanCatalogApp;
+    /** ISO-4217 currency code. */
+    currency: string;
+    /** VAT rate in percent. */
+    vatRate: number;
+    /** App-wide marketing configuration. Optional. */
+    marketing?: PlanCatalogMarketing;
+    features?: FeatureDef[];
+    /**
+     * Optional. When omitted, plans come exclusively from the
+     * AdminUI / DB table (Plans/PlanVersions lifecycle).
+     */
+    plans?: PlanDef[];
+}
+
+/** Backend capability key, convention: domain.action[.action]. */
+type CapabilityKey = string;
+/** Frontend action-registry key. Same convention as CapabilityKey. */
+type ActionKey = CapabilityKey;
+/** Lookup key in the static extensions: map of the UI build. */
+type ComponentKey = string;
+interface AdminManifest {
+    schemaVersion: 1;
+    project: {
+        key: string;
+        displayName: string;
+        /** Tag/subtitle (e.g. "SuperAdmin"). From `saas.yaml#app.label`. */
+        label?: string;
+        /** Short abbreviation for the logo badge (e.g. "ma", "da"). From `saas.yaml#app.icon`. */
+        icon?: string;
+        logoUrl?: string;
+        environment?: 'production' | 'staging' | 'development';
+        /**
+         * Allowed locale pool from the app config (`saas.yaml`
+         * `marketing.availableLocales`). First = default..
+         */
+        availableLocales?: string[];
+        /** Default locale; equals `availableLocales[0]`. */
+        defaultLocale?: string;
+    };
+    build: {
+        platformPackageVersion: string;
+        appVersion: string;
+        manifestHash: string;
+    };
+    planCatalogSnapshot: {
+        source: string;
+        hash: string;
+        currency: string;
+        vatRate: number;
+        features?: FeatureDef[];
+        plans: PlanDef[];
+    };
+    /** Map CapabilityKey → boolean. Manifest is never a security source. */
+    capabilities: Record<CapabilityKey, boolean>;
+    navigation: {
+        standardPages: Partial<Record<StandardPageKey, StandardPageDef>>;
+        projectPages?: ProjectPageDef[];
+    };
+    dashboard?: {
+        kpiCards?: KpiCardDef[];
+    };
+    tenants?: {
+        columns?: TenantColumnDef[];
+        actions?: TenantActionDef[];
+    };
+    audit?: {
+        actions?: AuditActionDef[];
+    };
+}
+type StandardPageKey = 'dashboard' | 'tenants' | 'subscriptions' | 'promoCodes' | 'plans' | 'audit' | 'users' | 'pilots' | 'discovery' | 'bundles' | 'marketingCatalog' | 'platformEmail' | 'platformEmailHistory';
+interface StandardPageDef {
+    enabled: boolean;
+    requiredCapability?: CapabilityKey;
+}
+interface ProjectPageDef {
+    /** `<projectKey>.<area>`, e.g. `demoapp.datev`. */
+    id: string;
+    label: string;
+    icon?: string;
+    /** Frontend route, e.g. `/admin/datev`. */
+    route: string;
+    navSection?: string;
+    /** Lookup in the static extensions: map of the shell build. */
+    componentKey: ComponentKey;
+    requiredCapability?: CapabilityKey;
+    prefetchOnIdle?: boolean;
+}
+interface KpiCardDef {
+    id: string;
+    label: string;
+    /** Required path: /api/v1/admin/(extras|dashboard)/... */
+    endpoint: string;
+    displayHint: KpiDisplayHint;
+    /** 0–100; UI sorts descending. */
+    slotPriority?: number;
+    requiredCapability?: CapabilityKey;
+}
+interface KpiDisplayHint {
+    type: 'value' | 'value+timestamp' | 'value+spark8w' | 'value+delta';
+    icon?: string;
+}
+interface TenantColumnDef {
+    key: string;
+    label: string;
+    /** Required path: /api/v1/admin/extras/...; MUST be batch-capable, no {slug}/{tenantId}. */
+    endpoint: string;
+    requiredCapability?: CapabilityKey;
+}
+interface TenantActionDef {
+    /** `<projectKey>.<area>.<verb>`, e.g. `demoapp.datev.runExport`. */
+    id: string;
+    label: string;
+    /** Lookup in the static actions: map of the shell build. */
+    actionKey: ActionKey;
+    requiredCapability?: CapabilityKey;
+    requiresMfa?: boolean;
+    confirmType?: 'none' | 'simple' | 'typed-slug' | 'typed-production' | 'date';
+}
+interface AuditActionDef {
+    /** SCREAMING_SNAKE_CASE; matched to the AuditLog.action column. */
+    key: string;
+    label: string;
+    severity?: 'info' | 'low' | 'medium' | 'high';
+}
+interface ManifestContribution {
+    capabilities?: Record<CapabilityKey, boolean>;
+    navigation?: {
+        standardPages?: Partial<Record<StandardPageKey, StandardPageDef>>;
+        projectPages?: ProjectPageDef[];
+    };
+    dashboard?: {
+        kpiCards?: KpiCardDef[];
+    };
+    tenants?: {
+        columns?: TenantColumnDef[];
+        actions?: TenantActionDef[];
+    };
+    audit?: {
+        actions?: AuditActionDef[];
+    };
+}
+interface PublicBootResponse {
+    project: {
+        key: string;
+        displayName: string;
+        /** Tag/subtitle (e.g. "SuperAdmin"). From `saas.yaml#app.label`. */
+        label?: string;
+        /** Short abbreviation for the logo badge (e.g. "ma", "da"). From `saas.yaml#app.icon`. */
+        icon?: string;
+        logoUrl?: string;
+        environment?: 'production' | 'staging' | 'development';
+    };
+}
+
+/** Format: 'web:<email>:<sessionId>' or 'cli:<email>:<host>'. */
+type ActorTag = string;
+interface AuditEntry {
+    id: string;
+    /** null = platform action without tenant context (SUPER_ADMIN). */
+    tenantId: string | null;
+    /** null = system / cron-triggered. */
+    userId: string | null;
+    /** Convenience field; backend resolves it from userId. */
+    userEmail: string | null;
+    /** e.g. 'Tenant', 'PromoCode', 'Subscription', 'PlanVersion', 'User'. */
+    entity: string;
+    entityId: string;
+    /** SCREAMING_SNAKE_CASE; past-tense oriented. */
+    action: string;
+    /** Freely structured. Convention: { field: { old, new } } or { reason, ... }. */
+    changes: Record<string, unknown> | null;
+    actorTag: ActorTag | null;
+    ipAddress: string | null;
+    userAgent: string | null;
+    createdAt: string;
+}
+interface AuditQuery {
+    tenantId?: string;
+    userId?: string;
+    entity?: string;
+    entityId?: string;
+    action?: string;
+    /** Wildcard-capable, e.g. 'cli:*'. */
+    actorTag?: string;
+    from?: string;
+    to?: string;
+    page?: number;
+    pageSize?: number;
+}
+
+/**
+ * Approval lifecycle of a feature or a quota. Approval happens per
+ * FEATURE/QUOTA — not per capability (#20); only `approved` entries
+ * are sellable (gate in strict-mode-check/seed-gate/preflight).
+ *
+ * - `pending`  — found in code, not yet approved; not available for
+ *                planning
+ * - `approved` — approved by the SuperAdmin for plans, bundles & marketing;
+ *                the approval signature freezes the code state
+ * - `outdated` — drift: the implementation has changed since approval
+ *                (approval signature ≠ current snapshot) or was manually
+ *                marked stale — re-approve
+ * - `obsolete` — deprecated or removed from code; no longer use in new
+ *                plans
+ *
+ * A "replaced by X" (#39) is deliberately NOT its own status value: the union
+ * is consumed exhaustively (review state machine as `Record<DiscoveryStatus, …>`,
+ * status badges in the AdminUI, status columns in the consumer DBs) — a new
+ * value would force lockstep migrations across all consumers. Instead:
+ * `obsolete` + `successorKey` as a successor pointer; old readers degrade
+ * gracefully (still see `obsolete`).
+ */
+type DiscoveryStatus = 'pending' | 'approved' | 'outdated' | 'obsolete';
+/**
+ * Code status of a capability — read-only code fact from the scan (#20):
+ * `active`/`experimental`/`deprecated` come from the decorator, `retired`
+ * is set by the sync when the capability has disappeared from the code.
+ * Capabilities no longer carry a review status; the business approval
+ * lives on the feature/the quota.
+ */
+type CapabilityCodeStatus = 'active' | 'experimental' | 'deprecated' | 'retired';
+/**
+ * Implementation kind of a capability — corresponds to `kind` in the
+ * `@ImplementsCapability(...)` decorator.
+ */
+type CapabilityKind = 'endpoint' | 'service' | 'job' | 'event';
+/**
+ * Enforcement mode of a quota:
+ * - `hard` — exceeding blocks at the business level (corresponds to policy `hardCap`)
+ * - `soft` — exceeding is only counted/warned
+ */
+type QuotaEnforcementMode = 'hard' | 'soft';
+/**
+ * Locale-specific translation fields of a catalog entry. Empty/missing
+ * fields fall back in the UI to the default locale (`de`). `unit` is only
+ * relevant for quotas.
+ */
+interface CatalogEntryI18nFields {
+    label?: string;
+    description?: string;
+    unit?: string;
+}
+/** `{ 'en': { label, description }, 'tr': { … } }` — the default locale is intentionally absent. */
+type CatalogEntryI18n = Record<string, CatalogEntryI18nFields>;
+/**
+ * SuperAdmin projection of a code-declared capability. The business
+ * truth (exists / does not exist) stays in the code; this table holds
+ * the code status (read-only fact, #20) and denormalized aggregation
+ * shells for UI lookups. Approval lives on the feature/the quota.
+ */
+interface CapabilityCatalogEntryRow {
+    id: string;
+    projectKey: string;
+    capabilityKey: string;
+    label: string;
+    description: string | null;
+    /** Aggregation shell from the decorator (denormalized for UI lookup). */
+    featureKey: string | null;
+    /** Aggregation shell from the decorator (denormalized). */
+    bundleKey: string | null;
+    codeStatus: CapabilityCodeStatus;
+    /** Code owner tag from the decorator (e.g. 'accounting'). */
+    owner: string | null;
+    kind: CapabilityKind;
+    /** Recommended when codeStatus = 'deprecated'. */
+    replacementKey: string | null;
+    deprecatedAt: string | null;
+    removalPlannedAt: string | null;
+    reason: string | null;
+    /** Locale translations (discovery translation tab). */
+    i18n: CatalogEntryI18n;
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+/**
+ * Tier hint for comparison-matrix sorting. Convention:
+ * `CORE` < `ADVANCED` < `PRO` < `ENTERPRISE`. Apps may add further
+ * tiers; sorting then happens via `FeatureCatalogEntry.sortOrder`.
+ */
+type FeatureTier = 'CORE' | 'ADVANCED' | 'PRO' | 'ENTERPRISE' | string;
+/**
+ * SuperAdmin projection of a feature (aggregation of capabilities that declare
+ * `feature: 'XYZ'` in the decorator). The short marketing form lives here;
+ * locale-specific long texts in MarketingProjectionRow.
+ */
+interface FeatureCatalogEntryRow {
+    id: string;
+    projectKey: string;
+    featureKey: string;
+    label: string;
+    description: string | null;
+    /** Short marketing label for sidebar / comparison matrix. */
+    marketingLabel: string | null;
+    /** Short marketing description. For long locale texts: MarketingProjectionRow. */
+    marketingDescription: string | null;
+    icon: string | null;
+    tier: FeatureTier | null;
+    discoveryStatus: DiscoveryStatus;
+    /** Code-discovered feature dependencies (#35) — empty list = none. */
+    requires: string[];
+    /** Old feature keys that this feature supersedes (#39) — empty list = none. */
+    replaces: string[];
+    /**
+     * Successor pointer (#39): set when this key has disappeared from the
+     * code AND another snapshot key claims it via `replaces` — "replaced by
+     * X = guided migration" instead of a bare `obsolete` (= deleted without
+     * replacement).
+     */
+    successorKey: string | null;
+    /** Timestamp of the last approval; `null` while never approved. */
+    approvedAt: string | null;
+    /** User ID of the approving SuperAdmin. */
+    approvedBy: string | null;
+    /**
+     * Signature of the capability set at approval time
+     * (`capabilityKey@codeStatus`, sorted, `|`-separated). The auto-sync
+     * compares it against the current snapshot — on divergence,
+     * `approved` → `outdated` (drift, #20).
+     */
+    approvedSignature: string | null;
+    /**
+     * `true` = the feature is planned in the SuperAdmin plan but not yet
+     * implemented in the code. The blocking strict-mode check
+     * rejects plan publish with `plannedOnly` features.
+     */
+    plannedOnly: boolean;
+    /** true = base/always included (not bookable per plan). */
+    core: boolean;
+    /** Locale translations (discovery translation tab). */
+    i18n: CatalogEntryI18n;
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+/**
+ * SuperAdmin projection of a code-declared quota (`@DefinesQuota`).
+ * Carries the review status as well as deploy relevance: a hard quota
+ * without `usageProvider` is not deployable (Preflight).
+ */
+interface QuotaCatalogEntryRow {
+    id: string;
+    projectKey: string;
+    quotaKey: string;
+    label: string;
+    description: string | null;
+    /** Display unit, e.g. `members`, `GB`, `/month`. */
+    unit: string;
+    /** Aggregation shell from the decorator (denormalized). */
+    featureKey: string | null;
+    /**
+     * Class that declares the quota via `@DefinesQuota` (= UsageProvider).
+     * `null` = the quota is referenced (`@EnforceQuota`) but provided by no
+     * class — deploy-blocking when `enforcementMode: 'hard'`.
+     */
+    usageProvider: string | null;
+    enforcementMode: QuotaEnforcementMode;
+    discoveryStatus: DiscoveryStatus;
+    /** Old quota keys that this quota supersedes (#39) — empty list = none. */
+    replaces: string[];
+    /** Successor pointer (#39), analogous to `FeatureCatalogEntryRow.successorKey`. */
+    successorKey: string | null;
+    /** Timestamp of the last approval; `null` while never approved. */
+    approvedAt: string | null;
+    /** User ID of the approving SuperAdmin. */
+    approvedBy: string | null;
+    /**
+     * Signature of the code-derived quota facts at approval time
+     * (`unit|enforcementMode|usageProvider|featureKey`). The auto-sync
+     * compares it against the current snapshot — on divergence,
+     * `approved` → `outdated` (drift, #20).
+     */
+    approvedSignature: string | null;
+    /** Locale translations (`label`, `unit`, `description`). */
+    i18n: CatalogEntryI18n;
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+/**
+ * Filter for `CatalogEntryRepository.list*()`. `discoveryStatus` applies to
+ * features/quotas, `codeStatus` to capabilities — per list, only the
+ * matching field is relevant.
+ */
+interface CatalogEntryFilter {
+    projectKey: string;
+    discoveryStatus?: DiscoveryStatus;
+    codeStatus?: CapabilityCodeStatus;
+}
+/**
+ * Body of `PATCH …/{features,quotas}/:key/review` — the target status of
+ * the approval state machine. The service validates the allowed transitions
+ * (`pending → approved/obsolete`, `approved → pending/outdated/obsolete`,
+ * `outdated → approved/pending/obsolete`, `obsolete → pending`).
+ */
+interface ReviewCatalogEntryData {
+    discoveryStatus: DiscoveryStatus;
+}
+/**
+ * Approved gate (#20 Slice 5): the sets of approved feature/quota keys
+ * (`discoveryStatus = 'approved'`) from the catalog entries. Strict-mode
+ * check, Seed-Gate and Preflight use them to enforce "only approved is
+ * sellable" — `null`/omitted skips the approval part (e.g. when no
+ * CatalogEntryRepository is registered).
+ */
+interface ApprovedCatalogKeys {
+    features: ReadonlySet<string>;
+    quotas: ReadonlySet<string>;
+}
+/** Body of `PATCH …/{features,quotas}/:key/i18n`. */
+interface UpdateCatalogEntryI18nData {
+    /** Complete i18n tree — replaces the existing one. */
+    i18n: CatalogEntryI18n;
+}
+/**
+ * Body of `PATCH …/{features,quotas}/:key` — editable base/default locale
+ * fields (`de`). Quotas: `unit` stays code-derived and is not editable —
+ * but is translatable per locale via `i18n`.
+ */
+interface UpdateCatalogEntryBaseData {
+    label?: string;
+    description?: string | null;
+    /** Feature-only (#13): static default icon (Quasar icon name). Quotas ignore it. */
+    icon?: string | null;
+    /** Feature-only (#13): tier hint (open union). Quotas ignore it. */
+    tier?: FeatureTier | null;
+}
+/**
+ * Result of `POST …/discovery/sync` — counters for the UI.
+ * `discovered`/`retired` are scan events (new in code / disappeared from
+ * code); `outdated` counts `approved` entries that the sync flipped to
+ * `outdated` due to signature drift (#20). `replaced` counts entries to
+ * which the sync assigned a successor pointer (`successorKey`) in this run
+ * (#39).
+ */
+interface SyncDiscoveryResult {
+    capabilities: {
+        discovered: number;
+        retired: number;
+        total: number;
+    };
+    features: {
+        discovered: number;
+        retired: number;
+        outdated: number;
+        replaced: number;
+        total: number;
+    };
+    quotas: {
+        discovered: number;
+        retired: number;
+        outdated: number;
+        replaced: number;
+        total: number;
+    };
+}
+/**
+ * Polymorphic target type of a MarketingProjection. References the
+ * versioned entity (plan or bundle version) that is
+ * marketed publicly.
+ */
+type MarketingTargetType = 'PLAN' | 'BUNDLE';
+/**
+ * A top-feature entry in the public-catalog card.
+ *
+ * - `key` — optional reference to a feature/quota key. If `key` is
+ *   set and `label` is empty, the displayed label is resolved (translated)
+ *   from the `FeatureCatalogEntry`/`QuotaCatalogEntry` in the respective
+ *   locale. This keeps the card language-reactive.
+ * - `label` — free text or override; empty + `key` set = auto label.
+ * - `strong` — optional bold-set addition (e.g. "up to 100", "5 GB").
+ */
+interface MarketingTopFeature {
+    key?: string;
+    label: string;
+    strong: string;
+}
+/**
+ * Locale-specific marketing texts per plan/bundle version.
+ * Read and projected by the Public-Catalog-Controller
+ * (`GET /public/catalog?locale=de`).
+ *
+ * Polymorphic reference via (`targetType`, `targetVersionId`) — no FK,
+ * app logic checks existence on read.
+ */
+interface MarketingProjectionRow {
+    id: string;
+    projectKey: string;
+    targetType: MarketingTargetType;
+    targetVersionId: string;
+    /** ISO-639-1, optionally with region suffix (`de`, `en`, `de-AT`). */
+    locale: string;
+    displayLabel: string;
+    description: string;
+    /**
+     * Visibility in the public catalog. `false` = the projection exists,
+     * but the plan is not shown on the pricing page (e.g. during
+     * preparation).
+     */
+    visible: boolean;
+    /**
+     * Optional badge at the top of the card (e.g. "Popular", "New"). Empty
+     * string = no badge.
+     */
+    badge: string;
+    /**
+     * Top features that appear prominently on the public-catalog card.
+     * Order is the display order.
+     */
+    topFeatures: MarketingTopFeature[];
+    /** Free trial active — controls the automatic CTA text. */
+    trialEnabled: boolean;
+    /** Length of the trial in days (only relevant when `trialEnabled`). */
+    trialDays: number;
+    /**
+     * Optional formatted price tag (e.g. "€ 9.90 / month" or "on
+     * request"). null = pricing is formatted automatically from
+     * PlanVersion.monthlyNet etc. at render time.
+     */
+    priceTag: string | null;
+    /**
+     * Overrides the automatically generated call-to-action text
+     * (e.g. "Get in touch"). null = auto text from trial/pricing.
+     */
+    ctaLabel: string | null;
+    /** Sorting in the public list (DESC). Higher values first. */
+    priority: number;
+    /** "Recommended" star or featured highlight in the UI. */
+    highlight: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Filter for `MarketingProjectionRepository.list()`. At least projectKey. */
+interface MarketingProjectionFilter {
+    projectKey: string;
+    targetType?: MarketingTargetType;
+    targetVersionId?: string;
+    locale?: string;
+}
+interface CreateMarketingProjectionData {
+    projectKey: string;
+    targetType: MarketingTargetType;
+    targetVersionId: string;
+    locale?: string;
+    displayLabel: string;
+    description: string;
+    visible?: boolean;
+    badge?: string;
+    topFeatures?: MarketingTopFeature[];
+    trialEnabled?: boolean;
+    trialDays?: number;
+    priceTag?: string | null;
+    ctaLabel?: string | null;
+    priority?: number;
+    highlight?: boolean;
+}
+interface UpdateMarketingProjectionData {
+    displayLabel?: string;
+    description?: string;
+    visible?: boolean;
+    badge?: string;
+    topFeatures?: MarketingTopFeature[];
+    trialEnabled?: boolean;
+    trialDays?: number;
+    priceTag?: string | null;
+    ctaLabel?: string | null;
+    priority?: number;
+    highlight?: boolean;
+}
+
+type PromoCodeValueType = 'PERCENT' | 'ABSOLUTE';
+type PromoCodeDurationType = 'ONCE' | 'MONTHS' | 'BILLING_CYCLES';
+type PromoCodeStatus = 'ACTIVE' | 'PAUSED' | 'EXHAUSTED' | 'EXPIRED';
+type PromoCodeRedemptionStatus = 'ACTIVE' | 'REVERSED' | 'EXPIRED';
+type BillingCycle = 'MONTHLY' | 'YEARLY';
+type PromoCodeValidationResult = 'VALID' | 'EXPIRED' | 'EXHAUSTED' | 'NOT_FOUND' | 'PAUSED' | 'NOT_APPLICABLE' | 'FIRST_TIME_ONLY' | 'ZERO_INVOICE_BLOCKED' | 'MIN_AMOUNT_NOT_REACHED' | 'RATE_LIMITED';
+interface CreatePromoCodeRequest {
+    /** A–Z, 0–9, '-' and '_'; 4–32 characters; case-insensitive, stored in UPPER. */
+    code: string;
+    valueType: PromoCodeValueType;
+    /** For PERCENT: 0.01–100. For ABSOLUTE: > 0 in catalog currency. */
+    value: number;
+    durationType: PromoCodeDurationType;
+    /** Required for MONTHS / BILLING_CYCLES, null for ONCE. */
+    durationValue?: number | null;
+    validFrom?: string | null;
+    validUntil?: string | null;
+    maxRedemptions?: number | null;
+    /** Empty = all plans. */
+    appliesToPlans?: PlanId[];
+    appliesToBilling?: BillingCycle | null;
+    firstTimeCustomersOnly?: boolean;
+    minimumPlanAmountGross?: number | null;
+    /** Default false: discount must not reduce the invoice to 0. */
+    allowZeroInvoice?: boolean;
+    description?: string | null;
+    campaignTag?: string | null;
+    /** SKR account for accounting; project-specific. */
+    revenueDeductionAccount?: string | null;
+}
+interface UpdatePromoCodeRequest {
+    status?: 'ACTIVE' | 'PAUSED';
+    description?: string | null;
+    validUntil?: string | null;
+    maxRedemptions?: number | null;
+    campaignTag?: string | null;
+}
+interface PromoCode {
+    id: string;
+    code: string;
+    valueType: PromoCodeValueType;
+    value: number;
+    durationType: PromoCodeDurationType;
+    durationValue: number | null;
+    validFrom: string | null;
+    validUntil: string | null;
+    maxRedemptions: number | null;
+    redemptionsCount: number;
+    appliesToPlans: PlanId[];
+    appliesToBilling: BillingCycle | null;
+    firstTimeCustomersOnly: boolean;
+    minimumPlanAmountGross: number | null;
+    allowZeroInvoice: boolean;
+    status: PromoCodeStatus;
+    description: string | null;
+    campaignTag: string | null;
+    revenueDeductionAccount: string | null;
+    createdAt: string;
+    deletedAt: string | null;
+}
+interface PromoCodeRedemption {
+    id: string;
+    promoCodeId: string;
+    subscriptionId: string;
+    tenantId: string;
+    appliedValueType: PromoCodeValueType;
+    appliedValue: number;
+    appliedDurationType: PromoCodeDurationType;
+    appliedDurationValue: number | null;
+    startsAt: string;
+    endsAt: string | null;
+    status: PromoCodeRedemptionStatus;
+    redeemedAt: string;
+    reversedAt: string | null;
+}
+interface PromoCodeValidationLog {
+    id: string;
+    /** null for NOT_FOUND. */
+    promoCodeId: string | null;
+    codeAttempt: string;
+    /** Hash, not plaintext. */
+    ipHash: string | null;
+    sessionId: string | null;
+    result: PromoCodeValidationResult;
+    createdAt: string;
+}
+
+type SubscriptionStatus = 'TRIAL' | 'ACTIVE' | 'PAST_DUE' | 'CANCELED' | 'PENDING_SALES';
+interface Subscription {
+    id: string;
+    tenantId: string;
+    planId: PlanId;
+    /** FK to PlanVersion — binding for existing subscriptions (contract protection P1). */
+    planVersionId: string;
+    billingCycle: BillingCycle;
+    status: SubscriptionStatus;
+    /** Override per Tenant; unset fields fall back to the PlanVersion. */
+    customLimits?: Partial<Record<QuotaKey, number>>;
+    /** ENTERPRISE special contract. */
+    customMonthlyNet?: number | null;
+    isPilot: boolean;
+    pilotEndsAt: string | null;
+    pilotNote?: string | null;
+    trialEndsAt: string | null;
+    startedAt: string;
+    canceledAt: string | null;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    /** Plan version migration (see ROADMAP §6). */
+    pendingPlanVersionId: string | null;
+    pendingPlanVersionEffectiveAt: string | null;
+    pendingPlanVersionAccepted: boolean;
+    pendingPlanVersionAcceptedAt: string | null;
+    pendingPlanVersionAcceptedByUserId: string | null;
+    pendingPlanVersionNotifiedAt: string | null;
+    pendingPlanVersionReminderSentAt: string | null;
+    /** Plan change at period end (orthogonal to pendingPlanVersionId). */
+    pendingPlanId: PlanId | null;
+    pendingBillingCycle: BillingCycle | null;
+    pendingEffectiveAt: string | null;
+    postTrialPlanId: PlanId | null;
+    trialEntitlementPlanId: PlanId | null;
+    createdAt: string;
+    updatedAt: string;
+}
+type VersionChangeDirection = 'IMPROVEMENT' | 'REGRESSION' | 'NEUTRAL';
+interface VersionChange {
+    field: string;
+    oldValue: unknown;
+    newValue: unknown;
+    direction: VersionChangeDirection;
+}
+interface VersionedEntityBase {
+    id: string;
+    version: number;
+    /** Predecessor the draft diffed against. */
+    baseVersionId: string | null;
+    /** null = draft, set = live or superseded. */
+    publishedAt: string | null;
+    /** set = no longer marketed, but contractually valid for existing subscriptions. */
+    supersededAt: string | null;
+    publishedChanges: VersionChange[] | null;
+    /** Required on publish; quoted in notification emails. */
+    changeNote: string;
+    /** Computed on publish. */
+    nonRegressive: boolean;
+    /**
+     * From when this version is active for *new* bookings.
+     * null = draft (no date yet). Required on publish; must lie strictly after
+     * the `validFrom` of the predecessor version.
+     */
+    validFrom: string | null;
+    /**
+     * Until when this version is available for *new* bookings; null = unlimited.
+     * Automatically set to `successor.validFrom - 1 day` when a successor
+     * version is published (auto-succession).
+     * Existing subscriptions (P1) are unaffected by this.
+     */
+    validUntil: string | null;
+    createdByUserId: string | null;
+    publishedByUserId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Computed on the list read in the service: `true` when no version with a
+     * higher `version` number (same lineage) exists. Needed to keep a
+     * published-but-future version editable — only the last one in the chain
+     * may be readjusted, because successor versions would otherwise become
+     * inconsistent. Optional, because adapter reads that do not set the field
+     * are interpreted by the helper as `undefined → false` (= frozen).
+     */
+    isLatestInChain?: boolean;
+    /**
+     * Computed on the list read in the service: number of subscriptions that
+     * bind this version. Needed to keep a published-but-future version
+     * editable — as soon as a booking exists, the version is frozen because it
+     * has become part of the contract. Optional for backwards-compat reasons;
+     * the helper defensively interprets `undefined` as `>0` (= frozen). How the
+     * adapter counts depends on the version type: PlanVersion via
+     * `Subscription.planVersionId` (+ `pendingPlanVersionId`), BundleVersion
+     * via the respective app-specific Subscription→Bundle binding.
+     */
+    subscriptionCount?: number;
+}
+/**
+ * SubscriptionBundle — wire format of the `subscription_bundles` junction
+ *. Models a **standalone** bundle booking of a
+ * subscription, analogous to the plan booking; bundles are maintained with
+ * their own minimum term + their own cancellation (user requirement from
+ * P11.7.3).
+ *
+ * - `bundleVersionId` binds the booking to an *exact* BundleVersion
+ *   (immutable; bundle updates only take effect after a new version with its
+ *   own migration).
+ * - `startedAt` is the contract start of this booking.
+ * - `minimumTermEndsAt` = end of the minimum term; `null` = no minimum term
+ *   (platform default = 12 months, set service-side).
+ * - `canceledAt` / `canceledEffectiveAt`: cancellation anchor vs. effective
+ *   date. Before the minimum term ends, `canceledEffectiveAt =
+ *   minimumTermEndsAt`, otherwise the subscription's period end.
+ *
+ * Existing-subscription protection: for SuperAdmin editor editability,
+ * `SubscriptionRepository.countByBundleVersionId` counts the non-canceled
+ * entries (`canceledAt IS NULL OR canceledEffectiveAt > NOW()`).
+ */
+interface SubscriptionBundleRecord {
+    id: string;
+    subscriptionId: string;
+    bundleVersionId: string;
+    startedAt: Date;
+    minimumTermEndsAt: Date | null;
+    canceledAt: Date | null;
+    canceledEffectiveAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * API view for `GET /billing/subscription-bundles`: record + denormalized
+ * bundle info (key/label/price) from the booked BundleVersion. This lets the
+ * UI show booked bundles without a catalog join — the catalog may exclude
+ * filtered/superseded versions, otherwise the display falls back to the raw
+ * bundleVersionId (UUID).
+ */
+interface SubscriptionBundleView extends SubscriptionBundleRecord {
+    bundleKey: string | null;
+    label: string | null;
+    monthlyNet: string | null;
+}
+interface CreateSubscriptionBundleData {
+    subscriptionId: string;
+    bundleVersionId: string;
+    startedAt: Date;
+    /** Default = startedAt + 12 months, unless set. */
+    minimumTermEndsAt?: Date | null;
+}
+interface CancelSubscriptionBundleData {
+    canceledAt: Date;
+    /**
+     * Effective date the cancellation takes effect. The service computes it:
+     * max(canceledAt + 1 period, minimumTermEndsAt).
+     */
+    canceledEffectiveAt: Date;
+}
+interface PlanVersion extends VersionedEntityBase {
+    planId: PlanId;
+    features: FeatureKey[];
+    quotas: Partial<Record<QuotaKey, number>>;
+    monthlyNet: number;
+    yearlyNet: number;
+    marketed: boolean;
+}
+
+/**
+ * Usage whitelist for a bundle. An empty/missing list means the bundle may
+ * be used with any plan.
+ */
+interface BundleCompatibility {
+    /**
+     * Whitelist of plan IDs; only these may use the bundle.
+     * Empty/missing = all plans allowed.
+     */
+    planIds?: string[];
+}
+/**
+ * Pricing override for a plan context.
+ *
+ * - `monthlyNet` / `yearlyNet` as string (Decimal wire format)
+ * - `null` = explicit "free in this context"
+ * - undefined / field missing = no override for this cycle
+ */
+interface BundlePricingOverride {
+    /** If set: override applies only with this plan. */
+    planId?: string;
+    monthlyNet?: string | null;
+    yearlyNet?: string | null;
+}
+/**
+ * Bundle — reusable component of Features + Quotas + Pricing.
+ * Master entity without content; the purchasable fields live on BundleVersionRow.
+ */
+interface BundleRow {
+    id: string;
+    projectKey: string;
+    bundleKey: string;
+    label: string;
+    description: string | null;
+    icon: string | null;
+    sortOrder: number;
+    /** Locale translations of `label`/`description`. */
+    i18n: CatalogEntryI18n;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+/**
+ * BundleVersion — versioned composition (Features, Quotas, Pricing).
+ * `quotas` is `Record<QuotaKey, number>`; `-1` = unlimited; a missing key
+ * contributes 0.
+ */
+interface BundleVersionRow extends VersionedEntityBase {
+    bundleId: string;
+    /** Denormalized for UI (avoids an extra lookup). */
+    bundleKey: string;
+    /** Denormalized for UI. */
+    label: string;
+    features: FeatureKey[];
+    quotas: Record<QuotaKey, number>;
+    compatibility: BundleCompatibility;
+    pricingOverrides: BundlePricingOverride[];
+    /** Default price; null = only via override pricing. */
+    monthlyNet: string | null;
+    yearlyNet: string | null;
+    marketed: boolean;
+}
+/**
+ * Fields that must be set when creating a new bundle master.
+ * `id`, `createdAt`, `updatedAt`, `deletedAt` are assigned by the repository.
+ * Version-specific fields (Features, Quotas, Pricing) belong in the
+ * first BundleVersion via `CreateBundleVersionDraftData`.
+ */
+interface CreateBundleData {
+    projectKey: string;
+    bundleKey: string;
+    label: string;
+    description?: string | null;
+    icon?: string | null;
+    sortOrder?: number;
+    i18n?: CatalogEntryI18n;
+}
+/**
+ * Fields that may be changed on the bundle master. `bundleKey` and
+ * `projectKey` are intentionally not here — master identity is immutable;
+ * whoever wants to change them creates a new bundle and retires the old one.
+ */
+interface UpdateBundleData {
+    label?: string;
+    description?: string | null;
+    icon?: string | null;
+    sortOrder?: number;
+    i18n?: CatalogEntryI18n;
+}
+/**
+ * Fields of a new BundleVersion in draft status (`publishedAt = null`).
+ * Created by the SuperAdmin, later published via `publishBundleVersion()`.
+ * Only **one** draft version per bundle allowed
+ * (see partial unique index in the migration).
+ */
+interface CreateBundleVersionDraftData {
+    bundleId: string;
+    /** Predecessor version the diff is computed against (null for v1). */
+    baseVersionId?: string | null;
+    features: FeatureKey[];
+    quotas?: Record<QuotaKey, number>;
+    compatibility?: BundleCompatibility;
+    pricingOverrides?: BundlePricingOverride[];
+    monthlyNet?: string | null;
+    yearlyNet?: string | null;
+    marketed?: boolean;
+    /** Required at publish (see contract protection P3 in). */
+    changeNote?: string;
+    /**
+     * From when this version should be active for *new* bookings. Required
+     * at the latest at publish (see `PublishBundleVersionData`); can
+     * already be pre-noted in the draft. Format: ISO-8601 (`YYYY-MM-DD`).
+     */
+    validFrom?: string | null;
+    /**
+     * Optional; null = unlimited until superseded by a successor
+     * version (auto succession). When a successor version is published it is
+     * automatically set by the service to `successor.validFrom - 1 day`.
+     */
+    validUntil?: string | null;
+    createdByUserId?: string | null;
+}
+/**
+ * Fields of a draft BundleVersion that may still be changed.
+ * With also for published-but-future versions
+ * (latest-in-chain, 0 subs, validFrom > now) — see
+ * `isVersionEditable`.
+ */
+interface UpdateBundleVersionDraftData {
+    features?: FeatureKey[];
+    quotas?: Record<QuotaKey, number>;
+    compatibility?: BundleCompatibility;
+    pricingOverrides?: BundlePricingOverride[];
+    monthlyNet?: string | null;
+    yearlyNet?: string | null;
+    marketed?: boolean;
+    changeNote?: string;
+    /**
+     * New `validFrom` for the version. Freely settable when updating a
+     * draft; for a published-but-future version the new date must still
+     * lie in the future — the service checks that with
+     * `isVersionEditable` against the freshly loaded state.
+     */
+    validFrom?: string | null;
+    validUntil?: string | null;
+}
+/**
+ * Input for `publishBundleVersion()`. `nonRegressive` and
+ * `publishedChanges` are computed by the service from the diff against the
+ * predecessor version; the caller supplies only confirmation
+ * + user tag + validity dates.
+ *
+ * `validFrom` is **required** at publish (analogous to `PublishPlanVersionData`).
+ * If the draft already carries a `validFrom`, it is optional here. The
+ * service validates strictly > `validFrom` of the predecessor version and sets
+ * its `validUntil` via auto succession to `validFrom - 1 day`.
+ */
+interface PublishBundleVersionData {
+    publishedByUserId: string | null;
+    /**
+     * If true and the diff classifies the version as regressive,
+     * it is published anyway — relevant for bulk-publish MFA confirmation
+     * ( editor-UI obligations).
+     */
+    forceRegressive?: boolean;
+    /**
+     * Allows publish despite an explicit price of 0.00. Default false: an
+     * explicit 0.00 publish is blocked (protection against seed placeholders).
+     * `null` prices (override resolution) are not affected.
+     */
+    allowZeroPrice?: boolean;
+    /**
+     * Required at publish if the draft has no `validFrom`. Must lie
+     * strictly after `validFrom` of the predecessor version. ISO-8601
+     * (`YYYY-MM-DD` or full timestamp).
+     */
+    validFrom?: string | null;
+    /**
+     * Optional; null = valid indefinitely (fits the last version
+     * of a bundle). When a successor version is created it is automatically
+     * overwritten by the service.
+     */
+    validUntil?: string | null;
+}
+/**
+ * Code of a strict-mode violation. lists the eight rules
+ * that are checked; each rule has its own code so the UI can show
+ * focused help texts.
+ */
+type StrictModeWarningCode = 'CAPABILITY_MISSING' | 'CAPABILITY_RETIRED' | 'FEATURE_MISSING' | 'FEATURE_PLANNED_ONLY' | 'BUNDLE_FEATURE_UNKNOWN' | 'BUNDLE_PLAN_KEY_UNKNOWN' | 'PLAN_FEATURE_UNKNOWN' | 'PLAN_FEATURE_NOT_APPROVED' | 'BUNDLE_FEATURE_NOT_APPROVED' | 'PLAN_FEATURE_DEPENDENCY_UNSATISFIED' | 'BUNDLE_FEATURE_DEPENDENCY_UNSATISFIED' | 'QUOTA_MISSING' | 'QUOTA_NOT_APPROVED' | 'VERSION_PUBLISH_OVERLAP';
+/**
+ * A strict-mode violation. `field` points to the violating field
+ * (e.g. `'features[3]'`), `value` is the concrete value (e.g. `'INVENTORY'`).
+ */
+interface StrictModeWarning {
+    code: StrictModeWarningCode;
+    /** Human-readable reason (German). */
+    message: string;
+    /** Path to the violating field; optional. */
+    field?: string;
+    /** The concrete violating value; optional. */
+    value?: string;
+}
+/**
+ * Service result for mutating Bundle operations
+ * (createDraft, updateDraft, publish): returns the persisted row plus
+ * a list of strict-mode warnings. In `warn-only` mode the
+ * warnings go into the UI as a banner; in `blocking` mode the service throws
+ * HTTP 422 instead, with the same warning list as the body.
+ */
+interface BundleVersionMutationResult {
+    bundleVersion: BundleVersionRow;
+    warnings: StrictModeWarning[];
+}
+
+/** Promotion type. */
+type PromotionType = 'percent' | 'amount' | 'intro' | 'freeMonths';
+/** Billing cycle for which the promotion applies. */
+type PromotionBillingCycle = 'monthly' | 'yearly' | 'both';
+/** Derived time status (from validFrom/validTo + today). */
+type PromotionStatus = 'scheduled' | 'active' | 'expired';
+/** Target type of a promotion. Missing/undefined means legacy `PLAN`. */
+type PromotionTargetType = 'PLAN' | 'BUNDLE' | 'OFFER';
+/**
+ * Type-dependent promotion value:
+ * - `percent`/`amount` → number
+ * - `intro` → `{ price, months }`
+ * - `freeMonths` → number (count of free months)
+ */
+type PromotionValue = number | {
+    price: number;
+    months: number;
+};
+/** Locale-specific promotion texts. */
+interface PromotionI18nFields {
+    badge?: string;
+    fineprint?: string;
+}
+/** `{ 'de': { badge, fineprint }, 'en': { … } }`. */
+type PromotionI18n = Record<string, PromotionI18nFields>;
+/** Wire format of a `promotions` row. */
+interface PromotionRow {
+    id: string;
+    projectKey: string;
+    /** Internal label (not public). */
+    internalLabel: string;
+    type: PromotionType;
+    value: PromotionValue;
+    /** Plan keys the promotion applies to. */
+    appliesTo: string[];
+    /** Target type of the keys in `appliesTo`. Missing = PLAN. */
+    targetType?: PromotionTargetType;
+    billingCycle: PromotionBillingCycle;
+    /** ISO date. */
+    validFrom: string;
+    validTo: string;
+    /** On overlap, the highest value wins. */
+    priority: number;
+    /** Language restriction; null = all locales. */
+    onlyLocales: string[] | null;
+    requiresCoupon: boolean;
+    /** Referenced `PromoCode` codes (only relevant when requiresCoupon). */
+    codes: string[];
+    /** UI accent color (timeline/ribbon). */
+    color: string;
+    i18n: PromotionI18n;
+    createdAt: string;
+    updatedAt: string;
+}
+interface PromotionFilter {
+    projectKey: string;
+}
+interface CreatePromotionData {
+    projectKey: string;
+    internalLabel: string;
+    type: PromotionType;
+    value: PromotionValue;
+    appliesTo?: string[];
+    targetType?: PromotionTargetType;
+    billingCycle?: PromotionBillingCycle;
+    validFrom: string;
+    validTo: string;
+    priority?: number;
+    onlyLocales?: string[] | null;
+    requiresCoupon?: boolean;
+    codes?: string[];
+    color?: string;
+    i18n?: PromotionI18n;
+}
+interface UpdatePromotionData {
+    internalLabel?: string;
+    type?: PromotionType;
+    value?: PromotionValue;
+    appliesTo?: string[];
+    targetType?: PromotionTargetType;
+    billingCycle?: PromotionBillingCycle;
+    validFrom?: string;
+    validTo?: string;
+    priority?: number;
+    onlyLocales?: string[] | null;
+    requiresCoupon?: boolean;
+    codes?: string[];
+    color?: string;
+    i18n?: PromotionI18n;
+}
+/** Time status of a promotion relative to `today` (default: now). */
+declare function promoStatus(promo: Pick<PromotionRow, 'validFrom' | 'validTo'>, today?: Date): PromotionStatus;
+/**
+ * Selects **exactly one** applicable promotion for plan + locale + cycle:
+ * filtered on `appliesTo`, `billingCycle`, `onlyLocales`, status `active`,
+ * `!requiresCoupon`; if several, the highest `priority` wins.
+ */
+declare function pickActivePromo(promotions: PromotionRow[], targetKey: string, locale: string, cycle: 'monthly' | 'yearly', today?: Date, targetType?: PromotionTargetType): PromotionRow | null;
+/** Result of `applyPromo` — type-dependent price projection. */
+type PromotionResult = {
+    kind: 'percent';
+    discounted: number;
+    original: number;
+    pct: number;
+} | {
+    kind: 'amount';
+    discounted: number;
+    original: number;
+    saved: number;
+} | {
+    kind: 'intro';
+    discounted: number;
+    original: number;
+    months: number;
+} | {
+    kind: 'free';
+    discounted: number;
+    original: number;
+    months: number;
+};
+/** Applies the promotion math to a base price. */
+declare function applyPromo(promo: PromotionRow | null, basePrice: number | null): PromotionResult | null;
+
+type CheckoutOfferLineItemKind = 'plan' | 'bundle' | 'discount';
+/** Frozen billable line item in the offer. */
+interface CheckoutOfferLineItem {
+    kind: CheckoutOfferLineItemKind;
+    sourceKey: string;
+    sourceVersionId?: string | null;
+    titleSnapshot: string;
+    descriptionSnapshot?: string | null;
+    quantity: number;
+    unit?: string | null;
+    priceNet: number;
+    priceGross: number;
+    billingCycle: 'monthly' | 'yearly';
+    minimumTermUntil?: string | Date | null;
+    featuresSnapshot?: string[];
+    quotaEffectsSnapshot?: Record<string, number>;
+    metadata?: Record<string, unknown> | null;
+}
+/** Frozen applied catalog promotion. */
+interface CheckoutOfferPromotionSnapshot {
+    id: string | null;
+    type: string;
+    value: unknown;
+    label: string;
+    resolvedAmountNet: number;
+    appliesTo: string[];
+    billingCycle: 'monthly' | 'yearly' | 'both';
+}
+/** Frozen promo-code preview before contract conclusion. */
+interface CheckoutOfferPromoCodeSnapshot {
+    code: string;
+    label: string;
+    valueType: string;
+    value: number;
+    resolvedAmountNet: number;
+    durationType?: string | null;
+    durationValue?: number | null;
+}
+/** Structured price breakdown — frozen at offer time. */
+interface CheckoutOfferPriceBreakdown {
+    currency: string;
+    billingCycle: 'monthly' | 'yearly';
+    /** Net base price of the plan. */
+    planNet: number;
+    /** Net surcharge from bundles. */
+    bundlesNet: number;
+    /** Net total before promo. */
+    regularNet: number;
+    /** Net total after promo. */
+    effectiveNet: number;
+    vatRate: number;
+    /** Gross total after promo. */
+    effectiveGross: number;
+}
+type CheckoutOfferStatus = 'open' | 'consumed' | 'expired';
+/** Wire format of a `checkout_offers` row. */
+interface CheckoutOfferRow {
+    id: string;
+    projectKey: string;
+    /** Plan selected on the website. */
+    planKey: string;
+    /** Resolved plan version, if known. */
+    planVersionId: string | null;
+    billingCycle: 'monthly' | 'yearly';
+    /** Applied promotion (active at offer time). */
+    promotionId: string | null;
+    /** Redeemed promo code, if the promotion was `requiresCoupon`. */
+    promoCode: string | null;
+    /** Added bundle keys. Legacy display; V3 uses `bundleVersionIds` + `lineItems`. */
+    bundles: string[];
+    /** Concrete BundleVersion IDs that the offer binds. */
+    bundleVersionIds?: string[];
+    priceBreakdown: CheckoutOfferPriceBreakdown;
+    /** V3 contract line items, already resolved at offer time. */
+    lineItems?: CheckoutOfferLineItem[];
+    /** Active automatic promotions as snapshot. */
+    promotionSnapshots?: CheckoutOfferPromotionSnapshot[];
+    /** Redeemed promo code as snapshot. */
+    promoCodeSnapshot?: CheckoutOfferPromoCodeSnapshot | null;
+    locale: string;
+    /** Temporal validity of the offer; null = repository/consumer policy. */
+    validUntil?: string | null;
+    status: CheckoutOfferStatus;
+    /** Set as soon as a subscription has arisen from the offer. */
+    consumedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CheckoutOfferFilter {
+    projectKey: string;
+    status?: CheckoutOfferStatus;
+}
+/** Body of `POST /public/checkout-offer` — called from the website. */
+interface CreateCheckoutOfferData {
+    projectKey: string;
+    planKey: string;
+    planVersionId?: string | null;
+    billingCycle: 'monthly' | 'yearly';
+    promotionId?: string | null;
+    promoCode?: string | null;
+    bundles?: string[];
+    bundleVersionIds?: string[];
+    priceBreakdown: CheckoutOfferPriceBreakdown;
+    lineItems?: CheckoutOfferLineItem[];
+    promotionSnapshots?: CheckoutOfferPromotionSnapshot[];
+    promoCodeSnapshot?: CheckoutOfferPromoCodeSnapshot | null;
+    locale?: string;
+    validUntil?: string | null;
+}
+/**
+ * Body of `PATCH /public/checkout-offer/:id` — customization during
+ * onboarding. `status`/`consumedAt` are not editable — `consume()`
+ * sets them server-side.
+ */
+interface UpdateCheckoutOfferData {
+    billingCycle?: 'monthly' | 'yearly';
+    promotionId?: string | null;
+    promoCode?: string | null;
+    bundles?: string[];
+    bundleVersionIds?: string[];
+    priceBreakdown?: CheckoutOfferPriceBreakdown;
+    lineItems?: CheckoutOfferLineItem[];
+    promotionSnapshots?: CheckoutOfferPromotionSnapshot[];
+    promoCodeSnapshot?: CheckoutOfferPromoCodeSnapshot | null;
+    locale?: string;
+    validUntil?: string | null;
+}
+
+/** Wire format of the `marketing_settings` row. */
+interface MarketingSettingsRow {
+    projectKey: string;
+    /** Runtime-activated subset of the `availableLocales` pool. */
+    activeLocales: string[];
+    updatedAt: string;
+}
+/** Body of `PUT /admin/catalog/marketing-settings`. */
+interface UpdateMarketingSettingsData {
+    activeLocales: string[];
+}
+
+/** Active promotion of a plan card — discount already computed. */
+interface PublicMarketingPromo {
+    type: PromotionType;
+    /** Locale-resolved badge (e.g. "Spring offer"). */
+    badge: string;
+    /** Locale-resolved fineprint below the CTA. */
+    fineprint: string;
+    /** UI accent color (ribbon). */
+    color: string;
+    /** Discounted net monthly price; null if not applicable. */
+    discountedMonthlyNet: number | null;
+    /** Discounted net yearly price; null if not applicable. */
+    discountedYearlyNet: number | null;
+}
+/** A fully marketed plan card. */
+interface PublicMarketingPlan {
+    planKey: string;
+    label: string;
+    /** Live PlanVersion ID — for the CheckoutOffer on click. */
+    planVersionId: string;
+    monthlyNet: number | null;
+    yearlyNet: number | null;
+    /** Editorial badge (empty = no badge). */
+    badge: string;
+    /** Teaser / description text. */
+    description: string;
+    highlight: boolean;
+    /**
+     * Formatted pricing tag from the MarketingProjection (#47, e.g.
+     * "€ 9.90 / month" or "on request"). null/missing = frontends
+     * format automatically from monthlyNet/yearlyNet.
+     */
+    priceTag?: string | null;
+    /** CTA override; null = automatic text. */
+    ctaLabel: string | null;
+    trialEnabled: boolean;
+    trialDays: number;
+    topFeatures: MarketingTopFeature[];
+    /** Sort priority DESC. */
+    priority: number;
+    /** Currently active promotion or null. */
+    promo: PublicMarketingPromo | null;
+    /** Feature keys included in the plan — for the comparison matrix. */
+    features: string[];
+    /** Quota limits of the plan (`-1` = unlimited) — for the matrix. */
+    quotas: Record<string, number>;
+}
+/**
+ * A marketed bundle card for the public catalog (P11.7.3 +
+ * P11.7.4). Bundles are offered as standalone add-ons to plans;
+ * `compatiblePlanKeys` lists the plans in which the bundle may be
+ * booked (empty = all plans allowed).
+ */
+interface PublicMarketingBundle {
+    bundleKey: string;
+    label: string;
+    /** Live BundleVersion ID — for the `add` request of the tenant self-service. */
+    bundleVersionId: string;
+    monthlyNet: number | null;
+    yearlyNet: number | null;
+    /** Description text (locale-resolved, falls back to bundle base). */
+    description: string;
+    /**
+     * Formatted pricing tag from the MarketingProjection (#47) — analogous
+     * to `PublicMarketingPlan.priceTag`. null/missing = automatic
+     * formatting from monthlyNet/yearlyNet.
+     */
+    priceTag?: string | null;
+    /** Feature keys included in the bundle. */
+    features: string[];
+    /** Quota top-ups of the bundle (`-1` = unlimited). */
+    quotas: Record<string, number>;
+    /** Currently active bundle promotion or null. */
+    promo: PublicMarketingPromo | null;
+    /**
+     * Plan keys the bundle is compatible with. Empty array =
+     * universal for all plans. The UI filters the display accordingly.
+     */
+    compatiblePlanKeys: string[];
+    /**
+     * Uncovered feature dependencies (#35): union of the `requires` of the
+     * contained features minus those contained in the bundle itself.
+     * The configurator greys out the bundle when these keys lie neither in
+     * the selected plan nor in the current selection. Missing/empty =
+     * self-contained or no requires data available.
+     */
+    requiresFeatures?: string[];
+    /**
+     * Locale-resolved display labels for `features` ∪ `requiresFeatures`
+     * (#48). `comparison.features` only covers the plan feature union —
+     * bundle-only features (e.g. RESOURCE_MANAGEMENT) would otherwise get no
+     * label. Source: curated FeatureCatalogEntries incl. i18n. Only keys
+     * with a curated entry are included; frontends fall back to the key
+     * itself for missing keys. Missing/empty = no
+     * CatalogEntryRepository registered.
+     */
+    featureLabels?: Record<string, string>;
+}
+/** A row of the comparison matrix (feature or quota). */
+interface PublicComparisonRow {
+    key: string;
+    /** Locale-resolved display label. */
+    label: string;
+    /** Quotas only: display unit. */
+    unit?: string;
+}
+/** Response of `GET /public/marketing-catalog`. */
+interface PublicMarketingCatalogResponse {
+    projectKey: string;
+    locale: string;
+    currency: string;
+    /** VAT rate in percent — for the CheckoutOffer price breakdown. */
+    vatRate: number;
+    /** Visible, marketed plans — sorted by `priority` DESC. */
+    plans: PublicMarketingPlan[];
+    /**
+     * Visible, marketed bundles (P11.7.3 + P11.7.4) — as standalone
+     * add-ons to the plans. The tenant self-service UI filters client-side
+     * via `compatiblePlanKeys` against its own plan; the backend
+     * does not filter here, so the marketing comparison page shows all
+     * bundles.
+     */
+    bundles: PublicMarketingBundle[];
+    /**
+     * Row definitions of the comparison matrix — union of all
+     * feature/quota keys across the visible plans, with labels.
+     */
+    comparison: {
+        features: PublicComparisonRow[];
+        quotas: PublicComparisonRow[];
+    };
+}
+
+/**
+ * Code status of a capability in the decorator (`@ImplementsCapability`):
+ *
+ * - `active`       — normally usable (default)
+ * - `experimental` — WIP capability; shown in the UI with a warning
+ * - `deprecated`   — to be replaced (`replacementKey` recommended)
+ * - `internal`     — does not appear in the SuperAdmin UI, but in the snapshot hash
+ */
+type DiscoveryCodeStatus = 'active' | 'experimental' | 'deprecated' | 'internal';
+/**
+ * A single capability entry in the DiscoverySnapshot — matches the
+ * wire format that `/admin/discovery` delivers.
+ */
+interface DiscoveredCapability {
+    capabilityKey: string;
+    label: string | null;
+    feature: string | null;
+    status: DiscoveryCodeStatus;
+    kind: CapabilityKind;
+    owner: string | null;
+    replacementKey: string | null;
+    removalPlannedAt: string | null;
+    reason: string | null;
+    /**
+     * Feature keys that this capability's feature requires at runtime
+     * (#35). `null` = no dependencies — the default, so that snapshots
+     * from older platform versions stay readable unchanged.
+     */
+    requires: string[] | null;
+    /**
+     * Old feature keys that this capability's feature replaces (#39,
+     * hard path: the old code has already been deleted). `null` = none.
+     */
+    replaces: string[] | null;
+    /**
+     * Where the capability is declared — `ClassName.methodName` for
+     * methods, `ClassName` for class level. Helps with forensics /
+     * discovery diff.
+     */
+    declaredAt: string;
+}
+/** Aggregate of several capabilities with `feature: 'X'`. */
+interface DiscoveredFeature {
+    featureKey: string;
+    /** Capability keys that declare this feature via `feature: 'X'`. */
+    capabilityKeys: string[];
+    /**
+     * Union of the capability `requires` minus its own featureKey (#35).
+     * `null` = no dependencies (backward-compatible with old snapshots).
+     */
+    requires: string[] | null;
+    /** Union of the capability `replaces` (#39). `null` = none. */
+    replaces: string[] | null;
+}
+/**
+ * Quota policy:
+ * - `monthlyReset` — counter is reset to 0 at the start of the month
+ * - `continuous`   — counter grows monotonically (e.g. storage consumption)
+ * - `hardCap`      — on overrun, HTTP 429 / domain-level block
+ */
+type DiscoveredQuotaPolicy = 'monthlyReset' | 'continuous' | 'hardCap';
+/** A quota declared in code via `@DefinesQuota`. */
+interface DiscoveredQuota {
+    quotaKey: string;
+    label: string;
+    unit: string;
+    policy: DiscoveredQuotaPolicy;
+    feature: string | null;
+    /** Old quotaKeys that this quota replaces (#39). `null` = none. */
+    replaces: string[] | null;
+    /** Where the quota is declared — `ClassName`. */
+    declaredAt: string;
+    /** Capability keys that reference this quota via `@EnforceQuota(quotaKey)`. */
+    enforcedBy: string[];
+}
+/**
+ * Complete discovery snapshot — built at boot time, delivered as JSON by
+ * the AdminController, checked against the DB catalog by the strict-mode
+ * check.
+ */
+interface DiscoverySnapshot {
+    schemaVersion: 1;
+    /** ISO timestamp of the boot-time scan. */
+    scannedAt: string;
+    app: {
+        /** projectKey, same concept as in the catalog tables. */
+        key: string;
+        /** Backend version, e.g. from package.json. */
+        version: string;
+    };
+    capabilities: DiscoveredCapability[];
+    features: DiscoveredFeature[];
+    quotas: DiscoveredQuota[];
+    /**
+     * Canonical SHA256 hash over sorted/normalized snapshot data.
+     * Stable across boot restarts, serves as the ETag for `/admin/discovery`.
+     */
+    hash: string;
+}
+
+interface EffectiveLimitsSnapshot {
+    plan: string;
+    quotas: Record<string, number>;
+    features: string[];
+}
+
+interface FeatureUiMeta {
+    /** Visible label for plan comparison tables, add-on lists. */
+    label: string;
+    /** Long description for tooltips, add-on cards. */
+    description: string;
+    /** Quasar icon name (e.g. 'directions_car', 'groups'). */
+    icon: string;
+    /** Mirror of `PlanCatalog.features[].plannedOnly` — cache for the UI without a catalog roundtrip. */
+    plannedOnly?: boolean;
+    /** true = base infrastructure, included in every plan (not bookable). */
+    core?: boolean;
+}
+/** Map FeatureKey → UI metadata. Consumer apps supply a complete table. */
+type FeatureUiRegistry = Record<string, FeatureUiMeta>;
+
+/** Alias for historical compatibility — equivalent to VersionChangeDirection. */
+type ChangeDirection = VersionChangeDirection;
+interface DiffResult {
+    nonRegressive: boolean;
+    changes: VersionChange[];
+}
+/**
+ * `Decimal | string | number` — the three forms in which prices appear
+ * in the platform. `Decimal` is the Prisma class (with
+ * `.toNumber()`), which is not imported directly in order to keep the
+ * platform Prisma-free — a structural view suffices.
+ */
+type DecimalLike = number | string | {
+    toNumber(): number;
+};
+interface PlanVersionFields {
+    features: FeatureKey[];
+    maxUsers: number;
+    maxVehicles: number;
+    maxStorageGb: number;
+    monthlyNet: DecimalLike;
+    yearlyNet: DecimalLike;
+}
+interface BundleVersionFields {
+    features: FeatureKey[];
+    /** Quota contributions of the bundle. -1 = unlimited; missing key = 0. */
+    quotas: Record<QuotaKey, number>;
+    /** Default pricing; null = only override pricing possible. */
+    monthlyNet: DecimalLike | null;
+    yearlyNet: DecimalLike | null;
+}
+declare function classifyPlanDiff(oldV: PlanVersionFields, newV: PlanVersionFields): DiffResult;
+/**
+ * Classification of a BundleVersion diff for contract protection.
+ *
+ * Quota comparison: `-1` (unlimited) is always better than any positive
+ * number. Otherwise higher = better. Missing keys are treated as 0.
+ *
+ * Pricing can be `null` (the bundle only has override pricing); a switch
+ * from value ↔ null is classified as REGRESSION (value dropped) or IMPROVEMENT
+ * (value added, lowerIsBetter inverted). Both null
+ * stay NEUTRAL.
+ */
+declare function classifyBundleVersionDiff(oldV: BundleVersionFields, newV: BundleVersionFields): DiffResult;
+
+interface PromoPreviewRequest {
+    /** Promo code (case-insensitive, normalized to uppercase in the service). */
+    code: string;
+    /** Plan ID the code is validated against. */
+    plan: PlanId;
+    billingCycle: BillingCycle;
+    /** Optional — for the firstTimeCustomersOnly check. */
+    email?: string;
+}
+/**
+ * Wire format of the service response. Decimals as string (two decimal places),
+ * dates as ISO-8601 string. Corresponds 1:1 to the service return type
+ * `PreviewResult` (@saasicat/nest/promo).
+ */
+type PromoPreviewResponse = {
+    valid: false;
+    reason: PromoPreviewInvalidReason;
+} | PromoPreviewValidResponse;
+type PromoPreviewInvalidReason = 'NOT_FOUND' | 'EXPIRED' | 'EXHAUSTED' | 'PAUSED' | 'PLAN_MISMATCH' | 'BILLING_MISMATCH' | 'BELOW_MINIMUM_AMOUNT' | 'WOULD_PRODUCE_ZERO_INVOICE' | 'NOT_FIRST_TIME_CUSTOMER' | 'RATE_LIMITED';
+interface PromoPreviewValidResponse {
+    valid: true;
+    code: string;
+    label: string;
+    discount: {
+        valueType: 'PERCENT' | 'ABSOLUTE';
+        /** Decimal-as-string. */
+        value: string;
+        durationType: 'ONCE' | 'MONTHS' | 'BILLING_CYCLES';
+        durationValue: number | null;
+    };
+    price: {
+        /** Decimal-as-string, e.g. "199.00". */
+        originalGross: string;
+        discountGross: string;
+        discountedGross: string;
+        includedVat: string;
+        nextRegularAmountGross: string;
+        /** ISO date from which the regular price applies, or null for ONCE. */
+        regularStartsAt: string | null;
+    };
+}
+interface OnboardingSelectionRequest {
+    plan: PlanId;
+    billingCycle: BillingCycle;
+    /**
+     * Optional: live BundleVersion IDs of independently bookable bundles.
+     * These are booked best-effort by the backend after the plan setup.
+     */
+    bundleVersionIds?: string[];
+    /** Optional — if set, the code is redeemed atomically with the plan selection. */
+    promoCode?: string;
+}
+interface OnboardingSelectionResponse {
+    plan: PlanId;
+    billingCycle: BillingCycle;
+    /**
+     * Number of bundles actually booked (P11.7.3). Bundles are added
+     * best-effort **after** the plan change — failed bookings end up as
+     * warnings without rolling back the plan change.
+     */
+    bundlesAdded: number;
+    /**
+     * Promo redemption — `null` if no code was sent or the redemption
+     * failed (plan change + bundles are then persisted anyway; the UI shows
+     * a hint and lets the tenant redeem the code later via
+     * `POST /billing/promo/redeem`).
+     */
+    promoRedemption: OnboardingPromoRedemption | null;
+    /**
+     * Additional quota hints or warnings the service produced during
+     * onboarding (e.g. plan-downgrade blockers that were not applied, or
+     * bundle-booking errors). Empty on success without anomalies.
+     */
+    warnings: string[];
+}
+interface OnboardingPromoRedemption {
+    code: string;
+    discount: {
+        valueType: 'PERCENT' | 'ABSOLUTE';
+        value: string;
+        durationType: 'ONCE' | 'MONTHS' | 'BILLING_CYCLES';
+        durationValue: number | null;
+    };
+    /** ISO date. */
+    startsAt: string;
+    /** ISO date or null for ONCE. */
+    endsAt: string | null;
+}
+
+interface PlanRow {
+    id: string;
+    projectKey: string;
+    planKey: string;
+    label: string;
+    description: string | null;
+    icon: string | null;
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+/**
+ * Fields that must be set when creating a new plan stem. `id`, `createdAt`,
+ * `updatedAt`, `deletedAt` are assigned by the repository. PlanVersion-specific
+ * fields (features, quotas, pricing) belong in a separate `PlanVersion`
+ * creation (follows in M6 Pack 2).
+ */
+interface CreatePlanData {
+    projectKey: string;
+    planKey: string;
+    label: string;
+    description?: string | null;
+    icon?: string | null;
+    sortOrder?: number;
+}
+/**
+ * Fields that may be changed on the plan stem. `planKey` and `projectKey`
+ * are deliberately not here — stem identity is immutable; whoever wants to
+ * change it creates a new plan and retires the old one.
+ */
+interface UpdatePlanData {
+    label?: string;
+    description?: string | null;
+    icon?: string | null;
+    sortOrder?: number;
+}
+
+/**
+ * PlanVersion — versioned plan definition (`BASIC v3`, `STANDARD v7`, …).
+ *
+ * Quotas: the platform convention is `quotas: { users: 10, vehicles: 50, … }`.
+ * Legacy backends ship flat fields (`maxUsers`, `maxVehicles`,
+ * `maxStorageGb`); these are marked optional and are tolerated by the
+ * lift-and-shift catalog-builder layer. An index signature allows further
+ * app-specific fields.
+ */
+interface PlanVersionRow extends VersionedEntityBase {
+    planId: PlanId;
+    features: FeatureKey[];
+    /**
+     * Bundle selection assembled in the editor (bundleKeys,
+     * SCREAMING_SNAKE_CASE). A bundle in this list implies that all of its
+     * features are also contained in `features` — bundles are marketing
+     * groupings of features. Persisted so the editor can reconstruct the
+     * original bundle selection and the public catalog can present the plan
+     * as a bundle. Optional, because consumer backends add the column
+     * additively — if it is missing, the selection is empty and the editor
+     * derives fully-active bundles from `features`.
+     */
+    bundles?: string[];
+    quotas?: Record<QuotaKey, number>;
+    monthlyNet: string;
+    yearlyNet: string;
+    marketed: boolean;
+    /**
+     * End date explicitly set by the SuperAdmin for a live PlanVersion.
+     * Null = no end date, runs indefinitely until superseded by a successor
+     * version (auto-succession then sets `supersededAt`).
+     *
+     * Unlike `validUntil` (auto-succession, maintained by the service),
+     * `endsAt` is user-initiated: `POST /admin/catalog/plan-versions/:id/terminate`
+     * sets the field. When `endsAt < NOW()` the version is no longer live for
+     * new bookings — existing subscriptions (P1) stay bound.
+     *
+     * Optional, because consumer backends add the column additively — if it
+     * is missing, there is no end date.
+     */
+    endsAt?: string | null;
+    /** @deprecated Read from `quotas['users']` once available. */
+    maxUsers?: number;
+    /** @deprecated Legacy field; read from `quotas['vehicles']`. */
+    maxVehicles?: number;
+    /** @deprecated Read from `quotas['storageGb']`. */
+    maxStorageGb?: number;
+}
+
+interface UpsertResult {
+    created: boolean;
+    /** If `created=false`, a short reason is here (e.g. "exists"). */
+    skipReason?: string;
+}
+interface UpsertPlanInput {
+    projectKey: string;
+    planKey: string;
+    label: string;
+    description?: string | null;
+    sortOrder?: number;
+}
+interface UpsertPlanVersionInput {
+    /** planKey, not the plan UUID — the sink resolves internally. */
+    planKey: string;
+    version: number;
+    features: FeatureKey[];
+    quotas: Record<QuotaKey, number>;
+    monthlyNet: string;
+    yearlyNet: string;
+    marketed: boolean;
+    /** For the importer: always published=true (`publishedAt = NOW`). */
+    publish: boolean;
+    changeNote: string;
+}
+interface UpsertFeatureCatalogEntryInput {
+    projectKey: string;
+    featureKey: FeatureKey;
+    label?: string;
+    icon?: string;
+    tier?: string;
+    plannedOnly?: boolean;
+    core?: boolean;
+}
+/**
+ * Adapter port for the plan catalog importer. Apps implement it
+ * against their Prisma client (or another persistence stack).
+ */
+interface PlanCatalogImportSink {
+    upsertPlan(input: UpsertPlanInput): Promise<UpsertResult>;
+    upsertPlanVersion(input: UpsertPlanVersionInput): Promise<UpsertResult>;
+    upsertFeatureCatalogEntry(input: UpsertFeatureCatalogEntryInput): Promise<UpsertResult>;
+}
+interface PlanCatalogImportReport {
+    plansCreated: number;
+    plansSkipped: number;
+    planVersionsCreated: number;
+    planVersionsSkipped: number;
+    featureEntriesCreated: number;
+    featureEntriesSkipped: number;
+    /** Warnings (non-fatal, e.g. "feature without label"). */
+    warnings: string[];
+}
+
+interface PlanCatalogReadSnapshot {
+    /** Plan stems (deletedAt IS NULL). */
+    plans: PlanRow[];
+    /**
+     * Live PlanVersions: per `planId` (= planKey) the currently published
+     * version (publishedAt IS NOT NULL AND supersededAt IS NULL).
+     * Apps with plans without a live version take over the plan, but without
+     * pricing/quotas — the importer probably emitted a warning.
+     */
+    livePlanVersions: PlanVersionRow[];
+    /** Feature catalog entries (deletedAt IS NULL). */
+    featureEntries: FeatureCatalogEntryRow[];
+}
+/**
+ * Adapter port for the DB-based PlanCatalog assembly. Apps
+ * implement it against their Prisma tables.
+ */
+interface PlanCatalogReadSink {
+    loadSnapshot(projectKey: string): Promise<PlanCatalogReadSnapshot>;
+}
+
+/**
+ * Fields of a new PlanVersion in draft status (`publishedAt = null`).
+ * Created by the SuperAdmin, later published via `publishPlanVersion()`.
+ * Only **one** draft version per `planId` is allowed
+ * (partial unique index in the migration).
+ */
+interface CreatePlanVersionDraftData {
+    /**
+     * **planKey** (e.g. "STARTER"), not the plan UUID. The service
+     * resolves the plan UUID from the controller path param to
+     * planKey beforehand. Adapters may store that semantic key directly or
+     * translate it to a normalized `Plan.id` foreign key.
+     */
+    planId: string;
+    /** Predecessor version the diff is computed against (null for v1). */
+    baseVersionId?: string | null;
+    features: FeatureKey[];
+    /** Bundle selection (bundleKeys). Default empty. See `PlanVersionRow.bundles`. */
+    bundles?: string[];
+    quotas: Record<QuotaKey, number>;
+    monthlyNet: string;
+    yearlyNet: string;
+    marketed?: boolean;
+    /** Required on publish (contract protection P3). */
+    changeNote?: string;
+    /** Optional in the draft (required on publish). ISO date string. */
+    validFrom?: string | null;
+    /** Optional; null = valid indefinitely. ISO date string. */
+    validUntil?: string | null;
+    createdByUserId?: string | null;
+}
+/**
+ * Fields of a draft PlanVersion that may still be changed.
+ * After `publishedAt` the version becomes immutable (contract protection P1/P4).
+ */
+interface UpdatePlanVersionDraftData {
+    features?: FeatureKey[];
+    /** Bundle selection (bundleKeys). See `PlanVersionRow.bundles`. */
+    bundles?: string[];
+    quotas?: Record<QuotaKey, number>;
+    monthlyNet?: string;
+    yearlyNet?: string;
+    marketed?: boolean;
+    changeNote?: string;
+    validFrom?: string | null;
+    validUntil?: string | null;
+}
+/**
+ * Input for `publishPlanVersion()`. The service computes `nonRegressive` and
+ * `publishedChanges` from the diff to the predecessor version (
+ * §7); the caller only provides confirmation + user tag.
+ *
+ * `validFrom` is **required** on publish. If the draft
+ * already has a `validFrom`, it is optional here. Auto-succession sets
+ * `validUntil` of the predecessor version.
+ */
+interface PublishPlanVersionData {
+    publishedByUserId: string | null;
+    /**
+     * If true and the diff classifies the version as regressive,
+     * it is published anyway (bulk-publish MFA confirmation,
+     */
+    forceRegressive?: boolean;
+    /**
+     * Allows publishing despite a price of 0.00. Default false: a 0.00 publish
+     * is blocked to prevent accidentally going live with seed placeholders.
+     * Only for deliberately free special contracts (e.g. ENTERPRISE).
+     */
+    allowZeroPrice?: boolean;
+    /**
+     * Required on publish if the draft has no `validFrom`. Must lie
+     * strictly after the `validFrom` of the predecessor version.
+     */
+    validFrom?: string | null;
+    /**
+     * Optional; null = valid indefinitely (fits the last version
+     * of a plan). Automatically overwritten by the service when a
+     * successor version is created.
+     */
+    validUntil?: string | null;
+}
+/**
+ * Service result for mutating PlanVersion operations
+ * (createDraft, updateDraft, publish): returns the persisted row plus
+ * a list of strict-mode warnings. In `warn-only` mode → banner in the UI;
+ * in `blocking` mode the service throws HTTP 422 instead with
+ * the same warning list.
+ */
+interface PlanVersionMutationResult {
+    planVersion: PlanVersionRow;
+    warnings: StrictModeWarning[];
+}
+
+type PlatformRole = 'SUPER_ADMIN' | 'TENANT_ADMIN' | 'TENANT_MEMBER';
+interface TenantDto {
+    id: string;
+    slug: string;
+    name: string;
+    isActive: boolean;
+    settings?: Record<string, unknown>;
+    deletedAt: string | null;
+}
+interface CreateTenantInput {
+    slug: string;
+    name: string;
+    settings?: Record<string, unknown>;
+}
+interface TenantListFilter {
+    status?: 'active' | 'suspended' | 'deleted';
+    plan?: string;
+    search?: string;
+    page?: number;
+    pageSize?: number;
+}
+interface Paginated<T> {
+    items: T[];
+    page: number;
+    pageSize: number;
+    total: number;
+}
+interface PlatformUserDto {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    platformRole: PlatformRole;
+    isActive: boolean;
+    lastLoginAt: string | null;
+    deletedAt: string | null;
+}
+interface UserListFilter {
+    search?: string;
+    role?: PlatformRole;
+    page?: number;
+    pageSize?: number;
+}
+/** Adapter to the project's own tenant schema. */
+interface TenantPort {
+    findById(id: string): Promise<TenantDto | null>;
+    findBySlug(slug: string): Promise<TenantDto | null>;
+    list(filter: TenantListFilter): Promise<Paginated<TenantDto>>;
+    create(input: CreateTenantInput): Promise<TenantDto>;
+    setActive(id: string, active: boolean, reason: string): Promise<void>;
+    softDelete(id: string, reason: string): Promise<void>;
+}
+/** Adapter to the project's own user schema. */
+interface UserPort {
+    findById(id: string): Promise<PlatformUserDto | null>;
+    findByEmail(email: string): Promise<PlatformUserDto | null>;
+    countActive(tenantId: string): Promise<number>;
+    listForTenant(tenantId: string, filter: UserListFilter): Promise<Paginated<PlatformUserDto>>;
+    resetPassword(userId: string, newHash: string): Promise<void>;
+    hasRole(userId: string, role: PlatformRole): Promise<boolean>;
+}
+interface CreateSuperAdminCliInput {
+    email: string;
+    /**
+     * Plaintext password. The adapter hashes it with the app's own method
+     * (argon2/bcrypt) — hashing therefore stays app-specific, the shared
+     * command doesn't know the algorithm.
+     */
+    password: string;
+    firstName?: string;
+    lastName?: string;
+}
+interface ReassignTenantAdminCliResult {
+    user: PlatformUserDto;
+    /** true if a new emergency admin was created (instead of a promotion). */
+    created: boolean;
+    /** Previous role on promotion; null on new creation. */
+    previousRole: PlatformRole | null;
+    /** On new creation: generated initial password that the admin passes on. */
+    oneTimePassword?: string;
+}
+interface PasswordResetCliResult {
+    user: PlatformUserDto;
+    /**
+     * If the app generates a one-time password (instead of an OTP/reset email),
+     * it's returned here so the command can output it out-of-band.
+     */
+    oneTimePassword?: string;
+}
+interface CliUserRow {
+    email: string;
+    role: PlatformRole;
+    status: string;
+    lastLoginAt: string | null;
+}
+/**
+ * Write/list operations for the shared `<app> user` CLI command. Separates
+ * the app-specific schema mutations (password hashing, role mapping,
+ * tenant relationship) from the generic command flow (identity/MFA/audit/output).
+ * Consumers register an implementation via
+ * `CliContextModule.forRoot({ userManagementPort })`.
+ */
+/**
+ * Narrow port for the first-run setup (interface segregation): ONLY
+ * an existence check + creation of the first SUPER_ADMIN. The `SetupModule` depends
+ * solely on this — a consumer that only wants the setup wizard doesn't need to
+ * implement tenant user management.
+ */
+interface SuperAdminProvisioningPort {
+    /** Number of active SUPER_ADMIN users — basis for the first-run setup guard. */
+    countSuperAdmins(): Promise<number>;
+    /** Creates a new SUPER_ADMIN; throws `PlatformUserExistsError` if the email exists. */
+    createSuperAdmin(input: CreateSuperAdminCliInput): Promise<PlatformUserDto>;
+}
+interface UserManagementPort extends SuperAdminProvisioningPort {
+    /** Promotes an existing user to TENANT_ADMIN or creates an emergency admin. */
+    reassignTenantAdmin(tenantSlug: string, email: string): Promise<ReassignTenantAdminCliResult>;
+    /** Lists a tenant's users (by slug) for `<app> user list`. */
+    listTenantUsers(tenantSlug: string): Promise<CliUserRow[]>;
+    /** Triggers the app's own password reset (one-time password or OTP email). */
+    triggerPasswordReset(email: string): Promise<PasswordResetCliResult>;
+    /** Deactivates a user (app-specific status). */
+    deactivate(email: string, reason: string): Promise<PlatformUserDto>;
+}
+/** Returns current usage for a limit dimension. */
+interface QuotaProvider {
+    /** quotaKey, as declared via `@DefinesQuota({ key })`. */
+    readonly key: string;
+    count(tenantId: string): Promise<number>;
+    /** Optional: cache TTL in seconds (default 30s). */
+    readonly cacheTtlSeconds?: number;
+}
+/**
+ * Password hashing adapter. The algorithm (argon2/bcrypt) stays app-specific;
+ * platform flows that persist credentials (registration, SuperAdmin
+ * bootstrap) hash through this port instead of choosing an algorithm.
+ */
+interface PasswordHasher {
+    hash(plain: string): Promise<string>;
+    verify(hash: string, plain: string): Promise<boolean>;
+}
+/** Adapter for MFA secret persistence. */
+interface MfaPort {
+    /** Returns the stored TOTP secret or null. */
+    getSecret(userId: string): Promise<string | null>;
+    /** Persists or deletes (null) the TOTP secret. */
+    setSecret(userId: string, secret: string | null): Promise<void>;
+    /** The platform calls this during the mfa-setup command. */
+    isEnabled(userId: string): Promise<boolean>;
+}
+/**
+ * Opaque transaction context. The consumer determines the concrete type
+ * (e.g. `Prisma.TransactionClient`). Platform code only passes it
+ * through — no content inspection.
+ */
+type TransactionContext = unknown;
+/**
+ * Transaction runner — wrapper over `prisma.$transaction`,
+ * Django `transaction.atomic`, etc.
+ */
+interface TransactionRunner {
+    run<T>(fn: (tx: TransactionContext) => Promise<T>): Promise<T>;
+}
+
+/**
+ * Snapshot of a `PromoCode` row for service-layer calls. Decimals as
+ * strings (`value`, `minimumPlanAmountGross`) — the service parses them to
+ * `number` for calculations, the consumer adapter maps from its
+ * `Prisma.Decimal` (toString()).
+ */
+interface PromoCodeRecord {
+    id: string;
+    code: string;
+    valueType: PromoCodeValueType;
+    /** Decimal-as-string (e.g. "25.00"). */
+    value: string;
+    durationType: PromoCodeDurationType;
+    durationValue: number | null;
+    validFrom: Date | null;
+    validUntil: Date | null;
+    maxRedemptions: number | null;
+    redemptionsCount: number;
+    appliesToPlans: string[];
+    appliesToBilling: BillingCycle | null;
+    firstTimeCustomersOnly: boolean;
+    /** Decimal-as-string or null. */
+    minimumPlanAmountGross: string | null;
+    allowZeroInvoice: boolean;
+    status: PromoCodeStatus;
+    description: string | null;
+    campaignTag: string | null;
+    revenueDeductionAccount: string | null;
+    createdById: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt: Date | null;
+}
+/** Snapshot of a `PromoCodeRedemption` row. */
+interface PromoCodeRedemptionRecord {
+    id: string;
+    promoCodeId: string;
+    subscriptionId: string;
+    tenantId: string;
+    appliedValueType: PromoCodeValueType;
+    appliedValue: string;
+    appliedDurationType: PromoCodeDurationType;
+    appliedDurationValue: number | null;
+    startsAt: Date;
+    endsAt: Date | null;
+    status: PromoCodeRedemptionStatus;
+    redeemedAt: Date;
+    reversedAt: Date | null;
+}
+/** Input for `PromoCodesService.create()`. */
+interface CreatePromoCodeData {
+    code: string;
+    valueType: PromoCodeValueType;
+    /** Numeric — the service serializes to a decimal string. */
+    value: number;
+    durationType: PromoCodeDurationType;
+    durationValue?: number | null;
+    validFrom?: Date | null;
+    validUntil?: Date | null;
+    maxRedemptions?: number | null;
+    appliesToPlans?: string[];
+    appliesToBilling?: BillingCycle | null;
+    firstTimeCustomersOnly?: boolean;
+    minimumPlanAmountGross?: number | null;
+    allowZeroInvoice?: boolean;
+    description?: string | null;
+    campaignTag?: string | null;
+    revenueDeductionAccount?: string | null;
+    createdById: string;
+}
+/** Input for `PromoCodesService.update()`. */
+interface UpdatePromoCodeData {
+    status?: PromoCodeStatus;
+    valueType?: PromoCodeValueType;
+    value?: number;
+    durationType?: PromoCodeDurationType;
+    durationValue?: number | null;
+    validFrom?: Date | null;
+    description?: string | null;
+    validUntil?: Date | null;
+    maxRedemptions?: number | null;
+    appliesToPlans?: string[];
+    appliesToBilling?: BillingCycle | null;
+    firstTimeCustomersOnly?: boolean;
+    minimumPlanAmountGross?: number | null;
+    allowZeroInvoice?: boolean;
+    campaignTag?: string | null;
+    revenueDeductionAccount?: string | null;
+}
+/** Filter for `PromoCodesService.findAll()`. */
+interface PromoCodeFilter {
+    status?: PromoCodeStatus;
+    campaignTag?: string;
+    /** Substring search in the code (case-insensitive on UPPERCASE). */
+    search?: string;
+}
+/** Entry for `PromoCodeRedemptionRepository.listByPromoCode()`. */
+interface PromoCodeRedemptionListItem extends PromoCodeRedemptionRecord {
+    tenant?: {
+        id: string;
+        name: string;
+        slug: string;
+    } | null;
+}
+/**
+ * Adapter for PromoCode persistence. Atomic slot reservation lives in the
+ * adapter because it is DB-specific (Postgres `UPDATE ... WHERE ... AND
+ * (maxRedemptions IS NULL OR redemptionsCount < maxRedemptions)`).
+ */
+interface PromoCodeRepository {
+    findById(id: string): Promise<PromoCodeRecord | null>;
+    findByCode(code: string, tx?: TransactionContext): Promise<PromoCodeRecord | null>;
+    findMany(filter: PromoCodeFilter): Promise<PromoCodeRecord[]>;
+    create(data: CreatePromoCodeData): Promise<PromoCodeRecord>;
+    update(id: string, data: UpdatePromoCodeData): Promise<PromoCodeRecord>;
+    softDelete(id: string): Promise<void>;
+    /**
+     * Atomic slot reservation: increments `redemptionsCount` and checks
+     * `status === 'ACTIVE' && (maxRedemptions IS NULL || redemptionsCount < maxRedemptions)`.
+     * Returns true if the slot was reserved, false if EXHAUSTED
+     * or the status is not ACTIVE.
+     */
+    claimSlot(id: string, tx?: TransactionContext): Promise<boolean>;
+    /** Sets the status to `EXHAUSTED` when `redemptionsCount >= maxRedemptions`. */
+    markExhaustedIfFull(id: string, tx?: TransactionContext): Promise<void>;
+    /** Decrements `redemptionsCount` by 1 (min 0); EXHAUSTED → ACTIVE. */
+    releaseSlot(id: string, tx?: TransactionContext): Promise<void>;
+    /**
+     * Bulk-expire cron: sets all codes with `validUntil < now` and status
+     * ACTIVE/PAUSED to EXPIRED. Returns: number of updated rows.
+     */
+    expireDueCodes(now: Date): Promise<number>;
+}
+/** Adapter for PromoCodeRedemption persistence. */
+interface PromoCodeRedemptionRepository {
+    findBySubscription(subscriptionId: string, tx?: TransactionContext): Promise<PromoCodeRedemptionRecord | null>;
+    create(data: Omit<PromoCodeRedemptionRecord, 'id' | 'redeemedAt' | 'status' | 'reversedAt'>, tx?: TransactionContext): Promise<PromoCodeRedemptionRecord>;
+    setReversed(id: string, tx?: TransactionContext): Promise<PromoCodeRedemptionRecord>;
+    countByPromoCode(promoCodeId: string, status?: PromoCodeRedemptionStatus): Promise<number>;
+    listByPromoCode(promoCodeId: string): Promise<PromoCodeRedemptionListItem[]>;
+    expireDueRedemptions(now: Date): Promise<number>;
+}
+/** Adapter for `PromoCodeValidationLog` writes. */
+interface PromoCodeValidationLogRepository {
+    log(args: {
+        promoCodeId: string | null;
+        codeAttempt: string;
+        result: string;
+        ipHash?: string;
+        sessionId?: string;
+    }): Promise<void>;
+    /** Number of `result = 'VALID'` logs for a promo code. */
+    countValid(promoCodeId: string): Promise<number>;
+}
+/**
+ * First-time-customer check for the `firstTimeCustomersOnly` eligibility.
+ * The consumer implementation decides what "first time" means. Important:
+ * unfinished onboarding drafts must not count as an existing customer.
+ */
+interface FirstTimeCustomerCheck {
+    /** Returns true if a completed/historical customer already exists for the email. */
+    hasExistingCustomerForEmail(email: string): Promise<boolean>;
+}
+/** Subscription lookup for `redeem()`. Sufficient for promo calculations. */
+interface PromoSubscriptionLookup {
+    findById(subscriptionId: string, tx?: TransactionContext): Promise<{
+        id: string;
+        tenantId: string;
+        plan: string;
+        billingCycle: BillingCycle;
+        startedAt: Date | null;
+    } | null>;
+}
+/**
+ * Aggregation adapter for the stats endpoint (`PromoCodesService.stats`).
+ * Consumers without an `InvoiceDiscount` table return '0.00'.
+ */
+interface PromoRevenueDeductionAggregator {
+    /** Sum of the amountGross values for all redemptions of a promo code (Decimal-as-string). */
+    sumGrossForPromoCode(promoCodeId: string): Promise<string>;
+}
+
+type ContractLineItemKind = 'plan' | 'bundle' | 'discount';
+type SubscriptionContractStatus = 'active' | 'scheduled' | 'terminated' | 'superseded';
+interface ContractLineItemRecord {
+    id: string;
+    contractId: string;
+    kind: ContractLineItemKind;
+    sourceKey: string;
+    sourceVersionId: string | null;
+    titleSnapshot: string;
+    descriptionSnapshot: string | null;
+    quantity: number;
+    unit: string | null;
+    priceNet: number;
+    priceGross: number;
+    billingCycle: 'monthly' | 'yearly';
+    minimumTermUntil: Date | null;
+    featuresSnapshot: string[];
+    quotaEffectsSnapshot: Record<string, number>;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+}
+interface SubscriptionContractPriceSnapshot {
+    currency: string;
+    billingCycle: 'monthly' | 'yearly';
+    subtotalNet: number;
+    discountNet: number;
+    totalNet: number;
+    vatRate: number;
+    totalGross: number;
+}
+interface SubscriptionContractRecord {
+    id: string;
+    projectKey: string;
+    tenantId: string;
+    status: SubscriptionContractStatus;
+    effectiveFrom: Date;
+    effectiveUntil: Date | null;
+    originalOfferId: string | null;
+    originalPlanVersionId: string | null;
+    originalBundleVersionIds: string[];
+    entitlementSnapshot: EffectiveLimitsSnapshot | null;
+    priceSnapshot: SubscriptionContractPriceSnapshot;
+    promotionSnapshots: unknown[];
+    promoCodeSnapshots: unknown[];
+    termsSnapshot: Record<string, unknown> | null;
+    lineItems: ContractLineItemRecord[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+type NewContractLineItemData = Omit<ContractLineItemRecord, 'id' | 'contractId' | 'createdAt'>;
+interface CreateSubscriptionContractData {
+    projectKey: string;
+    tenantId: string;
+    status?: SubscriptionContractStatus;
+    effectiveFrom: Date;
+    effectiveUntil?: Date | null;
+    originalOfferId?: string | null;
+    originalPlanVersionId?: string | null;
+    originalBundleVersionIds?: string[];
+    entitlementSnapshot?: EffectiveLimitsSnapshot | null;
+    priceSnapshot: SubscriptionContractPriceSnapshot;
+    promotionSnapshots?: unknown[];
+    promoCodeSnapshots?: unknown[];
+    termsSnapshot?: Record<string, unknown> | null;
+    lineItems: NewContractLineItemData[];
+}
+interface TerminateSubscriptionContractData {
+    effectiveUntil: Date;
+    status: Extract<SubscriptionContractStatus, 'terminated' | 'superseded'>;
+}
+interface SubscriptionContractFilter {
+    projectKey?: string;
+    tenantId?: string;
+    status?: SubscriptionContractStatus;
+    asOf?: Date;
+}
+interface InvoiceLineItemSnapshot {
+    sourceContractLineItemId: string;
+    sourceKey: string;
+    sourceVersionId: string | null;
+    kind: ContractLineItemKind;
+    title: string;
+    description: string | null;
+    quantity: number;
+    unit: string | null;
+    priceNet: number;
+    priceGross: number;
+    billingCycle: 'monthly' | 'yearly';
+    minimumTermUntil: Date | null;
+    metadata: Record<string, unknown> | null;
+}
+interface SubscriptionContractInvoiceSnapshot {
+    contractId: string;
+    projectKey: string;
+    tenantId: string;
+    originalOfferId: string | null;
+    currency: string;
+    billingCycle: 'monthly' | 'yearly';
+    effectiveFrom: Date;
+    effectiveUntil: Date | null;
+    subtotalNet: number;
+    discountNet: number;
+    totalNet: number;
+    vatRate: number;
+    totalGross: number;
+    lineItems: InvoiceLineItemSnapshot[];
+}
+
+/**
+ * Snapshot form of a `Subscription` row for the EntitlementService
+ * computation. The consumer maps its Prisma structure onto this form.
+ */
+interface SubscriptionRecord {
+    id: string;
+    tenantId: string;
+    plan: string;
+    status: string;
+    isPilot?: boolean;
+    trialEntitlementPlan?: string | null;
+    pendingPlan?: string | null;
+    pendingEffectiveAt?: Date | null;
+    customLimits?: {
+        quotas?: Record<string, number>;
+        features?: string[];
+    } | null;
+    planVersionId: string;
+    planVersion: PlanVersionRecord;
+}
+/** Snapshot of a `PlanVersion` row. */
+interface PlanVersionRecord {
+    planId: string;
+    quotas: Record<string, number>;
+    features: string[];
+}
+/**
+ * Read adapter for subscriptions. The consumer implementation loads from its
+ * own `Subscription` table incl. eager-loaded `planVersion`
+ * and maps to `SubscriptionRecord`.
+ */
+interface SubscriptionRepository {
+    /** Returns a tenant's subscription or null. */
+    findByTenantId(tenantId: string): Promise<SubscriptionRecord | null>;
+    /**
+     * Like `findByTenantId`, but within the transaction with a row lock
+     * (`SELECT ... FOR UPDATE`). Used by the transactional `enforceLimit`
+     * path to serialize concurrent creations on the same tenant.
+     */
+    findByTenantIdLocked(tenantId: string, tx: TransactionContext): Promise<SubscriptionRecord | null>;
+    /**
+     * Counts subscriptions that bind a specific PlanVersion — both
+     * via the active `planVersionId` and via the scheduled `pendingPlanVersionId`.
+     * Needed by the `PlanVersionsService` for the editability decision:
+     * a published-but-future PlanVersion stays correctable only as long
+     * as no booking references it.
+     *
+     * Optional for backwards-compat reasons — if an adapter does not
+     * implement the method, the service defensively treats the version as
+     * frozen (fail-closed). Implementation hint: count in a single
+     * COUNT(*) over the subscription table with an OR over the two
+     * FK columns — not in two separate queries, to avoid race conditions.
+     */
+    countByPlanVersionId?(planVersionId: string): Promise<number>;
+    /**
+     * Counts active (= not-canceled, or cancellation still in the future)
+     * SubscriptionBundle entries that bind a specific BundleVersion.
+     * Bundles are versioned and marketed independently (analogous to
+     * plans); the `BundlesService` needs the count for the editability
+     * decision of a published-but-future BundleVersion.
+     *
+     * Implementation since P11.7.3: direct COUNT on
+     * `subscription_bundles WHERE bundleVersionId = ? AND
+     * (canceledAt IS NULL OR canceledEffectiveAt > NOW())`. Apps without
+     * a SubscriptionBundle schema (or without the platform migration) can
+     * still return 0; the editability feature is then no longer
+     * fail-closed against bookings, but still latest-in-chain +
+     * validFrom-future.
+     *
+     * Optional — if not implemented, the service defensively treats the
+     * version as frozen (fail-closed).
+     */
+    countByBundleVersionId?(bundleVersionId: string): Promise<number>;
+    /**
+     * Counts active subscriptions (status `ACTIVE` or `TRIAL`) per plan key,
+     * platform-wide across all tenants of the project — feeds the tenant
+     * column of the SuperAdmin plan list (`GET /admin/catalog/plans/tenant-counts`).
+     * Cross-version: counts the plan, not a single PlanVersion
+     * (subscriptions on superseded versions are included). `projectKey` is
+     * informational for single-project consumers.
+     *
+     * Returns a map `planKey → count`; plans without an active subscription
+     * are missing (UI defaults to 0). Platform-wide count across all tenants →
+     * adapters must count RLS-exempt.
+     *
+     * Optional — if not implemented, the tenant column stays 0.
+     */
+    countActiveByPlanKey?(projectKey: string): Promise<Record<string, number>>;
+}
+/**
+ * Adapter for the `subscription_bundles` junction.
+ * Consumers implement it against their Prisma table. Writing
+ * via `add` / `cancel` is always a side effect of the subscription-service
+ * methods — the repository is dumb persistence, no domain
+ * constraints (plan compatibility, minimum-term default) here.
+ */
+interface SubscriptionBundleRepository {
+    /** All bundle bookings of a subscription, newest first. */
+    listBySubscription(subscriptionId: string): Promise<SubscriptionBundleRecord[]>;
+    /** A single booking (for the cancel/detail flow). */
+    findById(subscriptionBundleId: string): Promise<SubscriptionBundleRecord | null>;
+    /**
+     * Active bookings of a subscription (`canceledAt IS NULL OR
+     * canceledEffectiveAt > NOW()`). Used by the Entitlement path.
+     *
+     * `tx` is set when the call happens inside `enforceLimit`'s interactive
+     * transaction — adapters should then query on the transaction connection
+     * instead of drawing an extra pool connection (starvation guard, #70).
+     */
+    listActiveBySubscription(subscriptionId: string, asOf?: Date, tx?: TransactionContext): Promise<SubscriptionBundleRecord[]>;
+    add(data: CreateSubscriptionBundleData): Promise<SubscriptionBundleRecord>;
+    /**
+     * Sets `canceledAt` + `canceledEffectiveAt`. Throws on already
+     * canceled bookings — the service may offer "undo cancellation"
+     * as a separate path (not in this iteration).
+     */
+    cancel(subscriptionBundleId: string, data: CancelSubscriptionBundleData): Promise<SubscriptionBundleRecord>;
+    /**
+     * "Undo cancellation": resets `canceledAt` + `canceledEffectiveAt` to
+     * NULL. Only meaningful as long as the cancellation is not yet effective
+     * (`canceledEffectiveAt > NOW()`); the validity check is done by the service.
+     */
+    reactivate(subscriptionBundleId: string): Promise<SubscriptionBundleRecord>;
+    /**
+     * Counts active bundle bookings for a BundleVersion (same
+     * semantics as `SubscriptionRepository.countByBundleVersionId`, only
+     * directly on the junction adapter). Shared by both repository
+     * implementations to avoid drift.
+     */
+    countActiveByBundleVersionId(bundleVersionId: string, asOf?: Date): Promise<number>;
+}
+/**
+ * Append-only repository for V3 SubscriptionContracts. Contracts are the
+ * contractually binding source for billing and entitlement; catalog FKs are only
+ * trace data. Implementations may close existing contracts (at the domain level)
+ * only via `terminate`, not overwrite LineItems/Snapshots.
+ */
+interface SubscriptionContractRepository {
+    list(filter: SubscriptionContractFilter): Promise<SubscriptionContractRecord[]>;
+    findById(contractId: string): Promise<SubscriptionContractRecord | null>;
+    /**
+     * `tx` is set when the call happens inside `enforceLimit`'s interactive
+     * transaction — adapters should then query on the transaction connection
+     * instead of drawing an extra pool connection (starvation guard, #70).
+     */
+    findActiveByTenantId(tenantId: string, asOf?: Date, tx?: TransactionContext): Promise<SubscriptionContractRecord | null>;
+    create(data: CreateSubscriptionContractData): Promise<SubscriptionContractRecord>;
+    terminate(contractId: string, data: TerminateSubscriptionContractData): Promise<SubscriptionContractRecord>;
+}
+/**
+ * Display form of a subscription for the tenant self-service UI.
+ * Richer than `SubscriptionRecord` (which is only the aggregation form); contains
+ * additional fields such as `billingCycle`, pilot/trial date and full
+ * plan-version metadata.
+ *
+ * The platform controller `GET /billing/usage` maps this form 1:1 into the
+ * response body. The consumer adapter loads from its own subscription
+ * table (Prisma include planVersion + pendingPlanVersion).
+ */
+interface SubscriptionUsageRecord {
+    /**
+     * Subscription primary key. Optional, because existing adapters may not
+     * yet pass the column through — the platform service uses it
+     * only for downstream steps such as atomic promo-redeem in the
+     * onboarding endpoint. Adapters that want to support `POST /billing/onboarding/initial-subscription`
+     * with a promo code must set `id`.
+     */
+    id?: string;
+    plan: string;
+    billingCycle: string;
+    status: string;
+    isPilot: boolean;
+    pilotEndsAt: Date | null;
+    trialEndsAt: Date | null;
+    /** Subscription start (= period-window anchor for `periodEndAfter`). */
+    startedAt: Date | null;
+    /** Current period window — for proration and change-effective date. */
+    currentPeriodStart: Date | null;
+    currentPeriodEnd: Date | null;
+    pendingPlan: string | null;
+    pendingBillingCycle: string | null;
+    pendingEffectiveAt: Date | null;
+    planVersion: {
+        id: string;
+        planId: string;
+        version: number;
+        publishedAt: Date | null;
+        supersededAt: Date | null;
+        changeNote: string | null;
+    };
+    pendingPlanVersion: {
+        id: string;
+        planId: string;
+        version: number;
+        nonRegressive: boolean;
+        changeNote: string | null;
+        /** Catalog diff form from version-publish; free-form JSON structure. */
+        publishedChanges: unknown;
+    } | null;
+    pendingPlanVersionEffectiveAt: Date | null;
+    pendingPlanVersionAccepted: boolean;
+    pendingPlanVersionAcceptedAt: Date | null;
+    /**
+     * P11.4: frozen package snapshot from the
+     * `CheckoutOffer` that was activated during onboarding. Read-only —
+     * serves only for display in the tenant self-service UI, so that the
+     * tenant knows *which* advertised package was concretely booked.
+     * `null` for subscriptions that did not originate from a CheckoutOffer
+     * (direct creation, migration).
+     */
+    packageSnapshot?: unknown | null;
+    /**
+     * P11.4: reference to the original `CheckoutOffer.id`. Mostly not needed
+     * for the UI (the snapshot is self-contained), but useful for support
+     * tools and audit.
+     */
+    checkoutOfferId?: string | null;
+}
+/**
+ * Read adapter for the UI/display form of a subscription. Used by
+ * `TenantBillingController.getUsage`.
+ */
+interface SubscriptionUsagePort {
+    findForTenant(tenantId: string): Promise<SubscriptionUsageRecord | null>;
+}
+/**
+ * Returns the current usage for all quotaKeys of a tenant declared via
+ * `@DefinesQuota` (e.g. `{ users: 4, members: 850, storageGb: 1.2 }`).
+ * The consumer may use its own counter strategies (Prisma counts,
+ * DMS-service roundtrip, cached storage tracker, …) and must decide
+ * soft-fail behavior itself.
+ *
+ * If a quotaKey is missing from the return object, the platform controller
+ * maps it to `0` — robust display, even if a counter is not (yet) implemented.
+ */
+interface UsageSnapshotPort {
+    snapshot(tenantId: string): Promise<Record<string, number>>;
+}
+/** Input for `changePlanImmediate` with optional period-window reset. */
+interface ImmediatePlanChangeInput {
+    planId: string;
+    cycle: string;
+    /** Reset the period window (pro-rata change). NULL for TRIAL. */
+    periodStart: Date | null;
+    periodEnd: Date | null;
+    /** Target status — for TRIAL the status is not overwritten. */
+    nextStatus: string | null;
+    /**
+     * Trial carry-over (#17): new trial end when changing DURING the trial.
+     * Computed by the platform `changePlan` path from the `TrialProjectionPort`.
+     * `undefined`/`null` → adapter leaves `trialEndsAt` unchanged (no trial
+     * change, or target package without trial). A `Date` is persisted.
+     */
+    trialEndsAt?: Date | null;
+}
+/** Input for `schedulePlanChange` (change at period end). */
+interface ScheduledPlanChangeInput {
+    pendingPlan: string;
+    pendingBillingCycle: string;
+    pendingEffectiveAt: Date;
+}
+/**
+ * Input for `applyOnboardingSelection`. Plan-change fields that the
+ * adapter persists atomically in a single transaction.
+ */
+interface ApplyOnboardingSelectionInput {
+    planId: string;
+    cycle: string;
+    /** For TRIAL → null, otherwise period start from `initialPeriodWindow`. */
+    periodStart: Date | null;
+    periodEnd: Date | null;
+    /** For TRIAL → null, otherwise typically `'ACTIVE'`. */
+    nextStatus: string | null;
+}
+/**
+ * Result of the atomically executed onboarding step. Contains all
+ * effects that the platform service can log / respond with downstream.
+ */
+interface ApplyOnboardingSelectionResult {
+    plan: string;
+    billingCycle: string;
+    subscriptionId: string;
+    /** null if no redeemPromo callback was provided or the callback returned null. */
+    promoRedemption: PromoCodeRedemptionRecord | null;
+}
+/**
+ * Callback signature for promo-code redemption WITHIN the onboarding
+ * transaction. The platform service injects a closure that calls `PromoCodesService.
+ * redeemInTransaction(...)`; the adapter calls it after the
+ * subscription update, so that everything lives in a single DB transaction.
+ */
+type RedeemPromoInTransactionCallback = (tx: TransactionContext, subscriptionId: string) => Promise<PromoCodeRedemptionRecord>;
+/**
+ * Write adapter for tenant self-service mutations
+ * (`POST /billing/plan`, `/billing/cancel` etc.).
+ *
+ * The consumer implementation persists into its subscription table.
+ * Atomicity lies in the adapter, because transaction-client types are
+ * app-specific. The platform service calls `invalidateTenant` in the
+ * EntitlementService after a successful adapter call.
+ */
+interface TenantSubscriptionWritePort {
+    /** Immediate change: set plan + cycle, clear pending fields, optionally reset the period. */
+    changePlanImmediate(tenantId: string, input: ImmediatePlanChangeInput): Promise<{
+        plan: string;
+        billingCycle: string;
+    }>;
+    /** Change at period end: set pending fields. */
+    schedulePlanChange(tenantId: string, input: ScheduledPlanChangeInput): Promise<void>;
+    /**
+     * Marks the pending PlanVersion as accepted. Idempotent — a duplicate
+     * accept is a no-op. Returns `alreadyAccepted: true` if the status was
+     * already set.
+     */
+    acceptPendingPlanVersion(tenantId: string, userId: string, now: Date): Promise<{
+        accepted: boolean;
+        acceptedAt: Date | null;
+        effectiveAt: Date | null;
+        alreadyAccepted: boolean;
+    }>;
+    /**
+     * Cancel the subscription. `immediate=true` → status CANCELED from now;
+     * `false` → canceledAt = currentPeriodEnd, status is preserved.
+     */
+    cancelSubscription(tenantId: string, immediate: boolean, now: Date): Promise<{
+        canceledAt: Date | null;
+        status: string;
+    }>;
+    /**
+     * Atomic onboarding creation: sets plan + cycle + period window
+     * AND optionally calls a promo-redeem callback — all in a
+     * single consumer transaction. Without this method the
+     * platform service falls back to sequential `changePlanImmediate +
+     * promoCodes.redeem` calls (best-effort,
+     * P10.1.1 transitional solution).
+     *
+     * Optional, because existing adapters can add the support
+     * incrementally — a missing implementation is not a hard error.
+     */
+    applyOnboardingSelection?(tenantId: string, input: ApplyOnboardingSelectionInput, redeemPromo: RedeemPromoInTransactionCallback | null): Promise<ApplyOnboardingSelectionResult>;
+}
+/** Read adapter for PlanVersions. */
+interface PlanVersionRepository {
+    /**
+     * Currently published (= live) PlanVersion of a plan:
+     * `publishedAt IS NOT NULL AND supersededAt IS NULL`. Optionally within a
+     * transaction.
+     *
+     * Note: ignores `validFrom`/`validUntil`. For time-aware
+     * resolution (onboarding, plan fallback for TRIAL) use `findActive`.
+     */
+    findLatestLive(planId: string, tx?: TransactionContext): Promise<PlanVersionRecord | null>;
+    /**
+     * PlanVersion of a plan active at `asOf`:
+     *   `publishedAt IS NOT NULL`
+     *   `(validFrom IS NULL OR validFrom <= asOf)`
+     *   `(validUntil IS NULL OR validUntil >= startOfUtcDay(asOf))`
+     *
+     * `validUntil` is day-inclusive. If multiple versions match, adapters
+     * return the highest `validFrom`, explicitly ordering null start dates
+     * last as a legacy fallback. Adapters without validity columns may omit
+     * the method (consumers fall back to `findLatestLive`).
+     */
+    findActive?(planId: string, asOf?: Date, tx?: TransactionContext): Promise<PlanVersionRecord | null>;
+}
+
+/** Aggregate snapshot of subscriptions, orchestrated by `AdminStatsService`. */
+interface SubscriptionStatsSnapshot {
+    /** Sum of all non-soft-deleted subscriptions. */
+    total: number;
+    /** Sum of subscriptions with `isPilot: true`. */
+    pilots: number;
+    /** Sum of subscriptions with `status: 'TRIAL'`. */
+    trialing: number;
+    /** Map planId → count. */
+    byPlan: Record<string, number>;
+    /** Map status → count (ACTIVE / TRIAL / PAST_DUE / CANCELED / PENDING_SALES). */
+    byStatus: Record<string, number>;
+}
+/**
+ * Stats adapter for subscriptions. Consumers implement this based on their
+ * Prisma `subscription.groupBy(...)` / `count(...)` calls.
+ */
+interface SubscriptionStatsPort {
+    getStats(): Promise<SubscriptionStatsSnapshot>;
+}
+/** Top promo-code entry (highest redemption count). */
+interface TopPromoCode {
+    code: string;
+    redemptionsCount: number;
+    status: string;
+}
+/** Aggregate snapshot of promo codes. */
+interface PromoCodeStatsSnapshot {
+    /** Sum of all non-soft-deleted promo codes. */
+    total: number;
+    /** Map status → count (ACTIVE / PAUSED / EXPIRED / EXHAUSTED). */
+    byStatus: Record<string, number>;
+    /** Highest-redemption code; null when no codes exist. */
+    top: TopPromoCode | null;
+}
+/** Stats adapter for promo codes. */
+interface PromoCodeStatsPort {
+    getStats(): Promise<PromoCodeStatsSnapshot>;
+}
+/** Aggregate snapshot of the audit log. */
+interface AuditStatsSnapshot {
+    /** Number of entries in the last N days. */
+    countLastNDays: number;
+    /** Default 7. Configurable via `forRoot.auditWindowDays`. */
+    nDays: number;
+}
+/** Stats adapter for the audit log. */
+interface AuditStatsPort {
+    /** Number of audit events since `since`. */
+    countSince(since: Date): Promise<number>;
+}
+/**
+ * Identifier of an admin actor for the audit log. `source` distinguishes
+ * web UI (`'web'`) and CLI (`'cli'`); `context` is the session ID (web)
+ * or the hostname (CLI).
+ */
+interface AdminActor {
+    userId: string;
+    email: string;
+    source: 'web' | 'cli';
+    context: string;
+}
+/**
+ * Audit adapter: platform services write to the audit log through this
+ * interface. The consumer implementation persists the records (e.g.
+ * Prisma `auditLog.create`, Django `AuditLog.objects.create`).
+ *
+ * `action` is SCREAMING_SNAKE_CASE (see `audit-event.schema.json`).
+ * `changes` is a free-form object; platform services attach the `actor` tag
+ * automatically.
+ */
+interface AuditPort {
+    write(input: {
+        actor: AdminActor;
+        entity: string;
+        entityId: string;
+        action: string;
+        changes?: Record<string, unknown>;
+    }): Promise<void>;
+}
+/**
+ * Read/query adapter for audit logs. Used by the CLI `<app> audit tail` and
+ * UI audit pages. The consumer implementation translates the filter object
+ * (see `audit-event.types.ts.AuditQuery`) into the respective DB query. The
+ * returned records follow `AuditEntry` from the same file.
+ */
+interface AuditQueryPort {
+    list(filter: AuditQuery): Promise<AuditEntry[]>;
+}
+interface AdminTenantListFilter {
+    status?: string;
+    plan?: string;
+    search?: string;
+}
+interface AdminUserListFilter {
+    q?: string;
+    tenant?: string;
+}
+interface AdminAuditListFilter {
+    actor?: string;
+    action?: string;
+    entity?: string;
+    since?: string;
+    limit?: number;
+}
+interface AdminTenantListRow {
+    id: string;
+    slug: string;
+    name: string;
+    isActive: boolean;
+    deletedAt: string | null;
+    plan: string | null;
+    status: string | null;
+    createdAt: string;
+    /** App-selected counters, exposed as ordinary row fields for the UI. */
+    [metric: string]: string | number | boolean | null;
+}
+interface AdminTenantDetail {
+    id: string;
+    slug: string;
+    name: string;
+    isActive: boolean;
+    subscription: {
+        plan: string;
+        status: string;
+        billingCycle: string;
+        isPilot: boolean;
+        trialEndsAt: string | null;
+        pilotEndsAt: string | null;
+    } | null;
+    users: Array<{
+        id: string;
+        email: string;
+        firstName?: string;
+        lastName?: string;
+        createdAt: string;
+    }>;
+    counts: Record<string, number>;
+}
+interface AdminUserListRow {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    role: string;
+    isActive: boolean;
+    tenantSlug: string | null;
+    lastLoginAt: string | null;
+    createdAt: string;
+    /** Apps may add columns without replacing the standard page contract. */
+    [extra: string]: unknown;
+}
+interface AdminSubscriptionListRow {
+    id: string;
+    tenant: {
+        slug: string;
+        name: string;
+    };
+    plan: string;
+    status: string;
+    billingCycle: string;
+    periodEndsAt: string | null;
+    monthlyNet: string | null;
+    /** Apps may add columns without replacing the standard page contract. */
+    [extra: string]: unknown;
+}
+interface AdminTenantStateResult {
+    ok: true;
+    id: string;
+    slug: string;
+    isActive: boolean;
+    status: string | null;
+}
+/**
+ * One narrow backend boundary for the generic Tenant/User/Audit/Subscription
+ * SuperAdmin pages. The canonical Prisma adapter implements it out of the box;
+ * custom schemas replace only this port, while controllers and DTOs stay in
+ * SaaSiCat.
+ */
+interface AdminResourcesPort {
+    listTenants(filter: AdminTenantListFilter): Promise<AdminTenantListRow[]>;
+    getTenantDetail(slug: string): Promise<AdminTenantDetail | null>;
+    setTenantActive(slug: string, active: boolean, subscriptionStatus: string): Promise<AdminTenantStateResult | null>;
+    listUsers(filter: AdminUserListFilter): Promise<AdminUserListRow[]>;
+    listAudit(filter: AdminAuditListFilter): Promise<AuditEntry[]>;
+    listSubscriptions(): Promise<AdminSubscriptionListRow[]>;
+}
+/**
+ * Read adapter for the current AdminManifest. The consumer implementation
+ * delegates to its `AdminManifestService.getManifest()`. The platform CLI
+ * uses this for `<app> manifest dump|hash|check` etc.
+ */
+interface ManifestAccessPort {
+    getManifest(): AdminManifest;
+    /** Optional: forces a rebuild from the contributions (e.g. after code reload). */
+    rebuild?(): AdminManifest;
+}
+/**
+ * Adapter for the RLS bypass context. Platform code calls `runWithBypass`,
+ * the consumer implementation triggers the Postgres session variable
+ * (`set_config('app.bypass_rls', 'true', true)`) or the equivalent in
+ * Django/other stacks. The execution context lives for exactly one
+ * request pipeline (AsyncLocalStorage / `contextvars` etc.).
+ *
+ * SuperAdmin operations are platform-wide without tenant scope — without
+ * bypass, all RLS-protected reads would come back empty.
+ */
+interface RlsBypassPort {
+    runWithBypass<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+/** Filter for `PlanRepository.list()`. */
+interface PlanListFilter {
+    projectKey: string;
+    /** Exclude soft-deleted plans — default `true`. */
+    excludeDeleted?: boolean;
+    /**
+     * Only plans with at least one live version
+     * (`publishedAt` set, `supersededAt` null). Default `false` — plan
+     * management still lists drafts as well. Selection masks (e.g.
+     * pilot setup) set `true` so that no unbookable plans appear.
+     */
+    onlyPublished?: boolean;
+}
+/**
+ * Adapter for `Plan` stem + `PlanVersion` lifecycle persistence
+ *. Consumers implement this against the Prisma
+ * tables `plans` + `plan_versions`.
+ *
+ * Pack 1 (CRUD stem) and Pack 2a (lifecycle) live in one interface,
+ * analogous to `BundleRepository` — but the lifecycle methods are **optional**
+ * (apps without a SuperAdmin editor do not implement them; CatalogModule
+ * then does not register `PlanVersionsService`).
+ *
+ * Binding for lifecycle:
+ * - `createDraft` may only succeed if no other draft version
+ *   exists for the same `planId` (partial unique index in the SQL
+ *   migration).
+ * - `publishDraft` sets `publishedAt = NOW()`, `publishedChanges`,
+ *   `nonRegressive`, `publishedByUserId` on the draft — and supersedes the
+ *   previously live version (same `planId`, `publishedAt IS NOT NULL`,
+ *   `supersededAt IS NULL`) to `supersededAt = NOW()`. Both in one
+ *   transaction.
+ */
+interface PlanRepository {
+    list(filter: PlanListFilter): Promise<PlanRow[]>;
+    findById(planId: string): Promise<PlanRow | null>;
+    findByKey(projectKey: string, planKey: string): Promise<PlanRow | null>;
+    create(data: CreatePlanData): Promise<PlanRow>;
+    update(planId: string, data: UpdatePlanData): Promise<PlanRow>;
+    /** Sets `deletedAt` to NOW(); soft-deleted plans are filtered from `list` by default. */
+    softDelete(planId: string): Promise<void>;
+    /**
+     * Hard-removes the plan stem from the DB (no `deletedAt`, no
+     * recovery path). The service only calls this method after it has
+     * verified that no `PlanVersion` still exists — consumers
+     * may rely on the table being empty. If the
+     * method is not implemented, the service responds with 422
+     * `PLAN_HARD_DELETE_NOT_IMPLEMENTED`.
+     */
+    hardDelete?(planId: string): Promise<void>;
+    /**
+     * Returns all versions of a plan stem (drafts + published +
+     * superseded), sorted by `version` ascending.
+     */
+    listVersions?(planKey: string): Promise<PlanVersionRow[]>;
+    findVersionById?(versionId: string): Promise<PlanVersionRow | null>;
+    findCurrentDraft?(planKey: string): Promise<PlanVersionRow | null>;
+    /**
+     * Currently published (= live) PlanVersion of a plan:
+     * `publishedAt IS NOT NULL AND supersededAt IS NULL`.
+     *
+     * Note: returns the *newest* published version by
+     * `version` number and ignores `validFrom`/`validUntil`. For
+     * time-aware reads (onboarding, marketing catalog, entitlement
+     * fallback) use `findActivePlanVersion(planKey, asOf)`, which returns
+     * the version *active at a point in time*.
+     */
+    findLatestLivePlanVersion?(planKey: string, tx?: TransactionContext): Promise<PlanVersionRow | null>;
+    /**
+     * PlanVersion of a plan active at `asOf` ( extended):
+     *   `publishedAt IS NOT NULL`
+     *   `(validFrom IS NULL OR validFrom <= asOf)`
+     *   `(validUntil IS NULL OR validUntil >= startOfUtcDay(asOf))`  — day-inclusive
+     *
+     * `validFrom IS NULL` is treated like "valid since forever" so that legacy data
+     * without a start date (published before the §4.2 publish requirement) does not
+     * fall out of the catalog. `validUntil` is day-inclusive (calendar day): the version
+     * is valid until the end of its validUntil day, not just until midnight.
+     * Adapters build the WHERE via `buildActivePlanVersionWhere`.
+     *
+     * If multiple match: the one with the highest `validFrom` (= the
+     * "last active"). Adapters must request `NULLS LAST` explicitly so a
+     * null start date remains a genuine fallback. Default `asOf` is the call
+     * time.
+     *
+     * Usage: everything that concerns *new* bookings/plan changes
+     * (onboarding, public marketing, entitlement fallback on TRIAL).
+     * Existing subscriptions stay on their bound `planVersionId`
+     * (P1 contract protection).
+     */
+    findActivePlanVersion?(planKey: string, asOf?: Date, tx?: TransactionContext): Promise<PlanVersionRow | null>;
+    /**
+     * Creates a new draft version (`publishedAt = null`). Throws if
+     * a draft already exists (partial unique index violation).
+     * Computes `version` as `MAX(version) + 1` over all versions of the
+     * `planId`.
+     */
+    createPlanVersionDraft?(data: CreatePlanVersionDraftData): Promise<PlanVersionRow>;
+    updatePlanVersionDraft?(versionId: string, data: UpdatePlanVersionDraftData): Promise<PlanVersionRow>;
+    /**
+     * Publishes a draft version atomically:
+     * 1. Sets `publishedAt = NOW()`, `publishedChanges`, `nonRegressive`,
+     *    `publishedByUserId`, `validFrom` on the draft.
+     * 2. Sets `supersededAt = NOW()` on the previously live version AND
+     *    `validUntil = validFrom - 1 day` (auto-succession).
+     * 3. Sets `validUntil` on the new version (optional, default null = unbounded).
+     */
+    publishPlanVersionDraft?(versionId: string, publishMeta: {
+        publishedByUserId: string | null;
+        publishedChanges: VersionChange[];
+        nonRegressive: boolean;
+        /** Required — validated by the service before the repository call. */
+        validFrom: Date;
+        validUntil: Date | null;
+    }, tx?: TransactionContext): Promise<PlanVersionRow>;
+    /**
+     * Hard-discards a draft version (`publishedAt === null`) from the DB.
+     * Throws if the version was already published — published versions
+     * remain immutable (audit + existing subscriptions
+     * reference them). If the version does not exist, discard is
+     * a no-op (the caller may have already used a different path in parallel).
+     */
+    deletePlanVersionDraft?(versionId: string): Promise<void>;
+    /**
+     * Sets the `endsAt` date chosen by the SuperAdmin on a **published**
+     * PlanVersion (`publishedAt != null && supersededAt == null`). Idempotent —
+     * a second call with a different date overwrites the field.
+     *
+     * Service-side preconditions (live + future date) are checked by the
+     * `PlanVersionsService`; the adapter only persists. If the
+     * method is not implemented, the service responds with 422
+     * `PLAN_TERMINATE_NOT_IMPLEMENTED`.
+     */
+    terminate?(versionId: string, endsAt: Date): Promise<PlanVersionRow>;
+}
+/** Filter for `BundleRepository.list()`. */
+interface BundleListFilter {
+    projectKey: string;
+    /** Exclude soft-deleted bundles — default `true`. */
+    excludeDeleted?: boolean;
+}
+/**
+ * Adapter for `Bundle` + `BundleVersion` persistence. Consumers implement
+ * this against their Prisma tables (`bundles` + `bundle_versions`).
+ *
+ * Binding:
+ * - `createDraft` may only succeed if no other draft version
+ *   exists for the same `bundleId` (partial unique index in the SQL
+ *   migration; see the README in the Prisma fragment).
+ * - `publishDraft` sets `publishedAt = NOW()`, `publishedChanges`,
+ *   `nonRegressive`, `publishedByUserId` — and supersedes the previously live
+ *   version (same `bundleId`, `publishedAt IS NOT NULL`,
+ *   `supersededAt IS NULL`) to `supersededAt = NOW()`.
+ * - Operations that need atomicity may optionally accept a
+ *   `TransactionContext`.
+ */
+interface BundleRepository {
+    list(filter: BundleListFilter): Promise<BundleRow[]>;
+    findById(bundleId: string): Promise<BundleRow | null>;
+    findByKey(projectKey: string, bundleKey: string): Promise<BundleRow | null>;
+    create(data: CreateBundleData): Promise<BundleRow>;
+    update(bundleId: string, data: UpdateBundleData): Promise<BundleRow>;
+    /** Sets `deletedAt` to NOW(); soft-deleted bundles are filtered from `list` by default. */
+    softDelete(bundleId: string): Promise<void>;
+    listVersions(bundleId: string): Promise<BundleVersionRow[]>;
+    /**
+     * `tx` is set when the entitlement path resolves bundle versions inside
+     * `enforceLimit`'s interactive transaction (starvation guard, #70).
+     */
+    findVersionById(versionId: string, tx?: TransactionContext): Promise<BundleVersionRow | null>;
+    findCurrentDraft(bundleId: string): Promise<BundleVersionRow | null>;
+    /**
+     * Currently published (= live) BundleVersion of a bundle:
+     * `publishedAt IS NOT NULL AND supersededAt IS NULL`.
+     *
+     * This deliberately ignores `validFrom`/`validUntil`. For new bookings
+     * and other time-aware catalog reads use `findActiveBundleVersion`.
+     */
+    findLatestLive(bundleId: string, tx?: TransactionContext): Promise<BundleVersionRow | null>;
+    /**
+     * BundleVersion active at `asOf`:
+     *   `publishedAt IS NOT NULL`
+     *   `(validFrom IS NULL OR validFrom <= asOf)`
+     *   `(validUntil IS NULL OR validUntil >= startOfUtcDay(asOf))`
+     *
+     * Both boundaries are inclusive. If multiple versions match, adapters
+     * return the highest `validFrom`, then the highest `version`; a null
+     * `validFrom` is a legacy fallback. Default `asOf` is the call time.
+     *
+     * Optional so adapters backed by legacy schemas without validity columns
+     * can omit the capability and consumers can fall back explicitly.
+     */
+    findActiveBundleVersion?(bundleId: string, asOf?: Date, tx?: TransactionContext): Promise<BundleVersionRow | null>;
+    /**
+     * Creates a new draft version (`publishedAt = null`). Throws if
+     * a draft already exists (partial unique index violation).
+     * Computes `version` as `MAX(version) + 1` over all versions of the
+     * `bundleId`.
+     */
+    createDraft(data: CreateBundleVersionDraftData): Promise<BundleVersionRow>;
+    updateDraft(versionId: string, data: UpdateBundleVersionDraftData): Promise<BundleVersionRow>;
+    /**
+     * Publishes a draft version atomically (
+     * Pack 2c, analogous to `PlanRepository.publishPlanVersionDraft`):
+     * 1. Sets `publishedAt = NOW()`, `publishedChanges`, `nonRegressive`,
+     *    `publishedByUserId`, `validFrom` on the draft.
+     * 2. Sets `supersededAt = NOW()` on the previously live version (if
+     *    present) AND its `validUntil = validFrom - 1 day`
+     *    (auto-succession).
+     * 3. Sets `validUntil` on the new version (optional, default null
+     *    = unbounded).
+     *
+     * All steps run in one transaction (consumers usually pass
+     * through a `TransactionRunner`). Pre-checked on the service side:
+     * `validFrom > previous.validFrom`, gapless constraint
+     * if the predecessor carries a `validUntil` — the adapter only
+     * persists, it does not validate again.
+     */
+    publishDraft(versionId: string, publishMeta: {
+        publishedByUserId: string | null;
+        publishedChanges: VersionChange[];
+        nonRegressive: boolean;
+        /** Required — validated by the service before the repository call. */
+        validFrom: Date;
+        validUntil: Date | null;
+    }, tx?: TransactionContext): Promise<BundleVersionRow>;
+    /**
+     * Hard-discards a draft version (`publishedAt === null`) from the DB.
+     * Throws if the version was already published — published versions
+     * remain immutable (contract protection P1). If the version
+     * does not exist, discard is a no-op (the caller may have already used
+     * a different path in parallel).
+     *
+     * Optional for backwards-compat reasons — if the adapter does not
+     * implement it, the service responds with 422
+     * `BUNDLE_VERSION_DISCARD_NOT_IMPLEMENTED`.
+     */
+    deleteDraft?(versionId: string): Promise<void>;
+}
+/**
+ * Adapter for `marketing_projections`. **No versioning** — per
+ * (`targetType`, `targetVersionId`, `locale`) there is exactly one row
+ * that is edited directly. Marketing edits go live immediately, because they
+ * only control the public catalog display, not existing subscriptions.
+ *
+ * Uniqueness over (`targetType`, `targetVersionId`, `locale`) is
+ * enforced as a unique index in the DB schema — `create` with a conflict throws.
+ */
+interface MarketingProjectionRepository {
+    list(filter: MarketingProjectionFilter): Promise<MarketingProjectionRow[]>;
+    findById(id: string): Promise<MarketingProjectionRow | null>;
+    /**
+     * Finds a projection by the triple
+     * (`targetType`, `targetVersionId`, `locale`).
+     */
+    findByTarget(targetType: string, targetVersionId: string, locale: string): Promise<MarketingProjectionRow | null>;
+    create(data: CreateMarketingProjectionData): Promise<MarketingProjectionRow>;
+    update(id: string, data: UpdateMarketingProjectionData): Promise<MarketingProjectionRow>;
+    /** Hard delete — no soft-delete column (not versioned). */
+    delete(id: string): Promise<void>;
+}
+/** Upsert input for a capability from the discovery sync. */
+interface UpsertCapabilityEntryData {
+    projectKey: string;
+    capabilityKey: string;
+    label: string;
+    description: string | null;
+    featureKey: string | null;
+    bundleKey: string | null;
+    /** Read-only code fact from the snapshot (#20) — the sync always overwrites. */
+    codeStatus: CapabilityCodeStatus;
+    owner: string | null;
+    kind: CapabilityCatalogEntryRow['kind'];
+    replacementKey: string | null;
+    deprecatedAt: string | null;
+    removalPlannedAt: string | null;
+    reason: string | null;
+}
+/** Upsert input for a feature from the discovery sync. */
+interface UpsertFeatureEntryData {
+    projectKey: string;
+    featureKey: string;
+    label: string;
+    description: string | null;
+    discoveryStatus: DiscoveryStatus;
+    /** Code-discovered feature dependencies (#35) — the sync always overwrites. */
+    requires: string[];
+    /** Old feature keys that this feature replaces (#39) — the sync always overwrites. */
+    replaces: string[];
+    /** true = base/always included (not bookable per plan). Deterministic from the registry. */
+    core?: boolean;
+}
+/** Upsert input for a quota from the discovery sync. */
+interface UpsertQuotaEntryData {
+    projectKey: string;
+    quotaKey: string;
+    label: string;
+    description: string | null;
+    unit: string;
+    featureKey: string | null;
+    usageProvider: string | null;
+    enforcementMode: QuotaCatalogEntryRow['enforcementMode'];
+    discoveryStatus: DiscoveryStatus;
+    /** Old quotaKeys that this quota replaces (#39) — the sync always overwrites. */
+    replaces: string[];
+}
+/**
+ * Review update of a feature/quota (`setFeatureReview`/
+ * `setQuotaReview`). The service has already validated the transition and
+ * resolved the approval fields — the adapter persists all four fields 1:1
+ * (`null` clears).
+ */
+interface SetCatalogEntryReviewData {
+    discoveryStatus: DiscoveryStatus;
+    approvedAt: string | null;
+    approvedBy: string | null;
+    approvedSignature: string | null;
+}
+/**
+ * Adapter for `capability_catalog_entries`, `feature_catalog_entries` and
+ * `quota_catalog_entries`. Consumers implement this against their
+ * Prisma tables.
+ *
+ * Binding:
+ * - `upsert*` matches on (`projectKey`, `<key>`) and leaves `i18n`,
+ *   `sortOrder`, `createdAt` as well as the approval fields (`approvedAt`/
+ *   `approvedBy`/`approvedSignature`) **untouched** on an update —
+ *   only the code-derived fields + the status (resolved by the service)
+ *   are written.
+ * - `retireMissing` marks all non-soft-deleted entries whose key
+ *   is not in `presentKeys`: capabilities → `codeStatus = 'retired'`,
+ *   features/quotas → `discoveryStatus = 'obsolete'`. Returns the count.
+ */
+interface CatalogEntryRepository {
+    listCapabilities(filter: CatalogEntryFilter): Promise<CapabilityCatalogEntryRow[]>;
+    listFeatures(filter: CatalogEntryFilter): Promise<FeatureCatalogEntryRow[]>;
+    listQuotas(filter: CatalogEntryFilter): Promise<QuotaCatalogEntryRow[]>;
+    upsertCapability(data: UpsertCapabilityEntryData): Promise<CapabilityCatalogEntryRow>;
+    upsertFeature(data: UpsertFeatureEntryData): Promise<FeatureCatalogEntryRow>;
+    upsertQuota(data: UpsertQuotaEntryData): Promise<QuotaCatalogEntryRow>;
+    retireMissing(projectKey: string, type: 'capability' | 'feature' | 'quota', presentKeys: string[]): Promise<number>;
+    /**
+     * Sets or clears the successor pointer of a feature/quota
+     * (#39). The sync calls this when a key disappears from the snapshot
+     * and another key claims it via `replaces` (`successorKey`
+     * set), or when the key reappears in the code (`null`). Optional —
+     * adapters without a `successor_key` column omit the methods, and the sync
+     * then skips the pointers with a warn log.
+     */
+    setFeatureSuccessor?(projectKey: string, featureKey: string, successorKey: string | null): Promise<FeatureCatalogEntryRow>;
+    setQuotaSuccessor?(projectKey: string, quotaKey: string, successorKey: string | null): Promise<QuotaCatalogEntryRow>;
+    findFeature(projectKey: string, featureKey: string): Promise<FeatureCatalogEntryRow | null>;
+    findQuota(projectKey: string, quotaKey: string): Promise<QuotaCatalogEntryRow | null>;
+    setFeatureReview(projectKey: string, featureKey: string, data: SetCatalogEntryReviewData): Promise<FeatureCatalogEntryRow>;
+    setQuotaReview(projectKey: string, quotaKey: string, data: SetCatalogEntryReviewData): Promise<QuotaCatalogEntryRow>;
+    setFeatureI18n(projectKey: string, featureKey: string, i18n: CatalogEntryI18n): Promise<FeatureCatalogEntryRow>;
+    setQuotaI18n(projectKey: string, quotaKey: string, i18n: CatalogEntryI18n): Promise<QuotaCatalogEntryRow>;
+    /** Sets the editable base fields (default locale `label`/`description`). */
+    setFeatureBase(projectKey: string, featureKey: string, data: UpdateCatalogEntryBaseData): Promise<FeatureCatalogEntryRow>;
+    setQuotaBase(projectKey: string, quotaKey: string, data: UpdateCatalogEntryBaseData): Promise<QuotaCatalogEntryRow>;
+}
+/**
+ * Adapter for `promotions`. **No versioning** — promotions are edited
+ * directly (analogous to MarketingProjectionRepository). Consumers implement
+ * this against their `promotions` Prisma table.
+ */
+interface PromotionRepository {
+    list(filter: PromotionFilter): Promise<PromotionRow[]>;
+    findById(id: string): Promise<PromotionRow | null>;
+    create(data: CreatePromotionData): Promise<PromotionRow>;
+    update(id: string, data: UpdatePromotionData): Promise<PromotionRow>;
+    /** Hard delete — no soft-delete column (not versioned). */
+    delete(id: string): Promise<void>;
+}
+/**
+ * Adapter for `marketing_settings` — one row per project. `get` returns
+ * `null` as long as the SuperAdmin has saved nothing (then the full
+ * `availableLocales` pool counts as active). `upsert` creates the row or replaces it.
+ */
+interface MarketingSettingsRepository {
+    get(projectKey: string): Promise<MarketingSettingsRow | null>;
+    upsert(projectKey: string, data: UpdateMarketingSettingsData): Promise<MarketingSettingsRow>;
+}
+
+/**
+ * Adapter for `checkout_offers`. The offer is an immutable bundle snapshot:
+ * `create` creates it, `update` only allows customization while
+ * `status = 'open'`, `consume` freezes it.
+ */
+interface CheckoutOfferRepository {
+    list(filter: CheckoutOfferFilter): Promise<CheckoutOfferRow[]>;
+    findById(id: string): Promise<CheckoutOfferRow | null>;
+    create(data: CreateCheckoutOfferData): Promise<CheckoutOfferRow>;
+    update(id: string, data: UpdateCheckoutOfferData): Promise<CheckoutOfferRow>;
+    /** Sets `status = 'consumed'` + `consumedAt = NOW()`. */
+    consume(id: string): Promise<CheckoutOfferRow>;
+}
+
+/** Class reference usable as a DI token (e.g. the consumer's `PrismaService`). */
+type PersistenceClassRef = abstract new (...args: never[]) => unknown;
+/** DI token forms a persistence bundle may reference in `inject`. */
+type PersistenceInjectionToken = string | symbol | PersistenceClassRef;
+/**
+ * Framework-free equivalent of the NestJS `ProviderSpec<T>`: either a ready
+ * instance or a `{ useFactory, inject }` factory description. Structurally
+ * assignable to `ProviderSpec<T>` in `@saasicat/nest`, so bundle fields can
+ * be passed to every `*.forRoot()` option unchanged.
+ */
+type PersistenceProvider<T> = T | {
+    useFactory: (...deps: never[]) => T | Promise<T>;
+    inject?: PersistenceInjectionToken[];
+};
+/**
+ * Capabilities a persistence adapter guarantees. The platform fail-fasts at
+ * boot when a required capability is missing, instead of silently degrading
+ * correctness (e.g. quota enforcement without row locks).
+ *
+ * These flags describe the ADAPTER + DATABASE combination, not the abstract
+ * ORM: an adapter may set `pessimisticLocking: false` when it targets a
+ * backend without `SELECT ... FOR UPDATE` semantics.
+ */
+interface PersistenceCapabilities {
+    /**
+     * `TransactionRunner.run` opens a real ACID transaction: throwing inside
+     * the callback rolls back every write performed through the passed
+     * `TransactionContext`.
+     */
+    transactions: boolean;
+    /**
+     * `SubscriptionRepository.findByTenantIdLocked` takes a row lock
+     * (`SELECT ... FOR UPDATE`) that serializes concurrent transactions on
+     * the same tenant. Required for the transactional `enforceLimit()` path.
+     */
+    pessimisticLocking: boolean;
+    /**
+     * The adapter stack integrates with Postgres row-level security (the
+     * `RlsBypassPort` frame actually lifts RLS for SuperAdmin reads).
+     * Informational — RLS policies themselves remain consumer-owned.
+     */
+    rowLevelSecurity: boolean;
+    /** Advisory-lock support (`pg_advisory_*`). No platform path requires it today. */
+    advisoryLocks: boolean;
+}
+/** Always-required slice: admin surface + transactions. */
+interface SaaSiCatPersistenceCore {
+    mfa: PersistenceProvider<MfaPort>;
+    audit: PersistenceProvider<AuditPort>;
+    rlsBypass: PersistenceProvider<RlsBypassPort>;
+    transactionRunner: PersistenceProvider<TransactionRunner>;
+    /** First-run setup wizard (`SetupModule`). */
+    superAdminProvisioning?: PersistenceProvider<SuperAdminProvisioningPort>;
+    /** Read side for `<app> audit tail` and admin audit pages. */
+    auditQuery?: PersistenceProvider<AuditQueryPort>;
+    /** Aggregation for the admin stats dashboard. */
+    auditStats?: PersistenceProvider<AuditStatsPort>;
+}
+/** Repositories for the entitlement/contract loop (`EntitlementModule`). */
+interface SaaSiCatPersistenceEntitlement {
+    subscriptionRepository: PersistenceProvider<SubscriptionRepository>;
+    planVersionRepository: PersistenceProvider<PlanVersionRepository>;
+    subscriptionContractRepository?: PersistenceProvider<SubscriptionContractRepository>;
+    subscriptionBundleRepository?: PersistenceProvider<SubscriptionBundleRepository>;
+    bundleRepository?: PersistenceProvider<BundleRepository>;
+}
+/**
+ * Repositories for the editable catalog plane. A complete adapter can expose
+ * this slice once and let the high-level Nest module wire `CatalogModule` and
+ * `PublicCatalogModule` without consumer-owned forwarding modules.
+ */
+interface SaaSiCatPersistenceCatalog {
+    planRepository: PersistenceProvider<PlanRepository>;
+    bundleRepository: PersistenceProvider<BundleRepository>;
+    catalogEntryRepository?: PersistenceProvider<CatalogEntryRepository>;
+    marketingProjectionRepository?: PersistenceProvider<MarketingProjectionRepository>;
+    promotionRepository?: PersistenceProvider<PromotionRepository>;
+    marketingSettingsRepository?: PersistenceProvider<MarketingSettingsRepository>;
+}
+/**
+ * Standard tenant self-service persistence. `usageSnapshotPort` is optional:
+ * the Nest high-level module derives it from registered `QuotaProvider`s when
+ * the adapter does not provide a more specialized implementation.
+ */
+interface SaaSiCatPersistenceTenantBilling {
+    subscriptionUsagePort: PersistenceProvider<SubscriptionUsagePort>;
+    subscriptionWritePort: PersistenceProvider<TenantSubscriptionWritePort>;
+    usageSnapshotPort?: PersistenceProvider<UsageSnapshotPort>;
+}
+/** Read/write backing for the standard SuperAdmin resource pages. */
+interface SaaSiCatPersistenceAdminResources {
+    resources: PersistenceProvider<AdminResourcesPort>;
+}
+/**
+ * Repositories for `PromoCodesModule.forRoot`. Field names match the module
+ * options so the slice can be spread into the options object. The
+ * app-semantic `firstTimeCustomerCheck` is deliberately NOT part of the
+ * bundle — what counts as an existing customer is a consumer decision.
+ */
+interface SaaSiCatPersistencePromo {
+    promoCodeRepository: PersistenceProvider<PromoCodeRepository>;
+    redemptionRepository: PersistenceProvider<PromoCodeRedemptionRepository>;
+    validationLogRepository: PersistenceProvider<PromoCodeValidationLogRepository>;
+    subscriptionLookup: PersistenceProvider<PromoSubscriptionLookup>;
+    revenueAggregator: PersistenceProvider<PromoRevenueDeductionAggregator>;
+}
+/**
+ * Aggregate persistence bundle. Produced by adapter factories such as
+ * `prismaPersistence({ client })`; consumed by
+ * `SaaSiCatModule.forRoot({ persistence })`. Fine-grained fields can still be
+ * passed to per-domain `forRoot` options for custom compositions.
+ */
+interface SaaSiCatPersistenceAdapter {
+    capabilities: PersistenceCapabilities;
+    core: SaaSiCatPersistenceCore;
+    entitlement?: SaaSiCatPersistenceEntitlement;
+    /** Editable plans, bundles, discovery review and marketing data. */
+    catalog?: SaaSiCatPersistenceCatalog;
+    /** Tenant subscription read/write adapters for the self-service API. */
+    tenantBilling?: SaaSiCatPersistenceTenantBilling;
+    /** Tenant, user, audit and subscription resources for the SuperAdmin UI. */
+    adminResources?: SaaSiCatPersistenceAdminResources;
+    promo?: SaaSiCatPersistencePromo;
+    /** DB hydration of the plan catalog at boot (`PlanCatalogModule`). */
+    planCatalogReadSink?: PersistenceProvider<PlanCatalogReadSink>;
+    /** One-shot `saas.yaml → DB` import. */
+    planCatalogImportSink?: PersistenceProvider<PlanCatalogImportSink>;
+}
+/** Options for capability assertions raised by platform modules at boot. */
+interface RequiredCapabilities {
+    transactions?: boolean;
+    pessimisticLocking?: boolean;
+    rowLevelSecurity?: boolean;
+    advisoryLocks?: boolean;
+}
+/**
+ * Thrown when a persistence adapter does not provide a capability the
+ * enabled platform feature set requires. Framework-free so both nest and
+ * CLI surfaces can map it.
+ */
+declare class PersistenceCapabilityError extends Error {
+    readonly missing: Array<keyof PersistenceCapabilities>;
+    readonly requiredBy: string;
+    readonly code = "PERSISTENCE_CAPABILITY_MISSING";
+    constructor(missing: Array<keyof PersistenceCapabilities>, requiredBy: string);
+}
+/**
+ * Validates declared capabilities against a feature's requirements. Throws
+ * `PersistenceCapabilityError` listing every missing capability.
+ */
+declare function assertPersistenceCapabilities(capabilities: PersistenceCapabilities, required: RequiredCapabilities, requiredBy: string): void;
+
+/** Codes of the first-run setup endpoints (`SetupController`). */
+declare const SETUP_ERROR_CODES: {
+    /** `SETUP_TOKEN` env not set → setup disabled. */
+    readonly SETUP_DISABLED: "SETUP_DISABLED";
+    /** Provided token does not match. */
+    readonly INVALID_SETUP_TOKEN: "INVALID_SETUP_TOKEN";
+    /** A SUPER_ADMIN already exists — self-disable. */
+    readonly SETUP_ALREADY_DONE: "SETUP_ALREADY_DONE";
+    /** Invalid email in the request. */
+    readonly INVALID_EMAIL: "INVALID_EMAIL";
+    /** Email already taken (mapped from `PlatformUserExistsError`). */
+    readonly EMAIL_EXISTS: "EMAIL_EXISTS";
+};
+type SetupErrorCode = (typeof SETUP_ERROR_CODES)[keyof typeof SETUP_ERROR_CODES];
+/** Plan and bundle lifecycle in the admin catalogue. */
+declare const CATALOG_ERROR_CODES: {
+    readonly PLAN_HAS_DRAFTS: "PLAN_HAS_DRAFTS";
+    readonly PLAN_HAS_PUBLISHED_VERSIONS: "PLAN_HAS_PUBLISHED_VERSIONS";
+    readonly PLAN_HARD_DELETE_NOT_IMPLEMENTED: "PLAN_HARD_DELETE_NOT_IMPLEMENTED";
+    readonly PLAN_VERSION_ALREADY_PUBLISHED: "PLAN_VERSION_ALREADY_PUBLISHED";
+    readonly PLAN_VERSION_NOT_EDITABLE: "PLAN_VERSION_NOT_EDITABLE";
+    readonly PLAN_VERSION_REGRESSION: "PLAN_VERSION_REGRESSION";
+    readonly PLAN_VERSION_ZERO_PRICE: "PLAN_VERSION_ZERO_PRICE";
+    readonly PLAN_VERSION_DISCARD_NOT_IMPLEMENTED: "PLAN_VERSION_DISCARD_NOT_IMPLEMENTED";
+    /** Version was never published, so it cannot be terminated. */
+    readonly PLAN_VERSION_NOT_PUBLISHED: "PLAN_VERSION_NOT_PUBLISHED";
+    /** Version was replaced by a successor (`supersededAt` set). */
+    readonly PLAN_VERSION_SUPERSEDED: "PLAN_VERSION_SUPERSEDED";
+    readonly PLAN_VERSION_VALID_FROM_REQUIRED: "PLAN_VERSION_VALID_FROM_REQUIRED";
+    readonly PLAN_VERSION_VALID_FROM_INVALID: "PLAN_VERSION_VALID_FROM_INVALID";
+    readonly PLAN_VERSION_VALID_FROM_NOT_AFTER_PREVIOUS: "PLAN_VERSION_VALID_FROM_NOT_AFTER_PREVIOUS";
+    readonly PLAN_VERSION_VALID_FROM_NOT_GAPLESS: "PLAN_VERSION_VALID_FROM_NOT_GAPLESS";
+    readonly PLAN_VERSION_VALID_UNTIL_INVALID: "PLAN_VERSION_VALID_UNTIL_INVALID";
+    readonly PLAN_VERSION_VALID_UNTIL_BEFORE_FROM: "PLAN_VERSION_VALID_UNTIL_BEFORE_FROM";
+    readonly PLAN_TERMINATE_INVALID_DATE: "PLAN_TERMINATE_INVALID_DATE";
+    readonly PLAN_TERMINATE_DATE_NOT_FUTURE: "PLAN_TERMINATE_DATE_NOT_FUTURE";
+    readonly PLAN_TERMINATE_NOT_IMPLEMENTED: "PLAN_TERMINATE_NOT_IMPLEMENTED";
+    readonly BUNDLE_VERSION_ALREADY_PUBLISHED: "BUNDLE_VERSION_ALREADY_PUBLISHED";
+    readonly BUNDLE_VERSION_NOT_EDITABLE: "BUNDLE_VERSION_NOT_EDITABLE";
+    readonly BUNDLE_VERSION_NOT_PUBLISHED: "BUNDLE_VERSION_NOT_PUBLISHED";
+    readonly BUNDLE_VERSION_SUPERSEDED: "BUNDLE_VERSION_SUPERSEDED";
+    readonly BUNDLE_VERSION_REGRESSION: "BUNDLE_VERSION_REGRESSION";
+    readonly BUNDLE_VERSION_ZERO_PRICE: "BUNDLE_VERSION_ZERO_PRICE";
+    readonly BUNDLE_VERSION_DISCARD_NOT_IMPLEMENTED: "BUNDLE_VERSION_DISCARD_NOT_IMPLEMENTED";
+    readonly BUNDLE_VERSION_VALID_FROM_REQUIRED: "BUNDLE_VERSION_VALID_FROM_REQUIRED";
+    readonly BUNDLE_VERSION_VALID_FROM_INVALID: "BUNDLE_VERSION_VALID_FROM_INVALID";
+    readonly BUNDLE_VERSION_VALID_FROM_NOT_AFTER_PREVIOUS: "BUNDLE_VERSION_VALID_FROM_NOT_AFTER_PREVIOUS";
+    readonly BUNDLE_VERSION_VALID_FROM_NOT_GAPLESS: "BUNDLE_VERSION_VALID_FROM_NOT_GAPLESS";
+    readonly BUNDLE_VERSION_VALID_FROM_NOT_FUTURE: "BUNDLE_VERSION_VALID_FROM_NOT_FUTURE";
+    readonly BUNDLE_VERSION_VALID_UNTIL_INVALID: "BUNDLE_VERSION_VALID_UNTIL_INVALID";
+    readonly BUNDLE_VERSION_VALID_UNTIL_BEFORE_FROM: "BUNDLE_VERSION_VALID_UNTIL_BEFORE_FROM";
+    /** Publish blocked by strict mode. Carries `warnings[]` with own codes. */
+    readonly STRICT_MODE_VIOLATIONS: "STRICT_MODE_VIOLATIONS";
+    readonly PLAN_NOT_FOUND: "PLAN_NOT_FOUND";
+    readonly PLAN_VERSION_NOT_FOUND: "PLAN_VERSION_NOT_FOUND";
+    readonly BUNDLE_NOT_FOUND: "BUNDLE_NOT_FOUND";
+    readonly BUNDLE_VERSION_NOT_FOUND: "BUNDLE_VERSION_NOT_FOUND";
+    readonly FEATURE_NOT_FOUND: "FEATURE_NOT_FOUND";
+    readonly QUOTA_NOT_FOUND: "QUOTA_NOT_FOUND";
+    readonly PROMOTION_NOT_FOUND: "PROMOTION_NOT_FOUND";
+    readonly MARKETING_PROJECTION_NOT_FOUND: "MARKETING_PROJECTION_NOT_FOUND";
+    readonly PLAN_ALREADY_EXISTS: "PLAN_ALREADY_EXISTS";
+    readonly BUNDLE_ALREADY_EXISTS: "BUNDLE_ALREADY_EXISTS";
+    readonly MARKETING_PROJECTION_ALREADY_EXISTS: "MARKETING_PROJECTION_ALREADY_EXISTS";
+    /** A draft already exists — publish or discard it before creating another. */
+    readonly PLAN_DRAFT_ALREADY_EXISTS: "PLAN_DRAFT_ALREADY_EXISTS";
+    readonly BUNDLE_DRAFT_ALREADY_EXISTS: "BUNDLE_DRAFT_ALREADY_EXISTS";
+    readonly QUOTA_NOT_IN_DISCOVERY_SNAPSHOT: "QUOTA_NOT_IN_DISCOVERY_SNAPSHOT";
+    readonly DISCOVERY_STATUS_TRANSITION_INVALID: "DISCOVERY_STATUS_TRANSITION_INVALID";
+    readonly DISCOVERY_NOT_INITIALIZED: "DISCOVERY_NOT_INITIALIZED";
+};
+type CatalogErrorCode = (typeof CATALOG_ERROR_CODES)[keyof typeof CATALOG_ERROR_CODES];
+/** Bundle bookings on a tenant subscription. */
+declare const BILLING_ERROR_CODES: {
+    /**
+     * Feature not covered by the plan. Defined in `upsell.types.ts` because the
+     * upsell body type is built around it; re-exported here so an exhaustive
+     * `PlatformErrorCode` switch covers it.
+     */
+    readonly FEATURE_NOT_LICENSED: "FEATURE_NOT_LICENSED";
+    readonly BUNDLE_ALREADY_SUBSCRIBED: "BUNDLE_ALREADY_SUBSCRIBED";
+    readonly BUNDLE_INCOMPATIBLE_WITH_PLAN: "BUNDLE_INCOMPATIBLE_WITH_PLAN";
+    readonly BUNDLE_NOT_SELF_SERVICE: "BUNDLE_NOT_SELF_SERVICE";
+    readonly SUBSCRIPTION_BUNDLE_ALREADY_CANCELLED: "SUBSCRIPTION_BUNDLE_ALREADY_CANCELLED";
+    readonly SUBSCRIPTION_BUNDLE_NOT_CANCELLED: "SUBSCRIPTION_BUNDLE_NOT_CANCELLED";
+    readonly SUBSCRIPTION_BUNDLE_CANCELLATION_EFFECTIVE: "SUBSCRIPTION_BUNDLE_CANCELLATION_EFFECTIVE";
+    readonly SUBSCRIPTION_NOT_FOUND: "SUBSCRIPTION_NOT_FOUND";
+    readonly SUBSCRIPTION_TENANT_MISMATCH: "SUBSCRIPTION_TENANT_MISMATCH";
+    readonly SUBSCRIPTION_BUNDLE_NOT_FOUND: "SUBSCRIPTION_BUNDLE_NOT_FOUND";
+    readonly TENANT_NOT_FOUND: "TENANT_NOT_FOUND";
+    /** No plan version is active as of the requested date. */
+    readonly NO_ACTIVE_PLAN_VERSION: "NO_ACTIVE_PLAN_VERSION";
+    /** Plan is unknown to the loaded plan catalogue. */
+    readonly PLAN_NOT_IN_CATALOG: "PLAN_NOT_IN_CATALOG";
+    /** Plan exists but cannot be booked via self-service. */
+    readonly PLAN_NOT_SELF_SERVICE: "PLAN_NOT_SELF_SERVICE";
+    /** Plan change refused. Carries `blockers[]` with their own codes. */
+    readonly PLAN_CHANGE_BLOCKED: "PLAN_CHANGE_BLOCKED";
+    readonly NO_PENDING_PLAN_VERSION: "NO_PENDING_PLAN_VERSION";
+    readonly ONBOARDING_CREATE_FAILED: "ONBOARDING_CREATE_FAILED";
+    readonly BUNDLE_PREVIEW_ARGUMENT_AMBIGUOUS: "BUNDLE_PREVIEW_ARGUMENT_AMBIGUOUS";
+    /**
+     * The adapter returned a `SubscriptionUsageRecord` without `id`. A wiring
+     * error in the consumer, not a missing subscription — hence its own code.
+     */
+    readonly SUBSCRIPTION_PK_MISSING: "SUBSCRIPTION_PK_MISSING";
+    /** Quota exhausted. Carries `dimension`, `used`, `max`. */
+    readonly LIMIT_EXCEEDED: "LIMIT_EXCEEDED";
+    readonly QUOTA_DIMENSION_UNKNOWN: "QUOTA_DIMENSION_UNKNOWN";
+};
+type BillingErrorCode = (typeof BILLING_ERROR_CODES)[keyof typeof BILLING_ERROR_CODES];
+/** Checkout offers and the subscription contracts derived from them. */
+declare const CONTRACT_ERROR_CODES: {
+    readonly CHECKOUT_OFFER_LINE_ITEMS_REQUIRED: "CHECKOUT_OFFER_LINE_ITEMS_REQUIRED";
+    readonly CHECKOUT_OFFER_PLAN_LINE_ITEM_REQUIRED: "CHECKOUT_OFFER_PLAN_LINE_ITEM_REQUIRED";
+    readonly CHECKOUT_OFFER_BUNDLE_LINE_ITEMS_REQUIRED: "CHECKOUT_OFFER_BUNDLE_LINE_ITEMS_REQUIRED";
+    readonly CHECKOUT_OFFER_BUNDLE_VERSION_NOT_BOOKABLE: "CHECKOUT_OFFER_BUNDLE_VERSION_NOT_BOOKABLE";
+    readonly CHECKOUT_OFFER_FEATURE_DEPENDENCY_UNSATISFIED: "CHECKOUT_OFFER_FEATURE_DEPENDENCY_UNSATISFIED";
+    readonly SUBSCRIPTION_CONTRACT_LINE_ITEMS_REQUIRED: "SUBSCRIPTION_CONTRACT_LINE_ITEMS_REQUIRED";
+    readonly SUBSCRIPTION_CONTRACT_PLAN_LINE_ITEM_REQUIRED: "SUBSCRIPTION_CONTRACT_PLAN_LINE_ITEM_REQUIRED";
+    readonly SUBSCRIPTION_CONTRACT_INVALID_DATE: "SUBSCRIPTION_CONTRACT_INVALID_DATE";
+    readonly SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "SUBSCRIPTION_CONTRACT_INVALID_WINDOW";
+    readonly SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START";
+    readonly CHECKOUT_OFFER_NOT_FOUND: "CHECKOUT_OFFER_NOT_FOUND";
+    readonly CHECKOUT_OFFER_EXPIRED: "CHECKOUT_OFFER_EXPIRED";
+    readonly CHECKOUT_OFFER_ALREADY_CONSUMED: "CHECKOUT_OFFER_ALREADY_CONSUMED";
+    readonly CHECKOUT_OFFER_NOT_CONSUMED: "CHECKOUT_OFFER_NOT_CONSUMED";
+    readonly SUBSCRIPTION_CONTRACT_NOT_FOUND: "SUBSCRIPTION_CONTRACT_NOT_FOUND";
+    readonly NO_ACTIVE_SUBSCRIPTION_CONTRACT: "NO_ACTIVE_SUBSCRIPTION_CONTRACT";
+    readonly SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SUBSCRIPTION_CONTRACT_ALREADY_CLOSED";
+};
+type ContractErrorCode = (typeof CONTRACT_ERROR_CODES)[keyof typeof CONTRACT_ERROR_CODES];
+/** Self-service registration funnel (`PendingRegistration`). */
+declare const REGISTRATION_ERROR_CODES: {
+    readonly PENDING_REGISTRATION_NOT_FOUND: "PENDING_REGISTRATION_NOT_FOUND";
+    readonly PENDING_REGISTRATION_EXPIRED: "PENDING_REGISTRATION_EXPIRED";
+    readonly INVALID_REGISTRATION_STATE: "INVALID_REGISTRATION_STATE";
+    readonly OTP_INVALID: "OTP_INVALID";
+    readonly OTP_EXPIRED: "OTP_EXPIRED";
+    readonly OTP_LOCKED: "OTP_LOCKED";
+    /** Too many attempts from this origin. Carries `retryAfterSeconds`. */
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly RESUME_TOKEN_INVALID: "RESUME_TOKEN_INVALID";
+    readonly RESUME_NOT_CONFIGURED: "RESUME_NOT_CONFIGURED";
+    readonly CONFIGURATOR_NOT_CONFIGURED: "CONFIGURATOR_NOT_CONFIGURED";
+    readonly CONFIG_NOT_SAVED: "CONFIG_NOT_SAVED";
+    readonly PLAN_NOT_AVAILABLE: "PLAN_NOT_AVAILABLE";
+    readonly PLAN_NOT_SELECTED: "PLAN_NOT_SELECTED";
+    readonly MODEL_NOT_AVAILABLE: "MODEL_NOT_AVAILABLE";
+};
+type RegistrationErrorCode = (typeof REGISTRATION_ERROR_CODES)[keyof typeof REGISTRATION_ERROR_CODES];
+/** Authentication, role and tenant-context failures raised by the guards. */
+declare const AUTH_ERROR_CODES: {
+    /** No authenticated user on the request. */
+    readonly NOT_AUTHENTICATED: "NOT_AUTHENTICATED";
+    /** Authenticated, but the request carries no tenant. */
+    readonly NO_TENANT_ASSIGNED: "NO_TENANT_ASSIGNED";
+    /** Neither `tenantId` nor `userId` could be resolved from the request. */
+    readonly TENANT_CONTEXT_MISSING: "TENANT_CONTEXT_MISSING";
+    readonly TENANT_ADMIN_REQUIRED: "TENANT_ADMIN_REQUIRED";
+    readonly SUPER_ADMIN_REQUIRED: "SUPER_ADMIN_REQUIRED";
+    /** TOTP MFA has never been set up for this user. */
+    readonly MFA_NOT_SET_UP: "MFA_NOT_SET_UP";
+    /** Endpoint is MFA-gated and no `X-Mfa-Code` header was sent. */
+    readonly MFA_REQUIRED: "MFA_REQUIRED";
+    /** The supplied TOTP code did not verify. */
+    readonly MFA_FAILED: "MFA_FAILED";
+    /** Module misconfiguration, not an end-user condition. */
+    readonly AUTH_GUARDS_NOT_CONFIGURED: "AUTH_GUARDS_NOT_CONFIGURED";
+};
+type AuthErrorCode = (typeof AUTH_ERROR_CODES)[keyof typeof AUTH_ERROR_CODES];
+/** Promo-code administration and redemption. */
+declare const PROMO_ERROR_CODES: {
+    readonly PROMO_CODE_NOT_FOUND: "PROMO_CODE_NOT_FOUND";
+    readonly PROMO_CODE_ALREADY_EXISTS: "PROMO_CODE_ALREADY_EXISTS";
+    readonly PROMO_CODE_HAS_REDEMPTIONS: "PROMO_CODE_HAS_REDEMPTIONS";
+    /** Not redeemable. Carries `reason` (`PromoPreviewInvalidReason`). */
+    readonly PROMO_CODE_NOT_REDEEMABLE: "PROMO_CODE_NOT_REDEEMABLE";
+    readonly PROMO_CODE_FORMAT_INVALID: "PROMO_CODE_FORMAT_INVALID";
+    readonly PROMO_PERCENT_OUT_OF_RANGE: "PROMO_PERCENT_OUT_OF_RANGE";
+    readonly PROMO_AMOUNT_NOT_POSITIVE: "PROMO_AMOUNT_NOT_POSITIVE";
+    readonly PROMO_ONE_OFF_WITH_DURATION: "PROMO_ONE_OFF_WITH_DURATION";
+    readonly PROMO_DURATION_INVALID: "PROMO_DURATION_INVALID";
+    readonly PROMO_VALIDITY_WINDOW_INVALID: "PROMO_VALIDITY_WINDOW_INVALID";
+    readonly PROMO_PLAN_NOT_DISCOUNTABLE: "PROMO_PLAN_NOT_DISCOUNTABLE";
+    readonly PROMO_MIN_AMOUNT_NOT_POSITIVE: "PROMO_MIN_AMOUNT_NOT_POSITIVE";
+    readonly PROMO_WOULD_PRODUCE_ZERO_INVOICE: "PROMO_WOULD_PRODUCE_ZERO_INVOICE";
+    readonly PROMO_MAX_REDEMPTIONS_LOWERED: "PROMO_MAX_REDEMPTIONS_LOWERED";
+};
+type PromoErrorCode = (typeof PROMO_ERROR_CODES)[keyof typeof PROMO_ERROR_CODES];
+/**
+ * Every exception code the platform emits, in one object.
+ *
+ * Group membership is presentational — the wire format is the bare string, so
+ * a code may be moved between groups without breaking consumers. Renaming or
+ * removing one may not.
+ */
+declare const PLATFORM_ERROR_CODES: {
+    readonly PENDING_REGISTRATION_NOT_FOUND: "PENDING_REGISTRATION_NOT_FOUND";
+    readonly PENDING_REGISTRATION_EXPIRED: "PENDING_REGISTRATION_EXPIRED";
+    readonly INVALID_REGISTRATION_STATE: "INVALID_REGISTRATION_STATE";
+    readonly OTP_INVALID: "OTP_INVALID";
+    readonly OTP_EXPIRED: "OTP_EXPIRED";
+    readonly OTP_LOCKED: "OTP_LOCKED";
+    /** Too many attempts from this origin. Carries `retryAfterSeconds`. */
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly RESUME_TOKEN_INVALID: "RESUME_TOKEN_INVALID";
+    readonly RESUME_NOT_CONFIGURED: "RESUME_NOT_CONFIGURED";
+    readonly CONFIGURATOR_NOT_CONFIGURED: "CONFIGURATOR_NOT_CONFIGURED";
+    readonly CONFIG_NOT_SAVED: "CONFIG_NOT_SAVED";
+    readonly PLAN_NOT_AVAILABLE: "PLAN_NOT_AVAILABLE";
+    readonly PLAN_NOT_SELECTED: "PLAN_NOT_SELECTED";
+    readonly MODEL_NOT_AVAILABLE: "MODEL_NOT_AVAILABLE";
+    readonly CHECKOUT_OFFER_LINE_ITEMS_REQUIRED: "CHECKOUT_OFFER_LINE_ITEMS_REQUIRED";
+    readonly CHECKOUT_OFFER_PLAN_LINE_ITEM_REQUIRED: "CHECKOUT_OFFER_PLAN_LINE_ITEM_REQUIRED";
+    readonly CHECKOUT_OFFER_BUNDLE_LINE_ITEMS_REQUIRED: "CHECKOUT_OFFER_BUNDLE_LINE_ITEMS_REQUIRED";
+    readonly CHECKOUT_OFFER_BUNDLE_VERSION_NOT_BOOKABLE: "CHECKOUT_OFFER_BUNDLE_VERSION_NOT_BOOKABLE";
+    readonly CHECKOUT_OFFER_FEATURE_DEPENDENCY_UNSATISFIED: "CHECKOUT_OFFER_FEATURE_DEPENDENCY_UNSATISFIED";
+    readonly SUBSCRIPTION_CONTRACT_LINE_ITEMS_REQUIRED: "SUBSCRIPTION_CONTRACT_LINE_ITEMS_REQUIRED";
+    readonly SUBSCRIPTION_CONTRACT_PLAN_LINE_ITEM_REQUIRED: "SUBSCRIPTION_CONTRACT_PLAN_LINE_ITEM_REQUIRED";
+    readonly SUBSCRIPTION_CONTRACT_INVALID_DATE: "SUBSCRIPTION_CONTRACT_INVALID_DATE";
+    readonly SUBSCRIPTION_CONTRACT_INVALID_WINDOW: "SUBSCRIPTION_CONTRACT_INVALID_WINDOW";
+    readonly SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START: "SUBSCRIPTION_CONTRACT_TERMINATION_BEFORE_START";
+    readonly CHECKOUT_OFFER_NOT_FOUND: "CHECKOUT_OFFER_NOT_FOUND";
+    readonly CHECKOUT_OFFER_EXPIRED: "CHECKOUT_OFFER_EXPIRED";
+    readonly CHECKOUT_OFFER_ALREADY_CONSUMED: "CHECKOUT_OFFER_ALREADY_CONSUMED";
+    readonly CHECKOUT_OFFER_NOT_CONSUMED: "CHECKOUT_OFFER_NOT_CONSUMED";
+    readonly SUBSCRIPTION_CONTRACT_NOT_FOUND: "SUBSCRIPTION_CONTRACT_NOT_FOUND";
+    readonly NO_ACTIVE_SUBSCRIPTION_CONTRACT: "NO_ACTIVE_SUBSCRIPTION_CONTRACT";
+    readonly SUBSCRIPTION_CONTRACT_ALREADY_CLOSED: "SUBSCRIPTION_CONTRACT_ALREADY_CLOSED";
+    /**
+     * Feature not covered by the plan. Defined in `upsell.types.ts` because the
+     * upsell body type is built around it; re-exported here so an exhaustive
+     * `PlatformErrorCode` switch covers it.
+     */
+    readonly FEATURE_NOT_LICENSED: "FEATURE_NOT_LICENSED";
+    readonly BUNDLE_ALREADY_SUBSCRIBED: "BUNDLE_ALREADY_SUBSCRIBED";
+    readonly BUNDLE_INCOMPATIBLE_WITH_PLAN: "BUNDLE_INCOMPATIBLE_WITH_PLAN";
+    readonly BUNDLE_NOT_SELF_SERVICE: "BUNDLE_NOT_SELF_SERVICE";
+    readonly SUBSCRIPTION_BUNDLE_ALREADY_CANCELLED: "SUBSCRIPTION_BUNDLE_ALREADY_CANCELLED";
+    readonly SUBSCRIPTION_BUNDLE_NOT_CANCELLED: "SUBSCRIPTION_BUNDLE_NOT_CANCELLED";
+    readonly SUBSCRIPTION_BUNDLE_CANCELLATION_EFFECTIVE: "SUBSCRIPTION_BUNDLE_CANCELLATION_EFFECTIVE";
+    readonly SUBSCRIPTION_NOT_FOUND: "SUBSCRIPTION_NOT_FOUND";
+    readonly SUBSCRIPTION_TENANT_MISMATCH: "SUBSCRIPTION_TENANT_MISMATCH";
+    readonly SUBSCRIPTION_BUNDLE_NOT_FOUND: "SUBSCRIPTION_BUNDLE_NOT_FOUND";
+    readonly TENANT_NOT_FOUND: "TENANT_NOT_FOUND";
+    /** No plan version is active as of the requested date. */
+    readonly NO_ACTIVE_PLAN_VERSION: "NO_ACTIVE_PLAN_VERSION";
+    /** Plan is unknown to the loaded plan catalogue. */
+    readonly PLAN_NOT_IN_CATALOG: "PLAN_NOT_IN_CATALOG";
+    /** Plan exists but cannot be booked via self-service. */
+    readonly PLAN_NOT_SELF_SERVICE: "PLAN_NOT_SELF_SERVICE";
+    /** Plan change refused. Carries `blockers[]` with their own codes. */
+    readonly PLAN_CHANGE_BLOCKED: "PLAN_CHANGE_BLOCKED";
+    readonly NO_PENDING_PLAN_VERSION: "NO_PENDING_PLAN_VERSION";
+    readonly ONBOARDING_CREATE_FAILED: "ONBOARDING_CREATE_FAILED";
+    readonly BUNDLE_PREVIEW_ARGUMENT_AMBIGUOUS: "BUNDLE_PREVIEW_ARGUMENT_AMBIGUOUS";
+    /**
+     * The adapter returned a `SubscriptionUsageRecord` without `id`. A wiring
+     * error in the consumer, not a missing subscription — hence its own code.
+     */
+    readonly SUBSCRIPTION_PK_MISSING: "SUBSCRIPTION_PK_MISSING";
+    /** Quota exhausted. Carries `dimension`, `used`, `max`. */
+    readonly LIMIT_EXCEEDED: "LIMIT_EXCEEDED";
+    readonly QUOTA_DIMENSION_UNKNOWN: "QUOTA_DIMENSION_UNKNOWN";
+    readonly PLAN_HAS_DRAFTS: "PLAN_HAS_DRAFTS";
+    readonly PLAN_HAS_PUBLISHED_VERSIONS: "PLAN_HAS_PUBLISHED_VERSIONS";
+    readonly PLAN_HARD_DELETE_NOT_IMPLEMENTED: "PLAN_HARD_DELETE_NOT_IMPLEMENTED";
+    readonly PLAN_VERSION_ALREADY_PUBLISHED: "PLAN_VERSION_ALREADY_PUBLISHED";
+    readonly PLAN_VERSION_NOT_EDITABLE: "PLAN_VERSION_NOT_EDITABLE";
+    readonly PLAN_VERSION_REGRESSION: "PLAN_VERSION_REGRESSION";
+    readonly PLAN_VERSION_ZERO_PRICE: "PLAN_VERSION_ZERO_PRICE";
+    readonly PLAN_VERSION_DISCARD_NOT_IMPLEMENTED: "PLAN_VERSION_DISCARD_NOT_IMPLEMENTED";
+    /** Version was never published, so it cannot be terminated. */
+    readonly PLAN_VERSION_NOT_PUBLISHED: "PLAN_VERSION_NOT_PUBLISHED";
+    /** Version was replaced by a successor (`supersededAt` set). */
+    readonly PLAN_VERSION_SUPERSEDED: "PLAN_VERSION_SUPERSEDED";
+    readonly PLAN_VERSION_VALID_FROM_REQUIRED: "PLAN_VERSION_VALID_FROM_REQUIRED";
+    readonly PLAN_VERSION_VALID_FROM_INVALID: "PLAN_VERSION_VALID_FROM_INVALID";
+    readonly PLAN_VERSION_VALID_FROM_NOT_AFTER_PREVIOUS: "PLAN_VERSION_VALID_FROM_NOT_AFTER_PREVIOUS";
+    readonly PLAN_VERSION_VALID_FROM_NOT_GAPLESS: "PLAN_VERSION_VALID_FROM_NOT_GAPLESS";
+    readonly PLAN_VERSION_VALID_UNTIL_INVALID: "PLAN_VERSION_VALID_UNTIL_INVALID";
+    readonly PLAN_VERSION_VALID_UNTIL_BEFORE_FROM: "PLAN_VERSION_VALID_UNTIL_BEFORE_FROM";
+    readonly PLAN_TERMINATE_INVALID_DATE: "PLAN_TERMINATE_INVALID_DATE";
+    readonly PLAN_TERMINATE_DATE_NOT_FUTURE: "PLAN_TERMINATE_DATE_NOT_FUTURE";
+    readonly PLAN_TERMINATE_NOT_IMPLEMENTED: "PLAN_TERMINATE_NOT_IMPLEMENTED";
+    readonly BUNDLE_VERSION_ALREADY_PUBLISHED: "BUNDLE_VERSION_ALREADY_PUBLISHED";
+    readonly BUNDLE_VERSION_NOT_EDITABLE: "BUNDLE_VERSION_NOT_EDITABLE";
+    readonly BUNDLE_VERSION_NOT_PUBLISHED: "BUNDLE_VERSION_NOT_PUBLISHED";
+    readonly BUNDLE_VERSION_SUPERSEDED: "BUNDLE_VERSION_SUPERSEDED";
+    readonly BUNDLE_VERSION_REGRESSION: "BUNDLE_VERSION_REGRESSION";
+    readonly BUNDLE_VERSION_ZERO_PRICE: "BUNDLE_VERSION_ZERO_PRICE";
+    readonly BUNDLE_VERSION_DISCARD_NOT_IMPLEMENTED: "BUNDLE_VERSION_DISCARD_NOT_IMPLEMENTED";
+    readonly BUNDLE_VERSION_VALID_FROM_REQUIRED: "BUNDLE_VERSION_VALID_FROM_REQUIRED";
+    readonly BUNDLE_VERSION_VALID_FROM_INVALID: "BUNDLE_VERSION_VALID_FROM_INVALID";
+    readonly BUNDLE_VERSION_VALID_FROM_NOT_AFTER_PREVIOUS: "BUNDLE_VERSION_VALID_FROM_NOT_AFTER_PREVIOUS";
+    readonly BUNDLE_VERSION_VALID_FROM_NOT_GAPLESS: "BUNDLE_VERSION_VALID_FROM_NOT_GAPLESS";
+    readonly BUNDLE_VERSION_VALID_FROM_NOT_FUTURE: "BUNDLE_VERSION_VALID_FROM_NOT_FUTURE";
+    readonly BUNDLE_VERSION_VALID_UNTIL_INVALID: "BUNDLE_VERSION_VALID_UNTIL_INVALID";
+    readonly BUNDLE_VERSION_VALID_UNTIL_BEFORE_FROM: "BUNDLE_VERSION_VALID_UNTIL_BEFORE_FROM";
+    /** Publish blocked by strict mode. Carries `warnings[]` with own codes. */
+    readonly STRICT_MODE_VIOLATIONS: "STRICT_MODE_VIOLATIONS";
+    readonly PLAN_NOT_FOUND: "PLAN_NOT_FOUND";
+    readonly PLAN_VERSION_NOT_FOUND: "PLAN_VERSION_NOT_FOUND";
+    readonly BUNDLE_NOT_FOUND: "BUNDLE_NOT_FOUND";
+    readonly BUNDLE_VERSION_NOT_FOUND: "BUNDLE_VERSION_NOT_FOUND";
+    readonly FEATURE_NOT_FOUND: "FEATURE_NOT_FOUND";
+    readonly QUOTA_NOT_FOUND: "QUOTA_NOT_FOUND";
+    readonly PROMOTION_NOT_FOUND: "PROMOTION_NOT_FOUND";
+    readonly MARKETING_PROJECTION_NOT_FOUND: "MARKETING_PROJECTION_NOT_FOUND";
+    readonly PLAN_ALREADY_EXISTS: "PLAN_ALREADY_EXISTS";
+    readonly BUNDLE_ALREADY_EXISTS: "BUNDLE_ALREADY_EXISTS";
+    readonly MARKETING_PROJECTION_ALREADY_EXISTS: "MARKETING_PROJECTION_ALREADY_EXISTS";
+    /** A draft already exists — publish or discard it before creating another. */
+    readonly PLAN_DRAFT_ALREADY_EXISTS: "PLAN_DRAFT_ALREADY_EXISTS";
+    readonly BUNDLE_DRAFT_ALREADY_EXISTS: "BUNDLE_DRAFT_ALREADY_EXISTS";
+    readonly QUOTA_NOT_IN_DISCOVERY_SNAPSHOT: "QUOTA_NOT_IN_DISCOVERY_SNAPSHOT";
+    readonly DISCOVERY_STATUS_TRANSITION_INVALID: "DISCOVERY_STATUS_TRANSITION_INVALID";
+    readonly DISCOVERY_NOT_INITIALIZED: "DISCOVERY_NOT_INITIALIZED";
+    readonly PROMO_CODE_NOT_FOUND: "PROMO_CODE_NOT_FOUND";
+    readonly PROMO_CODE_ALREADY_EXISTS: "PROMO_CODE_ALREADY_EXISTS";
+    readonly PROMO_CODE_HAS_REDEMPTIONS: "PROMO_CODE_HAS_REDEMPTIONS";
+    /** Not redeemable. Carries `reason` (`PromoPreviewInvalidReason`). */
+    readonly PROMO_CODE_NOT_REDEEMABLE: "PROMO_CODE_NOT_REDEEMABLE";
+    readonly PROMO_CODE_FORMAT_INVALID: "PROMO_CODE_FORMAT_INVALID";
+    readonly PROMO_PERCENT_OUT_OF_RANGE: "PROMO_PERCENT_OUT_OF_RANGE";
+    readonly PROMO_AMOUNT_NOT_POSITIVE: "PROMO_AMOUNT_NOT_POSITIVE";
+    readonly PROMO_ONE_OFF_WITH_DURATION: "PROMO_ONE_OFF_WITH_DURATION";
+    readonly PROMO_DURATION_INVALID: "PROMO_DURATION_INVALID";
+    readonly PROMO_VALIDITY_WINDOW_INVALID: "PROMO_VALIDITY_WINDOW_INVALID";
+    readonly PROMO_PLAN_NOT_DISCOUNTABLE: "PROMO_PLAN_NOT_DISCOUNTABLE";
+    readonly PROMO_MIN_AMOUNT_NOT_POSITIVE: "PROMO_MIN_AMOUNT_NOT_POSITIVE";
+    readonly PROMO_WOULD_PRODUCE_ZERO_INVOICE: "PROMO_WOULD_PRODUCE_ZERO_INVOICE";
+    readonly PROMO_MAX_REDEMPTIONS_LOWERED: "PROMO_MAX_REDEMPTIONS_LOWERED";
+    /** No authenticated user on the request. */
+    readonly NOT_AUTHENTICATED: "NOT_AUTHENTICATED";
+    /** Authenticated, but the request carries no tenant. */
+    readonly NO_TENANT_ASSIGNED: "NO_TENANT_ASSIGNED";
+    /** Neither `tenantId` nor `userId` could be resolved from the request. */
+    readonly TENANT_CONTEXT_MISSING: "TENANT_CONTEXT_MISSING";
+    readonly TENANT_ADMIN_REQUIRED: "TENANT_ADMIN_REQUIRED";
+    readonly SUPER_ADMIN_REQUIRED: "SUPER_ADMIN_REQUIRED";
+    /** TOTP MFA has never been set up for this user. */
+    readonly MFA_NOT_SET_UP: "MFA_NOT_SET_UP";
+    /** Endpoint is MFA-gated and no `X-Mfa-Code` header was sent. */
+    readonly MFA_REQUIRED: "MFA_REQUIRED";
+    /** The supplied TOTP code did not verify. */
+    readonly MFA_FAILED: "MFA_FAILED";
+    /** Module misconfiguration, not an end-user condition. */
+    readonly AUTH_GUARDS_NOT_CONFIGURED: "AUTH_GUARDS_NOT_CONFIGURED";
+    /** `SETUP_TOKEN` env not set → setup disabled. */
+    readonly SETUP_DISABLED: "SETUP_DISABLED";
+    /** Provided token does not match. */
+    readonly INVALID_SETUP_TOKEN: "INVALID_SETUP_TOKEN";
+    /** A SUPER_ADMIN already exists — self-disable. */
+    readonly SETUP_ALREADY_DONE: "SETUP_ALREADY_DONE";
+    /** Invalid email in the request. */
+    readonly INVALID_EMAIL: "INVALID_EMAIL";
+    /** Email already taken (mapped from `PlatformUserExistsError`). */
+    readonly EMAIL_EXISTS: "EMAIL_EXISTS";
+};
+type PlatformErrorCode = SetupErrorCode | AuthErrorCode | PromoErrorCode | CatalogErrorCode | BillingErrorCode | ContractErrorCode | RegistrationErrorCode;
+/**
+ * Shape of a coded error response.
+ *
+ * Note what NestJS does with this: throwing an exception with a string
+ * argument yields `{ message, error, statusCode }`, whereas throwing it with
+ * an object passes that object through verbatim. Coded errors therefore carry
+ * no `error`/`statusCode` field in the body — the HTTP status is on the
+ * response itself, which is where a client should read it.
+ */
+interface PlatformErrorBody {
+    /** Stable machine-readable discriminator. Resolve i18n by this. */
+    code: PlatformErrorCode;
+    /** English developer-facing fallback. Do not parse it. */
+    message: string;
+    /**
+     * Named values interpolated into `message`, so a consumer can render a
+     * translated sentence without scraping the ids back out of the text.
+     */
+    params?: Record<string, unknown>;
+}
+
+/**
+ * A user to be created already exists under this email. Adapters throw it
+ * (e.g. in the SuperAdmin bootstrap); callers map it semantically:
+ * SetupService → HTTP 409, CLI → readable message.
+ */
+declare class PlatformUserExistsError extends Error {
+    readonly email: string;
+    readonly existingRole: PlatformRole;
+    readonly code = "USER_ALREADY_EXISTS";
+    constructor(email: string, existingRole: PlatformRole);
+}
+/**
+ * Realm-safe type guard (checks `code` instead of `instanceof`) — works even
+ * when thrower and catcher see the class from different module instances.
+ */
+declare function isPlatformUserExistsError(err: unknown): err is PlatformUserExistsError;
+
+/** Feature key → its `requires` keys (from Discovery/FeatureCatalogEntry). */
+type FeatureRequiresIndex = ReadonlyMap<string, readonly string[]>;
+interface FeatureRequiresSource {
+    featureKey: string;
+    requires?: readonly string[] | null;
+}
+/**
+ * Builds the lookup index from snapshot features (`DiscoveredFeature`) or
+ * catalog entries (`FeatureCatalogEntryRow`) — both carry
+ * `featureKey` + `requires`. Self-references are ignored.
+ */
+declare function buildFeatureRequiresIndex(features: readonly FeatureRequiresSource[]): FeatureRequiresIndex;
+/**
+ * Union of the `requires` of all `selected` features minus the features that
+ * `selected` itself contains — i.e. exactly the dependencies that must be
+ * covered outside the selection. Sorted, deduplicated; an empty result
+ * = the selection is self-contained (e.g. combo bundle SPORTPLATZ).
+ */
+declare function collectUnsatisfiedRequires(selected: readonly string[], index: FeatureRequiresIndex): string[];
+/**
+ * Bookability state of a bundle relative to the already covered
+ * features (plan ∪ already selected/booked bundles):
+ * - `covered`     — all bundle features are already covered → would be sold
+ *                   twice; the UI shows "already included" and it doesn't count.
+ * - `missing-requires` — at least one `requiresFeatures` is uncovered → grey out.
+ * - `bookable`    — selectable.
+ */
+type BundleAvailabilityState = 'bookable' | 'covered' | 'missing-requires';
+/** Feature carrier of a bundle for the bookability derivation. */
+interface BundleFeatureShape {
+    features: readonly string[];
+    requiresFeatures?: readonly string[] | null;
+}
+/**
+ * Uncovered `requiresFeatures` of a bundle relative to the coverage. Sorted,
+ * deduplicated; an empty result = all prerequisites covered.
+ */
+declare function missingRequiresFor(bundle: BundleFeatureShape, coveredFeatures: ReadonlySet<string>): string[];
+/**
+ * Unified status derivation for configurator and bundle-store UIs (#22/#35).
+ * Order is deliberate: full coverage beats missing requires (a fully
+ * covered bundle is never bookable, no matter which requires are open).
+ * Quotas don't count — they act additively.
+ */
+declare function resolveBundleAvailability(bundle: BundleFeatureShape, coveredFeatures: ReadonlySet<string>): BundleAvailabilityState;
+/** Bundle with features + identifying version ID for the redundancy derivation. */
+interface SelectableBundleShape extends BundleFeatureShape {
+    bundleVersionId: string;
+    /**
+     * Optional sort position. Makes the choice of the kept bundle
+     * predictable under mutual coverage (`selectChargeableBundles`).
+     * Missing = sorted to the end, then by `bundleVersionId`.
+     */
+    sortOrder?: number;
+}
+/**
+ * Coverage of a bundle relative to plan ∪ the *remaining* selected bundles —
+ * the bundle itself doesn't count against itself (otherwise every bundle would
+ * trivially be "already included"). Shared source for grid greying AND price/
+ * payload exclusion: the configurator grid and the subscription draft must see
+ * the same coverage, otherwise display and billing drift apart.
+ */
+declare function coverageExcludingSelf(selfVersionId: string, planFeatures: readonly string[], selectedBundles: readonly SelectableBundleShape[]): Set<string>;
+/**
+ * Is an already selected bundle fully covered (redundant) by plan ∪ the
+ * remaining selected bundles? Such bundles get sold twice — they must
+ * flow neither into the price total nor into the API payload.
+ * Uses the same `resolveBundleAvailability` derivation as the grid.
+ */
+declare function isBundleRedundant(bundle: SelectableBundleShape, planFeatures: readonly string[], selectedBundles: readonly SelectableBundleShape[]): boolean;
+/**
+ * Minimally covering subset of the selected bundles: keeps exactly the bundles
+ * that get charged/booked, and discards redundant ones (fully covered by
+ * plan ∪ the remaining kept bundles).
+ *
+ * Iterative rather than one-shot removal: a single
+ * `filter(b => !isBundleRedundant(b, plan, all))` over the full selection
+ * discards ALL participants under mutual/cyclic coverage (Y={C} and
+ * Z={C} cover each other → both filtered → feature C would be lost
+ * and neither charged nor booked). Instead, ONE redundant bundle relative
+ * to the CURRENTLY kept set is repeatedly removed and re-evaluated.
+ * That guarantees that the kept set covers the same feature union
+ * (minus plan) as the full selection — under mutual/cyclic coverage
+ * exactly ONE bundle remains deterministically, and for a proper subset
+ * (Y={C} ⊂ Z={C,D}) Y is discarded and Z is kept.
+ */
+declare function selectChargeableBundles<T extends SelectableBundleShape>(planFeatures: readonly string[], selectedBundles: readonly T[]): T[];
+
+/** Error code of the structured FeatureGuard 403 (#36). */
+declare const FEATURE_NOT_LICENSED: "FEATURE_NOT_LICENSED";
+/**
+ * A purchase offer that would cover the missing feature — typically
+ * a published catalog BundleVersion that contains the feature key.
+ */
+interface UpsellOffer {
+    bundleKey: string;
+    /** Live BundleVersion ID — for the `add` request of the tenant self-service. */
+    bundleVersionId?: string;
+    /** Net monthly price; `null` = price only context-dependent (pricing override). */
+    priceMonthlyNet: number | null;
+    /** ISO 4217, e.g. `EUR`. */
+    currency: string;
+    label?: string;
+}
+/**
+ * 403 body of the FeatureGuard on a missing entitlement — emitted in this
+ * complete shape by every guard, `FeatureGuard` and `StaticFeatureGuard`
+ * alike. Without a registered `UpsellOfferResolver` (or when the resolver
+ * fails) `offers` is an empty array, never absent, so a consumer that matched
+ * on `code === 'FEATURE_NOT_LICENSED'` may read `offers`/`featureKey` without
+ * a presence check.
+ */
+interface FeatureNotLicensedBody {
+    code: typeof FEATURE_NOT_LICENSED;
+    /** First required key — convenience for single-feature guards (issue shape). */
+    featureKey: string;
+    /** All required keys (`@RequireFeature` is a logical OR). */
+    featureKeys: string[];
+    offers: UpsellOffer[];
+    /** Human-readable message (fallback display). */
+    message: string;
+}
+/**
+ * Port (#36): resolves missing feature keys into purchase offers. Consumers
+ * register an implementation under `UPSELL_OFFER_RESOLVER_TOKEN`
+ * (@saasicat/nest) — e.g. the bundled
+ * `CatalogBundleUpsellResolver` against the published catalog bundles.
+ *
+ * `tenantId` allows tenant-specific offers (e.g. taking plan compatibility
+ * or already-booked dependencies into account); the
+ * default implementation does not use it.
+ */
+interface UpsellOfferResolver {
+    resolveOffers(featureKeys: string[], tenantId: string): Promise<UpsellOffer[]>;
+}
+
+declare const PENDING_EMAIL_TTL_HOURS = 72;
+declare const PENDING_ONBOARDING_TTL_DAYS = 14;
+declare const PENDING_CHECKOUT_TTL_DAYS = 30;
+declare const OTP_TTL_MINUTES = 10;
+declare const PASSWORD_RESET_TTL_MINUTES = 30;
+/** Number of OTP sends per rolling window before further sends are silently swallowed. */
+declare const OTP_RATE_LIMIT_MAX_SENDS = 3;
+declare const OTP_RATE_LIMIT_WINDOW_MINUTES = 15;
+/**
+ * Max. verification attempts per OTP code (each attempt atomically claims a
+ * slot before the hash comparison). Once reached, `verifyOtp()` throws
+ * `OTP_LOCKED` — even for a subsequently correct code. A newly generated OTP
+ * resets the counter (sending stays rate-limited separately).
+ * Env override: `SAAS_PLATFORM_OTP_VERIFY_MAX_ATTEMPTS`.
+ */
+declare const OTP_VERIFY_MAX_ATTEMPTS = 5;
+type RegistrationStatus = 'PENDING_EMAIL_VERIFICATION' | 'EMAIL_VERIFIED' | 'PLAN_SELECTED' | 'CHECKOUT_STARTED' | 'EXPIRED' | 'DELETED';
+type RegistrationStep = 1 | 2 | 3 | 4;
+/** Mapping status -> step that the frontend uses after login/resume. */
+declare const REGISTRATION_STEP_BY_STATUS: Record<RegistrationStatus, RegistrationStep>;
+interface PendingRegistration {
+    id: string;
+    tenantName: string;
+    tenantSlug: string | null;
+    salutation: string | null;
+    firstName: string;
+    lastName: string;
+    email: string;
+    passwordHash: string;
+    locale: string;
+    status: RegistrationStatus;
+    currentStep: RegistrationStep;
+    emailVerifiedAt: Date | null;
+    otpHash: string | null;
+    otpExpiresAt: Date | null;
+    otpSendCount: number;
+    lastOtpSentAt: Date | null;
+    /** Persistent counter of OTP verification attempts (brute-force lockout). */
+    otpAttemptCount: number;
+    selectedPlanId: string | null;
+    /** Configurator selection snapshot (step 3). Set by the service. */
+    configJson: RegistrationConfigSelection | null;
+    /** Set on the first `saveConfiguration()` call. */
+    billingCycle: 'MONTHLY' | 'YEARLY' | null;
+    /** Plaintext code (UI display). Validation runs fresh every time. */
+    appliedPromoCode: string | null;
+    checkoutSessionId: string | null;
+    checkoutStartedAt: Date | null;
+    expiresAt: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface PendingRegistrationCreateInput {
+    tenantName: string;
+    tenantSlug: string | null;
+    salutation: string | null;
+    firstName: string;
+    lastName: string;
+    email: string;
+    passwordHash: string;
+    locale: string;
+    otpHash: string;
+    otpExpiresAt: Date;
+    expiresAt: Date;
+}
+interface PendingRegistrationUpdateInput {
+    status?: RegistrationStatus;
+    currentStep?: RegistrationStep;
+    emailVerifiedAt?: Date | null;
+    otpHash?: string | null;
+    otpExpiresAt?: Date | null;
+    otpSendCount?: number;
+    lastOtpSentAt?: Date | null;
+    otpAttemptCount?: number;
+    selectedPlanId?: string | null;
+    configJson?: RegistrationConfigSelection | null;
+    billingCycle?: 'MONTHLY' | 'YEARLY' | null;
+    appliedPromoCode?: string | null;
+    checkoutSessionId?: string | null;
+    checkoutStartedAt?: Date | null;
+    expiresAt?: Date;
+}
+/** Adapter port: persistence for PendingRegistration (CRUD). */
+interface PendingRegistrationRepository {
+    findById(id: string): Promise<PendingRegistration | null>;
+    findByEmail(email: string): Promise<PendingRegistration | null>;
+    /** Webhook lookup: finds the pending record for the provider session. */
+    findByCheckoutSession(sessionId: string): Promise<PendingRegistration | null>;
+    /**
+     * Cleanup lookup: all pending records with `expiresAt < now`, max
+     * `limit` entries per call (batch protection). Ordering irrelevant, the
+     * cron service iterates sequentially.
+     */
+    findExpired(now: Date, limit: number): Promise<PendingRegistration[]>;
+    create(input: PendingRegistrationCreateInput): Promise<PendingRegistration>;
+    update(id: string, input: PendingRegistrationUpdateInput): Promise<PendingRegistration>;
+    /**
+     * Increments `otpAttemptCount` atomically by 1 and returns the NEW value.
+     * Must be atomic on the DB side (e.g. Prisma `{ increment: 1 }`) so that
+     * parallel failed attempts do not overwrite each other — the return
+     * value is the authoritative threshold for the lockout check.
+     */
+    incrementOtpAttemptCount(id: string): Promise<number>;
+    delete(id: string): Promise<void>;
+}
+/** Adapter port: detects whether a full user account (verified) exists for this email. */
+interface UserAccountLookup {
+    hasActiveUser(email: string): Promise<boolean>;
+}
+/** Adapter port: check whether a slug is available for a new tenant. */
+interface SlugAvailabilityCheck {
+    isSlugAvailable(slug: string): Promise<boolean>;
+}
+/** Wire format of a created checkout session (provider-agnostic). */
+interface CheckoutSession {
+    /** Provider-specific session ID (e.g. Stripe `cs_…`). */
+    sessionId: string;
+    /** Payment URL to be opened by the frontend. */
+    checkoutUrl: string;
+    /** Optional: provider name (`stripe`, `dev-stub`) for logging/audit. */
+    provider?: string;
+}
+type PaymentEventStatus = 'SUCCEEDED' | 'FAILED';
+/**
+ * Adapter port: idempotency log for payment webhooks. Stripe (and most
+ * other providers) deliver events at-least-once — the service calls
+ * `tryClaim` as an atomic race guard BEFORE it triggers the final
+ * activation.
+ */
+interface PaymentEventLog {
+    /**
+     * Tries to insert an event record via `@unique` INSERT. Returns
+     * `true` if it was newly created (webhook seen for the first time),
+     * `false` if it already exists (duplicate → silently drop).
+     *
+     * Implementations must return a DB unique-constraint-violation error
+     * (Prisma P2002) as `false`.
+     */
+    tryClaim(eventId: string, payload: {
+        provider: string;
+        sessionId: string | null;
+        status: PaymentEventStatus;
+        rawPayload?: unknown;
+    }): Promise<boolean>;
+}
+interface FinalActivationResult {
+    userId: string;
+    tenantId: string;
+    subscriptionId: string;
+}
+/**
+ * Adapter port: orchestrates the final creation of User + Tenant +
+ * Subscription after successful payment. App-specific — each app has its
+ * own schema (e.g. Tenant + TenantUser + Role + UserRole +
+ * Subscription).
+ *
+ * Implementations MUST perform the creation in a DB transaction so that
+ * partial creations are fully rolled back on errors.
+ */
+interface ActivationOrchestrator {
+    activate(pending: PendingRegistration): Promise<FinalActivationResult>;
+}
+interface HandlePaymentEventInput {
+    eventId: string;
+    sessionId: string | null;
+    provider: string;
+    status: PaymentEventStatus;
+    rawPayload?: unknown;
+}
+type HandlePaymentEventReason = 'ALREADY_PROCESSED' | 'PAYMENT_NOT_SUCCEEDED' | 'MISSING_SESSION_ID' | 'PENDING_REGISTRATION_NOT_FOUND' | 'INVALID_STATE';
+interface HandlePaymentEventResult {
+    activated: boolean;
+    reason?: HandlePaymentEventReason;
+    result?: FinalActivationResult;
+}
+interface CleanupResult {
+    /** Number of deleted PendingRegistration records. */
+    deleted: number;
+    /**
+     * `true` if the batch limit was reached — the next cron run
+     * handles the rest. Prevents memory spikes on large backlogs.
+     */
+    moreAvailable: boolean;
+}
+type RegistrationAuditEventType = 'REGISTRATION_STARTED' | 'REGISTRATION_NEUTRAL_ACTIVE_USER' | 'REGISTRATION_NEUTRAL_REPLAY' | 'REGISTRATION_NEUTRAL_EXPIRED' | 'OTP_VERIFIED' | 'OTP_VERIFY_FAILED' | 'OTP_RESEND_REQUESTED' | 'OTP_RATE_LIMIT_HIT' | 'PLAN_SELECTED' | 'CHECKOUT_STARTED' | 'PAYMENT_RECEIVED' | 'PAYMENT_DUPLICATE_IGNORED' | 'PAYMENT_FAILED' | 'ACTIVATION_COMPLETED' | 'LOGIN_SUCCEEDED' | 'LOGIN_INVALID_CREDENTIALS' | 'LOGIN_ONBOARDING_REQUIRED';
+/**
+ * Context information that the audit layer records per event.
+ * IP is expected as a hashed fingerprint — no plaintext IPs in the
+ * audit log (GDPR/compliance), no plaintext email (account enumeration).
+ */
+interface RegistrationAuditContext {
+    ipHash?: string | null;
+    userAgent?: string | null;
+}
+interface RegistrationAuditEvent {
+    eventType: RegistrationAuditEventType;
+    /**
+     * Pending registration ID, if already known. `null` for neutral
+     * responses (e.g. `start` without a new pending record).
+     */
+    pendingRegistrationId: string | null;
+    context?: RegistrationAuditContext;
+    /**
+     * Free-form metadata field. NEVER put email/password/OTP in plaintext —
+     * implementations must enforce that themselves.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Adapter port: persists audit events for the registration flow.
+ * Implementations typically target the app's respective `AuditLog` table.
+ *
+ * Log failures must not abort the auth flow — implementations should
+ * catch errors internally and only log them, not throw.
+ */
+interface RegistrationAuditLogger {
+    log(event: RegistrationAuditEvent): Promise<void>;
+}
+interface ConfiguratorModel {
+    id: string;
+    code: string;
+    name: string;
+    glyph: string;
+    tagline: string;
+    /** Mapping to the PlanCatalog (STARTER/STANDARD/PROFESSIONAL). */
+    planId: string;
+    monthlyNet: number;
+    yearlyNet: number;
+    tags: string[];
+    /** Feature keys included in the model price (PlanVersion.features). */
+    includedFeatureKeys: string[];
+    quotaBase: Record<string, number>;
+    popular?: boolean;
+}
+interface ConfiguratorCatalog {
+    /** Factor `yearlyNet = monthlyNet * cycleDiscount` (typically 10 = 2 months free). */
+    cycleDiscount: number;
+    currency: string;
+    vatRate: number;
+    models: ConfiguratorModel[];
+}
+interface RegistrationConfigSelection {
+    modelId: string;
+    billingCycle: 'MONTHLY' | 'YEARLY';
+    appliedPromoCode: string | null;
+    /**
+     * P11.4: preselected CheckoutOffer from the website
+     * (`?offer=<id>` parameter). Moves into `PendingRegistration.configJson`,
+     * is read by the `ActivationOrchestrator` to consume the offer during
+     * onboarding activation (`status=consumed`) and freeze it into
+     * `Subscription.packageSnapshot`. When `null`, activation runs
+     * without an offer snapshot.
+     */
+    offerId?: string | null;
+}
+interface ConfiguratorPriceBreakdown {
+    cycle: 'MONTHLY' | 'YEARLY';
+    effectiveQuotas: Record<string, number>;
+    modelMonthlyNet: number;
+    subtotalMonthlyNet: number;
+    subtotalNet: number;
+    discountAmount: number;
+    totalNet: number;
+    vatRate: number;
+    totalGross: number;
+    yearlySavings: number;
+    appliedPromo?: {
+        code: string;
+        label: string;
+        percent: number;
+    };
+}
+interface SaveRegistrationConfigInput {
+    pendingRegistrationId: string;
+    selection: RegistrationConfigSelection;
+}
+interface SaveRegistrationConfigResult {
+    pendingRegistrationId: string;
+    status: RegistrationStatus;
+    nextStep: RegistrationStep;
+    selection: RegistrationConfigSelection;
+    breakdown: ConfiguratorPriceBreakdown;
+}
+/**
+ * Adapter port: provides the (app-specific) configurator catalog.
+ *
+ * Recommended implementation: `ConfiguratorCatalogBuilder` from
+ * `@saasicat/nest/billing`. The builder combines SuperAdmin DB data
+ * (live PlanVersions) with an app-local plan marketing map.
+ */
+interface RegistrationConfiguratorLookup {
+    getCatalog(): Promise<ConfiguratorCatalog>;
+}
+/**
+ * Wire format of a live PlanVersion (latest published per planId).
+ * Read from the DB table `plan_versions`.
+ */
+interface ConfiguratorPlanVersionRow {
+    planId: string;
+    version: number;
+    monthlyNet: number;
+    yearlyNet: number;
+    /** Feature keys included in the plan price. */
+    features: string[];
+    /** Quota key → base value (`-1` = unlimited). */
+    quotas: Record<string, number>;
+    marketed: boolean;
+}
+/**
+ * Adapter port: reads the configurator sources from the DB (SuperAdmin
+ * maintains them). Consumers typically use a Prisma implementation.
+ */
+interface ConfiguratorSourcesLookup {
+    listLivePlans(): Promise<ConfiguratorPlanVersionRow[]>;
+}
+/**
+ * App-local marketing data for the plan selection area of the configurator.
+ * The SuperAdmin stores only PlanId/prices — the "model" presentation
+ * (display name, glyph, tagline) is branding and lives in the app.
+ */
+interface ConfiguratorPlanMarketing {
+    /** PlanId from the SuperAdmin (e.g. `STARTER`). */
+    planId: string;
+    code: string;
+    name: string;
+    glyph: string;
+    tagline: string;
+    tags: string[];
+    popular?: boolean;
+}
+/**
+ * Adapter port: provides the app-specific marketing data (plan names,
+ * price parameters). Typically supplied by a static TS constant
+ * in the app.
+ */
+interface ConfiguratorMarketingProvider {
+    listPlanMarketing(): ConfiguratorPlanMarketing[];
+    /** Factor `yearlyNet = monthlyNet * cycleDiscount`. Default `10`. */
+    getCycleDiscount(): number;
+    getVatRate(): number;
+    getCurrency(): string;
+}
+/**
+ * Adapter port: promo-code preview against a gross subtotal.
+ * Typically wraps `@saasicat/nest/promo:PromoCodesService.preview()`.
+ */
+interface RegistrationPromoPreview {
+    preview(params: {
+        code: string;
+        planId: string;
+        billingCycle: 'MONTHLY' | 'YEARLY';
+        subtotalGross: number;
+        /** Optional for the firstTimeCustomersOnly check. */
+        email?: string;
+    }): Promise<{
+        valid: boolean;
+        reason?: string;
+        percent?: number;
+        label?: string;
+        discountAmount?: number;
+    }>;
+}
+/** Default TTL for signed resume tokens (60 min). */
+declare const REGISTRATION_RESUME_TTL_MINUTES = 60;
+/**
+ * Adapter port: signs / verifies resume tokens for the
+ * "resume registration" flow (cases C/D per spec).
+ *
+ * Token payload is a provider detail (typically JWT) — the service only knows
+ * `pendingRegistrationId` as content and `ttlMinutes` as the expiry window.
+ */
+interface RegistrationResumeTokenSigner {
+    sign(params: {
+        pendingRegistrationId: string;
+        ttlMinutes?: number;
+    }): Promise<string>;
+    /**
+     * Verifies the token. Throws if signature or expiry do not match
+     * — the service layer translates this into a BadRequestException with
+     * code `RESUME_TOKEN_INVALID`.
+     */
+    verify(token: string): Promise<{
+        pendingRegistrationId: string;
+    }>;
+}
+/** Adapter port: sends the resume-link email to the user. */
+interface RegistrationResumeDelivery {
+    sendResumeEmail(params: {
+        to: string;
+        firstName: string;
+        locale: string;
+        resumeUrl: string;
+    }): Promise<void>;
+}
+/**
+ * Input to `PendingRegistrationService.resumeWithToken()` — the frontend
+ * passes the token from the `?resume=<jwt>` query.
+ */
+interface ResumeRegistrationInput {
+    token: string;
+    /**
+     * Base URL of the app against which the resume link is generated
+     * (e.g. `https://app.example.com`). Only forwarded to the mail delivery,
+     * the service itself hosts no link.
+     */
+    resumeBaseUrl?: string;
+}
+/**
+ * Public-safe snapshot of a PendingRegistration for the resume flow:
+ * the frontend fills the completed onboarding steps with this data.
+ *
+ * Deliberately WITHOUT `passwordHash`, `otpHash`, `otpExpiresAt` — these must
+ * never go to the client.
+ */
+interface PendingRegistrationSnapshot {
+    tenantName: string;
+    tenantSlug: string | null;
+    salutation: string | null;
+    firstName: string;
+    lastName: string;
+    email: string;
+    locale: string;
+    status: RegistrationStatus;
+    currentStep: RegistrationStep;
+    emailVerifiedAt: string | null;
+    selectedPlanId: string | null;
+    /** Configurator selection snapshot for step-3 resume. */
+    config: RegistrationConfigSelection | null;
+    billingCycle: 'MONTHLY' | 'YEARLY' | null;
+    appliedPromoCode: string | null;
+    checkoutSessionId: string | null;
+}
+interface ResumeRegistrationResult {
+    pendingRegistrationId: string;
+    status: RegistrationStatus;
+    nextStep: RegistrationStep;
+    snapshot: PendingRegistrationSnapshot;
+}
+/** Adapter port: payment provider (Stripe, Dev-Stub, Mollie, ...). */
+interface PaymentProvider {
+    /**
+     * Creates a checkout session at the payment provider and returns the URL
+     * that the frontend should redirect to.
+     *
+     * @param params.pendingRegistrationId Stored as `client_reference_id` (or similar)
+     *   in the provider — the webhook needs it to link back.
+     * @param params.planId The chosen plan (Stripe price/product mapping lives
+     *   in the adapter).
+     * @param params.successUrl Where to go after successful payment.
+     * @param params.cancelUrl Where to go on cancellation.
+     */
+    createCheckoutSession(params: {
+        pendingRegistrationId: string;
+        planId: string;
+        email: string;
+        successUrl: string;
+        cancelUrl: string;
+    }): Promise<CheckoutSession>;
+}
+/** Adapter port: OTP delivery via email (or another channel). */
+interface RegistrationOtpDelivery {
+    sendVerificationOtp(params: {
+        to: string;
+        code: string;
+        firstName: string;
+        locale: string;
+    }): Promise<void>;
+}
+/** Wire format for a publicly selectable plan in onboarding step 3. */
+interface PublicSignupPlan {
+    id: string;
+    name?: string;
+    tagline?: string;
+    monthlyNet: number | null;
+    yearlyNet: number | null;
+    popular?: boolean;
+    features: string[];
+}
+/**
+ * Adapter port: provides the plan selection for step 3 (package selection).
+ *
+ * Implementation must check BOTH:
+ *  - Plan is marketable in the catalog (`marketed !== false`).
+ *  - A published, non-superseded `PlanVersion` exists in the DB
+ *    (otherwise the final `Subscription` cannot set a `planVersionId`).
+ */
+interface PlanCatalogLookup {
+    /** List of all public-signup-capable plans; empty if none. */
+    listPublicSignupPlans(): Promise<PublicSignupPlan[]>;
+    /** Detail lookup of a plan. null if not selectable (e.g. ENTERPRISE). */
+    findPublicSignupPlan(planId: string): Promise<PublicSignupPlan | null>;
+}
+/** Input to PendingRegistrationService.start(). */
+interface StartRegistrationInput {
+    tenantName: string;
+    /** If null/undefined it is generated from tenantName. */
+    tenantSlug?: string | null;
+    salutation?: string | null;
+    firstName: string;
+    lastName: string;
+    email: string;
+    password: string;
+    locale?: string;
+}
+/** Result contract for the (account-enumeration-safe) start call. */
+interface StartRegistrationResult {
+    /** Always true. Account-enumeration protection: no information about DB state to the outside. */
+    neutral: true;
+}
+interface VerifyRegistrationOtpResult {
+    status: RegistrationStatus;
+    nextStep: RegistrationStep;
+    pendingRegistrationId: string;
+}
+interface SelectPlanInput {
+    pendingRegistrationId: string;
+    planId: string;
+}
+interface SelectPlanResult {
+    pendingRegistrationId: string;
+    status: RegistrationStatus;
+    nextStep: RegistrationStep;
+    selectedPlanId: string;
+}
+interface StartCheckoutInput {
+    pendingRegistrationId: string;
+    successUrl: string;
+    cancelUrl: string;
+}
+interface StartCheckoutResult {
+    pendingRegistrationId: string;
+    status: RegistrationStatus;
+    nextStep: RegistrationStep;
+    checkoutSessionId: string;
+    checkoutUrl: string;
+}
+
+interface SetupStatusResponse {
+    /** true as long as no SUPER_ADMIN exists — the UI then shows the wizard. */
+    needsSetup: boolean;
+}
+interface SetupRequest {
+    /** Must match the server-side `SETUP_TOKEN` (env var). */
+    token: string;
+    email: string;
+    /** Optional — if absent, the server generates one and returns it. */
+    password?: string;
+}
+interface SetupResult {
+    userId: string;
+    email: string;
+    /** otpauth:// URI (fallback / deep link). */
+    otpauthUri: string;
+    /** Server-side rendered QR code as a PNG data URL for scanning. */
+    qrDataUrl: string;
+    /** Base32 TOTP secret as a fallback for manual entry. */
+    secret: string;
+    /** Set when the server generated the password (no `password` in the request). */
+    generatedPassword?: string;
+}
+interface SetupConfirmMfaRequest {
+    token: string;
+    userId: string;
+    /** TOTP code from the authenticator app. */
+    code: string;
+}
+interface SetupConfirmMfaResponse {
+    ok: boolean;
+}
+
+/** Why a version is editable (for UI badges + audit logs). */
+type VersionEditableReason = 'draft' | 'pre-active';
+interface VersionEditability {
+    editable: boolean;
+    reason: VersionEditableReason | null;
+}
+/**
+ * Decides whether a versioned catalog entity may currently be edited.
+ * `now` is parameterized so that tests can be deterministic and
+ * services use the same point in time for list annotation + mutation
+ * gate.
+ */
+declare function isVersionEditable(v: VersionedEntityBase, now?: Date): VersionEditability;
+
+declare const ERROR_MESSAGES_EN: Record<PlatformErrorCode, string>;
+/** Values available for interpolation into a message template. */
+type ErrorMessageParams = Record<string, unknown>;
+/**
+ * Replaces `{name}` with `params.name`. An unknown placeholder is left
+ * verbatim, so a missing value is visible in the UI rather than silently
+ * vanishing.
+ */
+declare function formatErrorMessage(template: string, params?: ErrorMessageParams): string;
+/**
+ * Turns an error body into display text.
+ *
+ * Falls back in this order: the consumer's own catalogue, the shipped default,
+ * the English `message` the backend sent, and only then the bare code. Because
+ * every coded exception carries a message, the last step is unreachable in
+ * practice — a consumer that has not translated a new code yet shows English
+ * prose, never `PLAN_VERSION_SUPERSEDED`.
+ *
+ * Interpolation reads `params` first and the remaining top-level body fields
+ * second, so a template may name either without the value being duplicated on
+ * the wire.
+ */
+declare function resolveErrorMessage(body: Partial<PlatformErrorBody> & Record<string, unknown>, overrides?: Partial<Record<string, string>>, defaults?: Partial<Record<string, string>>): string;
+
+declare const ERROR_MESSAGES_DE: Record<PlatformErrorCode, string>;
+
+export { AUTH_ERROR_CODES, type ActionKey, type ActivationOrchestrator, type ActivePlanVersionWhere, type ActivePlanVersionWhereWithEndsAt, type ActiveVersionWhere, type ActiveVersionWhereWithEndsAt, type ActorTag, type AdminActor, type AdminAuditListFilter, type AdminManifest, type AdminResourcesPort, type AdminSubscriptionListRow, type AdminTenantDetail, type AdminTenantListFilter, type AdminTenantListRow, type AdminTenantStateResult, type AdminUserListFilter, type AdminUserListRow, type ApplyOnboardingSelectionInput, type ApplyOnboardingSelectionResult, type ApprovedCatalogKeys, type AuditActionDef, type AuditEntry, type AuditPort, type AuditQuery, type AuditQueryPort, type AuditStatsPort, type AuditStatsSnapshot, type AuthErrorCode, BILLING_ERROR_CODES, type BillingCycle, type BillingErrorCode, type BundleAvailabilityState, type BundleCompatibility, type BundleFeatureShape, type BundleListFilter, type BundlePricingOverride, type BundleRepository, type BundleRow, type BundleVersionFields, type BundleVersionMutationResult, type BundleVersionRow, CATALOG_ERROR_CODES, CONTRACT_ERROR_CODES, type CancelSubscriptionBundleData, type CapabilityCatalogEntryRow, type CapabilityCodeStatus, type CapabilityKey, type CapabilityKind, type CatalogEntryFilter, type CatalogEntryI18n, type CatalogEntryI18nFields, type CatalogEntryRepository, type CatalogErrorCode, type ChangeDirection, type CheckoutOfferFilter, type CheckoutOfferLineItem, type CheckoutOfferLineItemKind, type CheckoutOfferPriceBreakdown, type CheckoutOfferPromoCodeSnapshot, type CheckoutOfferPromotionSnapshot, type CheckoutOfferRepository, type CheckoutOfferRow, type CheckoutOfferStatus, type CheckoutSession, type CleanupResult, type CliUserRow, type ComponentKey, type ConfiguratorCatalog, type ConfiguratorMarketingProvider, type ConfiguratorModel, type ConfiguratorPlanMarketing, type ConfiguratorPlanVersionRow, type ConfiguratorPriceBreakdown, type ConfiguratorSourcesLookup, type ContractErrorCode, type ContractLineItemKind, type ContractLineItemRecord, type CreateBundleData, type CreateBundleVersionDraftData, type CreateCheckoutOfferData, type CreateMarketingProjectionData, type CreatePlanData, type CreatePlanVersionDraftData, type CreatePromoCodeData, type CreatePromoCodeRequest, type CreatePromotionData, type CreateSubscriptionBundleData, type CreateSubscriptionContractData, type CreateSuperAdminCliInput, type CreateTenantInput, type DiffResult, type DiscoveredCapability, type DiscoveredFeature, type DiscoveredQuota, type DiscoveredQuotaPolicy, type DiscoveryCodeStatus, type DiscoverySnapshot, type DiscoveryStatus, ERROR_MESSAGES_DE, ERROR_MESSAGES_EN, type EffectiveLimitsSnapshot, type ErrorMessageParams, FEATURE_NOT_LICENSED, type FeatureCatalogEntryRow, type FeatureDef, type FeatureKey, type FeatureNotLicensedBody, type FeatureRequiresIndex, type FeatureTier, type FeatureUiMeta, type FeatureUiRegistry, type FinalActivationResult, type FirstTimeCustomerCheck, type HandlePaymentEventInput, type HandlePaymentEventReason, type HandlePaymentEventResult, type ImmediatePlanChangeInput, type InvoiceLineItemSnapshot, type KpiCardDef, type KpiDisplayHint, type ManifestAccessPort, type ManifestContribution, type MarketingProjectionFilter, type MarketingProjectionRepository, type MarketingProjectionRow, type MarketingSettingsRepository, type MarketingSettingsRow, type MarketingTargetType, type MarketingTopFeature, type MfaPort, type NewContractLineItemData, OTP_RATE_LIMIT_MAX_SENDS, OTP_RATE_LIMIT_WINDOW_MINUTES, OTP_TTL_MINUTES, OTP_VERIFY_MAX_ATTEMPTS, type OnboardingPromoRedemption, type OnboardingSelectionRequest, type OnboardingSelectionResponse, PASSWORD_RESET_TTL_MINUTES, PENDING_CHECKOUT_TTL_DAYS, PENDING_EMAIL_TTL_HOURS, PENDING_ONBOARDING_TTL_DAYS, PLATFORM_ERROR_CODES, PROMO_ERROR_CODES, type Paginated, type PasswordHasher, type PasswordResetCliResult, type PaymentEventLog, type PaymentEventStatus, type PaymentProvider, type PendingRegistration, type PendingRegistrationCreateInput, type PendingRegistrationRepository, type PendingRegistrationSnapshot, type PendingRegistrationUpdateInput, type PersistenceCapabilities, PersistenceCapabilityError, type PersistenceClassRef, type PersistenceInjectionToken, type PersistenceProvider, type PlanCatalog, type PlanCatalogApp, type PlanCatalogImportReport, type PlanCatalogImportSink, type PlanCatalogLookup, type PlanCatalogMarketing, type PlanCatalogReadSink, type PlanCatalogReadSnapshot, type PlanDef, type PlanId, type PlanListFilter, type PlanRepository, type PlanRow, type PlanVersion, type PlanVersionFields, type PlanVersionMutationResult, type PlanVersionRecord, type PlanVersionRepository, type PlanVersionRow, type PlatformErrorBody, type PlatformErrorCode, type PlatformRole, type PlatformUserDto, PlatformUserExistsError, type ProjectPageDef, type PromoCode, type PromoCodeDurationType, type PromoCodeFilter, type PromoCodeRecord, type PromoCodeRedemption, type PromoCodeRedemptionListItem, type PromoCodeRedemptionRecord, type PromoCodeRedemptionRepository, type PromoCodeRedemptionStatus, type PromoCodeRepository, type PromoCodeStatsPort, type PromoCodeStatsSnapshot, type PromoCodeStatus, type PromoCodeValidationLog, type PromoCodeValidationLogRepository, type PromoCodeValidationResult, type PromoCodeValueType, type PromoErrorCode, type PromoPreviewInvalidReason, type PromoPreviewRequest, type PromoPreviewResponse, type PromoPreviewValidResponse, type PromoRevenueDeductionAggregator, type PromoSubscriptionLookup, type PromotionBillingCycle, type PromotionFilter, type PromotionI18n, type PromotionI18nFields, type PromotionRepository, type PromotionResult, type PromotionRow, type PromotionStatus, type PromotionTargetType, type PromotionType, type PromotionValue, type PublicBootResponse, type PublicComparisonRow, type PublicMarketingBundle, type PublicMarketingCatalogResponse, type PublicMarketingPlan, type PublicMarketingPromo, type PublicSignupPlan, type PublishBundleVersionData, type PublishPlanVersionData, type QuotaCatalogEntryRow, type QuotaEnforcementMode, type QuotaKey, type QuotaProvider, REGISTRATION_ERROR_CODES, REGISTRATION_RESUME_TTL_MINUTES, REGISTRATION_STEP_BY_STATUS, type ReassignTenantAdminCliResult, type RedeemPromoInTransactionCallback, type RegistrationAuditContext, type RegistrationAuditEvent, type RegistrationAuditEventType, type RegistrationAuditLogger, type RegistrationConfigSelection, type RegistrationConfiguratorLookup, type RegistrationErrorCode, type RegistrationOtpDelivery, type RegistrationPromoPreview, type RegistrationResumeDelivery, type RegistrationResumeTokenSigner, type RegistrationStatus, type RegistrationStep, type RequiredCapabilities, type ResumeRegistrationInput, type ResumeRegistrationResult, type ReviewCatalogEntryData, type RlsBypassPort, SETUP_ERROR_CODES, type SaaSiCatPersistenceAdapter, type SaaSiCatPersistenceAdminResources, type SaaSiCatPersistenceCatalog, type SaaSiCatPersistenceCore, type SaaSiCatPersistenceEntitlement, type SaaSiCatPersistencePromo, type SaaSiCatPersistenceTenantBilling, type SaveRegistrationConfigInput, type SaveRegistrationConfigResult, type ScheduledPlanChangeInput, type SelectPlanInput, type SelectPlanResult, type SelectableBundleShape, type SetCatalogEntryReviewData, type SetupConfirmMfaRequest, type SetupConfirmMfaResponse, type SetupErrorCode, type SetupRequest, type SetupResult, type SetupStatusResponse, type SlugAvailabilityCheck, type StandardPageDef, type StandardPageKey, type StartCheckoutInput, type StartCheckoutResult, type StartRegistrationInput, type StartRegistrationResult, type StrictModeWarning, type StrictModeWarningCode, type Subscription, type SubscriptionBundleRecord, type SubscriptionBundleRepository, type SubscriptionBundleView, type SubscriptionContractFilter, type SubscriptionContractInvoiceSnapshot, type SubscriptionContractPriceSnapshot, type SubscriptionContractRecord, type SubscriptionContractRepository, type SubscriptionContractStatus, type SubscriptionRecord, type SubscriptionRepository, type SubscriptionStatsPort, type SubscriptionStatsSnapshot, type SubscriptionStatus, type SubscriptionUsagePort, type SubscriptionUsageRecord, type SuperAdminProvisioningPort, type SyncDiscoveryResult, type TenantActionDef, type TenantColumnDef, type TenantDto, type TenantListFilter, type TenantPort, type TenantSubscriptionWritePort, type TerminateSubscriptionContractData, type TopPromoCode, type TransactionContext, type TransactionRunner, type UpdateBundleData, type UpdateBundleVersionDraftData, type UpdateCatalogEntryBaseData, type UpdateCatalogEntryI18nData, type UpdateCheckoutOfferData, type UpdateMarketingProjectionData, type UpdateMarketingSettingsData, type UpdatePlanData, type UpdatePlanVersionDraftData, type UpdatePromoCodeData, type UpdatePromoCodeRequest, type UpdatePromotionData, type UpsellOffer, type UpsellOfferResolver, type UpsertCapabilityEntryData, type UpsertFeatureCatalogEntryInput, type UpsertFeatureEntryData, type UpsertPlanInput, type UpsertPlanVersionInput, type UpsertQuotaEntryData, type UpsertResult, type UsageSnapshotPort, type UserAccountLookup, type UserListFilter, type UserManagementPort, type UserPort, type VerifyRegistrationOtpResult, type VersionChange, type VersionChangeDirection, type VersionEditability, type VersionEditableReason, type VersionedEntityBase, applyPromo, assertPersistenceCapabilities, buildActivePlanVersionWhere, buildActiveVersionWhere, buildFeatureRequiresIndex, classifyBundleVersionDiff, classifyPlanDiff, collectUnsatisfiedRequires, coverageExcludingSelf, formatErrorMessage, isBundleRedundant, isPlatformUserExistsError, isVersionEditable, missingRequiresFor, pickActivePromo, promoStatus, resolveBundleAvailability, resolveErrorMessage, selectChargeableBundles, startOfUtcDay };