@saasicat/nest 0.26.1 → 0.27.0

package/dist/platform/index.d.cts

@@ -1,31 +1,179 @@
-import { p as PlanResolverPort } from '../saas-platform.module-CgalxzcT.cjs';
-export { P as PLAN_RESOLVER_PORT_TOKEN, S as SaaSiCatModule, a as SaasPlatformAdapters, b as SaasPlatformAdminResourcesOptions, c as SaasPlatformAdminStatsOptions, d as SaasPlatformCatalogOptions, e as SaasPlatformCheckoutOfferOptions, S as SaasPlatformModule, f as SaasPlatformModuleOptions, g as SaasPlatformPromoCodesOptions, h as SaasPlatformSetupOptions, i as SaasPlatformSubscriptionBundlesOptions, j as SaasPlatformSubscriptionContractOptions, k as SaasPlatformTenantAuthGuards, l as SaasPlatformTenantBillingOptions, m as SetupModule, n as SetupModuleOptions, o as StaticPlanResolver, T as TenantManifestControllerOptions, q as buildTenantManifestController } from '../saas-platform.module-CgalxzcT.cjs';
-export { a as SAASICAT_PUBLIC_ROUTE_KEY, d as SaaSiCatPublicRoute, S as SetupService, f as defineSaaSiCat, i as isSaaSiCatPublicRoute } from '../define-saasicat-D30I-WET.cjs';
-import { SubscriptionRepository, UsageSnapshotPort, QuotaProvider } from '@saasicat/types';
-import { S as StaticEntitlementService } from '../enforce-quota.interceptor-DY6CLjoP.cjs';
-export { E as EnforceQuotaInterceptor, Q as QUOTA_PROVIDERS_TOKEN, b as STATIC_FEATURE_GUARD_CONFIG_TOKEN, c as StaticEntitlementSnapshot, a as StaticFeatureGuard, d as StaticFeatureGuardConfig } from '../enforce-quota.interceptor-DY6CLjoP.cjs';
-import { OnApplicationBootstrap } from '@nestjs/common';
+export { a as SAASICAT_PUBLIC_ROUTE_KEY, d as SaaSiCatModule, e as SaaSiCatPublicRoute, d as SaasPlatformModule, S as SetupService, g as defineSaaSiCat, i as isSaaSiCatPublicRoute } from '../define-saasicat-CFxut1VR.cjs';
+import { CanActivate, DynamicModule, OnApplicationBootstrap } from '@nestjs/common';
+import { SaasicatPersistenceAdapter, SubscriptionUsagePort, SubscriptionRepository, UsageSnapshotPort, QuotaProvider } from '@saasicat/types';
+import { P as ProviderSpec } from '../di-CcNeq9v-.cjs';
+import { b as DiscoveryAppInfo } from '../discovery.scanner-DLgEvuoy.cjs';
+export { c as DiscoveryScanner } from '../discovery.scanner-DLgEvuoy.cjs';
+import { e as SaasPlatformModuleOptions, S as SaasPlatformAdapters, o as PlanResolverPort } from '../module-options-klrPnWGF.cjs';
+export { P as PLAN_RESOLVER_PORT_TOKEN, a as SaasPlatformAdminResourcesOptions, b as SaasPlatformAdminStatsOptions, c as SaasPlatformCatalogOptions, d as SaasPlatformCheckoutOfferOptions, f as SaasPlatformPromoCodesOptions, g as SaasPlatformSetupOptions, h as SaasPlatformSubscriptionBundlesOptions, i as SaasPlatformSubscriptionContractOptions, j as SaasPlatformTenantAuthGuards, k as SaasPlatformTenantBillingOptions, l as SetupModule, m as SetupModuleOptions, n as StaticPlanResolver, T as TenantManifestControllerOptions, p as buildTenantManifestController } from '../module-options-klrPnWGF.cjs';
+import { S as StaticEntitlementService } from '../enforce-quota.interceptor-N80KC34N.cjs';
+export { E as EnforceQuotaInterceptor, Q as QUOTA_PROVIDERS_TOKEN, b as STATIC_FEATURE_GUARD_CONFIG_TOKEN, c as StaticEntitlementSnapshot, a as StaticFeatureGuard, d as StaticFeatureGuardConfig } from '../enforce-quota.interceptor-N80KC34N.cjs';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 export { A as AdminBypassRlsInterceptor, a as AdminManifestModule, b as AdminManifestModuleOptions, c as AdminManifestService, d as AdminModule, e as AdminModuleOptions, f as AdminStatsService, M as MfaGuard, h as MfaService, S as SuperAdminGuard } from '../admin-stats.service-HUZIU448.cjs';
 export { A as AdminAuditService } from '../admin-audit.service-9IqXMlZm.cjs';
 export { e as AdminResourcesService, f as AdminStatsModule, g as AdminStatsModuleOptions } from '../admin-resources.module-DGgGSdzN.cjs';
 export { c as EntitlementService } from '../aggregation-mZ7WZROK.cjs';
