@cosmicdrift/kumiko-server-runtime 0.340.0 → 0.341.0

package/README.md

@@ -12,4 +12,22 @@ bun add @cosmicdrift/kumiko-server-runtime
 import { runProdApp } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
 ```
 
+## Bundled read-only assets
+
+Files your own build ships (fonts, templates) are declared in `package.json` next to `kumiko.clientEntries`:
+
+```json
+"kumiko": { "assets": [{ "name": "inter-bold.ttf", "source": "packages/site-kit/fonts/inter-bold.ttf" }] }
+```
+
+`source` is relative to the app's `package.json` and must stay inside it; `name` matches `/^[A-Za-z0-9][A-Za-z0-9._-]*$/`. `buildProdBundle` copies each asset to `dist/kumiko-bundled-assets/<name>`, a folder the static file server never serves. Read them without `node:fs`:
+
+```ts
+import { readBundledAsset } from "@cosmicdrift/kumiko-server-runtime";
+
+const bytes = await readBundledAsset("inter-bold.ttf"); // dist copy in prod, declared source in dev
+```
+
+`resolveBundledAsset(name)` returns the absolute path for libraries that only take a path.
+
 Documentation: https://kumiko.rocks

package/dist/boot/worker-boot-core.d.ts

@@ -0,0 +1,36 @@
+import type { AuthEmailPasswordOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type FeatureDefinition, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { type WorkerEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { Redis } from "ioredis";
+import type { RunWorkerAppOptions } from "../run-worker-app.js";
+export type WorkerBootCoreOptions = Omit<RunWorkerAppOptions, "wireComponents">;
+export type WorkerBootProfile = {
+    /** Log prefix and requireEnv context, e.g. "runWorkerApp". */
+    readonly processName: string;
+    /** Resolved auth block for composeFeatures; implies includeBundled. */
+    readonly authOptions?: AuthEmailPasswordOptions;
+    /** One-shot process: its job queue is not drained after exit, so ctx.notify
+     *  sends queued channels inline. */
+    readonly deliverQueuedInline?: boolean;
+};
+export type BootedWorkerProcess = {
+    readonly kind: "booted";
+    readonly db: DbConnection;
+    readonly redis: Redis;
+    readonly registry: Registry;
+    readonly features: readonly FeatureDefinition[];
+    readonly envSource: Record<string, string | undefined>;
+    readonly entrypoint: WorkerEntrypoint;
+    /** ctx.secrets as wired into the entrypoint (auto-wired when the secrets
+     *  feature is mounted and a master key exists, or from `extraContext`). */
+    readonly secrets?: SecretsContext;
+    readonly close: () => Promise<void>;
+};
+export type WorkerBootResult = {
+    readonly kind: "dry-run";
+    readonly envSource: Record<string, string | undefined>;
+} | BootedWorkerProcess;
+export declare function resolveWorkerEnvSource(options: Pick<WorkerBootCoreOptions, "envSource" | "kmsSlots">, processName: string): Promise<Record<string, string | undefined>>;
+export declare function bootWorkerProcess(options: WorkerBootCoreOptions, envSource: Record<string, string | undefined>, profile: WorkerBootProfile): Promise<WorkerBootResult>;

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

@@ -0,0 +1,183 @@
+// Shared boot core of the HTTP-less processes (runWorkerApp, runBootstrap):
+// env fail-fast, Temporal polyfill, composeFeatures/registry, PII invariants,
+// dry-run exit, KMS health gate, connections, schema-drift gate, boot-crypto
+// and extraContext. Both processes must write rows the API can read, so they
+// 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, } from "@cosmicdrift/kumiko-framework/db";
+import { createRegistry, findTierResolverUsage, 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";
+import { createRedisCacheSyncBus, redisClientOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/redis";
+import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
+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 { addConfigAccessorFactory, buildBootExtraContext } from "../run-prod-app-boot-context.js";
+import { resolveBootCrypto } from "./boot-crypto.js";
+import { jobRunLoggerCallbacks } from "./job-run-logger.js";
+import { assertWorkerMetricsOptions } from "./worker-metrics-server.js";
+function isSecretsContext(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return ["get", "has", "set", "delete"].every((method) => typeof value[method] === "function");
+}
+export async function resolveWorkerEnvSource(options, processName) {
+    const rawEnvSource = options.envSource ?? process.env;
+    return options.kmsSlots
+        ? await resolvePlatformKeks(rawEnvSource, {
+            slots: options.kmsSlots,
+            logPrefix: `[${processName}]`,
+        })
+        : rawEnvSource;
+}
+async function buildTierEffectiveFeatures(features, db, registry, cacheSync) {
+    const tierResolverUsage = findTierResolverUsage(features);
+    if (!tierResolverUsage)
+        return undefined;
+    const plugin = tierResolverUsage.options;
+    return plugin.build({ db, registry, cacheSync });
+}
+async function assertWorkerSchemaCurrent(db, migrationsDir, processName) {
+    const dir = migrationsDir ?? "./kumiko/migrations";
+    // biome-ignore lint/suspicious/noConsole: boot-time progress hint
+    console.log(`[${processName}] checking schema drift (${dir})…`);
+    try {
+        await assertKumikoSchemaCurrent(db, dir);
+    }
+    catch (err) {
+        if (err instanceof SchemaDriftError) {
+            // biome-ignore lint/suspicious/noConsole: terminal error message
+            console.error(`\n[${processName}] BOOT ABORTED — ${err.message}\n`);
+        }
+        throw err;
+    }
+}
+export async function bootWorkerProcess(options, envSource, profile) {
+    const { processName } = profile;
+    // Polyfill before anything else (fw#1725): 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();
+    const databaseUrl = requireEnv("DATABASE_URL", envSource, processName);
+    const redisUrl = requireEnv("REDIS_URL", envSource, processName);
+    const jwtSecretOrKeyring = loadJwtSecretOrKeyring(envSource);
+    // MUST be composed with the same `includeBundled` as the API process.
+    const includeBundled = !!options.includeBundled || profile.authOptions !== undefined;
+    const features = composeFeatures(options.features, {
+        includeBundled,
+        ...(profile.authOptions && { authOptions: profile.authOptions }),
+    });
+    validateBoot(features, { env: envSource, ...options.validateBootOptions });
+    warnIfNonUtcServerTimeZone();
+    assertWorkerMetricsOptions(options.metrics, options.observability, processName);
+    assertPiiBootInvariants(features, {
+        kms: options.kms,
+        blindIndexKey: options.blindIndexKey,
+        allowPlaintextPii: options.allowPlaintextPii,
+        mode: "prod",
+    });
+    const registry = createRegistry(features);
+    if (envSource["KUMIKO_DRY_RUN_ENV"] === "boot") {
+        // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
+        console.log(`[${processName}] boot validation OK (${features.length} features, ${registry.features.size} registry entries)`);
+        if (options.envSource === undefined) {
+            process.exit(0);
+        }
+        return { kind: "dry-run", envSource };
+    }
+    // Before the connections, so an abort leaks nothing.
+    if (options.kms) {
+        const kmsHealth = await options.kms.health();
+        if (!kmsHealth.ok) {
+            throw new Error(`[${processName}] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`);
+        }
+    }
+    const { db, close: closeDb } = createDbConnection(databaseUrl);
+    const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
+    const cacheSync = createRedisCacheSyncBus({
+        redisUrl,
+        clientOptions: redisClientOptionsFromEnv(envSource),
+    });
+    const resolvedEffectiveFeatures = options.effectiveFeatures ??
+        (await buildTierEffectiveFeatures(features, db, registry, cacheSync));
+    if (options.migrations !== false) {
+        try {
+            await assertWorkerSchemaCurrent(db, options.migrations?.dir, processName);
+        }
+        catch (err) {
+            await closeDb();
+            redis.disconnect();
+            await cacheSync.close();
+            throw err;
+        }
+    }
+    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
+    // rows the API can no longer read (different cipher, missing blind index).
+    const deps = { db, redis, registry };
+    const resolvedExtraContext = typeof options.extraContext === "function"
+        ? options.extraContext(deps)
+        : (options.extraContext ?? {});
+    const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
+    configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
+    configurePiiSubjectKms(options.kms);
+    configureBlindIndexKey(options.blindIndexKey);
+    const autoExtraContext = buildBootExtraContext({
+        db,
+        features,
+        envSource,
+        registry,
+        hasAuth: includeBundled,
+        crypto: bootCrypto,
+        ...(options.kms && { kms: options.kms }),
+        ...(profile.deliverQueuedInline === true && { deliverQueuedInline: true }),
+    });
+    const extraContext = addConfigAccessorFactory({ ...autoExtraContext, ...resolvedExtraContext }, registry);
+    const jobLogger = jobRunLoggerCallbacks(registry, db);
+    const entrypoint = createWorkerEntrypoint({
+        registry,
+        context: { db, redis, entityCache, registry, ...extraContext },
+        jwtSecret: jwtSecretOrKeyring,
+        dispatcherOptions: {
+            idempotency,
+            cacheSync,
+            ...(resolvedEffectiveFeatures && { effectiveFeatures: resolvedEffectiveFeatures }),
+        },
+        eventDedup,
+        ...(options.observability && { observability: options.observability }),
+        ...(options.observabilityOptions && { observabilityOptions: options.observabilityOptions }),
+        redisUrl,
+        ...jobLogger,
+        ...(options.jobs?.queueNamePrefix !== undefined && {
+            queueNamePrefix: options.jobs.queueNamePrefix,
+        }),
+        ...(options.jobs?.getActiveTenantIds !== undefined && {
+            getActiveTenantIds: options.jobs.getActiveTenantIds,
+        }),
+        ...(options.eventDispatcher && { eventDispatcher: options.eventDispatcher }),
+    });
+    entrypoint.lifecycle.registerShutdownHook("workerCacheSync", async () => {
+        await cacheSync.close();
+    });
+    return {
+        kind: "booted",
+        db,
+        redis,
+        registry,
+        features,
+        envSource,
+        entrypoint,
+        ...(isSecretsContext(extraContext["secrets"]) && { secrets: extraContext["secrets"] }),
+        close: async () => {
+            await entrypoint.stop();
+            await closeDb();
+            redis.disconnect();
+        },
+    };
+}

package/dist/boot/worker-metrics-server.d.ts

@@ -0,0 +1,14 @@
+import { type MetricsRouteOptions } from "@cosmicdrift/kumiko-framework/api";
+import type { WorkerEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
+import type { ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
+export type WorkerMetricsOptions = MetricsRouteOptions & {
+    /** Port of the scrape server. 0 picks a free port (tests). */
+    readonly port: number;
+};
+export type WorkerMetricsServer = {
+    readonly port: number;
+};
+/** Fails the boot (also under KUMIKO_DRY_RUN_ENV=boot) on a metrics config
+ *  that would otherwise only surface as a 503 on the first scrape. */
+export declare function assertWorkerMetricsOptions(metrics: WorkerMetricsOptions | undefined, observability: ObservabilityProvider | undefined, processName: string): void;
+export declare function startWorkerMetricsServer(metrics: WorkerMetricsOptions, entrypoint: WorkerEntrypoint): WorkerMetricsServer;

package/dist/boot/worker-metrics-server.js

@@ -0,0 +1,25 @@
+// /metrics for HTTP-less worker pods: the worker entrypoint has no Hono app,
+// so scraping needs its own tiny server on a dedicated port.
+import { createMetricsApp, isPrometheusMeter, } from "@cosmicdrift/kumiko-framework/api";
+/** Fails the boot (also under KUMIKO_DRY_RUN_ENV=boot) on a metrics config
+ *  that would otherwise only surface as a 503 on the first scrape. */
+export function assertWorkerMetricsOptions(metrics, observability, processName) {
+    // skip: metrics not configured, nothing to validate
+    if (!metrics)
+        return;
+    if (!Number.isInteger(metrics.port) || metrics.port < 0 || metrics.port > 65535) {
+        throw new Error(`[${processName}] metrics.port must be an integer between 0 and 65535, got ${metrics.port}`);
+    }
+    if (!observability || !isPrometheusMeter(observability.meter)) {
+        throw new Error(`[${processName}] metrics is set but observability has no PrometheusMeter — pass observability: { ...createNoopProvider(), meter: createPrometheusMeter() }`);
+    }
+}
+export function startWorkerMetricsServer(metrics, entrypoint) {
+    const app = createMetricsApp(entrypoint.observability.meter, metrics);
+    const server = Bun.serve({ port: metrics.port, fetch: app.fetch });
+    entrypoint.lifecycle.registerShutdownHook("metrics-server", async () => {
+        await server.stop();
+    });
+    // Bun.serve with a bound TCP port always reports one.
+    return { port: server.port ?? metrics.port };
+}

package/dist/build-prod-bundle.js

@@ -36,6 +36,7 @@
 //       <chunk>-<hash>.js     ← split chunks
 //       styles-<hash>.css     ← Tailwind output
 //       <asset>-<hash>.<ext>  ← imported file-loader assets
+//     kumiko-bundled-assets/  ← package.json "kumiko.assets", never served over HTTP
 //     manifest.json           ← logical → hashed-URL mapping
 //     <public/* 1:1>          ← favicon.ico, robots.txt, og-image.png, …
 //
@@ -53,6 +54,7 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isPlainObject, parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
 import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import { Temporal } from "temporal-polyfill";
+import { BUNDLED_ASSETS_DIST_DIR, readBundledAssetDeclarations, resolveBundledAssetSource, } from "./bundled-assets.js";
 import { RENDERER_WEB_FONT_FILE_PATTERN, RENDERER_WEB_FONTS_DIST_DIR, resolveRendererWebFontsDir, } from "./renderer-web-fonts.js";
 import { canResolveTailwindStylesheet, resolveTailwindCli } from "./resolve-tailwind-cli.js";
 // Bun-Runtime-Check als module-level Konstante: alle Build-Schritte
@@ -105,6 +107,8 @@ export async function buildProdBundle(options = {}) {
     const stylesheet = resolveStylesheetEntry(cwd, firstClientSource, options.stylesheet);
     const publicDir = resolve(cwd, "public");
     const hasPublicDir = existsSync(publicDir);
+    // Validated before the clean step so a bad declaration cannot leave a wiped dist/.
+    const bundledAssets = readBundledAssetDeclarations(cwd);
     if (clientEntries.length === 0 && !hasPublicDir) {
         throw new Error(`[kumiko build] nothing to build in ${cwd} — expected one of: ` +
             `package.json "kumiko.clientEntry"/"kumiko.clientEntries", src/client.tsx, public/`);
@@ -143,6 +147,9 @@ export async function buildProdBundle(options = {}) {
     if (hasPublicDir) {
         await copyPublicFolder(publicDir, outDir, templateBasenames);
     }
+    // 5a. Declared read-only assets (package.json "kumiko.assets"), copied after
+    //     public/ so a same-named public file cannot shadow them.
+    await copyBundledAssets(cwd, outDir, bundledAssets);
     // 5b. Build-Identität: Hash über die content-gehashten Asset-URLs +
     //     lesbarer Zeitstempel. Wird in index.html gebacken und als
     //     build-info.json geschrieben (Update-Awareness, default an).
@@ -483,6 +490,20 @@ async function copyRendererWebFonts(cwd, outDir) {
         }
     }
 }
+// Fails the build on a missing source: a runtime readBundledAsset() miss in
+// prod would otherwise only surface on the first request that needs the file.
+async function copyBundledAssets(cwd, outDir, declarations) {
+    const target = join(outDir, BUNDLED_ASSETS_DIST_DIR);
+    for (const declaration of declarations) {
+        const source = resolveBundledAssetSource(cwd, declaration);
+        if (!existsSync(source) || !statSync(source).isFile()) {
+            throw new Error(`[kumiko build] package.json "kumiko.assets" "${declaration.name}": source file not found ` +
+                `at ${source} (declared as "${declaration.source}").`);
+        }
+        await mkdir(target, { recursive: true });
+        await cp(source, join(target, declaration.name));
+    }
+}
 // @internal — exported nur für Unit-Tests.
 export function discoverHtmlTemplate(cwd) {
     for (const candidate of ["index.html", "public/index.html"]) {

package/dist/bundled-assets.d.ts

@@ -0,0 +1,25 @@
+/** dist-relative folder holding the copied assets. The static file server
+ *  refuses to serve it (see run-prod-app-static-files.ts) — assets are
+ *  server-side inputs, not public URLs. */
+export declare const BUNDLED_ASSETS_DIST_DIR = "kumiko-bundled-assets";
+/** Allowlist for asset names; also rules out path segments. */
+export declare const BUNDLED_ASSET_NAME_PATTERN: RegExp;
+export type BundledAssetDeclaration = {
+    readonly name: string;
+    /** Relative to the directory of the declaring package.json. */
+    readonly source: string;
+};
+export type BundledAssetOptions = {
+    /** App root (the dir holding dist/ and package.json). Default: process.cwd(). */
+    readonly cwd?: string;
+};
+export declare function isValidBundledAssetName(name: string): boolean;
+/** Absolute source path of a declaration, contained in `packageDir`. */
+export declare function resolveBundledAssetSource(packageDir: string, declaration: BundledAssetDeclaration): string;
+/** Reads and validates package.json `kumiko.assets`. Missing file or key → [];
+ *  anything malformed throws, so a typo cannot silently drop a declared asset. */
+export declare function readBundledAssetDeclarations(packageDir: string): readonly BundledAssetDeclaration[];
+/** Absolute path of a declared asset: the built copy in prod, the declared
+ *  source in dev. Throws for invalid, undeclared or missing assets. */
+export declare function resolveBundledAsset(name: string, opts?: BundledAssetOptions): string;
+export declare function readBundledAsset(name: string, opts?: BundledAssetOptions): Promise<Uint8Array>;

package/dist/bundled-assets.js

@@ -0,0 +1,117 @@
+// Read-only files an app's own build ships (fonts, templates). Declared in
+// package.json `kumiko.assets: [{ name, source }]`; buildProdBundle copies
+// them into dist/<BUNDLED_ASSETS_DIST_DIR>/, readBundledAsset() finds them in
+// prod (the copy) and in dev (the declared source) behind one name. The one
+// guarded place for this lookup — apps must not wire node:fs for it.
+import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { isPlainObject, parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+/** dist-relative folder holding the copied assets. The static file server
+ *  refuses to serve it (see run-prod-app-static-files.ts) — assets are
+ *  server-side inputs, not public URLs. */
+export const BUNDLED_ASSETS_DIST_DIR = "kumiko-bundled-assets";
+/** Allowlist for asset names; also rules out path segments. */
+export const BUNDLED_ASSET_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function isValidBundledAssetName(name) {
+    return BUNDLED_ASSET_NAME_PATTERN.test(name) && !name.includes("..");
+}
+function assertValidBundledAssetName(name) {
+    if (!isValidBundledAssetName(name)) {
+        throw new Error(`[kumiko assets] invalid asset name "${name}" — must match ${BUNDLED_ASSET_NAME_PATTERN} ` +
+            `and contain no "..".`);
+    }
+}
+// Same two-line defense as the storage layer's resolveContainedPath.
+function resolveContained(baseDir, relative, label) {
+    const base = resolve(baseDir);
+    if (isAbsolute(relative)) {
+        throw new Error(`[kumiko assets] ${label} "${relative}" must be relative to the package dir.`);
+    }
+    const filePath = resolve(join(base, relative));
+    if (filePath !== base && !filePath.startsWith(base + sep)) {
+        throw new Error(`[kumiko assets] ${label} "${relative}" escapes the package dir ${base}.`);
+    }
+    return filePath;
+}
+/** Absolute source path of a declaration, contained in `packageDir`. */
+export function resolveBundledAssetSource(packageDir, declaration) {
+    return resolveContained(packageDir, declaration.source, `kumiko.assets["${declaration.name}"].source`);
+}
+/** Reads and validates package.json `kumiko.assets`. Missing file or key → [];
+ *  anything malformed throws, so a typo cannot silently drop a declared asset. */
+export function readBundledAssetDeclarations(packageDir) {
+    const pkgJsonPath = resolve(packageDir, "package.json");
+    if (!existsSync(pkgJsonPath))
+        return [];
+    const parsed = parseJsonOrThrow(readFileSync(pkgJsonPath, "utf8"), pkgJsonPath);
+    if (!isPlainObject(parsed))
+        return [];
+    const kumiko = parsed["kumiko"];
+    if (!isPlainObject(kumiko) || !("assets" in kumiko))
+        return [];
+    const value = kumiko["assets"];
+    if (!Array.isArray(value)) {
+        throw new Error(`[kumiko assets] package.json "kumiko.assets" must be an array.`);
+    }
+    const seen = new Set();
+    return value.map((item, index) => {
+        const declaration = parseDeclaration(item, index);
+        if (seen.has(declaration.name)) {
+            throw new Error(`[kumiko assets] duplicate "kumiko.assets[].name" "${declaration.name}" — names must be unique.`);
+        }
+        seen.add(declaration.name);
+        resolveBundledAssetSource(packageDir, declaration);
+        return declaration;
+    });
+}
+function parseDeclaration(item, index) {
+    if (!isPlainObject(item)) {
+        throw new Error(`[kumiko assets] package.json "kumiko.assets[${index}]" must be an object.`);
+    }
+    const name = item["name"];
+    const source = item["source"];
+    if (typeof name !== "string") {
+        throw new Error(`[kumiko assets] package.json "kumiko.assets[${index}].name" must be a string.`);
+    }
+    assertValidBundledAssetName(name);
+    if (typeof source !== "string" || source.length === 0) {
+        throw new Error(`[kumiko assets] package.json "kumiko.assets[${index}].source" must be a non-empty string.`);
+    }
+    return { name, source };
+}
+function findNearestPackageDir(from) {
+    let dir = resolve(from);
+    for (;;) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Absolute path of a declared asset: the built copy in prod, the declared
+ *  source in dev. Throws for invalid, undeclared or missing assets. */
+export function resolveBundledAsset(name, opts = {}) {
+    assertValidBundledAssetName(name);
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    const built = resolveContained(join(cwd, "dist", BUNDLED_ASSETS_DIST_DIR), name, "asset name");
+    if (existsSync(built))
+        return built;
+    const packageDir = findNearestPackageDir(cwd);
+    const declaration = packageDir
+        ? readBundledAssetDeclarations(packageDir).find((d) => d.name === name)
+        : undefined;
+    if (packageDir === undefined || declaration === undefined) {
+        throw new Error(`[kumiko assets] "${name}" is not a built asset and not declared in package.json "kumiko.assets".`);
+    }
+    const source = resolveBundledAssetSource(packageDir, declaration);
+    if (!existsSync(source)) {
+        throw new Error(`[kumiko assets] source of "${name}" not found: ${source}`);
+    }
+    return source;
+}
+export async function readBundledAsset(name, opts = {}) {
+    return readFile(resolveBundledAsset(name, opts));
+}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
+export { type BundledAssetDeclaration, type BundledAssetOptions, readBundledAsset, resolveBundledAsset, } from "./bundled-assets.js";
 export { type ComposeFeaturesOptions, composeFeatures } from "./compose-features.js";
+export type { RunBootstrapOptions } from "./run-bootstrap.js";
+export { runBootstrap } from "./run-bootstrap.js";
 export type { AccountUnlockSetup, EmailVerificationSetup, InviteSetup, PageHeadMeta, PageHeadResolver, PageHeadSystemQuery, PasswordResetSetup, ProdAppHandle, ProdSeedFn, RunProdAppAuthOptions, RunProdAppOptions, SignupSetup, } from "./run-prod-app.js";
 export { requireEnv, runProdApp } from "./run-prod-app.js";
 export type { RunWorkerAppOptions, WorkerAppHandle, WorkerWireDeps, } from "./run-worker-app.js";

package/dist/index.js

@@ -2,6 +2,8 @@
 // runDevApp (kumiko-dev-server), aber ohne Dev-/Scaffold-/Codegen-
 // Tooling (ts-morph) als Dependency — Prod-Apps ziehen so kein
 // Dev-Tooling mehr in ihre node_modules.
+export { readBundledAsset, resolveBundledAsset, } from "./bundled-assets.js";
 export { composeFeatures } from "./compose-features.js";
+export { runBootstrap } from "./run-bootstrap.js";
 export { requireEnv, runProdApp } from "./run-prod-app.js";
 export { runWorkerApp } from "./run-worker-app.js";

package/dist/run-bootstrap.d.ts

@@ -0,0 +1,13 @@
+import { type BootstrapPlan, type BootstrapReport } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { type RunProdAppAuthOptions } from "./run-prod-app.js";
+import type { RunWorkerAppOptions } from "./run-worker-app.js";
+export type RunBootstrapOptions = Omit<RunWorkerAppOptions, "wireComponents" | "includeBundled" | "jobs" | "eventDispatcher" | "metrics"> & BootstrapPlan & {
+    /** The same auth block the app passes to runProdApp (`admin` is ignored).
+     *  Needs a mounted invite flow: `auth.invite`, or `auth.mail` with
+     *  SMTP_HOST set — invitations are the only way bootstrap grants access. */
+    readonly auth: Omit<RunProdAppAuthOptions, "admin">;
+};
+/** Returns the report, or undefined in KUMIKO_DRY_RUN_ENV=boot mode. Without
+ *  an injected `envSource` (a real process) it exits the process when done,
+ *  so a k8s Job never hangs on a leftover socket. */
+export declare function runBootstrap(options: RunBootstrapOptions): Promise<BootstrapReport | undefined>;

package/dist/run-bootstrap.js

@@ -0,0 +1,71 @@
+// runBootstrap — one-shot, passwordless first-run provisioning for prod:
+// creates the listed tenants (seed hook only on creation) and invites the
+// listed users; SystemAdmins receive their global role only when they accept
+// the invitation. Idempotent: a second run with the same plan sends nothing,
+// an invitation that expired unused is re-sent, accepted or cancelled ones
+// stay untouched.
+//
+// Boots like runWorkerApp (same env, crypto and schema gate) but composes the
+// auth feature with the app's invite flow, dispatches its writes as the
+// system user, and stops again. Convention: `bin/bootstrap.ts` →
+// `dist-server/bootstrap.js` (see buildServerBundle).
+import { bootstrapTenants, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { bootWorkerProcess, resolveWorkerEnvSource } from "./boot/worker-boot-core.js";
+import { buildComposeAuthOptions } from "./compose-features.js";
+import { requireEnv } from "./run-prod-app.js";
+import { resolveAuthMail } from "./run-prod-app-boot-context.js";
+const PROCESS_NAME = "runBootstrap";
+function maskEmailForLog(email) {
+    const at = email.indexOf("@");
+    return at <= 0 ? "***" : `${email[0]}***${email.slice(at)}`;
+}
+function logBootstrapReport(report) {
+    for (const tenant of report.tenants) {
+        // biome-ignore lint/suspicious/noConsole: the report IS the deliverable of a one-shot process
+        console.log(`[${PROCESS_NAME}] tenant ${tenant.id}: ${tenant.outcome}${tenant.seeded ? " (seeded)" : ""}${tenant.configApplied.length > 0 ? ` (config: ${tenant.configApplied.join(", ")})` : ""}`);
+    }
+    for (const invite of report.invites) {
+        const globalRoles = invite.globalRoles.length > 0 ? ` +${invite.globalRoles.join(",")}` : "";
+        // biome-ignore lint/suspicious/noConsole: the report IS the deliverable of a one-shot process
+        console.log(`[${PROCESS_NAME}] invite ${maskEmailForLog(invite.email)} → tenant ${invite.tenantId}${globalRoles}: ${invite.outcome}`);
+    }
+}
+/** Returns the report, or undefined in KUMIKO_DRY_RUN_ENV=boot mode. Without
+ *  an injected `envSource` (a real process) it exits the process when done,
+ *  so a k8s Job never hangs on a leftover socket. */
+export async function runBootstrap(options) {
+    const envSource = await resolveWorkerEnvSource(options, PROCESS_NAME);
+    const jwtSecret = requireEnv("JWT_SECRET", envSource, PROCESS_NAME);
+    const effectiveAuth = resolveAuthMail(options.auth, jwtSecret, envSource);
+    const authOptions = buildComposeAuthOptions(effectiveAuth);
+    if (!authOptions?.invite) {
+        throw new Error(`[${PROCESS_NAME}] no invite flow mounted — set auth.invite, or auth.mail together with the SMTP_HOST env var`);
+    }
+    // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+    console.log(`[${PROCESS_NAME}] booting…`);
+    const boot = await bootWorkerProcess(options, envSource, {
+        processName: PROCESS_NAME,
+        authOptions,
+        deliverQueuedInline: true,
+    });
+    if (boot.kind === "dry-run")
+        return undefined;
+    let report;
+    try {
+        report = await bootstrapTenants({ db: boot.db, redis: boot.redis, dispatcher: boot.entrypoint.dispatcher }, {
+            tenants: options.tenants,
+            ...(options.systemAdmins && { systemAdmins: options.systemAdmins }),
+            ...(options.seed && { seed: options.seed }),
+        });
+    }
+    finally {
+        await boot.close();
+    }
+    logBootstrapReport(report);
+    // biome-ignore lint/suspicious/noConsole: boot-time progress hint
+    console.log(`[${PROCESS_NAME}] done.`);
+    if (options.envSource === undefined) {
+        process.exit(0);
+    }
+    return report;
+}

package/dist/run-prod-app-boot-context.d.ts

@@ -20,6 +20,9 @@ export declare function buildBootExtraContext(opts: {
     readonly masterKey?: MasterKeyProvider;
     readonly sseBroker?: SseBroker;
     readonly kms?: KmsAdapter;
+    /** One-shot process (runBootstrap): nothing drains its job queue once it
+     *  exits, so queued channels must send inline instead of enqueueing. */
+    readonly deliverQueuedInline?: boolean;
 }): Record<string, unknown>;
 /** Die Auth-Felder die resolveAuthMail liest/normalisiert — beide
  *  App-Auth-Typen (prod + dev) erfüllen das strukturell. */

package/dist/run-prod-app-boot-context.js

@@ -41,27 +41,40 @@ export function addConfigAccessorFactory(resolved, registry) {
 // Prod/dev parity for ctx.notify: without this `_notifyFactory` is only wired
 // in tests (createDeliveryTestContext), so ctx.notify is undefined at runtime
 // and every notification silently skips. sseBroker optional (email/push don't
-// need it, in-app SSE does); no jobRunner → queued channels send inline.
+// need it, in-app SSE does). Queued channels go through the delivery jobs of
+// the calling context's job runner (3rd factory arg); without one they send
+// inline, with `secrets` for chat-channel credentials.
 function buildDeliveryNotifyFactory(opts) {
     const deliveryService = createDeliveryService({
         db: opts.db,
         registry: opts.registry,
         channels: collectChannels(opts.registry),
+        ...(opts.secrets && { secrets: opts.secrets }),
         ...(opts.sseBroker && { sseBroker: opts.sseBroker }),
         ...(opts.escapeHatchAuditSink && { escapeHatchAuditSink: opts.escapeHatchAuditSink }),
     });
-    return (user, tenantId) => (notificationType, options) => deliveryService.notify(notificationType, options, user, tenantId);
+    return (user, tenantId, jobDispatcher) => (notificationType, options) => deliveryService.notify(notificationType, options, user, tenantId, opts.deliverQueuedInline === true ? undefined : jobDispatcher);
 }
 function resolveEscapeHatchAuditSink(features, db) {
     const hasAuditFeature = features.some((f) => f.name === AUDIT_FEATURE);
     return hasAuditFeature ? createEscapeHatchAuditSink({ db }) : undefined;
 }
+function resolveBootSecrets(db, features, crypto, registry) {
+    const hasSecretsFeature = features.some((f) => f.name === SECRETS_FEATURE_NAME);
+    if (!hasSecretsFeature || !crypto.masterKeyProvider)
+        return undefined;
+    return createSecretsContext({
+        db,
+        masterKeyProvider: crypto.masterKeyProvider,
+        registry,
+        dekCache: crypto.dekCache,
+    });
+}
 export function buildBootExtraContext(opts) {
     const crypto = opts.crypto ?? resolveBootCrypto(opts.envSource, opts.masterKey);
-    const hasSecretsFeature = opts.features.some((f) => f.name === SECRETS_FEATURE_NAME);
-    const wireSecrets = hasSecretsFeature && crypto.masterKeyProvider !== undefined;
     const hasDeliveryFeature = opts.features.some((f) => f.name === DELIVERY_FEATURE);
     const escapeHatchAuditSink = resolveEscapeHatchAuditSink(opts.features, opts.db);
+    const secrets = resolveBootSecrets(opts.db, opts.features, crypto, opts.registry);
     return {
         templateResolver: createTemplateResolverApi(opts.db),
         ...(opts.kms && { kms: opts.kms }),
@@ -70,8 +83,10 @@ export function buildBootExtraContext(opts) {
             _notifyFactory: buildDeliveryNotifyFactory({
                 db: opts.db,
                 registry: opts.registry,
+                ...(secrets && { secrets }),
                 ...(opts.sseBroker && { sseBroker: opts.sseBroker }),
                 ...(escapeHatchAuditSink && { escapeHatchAuditSink }),
+                deliverQueuedInline: opts.deliverQueuedInline,
             }),
         }),
         // Top-level provider so feature jobs (secrets rotate, config reencrypt)
@@ -81,14 +96,7 @@ export function buildBootExtraContext(opts) {
         // whenever a master key exists — NOT gated on the secrets feature,
         // config encryption must work without mounting ctx.secrets.
         ...(crypto.configCipher && { configEncryption: crypto.configCipher }),
-        ...(wireSecrets &&
-            crypto.masterKeyProvider && {
-            secrets: createSecretsContext({
-                db: opts.db,
-                masterKeyProvider: crypto.masterKeyProvider,
-                dekCache: crypto.dekCache,
-            }),
-        }),
+        ...(secrets && { secrets }),
         ...(opts.hasAuth && {
             configResolver: createConfigResolver({
                 appOverrides: buildEnvConfigOverrides(opts.registry, opts.envSource),

package/dist/run-prod-app-static-files.js

@@ -1,7 +1,9 @@
+import { resolve, sep } from "node:path";
 import { buildRequestContextDataFromRequest, cachedResponse, computeStrongEtag, computeWeakEtag, createClientIpResolver, requestContext, } from "@cosmicdrift/kumiko-framework/api";
 import { createAnonymousUser } from "@cosmicdrift/kumiko-framework/engine";
 import { resolveAndInjectPageHead } from "@cosmicdrift/kumiko-headless/apex";
 import { ASSETS_DIR } from "./build-prod-bundle.js";
+import { BUNDLED_ASSETS_DIST_DIR } from "./bundled-assets.js";
 import { stripNoRouteMatchHeader, tryHonoFirst } from "./try-hono-first.js";
 // Static-asset + SPA-fallback serving for runProdApp's HTTP handler. Split
 // out of run-prod-app.ts (#1005, Welle 2) — mechanical relocation, these
@@ -45,6 +47,14 @@ export async function readStaticFile(filePath) {
         throw err;
     }
 }
+// Bundled assets are server-side inputs (readBundledAsset), never public URLs.
+// Compared on the resolved path, not the URL prefix: "//kumiko-bundled-assets/x"
+// or a case variant on a case-insensitive disk would slip past a prefix check.
+function isInsideBundledAssetsDir(staticDir, filePath) {
+    const bundledDir = resolve(staticDir, BUNDLED_ASSETS_DIST_DIR).toLowerCase();
+    const target = resolve(filePath).toLowerCase();
+    return target === bundledDir || target.startsWith(bundledDir + sep);
+}
 export function serveDiskFile(req, pathname, file) {
     return cachedResponse(req, {
         // @cast-boundary bun-types — Response BodyInit narrowing
@@ -247,7 +257,9 @@ trustedProxyHops = 0) {
         if (!isIndexRequest) {
             const relPath = url.pathname.slice(1);
             const filePath = `${staticDir}/${relPath}`;
-            const file = await readStaticFile(filePath);
+            const file = isInsideBundledAssetsDir(staticDir, filePath)
+                ? undefined
+                : await readStaticFile(filePath);
             if (file) {
                 return serveDiskFile(req, url.pathname, file);
             }

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

@@ -78,9 +78,11 @@ export type AuthMailOptions = {
     readonly hmacSecret?: string;
 };
 export type RunProdAppAuthOptions = {
-    /** Initial admin user. Seeded once (idempotent — re-boots check first
-     *  whether the email is already in the users table). */
-    readonly admin: SeedAdminOptions;
+    /** Initial admin user with a password, seeded once (idempotent — re-boots
+     *  check first whether the email is already in the users table). Optional:
+     *  passwordless setups provision their first admins via `runBootstrap`
+     *  (invitation, global role granted on accept) instead. */
+    readonly admin?: SeedAdminOptions;
     /** Optional override of the login error → HTTP status map. */
     readonly loginErrorStatusMap?: Readonly<Record<string, number>>;
     /** Auth-Mail-Convenience: verdrahtet alle 4 Mail-Flows (passwordReset,
@@ -329,17 +331,18 @@ export type RunProdAppOptions = {
      *  ist eine Begründung für den Audit-Trail (z.B. "kms rollout pending,
      *  infra#188"). Ohne Flag und ohne `kms` bricht der Boot ab. */
     readonly allowPlaintextPii?: string;
-    /** Deploy-Topologie. Default `true` (Single-Container): dieser Prozess
-     *  fährt HTTP + BEIDE Job-Lanes (api + worker) + den Event-Dispatcher
-     *  (MSP-Anwendung) inline — via `createAllInOneEntrypoint`. Damit laufen
-     *  worker-Lane-Crons (z.B. der Daten-Export `run-export-jobs`, default
-     *  `runIn:"worker"`) und r.multiStreamProjection ohne separaten Worker.
+    /** Deploy topology. Default `true` (single container): this process runs
+     *  HTTP, both job lanes (api + worker) and the event dispatcher (MSP apply)
+     *  inline via `createAllInOneEntrypoint`. Worker-lane crons (e.g. the data
+     *  export `run-export-jobs`, default `runIn:"worker"`), the delivery jobs
+     *  `delivery.render`/`delivery.send` (worker lane; mail, push and chat
+     *  delivery) and r.multiStreamProjection then run without a separate worker.
      *
-     *  `false` NUR mit einem dezidierten Worker-Deployment setzen: dann fährt
-     *  dieser Prozess API-only (`createApiEntrypoint`), und worker-Lane-Jobs
-     *  + MSPs werden NICHT mehr lokal angewandt — der Worker muss sie
-     *  übernehmen, sonst bleiben Export-Jobs pending und die Read-Side leer
-     *  (2026-06-11-Incident-Klasse). */
+     *  Set `false` ONLY with a dedicated worker deployment: this process then
+     *  runs API-only (`createApiEntrypoint`) and no longer applies worker-lane
+     *  jobs or MSPs locally. The worker has to take them over, otherwise export
+     *  jobs and queued delivery attempts (email/push/chat) stay pending and the
+     *  read side stays empty (2026-06-11 incident class). */
     readonly runSingleInstance?: boolean;
     /** Job-Block. Wenn das Feature `r.job(...)` registriert, wird er
      *  automatisch verdrahtet (siehe runSingleInstance). */

package/dist/run-prod-app.js

@@ -57,6 +57,7 @@ import { renderDryRun } from "@cosmicdrift/kumiko-framework/env/dry-run";
 import { createEsOperationsTable, createSeedMigrationContext, runPendingSeedMigrations, } from "@cosmicdrift/kumiko-framework/es-ops";
 import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
 import { createDispatcher, createEntityCache, createEventDedup, createIdempotencyGuard, } from "@cosmicdrift/kumiko-framework/pipeline";
+import { createRedisCacheSyncBus, redisClientOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/redis";
 import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import { Redis } from "ioredis";
 import { applyBootSeeds } from "./boot/apply-boot-seeds.js";
@@ -315,12 +316,18 @@ export async function runProdApp(options) {
     // effectiveFeatures, 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).
+    const cacheSync = createRedisCacheSyncBus({
+        redisUrl,
+        clientOptions: redisClientOptionsFromEnv(envSource),
+    });
     let resolvedEffectiveFeatures = options.effectiveFeatures;
     if (resolvedEffectiveFeatures === undefined) {
         const tierResolverUsage = findTierResolverUsage(features);
         if (tierResolverUsage) {
             const plugin = tierResolverUsage.options;
-            resolvedEffectiveFeatures = await plugin.build({ db, registry });
+            resolvedEffectiveFeatures = await plugin.build({ db, registry, cacheSync });
         }
     }
     // 5. Schema-Drift-Gate (drizzle-frei, kumiko/migrations). `kumiko schema
