@cosmicdrift/kumiko-server-runtime 0.373.0 → 0.377.0

package/dist/run-prod-app.js

@@ -44,17 +44,14 @@ import { seedAdminGuarded, } from "@cosmicdrift/kumiko-bundled-features/auth-ema
 import { EXT_SESSION_STORE, EXT_TOKEN_VERIFIER, resolveAnonymousAccessFromRegistry, resolveTokenVerifier, } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { AUTH_MFA_FEATURE, AuthMfaHandlers, bindMfaTokenSecretsFromFeature, } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
 import { PAT_FEATURE, patRateLimitFromFeature, } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
-import { SECRETS_MASTER_KEK_ENV_KEYS } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { SESSIONS_FEATURE } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
 import { createDefaultSseBroker, createRedisLoginRateLimiter, loadJwtSecretOrKeyring, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, withFileProviderResolver, } from "@cosmicdrift/kumiko-framework/api";
-import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
+import { configureBlindIndexKey, configurePiiSubjectKms, } from "@cosmicdrift/kumiko-framework/crypto";
 import { configureEntityFieldEncryption, createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
 import { collectWriteHandlerQns, createRegistry, findTierResolverUsage, requireTierResolverPlugin, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
 import { createAllInOneEntrypoint, createApiEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
-import { inspectEnv, KumikoBootError, kmsSlotsOf, parseEnv, withOptionalEnvKeys, } from "@cosmicdrift/kumiko-framework/env";
-import { DRY_RUN_ENV_VAR, parseDryRunEnvMode, renderDryRun, renderEnvInspection, } from "@cosmicdrift/kumiko-framework/env/dry-run";
 import { createEsOperationsTable, createSeedMigrationContext, runPendingSeedMigrations, } from "@cosmicdrift/kumiko-framework/es-ops";
 import { assertSeedModeNotInProduction } from "@cosmicdrift/kumiko-framework/event-store";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
@@ -66,11 +63,11 @@ import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import { Redis } from "ioredis";
 import { applyBootSeeds } from "./boot/apply-boot-seeds.js";
 import { resolveBootCrypto } from "./boot/boot-crypto.js";
+import { runEnvGate } from "./boot/env-gate.js";
 import { jobRunLoggerCallbacks } from "./boot/job-run-logger.js";
 import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot.js";
 import { recordAppStartedOnBoot } from "./boot/record-app-started-on-boot.js";
 import { waitForDatabase, waitUntilDatabaseReachable } from "./boot/wait-for-database.js";
-import { withBootOptionEnvBlocks } from "./boot-options/option-env-schema.js";
 import { installShutdownSignals } from "./boot-options/process-signals.js";
 import { resolveBootOptionWiring } from "./boot-options/resolve-boot-options.js";
 import { assertStackBootRequirements } from "./boot-options/stack-boot-requirements.js";
@@ -88,21 +85,11 @@ import { makeSeedCreateFileRef, withSeedErrorContext, } from "./seed-dispatcher.
 import { assertSessionBootInvariants } from "./session-boot-gate.js";
 import { shouldWireProdSessions } from "./session-wiring.js";
 import { stripNoRouteMatchHeader } from "./try-hono-first.js";
+export { parseRunMode } from "./boot/env-gate.js";
 export { buildBunServeOptions } from "./bun-serve-options.js";
 export { resolveUnsubscribeWiring, } from "./resolve-unsubscribe-wiring.js";
 export { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, resolveAuthMail, } from "./run-prod-app-boot-context.js";
 export { staticCachePolicy } from "./run-prod-app-static-files.js";
-// runProdApp reads these itself, so the boot dry run lists them even when
-// the app schema leaves them out (JWT_SECRET usually comes from auth-email-password).
-const RUNTIME_REQUIRED_ENV_KEYS = ["DATABASE_URL", "REDIS_URL", "JWT_SECRET"];
-function inspectUndeclaredRuntimeEnv(declaredShape, env) {
-    return RUNTIME_REQUIRED_ENV_KEYS.filter((name) => !(name in declaredShape)).map((name) => ({
-        name,
-        klass: "required",
-        source: "server-runtime",
-        status: env[name] ? "set" : "missing",
-    }));
-}
 // Strict env-var read. Throws with a clear hint when missing — better
 // than discovering a Postgres-connection-refused 30s into the boot.
 // `src` defaults to process.env but is threaded from the caller's envSource
@@ -124,25 +111,6 @@ function readEnv(name, src = process.env) {
     const value = src[name];
     return value === undefined || value === "" ? undefined : value;
 }
-export function parseRunMode(raw) {
-    const mode = parseDryRunEnvMode(raw);
-    if (mode !== undefined)
-        return mode;
-    if (raw) {
-        // biome-ignore lint/suspicious/noConsole: boot-time warn for typo discovery
-        console.warn(`[runProdApp] ${DRY_RUN_ENV_VAR}="${raw}" unrecognized ` +
-            `(expected 1|human|json|pulumi|k8s|boot); continuing with normal boot.`);
-    }
-    return null;
-}
-function isRenderMode(mode) {
-    return mode !== null && mode !== "boot";
-}
-function defaultBootErrorReporter(err) {
-    // biome-ignore lint/suspicious/noConsole: boot-time error, no logger configured yet
-    console.error(err.format());
-    process.exit(1);
-}
 // Returned from runProdApp when KUMIKO_DRY_RUN_ENV is set AND envSource
 // was passed (= test-mode). The handle is intentionally inert — listen()
 // and stop() are no-ops; tests inspect the dry-run console output and
@@ -176,19 +144,6 @@ function warnLegacyJwtSecretOnce() {
         "that is no longer present in any in-flight token (see resolveAuthMail / " +
         "loadJwtSecretOrKeyring).");
 }
-// JS callers and apps built against older typings can still omit it.
-function requireEnvSchema(envSchema) {
-    if (envSchema === undefined) {
-        throw new KumikoBootError([
-            {
-                name: "envSchema",
-                kind: "missing",
-                message: "runProdApp needs envSchema. Pass composeEnvSchema({ core: frameworkCoreEnvSchema, features, extend }): composeEnvSchema from @cosmicdrift/kumiko-framework/env, frameworkCoreEnvSchema from @cosmicdrift/kumiko-dev-server/env-schema, features the same list as runProdApp's.",
-            },
-        ]);
-    }
-    return envSchema;
-}
 export async function runProdApp(options) {
     assertSeedModeNotInProduction();
     // 0. Env-Schema validation + dry-run modes. Runs FIRST so:
@@ -208,88 +163,10 @@ export async function runProdApp(options) {
     //    at parse-time before the polyfill loads. Plain strings + .regex /
     //    .min / .email / .url cover every env-var shape we've actually
     //    needed in 9.1's audit (37 references, 25 distinct vars).
-    const rawEnvSource = options.envSource ?? process.env;
-    const runMode = parseRunMode(rawEnvSource[DRY_RUN_ENV_VAR]);
-    const composedEnvSchema = withBootOptionEnvBlocks(requireEnvSchema(options.envSchema), options);
-    const effectiveEnvSchema = options.masterKey
-        ? withOptionalEnvKeys(composedEnvSchema.schema, SECRETS_MASTER_KEK_ENV_KEYS)
-        : composedEnvSchema.schema;
-    const reportBootError = (err) => {
-        const reporter = options.bootErrorReporter ?? defaultBootErrorReporter;
-        reporter(err);
-    };
-    const validateEnv = (source) => {
-        try {
-            parseEnv(effectiveEnvSchema, source, {
-                sources: composedEnvSchema.sources,
-                ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
-            });
-        }
-        catch (err) {
-            if (err instanceof KumikoBootError)
-                reportBootError(err);
-            throw err;
-        }
-    };
-    if (isRenderMode(runMode)) {
-        // biome-ignore lint/suspicious/noConsole: dry-run output IS the deliverable
-        console.log(renderDryRun(composedEnvSchema, runMode, {
-            ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
-            sources: composedEnvSchema.sources,
-        }));
-        // Tests inject envSource and want a return-value, not exit. Detecting
-        // "this is a test" via envSource is brittle; instead exit when running
-        // against the real process.env (the deploy-flow), return otherwise.
-        if (options.envSource === undefined) {
-            process.exit(0);
-        }
+    const envGate = await runEnvGate(options, "runProdApp");
+    if (envGate.kind === "stopped")
         return makeDryRunHandle();
-    }
-    if (runMode === "boot") {
-        const inspection = [
-            ...inspectEnv(effectiveEnvSchema, rawEnvSource, { sources: composedEnvSchema.sources }),
-            ...inspectUndeclaredRuntimeEnv(effectiveEnvSchema.shape, rawEnvSource),
-        ];
-        // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
-        console.log(renderEnvInspection(inspection));
-        if (inspection.some((row) => row.status === "invalid")) {
-            // Missing rows go into the same report: the run fails anyway, so the
-            // operator sees every variable to fix in one pass.
-            reportBootError(new KumikoBootError(inspection.flatMap((row) => row.status === "invalid" || row.status === "missing"
-                ? [
-                    {
-                        name: row.name,
-                        kind: row.status,
-                        message: row.message ?? (row.status === "missing" ? "missing" : "invalid value"),
-                        source: row.source,
-                    },
-                ]
-                : [])));
-            return makeDryRunHandle();
-        }
-        // A build pipeline has no deploy secrets: the inventory is the result,
-        // and the wiring check below needs every value, so it stops here.
-        if (inspection.some((row) => row.status === "missing")) {
-            if (options.envSource === undefined) {
-                process.exit(0);
-            }
-            return makeDryRunHandle();
-        }
-    }
-    // boot-mode with a complete env AND normal boot run the full validation,
-    // including object-level refinements the per-field check skips.
-    validateEnv(rawEnvSource);
-    // Slots the schema marks `kms` are decrypted once here so every consumer
-    // below (boot probe, master-key keyring, config) sees the same resolved env.
-    const decryptedEnvSource = await resolvePlatformKeks(rawEnvSource, {
-        slots: kmsSlotsOf(composedEnvSchema.schema),
-        logPrefix: "[runProdApp]",
-    });
-    // The first parse relaxes ciphertext-only slots, so their decrypted
-    // plaintext never met the slot's own validators (.regex/.min/.refine).
-    if (kmsSlotsOf(composedEnvSchema.schema).some((slot) => rawEnvSource[slot] === undefined && decryptedEnvSource[slot] !== undefined)) {
-        validateEnv(decryptedEnvSource);
-    }
+    const { runMode, decryptedEnvSource } = envGate;
     // Stacks whose boot options are missing and the declarative boot options
     // (mail, kmsMode, fileStorage, billing, demoMode, seed shortcuts) fail here, before any connection. Their defaults sit under
     // the env so an explicitly set variable wins.
@@ -432,9 +309,8 @@ export async function runProdApp(options) {
     const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
     await waitForDatabase(db, { processName: "runProdApp" });
     // Sprint-8a Tier-Composition auto-wire: scan features for a
-    // tenantTierResolver-extension. If found AND user didn't supply own
-    // effectiveFeatures, build the resolver here (db + registry are
-    // available) before the dispatcher is constructed. App-Author sees
+    // tenantTierResolver-extension. If found, build the resolver here (db +
+    // registry are available) before the dispatcher is constructed. App-Author sees
     // nothing — `createTierEngineFeature(opts)` mounts + framework auto-wires.
     // One bus per process: the tier resolver, the dispatcher and the file-provider
     // resolver all subscribe to it (invalidation across the API pods).
@@ -442,16 +318,23 @@ export async function runProdApp(options) {
         redisUrl,
         clientOptions: redisClientOptionsFromEnv(envSource),
     });
-    let resolvedEffectiveFeatures = options.effectiveFeatures;
-    if (resolvedEffectiveFeatures === undefined) {
-        const tierResolverUsage = findTierResolverUsage(features);
-        if (tierResolverUsage) {
-            resolvedEffectiveFeatures = await requireTierResolverPlugin(tierResolverUsage).build({
-                db,
-                registry,
-                cacheSync,
-            });
-        }
+    let resolvedEffectiveFeatures;
+    const tierResolverUsage = findTierResolverUsage(features);
+    if (tierResolverUsage) {
+        resolvedEffectiveFeatures = await requireTierResolverPlugin(tierResolverUsage).build({
+            db,
+            registry,
+            cacheSync,
+        });
+    }
+    if (bootOptionWiring.featureToggles) {
+        const bound = await bootOptionWiring.featureToggles.bind({
+            db,
+            registry,
+            cacheSync,
+            tierResolver: resolvedEffectiveFeatures,
+        });
+        resolvedEffectiveFeatures = bound.resolver;
     }
     // 5. Schema-Drift-Gate (drizzle-frei, kumiko/migrations). `kumiko schema
     //    apply` läuft als Deploy-Step VOR dem Container-Rollout. Boot prüft nur:
@@ -502,7 +385,15 @@ export async function runProdApp(options) {
     // wins), which is exactly how fw#2630's cross-replica fanout fix shipped
     // without ever taking effect in production.
     const { sseBroker, ownedRedisSseBroker } = createDefaultSseBroker(envSource);
-    const deps = { db, redis, registry, sseBroker, env: envSource };
+    const deps = {
+        db,
+        redis,
+        registry,
+        sseBroker,
+        env: envSource,
+        ...(bootCrypto.masterKeyProvider && { masterKeyProvider: bootCrypto.masterKeyProvider }),
+        ...(bootCrypto.configCipher && { configEncryption: bootCrypto.configCipher }),
+    };
     const resolvedExtraContext = typeof options.extraContext === "function"
         ? options.extraContext(deps)
         : (options.extraContext ?? {});
@@ -534,6 +425,7 @@ export async function runProdApp(options) {
         ...(bootKms.kms && { kms: bootKms.kms }),
         ...(bootLogger && { log: bootLogger }),
         ...(unsubscribeLinks && { unsubscribeLinks }),
+        ...(options.appOverrides && { appOverrides: options.appOverrides }),
     });
     const extraContext = {
         ...addConfigAccessorFactory({ ...autoExtraContext, ...resolvedExtraContext }, registry),
@@ -776,6 +668,8 @@ export async function runProdApp(options) {
             db,
             redis,
             registry,
+            ...(bootCrypto.masterKeyProvider && { masterKeyProvider: bootCrypto.masterKeyProvider }),
+            ...(bootCrypto.configCipher && { configEncryption: bootCrypto.configCipher }),
             metricsFor: createMetricsForFactory(entrypoint.observability.meter),
             dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
             dispatchSystemQuery: makeDispatchSystemQuery(entrypoint.dispatcher),
@@ -820,7 +714,14 @@ export async function runProdApp(options) {
     if (seedDispatcher && seedContext) {
         const createFileRef = makeSeedCreateFileRef({ db, registry, context: seedContext });
         for (const seed of customSeeds) {
-            await seed({ db, registry, dispatcher: seedDispatcher, createFileRef });
+            await seed({
+                db,
+                registry,
+                dispatcher: seedDispatcher,
+                createFileRef,
+                ...(bootCrypto.masterKeyProvider && { masterKeyProvider: bootCrypto.masterKeyProvider }),
+                ...(bootCrypto.configCipher && { configEncryption: bootCrypto.configCipher }),
+            });
         }
     }
     // ES-Operations / Seed-Migrations (Phase 1). Läuft NACH applyBootSeeds +

package/dist/run-worker-app.d.ts

@@ -1,13 +1,18 @@
 import type { ServerOptions } from "@cosmicdrift/kumiko-framework/api";
 import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { EffectiveFeaturesResolver, FeatureDefinition, Registry, ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
+import type { FeatureDefinition, Registry, ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
 import type { WorkerEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
+import type { ComposedEnvSchema, KumikoBootError } from "@cosmicdrift/kumiko-framework/env";
 import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
 import { type ObservabilityOptions, type ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
 import type { MasterKeyProvider, SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
 import { type WorkerMetricsOptions, type WorkerMetricsServer } from "./boot/worker-metrics-server.ts";
+import type { BillingBootOption } from "./boot-options/billing-option.ts";
+import type { FileStorageBootOption } from "./boot-options/file-storage-option.ts";
+import type { KmsMode } from "./boot-options/kms-mode.ts";
+import type { MailBootOption } from "./boot-options/mail-option.ts";
 import { type SystemWireDeps } from "./extra-routes-deps.ts";
 export type WorkerContextOption = Record<string, unknown> | ((deps: WorkerDeps) => Record<string, unknown>);
 export type WorkerDeps = {
@@ -24,7 +29,7 @@ export type WorkerWireDeps = SystemWireDeps & {
     readonly lifecycle: WorkerEntrypoint["lifecycle"];
     /** The worker's ctx.secrets — what `createInboundMailSupervisor` needs as
      *  `providerCtx.secrets` (the IMAP provider reads credentials through it,
-     *  with `_userId` set to a system identity for the audit trail). Undefined
+     *  with `auditUserId` set to a system identity for the audit trail). Undefined
      *  when the secrets feature is not mounted or no master key is available. */
     readonly secrets?: SecretsContext;
 };
@@ -79,8 +84,22 @@ export type RunWorkerAppOptions = {
      *  `entrypoint.start()` — the hook itself is responsible for starting
      *  its component and registering a shutdown hook on `lifecycle`. */
     readonly wireComponents?: (deps: WorkerWireDeps) => Promise<void> | void;
-    /** Feature-toggle resolver (see RunProdAppOptions["effectiveFeatures"]). */
-    readonly effectiveFeatures?: EffectiveFeaturesResolver;
+    /** Same as RunProdAppOptions["mail"]: mounts channel-email so the worker delivers what the API queues. */
+    readonly mail?: MailBootOption;
+    /** Same as RunProdAppOptions["fileStorage"]: mounts the file providers the worker's file jobs use. */
+    readonly fileStorage?: FileStorageBootOption;
+    /** Same as RunProdAppOptions["kmsMode"]; cannot be combined with `kms` / `blindIndexKey` / `allowPlaintextPii`. */
+    readonly kmsMode?: KmsMode;
+    /** Same as RunProdAppOptions["billing"]: mounts subscription-stripe so the registry matches the API. The webhook route belongs to the API process. */
+    readonly billing?: BillingBootOption;
+    /** Same as RunProdAppOptions["featureToggles"]: mounts feature-toggles and layers the operator switches over the tier resolver. */
+    readonly featureToggles?: boolean;
+    /** Composed env schema (see RunProdAppOptions["envSchema"]). With it the worker validates its env,
+     *  derives the KMS slots from it (`kmsSlots` is ignored) and understands every `KUMIKO_DRY_RUN_ENV`
+     *  mode. Without it only `KUMIKO_DRY_RUN_ENV=boot` is available. */
+    readonly envSchema?: ComposedEnvSchema;
+    readonly pulumiPrefix?: string;
+    readonly bootErrorReporter?: (err: KumikoBootError) => void;
     /** Override `process.env` for env-validation (see
      *  RunProdAppOptions["envSource"]). */
     readonly envSource?: Record<string, string | undefined>;

package/dist/run-worker-app.js

@@ -16,10 +16,13 @@
 //   DATABASE_URL, REDIS_URL, JWT_SECRET — PORT is not needed.
 import { assertSeedModeNotInProduction } from "@cosmicdrift/kumiko-framework/event-store";
 import { createMetricsForFactory, } from "@cosmicdrift/kumiko-framework/observability";
+import { runEnvGate } from "./boot/env-gate.js";
 import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot.js";
 import { recordAppStartedOnBoot } from "./boot/record-app-started-on-boot.js";
-import { bootWorkerProcess, resolveWorkerEnvSource } from "./boot/worker-boot-core.js";
+import { bootWorkerProcess, resolveWorkerEnvSource, } from "./boot/worker-boot-core.js";
 import { startWorkerMetricsServer, } from "./boot/worker-metrics-server.js";
+import { resolveBootOptionWiring } from "./boot-options/resolve-boot-options.js";
+import { assertStackBootRequirements } from "./boot-options/stack-boot-requirements.js";
 import { makeDispatchSystemQuery, makeDispatchSystemWrite, } from "./extra-routes-deps.js";
 function makeBootModeHandle() {
     return {
@@ -29,14 +32,53 @@ function makeBootModeHandle() {
         stop: async () => { },
     };
 }
+// undefined: a dry-run mode already produced its output and the worker must not boot.
+async function resolveGatedEnvSource(options) {
+    if (!options.envSchema)
+        return resolveWorkerEnvSource(options, "runWorkerApp");
+    const envGate = await runEnvGate({ ...options, envSchema: options.envSchema }, "runWorkerApp");
+    return envGate.kind === "stopped" ? undefined : envGate.decryptedEnvSource;
+}
+// The API enforces the same requirement; a worker that skipped it would keep running
+// jobs and event handlers of features an operator switched off.
+function assertWorkerStackRequirements(options) {
+    assertStackBootRequirements({ features: options.features, ...(options.featureToggles && { featureToggles: true }) }, ["featureToggles"]);
+}
 export async function runWorkerApp(options) {
     assertSeedModeNotInProduction();
-    const envSource = await resolveWorkerEnvSource(options, "runWorkerApp");
+    const resolvedEnvSource = await resolveGatedEnvSource(options);
+    if (resolvedEnvSource === undefined)
+        return makeBootModeHandle();
     // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
     console.log("[runWorkerApp] booting Kumiko worker…");
-    const boot = await bootWorkerProcess(options, envSource, { processName: "runWorkerApp" });
-    if (boot.kind === "dry-run")
+    assertWorkerStackRequirements(options);
+    const wiring = await resolveBootOptionWiring(options, resolvedEnvSource);
+    const envSource = Object.keys(wiring.envDefaults).length > 0
+        ? { ...wiring.envDefaults, ...resolvedEnvSource }
+        : resolvedEnvSource;
+    let boot;
+    try {
+        boot = await bootWorkerProcess({
+            ...options,
+            features: [...options.features, ...wiring.features],
+            ...(wiring.kms.kms && { kms: wiring.kms.kms }),
+            ...(wiring.kms.blindIndexKey !== undefined && { blindIndexKey: wiring.kms.blindIndexKey }),
+            ...(wiring.kms.allowPlaintextPii !== undefined && {
+                allowPlaintextPii: wiring.kms.allowPlaintextPii,
+            }),
+        }, envSource, {
+            processName: "runWorkerApp",
+            ...(wiring.featureToggles && { featureToggles: wiring.featureToggles }),
+        });
+    }
+    catch (error) {
+        await wiring.kms.close().catch(() => { });
+        throw error;
+    }
+    if (boot.kind === "dry-run") {
+        await wiring.kms.close();
         return makeBootModeHandle();
+    }
     const { db, redis, registry, entrypoint } = boot;
     // Metrics first: a port clash must fail the boot before start() begins
     // consuming jobs/events. boot.close() runs the "metrics-server" shutdown
@@ -52,11 +94,15 @@ export async function runWorkerApp(options) {
         // The boot failure is the actionable error; a close failure on a
         // half-started worker must not replace it.
         await boot.close().catch(() => { });
+        await wiring.kms.close().catch(() => { });
         throw error;
     }
     const handle = {
         entrypoint,
-        stop: boot.close,
+        stop: async () => {
+            await boot.close();
+            await wiring.kms.close();
+        },
         ...(metricsServer && { metricsServer }),
     };
     await recordAppStartedOnBoot({ db, envSource });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.373.0",
+  "version": "0.377.0",
   "description": "Production server-boot runtime for Kumiko apps: connections, schema-drift-gate, seeds, lifecycle, graceful shutdown. Symmetric to kumiko-dev-server's runDevApp, without dev/scaffold tooling.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -88,19 +88,18 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.373.0",
-    "@cosmicdrift/kumiko-framework": "0.373.0",
-    "@cosmicdrift/kumiko-headless": "0.373.0",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.373.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.373.0",
-    "@cosmicdrift/kumiko-types": "0.373.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.377.0",
+    "@cosmicdrift/kumiko-framework": "0.377.0",
+    "@cosmicdrift/kumiko-renderer": "0.377.0",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.377.0",
+    "@cosmicdrift/kumiko-types": "0.377.0",
     "bun-types": "^1.3.13",
     "ioredis": "^5.10.1",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.373.0"
+    "@cosmicdrift/kumiko-testing": "0.377.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/changes.json

@@ -1,4 +1,55 @@
 [
+  {
+    "version": "0.376.0",
+    "type": "breaking",
+    "title": "effectiveFeatures is gone from runProdApp, runDevApp and runWorkerApp",
+    "detail": "The effectiveFeatures option of the boot functions is removed. Global operator switches come from the featureToggles option, tier gating from the tier-engine feature, which the boot functions wire themselves.",
+    "migration": "Replace a hand-built effectiveFeatures resolver with featureToggles true (global switches) and mount createTierEngineFeature for tier gating. A custom resolver that did neither has no replacement on the boot functions; wire it through createKumikoServer or setupTestStack in tests. The boot functions now abort when the option is still passed, because an ignored option would drop an operator kill-switch silently; the same goes for a feature-toggles feature in features without the featureToggles option, or with it set (the option mounts the feature)."
+  },
+  {
+    "version": "0.376.0",
+    "type": "breaking",
+    "title": "The default mail resolver only reaches members of the notifying tenant",
+    "detail": "The default resolveEmail of the mail boot option returns an address for a notification from a tenant other than the system tenant only if the user is a member of that tenant or holds the SystemAdmin role in the stored user row. Everyone else resolves to null and the mail is skipped. The new option mail.recipientScope takes \"membership\" (default) or \"any\", which restores the old behaviour of reaching every user. EmailChannelOptions resolveEmail now receives the tenant database as TenantDb instead of unknown.",
+    "migration": "Apps that notify users outside the notifying tenant on purpose, for example merchants reached from a SystemAdmin context, set mail recipientScope to \"any\" or keep their own resolveEmail. Apps whose notifications go to members of the active tenant need no change. Known consumers on the default: offlot-app (main.ts) reaches merchants and SystemAdmins across tenants and needs recipientScope any; publicstatus (main.ts), show-pony, solon (main.ts) and kumiko-studio (main.ts) take the default, which fits notifications to members of the active tenant. money-horse and phronexsis keep their own resolveEmail. Per-app resolvers that only copied the membership check can be deleted. A custom resolveEmail that cast ctx.db can drop the cast."
+  },
+  {
+    "version": "0.376.0",
+    "type": "improvement",
+    "title": "runDevApp and runWorkerApp take the declarative boot options",
+    "detail": "mail, fileStorage, kmsMode, billing, seeds, demoMode, envSchema and featureToggles work in runDevApp, and mail, fileStorage, kmsMode, billing, featureToggles and envSchema in runWorkerApp, through the same resolve functions as runProdApp. The worker honours KUMIKO_DRY_RUN_ENV with an env schema. A stack that sets runSingleInstance false only warns when no worker mounts the features.",
+    "migration": "RunDevAppOptions.seeds is now `readonly SeedFn[] | RunDevAppSeedsConfig`. Code that spreads `seeds` from an object typed as RunDevAppOptions no longer type-checks; declare that object with `satisfies RunDevAppOptions` so the array type survives, or build the seed list separately. An app that lists createFeatureTogglesFeature() in the features passed to runDevApp or runProdApp removes it there and sets `featureToggles: true`."
+  },
+  {
+    "version": "0.376.0",
+    "type": "improvement",
+    "title": "featureToggles, appOverrides and secrets in boot deps",
+    "detail": "featureToggles true mounts feature-toggles and layers the global switches over the tier resolver in runProdApp, runDevApp and runWorkerApp. appOverrides sets tenant-model, branding and seo defaults. masterKeyProvider and configEncryption reach extraContext factories, system wiring and seed functions, so an app no longer resolves its KEK a second time."
+  },
+  {
+    "version": "0.376.0",
+    "type": "improvement",
+    "title": "Boot errors for removed and half-wired feature toggles",
+    "detail": "runProdApp, runDevApp and runWorkerApp abort when the removed effectiveFeatures option is still passed, and when feature-toggles sits in features without the featureToggles option. runWorkerApp now enforces a stack that expects featureToggles, so a worker cannot keep running jobs and event handlers of features an operator switched off."
+  },
+  {
+    "version": "0.376.0",
+    "type": "improvement",
+    "title": "Named S3 provider names are validated at boot",
+    "detail": "fileStorage.providers refuses the names s3-env, s3 and inmemory, which the bundled providers register, and a name listed twice. A tenant admin can still select any mounted provider through the file-foundation provider config, so name a provider only if every tenant may use its bucket."
+  },
+  {
+    "version": "0.376.0",
+    "type": "improvement",
+    "title": "Named S3 providers and a corrected SMTP_HOST description",
+    "detail": "fileStorage.providers takes entries with name, envPrefix and lazy, each validated through createS3EnvSchema with its own prefix. The SMTP_HOST description in the env schema of mail smtp-env now says the variable is required."
+  },
+  {
+    "version": "0.376.0",
+    "type": "improvement",
+    "title": "Demo-mode accounts can carry a label",
+    "detail": "demoMode.notice.accounts entries may be { role, label? } next to a bare role; the GET /demo-mode payload then lists { role, label?, email, password } so the banner can name each login. Bare roles behave as before."
+  },
   {
     "version": "0.372.0",
     "type": "fix",