-export { d as ComposedTenantAuthGuard, P as PendingPlanMaterializationService, h as PlanChangePreviewService, r as SubscriptionBundlePreviewService, s as SubscriptionBundlesService, T as TenantAdminGuard, t as TenantBillingController } from '../tenant-billing.controller-DHSUrT_N.cjs';
+export { d as ComposedTenantAuthGuard, P as PendingPlanMaterializationService, h as PlanChangePreviewService, r as SubscriptionBundlePreviewService, s as SubscriptionBundlesService, T as TenantAdminGuard, t as TenantBillingController } from '../tenant-billing.controller-CAMMdfn1.cjs';
 export { B as BundlesService, C as CatalogEntriesService, M as MarketingProjectionsService, b as MarketingSettingsService, P as PlanVersionsService, c as PlansService, d as PromotionsService, e as PublicMarketingCatalogService } from '../plan-versions.service-_saKzb50.cjs';
-export { c as DiscoveryScanner } from '../discovery.scanner-DLgEvuoy.cjs';
 export { P as PromoCodeRateLimitGuard } from '../rate-limit.guard-dntqAlfZ.cjs';
 export { g as PromoCodesService } from '../service-D48clObR.cjs';
 export { a as CheckoutOfferModule, b as CheckoutOfferModuleOptions } from '../checkout-offer.module-DmlpPevf.cjs';
 export { C as CheckoutOfferService } from '../checkout-offer.service-BX51dljL.cjs';
 export { S as SubscriptionContractModule, a as SubscriptionContractModuleOptions } from '../subscription-contract.module-B2uNvUJL.cjs';
 export { S as SubscriptionContractService } from '../subscription-contract.service--cm47ZJJ.cjs';
-import '../di-CcNeq9v-.cjs';
+import '../tenant-billing.module-BxJS6fX4.cjs';
+import '../catalog.module-D-_pQDNA.cjs';
 import '../plan-resolution-CFCoUkrE.cjs';
 import '../module-CHMIyWlf.cjs';
-import '../catalog.module-D-_pQDNA.cjs';
-import '../subscription-bundles.module-Cfi-lFWF.cjs';
 import 'rxjs';
 
