@cosmicdrift/kumiko-server-runtime 0.387.0 → 0.389.0

package/dist/run-prod-app-entrypoint.js

@@ -0,0 +1,149 @@
+import { createAllInOneEntrypoint, createApiEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
+import { createMetricsForFactory } from "@cosmicdrift/kumiko-framework/observability";
+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 { makeDispatchSystemQuery, makeDispatchSystemWrite } from "./extra-routes-deps.js";
+import { makeFilesForTenant } from "./files-for-tenant.js";
+import { buildProdAuthRoutes } from "./run-prod-app-auth.js";
+function collectProdExtraRoutes(options, config, composed) {
+    const bootExtraRoutes = config.bootOptionWiring.extraRoutes;
+    if (!options.extraRoutes && !options.unsubscribe && bootExtraRoutes.length === 0) {
+        return undefined;
+    }
+    return [...(options.extraRoutes ?? []), ...composed.unsubscribeRoutes, ...bootExtraRoutes];
+}
+export function buildProdEntrypointOptions(options, config, composed, connections, requestContext, authWiring, effectiveFeatures) {
+    const { registry, effectiveAuth } = composed;
+    const { db, redis, outsideTransactionDb, cacheSync } = connections;
+    const { jwtIssuer, instanceId, trustedProxyHops, resolvedRateLimit } = config;
+    const extraRoutes = collectProdExtraRoutes(options, config, composed);
+    return {
+        registry,
+        context: {
+            db,
+            redis,
+            entityCache: requestContext.entityCache,
+            registry,
+            ...requestContext.extraContext,
+        },
+        sseBroker: requestContext.sseBroker,
+        jwtSecret: config.jwtSecretOrKeyring,
+        ...(jwtIssuer && { jwtIssuer }),
+        ...(instanceId && { instanceId }),
+        dispatcherOptions: {
+            idempotency: requestContext.idempotency,
+            cacheSync,
+            outsideTransactionDb,
+            ...(effectiveFeatures && { effectiveFeatures }),
+        },
+        eventDedup: requestContext.eventDedup,
+        ...(options.observability && { observability: options.observability }),
+        ...(options.metrics && { metrics: options.metrics }),
+        ...(resolvedRateLimit && { rateLimit: resolvedRateLimit }),
+        ...(trustedProxyHops !== undefined && { trustedProxyHops }),
+        ...(options.errorDocs && { errorDocs: options.errorDocs }),
+        ...(extraRoutes && { extraRoutes }),
+        ...(effectiveAuth && {
+            auth: buildProdAuthRoutes(effectiveAuth, config, composed, connections, authWiring),
+        }),
+        ...(requestContext.resolvedAnonymousAccess && {
+            anonymousAccess: requestContext.resolvedAnonymousAccess,
+        }),
+    };
+}
+function prodJobOptions(options, composed, connections) {
+    const queueNamePrefix = options.jobs?.queueNamePrefix;
+    return {
+        ...jobRunLoggerCallbacks(composed.registry, connections.db),
+        ...(queueNamePrefix !== undefined && { queueNamePrefix }),
+        ...(options.jobs?.getActiveTenantIds !== undefined && {
+            getActiveTenantIds: options.jobs.getActiveTenantIds,
+        }),
+    };
+}
+// Deployment topology. By default, createAllInOneEntrypoint runs HTTP, both
+// job lanes (two runners, each scheduling only its own lane's crons, so
+// nothing fires twice) and the event dispatcher inline. That way worker-lane
+// crons (run-export-jobs defaults to runIn:"worker") and MSPs run without a
+// separate worker process, the gap the data export used to stall on.
+// runSingleInstance:false means API-only: a dedicated worker must then take
+// over the worker lane and MSPs, while API-lane jobs keep running locally.
+// The legacy eventDispatcher.disabled maps to runSingleInstance:false so
+// existing callers keep working; the explicit flag takes precedence.
+export function createProdEntrypoint(options, config, composed, connections, entrypointOptions) {
+    const runSingleInstance = options.runSingleInstance ?? options.eventDispatcher?.disabled !== true;
+    const hasJobs = composed.registry.getAllJobs().size > 0;
+    const jobOptions = prodJobOptions(options, composed, connections);
+    const dispatcherTunables = options.eventDispatcher?.pollIntervalMs !== undefined
+        ? { pollIntervalMs: options.eventDispatcher.pollIntervalMs }
+        : {};
+    return runSingleInstance
+        ? createAllInOneEntrypoint({
+            ...entrypointOptions,
+            redisUrl: config.redisUrl,
+            ...jobOptions,
+            ...(!options.eventDispatcher?.disabled && { eventDispatcher: dispatcherTunables }),
+        })
+        : createApiEntrypoint({
+            ...entrypointOptions,
+            ...(hasJobs && {
+                jobs: {
+                    redisUrl: config.redisUrl,
+                    runLocalJobs: true,
+                    ...jobOptions,
+                },
+            }),
+        });
+}
+// The broker built above is always ours (runProdApp never accepts a
+// caller-supplied sseBroker), so — same reasoning as buildServer's own
+// ownedRedisSseBroker hook — closing it on shutdown is our job, not the
+// entrypoint's. Registered after createApiEntrypoint/createAllInOneEntrypoint
+// (which already registered the eventDispatcher/jobRunner hooks above),
+// so it drains LIFO before those, matching the close-before-teardown
+// order established for buildServer's own hook.
+export function registerProdShutdownHooks(entrypoint, cacheSync, ownedRedisSseBroker) {
+    entrypoint.lifecycle.registerShutdownHook("prodAppCacheSync", async () => {
+        await cacheSync.close();
+    });
+    if (ownedRedisSseBroker) {
+        const broker = ownedRedisSseBroker;
+        entrypoint.lifecycle.registerShutdownHook("prodAppRedisSseBroker", async () => {
+            await broker.close();
+        });
+    }
+}
+// `extraRoutes` itself is already mounted — buildServer wires it inside
+// createApiEntrypoint/createAllInOneEntrypoint, before this function ever
+// runs. `wire` is the remaining escape-hatch for app-wired co-running
+// components that need the system-write dispatcher but don't declare a
+// route.
+export async function runProdWireHook(options, composed, connections, entrypoint) {
+    const { wire } = options;
+    if (wire) {
+        const { bootCrypto } = composed;
+        await wire({
+            db: connections.db,
+            redis: connections.redis,
+            registry: composed.registry,
+            filesForTenant: makeFilesForTenant(entrypoint.context),
+            ...(bootCrypto.masterKeyProvider && { masterKeyProvider: bootCrypto.masterKeyProvider }),
+            ...(bootCrypto.configCipher && { configEncryption: bootCrypto.configCipher }),
+            metricsFor: createMetricsForFactory(entrypoint.observability.meter),
+            dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
+            dispatchSystemQuery: makeDispatchSystemQuery(entrypoint.dispatcher),
+        });
+    }
+}
+export async function startProdBackgroundWork(entrypoint, config, composed, connections) {
+    const { envSource } = config;
+    await entrypoint.start();
+    await recordAppStartedOnBoot({ db: connections.db, envSource });
+    startPiiEventBackfillOnBoot({
+        db: connections.db,
+        registry: composed.registry,
+        lifecycle: entrypoint.lifecycle,
+        envSource,
+    });
+}

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

@@ -0,0 +1,20 @@
+import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
+import type { ProdAppHandle, RunProdAppOptions } from "./run-prod-app.ts";
+import type { ProdBootConfig, ProdComposedFeatures } from "./run-prod-app-config.ts";
+import type { ProdConnections } from "./run-prod-app-connections.ts";
+import type { ProdEntrypoint } from "./run-prod-app-entrypoint.ts";
+export type ProdFetchHandler = {
+    readonly fetchHandler: ProdAppHandle["fetch"];
+    readonly cspScriptHashes: readonly string[];
+};
+export declare function buildProdFetchHandler(options: RunProdAppOptions, config: ProdBootConfig, entrypoint: ProdEntrypoint): Promise<ProdFetchHandler>;
+export type ProdAppHandleInput = {
+    readonly options: RunProdAppOptions;
+    readonly config: ProdBootConfig;
+    readonly composed: ProdComposedFeatures;
+    readonly connections: ProdConnections;
+    readonly entrypoint: ProdEntrypoint;
+    readonly fetch: ProdFetchHandler;
+    readonly log: Logger;
+};
+export declare function createProdAppHandle(input: ProdAppHandleInput): ProdAppHandle;

package/dist/run-prod-app-handle.js

@@ -0,0 +1,105 @@
+import { flushEscapeHatchAudits } from "@cosmicdrift/kumiko-framework/pipeline";
+import { installShutdownSignals } from "./boot-options/process-signals.js";
+import { buildBunServeOptions, resolveDerivedMaxRequestBodySize } from "./bun-serve-options.js";
+import { installFatalErrorHandlers } from "./fatal-error-handlers.js";
+import { uninstallProcessLogger } from "./process-logger.js";
+import { buildStaticFallback, resolveCspScriptHashes, resolveHostDispatchScriptHashes, } from "./run-prod-app-static-files.js";
+import { withSecurityHeaders } from "./security-headers.js";
+import { stripNoRouteMatchHeader } from "./try-hono-first.js";
+const SERVER_GRACEFUL_STOP_MS = 10_000;
+// stop() without force waits for open connections (SSE never ends on its own); force-close after the grace period.
+async function stopServerGracefully(server) {
+    let graceTimer;
+    const graceElapsed = new Promise((resolve) => {
+        graceTimer = setTimeout(resolve, SERVER_GRACEFUL_STOP_MS);
+    });
+    try {
+        await Promise.race([server.stop(), graceElapsed]);
+    }
+    finally {
+        clearTimeout(graceTimer);
+    }
+    await server.stop(true);
+}
+// Static-fallback for non-/api/ paths wired via a wrapper so Hono owns
+// /api/* + extraRoutes and disk owns the rest. Tests use this directly;
+// listen() wraps it in Bun.serve.
+export async function buildProdFetchHandler(options, config, entrypoint) {
+    const cspScriptHashes = await resolveCspScriptHashes(options.staticDir, options.securityHeaders);
+    const hostDispatchScriptHashes = options.hostDispatch !== undefined && options.staticDir !== undefined
+        ? await resolveHostDispatchScriptHashes(options.staticDir, options.securityHeaders, cspScriptHashes)
+        : [];
+    const fetchHandler = withSecurityHeaders(config.bootOptionWiring.wrapFetch(options.staticDir
+        ? buildStaticFallback(entrypoint.app.fetch.bind(entrypoint.app), options.staticDir, options.hostDispatch, options.resolvePageHead
+            ? { resolvePageHead: options.resolvePageHead, dispatcher: entrypoint.dispatcher }
+            : undefined, entrypoint.dispatcher, config.trustedProxyHops ?? 0, hostDispatchScriptHashes)
+        : // No staticDir (split-deploy / API-only container) → app.fetch's
+            // response goes straight to the client, bypassing buildStaticFallback
+            // (and with it tryHonoFirst) entirely. Must strip the router-miss
+            // marker here too, same reason as the /api/* passthrough in
+            // run-prod-app-static-files.ts (see try-hono-first.ts).
+            async (req, socketAddress) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req, socketAddress))), options.securityHeaders, cspScriptHashes);
+    return { fetchHandler, cspScriptHashes };
+}
+export function createProdAppHandle(input) {
+    const { options, config, composed, connections, entrypoint, log } = input;
+    const { fetchHandler, cspScriptHashes } = input.fetch;
+    // Upgrade rejections (401/403/426...) are ordinary responses and get the same headers as fetchHandler.
+    // Same read-only demo gate as fetchHandler: upgrade requests are GETs, but the socket then writes.
+    const securedUpgradeFetch = withSecurityHeaders(config.bootOptionWiring.wrapFetch(async (req, env) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req, env))), options.securityHeaders, cspScriptHashes);
+    const webSocketUpgradeFetch = async (req, env) => securedUpgradeFetch(req, env);
+    let uninstallShutdownSignals;
+    let uninstallFatalHandlers;
+    const handle = {
+        entrypoint,
+        fetch: fetchHandler,
+        webSocketUpgradeFetch,
+        listen: async (listenPort = config.port) => {
+            // Bun.serve provides production HTTP. Tests run under Node, so they call the
+            // fetch handler directly instead. buildBunServeOptions centralizes the
+            // options shape, including `idleTimeout: 0` for SSE.
+            if (typeof Bun === "undefined") {
+                // Throw a clear error instead of a raw ReferenceError when listen() is called
+                // under Node/vitest without autoListen:false, making the runtime
+                // requirement explicit.
+                throw new Error("[runProdApp] listen() requires Bun runtime (Bun.serve). " +
+                    "Under Node/vitest pass `autoListen: false` and call the returned `fetch()` directly.");
+            }
+            handle.server = Bun.serve(buildBunServeOptions(listenPort, fetchHandler, options.maxRequestBodySize ?? resolveDerivedMaxRequestBodySize(composed.registry), { upgradeFetch: webSocketUpgradeFetch }));
+            // SIGTERM/SIGINT — graceful shutdown. Only registered when we
+            // actually own a Bun-server, otherwise the test process picks up
+            // signals it shouldn't respond to.
+            if (options.signals !== false) {
+                uninstallShutdownSignals?.();
+                uninstallShutdownSignals = installShutdownSignals({
+                    stop: () => handle.stop(),
+                    ...(options.signals?.drainTimeoutMs !== undefined && {
+                        drainTimeoutMs: options.signals.drainTimeoutMs,
+                    }),
+                });
+                uninstallFatalHandlers?.();
+                uninstallFatalHandlers = installFatalErrorHandlers({
+                    logger: log,
+                    stop: () => handle.stop(),
+                });
+            }
+            log.info(`ready on http://0.0.0.0:${listenPort}`);
+        },
+        stop: async () => {
+            uninstallFatalHandlers?.();
+            uninstallFatalHandlers = undefined;
+            await entrypoint.stop();
+            if (handle.server)
+                await stopServerGracefully(handle.server);
+            await flushEscapeHatchAudits();
+            await connections.closeDb();
+            await connections.closeOutsideTransactionDb();
+            connections.redis.disconnect();
+            await config.bootKms.close();
+            uninstallShutdownSignals?.();
+            uninstallShutdownSignals = undefined;
+            uninstallProcessLogger();
+        },
+    };
+    return handle;
+}

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

