@cosmicdrift/kumiko-server-runtime 0.386.0 → 0.388.0

package/LICENSE

@@ -1,57 +1,21 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             Marc Frost
-
-Licensed Work:        @cosmicdrift/kumiko-framework
-                      The Licensed Work is © 2026 Marc Frost.
-
-Additional Use Grant: 
-You may use the Licensed Work in production for any purpose, including 
-commercially, EXCEPT for the Restricted Use. 
-
-"Restricted Use" is defined as using the Licensed Work to provide a platform 
-or service to third parties that allows them to host, deploy, or run their 
-own applications built with the Licensed Work. This includes, but is not 
-limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
-platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
-managed offering of the Licensed Work.
-
-This restriction does not apply to the Licensor, any entity controlled by, 
-controlling, or under common control with the Licensor ("Affiliates"), or 
-contractors acting on their behalf. The Licensor remains free to use the 
-Licensed Work for any purpose, including for the operation of kumiko.rocks.
-
-Change Date:          2030-05-05
-Change License:       Apache License, Version 2.0
-
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative works, 
-redistribute, and make non-production use of the Licensed Work. The Licensor may 
-make an Additional Use Grant, above, permitting limited production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly 
-available distribution of the Licensed Work under this License, whichever comes 
-first, this License will convert to the Change License.
-
-This Business Source License governs use of the Licensed Work in all cases, except 
-as to any use that is explicitly granted in the Additional Use Grant above or 
-under the Change License after the Change Date.
-
-If your use of the Licensed Work does not comply with the requirements of this 
-License, you must cease use of the Licensed Work immediately.
-
-All copies of the Licensed Work, and all derivative works thereof, must include 
-this License.
-
-This License does not grant you any right, title, or interest in any trademark, 
-logo, or branding of the Licensor, except as required to comply with this License.
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
-“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
-WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
-TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
-ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.
+MIT License
+
+Copyright (c) 2026 Marc Frost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/boot/boot-crypto.js