+/**
+ * What `tenantBilling` resolved and its two dependants need.
+ *
+ * Mutable, and the only mutable thing here: `composeTenantBilling` writes it,
+ * `composeSubscriptionBundles` and the entitlement runtime read it. A composer
+ * that runs before tenant billing sees the initial values, which is correct —
+ * there was no tenant billing to resolve anything.
+ */
+interface SharedTenantBinding {
+    /** Normalised `authGuards`, shared with the bundle controller. */
+    authGuards?: ProviderSpec<ReadonlyArray<CanActivate>>;
+    /** The usage port both controllers report against. */
+    subscriptionUsagePort?: ProviderSpec<SubscriptionUsagePort>;
+    /**
+     * Whether the tenant-billing module already registered the app's quota
+     * providers.
+     *
+     * It registers them as its own providers and exports, so the entitlement
+     * runtime must not register them a second time — two instances of a
+     * `QuotaProvider` are two counters over the same rows.
+     */
+    quotaProvidersHostedByTenantBilling: boolean;
+}
+interface CompositionContext {
+    readonly options: SaasPlatformModuleOptions;
+    /** After the bundle slices and the explicit entries have been merged. */
+    readonly adapters: SaasPlatformAdapters;
+    readonly persistence: SaasicatPersistenceAdapter | undefined;
+    /** App key and version, for discovery and the public catalogue. */
+    readonly appInfo: DiscoveryAppInfo;
+    /** Entitlement is needed directly, or by tenant billing / bundles. */
+    readonly requiresFullEntitlement: boolean;
+    readonly shared: SharedTenantBinding;
+}
+
+/** One feature's contribution: the modules it adds, or none. */
+type Composer = (ctx: CompositionContext) => DynamicModule[];
+declare const FEATURE_COMPOSERS: readonly Composer[];
+/** Every module the enabled features contribute, in composer order. */
+declare function composeFeatures(ctx: CompositionContext): DynamicModule[];
+
+/**
+ * Mounted on purpose and deliberately not re-exported.
+ *
+ * Declared here rather than left as an absence, because the guard in
+ * `tests/platform-composition.test.js` otherwise reports it every time and the
+ * next person has to re-derive whether it is a bug.
+ *
+ * `PublicCatalogModule` is a controller and one token, `FEATURE_UI_REGISTRY` —
+ * which the APP supplies through `catalog: { featureUiRegistry }` rather than
+ * injects. Re-exporting it would also collide with the identically named token
+ * from `billing`, which means something else (see CONTRIBUTING, "One bundle,
+ * many entries").
+ */
+declare const MOUNTED_BUT_NOT_EXPORTED: readonly string[];
+/** The `exports` of the assembled module, plus whatever it provides itself. */
+declare function composeModuleExports(ctx: CompositionContext, ownExports: NonNullable<DynamicModule['exports']>): NonNullable<DynamicModule['exports']>;
+
+/** Everything a rule may look at: the options as given, the adapters as resolved. */
+interface PlatformConfiguration {
+    readonly options: SaasPlatformModuleOptions;
+    /** After the bundle slices and the explicit entries have been merged. */
+    readonly adapters: SaasPlatformAdapters;
+}
+interface PlatformRule {
+    /** Stable id — `<area>.<what-it-requires>`. Appears in the boot error. */
+    readonly id: string;
+    /** Whether this rule has anything to say about this configuration. */
+    readonly when: (c: PlatformConfiguration) => boolean;
+    /** True when the configuration satisfies it. */
+    readonly assert: (c: PlatformConfiguration) => boolean;
+    /**
+     * What is wrong and what to do about it.
+     *
+     * A function only where it has to be: several of these name which of a set
+     * is missing, and "adapters are missing: subscriptionRepository,
+     * transactionRunner" is worth more than "adapters are missing". The rest
+     * are the same sentence every time, and a closure that ignores its argument
+     * is one more thing a reader has to check for.
+     */
+    readonly message: string | ((c: PlatformConfiguration) => string);
+    /**
+     * Where the option is documented.
+     *
+     * Derived from the id rather than written beside it — see `docsUrlFor`.
+     */
+    readonly docs: string;
+    /**
+     * The typed error this rule threw before the table existed, when it has
+     * one.
+     *
+     * Used only when this rule is the ONLY violation — and that is not a
+     * compromise, it is the exact set of cases where the typed error was ever
+     * observable. A configuration with two problems used to throw whichever
+     * check ran first and stop, so nothing could catch the second one by type
+     * either. Where a consumer could see `PersistenceCapabilityError`, it still
+     * sees it; where it could not, it now gets the full list instead of one
+     * arbitrary problem.
+     */
+    readonly error?: (c: PlatformConfiguration) => Error;
+}
+/**
+ * GitHub's heading slug for `text`: lowercased, punctuation dropped, spaces
+ * hyphenated.
+ *
+ * Written out because the anchor has to match a heading nobody types — the
+ * page is generated. `tests/options-reference-is-generated.test.js` asserts
+ * every rule's anchor is a heading in the file, so a wrong slug fails the build
+ * rather than producing a link that lands at the top of the page.
+ */
+declare const headingSlug: (text: string) => string;
+/**
+ * The documentation link for a rule.
+ *
+ * Derived from the id, so the two cannot disagree. They did, on the first
+ * attempt: eleven hand-written anchors against headings the generator names
+ * after the ids, and every one of them landed at the top of the page.
+ */
+declare const docsUrlFor: (id: string) => string;
+declare const PLATFORM_RULES: readonly PlatformRule[];
+
+interface PlatformViolation {
+    readonly id: string;
+    readonly message: string;
+    readonly docs: string;
+}
+/** Every rule that applies to this configuration and is not satisfied by it. */
+declare function findViolations(configuration: PlatformConfiguration, rules?: readonly PlatformRule[]): PlatformViolation[];
+/**
+ * The error a misconfigured application boots into.
+ *
+ * Carries the violations as data as well as prose: a consumer's own boot
+ * diagnostics can group them, and the rule ids are stable enough to assert on.
+ */
+declare class SaaSiCatConfigurationError extends Error {
+    readonly violations: readonly PlatformViolation[];
+    constructor(violations: readonly PlatformViolation[]);
+}
+/**
+ * Throws once, naming every problem, or returns.
+ *
+ * A single violation from a rule that owns a typed error raises that error
+ * instead of the aggregate — see `PlatformRule.error` for why that is the
+ * whole of the previous behaviour rather than part of it.
+ */
+declare function assertConfiguration(configuration: PlatformConfiguration, rules?: readonly PlatformRule[]): void;
+
 /**
  * Standard `tenantId → planId` resolver backed by the canonical subscription
  * repository. This removes the identical resolver class most applications
@@ -48,22 +196,56 @@ declare class QuotaProvidersUsageSnapshot implements UsageSnapshotPort {
     snapshot(tenantId: string): Promise<Record<string, number>>;
 }
 
-declare class FeatureGuardCoverageCheck implements OnApplicationBootstrap {
+/** What the module knows at composition time and this check cannot see. */
+interface EnforcementChainState {
+    /**
+     * Whether anything can enforce `@RequireFeature`.
+     *
+     * True on the static path, and also on the V3 path, where the application
+     * binds `FeatureGuard` from `@saasicat/nest/billing` itself.
+     */
+    readonly featureEnforcementActive: boolean;
+    /**
+     * Whether anything can enforce `@EnforceQuota`.
+     *
+     * Narrower than the field above, and the two were one field until an app
+     * on the V3 path with no plan resolver booted with every quota unenforced:
+     * `EnforceQuotaInterceptor` comes from `composeEnforcementRuntime`, which
+     * registers nothing unless a plan resolver exists. A flag named for
+     * "entitlement" answered a question about features and was read as an
+     * answer about quotas.
+     */
+    readonly quotaEnforcementActive: boolean;
+    /** Whether the platform bound its own global feature guard. */
+    readonly globalGuardBound: boolean;
+    /**
+     * Whether `globalFeatureGuard: false` is what unbound it.
+     *
+     * Distinct from `globalGuardBound` because the two have different causes
+     * and the message has to say the true one. On the V3 entitlement path the
+     * platform binds no global guard either — it never registers the static
+     * stack — and naming an option the application did not set sends the reader
+     * to look for a line that is not in their file.
+     */
+    readonly globalGuardOptedOut: boolean;
+}
+declare const ENFORCEMENT_CHAIN_STATE_TOKEN: unique symbol;
+declare class EnforcementChainCheck implements OnApplicationBootstrap {
     private readonly discoveryService;
     private readonly metadataScanner;
-    private readonly logger;
-    constructor(discoveryService: DiscoveryService, metadataScanner: MetadataScanner);
+    private readonly state;
+    constructor(discoveryService: DiscoveryService, metadataScanner: MetadataScanner, state?: EnforcementChainState);
     onApplicationBootstrap(): void;
     /**
-     * Annotated handlers whose own guards and whose controller's guards contain
-     * no recognisable feature guard.
+     * Every route carrying an enforcement annotation, with whether a
+     * recognisable feature guard covers it.
      *
      * Deliberately conservative in one direction only: an unrecognised wrapper
      * is reported (and the message says so) rather than assumed safe, because
      * the named route is cheap to check. The reverse — staying silent about a
      * route with no guard at all — is the failure this exists to prevent.
      */
-    private findUncoveredRoutes;
+    private findAnnotatedRoutes;
 }
 
 interface TenantNavItem {
@@ -119,4 +301,4 @@ declare class TenantManifestService {
     getManifest(tenantId: string): Promise<TenantManifest>;
 }
 
-export { FeatureGuardCoverageCheck, PlanResolverPort, QuotaProvidersUsageSnapshot, StaticEntitlementService, SubscriptionPlanResolver, type TenantManifest, TenantManifestService, type TenantNavItem };
+export { type Composer, type CompositionContext, ENFORCEMENT_CHAIN_STATE_TOKEN, EnforcementChainCheck, type EnforcementChainState, FEATURE_COMPOSERS, MOUNTED_BUT_NOT_EXPORTED, PLATFORM_RULES, PlanResolverPort, type PlatformConfiguration, type PlatformRule, type PlatformViolation, QuotaProvidersUsageSnapshot, SaaSiCatConfigurationError, SaasPlatformAdapters, SaasPlatformModuleOptions, StaticEntitlementService, SubscriptionPlanResolver, type TenantManifest, TenantManifestService, type TenantNavItem, assertConfiguration, composeFeatures, composeModuleExports, docsUrlFor, findViolations, headingSlug };

package/dist/platform/index.d.ts

@@ -1,31 +1,179 @@
-import { p as PlanResolverPort } from '../saas-platform.module-D1mUZPrz.js';
-export { P as PLAN_RESOLVER_PORT_TOKEN, S as SaaSiCatModule, a as SaasPlatformAdapters, b as SaasPlatformAdminResourcesOptions, c as SaasPlatformAdminStatsOptions, d as SaasPlatformCatalogOptions, e as SaasPlatformCheckoutOfferOptions, S as SaasPlatformModule, f as SaasPlatformModuleOptions, g as SaasPlatformPromoCodesOptions, h as SaasPlatformSetupOptions, i as SaasPlatformSubscriptionBundlesOptions, j as SaasPlatformSubscriptionContractOptions, k as SaasPlatformTenantAuthGuards, l as SaasPlatformTenantBillingOptions, m as SetupModule, n as SetupModuleOptions, o as StaticPlanResolver, T as TenantManifestControllerOptions, q as buildTenantManifestController } from '../saas-platform.module-D1mUZPrz.js';
-export { a as SAASICAT_PUBLIC_ROUTE_KEY, d as SaaSiCatPublicRoute, S as SetupService, f as defineSaaSiCat, i as isSaaSiCatPublicRoute } from '../define-saasicat-BK6RRWWG.js';
-import { SubscriptionRepository, UsageSnapshotPort, QuotaProvider } from '@saasicat/types';
-import { S as StaticEntitlementService } from '../enforce-quota.interceptor-B9QueAFf.js';
-export { E as EnforceQuotaInterceptor, Q as QUOTA_PROVIDERS_TOKEN, b as STATIC_FEATURE_GUARD_CONFIG_TOKEN, c as StaticEntitlementSnapshot, a as StaticFeatureGuard, d as StaticFeatureGuardConfig } from '../enforce-quota.interceptor-B9QueAFf.js';
-import { OnApplicationBootstrap } from '@nestjs/common';
+export { a as SAASICAT_PUBLIC_ROUTE_KEY, d as SaaSiCatModule, e as SaaSiCatPublicRoute, d as SaasPlatformModule, S as SetupService, g as defineSaaSiCat, i as isSaaSiCatPublicRoute } from '../define-saasicat-3ois8t8s.js';
+import { CanActivate, DynamicModule, OnApplicationBootstrap } from '@nestjs/common';
+import { SaasicatPersistenceAdapter, SubscriptionUsagePort, SubscriptionRepository, UsageSnapshotPort, QuotaProvider } from '@saasicat/types';
+import { P as ProviderSpec } from '../di-CcNeq9v-.js';
+import { b as DiscoveryAppInfo } from '../discovery.scanner-DLgEvuoy.js';
+export { c as DiscoveryScanner } from '../discovery.scanner-DLgEvuoy.js';
+import { e as SaasPlatformModuleOptions, S as SaasPlatformAdapters, o as PlanResolverPort } from '../module-options-ByJL7FZm.js';
+export { P as PLAN_RESOLVER_PORT_TOKEN, a as SaasPlatformAdminResourcesOptions, b as SaasPlatformAdminStatsOptions, c as SaasPlatformCatalogOptions, d as SaasPlatformCheckoutOfferOptions, f as SaasPlatformPromoCodesOptions, g as SaasPlatformSetupOptions, h as SaasPlatformSubscriptionBundlesOptions, i as SaasPlatformSubscriptionContractOptions, j as SaasPlatformTenantAuthGuards, k as SaasPlatformTenantBillingOptions, l as SetupModule, m as SetupModuleOptions, n as StaticPlanResolver, T as TenantManifestControllerOptions, p as buildTenantManifestController } from '../module-options-ByJL7FZm.js';
+import { S as StaticEntitlementService } from '../enforce-quota.interceptor-CYDNvAQz.js';
+export { E as EnforceQuotaInterceptor, Q as QUOTA_PROVIDERS_TOKEN, b as STATIC_FEATURE_GUARD_CONFIG_TOKEN, c as StaticEntitlementSnapshot, a as StaticFeatureGuard, d as StaticFeatureGuardConfig } from '../enforce-quota.interceptor-CYDNvAQz.js';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 export { A as AdminBypassRlsInterceptor, a as AdminManifestModule, b as AdminManifestModuleOptions, c as AdminManifestService, d as AdminModule, e as AdminModuleOptions, f as AdminStatsService, M as MfaGuard, h as MfaService, S as SuperAdminGuard } from '../admin-stats.service-Db2exT_d.js';
 export { A as AdminAuditService } from '../admin-audit.service-9IqXMlZm.js';
 export { e as AdminResourcesService, f as AdminStatsModule, g as AdminStatsModuleOptions } from '../admin-resources.module-BY5r_1MG.js';
 export { c as EntitlementService } from '../aggregation-DP5zfKbU.js';
-export { d as ComposedTenantAuthGuard, P as PendingPlanMaterializationService, h as PlanChangePreviewService, r as SubscriptionBundlePreviewService, s as SubscriptionBundlesService, T as TenantAdminGuard, t as TenantBillingController } from '../tenant-billing.controller-BSlpFqVA.js';
+export { d as ComposedTenantAuthGuard, P as PendingPlanMaterializationService, h as PlanChangePreviewService, r as SubscriptionBundlePreviewService, s as SubscriptionBundlesService, T as TenantAdminGuard, t as TenantBillingController } from '../tenant-billing.controller-CYYK0CpT.js';
 export { B as BundlesService, C as CatalogEntriesService, M as MarketingProjectionsService, b as MarketingSettingsService, P as PlanVersionsService, c as PlansService, d as PromotionsService, e as PublicMarketingCatalogService } from '../plan-versions.service-B-YoE4SZ.js';
-export { c as DiscoveryScanner } from '../discovery.scanner-DLgEvuoy.js';
 export { P as PromoCodeRateLimitGuard } from '../rate-limit.guard-dntqAlfZ.js';
 export { g as PromoCodesService } from '../service-D48clObR.js';
 export { a as CheckoutOfferModule, b as CheckoutOfferModuleOptions } from '../checkout-offer.module-Ca3_TieR.js';
 export { C as CheckoutOfferService } from '../checkout-offer.service-BX51dljL.js';
 export { S as SubscriptionContractModule, a as SubscriptionContractModuleOptions } from '../subscription-contract.module-edyhBr4n.js';
 export { S as SubscriptionContractService } from '../subscription-contract.service--cm47ZJJ.js';
-import '../di-CcNeq9v-.js';
+import '../tenant-billing.module-B0stLoJn.js';
+import '../catalog.module-CQr1FpkI.js';
 import '../plan-resolution-CFCoUkrE.js';
 import '../module-BE17XFLg.js';
-import '../catalog.module-CQr1FpkI.js';
-import '../subscription-bundles.module-BDbODWvA.js';
 import 'rxjs';
 
+/**
+ * What `tenantBilling` resolved and its two dependants need.
+ *
+ * Mutable, and the only mutable thing here: `composeTenantBilling` writes it,
+ * `composeSubscriptionBundles` and the entitlement runtime read it. A composer
+ * that runs before tenant billing sees the initial values, which is correct —
+ * there was no tenant billing to resolve anything.
+ */
+interface SharedTenantBinding {
+    /** Normalised `authGuards`, shared with the bundle controller. */
+    authGuards?: ProviderSpec<ReadonlyArray<CanActivate>>;
+    /** The usage port both controllers report against. */
+    subscriptionUsagePort?: ProviderSpec<SubscriptionUsagePort>;
+    /**
+     * Whether the tenant-billing module already registered the app's quota
+     * providers.
+     *
+     * It registers them as its own providers and exports, so the entitlement
+     * runtime must not register them a second time — two instances of a
+     * `QuotaProvider` are two counters over the same rows.
+     */
+    quotaProvidersHostedByTenantBilling: boolean;
+}
+interface CompositionContext {
+    readonly options: SaasPlatformModuleOptions;
+    /** After the bundle slices and the explicit entries have been merged. */
+    readonly adapters: SaasPlatformAdapters;
+    readonly persistence: SaasicatPersistenceAdapter | undefined;
+    /** App key and version, for discovery and the public catalogue. */
+    readonly appInfo: DiscoveryAppInfo;
+    /** Entitlement is needed directly, or by tenant billing / bundles. */
+    readonly requiresFullEntitlement: boolean;
+    readonly shared: SharedTenantBinding;
+}
+
+/** One feature's contribution: the modules it adds, or none. */
+type Composer = (ctx: CompositionContext) => DynamicModule[];
+declare const FEATURE_COMPOSERS: readonly Composer[];
+/** Every module the enabled features contribute, in composer order. */
+declare function composeFeatures(ctx: CompositionContext): DynamicModule[];
+
+/**
+ * Mounted on purpose and deliberately not re-exported.
+ *
+ * Declared here rather than left as an absence, because the guard in
+ * `tests/platform-composition.test.js` otherwise reports it every time and the
+ * next person has to re-derive whether it is a bug.
+ *
+ * `PublicCatalogModule` is a controller and one token, `FEATURE_UI_REGISTRY` —
+ * which the APP supplies through `catalog: { featureUiRegistry }` rather than
+ * injects. Re-exporting it would also collide with the identically named token
+ * from `billing`, which means something else (see CONTRIBUTING, "One bundle,
+ * many entries").
+ */
+declare const MOUNTED_BUT_NOT_EXPORTED: readonly string[];
+/** The `exports` of the assembled module, plus whatever it provides itself. */
+declare function composeModuleExports(ctx: CompositionContext, ownExports: NonNullable<DynamicModule['exports']>): NonNullable<DynamicModule['exports']>;
+
+/** Everything a rule may look at: the options as given, the adapters as resolved. */
+interface PlatformConfiguration {
+    readonly options: SaasPlatformModuleOptions;
+    /** After the bundle slices and the explicit entries have been merged. */
+    readonly adapters: SaasPlatformAdapters;
+}
+interface PlatformRule {
+    /** Stable id — `<area>.<what-it-requires>`. Appears in the boot error. */
+    readonly id: string;
+    /** Whether this rule has anything to say about this configuration. */
+    readonly when: (c: PlatformConfiguration) => boolean;
+    /** True when the configuration satisfies it. */
+    readonly assert: (c: PlatformConfiguration) => boolean;
+    /**
+     * What is wrong and what to do about it.
+     *
+     * A function only where it has to be: several of these name which of a set
+     * is missing, and "adapters are missing: subscriptionRepository,
+     * transactionRunner" is worth more than "adapters are missing". The rest
+     * are the same sentence every time, and a closure that ignores its argument
+     * is one more thing a reader has to check for.
+     */
+    readonly message: string | ((c: PlatformConfiguration) => string);
+    /**
+     * Where the option is documented.
+     *
+     * Derived from the id rather than written beside it — see `docsUrlFor`.
+     */
+    readonly docs: string;
+    /**
+     * The typed error this rule threw before the table existed, when it has
+     * one.
+     *
+     * Used only when this rule is the ONLY violation — and that is not a
+     * compromise, it is the exact set of cases where the typed error was ever
+     * observable. A configuration with two problems used to throw whichever
+     * check ran first and stop, so nothing could catch the second one by type
+     * either. Where a consumer could see `PersistenceCapabilityError`, it still
+     * sees it; where it could not, it now gets the full list instead of one
+     * arbitrary problem.
+     */
+    readonly error?: (c: PlatformConfiguration) => Error;
+}
+/**
+ * GitHub's heading slug for `text`: lowercased, punctuation dropped, spaces
+ * hyphenated.
+ *
+ * Written out because the anchor has to match a heading nobody types — the
+ * page is generated. `tests/options-reference-is-generated.test.js` asserts
+ * every rule's anchor is a heading in the file, so a wrong slug fails the build
+ * rather than producing a link that lands at the top of the page.
+ */
+declare const headingSlug: (text: string) => string;
+/**
+ * The documentation link for a rule.
+ *
+ * Derived from the id, so the two cannot disagree. They did, on the first
+ * attempt: eleven hand-written anchors against headings the generator names
+ * after the ids, and every one of them landed at the top of the page.
+ */
+declare const docsUrlFor: (id: string) => string;
+declare const PLATFORM_RULES: readonly PlatformRule[];
+
+interface PlatformViolation {
+    readonly id: string;
+    readonly message: string;
+    readonly docs: string;
+}
+/** Every rule that applies to this configuration and is not satisfied by it. */
+declare function findViolations(configuration: PlatformConfiguration, rules?: readonly PlatformRule[]): PlatformViolation[];
+/**
+ * The error a misconfigured application boots into.
+ *
+ * Carries the violations as data as well as prose: a consumer's own boot
+ * diagnostics can group them, and the rule ids are stable enough to assert on.
+ */
+declare class SaaSiCatConfigurationError extends Error {
+    readonly violations: readonly PlatformViolation[];
+    constructor(violations: readonly PlatformViolation[]);
+}
+/**
+ * Throws once, naming every problem, or returns.
+ *
+ * A single violation from a rule that owns a typed error raises that error
+ * instead of the aggregate — see `PlatformRule.error` for why that is the
+ * whole of the previous behaviour rather than part of it.
+ */
+declare function assertConfiguration(configuration: PlatformConfiguration, rules?: readonly PlatformRule[]): void;
+
 /**
  * Standard `tenantId → planId` resolver backed by the canonical subscription
  * repository. This removes the identical resolver class most applications
@@ -48,22 +196,56 @@ declare class QuotaProvidersUsageSnapshot implements UsageSnapshotPort {
     snapshot(tenantId: string): Promise<Record<string, number>>;
 }
 
-declare class FeatureGuardCoverageCheck implements OnApplicationBootstrap {
+/** What the module knows at composition time and this check cannot see. */
+interface EnforcementChainState {
+    /**
+     * Whether anything can enforce `@RequireFeature`.
+     *
+     * True on the static path, and also on the V3 path, where the application
+     * binds `FeatureGuard` from `@saasicat/nest/billing` itself.
+     */
+    readonly featureEnforcementActive: boolean;
+    /**
+     * Whether anything can enforce `@EnforceQuota`.
+     *
+     * Narrower than the field above, and the two were one field until an app
+     * on the V3 path with no plan resolver booted with every quota unenforced:
+     * `EnforceQuotaInterceptor` comes from `composeEnforcementRuntime`, which
+     * registers nothing unless a plan resolver exists. A flag named for
+     * "entitlement" answered a question about features and was read as an
+     * answer about quotas.
+     */
+    readonly quotaEnforcementActive: boolean;
+    /** Whether the platform bound its own global feature guard. */
+    readonly globalGuardBound: boolean;
+    /**
+     * Whether `globalFeatureGuard: false` is what unbound it.
+     *
+     * Distinct from `globalGuardBound` because the two have different causes
+     * and the message has to say the true one. On the V3 entitlement path the
+     * platform binds no global guard either — it never registers the static
+     * stack — and naming an option the application did not set sends the reader
+     * to look for a line that is not in their file.
+     */
+    readonly globalGuardOptedOut: boolean;
+}
+declare const ENFORCEMENT_CHAIN_STATE_TOKEN: unique symbol;
+declare class EnforcementChainCheck implements OnApplicationBootstrap {
     private readonly discoveryService;
     private readonly metadataScanner;
-    private readonly logger;
-    constructor(discoveryService: DiscoveryService, metadataScanner: MetadataScanner);
+    private readonly state;
+    constructor(discoveryService: DiscoveryService, metadataScanner: MetadataScanner, state?: EnforcementChainState);
     onApplicationBootstrap(): void;
     /**
-     * Annotated handlers whose own guards and whose controller's guards contain
-     * no recognisable feature guard.
+     * Every route carrying an enforcement annotation, with whether a
+     * recognisable feature guard covers it.
      *
      * Deliberately conservative in one direction only: an unrecognised wrapper
      * is reported (and the message says so) rather than assumed safe, because
      * the named route is cheap to check. The reverse — staying silent about a
      * route with no guard at all — is the failure this exists to prevent.
      */
-    private findUncoveredRoutes;
+    private findAnnotatedRoutes;
 }
 
 interface TenantNavItem {
@@ -119,4 +301,4 @@ declare class TenantManifestService {
     getManifest(tenantId: string): Promise<TenantManifest>;
 }
 
-export { FeatureGuardCoverageCheck, PlanResolverPort, QuotaProvidersUsageSnapshot, StaticEntitlementService, SubscriptionPlanResolver, type TenantManifest, TenantManifestService, type TenantNavItem };
+export { type Composer, type CompositionContext, ENFORCEMENT_CHAIN_STATE_TOKEN, EnforcementChainCheck, type EnforcementChainState, FEATURE_COMPOSERS, MOUNTED_BUT_NOT_EXPORTED, PLATFORM_RULES, PlanResolverPort, type PlatformConfiguration, type PlatformRule, type PlatformViolation, QuotaProvidersUsageSnapshot, SaaSiCatConfigurationError, SaasPlatformAdapters, SaasPlatformModuleOptions, StaticEntitlementService, SubscriptionPlanResolver, type TenantManifest, TenantManifestService, type TenantNavItem, assertConfiguration, composeFeatures, composeModuleExports, docsUrlFor, findViolations, headingSlug };

package/dist/platform/index.js

@@ -1,13 +1,18 @@
 import {
   defineSaaSiCat
-} from "../chunk-FY4EJTV4.js";
+} from "../chunk-OYNHOY45.js";
 import {
+  ENFORCEMENT_CHAIN_STATE_TOKEN,
   EnforceQuotaInterceptor,
-  FeatureGuardCoverageCheck,
+  EnforcementChainCheck,
+  FEATURE_COMPOSERS,
+  MOUNTED_BUT_NOT_EXPORTED,
   PLAN_RESOLVER_PORT_TOKEN,
+  PLATFORM_RULES,
   QUOTA_PROVIDERS_TOKEN,
   QuotaProvidersUsageSnapshot,
   STATIC_FEATURE_GUARD_CONFIG_TOKEN,
+  SaaSiCatConfigurationError,
   SaasPlatformModule,
   SetupModule,
   SetupService,
@@ -16,11 +21,20 @@ import {
   StaticPlanResolver,
   SubscriptionPlanResolver,
   TenantManifestService,
-  buildTenantManifestController
-} from "../chunk-TCBYOFAC.js";
+  assertConfiguration,
+  buildTenantManifestController,
+  composeFeatures,
+  composeModuleExports,
+  docsUrlFor,
+  findViolations,
+  headingSlug
+} from "../chunk-EHKMPP6J.js";
 import {
   PromoCodeRateLimitGuard
 } from "../chunk-B6IWLV7R.js";
+import {
+  SubscriptionContractModule
+} from "../chunk-3E6ONOMG.js";
 import {
   AdminBypassRlsInterceptor,
   AdminManifestModule,
@@ -41,14 +55,13 @@ import {
   SubscriptionBundlesService,
   TenantAdminGuard,
   TenantBillingController
-} from "../chunk-YWDLYOFN.js";
+} from "../chunk-UHD6FJBQ.js";
 import {
   PromoCodesService
 } from "../chunk-37HEKVDH.js";
 import {
-  SubscriptionContractModule,
   SubscriptionContractService
-} from "../chunk-B7NRY2LV.js";
+} from "../chunk-CJFAOD7K.js";
 import {
   BundlesService,
   CatalogEntriesService,
@@ -77,9 +90,10 @@ import "../chunk-6WL6VQ7Z.js";
 import {
   DiscoveryScanner
 } from "../chunk-5ZXBXYXU.js";
+import "../chunk-H4DOTO7S.js";
 import {
   EntitlementService
-} from "../chunk-NNNXXUPT.js";
+} from "../chunk-F4B2NJUZ.js";
 import "../chunk-DQKCK7DX.js";
 import "../chunk-NYLON2VC.js";
 import "../chunk-EBJJNTW6.js";
