@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/api/server.js

@@ -0,0 +1,1068 @@
+import { Hono } from "hono";
+import { ROLES } from "../auth/roles.js";
+import { createDerivativesContext } from "../derivatives/derivatives-context.js";
+import { buildAppSchema } from "../engine/build-app-schema.js";
+import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names.js";
+import { projectAppSchemaForRoles } from "../engine/project-app-schema-for-roles.js";
+import { runsInLane } from "../engine/run-in.js";
+import { ANONYMOUS_ROLE, createAnonymousUser, createSystemUser } from "../engine/system-user.js";
+import { isFileField, } from "../engine/types/index.js";
+import { createFileContext } from "../files/file-handle.js";
+import { createFileRoutes, readFilesRouteOptions } from "../files/file-routes.js";
+import { makeFileProviderResolver } from "../files/provider-resolver.js";
+import { createFallbackLogger } from "../logging/index.js";
+import { createNoopProvider, DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig, registerStandardMetrics, wrapRedisClient, } from "../observability/index.js";
+import { resolveTenantLifecyclePlugin } from "../pipeline/active-membership.js";
+import { createDispatcher } from "../pipeline/dispatcher.js";
+import { SHARED_INSTANCE_SENTINEL } from "../pipeline/event-consumer-state.js";
+import { createEventDispatcher } from "../pipeline/event-dispatcher.js";
+import { createLifecycleHooks } from "../pipeline/lifecycle-pipeline.js";
+import { createMultiStreamApplyContext } from "../pipeline/multi-stream-apply-context.js";
+import { createAccessInvalidationEventConsumer, createJobTriggerEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, } from "../pipeline/system-hooks.js";
+import { authEndpointRateLimit, createRateLimitResolver, globalIpRateLimit, } from "../rate-limit/index.js";
+import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config.js";
+import { assertUnreachable, generateId } from "../utils/index.js";
+import { NO_ROUTE_MATCH_HEADER_NAME, PUBLIC_API_PATHS, Routes } from "./api-constants.js";
+import { authMiddleware, getAuthTokenExpiry, getUser, } from "./auth-middleware.js";
+import { createAuthRoutes } from "./auth-routes.js";
+import { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, } from "./client-ip.js";
+import { csrfMiddleware } from "./csrf-middleware.js";
+import { ExtraRouteEntries, ExtraRouteRejection, } from "./extra-route.js";
+import { computeStrongEtag, etagMatches } from "./http-cache.js";
+import { createJwtHelper } from "./jwt.js";
+import { observabilityMiddleware } from "./observability-middleware.js";
+import { assertOriginGuardConfig, isWebSocketOriginAllowed, normalizeOrigin, originMiddleware, rejectOrigin, } from "./origin-middleware.js";
+import { patRouteGuard } from "./pat-route-guard.js";
+import { piiCiphertextResponseGuard } from "./pii-leak-guard.js";
+import { createDefaultSseBroker } from "./redis-sse-broker.js";
+import { requestContext } from "./request-context.js";
+import { buildRequestContextData, requestIdMiddleware } from "./request-id-middleware.js";
+import { DEFAULT_MAX_REQUEST_BYTES, registerBodyLimit, registerHealthRoutes, registerMetricsRoute, registerVersionRoute, } from "./route-registrars.js";
+import { createApiRoutes } from "./routes.js";
+import { createSseRoute } from "./sse-route.js";
+import { buildWebSocketSessionRevalidator, createWebSocketConnectionLimiter, hasWebSocketUpgradeServer, isWebSocketUpgradeRequest, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_DEFAULT_MAX_MESSAGE_BYTES, } from "./websocket-route.js";
+// The per-tenant file-provider resolver, built once for a registry+context so
+// a job-runner and the server it runs beside share one instance (and one
+// per-tenant provider cache). Mirrors buildServer's own resolution exactly —
+// including NOT inventing a resolver when no `file-provider-*` plugin is
+// mounted, which is what keeps buildServer's boot-guard below able to fire.
+export function withFileProviderResolver(registry, context) {
+    if (context._fileProviderResolver !== undefined)
+        return context;
+    if (registry.getExtensionUsages(EXT_FILE_PROVIDER).length === 0)
+        return context;
+    return {
+        ...context,
+        _fileProviderResolver: makeFileProviderResolver({
+            registry,
+            _configAccessorFactory: context._configAccessorFactory,
+            secrets: context.secrets,
+            db: context.db,
+        }),
+    };
+}
+export function buildServer(options) {
+    // Single effective hop-count for every IP-derived rate-limit + requestMeta
+    // below — the top-level option wins over the deprecated
+    // `auth.trustedProxyHops` fallback.
+    const trustedProxyHops = options.trustedProxyHops ?? options.auth?.trustedProxyHops ?? 0;
+    assertValidTrustedProxyHops(trustedProxyHops, "buildServer");
+    // Exactly ONE resolver for the whole server — the warn-once flag must fire
+    // once per boot, not once per consumer (requestIdMiddleware, L1, L2,
+    // auth-routes each sharing this same instance rather than building a
+    // private one).
+    const clientIpResolver = createClientIpResolver(trustedProxyHops, "buildServer");
+    // File-storage is resolved per-tenant through file-foundation: a mounted
+    // `file-provider-*` plugin (inmemory/s3/s3-env) is the single source for
+    // uploads, ctx.files and the GDPR jobs.
+    const hasFileProvider = options.registry.getExtensionUsages(EXT_FILE_PROVIDER).length > 0;
+    // A test/advanced caller may inject the resolver directly on the context
+    // (e.g. a static in-memory provider) instead of mounting a provider plugin.
+    const hasInjectedResolver = options.context._fileProviderResolver !== undefined;
+    // Hard-fail when the registry declares file/image fields but no provider
+    // plugin is mounted — uploads would otherwise fail at the first request
+    // instead of at boot. Proves a plugin is mounted, not that each tenant
+    // selected one; per-tenant misconfig surfaces via createFileProviderForTenant.
+    if (registryDeclaresFileFields(options.registry) && !hasFileProvider && !hasInjectedResolver) {
+        throw new Error("Features declare file/image fields but no file-storage provider is mounted — " +
+            "mount `file-foundation` + a `file-provider-*` feature (inmemory/s3/s3-env) and " +
+            "select one per tenant via the 'file-foundation:config:provider' config-key.");
+    }
+    // #2051 — a screen whose search box renders (kumiko-screen.tsx gates it on
+    // `screen.searchable ?? entity-has-searchable-field`, the same condition
+    // used below) sends `payload.search` on every query. Without a
+    // context.searchAdapter that throws UnprocessableError at request time
+    // (#2032) — surface the misconfig at boot instead of on the first search.
+    // Warn, not throw: unlike missing file-storage (uploads always fail),
+    // list screens still work without search: only the search box is broken.
+    // Several deployed apps (offlot-app, publicstatus, kumiko-studio,
+    // kumiko-enterprise) currently run in exactly this state.
+    if (!options.context.searchAdapter) {
+        const unwiredEntities = entitiesWithSearchableScreen(options.registry);
+        if (unwiredEntities.length > 0) {
+            console.warn(`[kumiko:boot] ${unwiredEntities.length} entit${unwiredEntities.length === 1 ? "y" : "ies"} ` +
+                `have a searchable list screen but no SearchAdapter is wired on context.searchAdapter: ` +
+                `${unwiredEntities.join(", ")}. Search requests against ${unwiredEntities.length === 1 ? "it" : "them"} will fail with a 422 (search_adapter_not_wired) at runtime. ` +
+                "Wire a SearchAdapter (e.g. createMeilisearchAdapter) on context.searchAdapter, or remove `searchable: true` from the affected fields.");
+        }
+    }
+    // Stateless JWTs (no sessionChecker → no revocation) default to a shorter
+    // TTL than session-backed ones, since a leaked stateless token can't be
+    // revoked and stays valid until it expires. Explicit jwtTtl always wins.
+    const defaultJwtTtl = options.auth?.sessionChecker ? 8 * 60 * 60 : 60 * 60;
+    const jwt = createJwtHelper(options.jwtSecret, options.jwtIssuer, options.jwtTtl ?? defaultJwtTtl);
+    // An explicit ServerOptions.sseBroker always wins (caller owns its
+    // lifecycle) — createDefaultSseBroker is the single decision point every
+    // other caller must funnel through instead of picking a broker on its
+    // own, so the REDIS_URL-gated cross-replica default (fw#2625) can't be
+    // silently bypassed the way runProdApp bypassed it before this existed.
+    let sseBroker;
+    let ownedRedisSseBroker;
+    if (options.sseBroker) {
+        sseBroker = options.sseBroker;
+    }
+    else {
+        const defaults = createDefaultSseBroker();
+        sseBroker = defaults.sseBroker;
+        ownedRedisSseBroker = defaults.ownedRedisSseBroker;
+    }
+    // Resolve the per-process instance identifier. Prefer explicit
+    // ServerOptions.instanceId (tests, deliberate wiring), fall back to the
+    // deploy-env variable, finally a boot-time UUID. Validator rejects the
+    // sentinel — a deliberate collision attempt would silently merge this
+    // instance's per-instance cursors with the shared-row cursors and
+    // deliver events twice to one shard while starving the other.
+    const resolvedInstanceId = options.instanceId ?? process.env["KUMIKO_INSTANCE_ID"] ?? generateId();
+    if (resolvedInstanceId === SHARED_INSTANCE_SENTINEL) {
+        throw new Error(`ServerOptions.instanceId / KUMIKO_INSTANCE_ID cannot equal the reserved sentinel "${SHARED_INSTANCE_SENTINEL}" — ` +
+            `pick any other stable string.`);
+    }
+    // Warn when we fell back to a random UUID: the default SSE system-consumer
+    // is delivery="per-instance", so every boot gets a fresh cursor-row in
+    // kumiko_event_consumers. The previous boot's row stays behind on its last
+    // cursor and pins pruneEvents (retention-guard uses MIN(lastProcessedEventId)
+    // across all shards). Without a stable KUMIKO_INSTANCE_ID this accumulates
+    // on every restart, not just scale-down. Silent when options.instanceId or
+    // KUMIKO_INSTANCE_ID is explicit — those are deliberate choices (the test
+    // suite sets KUMIKO_INSTANCE_ID="test-instance" in vitest config).
+    const instanceIdWasRandom = options.instanceId === undefined && !process.env["KUMIKO_INSTANCE_ID"];
+    if (instanceIdWasRandom) {
+        console.warn(`[kumiko:boot] No ServerOptions.instanceId / KUMIKO_INSTANCE_ID set — generated a random UUID (${resolvedInstanceId}). ` +
+            `Per-instance consumers (SSE by default) write one cursor-row per instance; without a stable id, each restart leaves an orphaned row behind and pins events-retention on its last cursor. ` +
+            `Set KUMIKO_INSTANCE_ID to a stable value (e.g. hostname, pod name) in production.`);
+    }
+    // Observability — Noop by default so no call-site needs to null-check.
+    // Every handler/middleware that reaches for ctx.tracer / ctx.metrics gets
+    // a working, zero-cost fallback when no provider is configured.
+    const observability = options.observability ?? createNoopProvider();
+    // Register framework + feature metrics once on this meter. Standard
+    // metrics (HTTP, dispatcher, DB) are used by Auto-Instrumentation; feature
+    // metrics come from r.metric(...) declarations collected in the registry.
+    registerStandardMetrics(observability.meter);
+    for (const [name, def] of options.registry.getAllMetrics()) {
+        if (observability.meter.definitions().has(name))
+            continue;
+        observability.meter.registerMetric({
+            name,
+            type: def.type,
+            description: def.description,
+            labels: def.labels,
+            buckets: def.buckets,
+            unit: def.unit,
+            tenantLabel: def.tenantLabel,
+        });
+    }
+    // When a non-default provider is configured, wrap the injected Redis clients
+    // so `redis.cmd` spans attach to every command. For the default NoopProvider
+    // we skip the proxy to keep zero runtime overhead when observability is off.
+    const shouldWrapRedis = options.observability !== undefined;
+    const redisCtx = options.context.redis;
+    const wrappedRedis = shouldWrapRedis && redisCtx ? wrapRedisClient(redisCtx, observability.tracer) : redisCtx;
+    // Inject tracer + meter into the AppContext so the dispatcher can propagate
+    // them into every HandlerContext it builds. Build the per-tenant file-provider
+    // resolver once (when a provider plugin is mounted) — the dispatcher uses it
+    // to materialise `ctx.files`, the upload routes + MSP-applies share it. The
+    // resolver reads config + the s3.secretAccessKey secret under SYSTEM identity.
+    const contextWithFiles = withFileProviderResolver(options.registry, options.context);
+    const fileProviderResolver = contextWithFiles._fileProviderResolver;
+    // Auto-wire the rate-limit resolver, but ONLY when at least one
+    // handler actually declared a rateLimit option. Apps that don't use
+    // L3 pay zero cost: no resolver instance, no Lua-script registration
+    // on Redis, no AppContext field. Apps that wire L1/L2 middleware can
+    // pass `context.rateLimit` explicitly — that takes precedence over
+    // the auto-wire (e.g. middleware-only setup without any L3 handler).
+    // Auto-build the resolver when L3 handlers declared rateLimit OR when
+    // the caller asked for L1/L2 middleware. Either path needs a resolver;
+    // both share the same instance to avoid duplicate Lua-script registration.
+    const wantsL3 = options.registry.hasRateLimitedHandler();
+    const wantsL1L2 = options.rateLimit?.global !== undefined || options.rateLimit?.auth !== undefined;
+    const wantsResolver = wantsL3 || wantsL1L2;
+    const rateLimitResolver = options.context.rateLimit ??
+        (wrappedRedis && wantsResolver ? createRateLimitResolver({ redis: wrappedRedis }) : undefined);
+    const contextWithObservability = {
+        ...contextWithFiles,
+        ...(wrappedRedis ? { redis: wrappedRedis } : {}),
+        ...(rateLimitResolver ? { rateLimit: rateLimitResolver } : {}),
+        // Propagate the feature-toggle resolver to the context so the event-
+        // dispatcher (and any future context-reading consumer) sees the same
+        // source as the command dispatcher's handler-gate. Options take
+        // precedence over whatever was already on context — the
+        // dispatcher-options arg is the authoritative wire-up point.
+        ...(options.dispatcherOptions?.effectiveFeatures
+            ? { effectiveFeatures: options.dispatcherOptions.effectiveFeatures }
+            : {}),
+        tracer: observability.tracer,
+        meter: observability.meter,
+    };
+    const lifecycle = createLifecycleHooks(options.registry, options.systemHooks, options.eventDedup ? { eventDedup: options.eventDedup } : undefined);
+    const dispatcher = createDispatcher(options.registry, contextWithObservability, {
+        ...options.dispatcherOptions,
+        lifecycle,
+        sseBroker,
+        ...(options.auth ? { membershipQuery: options.auth.membershipQuery } : {}),
+    });
+    // Async event-dispatcher — the replacement for the old transactional
+    // outbox. Consumer sources:
+    //   1. System: SSE broadcast (iff sseBroker), Search index (iff
+    //      context.searchAdapter).
+    //   2. Features: every r.multiStreamProjection registered in the registry
+    //      becomes its own consumer row with an independent cursor. The MSP
+    //      apply map is routed by event.type; apply receives the raw DbRunner
+    //      of a TX-scoped, tenant-bound DB handle so per-tenant writes stay
+    //      isolated.
+    //
+    // The dispatcher is built but NOT started here. Production boot code
+    // must call `.start()`; test code typically calls `.runOnce()`.
+    // @cast-boundary engine-bridge — context.db union narrows to DbConnection here
+    const baseDb = contextWithObservability.db;
+    // @cast-boundary engine-bridge — searchAdapter is an optional context-extension
+    const searchAdapter = contextWithObservability
+        .searchAdapter;
+    // Adapter is built before the registry exists (app boot order) — hand it
+    // the registry-derived default config here so it can lazily configure
+    // each tenant index on first access instead of requiring per-tenant app
+    // wiring.
+    const derivedSearchConfig = searchAdapter
+        ? deriveSearchAdapterConfig(options.registry)
+        : undefined;
+    if (searchAdapter && derivedSearchConfig) {
+        searchAdapter.setDefaultConfig?.(derivedSearchConfig);
+    }
+    const sseConsumerEnabled = options.eventDispatcher?.systemConsumers?.sse ?? true;
+    const searchConsumerEnabled = options.eventDispatcher?.systemConsumers?.search ?? true;
+    const jobTriggerConsumerEnabled = options.eventDispatcher?.systemConsumers?.jobTrigger ?? true;
+    const jobRunnerForTriggers = options.dispatcherOptions?.jobRunner;
+    const systemConsumers = [];
+    if (sseConsumerEnabled) {
+        systemConsumers.push(createSseBroadcastEventConsumer(sseBroker));
+    }
+    if (searchConsumerEnabled && searchAdapter) {
+        systemConsumers.push(createSearchEventConsumer(searchAdapter, options.registry));
+    }
+    if (jobTriggerConsumerEnabled && jobRunnerForTriggers) {
+        systemConsumers.push(createJobTriggerEventConsumer(jobRunnerForTriggers, options.registry));
+    }
+    // Default ON (#1524 global-by-default). Tests that opt out of SSE via
+    // systemConsumers.accessInvalidation=false (test-stack mirrors sse off)
+    // skip the row so retention prune suites are not blocked by a lagging
+    // cursor=0 consumer they never drain.
+    const accessInvalidationEnabled = options.eventDispatcher?.systemConsumers?.accessInvalidation ?? true;
+    if (accessInvalidationEnabled) {
+        systemConsumers.push(createAccessInvalidationEventConsumer(sseBroker));
+    }
+    // MultiStreamProjections: one EventConsumer per MSP. Handler routes by
+    // event.type into the MSP's apply map. MSPs aggregate cross-aggregate but
+    // still within one tenant by default — the applier receives the plain
+    // baseDb DbRunner; tenant consistency comes from the triggering event's
+    // own tenantId, not a per-event TenantDb scope.
+    //
+    // Lane-filter (Welle 2.6.b): MSPs declare `runIn` to pin them to a
+    // deploy-lane. An MSP with `runIn: "api"` won't be wired into the
+    // worker-process dispatcher (and vice versa). `runIn: "both"` (or the
+    // legacy undefined default of "worker") runs wherever a dispatcher is
+    // started — SKIP LOCKED on the consumer-cursor handles the race between
+    // processes that both want the same event.
+    const processLane = options.processLane ?? "worker";
+    const mspDefs = [...options.registry.getAllMultiStreamProjections().values()].filter((msp) => runsInLane(msp.runIn, processLane));
+    const mspConsumers = mspDefs.map((msp) => ({
+        name: msp.name,
+        // Feature-toggle gating: carry the owning feature so the event-dispatcher
+        // can pause this consumer when the feature is globally disabled. Events
+        // queue up in the store and replay cleanly from the same cursor on resume.
+        ...(options.registry.getMultiStreamProjectionFeature(msp.name) && {
+            featureName: options.registry.getMultiStreamProjectionFeature(msp.name), // @cast-boundary engine-bridge
+        }),
+        // Copy the continuous-lifecycle error policy straight onto the consumer.
+        // Rebuild uses its own policy (rebuildProjection reads msp.errorMode.rebuild
+        // directly); steady-state delivery runs through this consumer.
+        ...(msp.errorMode?.continuous && { errorPolicy: msp.errorMode.continuous }),
+        // Carry the MSP's declared delivery semantic through to the consumer.
+        // Default (shared) is applied inside event-dispatcher, so omitting when
+        // the MSP didn't declare one keeps the existing behaviour.
+        ...(msp.delivery && { delivery: msp.delivery }),
+        // Carry the MSP's declared cursor-seed through to the consumer. Default
+        // (beginning) is applied inside insertConsumerIfAbsent.
+        ...(msp.startFrom && { startFrom: msp.startFrom }),
+        handler: async (event, ctx) => {
+            const applyFn = msp.apply[event.type];
+            // skip: this MSP doesn't care about this event type — fast path,
+            // every event type passes through every MSP consumer exactly once.
+            if (!applyFn)
+                return;
+            if (!baseDb) {
+                // skip: no baseDb wired — allConsumers.length > 0 + baseDb check
+                // above gates dispatcher creation, so we won't reach here in
+                // production. Defensive return for the type-narrowing path.
+                return;
+            }
+            // Saga/process-manager ctx: apply can call ctx.appendEvent to cascade
+            // a follow-up event onto another aggregate. Uses the triggering event's
+            // tenantId + userId so the causal chain stays tenant-consistent.
+            // MSP qualified names are "<feature>:projection:<short>" — the
+            // prefix before the first ":" owns the MSP. Used to reject
+            // cross-feature ctx.appendEvent calls at emit-site.
+            const mspOwner = msp.name.split(":")[0];
+            const mspFiles = fileProviderResolver
+                ? createFileContext(() => fileProviderResolver(event.tenantId))
+                : undefined;
+            const applyCtx = createMultiStreamApplyContext({
+                registry: options.registry,
+                db: baseDb,
+                tenantId: event.tenantId,
+                userId: event.metadata.userId,
+                ...(mspOwner && { callerFeature: mspOwner }),
+                ...(mspFiles && { files: mspFiles }),
+                ...(contextWithObservability.secrets && { secrets: contextWithObservability.secrets }),
+                ...(mspFiles && {
+                    derivatives: createDerivativesContext({
+                        files: mspFiles,
+                        registry: options.registry,
+                        db: baseDb,
+                        tenantId: event.tenantId,
+                    }),
+                }),
+            });
+            await applyFn(event, baseDb, applyCtx);
+            // Keep ctx reachable to satisfy the EventConsumerHandler signature.
+            void ctx;
+        },
+    }));
+    const allConsumers = [...systemConsumers, ...mspConsumers];
+    const { disabled: dispatcherDisabled, systemConsumers: _systemConsumersOpt, ...dispatcherTunables } = options.eventDispatcher ?? {};
+    let eventDispatcher;
+    if (allConsumers.length > 0 && baseDb && !dispatcherDisabled) {
+        eventDispatcher = createEventDispatcher({
+            db: baseDb,
+            consumers: allConsumers,
+            context: contextWithObservability,
+            tracer: observability.tracer,
+            meter: observability.meter,
+            instanceId: resolvedInstanceId,
+            ...dispatcherTunables,
+        });
+    }
+    // Wire the event-dispatcher shutdown into the lifecycle so the caller
+    // doesn't have to know the dispatcher exists. Hooks drain LIFO, so this
+    // runs before anything registered later by the caller (e.g. DB pool close).
+    if (options.lifecycle && eventDispatcher) {
+        const dispatcher = eventDispatcher;
+        options.lifecycle.registerShutdownHook("eventDispatcher", async () => {
+            await dispatcher.stop();
+        });
+    }
+    // Same reasoning, scoped to the broker this function created itself — an
+    // app-injected sseBroker (options.sseBroker) owns its own teardown.
+    if (options.lifecycle && ownedRedisSseBroker) {
+        const broker = ownedRedisSseBroker;
+        options.lifecycle.registerShutdownHook("redisSseBroker", async () => {
+            await broker.close();
+        });
+    }
+    const app = new Hono();
+    // Only entry:"signature" bypasses jwtGuard (verify() authenticates
+    // itself); entry:"anonymous" still needs the anonymousAccess fallthrough
+    // (tenant-by-host), entry:"user" needs c.get("user") populated.
+    const extraRoutePublicMatchers = compileExtraRoutePublicMatchers(options.extraRoutes);
+    const isExtraRoutePublicPath = (c) => extraRoutePublicMatchers.some((m) => m.method === c.req.method && m.pattern.test(c.req.path));
+    const sensitiveConfig = mergeSensitiveConfig(options.observabilityOptions?.sensitiveFilter ?? DEFAULT_SENSITIVE_CONFIG);
+    registerHealthRoutes(app, {
+        lifecycle: options.lifecycle,
+        readiness: {
+            db: baseDb,
+            redis: options.context.redis,
+            consumers: allConsumers,
+            ...(options.readiness ?? {}),
+        },
+    });
+    if (options.metrics) {
+        registerMetricsRoute(app, observability.meter, options.metrics);
+    }
+    app.use("/api/*", requestIdMiddleware({ resolver: clientIpResolver }));
+    // Cap JSON bodies before rate-limit/auth/observability even run. Header-
+    // check is O(1); oversized requests never allocate memory for a full body
+    // parse. Upload route keeps its own per-field maxSize.
+    registerBodyLimit(app, options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES);
+    // L1/L2 rate-limit middleware run BEFORE auth so an unauthenticated
+    // flood can't even reach the JWT-verify code path. Wired only when
+    // the caller passed `rateLimit.global` or `rateLimit.auth`. The
+    // resolver is the auto-wired one (or `context.rateLimit` if set);
+    // boot-fails loudly when the caller asked for middleware without a
+    // working Redis to back it.
+    if (wantsL1L2) {
+        if (!rateLimitResolver) {
+            throw new Error("rateLimit middleware requested but no resolver available — pass `context.redis` " +
+                "or `context.rateLimit` so the resolver can be built.");
+        }
+        if (options.rateLimit?.global) {
+            app.use("/api/*", globalIpRateLimit({
+                ...options.rateLimit.global,
+                resolver: rateLimitResolver,
+                clientIpResolver,
+            }));
+        }
+        if (options.rateLimit?.auth) {
+            const { path: l2Path = "/api/auth/*", ...l2Opts } = options.rateLimit.auth;
+            app.use(l2Path, authEndpointRateLimit({ ...l2Opts, resolver: rateLimitResolver, clientIpResolver }));
+        }
+    }
+    // Observability span wraps everything that follows (auth, routes).
+    // Must come AFTER request-id (so span can carry the id) and BEFORE auth
+    // (so auth-verify can be a child span once we instrument it in v2).
+    app.use("/api/*", observabilityMiddleware({
+        tracer: observability.tracer,
+        meter: observability.meter,
+        sensitiveConfig,
+    }));
+    // Tripwire: a kumiko-pii: ciphertext in a JSON response is always a bug
+    // (raw read leaked past a decrypt) — dev fails loud, prod redacts (#820).
+    app.use("/api/*", piiCiphertextResponseGuard());
+    // Auth middleware skips public paths (login, health) — those routes need
+    // to be callable without a valid JWT. Every other /api/* request requires
+    // a token (or, when anonymousAccess is wired, falls through as anonymous).
+    // A session-checker is forwarded when the auth-config wires one, so the
+    // middleware can reject revoked sids on every request.
+    // Mounting a tenantLifecycleStatus provider is what turns the 410 on, so no
+    // entrypoint can forget the wiring; `??` short-circuits, so an explicit
+    // auth.resolveTenantLifecycleStatus remains the override.
+    const tenantLifecycleResolver = options.auth?.resolveTenantLifecycleStatus ??
+        deriveTenantLifecycleResolver(options.registry, baseDb);
+    // sessionOnlyGuard deliberately does NOT get this — its callers have no
+    // anonymousAccess fallback, so a foreign-origin cookie there must keep
+    // failing through the sibling originMiddleware 403.
+    const normalizedForeignCookieOrigins = options.auth?.allowedOrigins?.length
+        ? new Set(options.auth.allowedOrigins.map(normalizeOrigin))
+        : undefined;
+    const jwtGuard = authMiddleware(jwt, {
+        ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
+        ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
+        ...(tenantLifecycleResolver ? { resolveTenantLifecycleStatus: tenantLifecycleResolver } : {}),
+        ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
+        ...(normalizedForeignCookieOrigins
+            ? { foreignCookieOrigins: normalizedForeignCookieOrigins }
+            : {}),
+    });
+    app.use("/api/*", async (c, next) => {
+        if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c))
+            return next();
+        return jwtGuard(c, next);
+    });
+    // Fail-closed PAT scoping: a PAT-authenticated caller (user.pat set by
+    // jwtGuard's tokenVerifier above) may only reach the dispatcher routes —
+    // everywhere else on /api/* is off-limits regardless of granted scopes.
+    const patRouteGuardMiddleware = patRouteGuard();
+    app.use("/api/*", async (c, next) => {
+        if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c))
+            return next();
+        return patRouteGuardMiddleware(c, next);
+    });
+    // Without anonymousAccess a missing token 401s instead of falling through as anonymous.
+    const sessionOnlyGuard = authMiddleware(jwt, {
+        ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
+        ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
+        ...(tenantLifecycleResolver ? { resolveTenantLifecycleStatus: tenantLifecycleResolver } : {}),
+    });
+    // PAT rate limiting — runs AFTER the auth guard so the resolved principal is
+    // available. Only PAT-authenticated requests are counted (keyed by token id);
+    // cookie/JWT users pass through untouched. In-memory limiter is per-instance
+    // (see run-prod-app) — a multi-node deployment wanting a shared counter swaps
+    // in a Redis-backed LoginRateLimiter.
+    const patRateLimiter = options.auth?.patRateLimiter;
+    const patRateLimitGuard = patRateLimiter ? buildPatRateLimitGuard(patRateLimiter) : undefined;
+    if (patRateLimitGuard) {
+        app.use("/api/*", async (c, next) => {
+            if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c))
+                return next();
+            return patRateLimitGuard(c, next);
+        });
+    }
+    // Origin-allowlist guard — additional CSRF-hardening for deployments that
+    // widen the auth cookie across subdomains (auth.cookieDomain). Registered
+    // only when allowedOrigins is non-empty, with the same /api/* + public-skip
+    // scope as the CSRF guard and BEFORE it, so a disallowed cross-site POST
+    // surfaces as `origin_not_allowed` rather than `csrf_token_mismatch`. Fails
+    // closed (assertOriginGuardConfig throws) when a wide cookieDomain is set
+    // without an allowlist and without an explicit opt-out — that config is the
+    // unguarded-subdomain-XSS footgun, not a warn-and-continue case.
+    assertOriginGuardConfig(options.auth);
+    const allowedOrigins = options.auth?.allowedOrigins;
+    const originGuard = allowedOrigins && allowedOrigins.length > 0 ? originMiddleware(allowedOrigins) : undefined;
+    if (originGuard) {
+        app.use("/api/*", async (c, next) => {
+            if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c))
+                return next();
+            return originGuard(c, next);
+        });
+    }
+    // Double-submit CSRF guard — runs only on cookie-authenticated,
+    // state-changing requests (POST/PUT/PATCH/DELETE). The guard reads the
+    // authTransport flag set by authMiddleware, so public paths (no auth)
+    // and bearer-authenticated paths (no cookie vector) fall straight
+    // through. Must be registered AFTER the auth middleware above so the
+    // flag is populated; registered for the same scope so /api/* routes
+    // are covered uniformly.
+    const csrfGuard = csrfMiddleware();
+    app.use("/api/*", async (c, next) => {
+        if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c))
+            return next();
+        return csrfGuard(c, next);
+    });
+    // Same order as /api/* above: auth → PAT route scope → PAT rate-limit → origin → CSRF.
+    const sessionOnlyHttpRouteGuards = [
+        sessionOnlyGuard,
+        patRouteGuardMiddleware,
+        ...(patRateLimitGuard ? [patRateLimitGuard] : []),
+        ...(originGuard ? [originGuard] : []),
+        csrfGuard,
+    ];
+    // Public auth routes (login) need to be registered BEFORE the generic
+    // api routes so Hono matches them first.
+    if (options.auth) {
+        // A membershipQuery handler is registered but nothing fulfils
+        // principalStatus — surface that misconfig at boot instead of an InternalError on first login/switch-tenant.
+        if (options.registry.getQueryHandler(options.auth.membershipQuery) &&
+            options.registry.getExtensionUsages(EXT_PRINCIPAL_STATUS).length === 0) {
+            throw new Error(`[kumiko] auth membershipQuery "${options.auth.membershipQuery}" is registered but no feature ` +
+                'provides the "principalStatus" contract — mount the user feature (tenant switch and sign-in ' +
+                "need it to reject blocked principals).");
+        }
+        app.route("/api", createAuthRoutes(dispatcher, jwt, { ...options.auth, resolver: clientIpResolver }));
+    }
+    app.route("/api", createApiRoutes(dispatcher, {
+        ...(options.sseHeartbeatMs !== undefined ? { sseHeartbeatMs: options.sseHeartbeatMs } : {}),
+    }));
+    app.route("/api", createSseRoute(sseBroker));
+    // GET /api/schema — the only way a client obtains the AppSchema. Behind
+    // jwtGuard (NON_PUBLIC_API_PATHS), so anonymousAccess's synthesised user
+    // also gets rejected below — the schema never reaches an unauthenticated
+    // caller. The FULL schema is built lazily once — the registry is
+    // immutable for this server's lifetime, so it's the same on every
+    // request — then projected per caller-role-set (fw#3314: a role only
+    // sees the screens/navs/workspaces/content-collections it may reach,
+    // not the whole app's schema) and cached per role key. Tenant is
+    // deliberately NOT part of the key: the projection depends only on
+    // roles, and per-tenant caching would grow unboundedly across tenants
+    // that share the same role set.
+    let fullSchema;
+    const projectedSchemaCache = new Map();
+    app.get(`/api${Routes.schema}`, (c) => {
+        const user = getUser(c);
+        if (isMissingOrAnonymousUser(user)) {
+            return unauthenticatedResponse(c);
+        }
+        const roleKey = JSON.stringify([...new Set(user?.roles ?? [])].sort());
+        let cached = projectedSchemaCache.get(roleKey);
+        if (cached === undefined) {
+            if (fullSchema === undefined) {
+                fullSchema = buildAppSchema(options.registry, {
+                    searchAdapterMissing: !options.context.searchAdapter,
+                });
+            }
+            const projected = projectAppSchemaForRoles(fullSchema, user?.roles ?? []);
+            const json = JSON.stringify(projected);
+            cached = { json, etag: computeStrongEtag(json) };
+            projectedSchemaCache.set(roleKey, cached);
+        }
+        const cacheHeaders = { "Cache-Control": "private, no-cache", ETag: cached.etag };
+        if (etagMatches(c.req.header("If-None-Match") ?? null, cached.etag)) {
+            return c.body(null, 304, cacheHeaders);
+        }
+        return c.body(cached.json, 200, {
+            "Content-Type": "application/json; charset=utf-8",
+            ...cacheHeaders,
+        });
+    });
+    // Mount upload/download routes whenever a file provider is resolvable (a
+    // file-provider plugin is mounted, or a resolver was injected). They resolve
+    // the provider per-tenant through file-foundation — no `files` option; route
+    // policy comes from createFilesFeature(opts?). Gating on the resolver (not on
+    // declared file fields) keeps unattached uploads working and matches the old
+    // "files option present → routes" behavior.
+    if (fileProviderResolver) {
+        const fileDb = options.context.db; // @cast-boundary engine-bridge
+        if (!fileDb)
+            throw new Error("file routes require db in context");
+        const routeOptions = readFilesRouteOptions(options.registry);
+        app.route("/api", createFileRoutes({
+            db: fileDb,
+            registry: options.registry,
+            resolveProvider: fileProviderResolver,
+            ...(routeOptions.accessGuard ? { accessGuard: routeOptions.accessGuard } : {}),
+            ...(routeOptions.privilegedRoles ? { privilegedRoles: routeOptions.privilegedRoles } : {}),
+            ...(routeOptions.maxUploadSize ? { maxUploadSize: routeOptions.maxUploadSize } : {}),
+        }));
+    }
+    // Feature-deklarierte HTTP-Routes (r.httpRoute). Mount nach /api/* damit
+    // /api/* immer Vorrang hat — feature-Routes liegen ohnehin außerhalb
+    // (Boot-Validator blockt /api-Prefix). deps.app ist die Outer-App, sodass
+    // der Handler /api/query intern via app.fetch(...) nutzen kann (gleicher
+    // Auth-Pfad wie ein echter HTTP-Call). deps.systemQuery umgeht diesen
+    // Pfad bewusst — für Routes die einen FESTEN Tenant erzwingen müssen
+    // (z.B. legal-pages → immer SYSTEM_TENANT_ID), statt ihn per X-Tenant-
+    // Header vorzutäuschen (das sieht für die anonymousAccess-Auflösung
+    // wie ein normaler Client-Header aus und wird von resolverTrust:
+    // "authoritative"-Configs zurecht als Tenant-Override abgelehnt).
+    for (const feature of options.registry.features.values()) {
+        for (const route of Object.values(feature.httpRoutes)) {
+            // @wrapper-known semantic-alias
+            const honoHandler = async (c) => route.handler(c, {
+                app,
+                // createAnonymousUser, NOT createSystemUser: systemQuery's
+                // synthesized user must clear the SAME access gate a real
+                // anonymous visitor would, no more — regardless of the route's
+                // own `anonymous` mode. The system role would ALSO satisfy that
+                // gate here, but it can read fields gated to "system" that
+                // "anonymous" can't (filterReadFields is a plain role-in-map
+                // check) — a systemQuery caller reading a system-gated field
+                // would leak it into the response. The forced tenant already
+                // comes from bypassing the HTTP layer entirely; no elevated
+                // role is needed or wanted on top of that.
+                systemQuery: makeSystemQuery(c, dispatcher, clientIpResolver),
+                clientIp: clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
+            });
+            mountHonoRoute(app, route.method, route.path, honoHandler, route.anonymous ? [] : sessionOnlyHttpRouteGuards);
+        }
+    }
+    // r.webSocketRoute — GET routes under /api/ws/*, so the jwt/pat/rate-limit
+    // chain above already ran. Origin/CSRF guards skip GETs, hence the own check.
+    const webSocketOriginAllowlist = allowedOrigins?.length
+        ? new Set(allowedOrigins.map(normalizeOrigin))
+        : undefined;
+    const webSocketRoutePaths = new Map();
+    const webSocketConnectionLimiter = createWebSocketConnectionLimiter();
+    for (const feature of options.registry.features.values()) {
+        for (const route of Object.values(feature.webSocketRoutes)) {
+            const owner = webSocketRoutePaths.get(route.path);
+            if (owner !== undefined) {
+                throw new Error(`[kumiko] WebSocket route "${route.path}" is declared by both feature "${owner}" and ` +
+                    `"${feature.name}" — paths must be unique across features.`);
+            }
+            webSocketRoutePaths.set(route.path, feature.name);
+            app.get(route.path, buildWebSocketRouteHandler(route, {
+                dispatcher,
+                clientIpResolver,
+                originAllowlist: webSocketOriginAllowlist,
+                ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
+                ...(tenantLifecycleResolver
+                    ? { resolveTenantLifecycleStatus: tenantLifecycleResolver }
+                    : {}),
+                connectionLimiter: webSocketConnectionLimiter,
+            }));
+        }
+    }
+    // extraRoutes (kumiko-framework#3050) — declarative HTTP-routes with a
+    // Pflicht `entry` tier. Mounted after r.httpRoute for the same reason: an
+    // extraRoute dispatching through `dispatcher` builds Hono's matcher, so
+    // this must run before any seed that also dispatches (runProdApp/
+    // createKumikoServer call buildServer before seeding).
+    if (options.extraRoutes) {
+        // Boot-time validation for the whole list BEFORE mounting anything —
+        // an app with one bad route should fail loud at boot, not mount N-1
+        // routes and then throw on route N.
+        for (const route of options.extraRoutes) {
+            if (!isKnownExtraRouteEntry(route.entry)) {
+                throw new Error(`[kumiko] extraRoutes: unknown entry "${String(route.entry)}" on ` +
+                    `"${route.method} ${route.path}" — expected "anonymous" | "user" | "signature". ` +
+                    "A JS caller without the ExtraRouteDefinition type can hit this at boot.");
+            }
+            if (route.entry === ExtraRouteEntries.user && !route.path.startsWith("/api/")) {
+                throw new Error(`[kumiko] extraRoutes: entry:"user" route "${route.method} ${route.path}" must be ` +
+                    "mounted under \"/api/\" — that's the only path prefix that rides the framework's " +
+                    "jwtGuard chain, which is what populates deps.user.");
+            }
+            // A signature route under /api/ skips jwtGuard/origin/csrf for every
+            // path its pattern matches — a wildcard would switch off auth for
+            // unrelated /api/* handlers (e.g. "/api/*" swallows /api/write).
+            if (route.entry === ExtraRouteEntries.signature &&
+                route.path.startsWith("/api/") &&
+                route.path.includes("*")) {
+                throw new Error(`[kumiko] extraRoutes: entry:"signature" route "${route.method} ${route.path}" must not ` +
+                    'use a wildcard under "/api/" — it would bypass the auth chain for every matching path.');
+            }
+        }
+        const dispatchSystemWrite = makeDispatchSystemWrite(dispatcher);
+        const dispatchSystemQuery = makeDispatchSystemQuery(dispatcher);
+        for (const route of options.extraRoutes) {
+            const honoHandler = buildExtraRouteHonoHandler(route, {
+                app,
+                dispatcher,
+                registry: options.registry,
+                secrets: contextWithObservability.secrets,
+                dispatchSystemWrite,
+                dispatchSystemQuery,
+                clientIpResolver,
+            });
+            mountHonoRoute(app, route.method, route.path, honoHandler);
+        }
+    }
+    // /version-Default registriert NACH feature-routes — Hono "first match
+    // wins", also gewinnt feature-deklariertes /version (z.B. App-spezifisches
+    // version-format mit Tenant-Stats) wenn vorhanden, sonst greift der
+    // Default-Handler aus BUILD_VERSION/BUILD_TIME-env-vars.
+    registerVersionRoute(app);
+    // Marks "no route matched this path" so tryHonoFirst (server-runtime)
+    // can tell it apart from a matched route's OWN deliberate 404 (e.g.
+    // default-deny reads like file-derivatives' public-variant route) —
+    // without this, tryHonoFirst's only signal was the status code, and a
+    // matched route answering 404 got silently rewritten to the SPA shell
+    // with status 200 (kumiko-framework#2435). Must be the LAST thing wired
+    // on `app`: this only fires when the router found no handler at all, so
+    // a route's own `c.text(..., 404)` never passes through here. A handler
+    // that calls `c.notFound()` instead of building its own Response DOES
+    // route through this same handler and stays indistinguishable from a
+    // routing miss — pre-existing Hono semantics, not something this fix
+    // changes; deliberate 404s must build their own Response.
+    // The header is an internal signal only — tryHonoFirst and every direct
+    // app.fetch() passthrough strip it before a response reaches a client.
+    app.notFound((c) => c.text("Not Found", 404, { [NO_ROUTE_MATCH_HEADER_NAME]: "1" }));
+    return {
+        app,
+        jwt,
+        sseBroker,
+        observability,
+        dispatcher,
+        context: contextWithObservability,
+        ...(eventDispatcher ? { eventDispatcher } : {}),
+        ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
+    };
+}
+// Method-switch shared by r.httpRoute and extraRoutes — one place to keep
+// the two mounting paths from drifting on which Hono methods get a
+// convenience-call vs. app.on().
+function mountHonoRoute(app, method, path, 
+// biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+handler, middlewares = []) {
+    // Guards go into the route's own handler chain, never a method-gated
+    // app.use: Hono serves HEAD through the GET route with c.req.method still
+    // "HEAD", so a `method === c.req.method` gate would skip them for HEAD.
+    if (middlewares.length > 0) {
+        // [path]: only Hono's array-path overload accepts a variable-length handler spread.
+        app.on(method, [path], ...middlewares, handler);
+        // skip: guarded route already mounted with its guard chain
+        return;
+    }
+    switch (method) {
+        case "GET":
+            app.get(path, handler);
+            break;
+        case "POST":
+            app.post(path, handler);
+            break;
+        case "PUT":
+            app.put(path, handler);
+            break;
+        case "PATCH":
+            app.patch(path, handler);
+            break;
+        case "DELETE":
+            app.delete(path, handler);
+            break;
+        case "OPTIONS":
+        case "HEAD":
+            // Hono's on() for the methods without a convenience method.
+            app.on(method, path, handler);
+            break;
+        default:
+            assertUnreachable(method, "http method");
+    }
+}
+// Must run after the auth guard so getUser(c) carries the PAT.
+function buildPatRateLimitGuard(patRateLimiter) {
+    return async (c, next) => {
+        const pat = getUser(c)?.pat;
+        if (pat && !(await patRateLimiter.check(pat.tokenId))) {
+            return c.json({
+                error: {
+                    code: "pat_rate_limited",
+                    httpStatus: 429,
+                    message: "personal access token rate limit exceeded",
+                    i18nKey: "auth.errors.patRateLimited",
+                },
+            }, 429);
+        }
+        return next();
+    };
+}
+// Shared systemQuery builder for r.httpRoute and extraRoutes (anonymous +
+// signature entries). requestContext.run must wrap the dispatcher call —
+// both route kinds run outside the requestIdMiddleware chain that normally
+// populates it, and `rateLimit: {per: "ip", ...}` on a handler invoked
+// through systemQuery is otherwise silent dead-code (enforceRateLimit reads
+// requestContext.get()?.ip, undefined without this wrap).
+function makeSystemQuery(
+// biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+c, dispatcher, clientIpResolver) {
+    return (type, payload, tenantId) => requestContext.run(requestContext.get() ?? buildRequestContextData(c, clientIpResolver), () => dispatcher.query(type, payload, createAnonymousUser(tenantId)));
+}
+// SystemAdmin write/query builders shared by buildServer's `extraRoutes`
+// mount and server-runtime's `wire` hook (runProdApp/createKumikoServer,
+// after buildServer). Privilege-scope: SystemAdmin is the highest
+// non-tenant-scoped role — reaches ANY SystemAdmin-gated handler on ANY
+// tenant. Only safe for callers that already proved their own authenticity
+// (signature verify(), HMAC state, ...), never exposed to a raw request.
+export function makeDispatchSystemWrite(dispatcher) {
+    return ({ handlerQn, payload, tenantId }) => dispatcher.write(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
+}
+export function makeDispatchSystemQuery(dispatcher) {
+    return ({ handlerQn, payload, tenantId }) => dispatcher.query(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
+}
+// Same dispatcher.write(...) as entry:"user", but the user is getUser(c) —
+// see AnonymousExtraRouteDeps.write for the privilege/tenant contract.
+function makeAnonymousWrite(
+// biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+c, dispatcher) {
+    return (type, payload) => {
+        const user = getUser(c);
+        if (!user) {
+            throw new Error('[kumiko] extraRoutes: entry:"anonymous" deps.write requires this route to be mounted ' +
+                'under "/api/" with anonymousAccess wired — no request-resolved session user was found.');
+        }
+        return dispatcher.write(type, payload, user);
+    };
+}
+// Shared by entry:"user" extra routes and GET /api/schema — both require a
+// real, signed-in principal and reject the synthesised anonymousAccess user
+// (SessionUser.roles includes ANONYMOUS_ROLE) the same way.
+function isMissingOrAnonymousUser(user) {
+    return !user || user.roles.includes(ANONYMOUS_ROLE);
+}
+function unauthenticatedResponse(c) {
+    return c.json({
+        error: {
+            code: "unauthenticated",
+            httpStatus: 401,
+            message: "this route requires a signed-in user",
+            i18nKey: "auth.errors.missingToken",
+        },
+    }, 401);
+}
+const webSocketLog = createFallbackLogger("websocket");
+function webSocketErrorResponse(c, status, code, message) {
+    return c.json({ error: { code, httpStatus: status, message } }, status);
+}
+function buildWebSocketRouteHandler(route, shared) {
+    return async (c) => {
+        if (!isWebSocketOriginAllowed(c, shared.originAllowlist))
+            return rejectOrigin(c);
+        const user = getUser(c);
+        if (isMissingOrAnonymousUser(user))
+            return unauthenticatedResponse(c);
+        if (!isWebSocketUpgradeRequest(c.req.raw)) {
+            return webSocketErrorResponse(c, 426, "websocket_upgrade_required", "this route only accepts WebSocket upgrade requests");
+        }
+        const honoEnv = c.env;
+        if (!hasWebSocketUpgradeServer(honoEnv)) {
+            const message = "webSocketUpgradeFetch not wired: pass it to buildBunServeOptions";
+            webSocketLog.error(message, { path: route.path });
+            return webSocketErrorResponse(c, 501, "websocket_upgrade_not_wired", message);
+        }
+        // The slot is taken before connect (a refused attempt must not run it) and stays synchronous with
+        // the check, so concurrent upgrades can't overshoot the cap. Every path without a live socket frees it.
+        const releaseConnectionSlot = shared.connectionLimiter.tryAcquire(`${route.path}\n${user.tenantId}\n${user.id}`, route.maxConnectionsPerUser ?? WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER);
+        if (!releaseConnectionSlot) {
+            return webSocketErrorResponse(c, 429, "websocket_connection_limit", "too many open WebSocket connections for this user");
+        }
+        let upgraded = false;
+        try {
+            const handlers = await route.connect(c, {
+                user,
+                query: (type, payload) => shared.dispatcher.query(type, payload, user),
+                write: (type, payload) => shared.dispatcher.write(type, payload, user),
+                clientIp: shared.clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
+            });
+            if (handlers instanceof Response)
+                return handlers;
+            const captured = requestContext.get();
+            const requestContextData = captured ? withoutAbortSignal(captured) : undefined;
+            const revalidateSession = buildWebSocketSessionRevalidator({
+                user,
+                sessionChecker: shared.sessionChecker,
+                resolveTenantLifecycleStatus: shared.resolveTenantLifecycleStatus,
+                tokenExpiresAtSec: getAuthTokenExpiry(c),
+            });
+            upgraded = honoEnv.server.upgrade(c.req.raw, {
+                data: {
+                    handlers,
+                    maxMessageBytes: route.maxMessageBytes ?? WEBSOCKET_DEFAULT_MAX_MESSAGE_BYTES,
+                    requestContextData,
+                    revalidateSession,
+                    releaseConnectionSlot,
+                },
+            });
+            if (!upgraded) {
+                return webSocketErrorResponse(c, 400, "websocket_upgrade_failed", "the WebSocket upgrade was rejected");
+            }
+            // Bun ignores the returned Response after a successful upgrade.
+            return new Response(null);
+        }
+        finally {
+            if (!upgraded)
+                releaseConnectionSlot();
+        }
+    };
+}
+// The request's AbortSignal fires when the upgrade request ends, which would
+// abort every later handler running under the captured context.
+function withoutAbortSignal(data) {
+    const { signal: _signal, ...rest } = data;
+    return rest;
+}
+function isKnownExtraRouteEntry(entry) {
+    return (entry === ExtraRouteEntries.anonymous ||
+        entry === ExtraRouteEntries.user ||
+        entry === ExtraRouteEntries.signature);
+}
+// Hono path pattern ("/api/foo/:bar", "/api/foo/*") → RegExp. Only the
+// subset extraRoutes actually uses (static segments, `:param`, trailing
+// `*`) — no inline `:param{regex}` constraints, no optional `:param?`.
+function honoPathToRegex(path) {
+    const segments = path
+        .split("/")
+        .map((segment) => {
+        if (segment.startsWith(":"))
+            return "[^/]+";
+        if (segment === "*")
+            return ".*";
+        return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    })
+        .join("/");
+    return new RegExp(`^${segments}$`);
+}
+// See the bypass comment at the jwtGuard mount above — only signature
+// routes are public here.
+function compileExtraRoutePublicMatchers(extraRoutes) {
+    if (!extraRoutes)
+        return [];
+    return extraRoutes
+        .filter((route) => route.entry === ExtraRouteEntries.signature)
+        .map((route) => ({ method: route.method, pattern: honoPathToRegex(route.path) }));
+}
+function buildExtraRouteHonoHandler(route, shared) {
+    switch (route.entry) {
+        case ExtraRouteEntries.anonymous:
+            return async (c) => route.handler(c, {
+                app: shared.app,
+                registry: shared.registry,
+                systemQuery: makeSystemQuery(c, shared.dispatcher, shared.clientIpResolver),
+                write: makeAnonymousWrite(c, shared.dispatcher),
+                clientIp: shared.clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
+            });
+        case ExtraRouteEntries.user:
+            return async (c) => {
+                const user = getUser(c);
+                if (isMissingOrAnonymousUser(user)) {
+                    return unauthenticatedResponse(c);
+                }
+                return route.handler(c, {
+                    app: shared.app,
+                    registry: shared.registry,
+                    user,
+                    query: (type, payload) => shared.dispatcher.query(type, payload, user),
+                    write: (type, payload) => shared.dispatcher.write(type, payload, user),
+                });
+            };
+        case ExtraRouteEntries.signature:
+            return async (c) => {
+                const rawBody = await c.req.text();
+                const headers = {};
+                c.req.raw.headers.forEach((value, key) => {
+                    headers[key.toLowerCase()] = value;
+                });
+                let verified;
+                try {
+                    verified = await route.verify({ rawBody, headers, params: c.req.param(), query: c.req.query() }, { registry: shared.registry, secrets: shared.secrets });
+                }
+                catch (e) {
+                    if (e instanceof ExtraRouteRejection) {
+                        if (e.retryAfterSeconds !== undefined) {
+                            return c.json(e.body, e.status, { "Retry-After": String(e.retryAfterSeconds) });
+                        }
+                        return c.json(e.body, e.status);
+                    }
+                    return c.json({
+                        error: {
+                            code: "extra_route_signature_invalid",
+                            message: e instanceof Error ? e.message : String(e),
+                        },
+                    }, 401);
+                }
+                return route.handler(c, verified, {
+                    app: shared.app,
+                    registry: shared.registry,
+                    secrets: shared.secrets,
+                    systemQuery: makeSystemQuery(c, shared.dispatcher, shared.clientIpResolver),
+                    dispatchSystemWrite: shared.dispatchSystemWrite,
+                    dispatchSystemQuery: shared.dispatchSystemQuery,
+                });
+            };
+        default:
+            return assertUnreachable(route, "extra route entry");
+    }
+}
+function deriveTenantLifecycleResolver(registry, db) {
+    const plugin = resolveTenantLifecyclePlugin(registry, "buildServer");
+    if (!plugin)
+        return undefined;
+    if (!db) {
+        throw new Error("[kumiko] a tenantLifecycleStatus provider is mounted (tenant-lifecycle) but context.db is " +
+            "missing — the request-level teardown gate needs a DbConnection. Pass context.db, or wire " +
+            "auth.resolveTenantLifecycleStatus explicitly.");
+    }
+    return (tenantId) => plugin.resolveStatus(tenantId, { db });
+}
+// Scans every feature's entities for a file/image/files/images field. Short-
+// circuits on the first hit — no need to build a full inventory, we only want
+// the yes/no answer for the boot check.
+function registryDeclaresFileFields(registry) {
+    for (const feature of registry.features.values()) {
+        for (const entity of Object.values(feature.entities ?? {})) {
+            for (const field of Object.values(entity.fields)) {
+                if (isFileField(field))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+// Entities whose entityList screen WOULD render a search box based on
+// screen/field config alone: `screen.searchable` wins when set, otherwise
+// the box shows iff the entity has ≥1 searchable field. `screen.searchable
+// === false` is excluded — the boot-validator (entity-list-screens.ts) only
+// allows that on the whitelisted download-attempt-list-style screens, which
+// never render the box. This is the config-only half of the rule; the
+// client additionally gates on FeatureSchema.searchAdapterMissing (#2062,
+// set from the same `!options.context.searchAdapter` check below) so the
+// box is actually suppressed once this function finds a hit.
+function entitiesWithSearchableScreen(registry) {
+    const entities = new Set();
+    for (const feature of registry.features.values()) {
+        for (const screen of Object.values(feature.screens)) {
+            if (screen.type !== "entityList")
+                continue;
+            const isSearchable = screen.searchable === true ||
+                (screen.searchable === undefined && registry.getSearchableFields(screen.entity).length > 0);
+            if (isSearchable)
+                entities.add(screen.entity);
+        }
+    }
+    return [...entities];
+}