@wildo-ai/saas-backend-lib 1.1.2 → 1.1.3

package/dist/esm/runtime/services/start-application.backend.service.js

@@ -13,7 +13,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import 'reflect-metadata';
 import { injectable, inject, optional } from 'inversify';
 import { runDataSeedingApplicationBootstrap } from '../../data-seeding/services/data-seed-application-bootstrap.backend.js';
-import { ErrorType, ErrorCustomMessageReference, FeatureUnavailabilityBehavior, FeatureUnavailabilityReason, BILLING_SCOPES, ActivationCriterionType, ResourcePrimaryScope, CoreResourceType, CoreResourceOperation, CORE_APP_ROLES, RelationshipNature, validateRequiredForeignKeyFillability, ForeignKeyFillabilityViolationSeverity, validateCompositionSeedability, validateCompositionCascadeDeletability, ChildLifecycleStrategy, EngineCapability } from '@wildo-ai/saas-models';
+import { AdministrativeContinuityBreachDetection, ErrorType, ErrorCustomMessageReference, FeatureUnavailabilityBehavior, FeatureUnavailabilityReason, BILLING_SCOPES, ActivationCriterionType, ResourcePrimaryScope, CoreResourceType, CoreResourceOperation, CORE_APP_ROLES, RelationshipNature, validateRequiredForeignKeyFillability, ForeignKeyFillabilityViolationSeverity, validateCompositionSeedability, validateCompositionCascadeDeletability, ChildLifecycleStrategy, EngineCapability } from '@wildo-ai/saas-models';
 import { collectApplicationResourcesWithNoPersonalDataDeclaration } from '@wildo-ai/saas-models';
 import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
 import { LoggerService } from '../../monitoring/logger/services/logger.service.js';