@@ -0,0 +1,15 @@
+import type { RunProdAppOptions } from "./run-prod-app.ts";
+import type { ProdBootConfig, ProdComposedFeatures } from "./run-prod-app-config.ts";
+import type { ProdConnections } from "./run-prod-app-connections.ts";
+export declare function buildProdRequestContext(options: RunProdAppOptions, config: ProdBootConfig, composed: ProdComposedFeatures, connections: ProdConnections): Promise<{
+    idempotency: import("@cosmicdrift/kumiko-framework/pipeline").IdempotencyGuard;
+    eventDedup: import("@cosmicdrift/kumiko-framework/pipeline").EventDedup;
+    entityCache: import("@cosmicdrift/kumiko-types/entity-cache").EntityCache;
+    sseBroker: import("@cosmicdrift/kumiko-framework/api").SseBroker;
+    ownedRedisSseBroker: import("@cosmicdrift/kumiko-framework/api").RedisSseBroker | undefined;
+    extraContext: {
+        defaultLocale?: string | undefined;
+    };
+    resolvedAnonymousAccess: import("@cosmicdrift/kumiko-framework/api").AnonymousAccessResolved | undefined;
+}>;
+export type ProdRequestContext = Awaited<ReturnType<typeof buildProdRequestContext>>;

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

