@cosmicdrift/kumiko-server-runtime 0.296.0 → 0.299.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.296.0",
+  "version": "0.299.0",
   "description": "Production server-boot runtime for Kumiko apps: connections, schema-drift-gate, seeds, lifecycle, graceful shutdown. Symmetric to kumiko-dev-server's runDevApp, without dev/scaffold/codegen tooling.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -80,9 +80,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.296.0",
-    "@cosmicdrift/kumiko-framework": "0.296.0",
-    "@cosmicdrift/kumiko-headless": "0.296.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.299.0",
+    "@cosmicdrift/kumiko-framework": "0.299.0",
+    "@cosmicdrift/kumiko-headless": "0.299.0",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

package/src/__tests__/run-prod-app.integration.test.ts

@@ -22,9 +22,11 @@ import {
 import { userEntity } from "@cosmicdrift/kumiko-bundled-features/user";
 import {
   createRedisSseBroker,
+  ExtraRouteRejection,
   isRedisSseBroker,
   NO_ROUTE_MATCH_HEADER_NAME,
   type SseEvent,
+  signatureRoute,
 } from "@cosmicdrift/kumiko-framework/api";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { InMemoryKmsAdapter, type KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
@@ -97,8 +99,8 @@ const widgetFeature = defineFeature("prod-probe", (r) => {
     rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
     handler: async (_event, ctx) => ({ hasKms: ctx.kms !== undefined }),
   });
-  // SystemAdmin-gated write — Ziel des extraRoutes.dispatchSystemWrite-
-  // Tests: Echo von user.tenantId + roles beweist, dass der Dispatch
+  // SystemAdmin-gated write — Ziel der entry:"signature" / `wire`-Tests:
+  // Echo von user.tenantId + roles beweist, dass der Dispatch
   // durch den echten Dispatcher (Zod + Access-Check) läuft und der
   // auto-konstruierte SystemUser den Ziel-Tenant trägt.
   r.writeHandler({
@@ -313,64 +315,78 @@ describe("runProdApp", () => {
     expect(res.status).toBe(200);
   });
 
-  test("extraRoutes-callback mounts custom HTTP-routes on the Hono-app", async () => {
-    // Beweist dass die runProdApp.extraRoutes-Option den Hono-app
-    // bekommt und Routes daran VOR dem static-fallback greifen — das
-    // ist das Fundament für /feed.xml, /sitemap.xml, /og-image etc.
+  test("extraRoutes: entry:anonymous mounts custom HTTP-routes on the Hono-app", async () => {
+    // Proves runProdApp.extraRoutes mounts declarative route entries that
+    // take effect BEFORE the static fallback — the foundation for
+    // /feed.xml, /sitemap.xml, /og-image etc.
     let extraInvoked = false;
     const handle = await boot(undefined, {
-      extraRoutes: (app, deps) => {
-        extraInvoked = true;
-        // deps.db + deps.redis sind die runProdApp-Connections — die
-        // Route kann gegen die Domain queryen, hier reicht ein simple
-        // Echo zum Beweis dass wir ans App-Object kommen.
-        app.get("/feed.xml", (c) => {
-          const dbAvailable = deps.db !== undefined;
-          return c.body(`<?xml version="1.0"?><probe ok="${dbAvailable}" />`, 200, {
-            "content-type": "application/rss+xml",
-          });
-        });
-      },
+      extraRoutes: [
+        {
+          method: "GET",
+          path: "/feed.xml",
+          entry: "anonymous",
+          handler: (c) => {
+            extraInvoked = true;
+            return c.body('<?xml version="1.0"?><probe ok="true" />', 200, {
+              "content-type": "application/rss+xml",
+            });
+          },
+        },
+      ],
     });
 
-    expect(extraInvoked).toBe(true);
-
     // handle.fetch durchläuft den static-fallback wrapper — dort liegt
     // die "Hono-First, dann Disk"-Logik. entrypoint.app.fetch würde den
     // wrapper umgehen und damit die regression nicht erkennen.
     const res = await handle.fetch(new Request("http://test/feed.xml"));
     expect(res.status).toBe(200);
     expect(res.headers.get("content-type")).toBe("application/rss+xml");
+    expect(extraInvoked).toBe(true);
     const body = await res.text();
     expect(body).toContain('<probe ok="true" />');
   });
 
-  test("extraRoutes-deps: dispatchSystemWrite schreibt als SystemAdmin des Ziel-Tenants, registry verfügbar", async () => {
-    // Das ist das Wiring für Provider-Webhook-Routes (billing-foundation
-    // createSubscriptionWebhookHandler): die Route authentifiziert via
-    // Provider-Signatur und schreibt dann am JWT-Pfad vorbei durch den
-    // Command-Dispatcher. Beweist: (a) registry liegt in den deps,
-    // (b) dispatchSystemWrite geht durch Zod + Access-Check des Handlers,
-    // (c) der SystemUser trägt den Ziel-Tenant (Event-Store-Konsistenz).
+  test("extraRoutes: entry:signature dispatchSystemWrite schreibt als SystemAdmin des Ziel-Tenants, registry verfügbar", async () => {
+    // Wiring for provider webhook routes (billing-foundation
+    // createSubscriptionWebhookRoute): the route authenticates via
+    // provider signature (verify()) and then writes past the JWT path
+    // through the command dispatcher. Proves: (a) registry is in the
+    // deps, (b) dispatchSystemWrite goes through Zod + the handler's
+    // access check, (c) the SystemUser carries the target tenant.
     let registryHasProbe = false;
     const handle = await boot(undefined, {
-      extraRoutes: (app, deps) => {
-        registryHasProbe = deps.registry.features.has("prod-probe");
-        app.post("/webhook-probe", async (c) => {
-          const result = await deps.dispatchSystemWrite({
-            handlerQn: "prod-probe:write:probe-write",
-            payload: { note: "from-webhook" },
-            tenantId: TENANT_ID as import("@cosmicdrift/kumiko-framework/engine").TenantId,
-          });
-          return c.json(result);
-        });
-      },
+      extraRoutes: [
+        signatureRoute({
+          method: "POST",
+          path: "/webhook-probe",
+          entry: "signature",
+          verify: async (req) => {
+            if (req.headers["x-probe-signature"] !== "test-secret") {
+              throw new ExtraRouteRejection(401, { error: "bad-signature" });
+            }
+          },
+          handler: async (c, _verified, deps) => {
+            registryHasProbe = deps.registry.features.has("prod-probe");
+            const result = await deps.dispatchSystemWrite({
+              handlerQn: "prod-probe:write:probe-write",
+              payload: { note: "from-webhook" },
+              tenantId: TENANT_ID as import("@cosmicdrift/kumiko-framework/engine").TenantId,
+            });
+            return c.json(result);
+          },
+        }),
+      ],
     });
 
-    expect(registryHasProbe).toBe(true);
-
-    const res = await handle.fetch(new Request("http://test/webhook-probe", { method: "POST" }));
+    const res = await handle.fetch(
+      new Request("http://test/webhook-probe", {
+        method: "POST",
+        headers: { "x-probe-signature": "test-secret" },
+      }),
+    );
     expect(res.status).toBe(200);
+    expect(registryHasProbe).toBe(true);
     const body = (await res.json()) as {
       isSuccess: boolean;
       data?: { tenantSeen: string; roles: string[] };
@@ -380,6 +396,44 @@ describe("runProdApp", () => {
     expect(body.data?.roles).toContain("SystemAdmin");
   });
 
+  test("extraRoutes: entry:signature with a wrong signature rejects with 401 before dispatchSystemWrite runs", async () => {
+    let dispatched = false;
+    const handle = await boot(undefined, {
+      extraRoutes: [
+        signatureRoute({
+          method: "POST",
+          path: "/webhook-probe",
+          entry: "signature",
+          verify: async (req) => {
+            if (req.headers["x-probe-signature"] !== "test-secret") {
+              throw new ExtraRouteRejection(401, { error: "bad-signature" });
+            }
+          },
+          handler: async (c, _verified, deps) => {
+            dispatched = true;
+            const result = await deps.dispatchSystemWrite({
+              handlerQn: "prod-probe:write:probe-write",
+              payload: { note: "from-webhook" },
+              tenantId: TENANT_ID as import("@cosmicdrift/kumiko-framework/engine").TenantId,
+            });
+            return c.json(result);
+          },
+        }),
+      ],
+    });
+
+    const res = await handle.fetch(
+      new Request("http://test/webhook-probe", {
+        method: "POST",
+        headers: { "x-probe-signature": "wrong" },
+      }),
+    );
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("bad-signature");
+    expect(dispatched).toBe(false);
+  });
+
   test("static-fallback: extraRoute beats Disk-File at colliding path (Hono-First)", async () => {
     // Regression-Test für den static-fallback-Bug von Phase 2 Step 1:
     // wenn ein extraRoute (z.B. /feed.xml) UND eine gleichnamige Disk-
@@ -393,13 +447,17 @@ describe("runProdApp", () => {
 
     const handle = await boot(undefined, {
       staticDir: tmpStaticDir,
-      extraRoutes: (app) => {
-        app.get("/feed.xml", (c) =>
-          c.body("<this-is-the-hono-version />", 200, {
-            "content-type": "application/rss+xml",
-          }),
-        );
-      },
+      extraRoutes: [
+        {
+          method: "GET",
+          path: "/feed.xml",
+          entry: "anonymous",
+          handler: (c) =>
+            c.body("<this-is-the-hono-version />", 200, {
+              "content-type": "application/rss+xml",
+            }),
+        },
+      ],
     });
 
     const res = await handle.fetch(new Request("http://test/feed.xml"));
@@ -436,12 +494,17 @@ describe("runProdApp", () => {
 
     const handle = await boot(undefined, {
       staticDir: tmpStaticDir,
-      extraRoutes: (app) => {
-        app.get("/probe/:id", (c) => {
-          if (c.req.param("id") === "missing") return c.text("not found", 404);
-          return c.text(`probe:${c.req.param("id")}`, 200);
-        });
-      },
+      extraRoutes: [
+        {
+          method: "GET",
+          path: "/probe/:id",
+          entry: "anonymous",
+          handler: (c) => {
+            if (c.req.param("id") === "missing") return c.text("not found", 404);
+            return c.text(`probe:${c.req.param("id")}`, 200);
+          },
+        },
+      ],
     });
 
     const res = await handle.fetch(new Request("http://test/probe/missing"));
@@ -458,9 +521,14 @@ describe("runProdApp", () => {
 
     const handle = await boot(undefined, {
       staticDir: tmpStaticDir,
-      extraRoutes: (app) => {
-        app.get("/probe/:id", (c) => c.text("not found", 404));
-      },
+      extraRoutes: [
+        {
+          method: "GET",
+          path: "/probe/:id",
+          entry: "anonymous",
+          handler: (c) => c.text("not found", 404),
+        },
+      ],
     });
 
     const res = await handle.fetch(new Request("http://test/some/client-route"));
@@ -496,12 +564,17 @@ describe("runProdApp", () => {
     // through buildStaticFallback/tryHonoFirst, so the strip has to happen
     // at this bypass site too (run-prod-app.ts's fetchHandler assembly).
     const handle = await boot(undefined, {
-      extraRoutes: (app) => {
-        app.get("/probe/:id", (c) => {
-          if (c.req.param("id") === "missing") return c.text("not found", 404);
-          return c.text(`probe:${c.req.param("id")}`, 200);
-        });
-      },
+      extraRoutes: [
+        {
+          method: "GET",
+          path: "/probe/:id",
+          entry: "anonymous",
+          handler: (c) => {
+            if (c.req.param("id") === "missing") return c.text("not found", 404);
+            return c.text(`probe:${c.req.param("id")}`, 200);
+          },
+        },
+      ],
     });
 
     const routerMiss = await handle.fetch(new Request("http://test/totally/unknown/path"));
@@ -514,6 +587,25 @@ describe("runProdApp", () => {
     expect(deliberate404.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
   });
 
+  test("hostDispatch: async fn receives deps.systemQuery, 'not-found' result → 404", async () => {
+    const tmpStaticDir = await createTempStaticDir({
+      "index.html": "<html>SPA shell</html>",
+    });
+    let systemQueryPonged = false;
+    const handle = await boot(undefined, {
+      staticDir: tmpStaticDir,
+      hostDispatch: async (_req, deps) => {
+        const result = await deps.systemQuery("prod-probe:query:ping", {}, TENANT_ID);
+        systemQueryPonged = (result as { pong: boolean }).pong === true; // @cast-boundary engine-payload
+        return { kind: "not-found" };
+      },
+    });
+
+    const res = await handle.fetch(new Request("http://test/"));
+    expect(res.status).toBe(404);
+    expect(systemQueryPonged).toBe(true);
+  });
+
   test("static-fallback: If-None-Match → 304 on disk file", async () => {
     const tmpStaticDir = await createTempStaticDir({
       "robots.txt": "User-agent: *\nAllow: /",
@@ -915,10 +1007,10 @@ describe("runProdApp: lokaler Event-Dispatcher (MSP-Anwendung im Single-Containe
   test(
     "Write → appendEvent → MSP wendet async an; Consumer-Cursor wandert",
     async () => {
-      let dispatchSystemWrite: import("../extra-routes-deps").ExtraRoutesSystemDeps["dispatchSystemWrite"];
+      let dispatchSystemWrite: import("../extra-routes-deps").SystemWireDeps["dispatchSystemWrite"];
       const handle = await boot(undefined, {
         eventDispatcher: { pollIntervalMs: 50 },
-        extraRoutes: (_app, deps) => {
+        wire: (deps) => {
           dispatchSystemWrite = deps.dispatchSystemWrite;
         },
       });

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.298.0",
+    "type": "breaking",
+    "title": "ExtraRoutesSystemDeps renamed to SystemWireDeps; hostDispatch gains systemQuery",
+    "migration": "ExtraRoutesSystemDeps is renamed to SystemWireDeps and now backs the new wire hook instead of extraRoutes; WorkerWireDeps is derived from it. A consumer importing ExtraRoutesSystemDeps from server-runtime must switch to SystemWireDeps (same shape: db, redis, registry, dispatchSystemWrite). HostDispatchFn passed to runProdApp now takes a second argument { systemQuery } - a dispatch function reading db directly for routing decisions must switch to systemQuery."
+  },
   {
     "version": "0.291.0",
     "type": "fix",

package/src/extra-routes-deps.ts

@@ -1,47 +1,38 @@
-import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import {
-  createSystemUser,
-  type Registry,
-  type SessionUser,
-  type TenantId,
-  type WriteResult,
-} from "@cosmicdrift/kumiko-framework/engine";
+import type { Registry, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 import type Redis from "ioredis";
 
-/** Deps für `extraRoutes` — geteilt zwischen runProdApp (prod) und
- *  createKumikoServer (dev), damit die beiden Pfade nicht driften.
- *  Naming: `deps` statt `ctx` weil im Framework `ctx` der HandlerContext
- *  mit user/tenant/registry ist — hier ist der Scope absichtlich kleiner
- *  (Routes laufen außerhalb der Auth/Tenant-Pipeline). */
-export type ExtraRoutesSystemDeps = {
+export type { SystemDispatchArgs } from "@cosmicdrift/kumiko-framework/api";
+// Re-export the SystemAdmin write/query builders — the single source of
+// truth lives in framework/api next to buildServer's own `extraRoutes`
+// mount so the two never drift on how the SystemAdmin identity is built.
+export {
+  makeDispatchSystemQuery,
+  makeDispatchSystemWrite,
+} from "@cosmicdrift/kumiko-framework/api";
+
+/** Deps for the `wire` hook (runProdApp/createKumikoServer, after
+ *  buildServer has mounted `extraRoutes` — see kumiko-framework#3050) and
+ *  for `runWorkerApp.wireComponents`. Naming: `deps` not `ctx` because
+ *  `ctx` is the framework's HandlerContext (user/tenant/registry) — this
+ *  scope is deliberately smaller and has NO `app` (routes are declared via
+ *  `extraRoutes`, not wired here). */
+export type SystemWireDeps = {
   readonly db: DbConnection;
   readonly redis: Redis;
-  /** Feature-registry — z.B. für Plugin-Lookups via
+  /** Feature-registry — e.g. for plugin-lookups via
    *  `registry.getExtensionUsages("subscriptionProvider")`. */
   readonly registry: Registry;
-  /** Schreibt durch den /api/*-Command-Dispatcher (gleiche Idempotency/
-   *  Job-Hooks) — aber als auto-konstruierter SystemAdmin des Ziel-
-   *  Tenants, OHNE Access-Check der Route. Privilege-Scope: SystemAdmin
-   *  ist die höchste nicht-tenant-scoped Rolle — der Call erreicht JEDEN
-   *  SystemAdmin-gegateten Handler auf jedem Tenant; das Rollen-Set ist
-   *  nicht konfigurierbar. Nur für Pfade, die ihre Authentizität selbst
-   *  beweisen (Provider-Webhook-Signaturen,
-   *  createSubscriptionWebhookHandler et al.). */
+  /** Writes through the /api/*-command-dispatcher (same idempotency/job
+   *  hooks) as an auto-constructed SystemAdmin of the target tenant,
+   *  WITHOUT the route's own access-check. Privilege-scope: SystemAdmin is
+   *  the highest non-tenant-scoped role — reaches ANY SystemAdmin-gated
+   *  handler on ANY tenant; the role-set is not configurable. Only for
+   *  co-running components that already proved their own authenticity
+   *  (e.g. an IMAP supervisor authenticated against its own mailbox). */
   readonly dispatchSystemWrite: (args: {
     readonly handlerQn: string;
     readonly payload: unknown;
-    readonly tenantId: TenantId;
+    readonly tenantId: import("@cosmicdrift/kumiko-framework/engine").TenantId;
   }) => Promise<WriteResult>;
 };
-
-type SystemWriteDispatcher = {
-  readonly write: (handlerQn: string, payload: unknown, user: SessionUser) => Promise<WriteResult>;
-};
-
-export function makeDispatchSystemWrite(
-  dispatcher: SystemWriteDispatcher,
-): ExtraRoutesSystemDeps["dispatchSystemWrite"] {
-  return ({ handlerQn, payload, tenantId }) =>
-    dispatcher.write(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
-}

package/src/run-prod-app-static-files.ts

@@ -132,6 +132,11 @@ export function buildStaticFallback(
   appSchemaJson: string,
   hostDispatch?: HostDispatchFn,
   pageHead?: PageHeadOptions,
+  /** Backs hostDispatch's `systemQuery` — required whenever `hostDispatch`
+   *  is set (a hostDispatch that reads `deps.systemQuery` without it would
+   *  throw). Separate from `pageHead.dispatcher` since resolvePageHead is
+   *  optional independently of hostDispatch. */
+  hostDispatchDispatcher?: QueryDispatcher,
 ): (req: Request) => Promise<Response> {
   const indexHtml = `${staticDir}/index.html`;
 
@@ -230,7 +235,21 @@ export function buildStaticFallback(
     if (!hostDispatch) return null;
     const url = new URL(req.url);
     const host = req.headers.get("host") ?? url.host;
-    const result = hostDispatch({ host, path: url.pathname, search: url.search });
+    const systemQuery: PageHeadSystemQuery = (type, payload, tenantId) => {
+      if (!hostDispatchDispatcher) {
+        throw new Error(
+          "hostDispatch called deps.systemQuery but buildStaticFallback got no hostDispatchDispatcher",
+        );
+      }
+      return requestContext.run(
+        requestContext.get() ?? buildRequestContextDataFromRequest(req),
+        () => hostDispatchDispatcher.query(type, payload, createAnonymousUser(tenantId)),
+      );
+    };
+    const result = await hostDispatch(
+      { host, path: url.pathname, search: url.search },
+      { systemQuery },
+    );
     if (result.kind === "not-found") {
       return new Response("Not Found", { status: 404 });
     }

package/src/run-prod-app.ts

@@ -72,6 +72,7 @@ import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
 import {
   createDefaultSseBroker,
   createRedisLoginRateLimiter,
+  type ExtraRouteDefinition,
   type LoginRateLimiter,
   loadJwtSecretOrKeyring,
   type SseBroker,
@@ -146,7 +147,7 @@ import { resolveBootCrypto } from "./boot/boot-crypto";
 import { jobRunLoggerCallbacks } from "./boot/job-run-logger";
 import { buildBunServeOptions } from "./bun-serve-options";
 import { buildComposeAuthOptions, composeFeatures } from "./compose-features";
-import { type ExtraRoutesSystemDeps, makeDispatchSystemWrite } from "./extra-routes-deps";
+import { makeDispatchSystemWrite, type SystemWireDeps } from "./extra-routes-deps";
 import { assertPiiBootInvariants } from "./pii-boot-gate";
 import {
   addConfigAccessorFactory,
@@ -425,14 +426,21 @@ export type HostDispatchResult =
   | { 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 inkl. führendem `?`, `""` wenn keiner. Redirects die
-   *  den Pfad auf einen anderen Host umbiegen (z.B. Auth-Routen mit
-   *  `?token=` aus alten Mail-Links) MÜSSEN ihn an `to` anhängen. */
-  readonly search: string;
-}) => HostDispatchResult;
+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
@@ -584,16 +592,18 @@ export type RunProdAppOptions = {
      *  späteren pgClient-Pass-through. */
     readonly pollIntervalMs?: number;
   };
-  /** Mount-Point für app-eigene HTTP-Routes außerhalb des Dispatcher-
-   *  Systems. Aufgerufen NACH /api/* + /health, VOR der static-fallback —
-   *  perfekt für GET-Endpoints die kein JSON liefern: /feed.xml,
-   *  /og-image, /sitemap.xml, /robots.txt-mit-Logik. Bekommt das raw
-   *  Hono-app + die Connection-Deps (db/redis) zum Querying.
-   *
-   *  Naming: `deps` statt `ctx` weil im Framework `ctx` der HandlerContext
-   *  mit user/tenant/registry ist — hier ist der Scope absichtlich kleiner
-   *  (Routes laufen außerhalb der Auth/Tenant-Pipeline). */
-  readonly extraRoutes?: (app: import("hono").Hono, deps: ExtraRoutesSystemDeps) => void;
+  /** 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
@@ -1065,6 +1075,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
     ...(options.observabilityOptions && { observabilityOptions: options.observabilityOptions }),
     ...(options.metrics && { metrics: options.metrics }),
     ...(options.rateLimit && { rateLimit: options.rateLimit }),
+    ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
     ...(effectiveAuth && {
       auth: {
         membershipQuery: TenantQueries.memberships,
@@ -1223,14 +1234,13 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // statt eines fixed JSON-Strings. Heute: registry-static, also OK.
   const appSchemaJson = JSON.stringify(buildAppSchema(registry, { searchAdapterMissing }));
 
-  // App-eigene HTTP-Routes mounten — VOR den Seeds (symmetrisch zum
-  // dev-server, siehe create-kumiko-server.ts). Ein Seed, der über den
-  // Dispatcher dispatcht, baut Honos Matcher; danach wirft jedes weitere
-  // app.get() "Can not add a route since the matcher is already built".
-  // Eingehende /api/*-Pfade sind schon vom dispatcher belegt; extraRoutes
-  // sollte die nicht überschreiben (kein enforce, das ist Author-Verantwortung).
-  if (options.extraRoutes) {
-    options.extraRoutes(entrypoint.app, {
+  // `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,
@@ -1296,6 +1306,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
           options.resolvePageHead
             ? { resolvePageHead: options.resolvePageHead, dispatcher: entrypoint.dispatcher }
             : undefined,
+          entrypoint.dispatcher,
         )
       : // No staticDir (split-deploy / API-only container) → app.fetch's
         // response goes straight to the client, bypassing buildStaticFallback

package/src/run-worker-app.ts

@@ -61,7 +61,7 @@ import Redis from "ioredis";
 import { resolveBootCrypto } from "./boot/boot-crypto";
 import { jobRunLoggerCallbacks } from "./boot/job-run-logger";
 import { composeFeatures } from "./compose-features";
-import { type ExtraRoutesSystemDeps, makeDispatchSystemWrite } from "./extra-routes-deps";
+import { makeDispatchSystemWrite, type SystemWireDeps } from "./extra-routes-deps";
 import { assertPiiBootInvariants } from "./pii-boot-gate";
 import { requireEnv } from "./run-prod-app";
 import { addConfigAccessorFactory, buildBootExtraContext } from "./run-prod-app-boot-context";
@@ -79,9 +79,9 @@ export type WorkerDeps = {
 /** Deps for the `wireComponents` hook — app-wired co-running components
  *  (an analysis runner, an IMAP supervisor, ...) that need the system-
  *  write dispatcher and register their own shutdown hooks on the worker
- *  lifecycle. Same deps shape as extraRoutes, plus `lifecycle` for
- *  `registerShutdownHook`. */
-export type WorkerWireDeps = ExtraRoutesSystemDeps & {
+ *  lifecycle. Same shape as the `wire` hook's SystemWireDeps, plus
+ *  `lifecycle` for `registerShutdownHook`. */
+export type WorkerWireDeps = SystemWireDeps & {
   readonly lifecycle: WorkerEntrypoint["lifecycle"];
 };