@@ -23,10 +23,12 @@ import { ADMINISTRATIVELY_USABLE_ORGANIZATION_MEMBER_STATUSES, ADMINISTRATIVELY_
 import { enumeratePrivilegedAccessPopulation } from '../../security/authorizations/privileged-access-review.backend.utils.js';
 import { ApplicationRuntimeProfile, resolveApplicationRuntimeProfileBootAssertions } from '../../config/bootstrap/application-runtime-profile.backend.js';
 import { AppConfigurationService } from '../../config/services/app-configuration.backend.service.js';
+import { describeAbuseThrottleRelaxation } from '../../errors/utils/rate-limit-environment-relaxation.backend.utils.js';
 import { ApplicationStartupConfigValidatorService } from '../../config/services/application-startup-config-validator.backend.service.js';
 import { ObservabilityBackendService } from '../../monitoring/observability/services/observability.backend.service.js';
 import { ResourcesRegistryBackendService } from '../../resources/services/resources-registry.backend.service.js';
 import { BackendProviderRegistryBackendService } from '../../external-providers/services/backend-provider-registry.backend.service.js';
+import { resolveBackendProviderRegistry } from '../../external-providers/services/backend-provider-loader.backend.service.js';
 import { ExternalProvidersRegistryBackendService } from '../../external-providers/services/external-providers-registry.backend.service.js';
 import { FeatureDefinitionRegistryBackendService } from '../../features/services/feature-definition-registry.backend.service.js';
 import { MilestoneDefinitionRegistryBackendService } from '../../guidance/services/milestone-definition-registry.backend.service.js';
@@ -56,7 +58,11 @@ import { createFilesCleanupBatch } from '../../files/batches/files-cleanup.batch
 import { createConsumableTokensCleanupBatch } from '../../security/consumable-tokens/batches/consumable-tokens-cleanup.batch.backend.service.js';
 import { createA2AAbandonedTaskSweepBatch } from '../../flows-actors/a2a/batches/a2a-abandoned-task-sweep.batch.backend.service.js';
 import { createAnonymousSessionCleanupBatch } from '../../security/authentications/batches/anonymous-session-cleanup.batch.backend.service.js';
+import { createChildLifecycleTeardownBatch } from '../../base-classes/services/batches/child-lifecycle-teardown.batch.backend.service.js';
 import { createOrganizationMemberInvitationSweepBatch } from '../../organizations/batches/organization-member-invitation-sweep.batch.backend.service.js';
+import { createCredentialExpirySweepBatch } from '../../base-classes/services/batches/credential-expiry-sweep.batch.backend.service.js';
+import { createUsageFlushBatch } from '../../billing/batches/usage-flush.batch.backend.service.js';
+import { createBillingReconciliationBatch } from '../../billing/batches/billing-reconciliation.batch.backend.service.js';
 import { createSuspensionReactivationSweepBatch } from '../../base-classes/services/batches/suspension-reactivation-sweep.batch.backend.service.js';
 import { createResourceRetentionSweepBatch } from '../../base-classes/services/batches/resource-retention-sweep.batch.backend.service.js';
 import { createOrganizationPurgeBatch } from '../../organizations/batches/organization-purge.batch.backend.service.js';
@@ -68,11 +74,11 @@ import { siemWebhookDeliveryBatchService } from '../../compliance/audit-trails/b
 import { immudbAuditReconcileBatchService } from '../../compliance/audit-trails/batches/immudb-audit-reconcile.batch.backend.service.js';
 import { auditLogsArchiveBatchService } from '../../compliance/audit-trails/batches/audit-logs-archive.batch.backend.service.js';
 import { shouldWarnLayer2AuditProviderInactive } from '../../compliance/audit-trails/utils/layer2-audit-provider-boot-diagnostic.backend.utils.js';
-import { StripeStandardBillingProvider } from '../../billing/services/stripe-standard-billing-provider.backend.service.js';
+import { listSupportedBillingSdkPackages, resolveBillingAdapterFactory } from '../../billing/services/billing-adapter-registry.backend.js';
 // Internal callers go through the path alias (the `@wildo-ai/saas-backend-lib/custom-batch-manifests`
 // subpath export exists for external spec-layer consumers; self-imports through the public
 // package name are not wired in this workspace's tsconfig path map).
-import { ANONYMOUS_SESSION_CLEANUP_BATCH_REF, ORGANIZATION_MEMBER_INVITATION_SWEEP_BATCH_REF, SUSPENSION_REACTIVATION_SWEEP_BATCH_REF, JOB_EXECUTIONS_RETENTION_SWEEP_BATCH_REF, JOB_PAYLOAD_STORAGE_RETENTION_SWEEP_BATCH_REF, ENGINE_JOB_EXECUTIONS_RETENTION_SWEEP_MANIFEST, ENGINE_JOB_PAYLOAD_STORAGE_RETENTION_SWEEP_MANIFEST, ORGANIZATION_PURGE_BATCH_REF, CONSUMABLE_TOKENS_CLEANUP_BATCH_REF, A2A_ABANDONED_TASK_SWEEP_BATCH_REF, DATA_SEEDING_RUN_CLEANUP_BATCH_REF, DATA_SEEDING_SCHEDULED_RERUN_BATCH_REF, DATA_SEEDING_SCHEDULED_RERUN_DEFAULT_CRON, EXTERNAL_DATA_PIPELINE_SCHEDULED_RUN_BATCH_REF, DORMANCY_DETECTION_BATCH_REF, EMAIL_BATCH_SEND_BATCH_REF, FILES_CLEANUP_BATCH_REF, M2M_WEBHOOK_DELIVERY_BATCH_REF, A2A_PUSH_DELIVERY_BATCH_REF, SIEM_WEBHOOK_DELIVERY_BATCH_REF, IMMUDB_AUDIT_RECONCILE_BATCH_REF, AUDIT_LOGS_ARCHIVE_BATCH_REF, RAG_RECONCILIATION_SWEEP_BATCH_REF, RAG_EMBEDDING_DRAIN_BATCH_REF, } from '../../base-classes/services/batches/engine-custom-batch-manifests.js';
+import { ANONYMOUS_SESSION_CLEANUP_BATCH_REF, ORGANIZATION_MEMBER_INVITATION_SWEEP_BATCH_REF, CREDENTIAL_EXPIRY_SWEEP_BATCH_REF, USAGE_FLUSH_BATCH_REF, BILLING_RECONCILIATION_BATCH_REF, SUSPENSION_REACTIVATION_SWEEP_BATCH_REF, JOB_EXECUTIONS_RETENTION_SWEEP_BATCH_REF, JOB_PAYLOAD_STORAGE_RETENTION_SWEEP_BATCH_REF, ENGINE_JOB_EXECUTIONS_RETENTION_SWEEP_MANIFEST, ENGINE_JOB_PAYLOAD_STORAGE_RETENTION_SWEEP_MANIFEST, ORGANIZATION_PURGE_BATCH_REF, CONSUMABLE_TOKENS_CLEANUP_BATCH_REF, A2A_ABANDONED_TASK_SWEEP_BATCH_REF, DATA_SEEDING_RUN_CLEANUP_BATCH_REF, DATA_SEEDING_SCHEDULED_RERUN_BATCH_REF, DATA_SEEDING_SCHEDULED_RERUN_DEFAULT_CRON, EXTERNAL_DATA_PIPELINE_SCHEDULED_RUN_BATCH_REF, DORMANCY_DETECTION_BATCH_REF, CHILD_LIFECYCLE_TEARDOWN_BATCH_REF, EMAIL_BATCH_SEND_BATCH_REF, FILES_CLEANUP_BATCH_REF, M2M_WEBHOOK_DELIVERY_BATCH_REF, A2A_PUSH_DELIVERY_BATCH_REF, SIEM_WEBHOOK_DELIVERY_BATCH_REF, IMMUDB_AUDIT_RECONCILE_BATCH_REF, AUDIT_LOGS_ARCHIVE_BATCH_REF, RAG_RECONCILIATION_SWEEP_BATCH_REF, RAG_EMBEDDING_DRAIN_BATCH_REF, } from '../../base-classes/services/batches/engine-custom-batch-manifests.js';
 import { createRagReconciliationSweepBatch } from '../../rag/batches/rag-reconciliation-sweep.batch.backend.service.js';
 import { createRagEmbeddingDrainBatch } from '../../rag/batches/rag-embedding-drain.batch.backend.service.js';
 import { MongoDBService } from '../../databases/services/mongodb.service.js';
@@ -83,8 +89,8 @@ import { PdfTemplateBindingBackendService } from '../../pdf-templates/services/p
 import { QueueWorkerInitializerBackendService } from '../../queue/queue-worker-initializer.backend.service.js';
 import { CronJobSyncBackendService } from '../../queue/cron-job-sync.backend.service.js';
 import { createBillingSubjectErasureEffect, TERMINAL_SUBSCRIPTION_STATUSES, } from '../../billing/services/back-office/billing-subject-erasure-effect.backend.js';
-import { initializeBillingCustomImplementations, registerBillingPostOperationHooks, setBillingWebSocketService } from '../../billing/services/custom-impl/billing-custom-implementations.backend.js';
-import { ExternalProvider_ExchangeProtocol_Kind } from '@wildo-ai/external-connectors-models';
+import { initializeBillingCustomImplementations, registerBillingPostOperationHooks, setBillingWebSocketService, setUsageMeteringService } from '../../billing/services/custom-impl/billing-custom-implementations.backend.js';
+import { ExternalProvider_ExchangeProtocol_Kind, ProviderProtocolRuntimeKind } from '@wildo-ai/external-connectors-models';
 import { BillingWebhookAdapter } from '../../billing/services/webhooks/billing-webhook-adapter.backend.service.js';
 import { BillingWebhookCapabilityHandler } from '../../billing/services/webhooks/billing-webhook-capability-handler.backend.service.js';
 import { BillingWebhookEventRouterBackendService } from '../../billing/services/webhooks/billing-webhook-event-router.backend.service.js';
@@ -124,6 +130,7 @@ import { resolveApplicationConfigForStartup } from '../../runtime/utils/applicat
  *   - PROVIDER_NOT_REACHABLE_ON_BACKEND → author the ref under `providers.scopes.backend` in `./wildo.saas.config.ts` + a matching backend contribution in `./backend-api/src/provider-contributions.ts` (the classic trap: authored only in a frontend scope), then `wildo config sync`
  *   - PROVIDER_DISABLED                 → the ref resolves but is disabled for the BILLING protocol in external-provider config
  *   - SECRET_MISSING                    → the env var named by the provider's `secretRef` is absent from the per-env `providerEnv` secrets
+ *   - NO_ADAPTER_FOR_SDK_PACKAGE        → the engine ships no billing adapter for the `sdkPackage` the provider declares. The one reason here that is NOT a config surface — no application edit fixes it
  *   - RESOLUTION_ERROR                  → the provider threw while resolving (registry / billing-SDK fault)
  */
 var BillingProviderResolutionFailureReason;
@@ -142,6 +149,17 @@ var BillingProviderResolutionFailureReason;
     BillingProviderResolutionFailureReason["PROVIDER_DISABLED"] = "provider-disabled";
     /** The provider resolves but its secret (env var `secretRef`) is absent. */
     BillingProviderResolutionFailureReason["SECRET_MISSING"] = "secret-missing";
+    /**
+     * The provider is reachable, enabled and holds its secret, but the engine ships no billing
+     * adapter for the `sdkPackage` its runtime contract declares.
+     *
+     * This is a FRAMEWORK gap rather than an application misconfiguration — the only one of these
+     * reasons the operator cannot fix by editing config — and it exists so that state is stated.
+     * Until this reason existed, that configuration silently received Stripe's adapter built over
+     * the other provider's secret, because the resolution narrowed on the protocol `kind` and then
+     * constructed one named class. `detail` carries the unserved `sdkPackage`.
+     */
+    BillingProviderResolutionFailureReason["NO_ADAPTER_FOR_SDK_PACKAGE"] = "no-adapter-for-sdk-package";
     /** An unexpected error was thrown while resolving (registry/SDK fault). */
     BillingProviderResolutionFailureReason["RESOLUTION_ERROR"] = "resolution-error";
 })(BillingProviderResolutionFailureReason || (BillingProviderResolutionFailureReason = {}));
