@cosmicdrift/kumiko-server-runtime 0.386.0 → 0.387.0

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

@@ -9,28 +9,27 @@ import { CSP_HASHES_FILE, parseCspHashes } from "./csp-hashes.js";
 import { buildRequestBoundSystemQuery, } from "./request-bound-system-query.js";
 import { stripNoRouteMatchHeader, tryHonoFirst } from "./try-hono-first.js";
 // Static-asset + SPA-fallback serving for runProdApp's HTTP handler. Split
-// out of run-prod-app.ts (#1005, Welle 2) — mechanical relocation, these
+// out of run-prod-app.ts — mechanical relocation, these
 // functions are self-contained (no closure over runProdApp's local boot
 // state), only params.
-// Static-fallback: try the Hono app first, fall back to a file in
-// staticDir if Hono returns 404. Keeps /api/* on the dispatcher and
-// everything else (HTML, JS, CSS, images) on the disk.
+// Static fallback: try the Hono app first and serve a file from staticDir only
+// when Hono returns 404, so /api/* stays on the dispatcher while HTML,
+// JavaScript, CSS, and images come from disk.
 //
-// Cache-Header-Strategie:
+// Cache-header strategy:
 //   /assets/*               → public, max-age=31536000, immutable
-//                             (gehashte Filenames vom Build, sicher cachebar)
+//                             (build-generated hashed filenames are safe to cache)
 //   /index.html             → no-cache, must-revalidate
-//                             (HTML-Shell, must reload on deploy)
+//                             (the HTML shell must reload after deployment)
 //   /manifest.json, /sw.js  → no-cache
-//                             (Update-Detection-Mechanismen, müssen frisch sein)
-//   alles andere            → kein expliziter Header
-//                             (Browser-Default, public/-Files wie favicon)
-// File-reader für den static-fallback. Nutzt node:fs/promises statt
-// Bun.file damit der Pfad in vitest+node integration-tests laufen kann
-// (Bun.file ist Bun-only). Performance-cost ist marginal: die Disk-
-// Files in einem prod-staticDir sind 1-200 KB, full-buffer-Read ist
-// ein paar Mikrosekunden. Streaming via Bun.file wäre nur relevant ab
-// ~1 MB.
+//                             (update-detection mechanisms must stay fresh)
+//   everything else         → no explicit header
+//                             (browser default, including public/ files such as favicon)
+//
+// Use node:fs/promises instead of Bun.file so this path also runs in vitest+node
+// integration tests; Bun.file is Bun-only. Full-buffer reads are acceptable because
+// production static files are typically 1–200 KB; streaming would matter only above
+// roughly 1 MB.
 export async function readStaticFile(filePath) {
     try {
         const { readFile, stat } = await import("node:fs/promises");
@@ -99,10 +98,9 @@ export function serveDiskFile(req, pathname, file) {
         lastModified: new Date(file.mtimeMs),
     });
 }