@@ -0,0 +1,103 @@
+import { resolveAnonymousAccessFromRegistry } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createDefaultSseBroker } from "@cosmicdrift/kumiko-framework/api";
+import { configureBlindIndexKey, configurePiiSubjectKms, } from "@cosmicdrift/kumiko-framework/crypto";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import { createFallbackLogger, setProcessLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { createEntityCache, createEventDedup, createIdempotencyGuard, } from "@cosmicdrift/kumiko-framework/pipeline";
+import { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, } from "./run-prod-app-boot-context.js";
+function buildProdExtraContext(options, config, composed, connections, deps) {
+    const { envSource, bootKms } = config;
+    const { registry, features, effectiveAuth, bootCrypto, unsubscribeLinks } = composed;
+    const resolvedExtraContext = typeof options.extraContext === "function"
+        ? options.extraContext(deps)
+        : (options.extraContext ?? {});
+    // Install framework defaults first; app values in resolvedExtraContext always
+    // win (for example, an app-specific configResolver).
+    // The app-wide cipher is resolved lazily, so entities without encrypted
+    // fields never access it.
+    configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
+    // Subject-key KMS for pii-annotated fields (crypto-shredding).
+    // No adapter only gets this far when assertPiiBootInvariants above let it
+    // through: no PII carriers, or an explicit allowPlaintextPii opt-out. The
+    // engine then stays off and those fields are stored in plaintext.
+    configurePiiSubjectKms(bootKms.kms);
+    // Blind-index key boot gate: with KMS enabled, lookupable fields are stored as
+    // ciphertext. Without the key, equality lookups such as login by email cannot
+    // work, so fail fast rather than allowing silently broken authentication.
+    configureBlindIndexKey(bootKms.blindIndexKey);
+    const bootLogger = loggerFromExtraContext(resolvedExtraContext);
+    if (bootLogger)
+        setProcessLogger(bootLogger);
+    const autoExtraContext = buildBootExtraContext({
+        db: connections.db,
+        features,
+        envSource,
+        registry,
+        hasAuth: !!effectiveAuth,
+        sseBroker: deps.sseBroker,
+        redis: connections.redis,
+        crypto: bootCrypto,
+        ...(bootKms.kms && { kms: bootKms.kms }),
+        ...(bootLogger && { log: bootLogger }),
+        ...(unsubscribeLinks && { unsubscribeLinks }),
+        ...(options.appOverrides && { appOverrides: options.appOverrides }),
+    });
+    return {
+        ...addConfigAccessorFactory({ ...autoExtraContext, ...resolvedExtraContext }, registry),
+        ...(options.defaultLocale !== undefined && { defaultLocale: options.defaultLocale }),
+    };
+}
+async function resolveProdAnonymousAccess(options, deps) {
+    const baseAnonymousAccess = typeof options.anonymousAccess === "function"
+        ? options.anonymousAccess(deps)
+        : options.anonymousAccess;
+    // tenantResolver / tenantExists come from auth-foundation providers.
+    return resolveAnonymousAccessFromRegistry(baseAnonymousAccess, {
+        db: deps.db,
+        registry: deps.registry,
+        warn: (message) => createFallbackLogger("runProdApp").warn(message),
+    });
+}
+export async function buildProdRequestContext(options, config, composed, connections) {
+    const { db, redis } = connections;
+    const { registry, bootCrypto } = composed;
+    // Pipeline pieces — same default config as runDevApp's setupTestStack.
+    const idempotency = createIdempotencyGuard(redis, { ttlSeconds: 60 });
+    const eventDedup = createEventDedup(redis, { ttlSeconds: 60 });
+    const entityCache = createEntityCache(redis, { ttlSeconds: 60 });
+    // When no lifecycle is supplied, createApiEntrypoint builds and owns it;
+    // the handle exposes it for SIGTERM.
+    //
+    // extraContext and anonymousAccess accept either an object or a factory that
+    // receives {db, redis, registry}; factories are useful when boot-time database
+    // access is needed, such as a subdomain-to-tenant resolver.
+    //
+    // Build the SSE broker here so extraContext factories can close over it, and
+    // pass the same broker into createApiEntrypoint (sseBroker option) so
+    // server-internal broadcasts and app-specific publishes share one broker. Use
+    // createDefaultSseBroker so REDIS_URL selects a Redis-backed broker; an
+    // unconditional in-memory broker would silently override buildServer's
+    // Redis-backed default (ServerOptions.sseBroker always wins) and prevent
+    // cross-replica fanout.
+    const { sseBroker, ownedRedisSseBroker } = createDefaultSseBroker(config.envSource);
+    const deps = {
+        db,
+        redis,
+        registry,
+        sseBroker,
+        env: config.envSource,
+        ...(bootCrypto.masterKeyProvider && { masterKeyProvider: bootCrypto.masterKeyProvider }),
+        ...(bootCrypto.configCipher && { configEncryption: bootCrypto.configCipher }),
+    };
+    const extraContext = buildProdExtraContext(options, config, composed, connections, deps);
+    const resolvedAnonymousAccess = await resolveProdAnonymousAccess(options, deps);
+    return {
+        idempotency,
+        eventDedup,
+        entityCache,
+        sseBroker,
+        ownedRedisSseBroker,
+        extraContext,
+        resolvedAnonymousAccess,
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { RunProdAppOptions } from "./run-prod-app.ts";
+import type { ProdBootConfig, ProdComposedFeatures } from "./run-prod-app-config.ts";
+import type { ProdConnections } from "./run-prod-app-connections.ts";
+import type { ProdEntrypoint, ProdEntrypointOptions } from "./run-prod-app-entrypoint.ts";
+import type { ProdRequestContext } from "./run-prod-app-request-context.ts";
+export type ProdSeedRun = {
+    readonly options: RunProdAppOptions;
+    readonly config: ProdBootConfig;
+    readonly composed: ProdComposedFeatures;
+    readonly connections: ProdConnections;
+    readonly requestContext: ProdRequestContext;
+};
+export declare function runProdBootSeeds(run: ProdSeedRun, entrypoint: ProdEntrypoint, dispatcherOptions: ProdEntrypointOptions["dispatcherOptions"]): Promise<void>;

package/dist/run-prod-app-seeds.js

@@ -0,0 +1,88 @@
+import { withFileProviderResolver } from "@cosmicdrift/kumiko-framework/api";
+import { createEsOperationsTable, createSeedMigrationContext, runPendingSeedMigrations, } from "@cosmicdrift/kumiko-framework/es-ops";
+import { createDispatcher, createUnlimitedRateLimitResolver, } from "@cosmicdrift/kumiko-framework/pipeline";
+import { applyStandardBootSeeds } from "./boot/shared-boot-steps.js";
+import { makeSeedCreateFileRef, withSeedErrorContext, } from "./seed-dispatcher.js";
+// Seeds are bootstrap writes, not tenant traffic: they always get the unlimited resolver,
+// even when the app has a real one, so a handler's rateLimit can neither fail nor drain them.
+function buildSeedContext(run) {
+    const { registry } = run.composed;
+    const { db, redis, cacheSync } = run.connections;
+    return withFileProviderResolver(registry, {
+        db,
+        redis,
+        entityCache: run.requestContext.entityCache,
+        registry,
+        ...run.requestContext.extraContext,
+        rateLimit: createUnlimitedRateLimitResolver(),
+    }, cacheSync);
+}
+async function runCustomSeeds(run, seedContext, seedDispatcher) {
+    const { db } = run.connections;
+    const { registry, bootCrypto } = run.composed;
+    const createFileRef = makeSeedCreateFileRef({
+        db,
+        registry,
+        context: seedContext,
+    });
+    for (const seed of run.config.bootOptionWiring.customSeeds) {
+        await seed({
+            db,
+            registry,
+            dispatcher: seedDispatcher,
+            createFileRef,
+            ...(bootCrypto.masterKeyProvider && { masterKeyProvider: bootCrypto.masterKeyProvider }),
+            ...(bootCrypto.configCipher && { configEncryption: bootCrypto.configCipher }),
+        });
+    }
+}
+// ES operations and seed migrations run after applyBootSeeds and the existing
+// seeds array. Declarative seeds insert missing records; seed migrations
+// diff and update state that existing seeds cannot revise, such as membership
+// roles changed after initial seed creation.
+async function runSeedMigrations(run, seedsDir, seedDispatcher) {
+    const { db } = run.connections;
+    await createEsOperationsTable(db);
+    await runPendingSeedMigrations({
+        db,
+        seedsDir,
+        appliedBy: "boot",
+        registry: run.composed.registry, // The dry-run validator catches handler QN typos before writing.
+        // @wrapper-known semantic-alias
+        createContext: (dbRunner) => createSeedMigrationContext({ dispatcher: seedDispatcher, dbRunner }),
+    });
+}
+// Seeds: admin first, then config-seeds from r.config({seeds}),
+// then app-specific. All idempotent — runProdApp doesn't gate
+// "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.
+export async function runProdBootSeeds(run, entrypoint, dispatcherOptions) {
+    const { options, config, composed, connections } = run;
+    await applyStandardBootSeeds({
+        db: connections.db,
+        registry: composed.registry,
+        admin: composed.effectiveAuth?.admin,
+        shortcutSeeds: config.bootOptionWiring.shortcutSeeds,
+        cipher: composed.bootCrypto.configCipher,
+        processName: "runProdApp",
+        ...(options.databaseWait && { databaseWait: options.databaseWait }),
+    });
+    const hasSeeds = config.bootOptionWiring.customSeeds.length > 0 || options.seedsDir !== undefined;
+    const seedContext = hasSeeds ? buildSeedContext(run) : undefined;
+    const seedDispatcher = seedContext
+        ? withSeedErrorContext(createDispatcher(composed.registry, seedContext, {
+            ...dispatcherOptions,
+            lifecycle: entrypoint.lifecycleHooks,
+            ...(entrypoint.mode === "all-in-one" && { jobRunner: entrypoint.jobRunner }),
+        }))
+        : undefined;
+    if (seedDispatcher && seedContext) {
+        await runCustomSeeds(run, seedContext, seedDispatcher);
+    }
+    if (seedDispatcher &&
+        options.seedsDir !== undefined &&
+        config.envSource["KUMIKO_SKIP_ES_OPS"] !== "1") {
+        await runSeedMigrations(run, options.seedsDir, seedDispatcher);
+    }
+}

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

@@ -1,9 +1,10 @@
+import { existsSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { cachedResponse, computeStrongEtag, computeWeakEtag, createClientIpResolver, } from "@cosmicdrift/kumiko-framework/api";
 import { rankPreferredLocales } from "@cosmicdrift/kumiko-framework/i18n";
 import { resolveAndInjectPageHead } from "@cosmicdrift/kumiko-renderer/headless/apex";
 import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
-import { ASSETS_DIR } from "./build-prod-bundle.js";
+import { ASSETS_DIR, collectBuildScriptHashes } from "./build-prod-bundle.js";
 import { BUNDLED_ASSETS_DIST_DIR } from "./bundled-assets.js";
 import { CSP_HASHES_FILE, parseCspHashes } from "./csp-hashes.js";
 import { buildRequestBoundSystemQuery, } from "./request-bound-system-query.js";
@@ -67,7 +68,14 @@ function usesDefaultCsp(securityHeaders) {
 export async function resolveHostDispatchScriptHashes(staticDir, securityHeaders, defaultCspHashes) {
     return usesDefaultCsp(securityHeaders) ? defaultCspHashes : readBuildScriptHashes(staticDir);
 }
+// Apps also write HTML into staticDir at boot (rendered landing pages), after kumiko build wrote
+// the file; staticDir is server-owned, so hashing what is on disk never trusts request data.
 export async function readBuildScriptHashes(staticDir) {
+    const fromFile = await readBuildHashesFile(staticDir);
+    const onDisk = existsSync(staticDir) ? collectBuildScriptHashes(staticDir).scriptSrc : [];
+    return [...new Set([...fromFile, ...onDisk])].sort();
+}
+async function readBuildHashesFile(staticDir) {
     const file = await readStaticFile(join(staticDir, CSP_HASHES_FILE));
     const result = file ? parseCspHashes(new TextDecoder().decode(file.bytes)) : undefined;
     if (result?.kind === "found")

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

@@ -1,36 +1,37 @@
 /// <reference types="bun-types" preserve="true" />
-import { type AccountLockoutOptions, type AccountUnlockOptions, type AuthMailLocale, type AuthPaths, type EmailVerificationOptions, type InviteOptions, type PasswordResetOptions, type SignupOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
-import { type SeedAdminOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
-import { type ExtraRouteDefinition, type KumikoServeEnv, type PostAuthLandingResolver, type SseBroker } from "@cosmicdrift/kumiko-framework/api";
-import { type KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
-import { type FeatureDefinition, type ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
-import { type AllInOneEntrypoint, type ApiEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
+import type { AccountLockoutOptions, AccountUnlockOptions, AuthMailLocale, AuthPaths, EmailVerificationOptions, InviteOptions, PasswordResetOptions, SignupOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import type { SeedAdminOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import type { ExtraRouteDefinition, KumikoServeEnv, PostAuthLandingResolver, SseBroker } from "@cosmicdrift/kumiko-framework/api";
+import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import type { BundledListsOptions, FeatureDefinition, ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
+import type { AllInOneEntrypoint, ApiEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
 import type { ComposedEnvSchema, KumikoBootError } from "@cosmicdrift/kumiko-framework/env";
 import type { ErrorDocsConfig } from "@cosmicdrift/kumiko-framework/errors";
 import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
-import { type ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
+import type { ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
 import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import type { PageHeadMeta, PageHeadResolver, PageHeadSystemQuery } from "@cosmicdrift/kumiko-renderer/headless/apex";
-import { Redis } from "ioredis";
+import type { Redis } from "ioredis";
+import type { DatabaseWaitClock } from "./boot/wait-for-database.ts";
 import type { BillingBootOption } from "./boot-options/billing-option.ts";
 import type { DemoModeOption } from "./boot-options/demo-mode.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 SignalsOption } from "./boot-options/process-signals.ts";
+import type { SignalsOption } from "./boot-options/process-signals.ts";
 import type { ProdSeedsConfig } from "./boot-options/seed-shortcuts.ts";
-import { type SystemWireDeps } from "./extra-routes-deps.ts";
-import { type RateLimitOption } from "./rate-limit-defaults.ts";
-import { type UnsubscribeOption } from "./resolve-unsubscribe-wiring.ts";
-import { type ConfigOverridesInput } from "./run-prod-app-boot-context.ts";
-import { type SecurityHeadersOption } from "./security-headers.ts";
-import { type SeedCreateFileRef } from "./seed-dispatcher.ts";
+import type { SystemWireDeps } from "./extra-routes-deps.ts";
+import type { RateLimitOption } from "./rate-limit-defaults.ts";
+import type { UnsubscribeOption } from "./resolve-unsubscribe-wiring.ts";
+import type { ConfigOverridesInput } from "./run-prod-app-boot-context.ts";
+import type { SecurityHeadersOption } from "./security-headers.ts";
+import type { SeedCreateFileRef } from "./seed-dispatcher.ts";
 export { parseRunMode } from "./boot/env-gate.ts";
 export { buildBunServeOptions } from "./bun-serve-options.ts";
+export { requireEnv } from "./require-env.ts";
 export { resolveUnsubscribeWiring, type UnsubscribeOption, } from "./resolve-unsubscribe-wiring.ts";
-export { addConfigAccessorFactory, buildBootExtraContext, type ConfigOverridesInput, loggerFromExtraContext, resolveAuthMail, } from "./run-prod-app-boot-context.ts";
+export { addConfigAccessorFactory, buildBootExtraContext, buildConfigOverrides, type ConfigOverridesInput, loggerFromExtraContext, resolveAuthMail, } from "./run-prod-app-boot-context.ts";
 export { staticCachePolicy } from "./run-prod-app-static-files.ts";
-export declare function requireEnv(name: string, src?: Record<string, string | undefined>, context?: string): string;
 /** Wrapper API for the password-reset flow.
  *
  *  Since the delivery migration PasswordResetOptions carries `appUrl`
@@ -263,6 +264,8 @@ export type RunProdAppOptions = {
     readonly features: readonly FeatureDefinition[];
     /** Opt-in boot-validator warnings — see ValidateBootOptions. */
     readonly validateBootOptions?: ValidateBootOptions;
+    /** One table block for every list of the bundled features, see ComposeFeaturesOptions.bundledLists. */
+    readonly bundledLists?: BundledListsOptions;
     /** Listen-Port. Default 3000 (or $PORT). */
     readonly port?: number;
     /** Ceiling Bun.serve buffers a request body to before any app-level
@@ -349,6 +352,9 @@ export type RunProdAppOptions = {
      *  cannot start against an unreachable KMS. Without an adapter,
      *  crypto-shredding remains disabled. */
     readonly kms?: KmsAdapter;
+    /** Replaces the real clock, sleep and log sink of the boot backoff for the database, KMS and
+     *  seed waits; tests use it to run the retry path without real waiting. */
+    readonly databaseWait?: DatabaseWaitClock;
     /** 32-byte base64 key for blind-index HMACs on `lookupable` fields
      *  (env: KUMIKO_BLIND_INDEX_KEY, `openssl rand -base64 32`). It is separate
      *  from PLATFORM_KEK and not part of the KmsAdapter contract. It is required
@@ -380,7 +386,7 @@ export type RunProdAppOptions = {
      *  @example
      *  fileStorage: { provider: "auto" } */
     readonly fileStorage?: FileStorageBootOption;
-    /** Stripe billing: `subscription-stripe` plus the tier-syncing webhook
+    /** Billing: `subscription-stripe` and/or `subscription-dodo` plus one tier-syncing webhook
      *  route. Needs `billing-foundation` and `tier-engine`. See `BillingBootOption`.
      *  @example
      *  billing: { stripe: { priceToTier: { [env.STRIPE_PRICE_PRO]: "pro" } }, defaultTier: "free" } */
@@ -449,7 +455,9 @@ export type RunProdAppOptions = {
      *  then the `APP_BASE_URL` env; with none of them no link is added (boot warning). Address
      *  recipients need a blind-index key, otherwise they get no link. Do not also mount
      *  `createUnsubscribeRoutes` via `extraRoutes`. `tenantOrigin` points a tenant's links at
-     *  its own subdomain or custom domain (the host must serve this app's `/api` routes); null,
+     *  its own subdomain or custom domain (the host must serve this app's `/api` routes, and
+     *  the callback must only return a verified, active domain, else null: the link carries a bearer
+     *  token a stale domain's new owner would receive); null,
      *  a throw or a non-https value fall back to the app origin. The link carries the mail's
      *  locale, so the confirmation pages speak the mail's language. An app reacts to an address
      *  opt-out with an `r.job` triggered on `DeliveryHandlers.unsubscribeAddress`. */