@@ -15,6 +15,9 @@ export function envHasMasterKek(env) {
 }
 export function resolveBootCrypto(envSource, masterKeyOverride) {
     const masterKeyProvider = masterKeyOverride ?? envMasterKeyProviderIfConfigured(envSource);
+    // Providers defer their keyring check under KUMIKO_DRY_RUN_ENV; an app-supplied
+    // provider must still be rejected at boot, not at the first key access.
+    masterKeyProvider?.currentVersion();
     const dekCache = createDekCache();
     const configCipher = masterKeyProvider
         ? createEnvelopeCipher(masterKeyProvider, { dekCache })
@@ -31,15 +34,11 @@ function envMasterKeyProviderIfConfigured(envSource) {
     if (!envHasMasterKek(envSource))
         return undefined;
     const provider = createEnvMasterKeyProvider({
-        // CURRENT_VERSION default "1" spiegelt secretsEnvSchema — ohne
-        // ihn wirft der raw-env-Provider, obwohl V1 gesetzt ist.
+        // CURRENT_VERSION defaults to "1" in secretsEnvSchema; without it, the raw-env provider throws even when V1 is set.
         env: {
             ...envSource,
             KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: envSource["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
         },
     });
-    // The provider defers its keyring check under KUMIKO_DRY_RUN_ENV; the boot
-    // must still reject a malformed keyring there.
-    provider.currentVersion();
     return provider;
 }

package/dist/boot/shared-boot-steps.d.ts

@@ -0,0 +1,43 @@
+import { type SeedAdminOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import type { AuthRoutesConfig } from "@cosmicdrift/kumiko-framework/api";
+import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type EffectiveFeaturesResolver, type FeatureDefinition, type Registry, type ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
+import type { CacheSyncBus } from "@cosmicdrift/kumiko-framework/redis";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
+import type { FeatureTogglesWiring } from "../boot-options/feature-toggles-option.ts";
+import type { DbSeedFn } from "../boot-options/seed-shortcuts.ts";
+import { type AuthOptionsCarrier } from "../compose-features.ts";
+import type { RunProdAppAuthOptions } from "../run-prod-app.ts";
+/** Returns `envSource` itself (it may be `process.env`) when there is nothing to layer under it. */
+export declare function withEnvDefaults(envDefaults: Readonly<Record<string, string | undefined>>, envSource: Record<string, string | undefined>): Record<string, string | undefined>;
+export declare function composeAppFeatures(appFeatures: readonly FeatureDefinition[], bootFeatures: readonly FeatureDefinition[], effectiveAuth: AuthOptionsCarrier | undefined): readonly FeatureDefinition[];
+export declare function validateComposedFeatures(features: readonly FeatureDefinition[], bootOptions: ValidateBootOptions): void;
+export declare function assertMfaSwitchTenantGate(registry: Registry, processName: string): void;
+export declare function buildEffectiveFeaturesResolver(deps: {
+    readonly features: readonly FeatureDefinition[];
+    readonly featureToggles: FeatureTogglesWiring | undefined;
+    readonly db: DbConnection;
+    readonly registry: Registry;
+    readonly cacheSync: CacheSyncBus;
+}): Promise<EffectiveFeaturesResolver | undefined>;
+export declare function applyStandardBootSeeds(deps: {
+    readonly db: DbConnection;
+    readonly registry: Registry;
+    readonly admin: SeedAdminOptions | undefined;
+    readonly shortcutSeeds: readonly DbSeedFn[];
+    readonly cipher: EnvelopeCipher | undefined;
+}): Promise<void>;
+type SharedAuthFlowFields = Pick<RunProdAppAuthOptions, "passwordReset" | "emailVerification" | "accountUnlock" | "signup" | "invite">;
+type AuthFlowRoutes = Pick<AuthRoutesConfig, "passwordReset" | "emailVerification" | "accountUnlock" | "signup" | "invite">;
+export type SharedAuthRouteSource = SharedAuthFlowFields & Pick<RunProdAppAuthOptions, "loginErrorStatusMap" | "cookieDomain" | "retiredCookieDomains" | "allowedOrigins" | "unsafeSkipOriginCheck" | "postAuthLanding">;
+export type SharedAuthRoutes = AuthFlowRoutes & Pick<AuthRoutesConfig, "membershipQuery" | "loginHandler" | "loginErrorStatusMap" | "cookieDomain" | "retiredCookieDomains" | "allowedOrigins" | "unsafeSkipOriginCheck" | "postAuthLanding" | "mfaVerifyHandler" | "switchTenantMfaGateHandler" | "mfaPreauthEnableStartHandler" | "mfaPreauthConfirmHandler">;
+export declare function buildSharedAuthRoutes(effectiveAuth: SharedAuthRouteSource, hasMfa: boolean): SharedAuthRoutes;
+export declare function waitForKmsHealthy(kms: KmsAdapter, processName: string, deadline: number): Promise<void>;
+export declare function openDatabasePools(databaseUrl: string, envSource: Record<string, string | undefined>): {
+    readonly db: DbConnection;
+    readonly closeDb: () => Promise<void>;
+    readonly outsideTransactionDb: DbConnection;
+    readonly closeOutsideTransactionDb: () => Promise<void>;
+};
+export {};

package/dist/boot/shared-boot-steps.js

@@ -0,0 +1,154 @@
+// Boot steps that runProdApp, the dev server and the worker processes run
+// identically. Each step keeps the caller in charge of ordering, logging sinks
+// and cleanup policy: those differ between the processes.
+import { AuthErrors, AuthHandlers, AuthQueries, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { seedAdminGuarded, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import { AuthMfaHandlers } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
+import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, serverTimeoutOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
+import { collectWriteHandlerQns, findTierResolverUsage, requireTierResolverPlugin, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
+import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
+import { buildComposeAuthOptions, composeFeatures, } from "../compose-features.js";
+import { applyBootSeeds } from "./apply-boot-seeds.js";
+import { waitUntilDatabaseReachable } from "./wait-for-database.js";
+/** Returns `envSource` itself (it may be `process.env`) when there is nothing to layer under it. */
+export function withEnvDefaults(envDefaults, envSource) {
+    return Object.keys(envDefaults).length > 0 ? { ...envDefaults, ...envSource } : envSource;
+}
+export function composeAppFeatures(appFeatures, bootFeatures, effectiveAuth) {
+    const composeAuthOptions = buildComposeAuthOptions(effectiveAuth);
+    return composeFeatures([...appFeatures, ...bootFeatures], {
+        includeBundled: !!effectiveAuth,
+        ...(composeAuthOptions && { authOptions: composeAuthOptions }),
+    });
+}
+export function validateComposedFeatures(features, bootOptions) {
+    validateBoot(features, bootOptions);
+    warnIfNonUtcServerTimeZone();
+    validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
+}
+export function assertMfaSwitchTenantGate(registry, processName) {
+    if (registry.getWriteHandler(AuthHandlers.switchTenantMfaGate) === undefined) {
+        throw new Error(`[${processName}] auth-mfa is mounted but ${AuthHandlers.switchTenantMfaGate} is not registered: ` +
+            "createAuthEmailPasswordFeature registers it only when mfaStatusChecker is set, and without it " +
+            "POST /auth/switch-tenant would mint sessions without the second factor");
+    }
+}
+export async function buildEffectiveFeaturesResolver(deps) {
+    const { features, featureToggles, db, registry, cacheSync } = deps;
+    const tierResolverUsage = findTierResolverUsage(features);
+    const tierResolver = tierResolverUsage
+        ? await requireTierResolverPlugin(tierResolverUsage).build({ db, registry, cacheSync })
+        : undefined;
+    if (!featureToggles)
+        return tierResolver;
+    const bound = await featureToggles.bind({ db, registry, cacheSync, tierResolver });
+    return bound.resolver;
+}
+export async function applyStandardBootSeeds(deps) {
+    const { db, registry, admin, shortcutSeeds, cipher } = deps;
+    if (admin) {
+        await seedAdminGuarded(db, admin);
+    }
+    for (const seed of shortcutSeeds) {
+        await seed(db);
+    }
+    // The helper indirection is what config-seed-boot.integration.ts pins — keep it as a single call.
+    await applyBootSeeds({
+        registry,
+        db,
+        ...(cipher && { cipher }),
+    });
+}
+const MFA_ROUTE_HANDLERS = {
+    mfaVerifyHandler: AuthMfaHandlers.verify,
+    switchTenantMfaGateHandler: AuthHandlers.switchTenantMfaGate,
+    mfaPreauthEnableStartHandler: AuthMfaHandlers.enableStartPreauth,
+    mfaPreauthConfirmHandler: AuthMfaHandlers.enableConfirmPreauth,
+};
+function buildAuthFlowRoutes(effectiveAuth) {
+    return {
+        ...(effectiveAuth.passwordReset && {
+            passwordReset: {
+                requestHandler: AuthHandlers.requestPasswordReset,
+                confirmHandler: AuthHandlers.resetPassword,
+            },
+        }),
+        ...(effectiveAuth.emailVerification && {
+            emailVerification: {
+                requestHandler: AuthHandlers.requestEmailVerification,
+                confirmHandler: AuthHandlers.verifyEmail,
+            },
+        }),
+        ...(effectiveAuth.accountUnlock && {
+            accountUnlock: {
+                requestHandler: AuthHandlers.requestAccountUnlock,
+                confirmHandler: AuthHandlers.confirmAccountUnlock,
+            },
+        }),
+        ...(effectiveAuth.signup && {
+            signup: {
+                requestHandler: AuthHandlers.signupRequest,
+                confirmHandler: AuthHandlers.signupConfirm,
+            },
+        }),
+        ...(effectiveAuth.invite && {
+            invite: {
+                acceptHandler: AuthHandlers.inviteAccept,
+                acceptWithLoginHandler: AuthHandlers.inviteAcceptWithLogin,
+                signupCompleteHandler: AuthHandlers.inviteSignupComplete,
+                infoHandler: AuthQueries.inviteInfo,
+            },
+        }),
+    };
+}
+export function buildSharedAuthRoutes(effectiveAuth, hasMfa) {
+    return {
+        membershipQuery: TenantQueries.memberships,
+        loginHandler: AuthHandlers.login,
+        loginErrorStatusMap: effectiveAuth.loginErrorStatusMap ?? {
+            [AuthErrors.invalidCredentials]: 401,
+            [AuthErrors.noMembership]: 403,
+        },
+        ...(effectiveAuth.cookieDomain !== undefined && {
+            cookieDomain: effectiveAuth.cookieDomain,
+        }),
+        ...(effectiveAuth.retiredCookieDomains !== undefined && {
+            retiredCookieDomains: effectiveAuth.retiredCookieDomains,
+        }),
+        ...(effectiveAuth.allowedOrigins !== undefined && {
+            allowedOrigins: effectiveAuth.allowedOrigins,
+        }),
+        ...(effectiveAuth.unsafeSkipOriginCheck !== undefined && {
+            unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
+        }),
+        ...(effectiveAuth.postAuthLanding !== undefined && {
+            postAuthLanding: effectiveAuth.postAuthLanding,
+        }),
+        ...(hasMfa && MFA_ROUTE_HANDLERS),
+        ...buildAuthFlowRoutes(effectiveAuth),
+    };
+}
+export async function waitForKmsHealthy(kms, processName, deadline) {
+    const kmsHealth = await waitUntilDatabaseReachable(() => kms.health(), {
+        processName,
+        target: "KMS",
+        deadline,
+    });
+    if (!kmsHealth.ok) {
+        throw new Error(`[${processName}] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`);
+    }
+}
+export function openDatabasePools(databaseUrl, envSource) {
+    const { db, close: closeDb } = createDbConnection({
+        url: databaseUrl,
+        ...dbConnectionOptionsFromEnv(envSource),
+        ...serverTimeoutOptionsFromEnv(envSource),
+    });
+    const { db: outsideTransactionDb, close: closeOutsideTransactionDb } = createDbConnection({
+        url: databaseUrl,
+        ...outsideTransactionPoolOptionsFromEnv(envSource),
+        ...serverTimeoutOptionsFromEnv(envSource),
+    });
+    return { db, closeDb, outsideTransactionDb, closeOutsideTransactionDb };
+}

package/dist/boot/wait-for-database.d.ts

@@ -5,9 +5,12 @@ export declare const WAIT_FOR_DATABASE_MAX_BACKOFF_MS = 15000;
 export declare const WAIT_FOR_DATABASE_DEADLINE_MS = 90000;
 export type WaitForDatabaseOptions = {
     readonly processName: string;
+    /** Names the dependency in the retry log line; default "database". */
+    readonly target?: string;
     readonly log?: (line: string) => void;
     readonly sleep?: (ms: number) => Promise<void>;
     readonly now?: () => number;
+    readonly deadline?: number;
 };
 export declare function waitForDatabase(db: DbConnection, options: WaitForDatabaseOptions): Promise<void>;
 export declare function waitUntilDatabaseReachable<T>(ping: () => Promise<T>, options: WaitForDatabaseOptions): Promise<T>;

package/dist/boot/wait-for-database.js

@@ -37,8 +37,8 @@ export async function waitForDatabase(db, options) {
     await waitUntilDatabaseReachable(() => tableExists(db, "pg_catalog.pg_class"), options);
 }
 export async function waitUntilDatabaseReachable(ping, options) {
-    const { processName, log = logToConsole, sleep = sleepReal, now = Date.now } = options;
-    const deadline = now() + WAIT_FOR_DATABASE_DEADLINE_MS;
+    const { processName, target = "database", log = logToConsole, sleep = sleepReal, now = Date.now, } = options;
+    const deadline = options.deadline ?? now() + WAIT_FOR_DATABASE_DEADLINE_MS;
     let backoffMs = WAIT_FOR_DATABASE_INITIAL_BACKOFF_MS;
     for (let attempt = 1;; attempt++) {
         try {
@@ -52,7 +52,7 @@ export async function waitUntilDatabaseReachable(ping, options) {
                 throw error;
             const waitMs = Math.min(backoffMs, remainingMs);
             const code = extractPgError(error)?.code ?? "unknown";
-            log(`[${processName}] database not reachable (code ${code}, attempt ${attempt}), retrying in ${waitMs}ms…`);
+            log(`[${processName}] ${target} not reachable (code ${code}, attempt ${attempt}), retrying in ${waitMs}ms…`);
             await sleep(waitMs);
             backoffMs = Math.min(backoffMs * 2, WAIT_FOR_DATABASE_MAX_BACKOFF_MS);
         }

package/dist/boot/worker-boot-core.js

@@ -5,8 +5,8 @@
 // share every step that decides ciphers, blind indexes and config encryption.
 import { loadJwtSecretOrKeyring } from "@cosmicdrift/kumiko-framework/api";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
-import { configureEntityFieldEncryption, createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, serverTimeoutOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
-import { createRegistry, findTierResolverUsage, requireTierResolverPlugin, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
+import { configureEntityFieldEncryption, } from "@cosmicdrift/kumiko-framework/db";
+import { createRegistry, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
 import { createWorkerEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
 import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
 import { createEntityCache, createEventDedup, createIdempotencyGuard, } from "@cosmicdrift/kumiko-framework/pipeline";
@@ -16,11 +16,13 @@ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { Redis } from "ioredis";
 import { composeFeatures } from "../compose-features.js";
 import { assertPiiBootInvariants } from "../pii-boot-gate.js";
-import { requireEnv } from "../run-prod-app.js";
+import { readEnv, requireEnv } from "../require-env.js";
 import { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, } from "../run-prod-app-boot-context.js";
 import { resolveBootCrypto } from "./boot-crypto.js";
 import { jobRunLoggerCallbacks } from "./job-run-logger.js";
-import { waitForDatabase, waitUntilDatabaseReachable } from "./wait-for-database.js";
+import { INSTANCE_ID_ENV } from "./record-app-started-on-boot.js";
+import { buildEffectiveFeaturesResolver, openDatabasePools, waitForKmsHealthy, } from "./shared-boot-steps.js";
+import { WAIT_FOR_DATABASE_DEADLINE_MS, waitForDatabase } from "./wait-for-database.js";
 import { assertWorkerMetricsOptions } from "./worker-metrics-server.js";
 function isSecretsContext(value) {
     if (typeof value !== "object" || value === null)
@@ -36,12 +38,6 @@ export async function resolveWorkerEnvSource(options, processName) {
         })
         : rawEnvSource;
 }
-async function buildTierEffectiveFeatures(features, db, registry, cacheSync) {
-    const tierResolverUsage = findTierResolverUsage(features);
-    if (!tierResolverUsage)
-        return undefined;
-    return requireTierResolverPlugin(tierResolverUsage).build({ db, registry, cacheSync });
-}
 async function assertWorkerSchemaCurrent(db, migrationsDir, processName) {
     const dir = migrationsDir ?? "./kumiko/migrations";
     // biome-ignore lint/suspicious/noConsole: boot-time progress hint
@@ -59,7 +55,7 @@ async function assertWorkerSchemaCurrent(db, migrationsDir, processName) {
 }
 export async function bootWorkerProcess(options, envSource, profile) {
     const { processName } = profile;
-    // Polyfill before anything else (fw#1725): without it every job fails with
+    // Polyfill before anything else: without it every job fails with
     // "Temporal is not defined" in a retry loop, with no boot-time signal.
     const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
     await ensureTemporalPolyfill();
@@ -96,32 +92,18 @@ export async function bootWorkerProcess(options, envSource, profile) {
         return { kind: "dry-run", envSource };
     }
     // Before the connections, so an abort leaks nothing.
+    const databaseWaitDeadline = Date.now() + WAIT_FOR_DATABASE_DEADLINE_MS;
     if (options.kms) {
-        const kms = options.kms;
-        const kmsHealth = await waitUntilDatabaseReachable(() => kms.health(), {
-            processName: processName,
-        });
-        if (!kmsHealth.ok) {
-            throw new Error(`[${processName}] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`);
-        }
+        await waitForKmsHealthy(options.kms, processName, databaseWaitDeadline);
     }
-    const { db, close: closeDb } = createDbConnection({
-        url: databaseUrl,
-        ...dbConnectionOptionsFromEnv(envSource),
-        ...serverTimeoutOptionsFromEnv(envSource),
-    });
-    const { db: outsideTransactionDb, close: closeOutsideTransactionDb } = createDbConnection({
-        url: databaseUrl,
-        ...outsideTransactionPoolOptionsFromEnv(envSource),
-        ...serverTimeoutOptionsFromEnv(envSource),
-    });
+    const { db, closeDb, outsideTransactionDb, closeOutsideTransactionDb } = openDatabasePools(databaseUrl, envSource);
     const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
     const cacheSync = createRedisCacheSyncBus({
         redisUrl,
         clientOptions: redisClientOptionsFromEnv(envSource),
     });
     try {
-        await waitForDatabase(db, { processName });
+        await waitForDatabase(db, { processName, deadline: databaseWaitDeadline });
     }
     catch (err) {
         await closeDb();
@@ -130,16 +112,13 @@ export async function bootWorkerProcess(options, envSource, profile) {
         await cacheSync.close();
         throw err;
     }
-    let resolvedEffectiveFeatures = await buildTierEffectiveFeatures(features, db, registry, cacheSync);
-    if (profile.featureToggles) {
-        const bound = await profile.featureToggles.bind({
-            db,
-            registry,
-            cacheSync,
-            tierResolver: resolvedEffectiveFeatures,
-        });
-        resolvedEffectiveFeatures = bound.resolver;
-    }
+    const resolvedEffectiveFeatures = await buildEffectiveFeaturesResolver({
+        features,
+        featureToggles: profile.featureToggles,
+        db,
+        registry,
+        cacheSync,
+    });
     if (options.migrations !== false) {
         try {
             await assertWorkerSchemaCurrent(db, options.migrations?.dir, processName);
@@ -155,7 +134,7 @@ export async function bootWorkerProcess(options, envSource, profile) {
     const idempotency = createIdempotencyGuard(redis, { ttlSeconds: 60 });
     const eventDedup = createEventDedup(redis, { ttlSeconds: 60 });
     const entityCache = createEntityCache(redis, { ttlSeconds: 60 });
-    // Same crypto wiring as the API (fw#1725), otherwise this process writes
+    // Same crypto wiring as the API, otherwise this process writes
     // rows the API can no longer read (different cipher, missing blind index).
     const deps = { db, redis, registry };
     const resolvedExtraContext = typeof options.extraContext === "function"
@@ -200,6 +179,7 @@ export async function bootWorkerProcess(options, envSource, profile) {
             getActiveTenantIds: options.jobs.getActiveTenantIds,
         }),
         ...(options.eventDispatcher && { eventDispatcher: options.eventDispatcher }),
+        instanceId: readEnv(INSTANCE_ID_ENV, envSource),
     });
     entrypoint.lifecycle.registerShutdownHook("workerCacheSync", async () => {
         await cacheSync.close();

package/dist/boot-options/billing-option.d.ts

@@ -1,37 +1,46 @@
 import { type TierSyncResult } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { type SubscriptionDodoOptions } from "@cosmicdrift/kumiko-bundled-features/subscription-dodo";
 import { type SubscriptionStripeOptions } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
 import type { ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-/** Mounts `subscription-stripe` plus the webhook route that writes the
- *  subscription and syncs the tenant's tier (`tier-engine`). Needs
- *  `billing-foundation`, `tier-engine`, `config` and `secrets` in `features`.
- *  `STRIPE_API_KEY` / `STRIPE_WEBHOOK_SECRET` from the env are only the
- *  bridge fallback; the keys normally live in the secrets store.
+/** Mounts `subscription-stripe` and/or `subscription-dodo` plus one webhook
+ *  route that writes the subscription and syncs the tenant's tier
+ *  (`tier-engine`). Needs `billing-foundation`, `tier-engine`, `config` and
+ *  `secrets` in `features`. The env keys (`STRIPE_API_KEY` /
+ *  `STRIPE_WEBHOOK_SECRET`, `DODO_PAYMENTS_API_KEY` /
+ *  `DODO_PAYMENTS_WEBHOOK_KEY`) are only the bridge fallback; the keys
+ *  normally live in the secrets store.
  *
  *  @example
  *  runProdApp({ ..., billing: {
  *    stripe: { priceToTier: { [env.STRIPE_PRICE_PRO]: "pro" } },
+ *    dodo: { priceToTier: { [env.DODO_PRODUCT_PRO]: "pro" } },
  *    defaultTier: "free",
  *  } })
  */
 export type BillingBootOption = {
-    readonly stripe: {
+    /** At least one of `stripe` and `dodo` is required. */
+    readonly stripe?: {
         readonly priceToTier: Readonly<Record<string, string>>;
-        /** Default `SUBSCRIPTION_WEBHOOK_PATH`; must contain `:providerName`. */
+        /** Default `SUBSCRIPTION_WEBHOOK_PATH`; must contain `:providerName`. Applies to every provider. */
         readonly webhookPath?: string;
         readonly oneOffPriceIds?: SubscriptionStripeOptions["oneOffPriceIds"];
         readonly paymentInvoiceCreation?: boolean;
     };
+    readonly dodo?: {
+        readonly priceToTier: Readonly<Record<string, string>>;
+        readonly oneOffPriceIds?: SubscriptionDodoOptions["oneOffPriceIds"];
+    };
     /** Tier a tenant falls back to without an active subscription. */
     readonly defaultTier: string;
     /** Valid tier names beyond `defaultTier` and the `priceToTier` targets. */
     readonly tierNames?: readonly string[];
-    /** Default `"fail-webhook"`: Stripe retries, so a failed tier sync gets another attempt. */
+    /** Default `"fail-webhook"`: the provider retries, so a failed tier sync gets another attempt. */
     readonly onTierSyncError?: "log" | "fail-webhook";
     /** Runs after every webhook whose tier sync succeeded, also when the tier stayed the same (`changed: false`). */
     readonly afterSync?: (result: TierSyncResult<string>) => Promise<void>;
 };
 export declare function resolveBillingOption(billing: BillingBootOption, envSource: Record<string, string | undefined>): {
-    readonly feature: FeatureDefinition;
+    readonly features: readonly FeatureDefinition[];
     readonly route: ExtraRouteDefinition;
 };

package/dist/boot-options/billing-option.js

@@ -1,29 +1,55 @@
 import { createSubscriptionTierSync, SUBSCRIPTION_WEBHOOK_PATH, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { createSubscriptionDodoFeature, } from "@cosmicdrift/kumiko-bundled-features/subscription-dodo";
 import { createSubscriptionStripeFeature, } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
 const PROVIDER_NAME_PARAM = ":providerName";
+function warnOnEmptyPriceMap(provider, priceToTier) {
+    if (Object.keys(priceToTier).length === 0) {
+        // biome-ignore lint/suspicious/noConsole: boot-time warn, no logger configured this early
+        console.warn(`[runProdApp] billing.${provider}.priceToTier is empty: every subscription webhook is ignored until a price maps to a tier.`);
+    }
+}
+function bridgeCredentials(envSource, apiKeyName, webhookSecretName) {
+    const apiKey = envSource[apiKeyName];
+    const webhookSecret = envSource[webhookSecretName];
+    return { ...(apiKey && { apiKey }), ...(webhookSecret && { webhookSecret }) };
+}
+function providerFeatures({ stripe, dodo }, envSource) {
+    const features = [];
+    if (stripe) {
+        warnOnEmptyPriceMap("stripe", stripe.priceToTier);
+        features.push(createSubscriptionStripeFeature({
+            priceToTier: stripe.priceToTier,
+            ...(stripe.oneOffPriceIds && { oneOffPriceIds: stripe.oneOffPriceIds }),
+            ...(stripe.paymentInvoiceCreation !== undefined && {
+                paymentInvoiceCreation: stripe.paymentInvoiceCreation,
+            }),
+            ...bridgeCredentials(envSource, "STRIPE_API_KEY", "STRIPE_WEBHOOK_SECRET"),
+        }));
+    }
+    if (dodo) {
+        warnOnEmptyPriceMap("dodo", dodo.priceToTier);
+        features.push(createSubscriptionDodoFeature({
+            priceToTier: dodo.priceToTier,
+            ...(dodo.oneOffPriceIds && { oneOffPriceIds: dodo.oneOffPriceIds }),
+            ...bridgeCredentials(envSource, "DODO_PAYMENTS_API_KEY", "DODO_PAYMENTS_WEBHOOK_KEY"),
+        }));
+    }
+    return features;
+}
 export function resolveBillingOption(billing, envSource) {
-    const webhookPath = billing.stripe.webhookPath ?? SUBSCRIPTION_WEBHOOK_PATH;
+    const { stripe, dodo } = billing;
+    if (!stripe && !dodo) {
+        throw new Error("[runProdApp] billing needs at least one provider: set billing.stripe or billing.dodo.");
+    }
+    const webhookPath = stripe?.webhookPath ?? SUBSCRIPTION_WEBHOOK_PATH;
     if (!webhookPath.includes(PROVIDER_NAME_PARAM)) {
         throw new Error(`[runProdApp] billing.stripe.webhookPath "${webhookPath}" must contain ${PROVIDER_NAME_PARAM}.`);
     }
-    if (Object.keys(billing.stripe.priceToTier).length === 0) {
-        // biome-ignore lint/suspicious/noConsole: boot-time warn, no logger configured this early
-        console.warn("[runProdApp] billing.stripe.priceToTier is empty: every subscription webhook is ignored until a price maps to a tier.");
-    }
-    const apiKey = envSource["STRIPE_API_KEY"];
-    const webhookSecret = envSource["STRIPE_WEBHOOK_SECRET"];
-    const feature = createSubscriptionStripeFeature({
-        priceToTier: billing.stripe.priceToTier,
-        ...(billing.stripe.oneOffPriceIds && { oneOffPriceIds: billing.stripe.oneOffPriceIds }),
-        ...(billing.stripe.paymentInvoiceCreation !== undefined && {
-            paymentInvoiceCreation: billing.stripe.paymentInvoiceCreation,
-        }),
-        ...(apiKey && { apiKey }),
-        ...(webhookSecret && { webhookSecret }),
-    });
+    const features = providerFeatures(billing, envSource);
     const tierNames = new Set([
         billing.defaultTier,
-        ...Object.values(billing.stripe.priceToTier),
+        ...Object.values(stripe?.priceToTier ?? {}),
+        ...Object.values(dodo?.priceToTier ?? {}),
         ...(billing.tierNames ?? []),
     ]);
     const tierSync = createSubscriptionTierSync({
@@ -32,5 +58,5 @@ export function resolveBillingOption(billing, envSource) {
         onSyncError: billing.onTierSyncError ?? "fail-webhook",
         ...(billing.afterSync && { afterSync: billing.afterSync }),
     });
-    return { feature, route: tierSync.createWebhookRoute({ path: webhookPath }) };
+    return { features, route: tierSync.createWebhookRoute({ path: webhookPath }) };
 }

package/dist/boot-options/file-storage-option.js

@@ -54,17 +54,17 @@ export function resolveFileStorageOption(fileStorage, deps) {
     else {
         provider = fileStorage.provider;
     }
-    if (provider === "s3-env" && missingS3.length > 0) {
-        throw new Error(`[runProdApp] fileStorage "s3-env" is missing: ${missingS3.join(", ")}.`);
-    }
-    if (provider === "inmemory" && deps.isProduction) {
-        throw new Error('[runProdApp] fileStorage "inmemory" loses every file on restart — not allowed with NODE_ENV=production.');
-    }
     const additional = fileStorage.providers ?? [];
     const wanted = new Set([
         provider,
         ...additional.filter((entry) => !isNamedS3FileProvider(entry)),
     ]);
+    if (wanted.has("s3-env") && missingS3.length > 0) {
+        throw new Error(`[runProdApp] fileStorage "s3-env" is missing: ${missingS3.join(", ")}.`);
+    }
+    if (wanted.has("inmemory") && deps.isProduction) {
+        throw new Error('[runProdApp] fileStorage "inmemory" loses every file on restart — not allowed with NODE_ENV=production.');
+    }
     const named = additional.filter(isNamedS3FileProvider);
     assertNamedProviderNames(named);
     for (const entry of named) {