-// Minimal-Mime-Map — deckt die Files ab die kumiko-build und typische
-// public/-Inhalte produzieren. Bun.file leitet das aus dem Suffix ab,
-// im node-Pfad müssen wir es selbst tun. Default: octet-stream (Browser
-// fragt bei unbekanntem MIME nach).
+// Covers files produced by kumiko-build and typical public/ contents. Bun.file
+// infers the type from the suffix, but the node path must do so explicitly;
+// unknown types use octet-stream so the browser can handle them safely.
 export function mimeTypeFor(filePath) {
     const ext = filePath.toLowerCase().split(".").pop() ?? "";
     switch (ext) {
@@ -190,9 +188,9 @@ hostDispatchScriptHashes = []) {
     // inject into) → the original html object is returned untouched.
     //
     // The resolve+timeout+inject itself runs through headless's
-    // resolveAndInjectPageHead — the single call site runDevApp also uses
-    // (kumiko-framework#3026), so only the systemQuery/dispatcher wiring
-    // below (Request-bound, prod-specific) and the etag recompute are local.
+    // resolveAndInjectPageHead, the same call site runDevApp uses, so only the
+    // systemQuery/dispatcher wiring below (Request-bound, prod-specific) and the
+    // etag recompute are local.
     async function applyPageHead(req, html, socketAddress) {
         if (!pageHead)
             return html;
@@ -224,10 +222,9 @@ hostDispatchScriptHashes = []) {
             etag: computeStrongEtag(encoded),
         };
     }
-    // hostDispatch konsultieren wenn gesetzt UND der Request auf den
-    // HTML-Fallback fällt (Root oder SPA-Route). Returnt entweder die
-    // resolved Response (redirect/404/html) oder null wenn der Default-
-    // Pfad weiterlaufen soll.
+    // Consult hostDispatch when the request reaches the HTML fallback (the root or
+    // an SPA route). It can return a resolved response (redirect, 404, or HTML),
+    // or null to continue with the default path.
     async function tryHostDispatch(req, socketAddress) {
         if (!hostDispatch)
             return null;
@@ -261,8 +258,8 @@ hostDispatchScriptHashes = []) {
     async function serveHostDispatchFile(req, file, csp, socketAddress, status) {
         const html = await readHtmlFile(`${staticDir}/${file}`);
         if (!html) {
-            // Author-Fehler: hostDispatch verweist auf nicht-existente Datei.
-            // Liefer 500 statt silent-404 damit der Bug schnell auffällt.
+            // Configuration error: hostDispatch references a nonexistent file. Return 500
+            // instead of silently returning 404 so the problem is visible immediately.
             return new Response(`hostDispatch: file not found: ${file}`, { status: 500 });
         }
         // Per-host body (hostDispatch picks the file by host) → Vary: Host,
@@ -282,26 +279,24 @@ hostDispatchScriptHashes = []) {
         if (url.pathname.startsWith("/api/") || url.pathname === "/health") {
             return stripNoRouteMatchHeader(await apiHandler(req, socketAddress));
         }
-        // Hono-First für andere Pfade: extraRoutes (z.B. /feed.xml,
-        // /sitemap.xml) UND r.httpRoute-Features (z.B. /legal/*) müssen vor
-        // dem Disk-Lookup greifen, sonst schluckt der SPA-Fallback unten
-        // unbekannte Pfade als index.html. Shared mit dev-server's
-        // createKumikoServer.handleFetch damit beide IDENTISCHE Semantik haben.
+        // Try Hono before disk lookup so extraRoutes (for example /feed.xml and
+        // /sitemap.xml) and r.httpRoute features (for example /legal/*) are handled
+        // before unknown paths fall through to index.html. Keep this consistent with
+        // dev-server's createKumikoServer.handleFetch so both paths have identical semantics.
         const honoTry = await tryHonoFirst({ fetch: apiHandler }, req, socketAddress);
         if (honoTry.matched) {
             return honoTry.response;
         }
         const honoRes = honoTry.response;
-        // Disk-/SPA-Fallback ist GET/HEAD-only. Ein non-GET ohne Hono-Match
-        // (z.B. POST auf einen falsch konfigurierten Webhook-Pfad) muss den
-        // Hono-404 durchreichen — 200 index.html würde dem Provider
-        // "delivered" signalisieren und Events gingen still verloren (#259).
+        // The disk/SPA fallback accepts only GET and HEAD. A non-GET without a Hono
+        // match (for example, POST to a misconfigured webhook path) must preserve the
+        // Hono 404: returning index.html with 200 could make the provider report the
+        // event as delivered even though it was dropped.
         if (req.method !== "GET" && req.method !== "HEAD") {
             return honoRes;
         }
-        // Disk-Datei (Asset oder konkrete File). Asset-Pfade laufen
-        // host-unabhängig — die Bundles in /assets/* werden vom client
-        // aktiv geladen, kein Server-side Routing nötig.
+        // Asset paths are host-independent because the client actively loads the
+        // bundles in /assets/*; they do not require server-side routing.
         const isIndexRequest = url.pathname === "/" || url.pathname === "/index.html";
         if (!isIndexRequest) {
             const relPath = url.pathname.slice(1);
@@ -324,18 +319,17 @@ hostDispatchScriptHashes = []) {
             const withHead = await applyPageHead(req, index, socketAddress);
             return serveHtmlFile(req, "/index.html", withHead, pageHead && { vary: PAGE_HEAD_VARY });
         }
-        // Kein Hono-Match, keine Disk-Datei, kein index.html → liefer den
-        // ursprünglichen 404 von Hono durch (statt einen neuen Roundtrip).
+        // If Hono found no route and neither a disk file nor index.html exists, preserve
+        // its original 404 instead of issuing another request.
         return honoRes;
     };
 }
 // The resolved page head depends on host and preferred locale; ?lang= is part of the URL and
 // already keys the cache.
 const PAGE_HEAD_VARY = "Host, Accept-Language";
-// Map URL-Pfad → Cache-Policy. Hashed-Asset-Pfade (/assets/*) sind
-// unveränderlich, der Rest bleibt revalidate/no-cache damit Updates ohne
-// Hard-Reload greifen. Exported für Unit-Tests; Konsumenten gehen via
-// runProdApp.
+// Map URL paths to cache policies. Hashed asset paths (/assets/*) are immutable;
+// other paths use revalidation or no-cache so updates take effect without a hard
+// reload. Exported for unit tests; consumers access it through runProdApp.
 export function staticCachePolicy(pathname) {
     if (pathname.startsWith(`/${ASSETS_DIR}/`)) {
         return { kind: "immutable" };
@@ -345,9 +339,8 @@ export function staticCachePolicy(pathname) {
     }
     if (pathname === "/manifest.json" ||
         pathname === "/sw.js" ||
-        // ponytail: build-info.json ist statisch — kein /api/version-Endpoint
-        // nötig, der Disk-Fallback serviert sie. no-cache, sonst pollt der
-        // UpdateChecker eine veraltete id.
+        // ponytail: build-info.json is static, so no /api/version endpoint is needed; the disk
+        // fallback serves it. Use no-cache so UpdateChecker does not poll a stale id.
         pathname === "/build-info.json") {
         return { kind: "no-cache" };
     }

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

@@ -48,17 +48,17 @@ export type PasswordResetSetup = Omit<PasswordResetOptions, "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. */
+/** Wrapper API for Magic-Link self-signup. = SignupOptions (appUrl; mail
+ *  is sent through delivery/ctx.notify like reset/verify). Unlike reset/verify,
+ *  there is no hmacSecret: signup tokens are opaque random values in Redis,
+ *  not 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). */
+/** Wrapper API for tenant-invite Magic-Link. = InviteOptions (appUrl; the
+ *  invite mail is sent through delivery like reset/verify/signup). The
+ *  framework has three accept branches; handler names are fixed in
+ *  run-prod-app through AuthHandlers, as with signup. */
 export type InviteSetup = InviteOptions;
-/** Wrapper API for the account-unlock flow (#1266). = AccountUnlockOptions
+/** Wrapper API for the account-unlock flow. = AccountUnlockOptions
  *  (appUrl via delivery, symmetric to PasswordResetSetup). Self-service
  *  escape hatch for accountLockout's failure counter; the lockout is always
  *  on, so `auth.mail` mounts this flow by default. */
@@ -68,23 +68,25 @@ export type AccountUnlockSetup = Omit<AccountUnlockOptions, "hmacSecret"> & {
 /** 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,
+ *  RunDevAppAuthOptions.accountLockout — 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 5 Mail-Flows aus einem env-SMTP-Transport + Standard-
- *  Templates (siehe `auth.mail` + resolveAuthMail). */
+/** Auth-mail convenience options shared by runProdApp and runDevApp.
+ *  Wires all five mail flows from an env-based SMTP transport and default
+ *  templates (see `auth.mail` and 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". */
+    /** App name used in the mail subject and body. Default: "Account". */
     readonly appName?: string;
-    /** Locale für die Mail-Templates. Default "de". */
+    /** Locale used by the mail templates. Default: "de". */
     readonly locale?: AuthMailLocale;
-    /** "strict" blockt Login bis emailVerified; "off" mountet ohne Gate. */
+    /** "strict" blocks login until emailVerified; "off" mounts the flow without
+     *  that gate. */
     readonly emailVerificationMode?: "strict" | "off";
-    /** Fallback-From-Adresse wenn `SMTP_FROM`-env fehlt (env gewinnt). */
+    /** Fallback From address when the `SMTP_FROM` env var is absent; the env var
+     *  takes precedence. */
     readonly from?: string;
     /** Overrides single auth paths (default DEFAULT_AUTH_PATHS). */
     readonly paths?: Partial<AuthPaths>;
@@ -119,16 +121,15 @@ export type RunProdAppAuthOptions = {
     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). */
+    /** Self-signup flow (Magic-Link). When set, /api/auth/signup-request and
+     *  /api/auth/signup-confirm are mounted; signup-confirm mints a JWT and
+     *  cookies like a successful login (automatic login after 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
+    /** Account-unlock flow. 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. */
@@ -163,13 +164,12 @@ export type RunProdAppAuthOptions = {
      *  `mail.baseUrl`, then of the APP_BASE_URL env. */
     readonly publicOrigin?: string;
     /** 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. */
+     *  process for client-IP derivation (see AuthRoutesConfig.trustedProxyHops)
+     *  — 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
@@ -192,12 +192,10 @@ export type ProdSeedFn = (deps: {
     masterKeyProvider?: import("@cosmicdrift/kumiko-framework/secrets").MasterKeyProvider;
     configEncryption?: import("@cosmicdrift/kumiko-framework/secrets").EnvelopeCipher;
 }) => 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. */
+/** Dependencies passed to the `extraContext` and `anonymousAccess` factories.
+ *  The returned config can close over them, for example a TenantResolver that
+ *  queries `db` or an extra-context provider that publishes SSE events. The
+ *  shape matches setupTestStack so test and production wiring remain aligned. */
 export type RunProdAppDeps = {
     readonly db: import("@cosmicdrift/kumiko-framework/db").DbConnection;
     readonly redis: Redis;
@@ -282,20 +280,16 @@ export type RunProdAppOptions = {
      *  @example
      *  seeds: { demoTenant: { key: "demo", name: "Demo" }, sysadminFromEnv: true, run: [seedDemoData] } */
     readonly seeds?: readonly ProdSeedFn[] | ProdSeedsConfig;
-    /** 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 */
+    /** Path to the seeds directory for ES operations and seed migrations
+     *  (file-based like drizzle-migrate). When set and KUMIKO_SKIP_ES_OPS != "1",
+     *  runProdApp scans it for `<id>.ts` files, diffs them against the
+     *  kumiko_es_operations table, and runs pending operations in a transaction. */
     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). */
+    /** Anonymous access for public endpoints (same shape as runDevApp).
+     *  Accepts either a static config object or a factory
+     *  `({db, redis, registry}) => Config`, called once at boot after
+     *  db/redis/registry have been constructed. The factory can close over these
+     *  dependencies so a TenantResolver can look up a subdomain in the database. */
     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
@@ -350,25 +344,24 @@ export type RunProdAppOptions = {
      *  (AWS/GCP/Azure); with it set, `KUMIKO_SECRETS_MASTER_KEY_V1` is not
      *  required in the env. */
     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. */
+    /** Subject-key adapter for crypto-shredding (GDPR Art. 17). When set, it is
+     *  exposed to feature code as `ctx.kms`, and boot checks its health so the app
+     *  cannot start against an unreachable KMS. Without an adapter,
+     *  crypto-shredding remains disabled. */
     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. */
+    /** 32-byte base64 key for blind-index HMACs on `lookupable` fields
+     *  (env: KUMIKO_BLIND_INDEX_KEY, `openssl rand -base64 32`). It is separate
+     *  from PLATFORM_KEK and not part of the KmsAdapter contract. It is required
+     *  when `kms` is set and a feature declares lookupable fields; otherwise
+     *  equality lookups on ciphertext, such as login by email, fail and boot
+     *  aborts. */
     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. */
+    /** Explicit opt-out from the strict PII boot gate. Features may declare
+     *  pii/userOwned/tenantOwned fields without a provisioned `kms`; those fields
+     *  remain plaintext in rows and events, and GDPR erasure through
+     *  crypto-shredding is unavailable. The value records the reason for the
+     *  audit trail (for example, "kms rollout pending"). Without this flag and
+     *  without `kms`, boot aborts. */
     readonly allowPlaintextPii?: string;
     /** Short form over `kms` / `blindIndexKey` / `allowPlaintextPii` that wires
      *  the subject-key KMS from the env; not combinable with them. Unset keeps
@@ -422,8 +415,8 @@ export type RunProdAppOptions = {
     /** With `runSingleInstance: false`: the worker mounts the same mail / fileStorage features
      *  (its own boot options or by hand), so the boot warning about them stays silent. */
     readonly workerMountsFeatures?: boolean;
-    /** Job-Block. Wenn das Feature `r.job(...)` registriert, wird er
-     *  automatisch verdrahtet (siehe runSingleInstance). */
+    /** Job settings. Jobs a feature registers with `r.job(...)` are wired
+     *  automatically (see runSingleInstance). */
     readonly jobs?: {
         /** BullMQ-Queue-Prefix (default "kumiko"). */
         readonly queueNamePrefix?: string;
@@ -433,25 +426,20 @@ export type RunProdAppOptions = {
          *  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. */
+    /** Event dispatcher (MSP application) in the API process. Enabled by default
+     *  because the single-container deployment has no separate worker process to
+     *  apply multiStreamProjections. Set `disabled: true` only when a dedicated
+     *  worker process takes over the dispatcher. */
     readonly eventDispatcher?: {
         readonly disabled?: boolean;
-        /** Poll-Intervall des Dispatcher-Loops (default siehe
-         *  createEventDispatcher). LISTEN/NOTIFY-Wiring kommt mit einem
-         *  späteren pgClient-Pass-through. */
+        /** Dispatcher-loop polling interval (default: see createEventDispatcher).
+         *  LISTEN/NOTIFY wiring comes with a later 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). */
+     *  inside buildServer, right after the r.httpRoute loop, before seeds. */
     readonly extraRoutes?: readonly ExtraRouteDefinition[];
     /** Framework-managed unsubscribe links. Mounts `createUnsubscribeRoutes({ secret })` and makes
      *  delivery sign `data.unsubscribeUrl` (path `DELIVERY_UNSUBSCRIBE_PATH`) for every email
@@ -508,13 +496,13 @@ export type RunProdAppOptions = {
      *  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). */
+    /** Observability provider (tracer and meter). Default: Noop, with no overhead
+     *  or `/metrics` endpoint. Supply a provider based on
+     *  `createPrometheusMeter()` together with `metrics` to expose `/metrics`. */
     readonly observability?: ObservabilityProvider;
-    /** Aktiviert den `/metrics`-Endpoint (Open-Metrics-Format). Ohne einen
-     *  PrometheusMeter-basierten `observability`-Provider antwortet `/metrics`
-     *  mit 503 + Misconfiguration-Hinweis statt echter Metriken. */
+    /** Enables the `/metrics` endpoint in OpenMetrics format. Without a
+     *  PrometheusMeter-based `observability` provider, `/metrics` returns 503
+     *  with a misconfiguration message instead of real metrics. */
     readonly metrics?: import("@cosmicdrift/kumiko-framework/api").ServerOptions["metrics"];
     /** L1 (global per-IP limit) + L2 (auth endpoints) rate-limit middleware, passed
      *  to `buildServer`'s `ServerOptions.rateLimit`. Without a value L1 allows 600/60 s