@cosmicdrift/kumiko-server-runtime 0.328.1 → 0.330.0

package/src/run-prod-app.ts

@@ -1,1420 +0,0 @@
-// runProdApp — production-grade Bootstrap-Wrapper für Kumiko-Apps.
-//
-// Symmetrisch zu runDevApp, aber:
-//   - DATABASE_URL / REDIS_URL / JWT_SECRET aus env (fail-fast bei Boot,
-//     keine ephemeralen Test-DBs)
-//   - Hard Schema-Drift-Gate: prüft kumiko/migrations vs. _kumiko_migrations
-//     + tableExists für jede erwartete Tabelle. KEIN Auto-CREATE TABLE im
-//     Boot — Migration ist ein CI-Step (`bun kumiko schema apply`), Boot
-//     validiert nur. Verhindert Race-Conditions bei Multi-Replica-Deploys
-//     + macht Schema-Stand reviewbar in der Pull-Request.
-//   - Idempotente Seeds: laufen nur wenn DB leer (über `isDbEmpty`-Probe
-//     pro Seed). Re-Boots nach erstem Seed sind no-op.
-//   - HTTP-Server via Bun.serve mit graceful SIGTERM/SIGINT → drain().
-//   - Auth-Routes + bundled-features auto-mix wenn `auth:` gesetzt
-//     (gleiche Logik wie runDevApp).
-//
-// App-Author schreibt:
-//   await runProdApp({ features, auth, anonymousAccess, seeds });
-//
-// Container/Coolify setzt:
-//   DATABASE_URL=postgresql://...
-//   REDIS_URL=redis://...
-//   JWT_SECRET=<random-32+>  (always required — also signs the password-
-//     reset/email-verification HMAC tokens, a separate non-rotating family)
-//     — additionally, for zero-downtime rotation of the session-JWT
-//     signing key specifically:
-//   JWT_SECRET_V1=<random-32+>  (repeat _V2, _V3, ... per rotation)
-//   JWT_SECRET_CURRENT_VERSION=1  (which V<n> signs new tokens; the others
-//     still verify in-flight tokens until they expire)
-//   Adopting rotation for the first time (no JWT_SECRET_V<n> set yet): the
-//   plain JWT_SECRET above stays set and is carried into the keyring as a
-//   verify-only legacy key (loadJwtSecretOrKeyring), so sessions signed
-//   before the cutover keep verifying — no mass-logout at adoption. This
-//   legacy key never expires on its own (boot logs a warning while it's
-//   present) — once max token TTL has elapsed since cutover, unset
-//   JWT_SECRET to retire it. Check first whether an app relies on the
-//   auth.mail convenience default for passwordReset/emailVerification
-//   hmacSecret (falls back to this same JWT_SECRET) before unsetting it.
-//   PORT=3000
-//   KUMIKO_INSTANCE_ID=<stable per replica>
-
-import {
-  type AccountLockoutOptions,
-  type AccountUnlockOptions,
-  AuthErrors,
-  AuthHandlers,
-  type AuthMailLocale,
-  type AuthPaths,
-  AuthQueries,
-  type EmailVerificationOptions,
-  type InviteOptions,
-  type PasswordResetOptions,
-  type SignupOptions,
-} from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
-import {
-  type SeedAdminOptions,
-  seedAdminGuarded,
-} from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
-import {
-  EXT_SESSION_STORE,
-  EXT_TOKEN_VERIFIER,
-  resolveAnonymousAccessFromRegistry,
-  resolveTokenVerifier,
-} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
-import { AUTH_MFA_FEATURE, AuthMfaHandlers } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
-import {
-  PAT_FEATURE,
-  patRateLimitFromFeature,
-} from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
-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,
-  type ExtraRouteDefinition,
-  type KumikoServeEnv,
-  type LoginRateLimiter,
-  loadJwtSecretOrKeyring,
-  type PostAuthLandingResolver,
-  parseTrustedProxyHopsEnv,
-  type SseBroker,
-  type TokenVerifier,
-  TRUSTED_PROXY_HOPS_ENV,
-} from "@cosmicdrift/kumiko-framework/api";
-import {
-  configureBlindIndexKey,
-  configurePiiSubjectKms,
-  type KmsAdapter,
-  resolvePlatformKeks,
-} from "@cosmicdrift/kumiko-framework/crypto";
-import {
-  configureEntityFieldEncryption,
-  createDbConnection,
-  type DbRunner,
-} from "@cosmicdrift/kumiko-framework/db";
-import {
-  collectWriteHandlerQns,
-  createRegistry,
-  type EffectiveFeaturesResolver,
-  type FeatureDefinition,
-  findTierResolverUsage,
-  type TierResolverPlugin,
-  type ValidateBootOptions,
-  validateAppCustomScreenWriteQns,
-  validateBoot,
-} from "@cosmicdrift/kumiko-framework/engine";
-import {
-  type AllInOneEntrypoint,
-  type ApiEntrypoint,
-  createAllInOneEntrypoint,
-  createApiEntrypoint,
-} from "@cosmicdrift/kumiko-framework/entrypoint";
-import {
-  type ComposedEnvSchema,
-  KumikoBootError,
-  kmsSlotsOf,
-  parseEnv,
-} from "@cosmicdrift/kumiko-framework/env";
-import { type DryRunMode, renderDryRun } from "@cosmicdrift/kumiko-framework/env/dry-run";
-import {
-  createEsOperationsTable,
-  createSeedMigrationContext,
-  runPendingSeedMigrations,
-} from "@cosmicdrift/kumiko-framework/es-ops";
-import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
-import {
-  assertKumikoSchemaCurrent,
-  SchemaDriftError,
-} from "@cosmicdrift/kumiko-framework/migrations";
-import type {
-  ObservabilityOptions,
-  ObservabilityProvider,
-} from "@cosmicdrift/kumiko-framework/observability";
-import {
-  createDispatcher,
-  createEntityCache,
-  createEventDedup,
-  createIdempotencyGuard,
-} from "@cosmicdrift/kumiko-framework/pipeline";
-import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
-import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
-import type {
-  PageHeadMeta,
-  PageHeadResolver,
-  PageHeadSystemQuery,
-} from "@cosmicdrift/kumiko-headless/apex";
-import Redis from "ioredis";
-import { applyBootSeeds } from "./boot/apply-boot-seeds";
-import { resolveBootCrypto } from "./boot/boot-crypto";
-import { jobRunLoggerCallbacks } from "./boot/job-run-logger";
-import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot";
-import { buildBunServeOptions, resolveDerivedMaxRequestBodySize } from "./bun-serve-options";
-import { buildComposeAuthOptions, composeFeatures } from "./compose-features";
-import { makeDispatchSystemWrite, type SystemWireDeps } from "./extra-routes-deps";
-import { assertPiiBootInvariants } from "./pii-boot-gate";
-import {
-  addConfigAccessorFactory,
-  buildBootExtraContext,
-  buildProdSessionAuth,
-  resolveAuthMail,
-  wireProdPatAutoRevoke,
-} from "./run-prod-app-boot-context";
-import { buildStaticFallback } from "./run-prod-app-static-files";
-import { type SecurityHeadersOption, withSecurityHeaders } from "./security-headers";
-import { assertSessionBootInvariants } from "./session-boot-gate";
-import { shouldWireProdSessions } from "./session-wiring";
-import { stripNoRouteMatchHeader } from "./try-hono-first";
-
-export { buildBunServeOptions } from "./bun-serve-options";
-export {
-  addConfigAccessorFactory,
-  buildBootExtraContext,
-  resolveAuthMail,
-} from "./run-prod-app-boot-context";
-export { staticCachePolicy } from "./run-prod-app-static-files";
-
-// Strict env-var read. Throws with a clear hint when missing — better
-// than discovering a Postgres-connection-refused 30s into the boot.
-// `src` defaults to process.env but is threaded from the caller's envSource
-// so the boot-path reads the SAME env-quelle that was validated above —
-// injected dummies in test-mode must not silently fall back to process.env.
-export function requireEnv(
-  name: string,
-  src: Record<string, string | undefined> = process.env,
-  context = "runProdApp",
-): string {
-  const value = src[name];
-  if (value === undefined || value === "") {
-    const advice =
-      context === "runProdApp"
-        ? "Set it in your container env / .env.production / Coolify secrets."
-        : "Set it in your .env / shell before running the dev server.";
-    throw new Error(`${context}: required env var "${name}" is missing or empty. ${advice}`);
-  }
-  return value;
-}
-
-// Optional env helper — returns undefined for missing, string for set.
-// Used for KUMIKO_INSTANCE_ID, JWT_ISSUER and other "nice to have" knobs.
-function readEnv(
-  name: string,
-  src: Record<string, string | undefined> = process.env,
-): string | undefined {
-  const value = src[name];
-  return value === undefined || value === "" ? undefined : value;
-}
-
-// `boot` is the C1 smoke-test path — validators run, no DB/Redis connect,
-// exit after registry-build. Render-modes (human|json|pulumi|k8s|1)
-// inspect the env-schema and exit before any feature wiring.
-type RunMode = DryRunMode | "boot";
-
-function parseRunMode(raw: string | undefined): RunMode | null {
-  if (!raw) return null;
-  const v = raw.toLowerCase();
-  if (v === "1" || v === "true" || v === "human") return "human";
-  if (v === "json" || v === "pulumi" || v === "k8s" || v === "boot") return v;
-  // biome-ignore lint/suspicious/noConsole: boot-time warn for typo discovery
-  console.warn(
-    `[runProdApp] KUMIKO_DRY_RUN_ENV="${raw}" unrecognized ` +
-      `(expected 1|human|json|pulumi|k8s|boot); continuing with normal boot.`,
-  );
-  return null;
-}
-
-function isRenderMode(mode: RunMode | null): mode is DryRunMode {
-  return mode !== null && mode !== "boot";
-}
-
-function defaultBootErrorReporter(err: KumikoBootError): never {
-  // biome-ignore lint/suspicious/noConsole: boot-time error, no logger configured yet
-  console.error(err.format());
-  process.exit(1);
-}
-
-// Returned from runProdApp when KUMIKO_DRY_RUN_ENV is set AND envSource
-// was passed (= test-mode). The handle is intentionally inert — listen()
-// and stop() are no-ops; tests inspect the dry-run console output and
-// move on.
-function makeDryRunHandle(): ProdAppHandle {
-  const noop = async () => {
-    /* dry-run handle: no server was constructed */
-  };
-  return {
-    // @cast-boundary dry-run-mode: no ApiEntrypoint exists because no
-    // boot ran; the handle only surfaces test/CLI inspection and the
-    // entrypoint is never reached by callers in dry-run.
-    entrypoint: undefined as unknown as ApiEntrypoint,
-    fetch: () => new Response("dry-run", { status: 503 }),
-    webSocketUpgradeFetch: async () => new Response("dry-run", { status: 503 }),
-    listen: noop,
-    stop: noop,
-  };
-}
-
-/** Wrapper API for the password-reset flow.
- *
- *  Since the delivery migration PasswordResetOptions carries `appUrl`
- *  (+ appName/locale) itself and the handler mails via ctx.notify — no
- *  sendResetEmail callback anymore. Apps pass `auth.mail` (convenience,
- *  resolveAuthMail builds the appUrl) OR an explicit block.
- *
- *  hmacSecret is optional here (unlike PasswordResetOptions): resolveAuthMail
- *  backfills it, so overriding just appUrl needs no secret of its own. */
-export type PasswordResetSetup = Omit<PasswordResetOptions, "hmacSecret"> & {
-  readonly hmacSecret?: string;
-};
-
-/** Wrapper API for the email-verification flow, symmetric to
- *  PasswordResetSetup (appUrl via delivery, optional hmacSecret). */
-export type EmailVerificationSetup = Omit<EmailVerificationOptions, "hmacSecret"> & {
-  readonly hmacSecret?: string;
-};
-
-/** Wrapper-API für Magic-Link Self-Signup. = SignupOptions (appUrl, die
- *  Mail geht via delivery/ctx.notify wie reset/verify). Anders als reset/
- *  verify gibt's KEIN hmacSecret — Signup-Tokens sind opaque random in
- *  Redis, nicht HMAC-signed. */
-export type SignupSetup = SignupOptions;
-
-/** Wrapper-API für Tenant-Invite Magic-Link. = InviteOptions (appUrl, die
- *  Invite-Mail geht via delivery wie reset/verify/signup). Drei accept-
- *  Branches im framework; handler-names sind hardcoded in run-prod-app aus
- *  AuthHandlers (analog signup). */
-export type InviteSetup = InviteOptions;
-
-/** Wrapper API for the account-unlock flow (#1266). = AccountUnlockOptions
- *  (appUrl via delivery, symmetric to PasswordResetSetup). Self-service
- *  escape hatch for accountLockout's monotonic failure counter — only
- *  meaningful when `auth.accountLockout` is also set, but wired
- *  independently like the other flows. */
-export type AccountUnlockSetup = AccountUnlockOptions;
-
-/** Wrapper API for the account-lockout brute-force guard on the login
- *  handler. = AccountLockoutOptions (maxFailedAttempts, lockoutDurationMinutes
- *  — no mail/appUrl fields, it doesn't mount any routes). Symmetric to
- *  RunDevAppAuthOptions.accountLockout (kumiko-framework#1627) — before this,
- *  `accountUnlock` existed on both wrappers with no way to ever set the
- *  lockout it's meant to escape. */
-export type AccountLockoutSetup = AccountLockoutOptions;
-
-/** Auth-Mail-Convenience-Optionen — shared zwischen runProdApp + runDevApp.
- *  Verdrahtet alle 4 Mail-Flows aus einem env-SMTP-Transport + Standard-
- *  Templates (siehe `auth.mail` + resolveAuthMail). */
-export type AuthMailOptions = {
-  /** App-Basis-URL inkl. Schema (z.B. "https://app.example.com"). */
-  readonly baseUrl: string;
-  /** App-Name für Mail-Subject + Body. Default "Account". */
-  readonly appName?: string;
-  /** Locale für die Mail-Templates. Default "de". */
-  readonly locale?: AuthMailLocale;
-  /** "strict" blockt Login bis emailVerified; "off" mountet ohne Gate. */
-  readonly emailVerificationMode?: "strict" | "off";
-  /** Fallback-From-Adresse wenn `SMTP_FROM`-env fehlt (env gewinnt). */
-  readonly from?: string;
-  /** Einzelne Auth-Pfade überschreiben (Default DEFAULT_AUTH_PATHS). */
-  readonly paths?: Partial<AuthPaths>;
-  /** Reset/verify token secret, decoupled from JWT_SECRET rotation.
-   *  Falls back to resolveAuthMail's call-site secret when unset. */
-  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;
-  /** Optional override of the login error → HTTP status map. */
-  readonly loginErrorStatusMap?: Readonly<Record<string, number>>;
-  /** Auth-Mail-Convenience: verdrahtet alle 4 Mail-Flows (passwordReset,
-   *  emailVerification, signup, invite) aus `auth.mail.baseUrl` + Standard-
-   *  Pfaden. Alle vier mailen via delivery (ctx.notify) — ersetzt das per-App
-   *  hand-gerollte `send*Email`-Callback-Wiring.
-   *
-   *  Null-Transport-Guard: ohne `SMTP_HOST`-env wird KEIN Mail-Flow
-   *  verdrahtet (Routes blieben sonst 500). Eine App die einen einzelnen
-   *  Flow custom braucht, setzt `passwordReset`/`signup`/… explizit —
-   *  der explizite Block gewinnt über den mail-Default.
-   *
-   *  Bewusste Entscheidung: `mail` mountet ALLE 4 Flows inkl. signup +
-   *  invite (Self-Registration on). Wer nur reset+verify will, lässt `mail`
-   *  weg und setzt die gewünschten Flows explizit — kein impliziter
-   *  Self-Signup. */
-  readonly mail?: AuthMailOptions;
-  /** Password-reset flow. When set, /api/auth/request-password-reset +
-   *  /api/auth/reset-password are mounted as public routes UND der
-   *  request/confirm-Handler im auth-email-password-Feature wird
-   *  registriert (sonst dispatchen die Routes ins Leere → 500).
-   *  Überschreibt den `mail`-Default für genau diesen Flow. */
-  readonly passwordReset?: PasswordResetSetup;
-  /** Email-verification flow. Symmetric to passwordReset. */
-  readonly emailVerification?: EmailVerificationSetup;
-  /** Self-Signup flow (Magic-Link). When set, /api/auth/signup-request +
-   *  /api/auth/signup-confirm are mounted; signup-confirm mintet JWT +
-   *  Cookies wie ein erfolgreicher login (Auto-Login direkt nach
-   *  Activation). */
-  readonly signup?: SignupSetup;
-  /** Tenant-Invite flow (Magic-Link). When set, /api/auth/invite-accept,
-   *  /api/auth/invite-accept-with-login, /api/auth/invite-signup-complete
-   *  are mounted. */
-  readonly invite?: InviteSetup;
-  /** Account-unlock flow (#1266). When set, /api/auth/request-account-unlock
-   *  + /api/auth/confirm-account-unlock are mounted. Self-service escape
-   *  hatch for accountLockout's monotonic failure-counter — confirming
-   *  clears the Redis lockout state, no entity write. */
-  readonly accountUnlock?: AccountUnlockSetup;
-  /** Brute-force guard on the login handler (maxFailedAttempts,
-   *  lockoutDurationMinutes). Mounts no routes — unlike the other flows,
-   *  it's a login-handler config knob, not a magic-link flow. Pair with
-   *  `accountUnlock` for a self-service escape hatch. */
-  readonly accountLockout?: AccountLockoutSetup;
-  /** Domain attribute for both auth cookies (see
-   *  AuthRoutesConfig.cookieDomain). Set to the registrable parent
-   *  domain when login and app live on different subdomains. */
-  readonly cookieDomain?: string;
-  /** Server-side Origin allowlist for the CSRF guard (see
-   *  AuthRoutesConfig.allowedOrigins). REQUIRED once `cookieDomain` is set —
-   *  buildServer fails closed otherwise. Apex + admin host, never tenant
-   *  subdomains. */
-  readonly allowedOrigins?: readonly string[];
-  /** Opt out of the Origin guard (see AuthRoutesConfig.unsafeSkipOriginCheck)
-   *  — accept the wide-cookie CSRF risk explicitly instead of setting
-   *  `allowedOrigins`. */
-  readonly unsafeSkipOriginCheck?: boolean;
-  /** Number of trusted reverse-proxy hops between the client and this
-   *  process for client-IP derivation (see AuthRoutesConfig.trustedProxyHops,
-   *  kumiko-framework#1539) — closes the X-Forwarded-For spoofing hole on
-   *  the auth rate-limiters. Falls back to the `KUMIKO_TRUSTED_PROXY_HOPS`
-   *  env var when unset; both unset means 0 hops, the safe socket-only
-   *  default (only the socket address counts, XFF ignored). Deprecated in
-   *  favor of the top-level `trustedProxyHops` option, which wins over
-   *  this and the env var. */
-  readonly trustedProxyHops?: number;
-  /** Server-computed post-auth redirect (see AuthRoutesConfig.postAuthLanding).
-   *  Result lands in the login/signup/invite response as `landingPath`; an
-   *  invalid path or a throwing resolver just omits the field. */
-  readonly postAuthLanding?: PostAuthLandingResolver;
-};
-
-/** Hook for app-specific seeding — runs after the admin (when auth is
- *  active). Each seed is responsible for its own idempotence (seeds are
- *  expected to check "is my row already there?" before inserting). */
-export type ProdSeedFn = (deps: {
-  db: import("@cosmicdrift/kumiko-framework/db").DbConnection;
-}) => Promise<void>;
-
-/** Boot-Time-Deps die `extraContext` + `anonymousAccess` Factories als
- *  Argument bekommen. Closure dann in der returned Config (z.B. ein
- *  TenantResolver der gegen `db` queriet, oder ein extraContext-Provider
- *  der direkt SSE-Events publishen will). Single-source: identisch zu
- *  setupTestStack's extraContext-Factory-Shape damit Test/Prod gleich
- *  aussehen. */
-export type RunProdAppDeps = {
-  readonly db: import("@cosmicdrift/kumiko-framework/db").DbConnection;
-  readonly redis: import("ioredis").default;
-  readonly registry: import("@cosmicdrift/kumiko-framework/engine").Registry;
-  readonly sseBroker: SseBroker;
-};
-
-export type AnonymousAccessOption =
-  | import("@cosmicdrift/kumiko-framework/api").AnonymousAccessConfig
-  | ((deps: RunProdAppDeps) => import("@cosmicdrift/kumiko-framework/api").AnonymousAccessConfig);
-
-export type ExtraContextOption =
-  | Record<string, unknown>
-  | ((deps: RunProdAppDeps) => Record<string, unknown>);
-
-/** Per-host routing decision for the staticDir fallback, returned from
- *  hostDispatch. Three modes:
- *    - "html": serve a specific HTML file (relative to staticDir), optionally
- *      with CSP. HTML never carries a schema — createKumikoApp fetches it
- *      itself from the authenticated GET /api/schema, after the
- *      clientFeature gates (auth) let it through.
- *    - "redirect": 301/302 to the given location.
- *    - "not-found": reject outright (e.g. unknown subdomain).
- *
- *  Only consulted when the path would otherwise fall through to the HTML
- *  fallback — i.e. for "/", "/index.html", or SPA routes that neither Hono
- *  matches nor a concrete disk file. Asset paths (/assets/*) and API paths
- *  run independent of the host. */
-export type HostDispatchResult =
-  | {
-      readonly kind: "html";
-      readonly file: string;
-      /** @deprecated Ignored — HTML never carries the schema; createKumikoApp
-       *  fetches it from the authenticated GET /api/schema. */
-      readonly injectSchema?: boolean;
-      readonly csp?: string;
-    }
-  | { readonly kind: "redirect"; readonly to: string; readonly status?: 301 | 302 }
-  | { readonly kind: "not-found" };
-
-export type HostDispatchFn = (
-  req: {
-    readonly host: string;
-    readonly path: string;
-    /** Query string incl. leading `?`, `""` if none. Redirects that
-     *  route the path to a different host (e.g. auth routes with
-     *  `?token=` from old mail links) MUST append it to `to`. */
-    readonly search: string;
-  },
-  /** `systemQuery` runs as the anonymous role (like PageHeadSystemQuery) —
-   *  hostDispatch is reachable by any public visitor, same access gate as a
-   *  real anonymous request. Lets a Multi-Tenant hostDispatch look up the
-   *  tenant for a subdomain instead of needing its own db handle. */
-  deps: { readonly systemQuery: PageHeadSystemQuery },
-) => HostDispatchResult | Promise<HostDispatchResult>;
-
-// PageHeadMeta/PageHeadResolver/PageHeadSystemQuery moved to
-// @cosmicdrift/kumiko-headless/apex (kumiko-framework#3026) — runDevApp needs
-// the same types and the same resolve+inject function runProdApp uses, and
-// headless is where renderApexHeadTags already lives. Re-exported here so
-// existing subpath-imports (`@cosmicdrift/kumiko-server-runtime/run-prod-app`)
-// keep working unchanged.
-export type { PageHeadMeta, PageHeadResolver, PageHeadSystemQuery };
-
-export type RunProdAppOptions = {
-  /** App-specific features. config/user/tenant/auth-email-password are
-   *  auto-mixed when `auth:` is set — don't add them yourself. */
-  readonly features: readonly FeatureDefinition[];
-  /** Opt-in boot-validator warnings — see ValidateBootOptions. */
-  readonly validateBootOptions?: ValidateBootOptions;
-  /** Listen-Port. Default 3000 (or $PORT). */
-  readonly port?: number;
-  /** Ceiling Bun.serve buffers a request body to before any app-level
-   *  body-limit middleware runs. Default is derived from `createFilesFeature`'s
-   *  configured `maxUploadSize`/field `maxSize` (see
-   *  resolveDerivedMaxRequestBodySize in bun-serve-options.ts) — override
-   *  only for a custom ceiling unrelated to that config. */
-  readonly maxRequestBodySize?: number;
-  /** Auth-mode: standard features + routes wired, admin seeded. */
-  readonly auth?: RunProdAppAuthOptions;
-  /** Custom seed functions, run after the admin seed (when auth-mode). */
-  readonly seeds?: readonly ProdSeedFn[];
-  /** Pfad zum seeds-Directory für ES-Operations / Seed-Migrations
-   *  (file-basiert wie drizzle-migrate). Wenn gesetzt + KUMIKO_SKIP_ES_OPS
-   *  != "1": runProdApp scannt das Verzeichnis nach `<id>.ts` Files,
-   *  diff vs kumiko_es_operations-Table, läuft pending in Tx.
-   *  Plan: kumiko-platform/docs/plans/features/es-ops.md */
-  readonly seedsDir?: string;
-  /** Anonymous-access for public endpoints (same shape as runDevApp).
-   *  Akzeptiert entweder einen statischen Config-Object ODER eine
-   *  Factory `({db, redis, registry}) => Config` — die Factory wird
-   *  einmal zur Boot-Zeit aufgerufen, NACHDEM db/redis/registry konstruiert
-   *  sind. Der Caller closure'd typischerweise db/redis/registry in den
-   *  TenantResolver damit z.B. ein Subdomain → Tenant-Lookup gegen die
-   *  DB möglich ist (siehe samples/showcases/publicstatus für das
-   *  Multi-Tenant-Pattern). */
-  readonly anonymousAccess?: AnonymousAccessOption;
-  /** Static-file root for HTML / assets. Served on the catch-all route
-   *  for any path that doesn't match an /api/ handler. Use this for the
-   *  public status page HTML, embed widget JS, etc. */
-  readonly staticDir?: string;
-  /** Host-aware routing hook for multi-tenant + multi-app deployments
-   *  (e.g. publicstatus's `<sub>.publicstatus.eu` (public page) +
-   *  `admin.publicstatus.eu` (admin UI) + `publicstatus.eu` (apex/
-   *  marketing) in the SAME container).
-   *
-   *  Called when the staticDir fallback would generate an HTML response
-   *  (root or SPA route). Default behavior without hostDispatch: index.html
-   *  (single-app), no schema.
-   *
-   *  Schema safety: HTML (per-host as well as single-app) never carries an
-   *  AppSchema — createKumikoApp fetches it via GET /api/schema, which sits
-   *  behind the auth middleware and only serves non-anonymous, signed-in
-   *  users. Per-host CSP headers can additionally restrict asset paths. */
-  readonly hostDispatch?: HostDispatchFn;
-  /** Per-request head-metadata resolver (Open-Graph/title/description) for
-   *  the static-fallback HTML shell — see `PageHeadResolver`. Consulted on
-   *  the same two HTML-serving paths as `hostDispatch` (host-dispatched
-   *  HTML + the default single-app index.html), right before the response
-   *  is sent. On error, `null`, or a resolve time over 300ms, the shell
-   *  ships unchanged with status 200 — this must never turn into a 500 or
-   *  a blank page. `systemQuery` inside the resolver runs as the
-   *  anonymous role (not system) — the resolver is reachable by any
-   *  public visitor, same access gate as a real anonymous request. */
-  readonly resolvePageHead?: PageHeadResolver;
-  /** Pfad zu kumiko/migrations für den Boot-Gate. Default "./kumiko/
-   *  migrations" relativ zum process-cwd (wo die App gestartet wird —
-   *  bei Container-Deploys typischerweise der App-Workspace-Root, weil
-   *  WORKDIR im Dockerfile dorthin zeigt). Boot wirft SchemaDriftError
-   *  wenn Migrations pending sind oder erwartete Tabellen fehlen.
-   *  Setze auf `false` um den Gate komplett zu deaktivieren — nur für
-   *  Setups die ihren eigenen Schema-Check fahren (z.B. bring-your-own-
-   *  ORM). Standard-Apps lassen das default. */
-  readonly migrations?: { readonly dir: string } | false;
-  /** Extra AppContext keys. Framework-Defaults werden zur Boot-Zeit
-   *  unter den Factory-Werten ergänzt, App-Werte gewinnen immer:
-   *    - `templateResolver` (createTemplateResolverApi(db)) — immer
-   *    - `secrets` (createSecretsContext) — nur wenn das `secrets`-Feature
-   *      gemountet ist (sonst kein KEK-env-Zwang für Apps ohne secrets)
-   *    - `configResolver` — im Auth-Mode (env-config-overrides)
-   *  Akzeptiert einen statischen Object ODER eine Factory
-   *  `({db, redis, registry}) => Record<string, unknown>` — gleiches
-   *  Pattern wie `anonymousAccess`. Eine App die einen dieser Keys selbst
-   *  setzt (z.B. eigener configResolver) überschreibt den Default. */
-  /** Boot default locale (BCP-47) for ctx.locale when the request carries
-   *  no locale signal. Merged into AppContext before extraContext (app wins). */
-  readonly defaultLocale?: string;
-  readonly extraContext?: ExtraContextOption;
-  /** MasterKeyProvider für die auto-verdrahtete `ctx.secrets`. Default:
-   *  `createEnvMasterKeyProvider` (KEK aus `KUMIKO_SECRETS_MASTER_KEY_V<n>`).
-   *  Override für KMS-Backends (AWS/GCP/Azure) statt env-KEK. Nur relevant
-   *  wenn das `secrets`-Feature gemountet ist. */
-  readonly masterKey?: MasterKeyProvider;
-  /** Subject-Key-Adapter für Crypto-Shredding (DSGVO Art. 17). Wenn gesetzt,
-   *  steht er Feature-Code als `ctx.kms` zur Verfügung und der Boot prüft
-   *  seine health() — die App startet nicht gegen ein unerreichbares KMS
-   *  (Silent-Start würde jeden PII-Read mit 503 beantworten). Kein Default:
-   *  ohne Adapter bleibt Crypto-Shredding aus. */
-  readonly kms?: KmsAdapter;
-  /** 32-Byte-Key (base64) für Blind-Index-HMACs auf `lookupable`-Feldern
-   *  (env: KUMIKO_BLIND_INDEX_KEY, `openssl rand -base64 32`). Bewusst
-   *  getrennt vom PLATFORM_KEK und nicht Teil des KmsAdapter-Contracts.
-   *  Pflicht sobald `kms` gesetzt ist UND ein Feature lookupable-Felder
-   *  deklariert — sonst bricht jeder Equality-Lookup auf Ciphertext
-   *  (Login by email!) und der Boot failt hart. */
-  readonly blindIndexKey?: string;
-  /** Explizites Opt-out aus dem harten PII-Boot-Gate: Features deklarieren
-   *  pii/userOwned/tenantOwned-Felder, aber es ist (noch) kein `kms`
-   *  provisioniert — die Felder liegen dann als KLARTEXT in Rows und
-   *  Events und DSGVO-Erasure via Crypto-Shredding ist unmöglich. Der Wert
-   *  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.
-   *
-   *  `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). */
-  readonly runSingleInstance?: boolean;
-  /** Job-Block. Wenn das Feature `r.job(...)` registriert, wird er
-   *  automatisch verdrahtet (siehe runSingleInstance). */
-  readonly jobs?: {
-    /** BullMQ-Queue-Prefix (default "kumiko"). */
-    readonly queueNamePrefix?: string;
-    /** Source of active tenant ids for `perTenant: true` jobs. Omit when the
-     *  tenant feature is mounted — the framework then resolves tenants on
-     *  its own via that feature's active-tenant-ids query. Only needed when
-     *  the app manages tenants outside that feature. */
-    readonly getActiveTenantIds?: JobRunnerOptions["getActiveTenantIds"];
-  };
-  /** Event-Dispatcher (MSP-Anwendung) im API-Process. Default AN —
-   *  runProdApp ist das Single-Container-Deployment, es gibt keinen
-   *  Worker-Process der multiStreamProjections anwenden könnte. Bis
-   *  2026-06-11 fehlte der Dispatcher hier komplett: jede MSP-basierte
-   *  Read-Projektion (z.B. custom-fields jsonb) blieb in Prod leer,
-   *  kumiko_event_consumers blieb ohne Rows. `disabled: true` nur für
-   *  Setups mit dezidiertem Worker-Process. */
-  readonly eventDispatcher?: {
-    readonly disabled?: boolean;
-    /** Poll-Intervall des Dispatcher-Loops (default siehe
-     *  createEventDispatcher). LISTEN/NOTIFY-Wiring kommt mit einem
-     *  späteren pgClient-Pass-through. */
-    readonly pollIntervalMs?: number;
-  };
-  /** Declarative HTTP-routes outside the /api/write|query|batch pipeline —
-   *  each entry declares its access tier (`entry`: "anonymous" | "user" |
-   *  "signature"), buildServer wires the matching guard + deps. Mounted
-   *  inside buildServer, right after the r.httpRoute loop, before seeds
-   *  (kumiko-framework#3050). */
-  readonly extraRoutes?: readonly ExtraRouteDefinition[];
-  /** Hook for app-wired co-running components that need the system-write
-   *  dispatcher (e.g. wiring a webhook plugin's system-scoped secrets, or
-   *  starting a co-running supervisor) — runs after buildServer, before
-   *  seeds, with NO `app` (routes are declared via `extraRoutes`, not
-   *  wired here). */
-  readonly wire?: (deps: SystemWireDeps) => void | Promise<void>;
-  /** When true (default), Bun.serve is started before runProdApp resolves —
-   *  the common case: `await runProdApp({...})` boots the server and the
-   *  process stays up listening on PORT. Set to false in tests that drive
-   *  the fetch-handler directly (Bun.serve isn't available under vitest +
-   *  node), then call handle.listen() manually if needed. */
-  readonly autoListen?: boolean;
-  /** Feature-toggle resolver — durchgereicht an createApiEntrypoint's
-   *  dispatcherOptions. Sprint-8 Tier-Composition: per-Tenant unterschied-
-   *  liche features aktiv via globalFeatureToggleRuntime. Pattern:
-   *  createLateBoundHolder + post-boot runtime.initialize in einem
-   *  seed-fn (db ist erst nach migrations + features ready). */
-  readonly effectiveFeatures?: EffectiveFeaturesResolver;
-  /** Composed Zod-schema for env-validation (from `composeEnvSchema({
-   *  features, extend })` in @cosmicdrift/kumiko-framework/env). When set:
-   *  - `process.env` is parsed against it BEFORE any boot work; missing
-   *    or invalid vars throw a `KumikoBootError` listing ALL problems
-   *    at once (not first-fail).
-   *  - `KUMIKO_DRY_RUN_ENV=human|json|pulumi|k8s` introspects the schema
-   *    and prints the env-var inventory, then exits without booting.
-   *
-   *  9.1 is additive: features that still read `process.env` directly
-   *  keep working. Migration to the schema is Sprint-9.2-9.5. */
-  readonly envSchema?: ComposedEnvSchema;
-  /** Prefix for `pulumi config set <prefix><CamelCase(VAR)>` in dry-run
-   *  output and boot-error suggestions. Without this, suggestions use
-   *  bare `camelCase(VAR)` and ops has to guess the app prefix. */
-  readonly pulumiPrefix?: string;
-  /** Handler for KumikoBootError. Default: print formatted error to
-   *  stderr and `process.exit(1)` so the container restarts with a
-   *  visible log line. Override in tests that drive runProdApp directly
-   *  (avoid the exit). Return type is `void` rather than `never` to keep
-   *  test-overrides honest — if a reporter returns, runProdApp falls
-   *  through to a regular `throw err` as the safety net. */
-  readonly bootErrorReporter?: (err: KumikoBootError) => void;
-  /** Override `process.env` for env-validation. Default: `process.env`.
-   *  Tests use this to feed crafted env-maps without polluting the
-   *  global. */
-  readonly envSource?: Record<string, string | undefined>;
-  /** Observability-Provider (Tracer + Meter). Default: Noop (kein Overhead,
-   *  kein `/metrics`-Endpoint). Setze `createPrometheusMeter()`-basierten
-   *  Provider + `metrics` um `/metrics` real zu exposen (publicstatus#91). */
-  readonly observability?: ObservabilityProvider;
-  /** Konfiguriert die Auto-Instrumentation des resolvierten Observability-
-   *  Providers (siehe `BaseEntrypointOptions.observabilityOptions`). */
-  readonly observabilityOptions?: ObservabilityOptions;
-  /** Aktiviert den `/metrics`-Endpoint (Open-Metrics-Format). Ohne einen
-   *  PrometheusMeter-basierten `observability`-Provider antwortet `/metrics`
-   *  mit 503 + Misconfiguration-Hinweis statt echter Metriken. */
-  readonly metrics?: import("@cosmicdrift/kumiko-framework/api").ServerOptions["metrics"];
-  /** L1 (Login-Lockout) + L2 (globaler IP-Limit) Rate-Limit-Middleware —
-   *  1:1 durchgereicht an `buildServer`s `ServerOptions.rateLimit`. Ohne
-   *  dieses Feld wird kein L1/L2 verdrahtet (L3 Handler-`rateLimit:`
-   *  funktioniert unabhängig davon bereits). */
-  readonly rateLimit?: import("@cosmicdrift/kumiko-framework/api").ServerOptions["rateLimit"];
-  /** Default security headers on every response (HSTS, X-Frame-Options,
-   *  X-Content-Type-Options, Referrer-Policy; CSP opt-in). Headers already
-   *  set by a response (e.g. hostDispatch's per-host CSP) are never
-   *  overridden. `false` disables the whole block; per-header overrides
-   *  via the object form — see SecurityHeadersOption. */
-  readonly securityHeaders?: SecurityHeadersOption;
-  /** Number of trusted reverse-proxy hops for client-IP resolution — 1:1
-   *  durchgereicht an `buildServer`s
-   *  top-level `ServerOptions.trustedProxyHops`. Wins over the deprecated
-   *  `auth.trustedProxyHops` and `KUMIKO_TRUSTED_PROXY_HOPS`. Default 0 =
-   *  trust no proxy header, only the socket address (or "unknown") counts. */
-  readonly trustedProxyHops?: number;
-};
-
-export type ProdAppHandle = {
-  /** The composed entrypoint — AllInOne (runSingleInstance, default) or
-   *  Api-only (runSingleInstance:false). In KUMIKO_DRY_RUN_ENV mode WITH
-   *  `envSource` injected (test path), no boot ran and this slot is an
-   *  undefined-cast — do not access. Production dry-run hits
-   *  `process.exit(0)` before returning a handle. */
-  readonly entrypoint: ApiEntrypoint | AllInOneEntrypoint;
-  /** The fetch-handler — wired into Bun.serve in production, called
-   *  directly in tests. Composes Hono + static-fallback. Apps with
-   *  `autoListen: false` that call `Bun.serve` themselves must pass the
-   *  2nd arg from `server.requestIP(req)?.address`, extracted in their
-   *  outermost Bun fetch callback — `requestIP` only resolves for Bun's
-   *  original Request instance, never a cloned/rebuilt one. */
-  readonly fetch: (req: Request, socketAddress?: string) => Promise<Response> | Response;
-  /** Serves WebSocket-upgrade requests (r.webSocketRoute) with Bun's original
-   *  Request. Apps with `autoListen: false` that run their own `Bun.serve`
-   *  must pass it as `{ upgradeFetch }` in the 4th argument of `buildBunServeOptions` to get
-   *  WebSockets; `listen()` already wires it. */
-  readonly webSocketUpgradeFetch: (req: Request, env: KumikoServeEnv) => Promise<Response>;
-  /** Active Bun-server (only set when listen() was called — tests skip
-   *  listen() because Bun.serve isn't available under vitest/node). */
-  server?: ReturnType<typeof Bun.serve>;
-  /** Bind to PORT and start serving. Production calls this; tests don't. */
-  readonly listen: (port?: number) => Promise<void>;
-  readonly stop: () => Promise<void>;
-};
-
-let warnedLegacyJwtSecret = false;
-function warnLegacyJwtSecretOnce(): void {
-  // 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 — " +
-      "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 " +
-      "that is no longer present in any in-flight token (see resolveAuthMail / " +
-      "loadJwtSecretOrKeyring).",
-  );
-}
-
-export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHandle> {
-  // 0. Env-Schema validation + dry-run modes. Runs FIRST so:
-  //    - operators can introspect env-requirements without a real boot
-  //      (no DB connection needed, KUMIKO_DRY_RUN_ENV=… → render + exit)
-  //    - missing/invalid env-vars produce a structured KumikoBootError
-  //      with ALL problems aggregated (not first-fail), before we waste
-  //      seconds on a Postgres connection that was never configured.
-  //
-  //    Both code paths are no-ops when no envSchema is passed — Sprint-9
-  //    migration is per-feature additive; pre-migration apps keep the
-  //    legacy `requireEnv("DATABASE_URL")` checks below.
-  //
-  //    Ordering invariant: this step runs BEFORE the Temporal polyfill,
-  //    so env-schemas MUST use only Temporal-free Zod types. Don't author
-  //    `z.iso.date()`/`Temporal.Instant` fields on env-vars — they'd crash
-  //    at parse-time before the polyfill loads. Plain strings + .regex /
-  //    .min / .email / .url cover every env-var shape we've actually
-  //    needed in 9.1's audit (37 references, 25 distinct vars).
-  const rawEnvSource = options.envSource ?? process.env;
-  const runMode = parseRunMode(rawEnvSource["KUMIKO_DRY_RUN_ENV"]);
-  if (options.envSchema) {
-    if (isRenderMode(runMode)) {
-      // biome-ignore lint/suspicious/noConsole: dry-run output IS the deliverable
-      console.log(
-        renderDryRun(options.envSchema, runMode, {
-          ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
-          sources: options.envSchema.sources,
-        }),
-      );
-      // Tests inject envSource and want a return-value, not exit. Detecting
-      // "this is a test" via envSource is brittle; instead exit when running
-      // against the real process.env (the deploy-flow), return otherwise.
-      if (options.envSource === undefined) {
-        process.exit(0);
-      }
-      return makeDryRunHandle();
-    }
-    // boot-mode AND normal-boot both run env-validation. boot-mode wants
-    // a real env-check (all required vars present + schema-valid) before
-    // it asserts feature-wiring works.
-    try {
-      parseEnv(options.envSchema.schema, rawEnvSource, {
-        sources: options.envSchema.sources,
-        ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
-      });
-    } catch (err) {
-      if (err instanceof KumikoBootError) {
-        const reporter = options.bootErrorReporter ?? defaultBootErrorReporter;
-        reporter(err);
-      }
-      throw err;
-    }
-  }
-
-  // Slots the schema marks `kms` are decrypted once here so every consumer
-  // below (boot probe, master-key keyring, config) sees the same resolved env.
-  const envSource: Record<string, string | undefined> = options.envSchema
-    ? await resolvePlatformKeks(rawEnvSource, {
-        slots: kmsSlotsOf(options.envSchema.schema),
-        logPrefix: "[runProdApp]",
-      })
-    : rawEnvSource;
-
-  // 1. Polyfill before anything else — feature code references Temporal.
-  const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
-  await ensureTemporalPolyfill();
-
-  // 2. Env-vars: fail-fast. Better a 0s boot crash with a clear error
-  //    than a 30s timeout chasing a Postgres connection that was never
-  //    configured.
-  const databaseUrl = requireEnv("DATABASE_URL", envSource);
-  const redisUrl = requireEnv("REDIS_URL", envSource);
-  // JWT_SECRET stays mandatory (also the resolveAuthMail hmacSecret
-  // fallback below — a separate, non-rotating HMAC token family, not the
-  // session JWT). jwtSecretOrKeyring is the OPTIONAL upgrade: set
-  // JWT_SECRET_V<n> + JWT_SECRET_CURRENT_VERSION for zero-downtime
-  // rotation of the session-JWT signing key — see loadJwtSecretOrKeyring.
-  const jwtSecret = requireEnv("JWT_SECRET", envSource);
-  const jwtSecretOrKeyring = loadJwtSecretOrKeyring(envSource);
-  if (typeof jwtSecretOrKeyring === "object" && Object.hasOwn(jwtSecretOrKeyring.keys, "legacy")) {
-    // Once per process — JWT_SECRET stays a required env (requireEnv above +
-    // resolveAuthMail hmacSecret fallback). Retiring the *legacy verify key*
-    // means setting auth.mail.hmacSecret explicitly and rotating JWT_SECRET
-    // to a fresh value that is no longer in any in-flight token; unsetting
-    // JWT_SECRET entirely hard-crashes boot.
-    warnLegacyJwtSecretOnce();
-  }
-  const jwtIssuer = readEnv("JWT_ISSUER", envSource);
-  const instanceId = readEnv("KUMIKO_INSTANCE_ID", envSource);
-  // 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 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}…`);
-
-  // 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.
-  const effectiveAuth = options.auth
-    ? resolveAuthMail(options.auth, jwtSecret, envSource)
-    : undefined;
-
-  // 3. Feature registry. Auth-mode auto-mixes config/user/tenant/auth-email-
-  //    password via composeFeatures — same source-of-truth as runDevApp
-  //    AND the per-app drizzle-Schema-Generator, so Migration und Runtime
-  //    sehen exakt dieselbe Liste. Built BEFORE any connection so boot-mode
-  //    can validate wiring and exit without opening a Postgres/Redis socket.
-  const composeAuthOptions = buildComposeAuthOptions(effectiveAuth);
-  const features = composeFeatures(options.features, {
-    includeBundled: !!effectiveAuth,
-    ...(composeAuthOptions && { authOptions: composeAuthOptions }),
-  });
-
-  validateBoot(features, { env: envSource, ...options.validateBootOptions });
-  warnIfNonUtcServerTimeZone();
-  validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
-  assertPiiBootInvariants(features, {
-    kms: options.kms,
-    blindIndexKey: options.blindIndexKey,
-    allowPlaintextPii: options.allowPlaintextPii,
-    mode: "prod",
-  });
-  const sessionsFeature = features.find((f) => f.name === SESSIONS_FEATURE);
-  const registry = createRegistry(features);
-  assertSessionBootInvariants({
-    hasAuth: Boolean(effectiveAuth),
-    sessionStoreProviderMounted: registry.getExtensionUsages(EXT_SESSION_STORE).length > 0,
-    mode: "prod",
-  });
-
-  // C1 boot-mode exit: validators ran + registry built; no DB/Redis client
-  // is constructed at all in this branch (the eager `new Redis(...)` below
-  // would otherwise open a TCP connect just to immediately disconnect it).
-  if (runMode === "boot") {
-    // 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)`,
-    );
-    if (options.envSource === undefined) {
-      process.exit(0);
-    }
-    return makeDryRunHandle();
-  }
-
-  // 4. Connections — Postgres + Redis. The Redis client is shared by
-  //    idempotency, event-dedup, entity-cache, rate-limit; failing to
-  //    construct here surfaces the misconfig immediately. `new Redis(...)`
-  //    connects eagerly, so it must stay AFTER the boot-mode exit above.
-  // KMS health gate: an app configured for crypto-shredding must not boot
-  // against an unreachable key store — a silent start would answer every
-  // PII read with 503. Runs BEFORE connections so an abort leaks nothing.
-  if (options.kms) {
-    const kmsHealth = await options.kms.health();
-    if (!kmsHealth.ok) {
-      throw new Error(
-        `[runProdApp] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`,
-      );
-    }
-  }
-
-  const { db, close: closeDb } = createDbConnection(databaseUrl);
-  const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
-
-  // Sprint-8a Tier-Composition auto-wire: scan features for a
-  // tenantTierResolver-extension. If found AND user didn't supply own
-  // effectiveFeatures, build the resolver here (db + registry are
-  // available) before the dispatcher is constructed. App-Author sees
-  // nothing — `createTierEngineFeature(opts)` mounts + framework auto-wires.
-  let resolvedEffectiveFeatures: EffectiveFeaturesResolver | undefined = options.effectiveFeatures;
-  if (resolvedEffectiveFeatures === undefined) {
-    const tierResolverUsage = findTierResolverUsage(features);
-    if (tierResolverUsage) {
-      const plugin = tierResolverUsage.options as TierResolverPlugin;
-      resolvedEffectiveFeatures = await plugin.build({ db, registry });
-    }
-  }
-
-  // 5. Schema-Drift-Gate (drizzle-frei, kumiko/migrations). `kumiko schema
-  //    apply` läuft als Deploy-Step VOR dem Container-Rollout. Boot prüft nur:
-  //      (a) Alle Migrations aus kumiko/migrations/*.sql sind in
-  //          _kumiko_migrations applied (+ checksum unverändert)
-  //      (b) Alle Tabellen aus kumiko/migrations/.snapshot.json existieren
-  //    Drift = Boot-Error mit klarer Meldung (kein Auto-Heal — mehrere
-  //    Container-Replicas würden sonst race-conditionen fahren). Opt-out via
-  //    `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})…`);
-    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`);
-      }
-      throw err;
-    }
-  }
-
-  // 6. 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 });
-
-  // 7. Lifecycle is built by createApiEntrypoint when not supplied —
-  //    we let the entrypoint own it and read it back through the handle
-  //    for SIGTERM.
-  //
-  // extraContext + anonymousAccess sind factory-union: entweder direktes
-  // Object oder Function die {db, redis, registry} bekommt und das Object
-  // returned. Factory-Form gilt als bevorzugt für Cases die zur Boot-Zeit
-  // gegen die DB resolven müssen (z.B. Subdomain-Tenant-Lookup im
-  // tenantResolver) — die Factory closure'd `db` und der Resolver kann
-  // sie zur Request-Zeit aufrufen.
-  // Build the sseBroker here (instead of letting createApiEntrypoint do it
-  // internally) so extraContext factories can close over it at boot time —
-  // e.g. an extraContext provider that publishes SSE events directly. We
-  // pass the same broker into createApiEntrypoint (sseBroker? option) so
-  // the server-internal broadcast and app-specific publishes run over
-  // exactly one broker. createDefaultSseBroker (not createSseBroker
-  // directly) is what makes that broker Redis-backed under REDIS_URL —
-  // an unconditional in-memory broker here would silently win over
-  // buildServer's own REDIS_URL default (ServerOptions.sseBroker always
-  // wins), which is exactly how fw#2630's cross-replica fanout fix shipped
-  // without ever taking effect in production.
-  const { sseBroker, ownedRedisSseBroker } = createDefaultSseBroker(envSource);
-  const deps: RunProdAppDeps = { db, redis, registry, sseBroker };
-  const resolvedExtraContext =
-    typeof options.extraContext === "function"
-      ? options.extraContext(deps)
-      : (options.extraContext ?? {});
-
-  // Framework-Default-Provider zuerst, App-Werte (resolvedExtraContext)
-  // gewinnen immer (z.B. money-horse's eigener configResolver).
-  const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
-  // App-wide cipher for `encrypted: true` entity fields — executors resolve
-  // it lazily, entities without encrypted fields never touch it.
-  configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
-  // Subject-key KMS for pii-annotated fields (crypto-shredding, #724).
-  // No adapter = engine off, plaintext as before — the warning keeps the gap
-  // visible until the prod-grade PgKmsAdapter (phase E) makes a hard boot
-  // gate viable (InMemory in prod would lose every DEK on restart).
-  configurePiiSubjectKms(options.kms);
-  // Blind-Index-Key (#818) — Boot-Gate: mit aktivem KMS würden lookupable-
-  // Felder als Ciphertext gespeichert, ohne Key gäbe es keinen bidx-Arm und
-  // jeder Equality-Lookup (Login by email!) liefe ins Leere. Fail-fast statt
-  // silent-broken-auth.
-  configureBlindIndexKey(options.blindIndexKey);
-  const autoExtraContext = buildBootExtraContext({
-    db,
-    features,
-    envSource,
-    registry,
-    hasAuth: !!effectiveAuth,
-    sseBroker,
-    crypto: bootCrypto,
-    ...(options.kms && { kms: options.kms }),
-  });
-  const extraContext = {
-    ...addConfigAccessorFactory({ ...autoExtraContext, ...resolvedExtraContext }, registry),
-    ...(options.defaultLocale !== undefined && { defaultLocale: options.defaultLocale }),
-  };
-  const baseAnonymousAccess =
-    typeof options.anonymousAccess === "function"
-      ? options.anonymousAccess(deps)
-      : options.anonymousAccess;
-  // #1374: tenantResolver / tenantExists come from auth-foundation providers.
-  const resolvedAnonymousAccess = await resolveAnonymousAccessFromRegistry(baseAnonymousAccess, {
-    db,
-    registry,
-  });
-
-  // Sessions opt-in: db ist hier schon konkret (createDbConnection oben),
-  // also direkt verdrahten — kein late-bound nötig wie bei runDevApp.
-  // Ein JWT ohne sid wird abgelehnt, sobald ein sessionChecker verdrahtet ist —
-  // Prod-Sessions können nicht stillschweigend umgangen werden. sessionMassRevoker
-  // (4. callback aus createSessionCallbacks) ist nicht Teil der
-  // AuthRoutesConfig-Surface — der geht via bindAutoRevokeFromFeature ans
-  // sessions-Feature (Password-Change/-Reset revoked alle Sessions), nicht
-  // über die auth-routes.
-  // Secure-by-default (#1372): sessionStore provider → resolveSessionStore.
-  const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
-  // Hoisted above buildProdSessionAuth: that call also wires MFA-enable/
-  // disable → PAT-revoke (bindRevokeAllPatTokensFromFeature), so it needs
-  // patFeature too.
-  const patFeature = features.find((f) => f.name === PAT_FEATURE);
-  const sessionAuthFragment = shouldWireProdSessions(
-    Boolean(effectiveAuth),
-    registry.getExtensionUsages(EXT_SESSION_STORE).length > 0,
-  )
-    ? await buildProdSessionAuth(db, registry, sessionsFeature, mfaFeature, patFeature)
-    : undefined;
-
-  // Password-change → PAT-revoke: independent of sessions/MFA being mounted
-  // (buildProdSessionAuth only runs when a sessionStore provider is
-  // registered), so wired unconditionally here whenever PAT itself is.
-  if (patFeature) {
-    wireProdPatAutoRevoke(db, patFeature);
-  }
-
-  // Token-verifier opt-in: any provider feature (personal-access-tokens, a
-  // future auth-provider-jwt, ...) self-registers via
-  // r.useExtension(EXT_TOKEN_VERIFIER, ...) — wire one generic resolver
-  // whenever at least one is mounted, resolved by shape at request-time.
-  // PAT keeps its own per-token rate limiter (patRateLimiter), unrelated to
-  // verification.
-  const hasTokenVerifierProviders = registry.getExtensionUsages(EXT_TOKEN_VERIFIER).length > 0;
-  let patAuthFragment:
-    | {
-        tokenVerifier: TokenVerifier;
-        patRateLimiter: LoginRateLimiter;
-      }
-    | undefined;
-  if (effectiveAuth && patFeature && hasTokenVerifierProviders) {
-    const rl = patRateLimitFromFeature(patFeature);
-    patAuthFragment = {
-      tokenVerifier: (rawToken) => resolveTokenVerifier({ db, registry }, rawToken),
-      patRateLimiter: createRedisLoginRateLimiter(redis, rl.maxRequests, rl.windowMs, "pat"),
-    };
-  }
-
-  const baseEntrypointOptions = {
-    registry,
-    context: {
-      db,
-      redis,
-      entityCache,
-      registry,
-      ...extraContext,
-    },
-    sseBroker,
-    jwtSecret: jwtSecretOrKeyring,
-    ...(jwtIssuer && { jwtIssuer }),
-    ...(instanceId && { instanceId }),
-    dispatcherOptions: {
-      idempotency,
-      ...(resolvedEffectiveFeatures && { effectiveFeatures: resolvedEffectiveFeatures }),
-    },
-    eventDedup,
-    ...(options.observability && { observability: options.observability }),
-    ...(options.observabilityOptions && { observabilityOptions: options.observabilityOptions }),
-    ...(options.metrics && { metrics: options.metrics }),
-    ...(options.rateLimit && { rateLimit: options.rateLimit }),
-    ...(trustedProxyHops !== undefined && { trustedProxyHops }),
-    ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
-    ...(effectiveAuth && {
-      auth: {
-        membershipQuery: TenantQueries.memberships,
-        userQuery: UserQueries.findForAuth,
-        loginHandler: AuthHandlers.login,
-        loginErrorStatusMap: effectiveAuth.loginErrorStatusMap ?? {
-          [AuthErrors.invalidCredentials]: 401,
-          [AuthErrors.noMembership]: 403,
-        },
-        // Redis-backed, not the in-memory default createAuthRoutes falls
-        // back to — an in-process limiter only rate-limits within a single
-        // replica, so a multi-instance prod deployment would silently give
-        // each replica its own bucket (#1262/#1274). Redis is required infra
-        // here already (REDIS_URL), so this is free.
-        loginRateLimit: createRedisLoginRateLimiter(redis),
-        ...(effectiveAuth.cookieDomain !== undefined && {
-          cookieDomain: effectiveAuth.cookieDomain,
-        }),
-        ...(effectiveAuth.allowedOrigins !== undefined && {
-          allowedOrigins: effectiveAuth.allowedOrigins,
-        }),
-        ...(effectiveAuth.unsafeSkipOriginCheck !== undefined && {
-          unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
-        }),
-        ...(trustedProxyHops !== undefined && { trustedProxyHops }),
-        ...(effectiveAuth.postAuthLanding !== undefined && {
-          postAuthLanding: effectiveAuth.postAuthLanding,
-        }),
-        ...sessionAuthFragment,
-        ...patAuthFragment,
-        ...(mfaFeature && {
-          mfaVerifyHandler: AuthMfaHandlers.verify,
-          mfaPreauthEnableStartHandler: AuthMfaHandlers.enableStartPreauth,
-          mfaPreauthConfirmHandler: AuthMfaHandlers.enableConfirmPreauth,
-          mfaVerifyRateLimit: createRedisLoginRateLimiter(
-            redis,
-            undefined,
-            undefined,
-            "mfa-verify",
-          ),
-          mfaPreauthEnableStartRateLimit: createRedisLoginRateLimiter(
-            redis,
-            undefined,
-            undefined,
-            "mfa-preauth-start",
-          ),
-          mfaPreauthConfirmRateLimit: createRedisLoginRateLimiter(
-            redis,
-            undefined,
-            undefined,
-            "mfa-preauth-confirm",
-          ),
-        }),
-        ...(effectiveAuth.passwordReset && {
-          passwordReset: {
-            requestHandler: AuthHandlers.requestPasswordReset,
-            confirmHandler: AuthHandlers.resetPassword,
-          },
-        }),
-        ...(effectiveAuth.emailVerification && {
-          emailVerification: {
-            requestHandler: AuthHandlers.requestEmailVerification,
-            confirmHandler: AuthHandlers.verifyEmail,
-          },
-        }),
-        ...(effectiveAuth.accountUnlock && {
-          accountUnlock: {
-            requestHandler: AuthHandlers.requestAccountUnlock,
-            confirmHandler: AuthHandlers.confirmAccountUnlock,
-          },
-        }),
-        ...(effectiveAuth.signup && {
-          signup: {
-            requestHandler: AuthHandlers.signupRequest,
-            confirmHandler: AuthHandlers.signupConfirm,
-          },
-        }),
-        ...(effectiveAuth.invite && {
-          invite: {
-            acceptHandler: AuthHandlers.inviteAccept,
-            acceptWithLoginHandler: AuthHandlers.inviteAcceptWithLogin,
-            signupCompleteHandler: AuthHandlers.inviteSignupComplete,
-            infoHandler: AuthQueries.inviteInfo,
-          },
-        }),
-      },
-    }),
-    ...(resolvedAnonymousAccess && { anonymousAccess: resolvedAnonymousAccess }),
-  };
-
-  // Deploy-Topologie. Default (Single-Container): createAllInOneEntrypoint
-  // fährt HTTP + BEIDE Job-Lanes (zwei Runner, jeder schedult seine eigene
-  // Lane-Crons → kein Double-Fire) + Event-Dispatcher inline. So laufen
-  // worker-Lane-Crons (run-export-jobs default runIn:"worker") UND MSPs ohne
-  // separaten Worker-Process — die Asymmetrie, an der der Daten-Export hing.
-  // runSingleInstance:false → API-only; ein dezidierter Worker MUSS dann die
-  // worker-Lane + MSPs übernehmen (api-Lane-Jobs laufen weiter lokal).
-  // Default single-instance. eventDispatcher.disabled ist die Alt-Art, MSPs
-  // diesem Prozess wegzunehmen (dezidierter Worker) — als runSingleInstance:
-  // false honorieren (api-only, kein lokaler Dispatcher), damit der explizite
-  // Flag Vorrang behält aber Bestands-Caller nicht brechen.
-  const runSingleInstance = options.runSingleInstance ?? options.eventDispatcher?.disabled !== true;
-  const hasJobs = registry.getAllJobs().size > 0;
-  const queueNamePrefix = options.jobs?.queueNamePrefix;
-  const jobLogger = jobRunLoggerCallbacks(registry, db);
-  const dispatcherTunables =
-    options.eventDispatcher?.pollIntervalMs !== undefined
-      ? { pollIntervalMs: options.eventDispatcher.pollIntervalMs }
-      : {};
-
-  const entrypoint: ApiEntrypoint | AllInOneEntrypoint = runSingleInstance
-    ? createAllInOneEntrypoint({
-        ...baseEntrypointOptions,
-        redisUrl,
-        ...jobLogger,
-        ...(queueNamePrefix !== undefined && { queueNamePrefix }),
-        ...(options.jobs?.getActiveTenantIds !== undefined && {
-          getActiveTenantIds: options.jobs.getActiveTenantIds,
-        }),
-        ...(!options.eventDispatcher?.disabled && { eventDispatcher: dispatcherTunables }),
-      })
-    : createApiEntrypoint({
-        ...baseEntrypointOptions,
-        ...(hasJobs && {
-          jobs: {
-            redisUrl,
-            runLocalJobs: true,
-            ...jobLogger,
-            ...(queueNamePrefix !== undefined && { queueNamePrefix }),
-            ...(options.jobs?.getActiveTenantIds !== undefined && {
-              getActiveTenantIds: options.jobs.getActiveTenantIds,
-            }),
-          },
-        }),
-      });
-
-  // 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 fw#2630 established for buildServer's own hook.
-  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 (kumiko-framework#3050).
-  if (options.wire) {
-    await options.wire({
-      db,
-      redis,
-      registry,
-      dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
-    });
-  }
-
-  // 9. 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.
-  if (effectiveAuth) {
-    await seedAdminGuarded(db, effectiveAuth.admin);
-  }
-  await applyBootSeeds({
-    registry,
-    db,
-    ...(bootCrypto.configCipher && { cipher: bootCrypto.configCipher }),
-  });
-  for (const seed of options.seeds ?? []) {
-    await seed({ db });
-  }
-
-  // ES-Operations / Seed-Migrations (Phase 1). Läuft NACH applyBootSeeds +
-  // existing seeds-array — die deklarativen Seeds sind die "always-insert-
-  // if-missing"-Schicht; seed-migrations sind die "diff-and-update"-
-  // Schicht für Drift den existing Seeds nicht erfassen können (z.B.
-  // Membership-Roles-Change nach initialer Seed-Erstellung).
-  if (options.seedsDir !== undefined && envSource["KUMIKO_SKIP_ES_OPS"] !== "1") {
-    await createEsOperationsTable(db);
-    const seedDispatcher = createDispatcher(registry, {
-      db,
-      redis,
-      entityCache,
-      registry,
-      ...extraContext,
-    });
-    await runPendingSeedMigrations({
-      db,
-      seedsDir: options.seedsDir,
-      appliedBy: "boot",
-      registry, // → dry-run-validator catched handler-QN-typos vor dem write
-      // @wrapper-known semantic-alias
-      createContext: (dbRunner: DbRunner) =>
-        createSeedMigrationContext({ dispatcher: seedDispatcher, dbRunner }),
-    });
-  }
-
-  await entrypoint.start();
-  startPiiEventBackfillOnBoot({
-    db,
-    registry,
-    lifecycle: entrypoint.lifecycle,
-    envSource,
-  });
-
-  // 11. Build the fetch-handler. 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.
-  const fetchHandler = withSecurityHeaders(
-    options.staticDir
-      ? buildStaticFallback(
-          entrypoint.app.fetch.bind(entrypoint.app),
-          options.staticDir,
-          options.hostDispatch,
-          options.resolvePageHead
-            ? { resolvePageHead: options.resolvePageHead, dispatcher: entrypoint.dispatcher }
-            : undefined,
-          entrypoint.dispatcher,
-          trustedProxyHops ?? 0,
-        )
-      : // 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: Request, socketAddress?: string) =>
-          stripNoRouteMatchHeader(await entrypoint.app.fetch(req, socketAddress)),
-    options.securityHeaders,
-  );
-
-  // 11. Mark lifecycle ready — health/ready flips to 200 after this.
-  entrypoint.lifecycle.markReady();
-
-  // Upgrade rejections (401/403/426...) are ordinary responses and get the same headers as fetchHandler.
-  const securedUpgradeFetch = withSecurityHeaders<KumikoServeEnv>(
-    async (req, env) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req, env)),
-    options.securityHeaders,
-  );
-  const webSocketUpgradeFetch = async (req: Request, env: KumikoServeEnv): Promise<Response> =>
-    securedUpgradeFetch(req, env);
-
-  const handle: ProdAppHandle = {
-    entrypoint,
-    fetch: fetchHandler,
-    webSocketUpgradeFetch,
-    listen: async (listenPort = port) => {
-      // Bun.serve is the production HTTP. Tests don't call listen()
-      // because vitest runs under Node where Bun.serve doesn't exist.
-      // Options-Shape (inkl. idleTimeout: 0 für SSE) liegt in der
-      // exportierten buildBunServeOptions-Funktion — siehe ihren
-      // Header für die Begründung.
-      if (typeof (globalThis as { Bun?: unknown }).Bun === "undefined") {
-        // Klare Fehlermeldung statt nackter ReferenceError. Trifft wenn
-        // jemand listen() unter Node/vitest aufruft ohne autoListen:false
-        // — hilft beim Debug, statt sich an "Bun is not defined" abzumühen.
-        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(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.
-      let shuttingDown = false;
-      const shutdown = async (signal: string) => {
-        // skip: shutdown already in progress, avoid double-drain
-        if (shuttingDown) return;
-        shuttingDown = true;
-        // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-        console.log(`[runProdApp] ${signal} received — draining…`);
-        try {
-          await handle.stop();
-          // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
-          console.log("[runProdApp] graceful shutdown complete.");
-        } catch (e) {
-          // biome-ignore lint/suspicious/noConsole: shutdown-time error, only path is stderr
-          console.error("[runProdApp] error during shutdown:", e);
-        } finally {
-          process.exit(0);
-        }
-      };
-      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(`[runProdApp] ready on http://0.0.0.0:${listenPort}`);
-    },
-    stop: async () => {
-      await entrypoint.stop();
-      handle.server?.stop();
-      await closeDb();
-      redis.disconnect();
-    },
-  };
-
-  // 12. Auto-listen unless explicitly suppressed (tests pass autoListen:
-  //     false because Bun.serve isn't available under vitest/node).
-  //     Production path: `await runProdApp({...})` and the server is up.
-  if (options.autoListen !== false) {
-    await handle.listen();
-  }
-
-  return handle;
-}