@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/api/server.js

@@ -1,1262 +1,60 @@
 import { Hono } from "hono";
-import { ROLES } from "../auth/roles.js";
-import { createProjectingTenantDb, withExecutorManagedWrites } from "../db/tenant-db.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 { resolveDisabledFeatureNames, stripDisabledFeaturesFromAppSchema, } from "../engine/strip-disabled-features-from-app-schema.js";
-import { createAnonymousUser, createSystemUser, isAnonymousSessionUser, } from "../engine/system-user.js";
-import { isFileField, } from "../engine/types/index.js";
-import { assertSeedModeNotInProduction } from "../event-store/seed-clock.js";
-import { createTenantFileContext } from "../files/file-handle.js";
-import { createFileRoutes, readFilesRouteOptions } from "../files/file-routes.js";
-import { makeFileProviderResolver } from "../files/provider-resolver.js";
-import { createRecordReadCheck } from "../files/record-read-check.js";
-import { createRecordWriteCheck } from "../files/record-write-check.js";
-import { createFallbackLogger } from "../logging/index.js";
-import { createNoopProvider, registerStandardMetrics, wrapRedisClient, } from "../observability/index.js";
-import { resolveTenantLifecyclePlugin } from "../pipeline/active-membership.js";
-import { configAccessorFactoryOf } from "../pipeline/config-accessor-factory.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, createPayloadDigest, createRateLimitResolver, globalIpRateLimit, httpRouteRateLimit, } from "../rate-limit/index.js";
-import { resolveCacheSyncBus } from "../redis/cache-sync-bus.js";
-import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config.js";
-import { assertUnreachable, generateId } from "../utils/index.js";
-import { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
-import { NO_ROUTE_MATCH_HEADER_NAME, NON_PUBLIC_API_PATHS, PUBLIC_API_PATHS, Routes, } from "./api-constants.js";
-import { authMiddleware, getAuthTokenExpiry, getUser, identifyOptionalSession, } from "./auth-middleware.js";
-import { assertSessionCallbacksPaired, createAuthRoutes, } from "./auth-routes.js";
-import { createClientErrorRoute } from "./client-error-route.js";
-import { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, } from "./client-ip.js";
-import { csrfMiddleware } from "./csrf-middleware.js";
-import { collectEntityReadAccess } from "./entity-read-access.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, rejectOrigin, resolveOriginGuard, } 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 { bodyLimitForRoutePath, DEFAULT_MAX_REQUEST_BYTES, registerBodyLimit, registerHealthRoutes, registerMetricsRoute, registerVersionRoute, } from "./route-registrars.js";
-import { createApiRoutes, handleUncaughtRouteError } from "./routes.js";
-import { resolveSessionCookies, sessionCookiesMiddleware } from "./session-cookies.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, cacheSync) {
-    if (context._fileProviderResolver !== undefined)
-        return context;
-    if (registry.getExtensionUsages(EXT_FILE_PROVIDER).length === 0)
-        return context;
-    return {
-        ...context,
-        _fileProviderResolver: makeFileProviderResolver({
-            registry,
-            _configAccessorFactory: configAccessorFactoryOf(context),
-            secrets: context.secrets,
-            db: context.db,
-            ...(cacheSync ? { cacheSync } : {}),
-        }),
-    };
-}
-// A payload-bucket handler without a resolver would answer every call with a
-// 500 at request time; fail at boot instead.
-function assertNoPayloadRateLimitsWithoutResolver(registry) {
-    const offenders = [];
-    for (const feature of registry.features.values()) {
-        for (const [name, handler] of Object.entries(feature.writeHandlers)) {
-            if (handler.additionalRateLimits !== undefined) {
-                offenders.push(`${feature.name}:write:${name}`);
-            }
-        }
-    }
-    // skip: every handler's payload buckets are covered by the resolver
-    if (offenders.length === 0)
-        return;
-    throw new Error(`Handlers declare additionalRateLimits but no RateLimitResolver is configured: ${offenders.join(", ")}. ` +
-        "Wire a Redis client on context.redis (or pass context.rateLimit), or drop the payload buckets " +
-        "(for the waitlist: emailRateLimits: []).");
-}
+import { DEFAULT_MAX_REQUEST_BYTES, registerBodyLimit, registerVersionRoute, } from "./route-registrars.js";
+import { handleUncaughtRouteError } from "./routes.js";
+import { compilePublicApiRequestMatcher, mountExtraRoutes } from "./server-extra-routes.js";
+import { installAuthGuardChain, installObservability, installPiiLeakGuard, installRateLimitMiddleware, installRequestId, installSessionCookies, } from "./server-middleware.js";
+import { installNoRouteMatchMarker, mountAuthRoutes, mountClientErrorRoute, mountDispatcherRoutes, mountFeatureHttpRoutes, mountFileRoutes, mountOperationalRoutes, mountSchemaRoute, } from "./server-routes.js";
+import { mountWebSocketRoutes } from "./server-websocket-routes.js";
+import { resolveServerWiring } from "./server-wiring.js";
 export function buildServer(options) {
-    assertSeedModeNotInProduction();
-    // 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;
-        if (!ownedRedisSseBroker) {
-            console.warn("[kumiko:boot] REDIS_URL is not set: cross-replica fanout disabled. SSE, access-invalidation and toggle-sync reach only the cursor-owning process, so with more than one replica clients on the other replicas miss events and revoked sessions stay open there.");
-        }
-    }
-    // Same decision as the SSE broker: an explicit dispatcherOptions value
-    // (incl. null = opt out) wins, otherwise REDIS_URL turns on cross-replica
-    // cache invalidation (no REDIS_URL = process-local bus).
-    const { bus: cacheSync, owned: ownedCacheSync } = resolveCacheSyncBus(options.dispatcherOptions?.cacheSync);
-    // 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 built-in SSE consumer is
-    // delivery="shared" (one cursor for all pods, fw#2625), so it no longer
-    // writes a row per instance. The id still labels this process in the
-    // app.started event and in per-instance consumers (opt-in delivery), where a
-    // fresh id per boot leaves an orphaned cursor-row that pins pruneEvents
-    // (retention-guard uses MIN(lastProcessedEventId) across all shards). Silent
-    // when options.instanceId or KUMIKO_INSTANCE_ID is explicit — those are
-    // deliberate choices (the test suite sets KUMIKO_INSTANCE_ID="test-instance").
-    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}). ` +
-            `SSE no longer needs a per-instance cursor, but the id labels this process in the app.started event and in per-instance consumers; without a stable id each restart leaves an orphaned cursor-row behind for those and pins events-retention on its last cursor. ` +
-            `Set KUMIKO_INSTANCE_ID to the pod name (e.g. from the Kubernetes downward API metadata.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, cacheSync);
-    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 wantsHttpRouteLimit = [...options.registry.features.values()].some((feature) => Object.values(feature.httpRoutes).some((route) => route.rateLimit !== undefined));
-    const wantsResolver = wantsL3 || wantsL1L2 || wantsHttpRouteLimit;
-    // Master for the payload-bucket HMAC: the current signing secret (the
-    // keyring's signKid for rotation setups). buildServer always has one, so
-    // the digest is available whenever a handler declares additionalRateLimits.
-    const payloadDigest = createPayloadDigest(payloadDigestMasterSecret(options.jwtSecret));
-    const rateLimitResolver = options.context.rateLimit ??
-        (wrappedRedis && wantsResolver ? createRateLimitResolver({ redis: wrappedRedis }) : undefined);
-    if (!rateLimitResolver) {
-        assertNoPayloadRateLimitsWithoutResolver(options.registry);
-        // The systemScope default limit only exists once a resolver does, and an app that
-        // declared no explicit rateLimit anywhere never gets one auto-wired (wantsL3 stays
-        // false) — so its cross-tenant handlers are silently unlimited.
-        const unlimitedSystemScopeFeatures = [...options.registry.features.values()]
-            .filter((feature) => feature.systemScope &&
-            Object.keys(feature.writeHandlers).length + Object.keys(feature.queryHandlers).length > 0)
-            .map((feature) => feature.name);
-        if (unlimitedSystemScopeFeatures.length > 0) {
-            console.warn(`[kumiko:boot] r.systemScope() features have handlers but no RateLimitResolver is configured, ` +
-                `so their default rate limit is not enforced: ${unlimitedSystemScopeFeatures.join(", ")}. ` +
-                "Wire a Redis client on context.redis and declare rateLimit on at least one handler (or pass " +
-                "context.rateLimit) to enable the resolver.");
-        }
-    }
-    const contextWithObservability = {
-        ...contextWithFiles,
-        ...(wrappedRedis ? { redis: wrappedRedis } : {}),
-        ...(rateLimitResolver ? { rateLimit: rateLimitResolver } : {}),
-        _rateLimitPayloadDigest: payloadDigest,
-        ...(cacheSync ? { cacheSync } : {}),
-        // 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,
-        cacheSync: cacheSync ?? null,
-        ...(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 mspJobs = jobRunnerForTriggers?.dispatch
-        ? {
-            dispatch: async (jobName, payload, dispatchOptions) => {
-                await jobRunnerForTriggers.dispatch?.(jobName, payload, dispatchOptions);
-            },
-        }
-        : undefined;
-    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
-                ? createTenantFileContext(fileProviderResolver, event.tenantId)
-                : undefined;
-            const mspDb = withExecutorManagedWrites(baseDb);
-            const applyCtx = createMultiStreamApplyContext({
-                registry: options.registry,
-                db: mspDb,
-                tenantId: event.tenantId,
-                userId: event.metadata.userId,
-                ...(mspOwner && { callerFeature: mspOwner }),
-                ...(mspFiles && { files: mspFiles }),
-                ...(contextWithObservability.secrets && { secrets: contextWithObservability.secrets }),
-                ...(mspJobs && { jobs: mspJobs }),
-                ...(mspFiles && {
-                    derivatives: createDerivativesContext({
-                        files: mspFiles,
-                        registry: options.registry,
-                        db: baseDb,
-                        tenantId: event.tenantId,
-                    }),
-                }),
-            });
-            await applyFn(event, mspDb, 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();
-        });
-    }
-    if (options.lifecycle && ownedCacheSync) {
-        const bus = ownedCacheSync;
-        options.lifecycle.registerShutdownHook("cacheSync", async () => {
-            await bus.close();
-        });
-    }
+    const wiring = resolveServerWiring(options);
     const app = new Hono();
     // Sub-apps mounted via app.route() without their own handler inherit this one.
     app.onError(handleUncaughtRouteError);