@@ -180,6 +198,14 @@ function describeBillingProviderResolutionFailure(reason, billingConfig, detail)
             return `${prefix} providerRef='${providerRef}' resolves but its secret `
                 + `(env var '${detail ?? 'UNKNOWN'}') is missing. Populate it in your per-env secrets `
                 + `(providerEnv) and re-run \`wildo config sync\` so it lands in the backend .env. ${disableHint}`;
+        case BillingProviderResolutionFailureReason.NO_ADAPTER_FOR_SDK_PACKAGE:
+            return `${prefix} providerRef='${providerRef}' is reachable, enabled and holds its secret, but `
+                + `it declares sdkPackage='${detail ?? 'UNKNOWN'}' and this engine ships no billing adapter `
+                + `for it (adapters available: ${listSupportedBillingSdkPackages().join(', ') || 'none'}). `
+                + `This is a FRAMEWORK gap, not a config error: no edit to wildo.saas.config.ts can fix it. `
+                + `Either point billing.providerRef at a provider whose sdkPackage is served, or add the `
+                + `adapter to the engine's billing adapter registry `
+                + `(billing/services/billing-adapter-registry.backend.ts). ${disableHint}`;
         case BillingProviderResolutionFailureReason.RESOLUTION_ERROR:
             return `${prefix} providerRef='${providerRef}' threw while resolving`
                 + `${detail ? `: ${detail}` : ''}. Inspect the backend provider registry / billing SDK `