@@ -467,6 +474,7 @@ export async function runProdApp(options) {
         ...(instanceId && { instanceId }),
         dispatcherOptions: {
             idempotency,
+            cacheSync,
             ...(resolvedEffectiveFeatures && { effectiveFeatures: resolvedEffectiveFeatures }),
         },
         eventDedup,
@@ -600,6 +608,9 @@ export async function runProdApp(options) {
     // (which already registered the eventDispatcher/jobRunner hooks above),
     // so it drains LIFO before those, matching the close-before-teardown
     // order fw#2630 established for buildServer's own hook.
+    entrypoint.lifecycle.registerShutdownHook("prodAppCacheSync", async () => {
+        await cacheSync.close();
+    });
     if (ownedRedisSseBroker) {
         const broker = ownedRedisSseBroker;
         entrypoint.lifecycle.registerShutdownHook("prodAppRedisSseBroker", async () => {
@@ -624,7 +635,7 @@ export async function runProdApp(options) {
     //    "first boot" via flag, every seed-step checks its own
     //    preconditions. Config-seeds rely on a deterministic
     //    aggregate-id so re-boot becomes a version_conflict skip.
-    if (effectiveAuth) {
+    if (effectiveAuth?.admin) {
         await seedAdminGuarded(db, effectiveAuth.admin);
     }
     await applyBootSeeds({

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

@@ -1,12 +1,13 @@
-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, type FeatureDefinition, type Registry, type ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
-import { type WorkerEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
+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 { WorkerEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
 import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
 import type { ObservabilityOptions, ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
-import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
-import { Redis } from "ioredis";
+import type { MasterKeyProvider, SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import type { Redis } from "ioredis";
+import { type WorkerMetricsOptions, type WorkerMetricsServer } from "./boot/worker-metrics-server.js";
 import { type SystemWireDeps } from "./extra-routes-deps.js";
 export type WorkerContextOption = Record<string, unknown> | ((deps: WorkerDeps) => Record<string, unknown>);
 export type WorkerDeps = {
@@ -21,6 +22,11 @@ export type WorkerDeps = {
  *  `lifecycle` for `registerShutdownHook`. */
 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
+     *  when the secrets feature is not mounted or no master key is available. */
+    readonly secrets?: SecretsContext;
 };
 export type RunWorkerAppOptions = {
     /** App-specific features — same array as in the API/all-in-one process,
@@ -82,11 +88,17 @@ export type RunWorkerAppOptions = {
     readonly kmsSlots?: readonly string[];
     readonly observability?: ObservabilityProvider;
     readonly observabilityOptions?: ObservabilityOptions;
+    /** Serves `/metrics` on its own port (the worker has no HTTP app). Needs a
+     *  PrometheusMeter-based `observability`; both are validated at boot,
+     *  including KUMIKO_DRY_RUN_ENV=boot. Same `token`/`path` as runProdApp. */
+    readonly metrics?: WorkerMetricsOptions;
 };
 export type WorkerAppHandle = {
     /** In KUMIKO_DRY_RUN_ENV=boot mode with an injected envSource (test
      *  path), no boot ran — this slot is an undefined-cast, do not access. */
     readonly entrypoint: WorkerEntrypoint;
     readonly stop: () => Promise<void>;
+    /** Set when `metrics` was configured. */
+    readonly metricsServer?: WorkerMetricsServer;
 };
 export declare function runWorkerApp(options: RunWorkerAppOptions): Promise<WorkerAppHandle>;

package/dist/run-worker-app.js

@@ -14,23 +14,10 @@
 //
 // Container/Coolify sets the same env vars as runProdApp:
 //   DATABASE_URL, REDIS_URL, JWT_SECRET — PORT is not needed.
-import { loadJwtSecretOrKeyring } from "@cosmicdrift/kumiko-framework/api";
-import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
-import { configureEntityFieldEncryption, createDbConnection, } from "@cosmicdrift/kumiko-framework/db";
-import { createRegistry, findTierResolverUsage, 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";
-import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
-import { Redis } from "ioredis";
-import { resolveBootCrypto } from "./boot/boot-crypto.js";
-import { jobRunLoggerCallbacks } from "./boot/job-run-logger.js";
 import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot.js";
-import { composeFeatures } from "./compose-features.js";
+import { bootWorkerProcess, resolveWorkerEnvSource } from "./boot/worker-boot-core.js";
+import { startWorkerMetricsServer, } from "./boot/worker-metrics-server.js";
 import { makeDispatchSystemWrite } from "./extra-routes-deps.js";
-import { assertPiiBootInvariants } from "./pii-boot-gate.js";
-import { requireEnv } from "./run-prod-app.js";
-import { addConfigAccessorFactory, buildBootExtraContext } from "./run-prod-app-boot-context.js";
 function makeBootModeHandle() {
     return {
         // @cast-boundary boot-mode: no entrypoint exists because no boot ran —
@@ -40,142 +27,34 @@ function makeBootModeHandle() {
     };
 }
 export async function runWorkerApp(options) {
-    const rawEnvSource = options.envSource ?? process.env;
-    const envSource = options.kmsSlots
-        ? await resolvePlatformKeks(rawEnvSource, {
-            slots: options.kmsSlots,
-            logPrefix: "[runWorkerApp]",
-        })
-        : rawEnvSource;
-    // 1. Polyfill before anything else — exactly the bug fw#1725 reports:
-    //    without it, every job in the worker 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();
-    // 2. Env vars: fail-fast, same requireEnv as runProdApp. JWT_SECRET is
-    //    validated by loadJwtSecretOrKeyring itself (throws when neither
-    //    JWT_SECRET nor JWT_SECRET_V<n> is set).
-    const databaseUrl = requireEnv("DATABASE_URL", envSource, "runWorkerApp");
-    const redisUrl = requireEnv("REDIS_URL", envSource, "runWorkerApp");
-    const jwtSecretOrKeyring = loadJwtSecretOrKeyring(envSource);
+    const envSource = await resolveWorkerEnvSource(options, "runWorkerApp");
     // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
     console.log("[runWorkerApp] booting Kumiko worker…");
-    // 3. Feature registry — identical to runProdApp, MUST be built with the
-    //    same `includeBundled` as the API process.
-    const features = composeFeatures(options.features, {
-        includeBundled: !!options.includeBundled,
-    });
-    validateBoot(features, { env: envSource, ...options.validateBootOptions });
-    warnIfNonUtcServerTimeZone();
-    assertPiiBootInvariants(features, {
-        kms: options.kms,
-        blindIndexKey: options.blindIndexKey,
-        allowPlaintextPii: options.allowPlaintextPii,
-        mode: "prod",
-    });
-    const registry = createRegistry(features);
-    // Boot-mode exit (parity with runProdApp's C1): validators ran and the
-    // registry is built, no DB/Redis client was constructed. Makes the boot
-    // testable without real Postgres/Redis infra.
-    if (envSource["KUMIKO_DRY_RUN_ENV"] === "boot") {
-        // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
-        console.log(`[runWorkerApp] boot validation OK (${features.length} features, ${registry.features.size} registry entries)`);
-        if (options.envSource === undefined) {
-            process.exit(0);
-        }
+    const boot = await bootWorkerProcess(options, envSource, { processName: "runWorkerApp" });
+    if (boot.kind === "dry-run")
         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
+    // hook, so a failing start() does not leak the listener.
+    let metricsServer;
+    try {
+        metricsServer = options.metrics
+            ? startWorkerMetricsServer(options.metrics, entrypoint)
+            : undefined;
+        await entrypoint.start();
     }
-    // 4. KMS health gate — runs BEFORE the connections, so an abort leaks
-    //    nothing (identical to runProdApp).
-    if (options.kms) {
-        const kmsHealth = await options.kms.health();
-        if (!kmsHealth.ok) {
-            throw new Error(`[runWorkerApp] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`);
-        }
+    catch (error) {
+        // The boot failure is the actionable error; a close failure on a
+        // half-started worker must not replace it.
+        await boot.close().catch(() => { });
+        throw error;
     }
-    const { db, close: closeDb } = createDbConnection(databaseUrl);
-    const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
-    let resolvedEffectiveFeatures = options.effectiveFeatures;
-    if (resolvedEffectiveFeatures === undefined) {
-        const tierResolverUsage = findTierResolverUsage(features);
-        if (tierResolverUsage) {
-            const plugin = tierResolverUsage.options;
-            resolvedEffectiveFeatures = await plugin.build({ db, registry });
-        }
-    }
-    // 5. Schema-drift gate — identical to runProdApp.
-    if (options.migrations !== false) {
-        const migrationsDir = options.migrations?.dir ?? "./kumiko/migrations";
-        // biome-ignore lint/suspicious/noConsole: boot-time progress hint
-        console.log(`[runWorkerApp] checking schema drift (${migrationsDir})…`);
-        try {
-            await assertKumikoSchemaCurrent(db, migrationsDir);
-        }
-        catch (err) {
-            if (err instanceof SchemaDriftError) {
-                // biome-ignore lint/suspicious/noConsole: terminal error message
-                console.error(`\n[runWorkerApp] BOOT ABORTED — ${err.message}\n`);
-            }
-            throw err;
-        }
-    }
-    // 6. Pipeline pieces — same defaults as runProdApp.
-    const idempotency = createIdempotencyGuard(redis, { ttlSeconds: 60 });
-    const eventDedup = createEventDedup(redis, { ttlSeconds: 60 });
-    const entityCache = createEntityCache(redis, { ttlSeconds: 60 });
-    // 7. Boot-crypto + extraContext — the core of fw#1725: KMS wiring,
-    //    blind-index, config-encryption must be wired in the worker exactly
-    //    like in the API, otherwise the worker writes rows the API can no
-    //    longer read (different cipher, missing blind index).
-    const deps = { db, redis, registry };
-    const resolvedExtraContext = typeof options.extraContext === "function"
-        ? options.extraContext(deps)
-        : (options.extraContext ?? {});
-    const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
-    configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
-    configurePiiSubjectKms(options.kms);
-    configureBlindIndexKey(options.blindIndexKey);
-    const autoExtraContext = buildBootExtraContext({
-        db,
-        features,
-        envSource,
-        registry,
-        hasAuth: !!options.includeBundled,
-        crypto: bootCrypto,
-        ...(options.kms && { kms: options.kms }),
-    });
-    const extraContext = addConfigAccessorFactory({ ...autoExtraContext, ...resolvedExtraContext }, registry);
-    const jobLogger = jobRunLoggerCallbacks(registry, db);
-    const entrypoint = createWorkerEntrypoint({
-        registry,
-        context: { db, redis, entityCache, registry, ...extraContext },
-        jwtSecret: jwtSecretOrKeyring,
-        dispatcherOptions: {
-            idempotency,
-            ...(resolvedEffectiveFeatures && { effectiveFeatures: resolvedEffectiveFeatures }),
-        },
-        eventDedup,
-        ...(options.observability && { observability: options.observability }),
-        ...(options.observabilityOptions && { observabilityOptions: options.observabilityOptions }),
-        redisUrl,
-        ...jobLogger,
-        ...(options.jobs?.queueNamePrefix !== undefined && {
-            queueNamePrefix: options.jobs.queueNamePrefix,
-        }),
-        ...(options.jobs?.getActiveTenantIds !== undefined && {
-            getActiveTenantIds: options.jobs.getActiveTenantIds,
-        }),
-        ...(options.eventDispatcher && { eventDispatcher: options.eventDispatcher }),
-    });
     const handle = {
         entrypoint,
-        stop: async () => {
-            await entrypoint.stop();
-            await closeDb();
-            redis.disconnect();
-        },
+        stop: boot.close,
+        ...(metricsServer && { metricsServer }),
     };
-    await entrypoint.start();
     startPiiEventBackfillOnBoot({
         db,
         registry,
@@ -189,6 +68,7 @@ export async function runWorkerApp(options) {
             registry,
             dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
             lifecycle: entrypoint.lifecycle,
+            ...(boot.secrets && { secrets: boot.secrets }),
         });
     }
     let shuttingDown = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.340.0",
+  "version": "0.341.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/codegen tooling.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -80,10 +80,10 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.340.0",
-    "@cosmicdrift/kumiko-framework": "0.340.0",
-    "@cosmicdrift/kumiko-headless": "0.340.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.340.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.341.0",
+    "@cosmicdrift/kumiko-framework": "0.341.0",
+    "@cosmicdrift/kumiko-headless": "0.341.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.341.0",
     "bun-types": "^1.3.13",
     "ioredis": "^5.10.1",
     "temporal-polyfill": "^0.3.2"

package/src/changes.json

@@ -1,4 +1,27 @@
 [
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "runBootstrap() for one-shot passwordless prod provisioning; runProdApp auth.admin is optional",
+    "detail": "Creates tenants (seed hook only on creation) and mails invitations; reruns send nothing, expired unused invitations are re-sent. Convention bin/bootstrap.ts -> dist-server/bootstrap.js."
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "runWorkerApp: secrets in wireComponents and a metrics port",
+    "detail": "WorkerWireDeps carries ctx.secrets (for createInboundMailSupervisor), and the new metrics option serves /metrics on its own port; KUMIKO_DRY_RUN_ENV=boot validates it."
+  },
+  {
+    "version": "0.341.0",
+    "type": "fix",
+    "title": "Worker metrics server starts before entrypoint.start() and is closed if boot fails"
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "Worker picks up tenant timezone changes made on API pods",
+    "detail": "The worker boot now joins the cache sync bus, so a timezone write on an API pod invalidates the worker's cached tenant timezone instead of leaving jobs on the old value until the TTL expires."
+  },
   {
     "version": "0.339.0",
     "type": "fix",