-    // Resolved once; auth routes, auth/csrf middleware and the tenant-cookie
-    // helpers read the cookie names from the request context.
-    const sessionCookies = resolveSessionCookies({
-        secureCookies: options.auth?.secureCookies,
-        cookieDomain: options.auth?.cookieDomain,
-        retiredCookieDomains: options.auth?.retiredCookieDomains,
-    });
-    app.use("*", sessionCookiesMiddleware(sessionCookies));
-    // 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));
-    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);
-    }
-    else if (process.env["NODE_ENV"] === "production") {
-        console.warn("[kumiko:boot] /metrics is off: no `metrics` option, so nothing is measured or scraped. " +
-            "Set PROMETHEUS_METRICS_TOKEN (min 32 chars) and spread resolveObservabilityWiring(token) into the server options.");
-    }
-    app.use("/api/*", requestIdMiddleware({
-        resolver: clientIpResolver,
-        ...(options.errorDocs && { errorDocs: options.errorDocs }),
-    }));
-    // 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.
+    // Hono runs middleware and routes in registration order, so the order below is behavior.
+    // On "*" and first: auth routes, auth/csrf guards and tenant-cookie helpers read the names from the context.
+    const sessionCookies = installSessionCookies(app, options.auth);
+    const isPublicApiRequest = compilePublicApiRequestMatcher(options.extraRoutes);
+    // /health and /metrics sit outside /api/*, so the /api/* guards below never run for them.
+    mountOperationalRoutes(app, wiring);
+    // First on /api/*: every later layer logs with the request id and client ip it sets.
+    installRequestId(app, wiring);
+    // O(1) header check before rate limit, auth and observability touch the body.
     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.
