@cosmicdrift/kumiko-server-runtime 0.382.0 → 0.383.1

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

@@ -5,7 +5,7 @@
 // share every step that decides ciphers, blind indexes and config encryption.
 import { loadJwtSecretOrKeyring } from "@cosmicdrift/kumiko-framework/api";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
-import { configureEntityFieldEncryption, createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
+import { configureEntityFieldEncryption, createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, serverTimeoutOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
 import { createRegistry, findTierResolverUsage, requireTierResolverPlugin, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
 import { createWorkerEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
 import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
@@ -108,10 +108,12 @@ export async function bootWorkerProcess(options, envSource, profile) {
     const { db, close: closeDb } = createDbConnection({
         url: databaseUrl,
         ...dbConnectionOptionsFromEnv(envSource),
+        ...serverTimeoutOptionsFromEnv(envSource),
     });
     const { db: outsideTransactionDb, close: closeOutsideTransactionDb } = createDbConnection({
         url: databaseUrl,
         ...outsideTransactionPoolOptionsFromEnv(envSource),
+        ...serverTimeoutOptionsFromEnv(envSource),
     });
     const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
     const cacheSync = createRedisCacheSyncBus({

package/dist/fatal-error-handlers.d.ts

@@ -0,0 +1,8 @@
+import { type Logger } from "@cosmicdrift/kumiko-framework/logging";
+export type FatalErrorHandlersOptions = {
+    readonly logger: Pick<Logger, "error">;
+    readonly stop: () => Promise<void>;
+    readonly exit?: (code: number) => void;
+    readonly hardExitMs?: number;
+};
+export declare function installFatalErrorHandlers(options: FatalErrorHandlersOptions): () => void;

package/dist/fatal-error-handlers.js

@@ -0,0 +1,48 @@
+import { scrubLogText } from "@cosmicdrift/kumiko-framework/logging";
+const DEFAULT_HARD_EXIT_MS = 10_000;
+function describeFatal(reason) {
+    if (reason instanceof Error) {
+        return {
+            message: scrubLogText(reason.message),
+            ...(reason.stack !== undefined && { stack: scrubLogText(reason.stack) }),
+        };
+    }
+    return { message: scrubLogText(String(reason)) };
+}
+// A process in an unknown state must not keep serving; the hard-exit timer
+// covers a stop() that hangs on the very fault that triggered it.
+export function installFatalErrorHandlers(options) {
+    const { logger, stop } = options;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const hardExitMs = options.hardExitMs ?? DEFAULT_HARD_EXIT_MS;
+    let handling = false;
+    const handle = (source) => (reason) => {
+        // skip: a second fault during shutdown is already covered by the running stop and hard-exit timer
+        if (handling)
+            return;
+        handling = true;
+        logger.error("fatal process error, shutting down", {
+            fatal: true,
+            source,
+            ...describeFatal(reason),
+        });
+        const hardExitTimer = setTimeout(() => exit(1), hardExitMs);
+        hardExitTimer.unref();
+        void stop()
+            .catch((stopError) => {
+            logger.error("shutdown after fatal error failed", describeFatal(stopError));
+        })
+            .finally(() => {
+            clearTimeout(hardExitTimer);
+            exit(1);
+        });
+    };
+    const onUncaughtException = handle("uncaughtException");
+    const onUnhandledRejection = handle("unhandledRejection");
+    process.on("uncaughtException", onUncaughtException);
+    process.on("unhandledRejection", onUnhandledRejection);
+    return () => {
+        process.off("uncaughtException", onUncaughtException);
+        process.off("unhandledRejection", onUnhandledRejection);
+    };
+}

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { assertStackBootRequirements } from "./boot-options/stack-boot-requireme
 export { type BundledAssetDeclaration, type BundledAssetOptions, readBundledAsset, resolveBundledAsset, } from "./bundled-assets.ts";
 export { type ComposeFeaturesOptions, composeFeatures } from "./compose-features.ts";
 export { type DiskFileRouteOptions, diskFileRoute } from "./disk-file-route.ts";
+export { type FatalErrorHandlersOptions, installFatalErrorHandlers, } from "./fatal-error-handlers.ts";
 export type { RateLimitOption } from "./rate-limit-defaults.ts";
 export type { RunBootstrapOptions } from "./run-bootstrap.ts";
 export { runBootstrap } from "./run-bootstrap.ts";

package/dist/index.js

@@ -12,6 +12,7 @@ export { assertStackBootRequirements } from "./boot-options/stack-boot-requireme
 export { readBundledAsset, resolveBundledAsset, } from "./bundled-assets.js";
 export { composeFeatures } from "./compose-features.js";
 export { diskFileRoute } from "./disk-file-route.js";
+export { installFatalErrorHandlers, } from "./fatal-error-handlers.js";
 export { runBootstrap } from "./run-bootstrap.js";
 export { parseRunMode, requireEnv, runProdApp } from "./run-prod-app.js";
 export { runWorkerApp } from "./run-worker-app.js";

package/dist/process-logger.d.ts

@@ -0,0 +1,3 @@
+import { type Logger } from "@cosmicdrift/kumiko-framework/logging";
+export declare function installProcessLogger(extraContext: unknown, consolePrefix: string): Logger;
+export declare function uninstallProcessLogger(): void;

package/dist/process-logger.js

@@ -0,0 +1,42 @@
+import { createLogger, setProcessLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { loggerFromExtraContext } from "./run-prod-app-boot-context.js";
+const CONSOLE_METHOD_BY_LEVEL = {
+    info: "log",
+    warn: "warn",
+    error: "error",
+    debug: "debug",
+};
+function createConsoleLogger(prefix) {
+    const write = (level) => (msg, data) => {
+        const method = CONSOLE_METHOD_BY_LEVEL[level];
+        const line = `[${prefix}] ${msg}`;
+        // biome-ignore lint/suspicious/noConsole: outside production, boot output stays human-readable on the console
+        console[method](...(data ? [line, data] : [line]));
+    };
+    return {
+        info: write("info"),
+        warn: write("warn"),
+        error: write("error"),
+        debug: write("debug"),
+        child: () => createConsoleLogger(prefix),
+    };
+}
+// Function-form extraContext needs boot deps, so only a static one can supply the logger this early.
+// Outside production no process logger is installed, so fallback loggers keep their console output.
+export function installProcessLogger(extraContext, consolePrefix) {
+    const appLogger = typeof extraContext === "object" && extraContext !== null
+        ? loggerFromExtraContext(Object.fromEntries(Object.entries(extraContext)))
+        : undefined;
+    if (appLogger) {
+        setProcessLogger(appLogger);
+        return appLogger;
+    }
+    if (process.env["NODE_ENV"] !== "production")
+        return createConsoleLogger(consolePrefix);
+    const logger = createLogger({ pretty: false });
+    setProcessLogger(logger);
+    return logger;
+}
+export function uninstallProcessLogger() {
+    setProcessLogger(null);
+}

package/dist/run-prod-app.js

@@ -47,18 +47,18 @@ import { PAT_FEATURE, patRateLimitFromFeature, } from "@cosmicdrift/kumiko-bundl
 import { SESSIONS_FEATURE } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
-import { createDefaultSseBroker, createRedisLoginRateLimiter, loadJwtSecretOrKeyring, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, withFileProviderResolver, } from "@cosmicdrift/kumiko-framework/api";
+import { createDefaultSseBroker, createRedisLoginRateLimiter, loadJwtSecretOrKeyring, TRUSTED_PROXY_HOPS_ENV, withFileProviderResolver, } from "@cosmicdrift/kumiko-framework/api";
 import { configureBlindIndexKey, configurePiiSubjectKms, } from "@cosmicdrift/kumiko-framework/crypto";
-import { configureEntityFieldEncryption, createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
+import { configureEntityFieldEncryption, createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, serverTimeoutOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
 import { collectWriteHandlerQns, createRegistry, findTierResolverUsage, requireTierResolverPlugin, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
 import { createAllInOneEntrypoint, createApiEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
 import { createEsOperationsTable, createSeedMigrationContext, runPendingSeedMigrations, } from "@cosmicdrift/kumiko-framework/es-ops";
 import { assertSeedModeNotInProduction } from "@cosmicdrift/kumiko-framework/event-store";
-import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { createFallbackLogger, setProcessLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
 import { createMetricsForFactory, } from "@cosmicdrift/kumiko-framework/observability";
 import { createDispatcher, createEntityCache, createEventDedup, createIdempotencyGuard, createUnlimitedRateLimitResolver, flushEscapeHatchAudits, } from "@cosmicdrift/kumiko-framework/pipeline";
-import { createRedisCacheSyncBus, redisClientOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/redis";
+import { createRedisCacheSyncBus, logRedisConnectionState, 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";
@@ -74,7 +74,9 @@ import { assertStackBootRequirements } from "./boot-options/stack-boot-requireme
 import { buildBunServeOptions, resolveDerivedMaxRequestBodySize } from "./bun-serve-options.js";
 import { buildComposeAuthOptions, composeFeatures } from "./compose-features.js";
 import { makeDispatchSystemQuery, makeDispatchSystemWrite, } from "./extra-routes-deps.js";
+import { installFatalErrorHandlers } from "./fatal-error-handlers.js";
 import { assertPiiBootInvariants } from "./pii-boot-gate.js";
+import { installProcessLogger, uninstallProcessLogger } from "./process-logger.js";
 import { resolveRateLimit } from "./rate-limit-defaults.js";
 import { resolveAuthPublicOrigin } from "./resolve-auth-public-origin.js";
 import { resolveUnsubscribeWiring } from "./resolve-unsubscribe-wiring.js";
@@ -84,6 +86,7 @@ import { withSecurityHeaders } from "./security-headers.js";
 import { makeSeedCreateFileRef, withSeedErrorContext, } from "./seed-dispatcher.js";
 import { assertSessionBootInvariants } from "./session-boot-gate.js";
 import { shouldWireProdSessions } from "./session-wiring.js";
+import { resolveTrustedProxyHops } from "./trusted-proxy-hops.js";
 import { stripNoRouteMatchHeader } from "./try-hono-first.js";
 export { parseRunMode } from "./boot/env-gate.js";
 export { buildBunServeOptions } from "./bun-serve-options.js";
@@ -130,14 +133,28 @@ function makeDryRunHandle() {
         stop: noop,
     };
 }
+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);
+}
 let warnedLegacyJwtSecret = false;
 function warnLegacyJwtSecretOnce() {
     // skip: already warned once this process — avoid log spam on every boot path.
     if (warnedLegacyJwtSecret)
         return;
     warnedLegacyJwtSecret = true;
-    // biome-ignore lint/suspicious/noConsole: boot-time ops hint, no logger configured this early
-    console.warn("[runProdApp] JWT keyring carries a legacy (pre-rotation) verify-only key — " +
+    createFallbackLogger("runProdApp").warn("JWT keyring carries a legacy (pre-rotation) verify-only key — " +
         "it never expires on its own. JWT_SECRET remains a required env (hmacSecret " +
         "fallback + boot requireEnv). To stop verifying with the pre-rotation secret: " +
         "set auth.mail.hmacSecret explicitly, then rotate JWT_SECRET to a fresh value " +
@@ -167,6 +184,7 @@ export async function runProdApp(options) {
     if (envGate.kind === "stopped")
         return makeDryRunHandle();
     const { runMode, decryptedEnvSource } = envGate;
+    const log = installProcessLogger(options.extraContext, "runProdApp");
     // Stacks whose boot options are missing and the declarative boot options
     // (mail, kmsMode, fileStorage, billing, demoMode, seed shortcuts) fail here, before any connection. Their defaults sit under
     // the env so an explicitly set variable wins.
@@ -204,20 +222,21 @@ export async function runProdApp(options) {
     // kumiko-framework#1539 — options.auth.trustedProxyHops wins; falls back
     // to the env var so ops can close the XFF-spoofing hole per-deployment
     // without a code change (mirrors instanceId's env-first pattern above).
-    const trustedProxyHops = options.trustedProxyHops ??
-        options.auth?.trustedProxyHops ??
-        parseTrustedProxyHopsEnv(readEnv(TRUSTED_PROXY_HOPS_ENV, envSource), "runProdApp");
+    const trustedProxyHops = resolveTrustedProxyHops({
+        option: options.trustedProxyHops,
+        authOption: options.auth?.trustedProxyHops,
+        envValue: readEnv(TRUSTED_PROXY_HOPS_ENV, envSource),
+        nodeEnv: process.env["NODE_ENV"],
+    });
     if (trustedProxyHops === undefined) {
         // With 0 hops every request appears to come from the proxy pod, so all IP-keyed
         // rate limiters collapse into one shared bucket behind a reverse proxy.
-        // biome-ignore lint/suspicious/noConsole: boot-time warn, no logger configured this early
-        console.warn(`[runProdApp] trustedProxyHops / ${TRUSTED_PROXY_HOPS_ENV} is not set; client IP falls back to the socket address. ` +
+        log.warn(`trustedProxyHops / ${TRUSTED_PROXY_HOPS_ENV} is not set; client IP falls back to the socket address. ` +
             "Behind a reverse proxy all clients share one rate-limit bucket, so the default L1/L2 limits throttle the whole site at once.");
     }
     const resolvedRateLimit = resolveRateLimit(options.rateLimit);
     const port = options.port ?? Number.parseInt(envSource["PORT"] ?? "3000", 10);
-    // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-    console.log(`[runProdApp] booting Kumiko stack on port ${port}…`);
+    log.info(`booting Kumiko stack on port ${port}`);
     // auth.mail → expandiert in die expliziten Flow-Felder, bevor sie sowohl
     // die Feature-Side (buildComposeAuthOptions) als auch das Routes-Fragment
     // unten speisen. Ab hier IMMER effectiveAuth statt options.auth lesen.
@@ -228,8 +247,7 @@ export async function runProdApp(options) {
         : undefined;
     const authPublicOrigin = effectiveAuth
         ? resolveAuthPublicOrigin(effectiveAuth, envSource, (message) => {
-            // biome-ignore lint/suspicious/noConsole: boot-time warn, no logger configured this early
-            console.warn(message);
+            log.warn(message);
         })
         : undefined;
     const { unsubscribeLinks, unsubscribeRoutes } = resolveUnsubscribeWiring({
@@ -277,6 +295,7 @@ export async function runProdApp(options) {
         // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
         console.log(`[runProdApp] boot validation OK (${features.length} features, ${registry.features.size} registry entries)`);
         await bootKms.close();
+        uninstallProcessLogger();
         if (options.envSource === undefined) {
             process.exit(0);
         }
@@ -301,12 +320,15 @@ export async function runProdApp(options) {
     const { db, close: closeDb } = createDbConnection({
         url: databaseUrl,
         ...dbConnectionOptionsFromEnv(envSource),
+        ...serverTimeoutOptionsFromEnv(envSource),
     });
     const { db: outsideTransactionDb, close: closeOutsideTransactionDb } = createDbConnection({
         url: databaseUrl,
         ...outsideTransactionPoolOptionsFromEnv(envSource),
+        ...serverTimeoutOptionsFromEnv(envSource),
     });
     const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
+    logRedisConnectionState(redis, log);
     await waitForDatabase(db, { processName: "runProdApp" });
     // Sprint-8a Tier-Composition auto-wire: scan features for a
     // tenantTierResolver-extension. If found, build the resolver here (db +
@@ -346,15 +368,13 @@ export async function runProdApp(options) {
     //    `migrations: false` für custom Schema-Setups.
     if (options.migrations !== false) {
         const migrationsDir = options.migrations?.dir ?? "./kumiko/migrations";
-        // biome-ignore lint/suspicious/noConsole: boot-time progress hint
-        console.log(`[runProdApp] checking schema drift (${migrationsDir})…`);
+        log.info(`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[runProdApp] BOOT ABORTED — ${err.message}\n`);
+                log.error(`BOOT ABORTED — ${err.message}`);
             }
             throw err;
         }
@@ -413,6 +433,8 @@ export async function runProdApp(options) {
     // silent-broken-auth.
     configureBlindIndexKey(bootKms.blindIndexKey);
     const bootLogger = loggerFromExtraContext(resolvedExtraContext);
+    if (bootLogger)
+        setProcessLogger(bootLogger);
     const autoExtraContext = buildBootExtraContext({
         db,
         features,
@@ -769,6 +791,7 @@ export async function runProdApp(options) {
     const securedUpgradeFetch = withSecurityHeaders(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,
@@ -798,13 +821,20 @@ export async function runProdApp(options) {
                         drainTimeoutMs: options.signals.drainTimeoutMs,
                     }),
                 });
+                uninstallFatalHandlers?.();
+                uninstallFatalHandlers = installFatalErrorHandlers({
+                    logger: log,
+                    stop: () => handle.stop(),
+                });
             }
-            // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-            console.log(`[runProdApp] ready on http://0.0.0.0:${listenPort}`);
+            log.info(`ready on http://0.0.0.0:${listenPort}`);
         },
         stop: async () => {
+            uninstallFatalHandlers?.();
+            uninstallFatalHandlers = undefined;
             await entrypoint.stop();
-            handle.server?.stop();
+            if (handle.server)
+                await stopServerGracefully(handle.server);
             await flushEscapeHatchAudits();
             await closeDb();
             await closeOutsideTransactionDb();
@@ -812,6 +842,7 @@ export async function runProdApp(options) {
             await bootKms.close();
             uninstallShutdownSignals?.();
             uninstallShutdownSignals = undefined;
+            uninstallProcessLogger();
         },
     };
     // 12. Auto-listen unless explicitly suppressed (tests pass autoListen:

package/dist/run-worker-app.js

@@ -15,7 +15,9 @@
 // Container/Coolify sets the same env vars as runProdApp:
 //   DATABASE_URL, REDIS_URL, JWT_SECRET — PORT is not needed.
 import { assertSeedModeNotInProduction } from "@cosmicdrift/kumiko-framework/event-store";
+import { scrubLogText } from "@cosmicdrift/kumiko-framework/logging";
 import { createMetricsForFactory, } from "@cosmicdrift/kumiko-framework/observability";
+import { logRedisConnectionState } from "@cosmicdrift/kumiko-framework/redis";
 import { runEnvGate } from "./boot/env-gate.js";
 import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot.js";
 import { recordAppStartedOnBoot } from "./boot/record-app-started-on-boot.js";
@@ -24,6 +26,8 @@ import { startWorkerMetricsServer, } from "./boot/worker-metrics-server.js";
 import { resolveBootOptionWiring } from "./boot-options/resolve-boot-options.js";
 import { assertStackBootRequirements } from "./boot-options/stack-boot-requirements.js";
 import { makeDispatchSystemQuery, makeDispatchSystemWrite, } from "./extra-routes-deps.js";
+import { installFatalErrorHandlers } from "./fatal-error-handlers.js";
+import { installProcessLogger, uninstallProcessLogger } from "./process-logger.js";
 function makeBootModeHandle() {
     return {
         // @cast-boundary boot-mode: no entrypoint exists because no boot ran —
@@ -49,8 +53,8 @@ export async function runWorkerApp(options) {
     const resolvedEnvSource = await resolveGatedEnvSource(options);
     if (resolvedEnvSource === undefined)
         return makeBootModeHandle();
-    // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-    console.log("[runWorkerApp] booting Kumiko worker…");
+    const log = installProcessLogger(options.extraContext, "runWorkerApp");
+    log.info("booting Kumiko worker");
     assertWorkerStackRequirements(options);
     const wiring = await resolveBootOptionWiring(options, resolvedEnvSource);
     const envSource = Object.keys(wiring.envDefaults).length > 0
@@ -77,9 +81,11 @@ export async function runWorkerApp(options) {
     }
     if (boot.kind === "dry-run") {
         await wiring.kms.close();
+        uninstallProcessLogger();
         return makeBootModeHandle();
     }
     const { db, redis, registry, entrypoint } = boot;
+    logRedisConnectionState(redis, log);
     // 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.
@@ -97,11 +103,15 @@ export async function runWorkerApp(options) {
         await wiring.kms.close().catch(() => { });
         throw error;
     }
+    let uninstallFatalHandlers;
     const handle = {
         entrypoint,
         stop: async () => {
+            uninstallFatalHandlers?.();
+            uninstallFatalHandlers = undefined;
             await boot.close();
             await wiring.kms.close();
+            uninstallProcessLogger();
         },
         ...(metricsServer && { metricsServer }),
     };
@@ -130,16 +140,15 @@ export async function runWorkerApp(options) {
         if (shuttingDown)
             return;
         shuttingDown = true;
-        // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-        console.log(`[runWorkerApp] ${signal} received — draining…`);
+        log.info(`${signal} received, draining`);
         try {
             await handle.stop();
-            // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-            console.log("[runWorkerApp] graceful shutdown complete.");
+            log.info("graceful shutdown complete");
         }
         catch (e) {
-            // biome-ignore lint/suspicious/noConsole: shutdown-time error, only path is stderr
-            console.error("[runWorkerApp] error during shutdown:", e);
+            log.error("error during shutdown", {
+                error: scrubLogText(e instanceof Error ? e.message : String(e)),
+            });
         }
         finally {
             process.exit(0);
@@ -147,7 +156,7 @@ export async function runWorkerApp(options) {
     };
     process.on("SIGTERM", () => void shutdown("SIGTERM"));
     process.on("SIGINT", () => void shutdown("SIGINT"));
-    // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-    console.log("[runWorkerApp] ready — worker running.");
+    uninstallFatalHandlers = installFatalErrorHandlers({ logger: log, stop: () => handle.stop() });
+    log.info("ready, worker running");
     return handle;
 }

package/dist/trusted-proxy-hops.d.ts

@@ -0,0 +1,6 @@
+export declare function resolveTrustedProxyHops(input: {
+    readonly option: number | undefined;
+    readonly authOption: number | undefined;
+    readonly envValue: string | undefined;
+    readonly nodeEnv: string | undefined;
+}): number | undefined;

package/dist/trusted-proxy-hops.js

@@ -0,0 +1,9 @@
+import { parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, } from "@cosmicdrift/kumiko-framework/api";
+export function resolveTrustedProxyHops(input) {
+    const hops = input.option ?? input.authOption ?? parseTrustedProxyHopsEnv(input.envValue, "runProdApp");
+    if (hops === undefined && input.nodeEnv === "production") {
+        throw new Error(`[runProdApp] trustedProxyHops is required in production: pass the trustedProxyHops option or set ${TRUSTED_PROXY_HOPS_ENV} ` +
+            "(0 when the app is exposed directly). Without it every client behind a reverse proxy shares one rate-limit bucket.");
+    }
+    return hops;
+}

package/package.json

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

package/src/changes.json

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "Production logs are plain JSON without the [runProdApp] prefix",
+    "detail": "Behavior change for log parsers and alert rules: runProdApp and runWorkerApp now write one JSON object per line from the process logger, without the former \"[runProdApp]\" text prefix. Match on the component field instead of the prefix."
+  },
+  {
+    "version": "0.383.0",
+    "type": "breaking",
+    "title": "runProdApp requires trustedProxyHops in production",
+    "detail": "In production runProdApp refuses to boot when neither the trustedProxyHops option, the auth option nor KUMIKO_TRUSTED_PROXY_HOPS is set. An explicit 0 is allowed. create-kumiko-app templates write KUMIKO_TRUSTED_PROXY_HOPS=0 into .env.example.",
+    "migration": "set KUMIKO_TRUSTED_PROXY_HOPS=<hops> (0 when the app is exposed directly) or pass trustedProxyHops"
+  },
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "Fatal-error handlers and graceful server stop",
+    "detail": "New installFatalErrorHandlers logs uncaughtException and unhandledRejection, stops the app and exits 1 (hard exit after 10 s). runProdApp and runWorkerApp install it. The HTTP server stop is awaited against a 10 s grace period and then forced before the database closes."
+  },
   {
     "version": "0.379.0",
     "type": "improvement",