@@ -216,6 +242,8 @@ let StartApplicationBackendService = class StartApplicationBackendService {
     featureDefinitionRegistryService;
     milestoneDefinitionRegistry;
     milestoneConditionRegistry;
+    valueMomentHandlerRegistry;
+    valueMomentDefinitionRegistry;
     lifecycleEvaluator;
     flowsActorsRegistryService;
     resourceServerInstancesRegistry;
@@ -241,7 +269,7 @@ let StartApplicationBackendService = class StartApplicationBackendService {
     logDebug;
     isInitialized = false;
     isPlatformMode = false;
-    constructor(logger, appConfigService, applicationStartupConfigValidator, resourcesRegistryService, repositoriesRegistryService, servicesRegistryService, controllersRegistryService, httpServerService, errorBuilder, errorHandler, authorizationsService, batchesExecutor, executionContextCreatorBackendService, customImplRegistry, mongoDBService, redisService, i18nService, backendProviderRegistryService, externalProvidersRegistryService, featureDefinitionRegistryService, milestoneDefinitionRegistry, milestoneConditionRegistry, lifecycleEvaluator, flowsActorsRegistryService, resourceServerInstancesRegistry, queueWorkerInitializer, cronJobSyncService, chartRegistryService, guidanceTriggerEvaluator, emailTemplateRegistryService, pdfTemplateBindingService, fileStorageRouter, dataSeedRegistryService, dataSeedDispatcherService, dataSeedScopeResolverRegistryService, observabilityBackendService, auditLogsService, authExecutionContextFactory) {
+    constructor(logger, appConfigService, applicationStartupConfigValidator, resourcesRegistryService, repositoriesRegistryService, servicesRegistryService, controllersRegistryService, httpServerService, errorBuilder, errorHandler, authorizationsService, batchesExecutor, executionContextCreatorBackendService, customImplRegistry, mongoDBService, redisService, i18nService, backendProviderRegistryService, externalProvidersRegistryService, featureDefinitionRegistryService, milestoneDefinitionRegistry, milestoneConditionRegistry, valueMomentHandlerRegistry, valueMomentDefinitionRegistry, lifecycleEvaluator, flowsActorsRegistryService, resourceServerInstancesRegistry, queueWorkerInitializer, cronJobSyncService, chartRegistryService, guidanceTriggerEvaluator, emailTemplateRegistryService, pdfTemplateBindingService, fileStorageRouter, dataSeedRegistryService, dataSeedDispatcherService, dataSeedScopeResolverRegistryService, observabilityBackendService, auditLogsService, authExecutionContextFactory) {
         this.logger = logger;
         this.appConfigService = appConfigService;
         this.applicationStartupConfigValidator = applicationStartupConfigValidator;
@@ -264,6 +292,8 @@ let StartApplicationBackendService = class StartApplicationBackendService {
         this.featureDefinitionRegistryService = featureDefinitionRegistryService;
         this.milestoneDefinitionRegistry = milestoneDefinitionRegistry;
         this.milestoneConditionRegistry = milestoneConditionRegistry;
+        this.valueMomentHandlerRegistry = valueMomentHandlerRegistry;
+        this.valueMomentDefinitionRegistry = valueMomentDefinitionRegistry;
         this.lifecycleEvaluator = lifecycleEvaluator;
         this.flowsActorsRegistryService = flowsActorsRegistryService;
         this.resourceServerInstancesRegistry = resourceServerInstancesRegistry;
@@ -300,7 +330,7 @@ let StartApplicationBackendService = class StartApplicationBackendService {
             this.logDebug('Application already initialized, skipping');
             return;
         }
-        const { sharedResourceConfigurations, sharedResourceFieldIdentifiers, sharedResourceRelationships, backendResourceConfigurations, backendResourceFieldIdentifiers, backendResourceRelationships = [], notificationBadgeDefinitions, organizationUnitNarrowing, resourceServerInstances, customServiceImplementations, customRoles, customControllers, container, controllerWhiteList, isPlatformApplication = false, platformPersistenceAdapter, customBatchesFactory, flowsActorsRegistry, customLabels, backendProviderRegistry, customFeatureDefinitions, customFeatureConfiguration, chartDefinitions, customMilestoneDefinitions, customMilestoneConditions, productDefinitions, emailTemplateDefinitions, providerRuntime, pdfTemplateBindings, backendConfig, guidanceFlowDefinitions, dataSeeds, dataSeedScopeResolvers, runtimeProfile = ApplicationRuntimeProfile.APPLICATION_BACKEND, headlessMode = false, skipCronSync = false, skipJobConsumers = false, servicesRegistryDecoratorFactory, afterResourcesRegistryInitialized, } = config;
+        const { sharedResourceConfigurations, sharedResourceFieldIdentifiers, sharedResourceRelationships, backendResourceConfigurations, backendResourceFieldIdentifiers, backendResourceRelationships = [], notificationBadgeDefinitions, organizationUnitNarrowing, resourceServerInstances, customServiceImplementations, customRoles, customControllers, container, controllerWhiteList, isPlatformApplication = false, platformPersistenceAdapter, customBatchesFactory, flowsActorsRegistry, customLabels, backendProviderRegistry, customFeatureDefinitions, customFeatureConfiguration, chartDefinitions, customMilestoneDefinitions, valueMomentHandlers, customMilestoneConditions, productDefinitions, emailTemplateDefinitions, providerRuntime, pdfTemplateBindings, backendConfig, guidanceFlowDefinitions, dataSeeds, dataSeedScopeResolvers, runtimeProfile = ApplicationRuntimeProfile.APPLICATION_BACKEND, headlessMode = false, skipCronSync = false, skipJobConsumers = false, servicesRegistryDecoratorFactory, afterResourcesRegistryInitialized, } = config;
         // Resolved ONCE, here, so every gated validator below reads the same
         // decision. Resolving per-call-site would let two validators disagree
         // about the runtime they are validating.
@@ -330,6 +360,27 @@ let StartApplicationBackendService = class StartApplicationBackendService {
                 }
                 this.appConfigService.assertNoPreOverridePlaceholders();
                 this.logDebug('✅ Application configuration initialized successfully');
+                /*
+                 * ANNOUNCE the abuse-throttle relaxation, loudly (#499).
+                 *
+                 * In DEVELOPMENT / TEST every abuse-throttle maximum is multiplied by a thousand, decided
+                 * from the resolved environment alone. That keeps one source of truth for "what kind of
+                 * host is this" instead of a second flag that can disagree with it — the deliberate
+                 * choice — and it means a host which merely REPORTS development runs with effectively no
+                 * abuse ceilings. Until now nothing said so at any volume.
+                 *
+                 * At `warn` rather than `info`, and naming the sites rather than saying "abuse limits
+                 * relaxed": an operator reading the vague form would reasonably assume ALL throttles, and
+                 * product-policy counters and audit de-duplication windows are deliberately untouched.
+                 * Silent in STAGING / PRODUCTION, where the descriptor returns null.
+                 */
+                const throttleRelaxation = describeAbuseThrottleRelaxation(this.appConfigService.applicationEnv);
+                if (throttleRelaxation) {
+                    this.logger.warn(`⚠️ ABUSE THROTTLES RELAXED ×${throttleRelaxation.multiplier} — this host reports `
+                        + `environment "${throttleRelaxation.applicationEnv}", so the ceilings below are effectively absent. `
+                        + `Relaxed: ${throttleRelaxation.relaxedSites.join(', ')}. `
+                        + 'Product-policy counters and audit de-duplication windows are NOT relaxed.', { applicationEnv: throttleRelaxation.applicationEnv, multiplier: throttleRelaxation.multiplier, relaxedSites: throttleRelaxation.relaxedSites });
+                }
                 /**
                  * Establish the default MongoDB connection — ONLY when this application has a
                  * MongoDB to connect to.
@@ -503,6 +554,28 @@ let StartApplicationBackendService = class StartApplicationBackendService {
                 this.milestoneDefinitionRegistry.logStartupSummary();
             }
             this.logDebug('✅ Milestone definition registry initialized successfully');
+            /*
+             * Step 2.0.2b: value moment definitions + their backend handlers.
+             *
+             * Until #414 `analyticsValueMoments` was read ONCE, a few lines above, purely to warn
+             * about invalid feature references — and then discarded. So the engine had nothing to
+             * evaluate, and the two `analytics.persistence.*` defaults promised an application
+             * cross-device persistence and authoritative evaluation it could not receive.
+             *
+             * Handlers register BEFORE definitions so a definition naming one is never briefly
+             * evaluable against a registry that does not hold it.
+             */
+            if (valueMomentHandlers && valueMomentHandlers.length > 0) {
+                for (const { ref, fn } of valueMomentHandlers) {
+                    this.valueMomentHandlerRegistry.registerHandler(ref, fn);
+                }
+                this.logDebug(`Registered ${valueMomentHandlers.length} value moment handler(s)`);
+            }
+            if (analyticsValueMoments && analyticsValueMoments.length > 0) {
+                this.valueMomentDefinitionRegistry.registerDefinitions(analyticsValueMoments);
+                this.valueMomentDefinitionRegistry.validateDefinitions();
+                this.valueMomentDefinitionRegistry.logStartupSummary();
+            }
             // Step 2.0.3: Initialize lifecycle evaluator configuration
             if (!isPlatformApplication && lifecycleConfig?.enabled) {
                 this.logDebug('🔄 Initializing lifecycle evaluator...');
@@ -533,16 +606,24 @@ let StartApplicationBackendService = class StartApplicationBackendService {
             else if (!isPlatformApplication) {
                 this.logDebug('🔄 Lifecycle system disabled (lifecycle.enabled = false or not configured)');
             }
-            // Step 2.1: Initialize first-class backend provider registry.
+            // Step 2.1: LOAD, then initialize, the first-class backend provider registry.
+            //
+            // The loader imports EXACTLY the refs `providerRuntime` declares — an
+            // application-supplied module first, then the engine's on-demand map, then a
+            // dynamic import of the package the artifact names for that ref (#330). Nothing
+            // this process did not declare is evaluated, which is what stops a worker that
+            // declares one email provider from pulling six model SDKs into its boot graph.
             //
-            // The composed catalog (engine + app-contributed via
-            // `backendProviderRegistry`) is filtered by the authored
-            // `providerRuntime.providerRefs` so this backend process only
-            // exposes providers materialized for it. Any ref claimed by the
-            // runtime artifact but missing from the catalog fails startup
-            // loudly — there is no silent fallback to the unfiltered catalog.
-            this.logDebug('📦 Initializing backend provider registry...');
-            this.backendProviderRegistryService.initialize(backendProviderRegistry, providerRuntime);
+            // `initialize` then re-filters against the same artifact and fails startup loudly
+            // for any ref that did not resolve, quoting the loader's reason. Minion and worker
+            // startup reach this same step by delegating here with their per-host projected
+            // artifact, so all three hosts load identically.
+            this.logDebug('📦 Loading backend providers...');
+            const resolvedProviders = await resolveBackendProviderRegistry({
+                providerRuntime,
+                applicationFragment: backendProviderRegistry,
+            });
+            this.backendProviderRegistryService.initialize(resolvedProviders.registry, providerRuntime, resolvedProviders.unresolved);
             this.logDebug('✅ Backend provider registry initialized', {
                 providerRuntimeApplied: Boolean(providerRuntime),
                 providerCount: this.backendProviderRegistryService.getRegistry().modules.size,
@@ -553,25 +634,15 @@ let StartApplicationBackendService = class StartApplicationBackendService {
                 this.logDebug('🔌 Initializing external providers registry...');
                 await this.externalProvidersRegistryService.initialize();
                 this.logDebug('✅ External providers registry initialized successfully');
-                // F5 (audit Phase 5) — required-capability boot guard. Fail LOUD if any
-                // capability the app marked `activation.required` resolves no active
-                // provider (a hard requirement with nothing to serve it). Generalizes the
-                // audit coherence to EVERY capability; audit is the first user, not special.
-                // (Platform apps initialize the registry later, in the `else` branch — they
-                // author no `required` capabilities, so the guard belongs on the app path.)
-                const missingRequiredCapabilities = this.externalProvidersRegistryService.getRequiredCapabilitiesWithoutProvider();
-                if (missingRequiredCapabilities.length > 0) {
-                    throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
-                        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
-                        context: {
-                            message: `Required engine capabilities resolve no active provider: [${missingRequiredCapabilities.join(', ')}]. `
-                                + 'Each is marked `required` in engineCapabilities but has no provider serving it — '
-                                + 'declare a provider for it (SELECT_ONE needs a primary; FAN_OUT needs ≥1 declared), '
-                                + 'or drop the `required` flag.',
-                            missingRequiredCapabilities,
-                        },
-                    });
-                }
+                // F5 (audit Phase 5) + #328 — required-capability floor. Fail LOUD if any capability
+                // the app marked `required`, or any ENABLED engine flow slot (email, billing, SMS),
+                // resolves no active provider. The door lives on the registry so the platform
+                // services run the same check after their own `refreshFromConfig()`; the engine
+                // half is profile-gated because a minion's scope-filtered registry serves none of
+                // those slots by design.
+                this.externalProvidersRegistryService.assertRequiredCapabilityFloor({
+                    includeEngineFloor: bootAssertions.assertsEngineCapabilityProviderFloor,
+                });
                 // G4 (audit Phase 5) — fail-OPEN audit-sink reconcile. Distinct from the
                 // F5 hard guard above: this WARNS (never throws) when COMPLIANCE_AUDIT_TRAIL
                 // is ENABLED but no provider resolves to deliver it — the operator turned on
@@ -1040,6 +1111,39 @@ let StartApplicationBackendService = class StartApplicationBackendService {
             // days" and suspends forever. Unlike the invitation sweep above, correctness does NOT
             // hold without it — the batch is what makes the declared contract true.
             customBatches.set(SUSPENSION_REACTIVATION_SWEEP_BATCH_REF, createSuspensionReactivationSweepBatch());
+            /*
+             * Nightly relabelling of elapsed machine credentials and platform access grants.
+             * Registered UNCONDITIONALLY, but for a DIFFERENT reason from the sweep above it, and
+             * the difference is worth keeping straight: correctness does NOT depend on this one.
+             * Every guard already compares `expiresAt` against now, so an elapsed credential is
+             * refused whether or not this batch runs. What depends on it is the RECORD — without it
+             * `EXPIRED` has no producer at all, and a listing of API keys, OAuth clients or access
+             * grants shows elapsed ones as ACTIVE forever (#413).
+             */
+            customBatches.set(CREDENTIAL_EXPIRY_SWEEP_BATCH_REF, createCredentialExpirySweepBatch());
+            /*
+             * The scheduled flush that makes a METERED product bill (#415). Registered CONDITIONALLY,
+             * unlike the two above it, because it is the one batch here whose work is meaningless
+             * without a configured provider: `flushToProvider` returns "Provider not initialized" on
+             * every tick, which would put an error line in the log of every application that has no
+             * billing every five minutes forever. A diagnostic that always fires is one operators stop
+             * reading, and this batch's errors are the ones that say whose money went unbilled.
+             *
+             * The condition is the same `billing.enabled` the provider bootstrap below keys on, so the
+             * batch exists exactly when the service it calls has been initialized.
+             */
+            if (applicationConfig?.billing?.enabled) {
+                customBatches.set(USAGE_FLUSH_BATCH_REF, createUsageFlushBatch());
+                /*
+                 * The scheduled reconciliation that makes a LOST webhook recoverable. Gated on the
+                 * same `billing.enabled` as the flush above it, and for the same reason: without a
+                 * provider it would report "Provider not initialized" every hour forever in every
+                 * application that has no billing, and a diagnostic that always fires is one nobody
+                 * reads — which matters most here, because this batch's findings are the ones that
+                 * say a customer's entitlements were wrong.
+                 */
+                customBatches.set(BILLING_RECONCILIATION_BATCH_REF, createBillingReconciliationBatch());
+            }
             /**
              * Retention sweeps for the two `.ttl()` resources. Registered UNCONDITIONALLY, like the
              * suspension sweep above and for the same reason: without them the declared contract is
@@ -1067,6 +1171,13 @@ let StartApplicationBackendService = class StartApplicationBackendService {
             // Event-triggered (enqueued by the notifications dispatcher, no cron).
             // Registered unconditionally so any email notification enqueued onto
             // the custom-batch queue can resolve its executor.
+            // Deferred child-lifecycle teardown (#427) — enqueued by
+            // `ServiceResourceBackendService.queueChildDeletion` when a relationship declares
+            // `ChildLifecycleMode.LAZY`, no cron. Registered UNCONDITIONALLY for exactly the reason
+            // the email and webhook drains are: a job whose ref does not resolve hits
+            // `JOB_BATCH_REF_NOT_FOUND` and is silently dead-lettered — and here that would mean a
+            // child teardown that the parent delete already reported as done.
+            customBatches.set(CHILD_LIFECYCLE_TEARDOWN_BATCH_REF, createChildLifecycleTeardownBatch());
             customBatches.set(EMAIL_BATCH_SEND_BATCH_REF, emailBatchSendService);
             // Event-triggered M2M outbound webhook delivery (enqueued by
             // `M2MWebhookDispatcherBackendService.enqueueDelivery`, no cron) and
@@ -1375,7 +1486,9 @@ let StartApplicationBackendService = class StartApplicationBackendService {
         // (a provider that resolves but then throws mid-wire) which remain
         // non-fatal. Config incoherence is a different, fatal class.
         const resolution = await this.resolveBillingProvider(billingConfig);
-        if (!resolution.provider) {
+        // Literal equality, not truthiness: this package compiles without `strictNullChecks`, under which
+        // `!resolution.resolved` cannot exclude the success member (its `true` may still be null there).
+        if (resolution.resolved === false) {
             throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
                 customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
                 context: {
@@ -1386,15 +1499,30 @@ let StartApplicationBackendService = class StartApplicationBackendService {
             });
         }
         const billingProvider = resolution.provider;
+        // Captured while `resolution` is narrowed to its success variant — the ref rows are stamped with.
+        const billingProviderRef = resolution.providerRef;
         try {
             // 2. Get billing services from DI container
             const catalogSync = container.get(SAAS_SERVICE_TYPES.ProductCatalogSyncService);
             const usageMetering = container.get(SAAS_SERVICE_TYPES.UsageMeteringService);
+            const billingReconciliation = container.get(SAAS_SERVICE_TYPES.BillingReconciliationService);
             // 3. Product definitions from the custom app (like customRoles, customFeatureDefinitions)
             const productDefinitions = appProductDefinitions ?? [];
             // 4. Initialize services in dependency order
             await catalogSync.initialize(productDefinitions, billingProvider);
             await usageMetering.initialize(billingProvider);
+            // The reconciliation sweep needs the same provider handle and nothing else. Initialized
+            // here rather than lazily so a deployment whose provider fails to resolve never reaches
+            // a state where the batch is registered and the service behind it is not.
+            await billingReconciliation.initialize(billingProvider);
+            /*
+             * Publish it for the post-operation usage hook (#415). A module-level seam rather than a
+             * DI edge because the metering service injects the services registry and the hook lives
+             * on that registry — injecting it there would be a container cycle. Set HERE, inside the
+             * billing bootstrap, so an application with no billing leaves the getter null and the
+             * hook costs one null check per write.
+             */
+            setUsageMeteringService(usageMetering);
             // 4b. Register the provider-side half of subject erasure.
             //
             // Registered HERE, inside the billing bootstrap, because that is what keeps the erasure
@@ -1438,7 +1566,7 @@ let StartApplicationBackendService = class StartApplicationBackendService {
             // 4b. Initialize billing custom implementations (late-binding for resource-centric operations)
             const featureSync = container.get(SAAS_SERVICE_TYPES.BillingFeatureSyncService);
             const billingStateService = container.get(SAAS_SERVICE_TYPES.BillingStateService);
-            initializeBillingCustomImplementations(billingProvider, featureSync, billingStateService, billingConfig, this.errorBuilder);
+            initializeBillingCustomImplementations(billingProvider, featureSync, billingStateService, billingConfig, this.errorBuilder, billingProviderRef);
             // 4c. Register post-operation hooks (feature sync fires automatically after subscription mutations)
             registerBillingPostOperationHooks(this.servicesRegistryService);
             // 5. Wire up billing webhooks
@@ -1450,7 +1578,7 @@ let StartApplicationBackendService = class StartApplicationBackendService {
             webhookHandler.registerAdapter(billingConfig.providerRef, 'billing', billingAdapter);
             const webSocketService = container.get(SAAS_SERVICE_TYPES.WebSocketService);
             setBillingWebSocketService(webSocketService);
-            const webhookEventRouter = new BillingWebhookEventRouterBackendService(this.servicesRegistryService, this.resourcesRegistryService, this.logger, webSocketService);
+            const webhookEventRouter = new BillingWebhookEventRouterBackendService(this.servicesRegistryService, this.resourcesRegistryService, this.logger, webSocketService, this.repositoriesRegistryService);
             const billingCapabilityHandler = new BillingWebhookCapabilityHandler(webhookEventRouter);
             webhookAutoController.registerCapabilityHandler(billingCapabilityHandler);
             this.logDebug('✅ Billing services initialized successfully', {
@@ -1482,11 +1610,11 @@ let StartApplicationBackendService = class StartApplicationBackendService {
         const providerRef = billingConfig.providerRef;
         if (!providerRef) {
             this.logDebug('No billing providerRef configured');
-            return { provider: null, reason: BillingProviderResolutionFailureReason.PROVIDER_REF_UNSET };
+            return { resolved: false, reason: BillingProviderResolutionFailureReason.PROVIDER_REF_UNSET };
         }
         try {
             const runtimeContract = this.backendProviderRegistryService.getRuntimeContract(providerRef, ExternalProvider_ExchangeProtocol_Kind.BILLING_PROVIDER);
-            if (runtimeContract?.kind !== 'billing') {
+            if (runtimeContract?.kind !== ProviderProtocolRuntimeKind.BILLING) {
                 // No billing runtime contract exposed to the backend registry for
                 // this ref — the provider was filtered out of the active catalog
                 // because it is not authored in `providers.scopes.backend` (and/or
@@ -1494,24 +1622,42 @@ let StartApplicationBackendService = class StartApplicationBackendService {
                 // from "secret missing": the ref never reached the backend host.
                 this.logDebug('Billing provider not reachable on the backend runtime', { providerRef });
                 return {
-                    provider: null,
+                    resolved: false,
                     reason: BillingProviderResolutionFailureReason.PROVIDER_NOT_REACHABLE_ON_BACKEND,
                 };
             }
             if (!this.externalProvidersRegistryService.isProviderEnabled(providerRef, ExternalProvider_ExchangeProtocol_Kind.BILLING_PROVIDER)) {
                 this.logDebug('Billing provider disabled by external provider configuration', { providerRef });
-                return { provider: null, reason: BillingProviderResolutionFailureReason.PROVIDER_DISABLED };
-            }
-            // The framework currently ships a single `kind: 'billing'`
-            // adapter (Stripe, via `StripeStandardBillingProvider`).
-            // The instantiation here is keyed on `kind` only — no
-            // provider literal — so the CI guard
-            // (`no-provider-ref-branches.guard.test.ts`) accepts it.
-            // When a second billing adapter arrives, factor the
-            // adapter constructor into the runtime contract via
-            // `sdkFactory: (secretKey, opts) => StandardBilling_Interface`,
-            // mirror of the LLM and email surfaces — do NOT
-            // reintroduce a `provider === '<ref>'` branch here.
+                return { resolved: false, reason: BillingProviderResolutionFailureReason.PROVIDER_DISABLED };
+            }
+            // WHICH adapter serves this provider is asked BEFORE the secret is read, and the order
+            // is deliberate: an unserved provider is a framework gap, and reporting "your secret is
+            // missing" for it would send an operator to populate a credential that could never have
+            // been used. Ask the answerable question first.
+            //
+            // The lookup is keyed on the contract's declared `sdkPackage`, never on the provider
+            // ref, so `no-provider-ref-branches.guard.test.ts` still holds — and so does the
+            // principle behind it, because nothing here BRANCHES: the registry answers which of the
+            // adapters this engine ships serves the declaration, exactly as
+            // `EngineBackendProviderRegistry.modules` answers which module serves a ref.
+            //
+            // This replaces a note proposing `sdkFactory: (secretKey, opts) => StandardBilling_Interface`
+            // on the runtime contract, "mirror of the LLM and email surfaces". It is not reachable and
+            // the two cited surfaces are not mirrors of this one — see the registry module's header
+            // for the dependency edge that blocks it and what the alternative would cost.
+            const adapterFactory = resolveBillingAdapterFactory(runtimeContract.sdkPackage);
+            if (!adapterFactory) {
+                this.logger.warn('Billing provider declares an sdkPackage this engine ships no adapter for', {
+                    providerRef,
+                    sdkPackage: runtimeContract.sdkPackage,
+                    supported: listSupportedBillingSdkPackages(),
+                });
+                return {
+                    resolved: false,
+                    reason: BillingProviderResolutionFailureReason.NO_ADAPTER_FOR_SDK_PACKAGE,
+                    detail: runtimeContract.sdkPackage,
+                };
+            }
             const secretRef = runtimeContract.secretRef;
             const secretKey = secretRef
                 ? this.externalProvidersRegistryService.getProviderSecret(providerRef, ExternalProvider_ExchangeProtocol_Kind.BILLING_PROVIDER, secretRef)
@@ -1519,18 +1665,25 @@ let StartApplicationBackendService = class StartApplicationBackendService {
             if (!secretKey) {
                 this.logger.warn('Billing provider configured but secret is missing', { providerRef, secretRef });
                 return {
-                    provider: null,
+                    resolved: false,
                     reason: BillingProviderResolutionFailureReason.SECRET_MISSING,
                     detail: secretRef,
                 };
             }
-            this.logDebug('Billing provider resolved from first-class billing runtime contract', { providerRef });
-            return { provider: new StripeStandardBillingProvider(secretKey, runtimeContract.apiVersion) };
+            this.logDebug('Billing provider resolved from first-class billing runtime contract', {
+                providerRef,
+                sdkPackage: runtimeContract.sdkPackage,
+            });
+            return {
+                resolved: true,
+                provider: adapterFactory({ secretKey, apiVersion: runtimeContract.apiVersion }),
+                providerRef,
+            };
         }
         catch (error) {
             const detail = describeCaughtError(error);
             this.logger.warn('Failed to resolve billing provider', { providerRef, error: detail });
-            return { provider: null, reason: BillingProviderResolutionFailureReason.RESOLUTION_ERROR, detail };
+            return { resolved: false, reason: BillingProviderResolutionFailureReason.RESOLUTION_ERROR, detail };
         }
     }
     async shutdown() {
@@ -1859,6 +2012,36 @@ let StartApplicationBackendService = class StartApplicationBackendService {
                 usableMembershipStatuses: [...ADMINISTRATIVELY_USABLE_ORGANIZATION_MEMBER_STATUSES],
                 usableOwnerUserStatuses: [...ADMINISTRATIVELY_USABLE_OWNER_USER_STATUSES],
             });
+            /*
+             * An AUDIT ROW per stranded tenant, beside the log line — the half this report was missing.
+             *
+             * The APPLICATION twin above has emitted `logApplicationSuperAdminFloorBreached` from the
+             * start, and the sibling that watches ALLOWED lifecycle writes emits the organization event
+             * per stranded tenant with the reasoning stated at its call site: a log line is not
+             * queryable evidence and never reaches a SIEM. This report — the only surface that observes
+             * a tenant stranded by a route no guard ever saw — wrote log lines and nothing else, so the
+             * breach with the WORST provenance was the one with no trail.
+             *
+             * `detectedBy: BOOT_REPORT` is what a reader needs and cannot infer: it separates "a guarded
+             * write let this through" from "we found it already broken". The action fields are omitted
+             * rather than filled, because there is no action to name.
+             *
+             * One row per tenant, matching the sibling: an operator who learns about them one at a time
+             * cannot plan the remediation. Each is awaited but individually guarded — a failing audit
+             * write must not cost the remaining tenants their rows, and must never be why startup fails.
+             */
+            for (const stranded of population.ownerlessOrganizations) {
+                try {
+                    await this.auditLogsService?.logOrganizationOwnerFloorBreached({
+                        organizationId: stranded.organizationId,
+                        detectedBy: AdministrativeContinuityBreachDetection.BOOT_REPORT,
+                        remainingUsableOwners: 0,
+                    });
+                }
+                catch (error) {
+                    this.logDebug('Organization-owner floor breach could not be recorded in the audit trail', projectCaughtErrorLogFields(error));
+                }
+            }
         }
         catch (error) {
             // See the header: a diagnostic must never be the reason startup fails.
@@ -2110,24 +2293,26 @@ StartApplicationBackendService = __decorate([
     __param(19, inject(SAAS_SERVICE_TYPES.FeatureDefinitionRegistryService)),
     __param(20, inject(SAAS_SERVICE_TYPES.MilestoneDefinitionRegistry)),
     __param(21, inject(SAAS_SERVICE_TYPES.MilestoneConditionRegistry)),
-    __param(22, inject(SAAS_SERVICE_TYPES.LifecycleEvaluator)),
-    __param(23, inject(SAAS_SERVICE_TYPES.FlowsActorsRegistryService)),
-    __param(24, inject(SAAS_SERVICE_TYPES.ResourceServerInstancesRegistry)),
-    __param(25, inject(SAAS_SERVICE_TYPES.QueueWorkerInitializerService)),
-    __param(26, inject(SAAS_SERVICE_TYPES.CronJobSyncService)),
-    __param(27, inject(SAAS_SERVICE_TYPES.ChartRegistryService)),
-    __param(28, inject(SAAS_SERVICE_TYPES.GuidanceTriggerEvaluator)),
-    __param(29, inject(SAAS_SERVICE_TYPES.EmailTemplateRegistry)),
-    __param(30, inject(SAAS_SERVICE_TYPES.PdfTemplateBinding)),
-    __param(31, inject(SAAS_SERVICE_TYPES.FileStorageRouter)),
-    __param(32, inject(SAAS_SERVICE_TYPES.DataSeedRegistry)),
-    __param(33, inject(SAAS_SERVICE_TYPES.DataSeedDispatcher)),
-    __param(34, inject(SAAS_SERVICE_TYPES.DataSeedScopeResolverRegistry)),
-    __param(35, inject(SAAS_SERVICE_TYPES.ObservabilityBackendService)),
-    __param(36, inject(SAAS_SERVICE_TYPES.AuditLogsService)),
-    __param(36, optional()),
-    __param(37, inject(SAAS_SERVICE_TYPES.AuthExecutionContextFactory)),
-    __param(37, optional()),
+    __param(22, inject(SAAS_SERVICE_TYPES.ValueMomentHandlerRegistry)),
+    __param(23, inject(SAAS_SERVICE_TYPES.ValueMomentDefinitionRegistry)),
+    __param(24, inject(SAAS_SERVICE_TYPES.LifecycleEvaluator)),
+    __param(25, inject(SAAS_SERVICE_TYPES.FlowsActorsRegistryService)),
+    __param(26, inject(SAAS_SERVICE_TYPES.ResourceServerInstancesRegistry)),
+    __param(27, inject(SAAS_SERVICE_TYPES.QueueWorkerInitializerService)),
+    __param(28, inject(SAAS_SERVICE_TYPES.CronJobSyncService)),
+    __param(29, inject(SAAS_SERVICE_TYPES.ChartRegistryService)),
+    __param(30, inject(SAAS_SERVICE_TYPES.GuidanceTriggerEvaluator)),
+    __param(31, inject(SAAS_SERVICE_TYPES.EmailTemplateRegistry)),
+    __param(32, inject(SAAS_SERVICE_TYPES.PdfTemplateBinding)),
+    __param(33, inject(SAAS_SERVICE_TYPES.FileStorageRouter)),
+    __param(34, inject(SAAS_SERVICE_TYPES.DataSeedRegistry)),
+    __param(35, inject(SAAS_SERVICE_TYPES.DataSeedDispatcher)),
+    __param(36, inject(SAAS_SERVICE_TYPES.DataSeedScopeResolverRegistry)),
+    __param(37, inject(SAAS_SERVICE_TYPES.ObservabilityBackendService)),
+    __param(38, inject(SAAS_SERVICE_TYPES.AuditLogsService)),
+    __param(38, optional()),
+    __param(39, inject(SAAS_SERVICE_TYPES.AuthExecutionContextFactory)),
+    __param(39, optional()),
     __metadata("design:paramtypes", [LoggerService,
         AppConfigurationService,
         ApplicationStartupConfigValidatorService,
@@ -2149,8 +2334,7 @@ StartApplicationBackendService = __decorate([
         ExternalProvidersRegistryBackendService,
         FeatureDefinitionRegistryBackendService,
         MilestoneDefinitionRegistryBackendService,
-        MilestoneConditionRegistryBackendService,
-        LifecycleEvaluatorBackendService,
+        MilestoneConditionRegistryBackendService, Function, Function, LifecycleEvaluatorBackendService,
         FlowsActorsRegistryService,
         ResourceServerInstancesRegistryBackendService,
         QueueWorkerInitializerBackendService,