-    let globalRateLimitGuard;
-    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) {
-            globalRateLimitGuard = globalIpRateLimit({
-                ...options.rateLimit.global,
-                resolver: rateLimitResolver,
-                clientIpResolver,
-                meter: observability.meter,
-            });
-            app.use("/api/*", globalRateLimitGuard);
-        }
-        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,
-    }));
-    // 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 tenantlessAnonymousQns = new Set([...options.registry.getAllWriteHandlers()]
-        .filter(([, handler]) => handler.tenantlessAnonymous === true)
-        .map(([qn]) => qn));
-    const jwtGuard = authMiddleware(jwt, {
-        ...(tenantlessAnonymousQns.size > 0
-            ? { isTenantlessAnonymousWrite: (qn) => tenantlessAnonymousQns.has(qn) }
-            : {}),
-        ...(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
-    // when allowedOrigins is non-empty, or with host-only cookies when
-    // auth.publicOrigin is known (see resolveOriginGuard), 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);
-    assertSessionCallbacksPaired(options.auth);
-    const allowedOrigins = options.auth?.allowedOrigins;
-    const originGuard = resolveOriginGuard(options.auth);
-    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);
-    });
-    // No PAT rate-limit here: patRouteGuardMiddleware rejects every PAT on httpRoutes before it could count.
-    // httpRoutes sit outside /api/*, so the pre-auth /api/* middlewares do not run for them: the
-    // global IP limit (an unauthenticated flood must not reach JWT verify / session checks) and the
-    // PII ciphertext tripwire are re-attached here. requestId, body limit and observability are not.
-    const sessionOnlyHttpRouteGuards = [
-        ...(globalRateLimitGuard ? [globalRateLimitGuard] : []),
-        piiCiphertextResponseGuard(),
-        sessionOnlyGuard,
-        patRouteGuardMiddleware,
-        ...(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 principalStatus is not provided by exactly
-        // one feature — surface that misconfig at boot instead of an InternalError on first login/switch-tenant.
-        if (options.registry.getQueryHandler(options.auth.membershipQuery)) {
-            const principalStatusProviders = options.registry.getExtensionUsages(EXT_PRINCIPAL_STATUS).length;
-            if (principalStatusProviders === 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).");
-            }
-            if (principalStatusProviders > 1) {
-                throw new Error(`[kumiko] auth membershipQuery "${options.auth.membershipQuery}" is registered but ` +
-                    `${principalStatusProviders} features provide the "principalStatus" contract — exactly one ` +
-                    "is expected (the bundled user feature already provides it).");
-            }
-        }
-        app.route("/api", createAuthRoutes(dispatcher, jwt, {
-            ...options.auth,
-            secureCookies: sessionCookies.secure,
-            resolver: clientIpResolver,
-        }));
-    }
-    app.route("/api", createClientErrorRoute({
-        resolver: rateLimitResolver ??
-            (wrappedRedis ? createRateLimitResolver({ redis: wrappedRedis }) : undefined),
-        clientIpResolver,
-        meter: observability.meter,
-        identifySession: (c) => identifyOptionalSession(c, jwt),
-    }));
-    app.route("/api", createApiRoutes(dispatcher, {
-        ...(options.sseHeartbeatMs !== undefined ? { sseHeartbeatMs: options.sseHeartbeatMs } : {}),
-    }));
-    app.route("/api", createSseRoute(sseBroker, {
-        anonymousLiveEntities: collectAnonymousLiveEntities(options.registry),
-        entityReadAccess: collectEntityReadAccess(options.registry),
-    }));
-    // 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. What IS part of the key: the sorted set of
-    // features the caller's tenant has switched off (r.toggleable) — few
-    // distinct sets, so the cache stays small. The resolver is read per request
-    // because run{Dev,Prod}App fill it in after the server is built.
-    let fullSchema;
-    const projectedSchemaCache = new Map();
-    app.get(`/api${Routes.schema}`, async (c) => {
-        const user = getUser(c);
-        if (isMissingOrAnonymousUser(user)) {
-            return unauthenticatedResponse(c);
-        }
-        const effectiveFeatures = options.dispatcherOptions?.effectiveFeatures;
-        const disabledFeatureNames = effectiveFeatures === undefined
-            ? []
-            : await resolveDisabledFeatureNames(options.registry, effectiveFeatures, user.tenantId);
-        const roleKey = JSON.stringify([[...new Set(user?.roles ?? [])].sort(), disabledFeatureNames]);
-        let cached = projectedSchemaCache.get(roleKey);
-        if (cached === undefined) {
-            if (fullSchema === undefined) {
-                fullSchema = buildAppSchema(options.registry, {
-                    searchAdapterMissing: !options.context.searchAdapter,
-                });
-            }
-            const projected = projectAppSchemaForRoles(stripDisabledFeaturesFromAppSchema(fullSchema, options.registry, disabledFeatureNames), 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);
-        const canReadRecord = createRecordReadCheck(options.registry, dispatcher.query);
-        app.route("/api", createFileRoutes({
-            db: fileDb,
-            registry: options.registry,
-            resolveProvider: fileProviderResolver,
-            canReadRecord,
-            canWriteRecord: createRecordWriteCheck({
-                registry: options.registry,
-                canReadRecord,
-                tenantDbFor: (tenantId) => createProjectingTenantDb(fileDb, tenantId, options.registry),
-            }),
-            ...(routeOptions.accessGuard ? { accessGuard: routeOptions.accessGuard } : {}),
-            ...(routeOptions.privilegedRoles ? { privilegedRoles: routeOptions.privilegedRoles } : {}),
-            ...(routeOptions.unclaimedUploadReaders
-                ? { unclaimedUploadReaders: routeOptions.unclaimedUploadReaders }
-                : {}),
-            ...(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)),
-            });
-            // Without a resolver (no Redis in the context — dev/test stacks) the
-            // declared limit is skipped rather than failing the boot of every app
-            // that mounts a bundled feature whose routes carry a default limit.
-            const routeLimit = route.rateLimit && rateLimitResolver
-                ? [
-                    httpRouteRateLimit({
-                        resolver: rateLimitResolver,
-                        rateLimit: route.rateLimit,
-                        routeKey: `${route.method} ${route.path}`,
-                        clientIpResolver,
-                        meter: observability.meter,
-                    }),
-                ]
-                : [];
-            mountHonoRoute(app, route.method, route.path, honoHandler, [
-                ...routeLimit,
-                ...(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.');
-            }
-            // A `:param` segment is as broad as a wildcard, and the public matchers test
-            // the bare request path: "/:seg/write" and "/api/:hook" both match /api/write.
-            if (route.entry === ExtraRouteEntries.signature) {
-                const routePattern = honoPathToRegex(route.path);
-                const shadowedFrameworkPath = [...PUBLIC_API_PATHS, ...NON_PUBLIC_API_PATHS].find((path) => routePattern.test(path));
-                if (shadowedFrameworkPath !== undefined) {
-                    throw new Error(`[kumiko] extraRoutes: entry:"signature" route "${route.method} ${route.path}" must not ` +
-                        `match the framework path "${shadowedFrameworkPath}" — it would bypass the auth chain for it.`);
-                }
-            }
-        }
-        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, bodyLimitForRoutePath(route.path, options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES));
-        }
-    }
-    // /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.
+    // Before auth, so an unauthenticated flood never reaches JWT verify.
+    const globalRateLimitGuard = installRateLimitMiddleware(app, wiring);
+    // After the request id (the span carries it), before auth and routes (they run inside the span).
+    installObservability(app, wiring.observability);
+    // Before the auth chain, so its error responses pass the ciphertext tripwire too.
+    installPiiLeakGuard(app);
+    // jwt first: the PAT route scope, PAT rate limit and csrf guards read the principal it resolves.
+    const authGuards = installAuthGuardChain(app, wiring, {
+        isPublicApiRequest,
+        globalRateLimitGuard,
+    });
+    // Before the generic /api routes: Hono serves the first match.
+    mountAuthRoutes(app, wiring, sessionCookies);
+    mountClientErrorRoute(app, wiring);
+    mountDispatcherRoutes(app, wiring);
+    mountSchemaRoute(app, options);
+    mountFileRoutes(app, wiring);
+    // Feature routes after /api/*, so the framework paths always win.
+    mountFeatureHttpRoutes(app, wiring, authGuards.sessionOnlyHttpRouteGuards);
+    mountWebSocketRoutes(app, wiring, authGuards.tenantLifecycleResolver);
+    mountExtraRoutes(app, wiring);
+    // After feature routes, so a feature-declared /version wins.
     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" }));
+    // Last: it may only fire when no route matched at all.
+    installNoRouteMatchMarker(app);
     return {
         app,
-        jwt,
-        sseBroker,
-        observability,
-        dispatcher,
-        context: contextWithObservability,
-        ...(eventDispatcher ? { eventDispatcher } : {}),
+        jwt: wiring.jwt,
+        sseBroker: wiring.sseBroker,
+        observability: wiring.observability,
+        dispatcher: wiring.dispatcher,
+        lifecycleHooks: wiring.lifecycleHooks,
+        context: wiring.context,
+        ...(wiring.eventDispatcher ? { eventDispatcher: wiring.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]));
-}
-// Privilege-scope: the system user gets exactly the roles the caller names —
-// no implicit SystemAdmin — so a seed can write data gated on app roles.
-// Same trust requirement as makeDispatchSystemWrite: never expose to a raw
-// request, only to code that already proved its own authenticity.
-export function makeDispatchWriteAs(dispatcher) {
-    return ({ handlerQn, payload, tenantId, roles }) => dispatcher.write(handlerQn, payload, createSystemUser(tenantId, roles));
-}
-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 || isAnonymousSessionUser(user);
-}
-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");
-const extraRouteLog = createFallbackLogger("extra-route");
-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);
-                    }
-                    // The body goes to unauthenticated callers; infra errors thrown by
-                    // verify() (secrets, DB) must not leak, so the detail stays in the log.
-                    extraRouteLog.error(`signature verify() threw on ${c.req.path}`, {
-                        error: e instanceof Error ? e.message : String(e),
-                    });
-                    return c.json({
-                        error: {
-                            code: "extra_route_signature_invalid",
-                            message: "signature verification failed",
-                        },
-                    }, 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];
-}
-function payloadDigestMasterSecret(jwtSecret) {
-    if (typeof jwtSecret === "string")
-        return jwtSecret;
-    const signingSecret = jwtSecret.keys[jwtSecret.signKid];
-    if (signingSecret === undefined) {
-        throw new Error(`[kumiko] jwtSecret.signKid "${jwtSecret.signKid}" not found in jwtSecret.keys`);
-    }
-    return signingSecret;
-}