@@ -103,14 +117,18 @@ export {
   CheckoutOfferService,
   ComposedTenantAuthGuard,
   DiscoveryScanner,
+  ENFORCEMENT_CHAIN_STATE_TOKEN,
   EnforceQuotaInterceptor,
+  EnforcementChainCheck,
   EntitlementService,
-  FeatureGuardCoverageCheck,
+  FEATURE_COMPOSERS,
+  MOUNTED_BUT_NOT_EXPORTED,
   MarketingProjectionsService,
   MarketingSettingsService,
   MfaGuard,
   MfaService,
   PLAN_RESOLVER_PORT_TOKEN,
+  PLATFORM_RULES,
   PendingPlanMaterializationService,
   PlanChangePreviewService,
   PlanVersionsService,
@@ -123,6 +141,7 @@ export {
   QuotaProvidersUsageSnapshot,
   SAASICAT_PUBLIC_ROUTE_KEY,
   STATIC_FEATURE_GUARD_CONFIG_TOKEN,
+  SaaSiCatConfigurationError,
   SaasPlatformModule as SaaSiCatModule,
   SaaSiCatPublicRoute,
   SaasPlatformModule,
@@ -140,7 +159,13 @@ export {
   TenantAdminGuard,
   TenantBillingController,
   TenantManifestService,
+  assertConfiguration,
   buildTenantManifestController,
+  composeFeatures,
+  composeModuleExports,
   defineSaaSiCat,
+  docsUrlFor,
+  findViolations,
+  headingSlug,
   isSaaSiCatPublicRoute
 };

package/dist/subscription-contract/index.js

@@ -1,10 +1,13 @@
+import "../chunk-2SLTRKXC.js";
+import {
+  SubscriptionContractModule
+} from "../chunk-3E6ONOMG.js";
 import {
-  SubscriptionContractModule,
   SubscriptionContractService,
   contractLineItemToInvoiceLineItem,
   sortContractLineItemsForInvoice,
   subscriptionContractToInvoiceSnapshot
-} from "../chunk-B7NRY2LV.js";
+} from "../chunk-CJFAOD7K.js";
 import "../chunk-BSK6YBLI.js";
 import {
   SUBSCRIPTION_CONTRACT_REPOSITORY_TOKEN