cartethyia 2.6.6 → 2.7.0

package/src/boot/app.ts

@@ -1,722 +1,714 @@
-import { Elysia } from "elysia";
-import { resolveDashboardDist, resolveElysiaPrecompile } from "../config/runtime";
-import { createConsoleRouter, type ConsoleApiCompositionDeps } from "../console/console-router";
-import type { ScheduledTaskRegistry } from "../workers/scheduler";
-import { createStaticHandler } from "../console/dashboard-assets";
-import { createShareRouter } from "../console/share/share-router";
-import { createShareStatsPort } from "../console/share/share-stats";
-import { DrizzleShareLinkStore } from "../persistence/stores/share-store";
-import { chatAdapter } from "../transport/surface/chat/adapter";
-import { responsesAdapter } from "../transport/surface/responses/adapter";
-import { messagesAdapter } from "../transport/surface/messages/adapter";
-import { completionAdapter } from "../transport/surface/completion";
-import { SurfaceAdapterRegistry } from "../transport/surface/adapters";
-import { GatewayError, publicGatewayErrorBody } from "../protocol/gateway-error";
-import { shutdownError, shutdownNotice } from "../transport/shutdown-notice";
-import type { CanonicalAdapter } from "../transport/contracts";
-import type { ApiKeyAuthorizationSnapshot } from "../security/api-key-auth";
-import { modelsListApiKeyError } from "../security/api-key-auth";
-import { getDbHandle } from "../persistence/boot";
-import { isPgHandle } from "../persistence/db-pg";
-import { resolveRedisClient } from "../persistence/redis";
-import type { CartethyiaDatabase } from "../persistence/db-handle";
-import type { ProviderAdapter } from "../providers/provider-contracts";
-import type { OAuthTokenRefresher, OAuthRefreshService } from "../providers/authentication/oauth-refresh-service";
-import { withTimeout } from "./timeout";
-import type { ByokUpstreamHost } from "../providers/operations/provider-catalog-service";
-import type { NetworkPoolSelector } from "../network/pool/selector";
-import type { ProxyRequestPreparer } from "../transport/request/preparer";
-import { ProxyRequestStateStore } from "../transport/request/state";
-import { fastPathname } from "../transport/pathname";
-import {
-  handleProviderProxyRequest,
-  type ProviderProxyHandlerDeps,
-} from "../transport/dispatch/proxy-request";
-import { createResponsesCompactHandler } from "../transport/dispatch/responses-compact";
-import { createSystemoneHandler } from "../transport/dispatch/systemone";
-import { createWebsearchHandler } from "../transport/dispatch/websearch";
-import {
-  createAudioSpeechHandler,
-  createAudioTranscriptionHandler,
-  createEmbeddingHandler,
-  createImageGenerationHandler,
-  createVideoGenerationHandler,
-} from "../transport/dispatch/generation";
-import { createTokenCountHandler } from "../transport/dispatch/token-count";
-
-import { createTransportPipeline } from "../transport/guards/pipeline";
-import { defaultProcessConcurrencyController } from "../transport/guards/concurrency-guard";
-import { createDrainHandler, isLoopbackPeer, tokenMatches } from "../transport/drain-endpoint";
-import { createConsoleAccountResetHandler } from "../console/auth/account-reset";
-import { resetConsoleAuthState } from "../console/auth/account-reset-store";
-import { createBackupExportHandler } from "../console/backup/export-endpoint";
-import { tenants } from "../persistence/schema";
-import { PublicModelCatalogStore, type AllowedModelEntry } from "../console/providers/catalog/public-model-store";
-import type { IpAbuseProtectionService } from "../security/abuse";
-import type { ReadinessCheckResult } from "../persistence/readiness";
-import type { RouteSnapshotService } from "../transport/routing/route-model";
-import type { TrustedProxyBoundary } from "../config/network";
-import { resolveClientIdentity } from "../security/ip-boundary";
-import type { ValidatedNetworkBindingFactory } from "../network/pool/resolver";
-import { metrics } from "../observability/metrics";
-import type { RuntimeMetricsSampler } from "../observability/runtime-metrics";
-import { API_CONTENT_SECURITY_POLICY, X_FRAME_OPTIONS } from "../security/outbound-headers";
-import type { ModelStrikeService } from "../security/model-abuse";
-
-
-import type { TelemetryBatchBuffer } from "../observability/telemetry-buffer";
-import type { ShutdownCoordinator } from "./lifecycle";
-import type { ShutdownDrainSource } from "../transport/contracts";
-
-/**
- * Route-only shell dependencies: the dashboard, `/health`, and `/metrics`
- * without the transport pipeline. Used when no database is available (AOT
- * manifest capture during `bun run build:aot`) and by tests that exercise
- * routing and static serving in isolation.
- *
- * Only the knobs route-only mode actually reads appear here. Transport and
- * console options (`db`, `resolvePeerAddress`, `trustedProxyBoundary`,
- * `maxBodyBytes`, `requestDeadlineMs`, `verifiedHttps`) are deliberately
- * absent: they are read inside the `mode === "production"` branches, where the
- * discriminant narrows `deps` to `ProductionAppDeps`. Listing them here would
- * let a caller pass a value the shell silently ignores.
- */
-interface GatewayShellDeps {
-  readonly mode: "route-only";
-  readonly dashboardDist?: string;
-  readonly checkDb?: () => Promise<void>;
-  readonly checkRedis?: () => Promise<void>;
-  readonly readiness?: () => Promise<ReadinessCheckResult>;
-  /**
-   * Drain state the readiness route reads. The shell has no coordinator, so it
-   * takes the narrow read surface (`ShutdownDrainSource`) rather than a
-   * hand-maintained copy of the whole `ShutdownCoordinator`.
-   */
-  readonly shutdownCoordinator?: ShutdownDrainSource;
-  /**
-   * Memory sampler when the caller owns one. The shell never constructs it, so
-   * it stays optional; production always supplies it and binds its in-flight
-   * source to the request store below.
-   */
-  readonly runtimeMetricsSampler?: RuntimeMetricsSampler;
-}
-
-/**
- * Full production dependencies. Every transport, pool, snapshot, telemetry,
- * and console field is required — the composition root in
- * `runtime/dependencies.ts` either supplies it or the app does not boot, so
- * there is no runtime shape check to fall through.
- */
-export interface ProductionAppDeps {
-  readonly mode: "production";
-  readonly db: CartethyiaDatabase;
-  readonly proxyPreparer: ProxyRequestPreparer;
-  readonly resolveProviderAdapter: (providerId: string) => Promise<ProviderAdapter | undefined>;
-  readonly providerAdapters?: ReadonlyMap<string, ProviderAdapter>;
-  /** Live lookup of a provider's SSRF-validated upstream host. */
-  readonly byokUpstreamHosts: { readonly get: (providerId: string) => ByokUpstreamHost | undefined };
-  readonly networkBindingFactory: ValidatedNetworkBindingFactory;
-  readonly ipAbuseProtection: IpAbuseProtectionService;
-  readonly trustedProxyBoundary: TrustedProxyBoundary;
-  readonly poolSelector: NetworkPoolSelector;
-  readonly snapshotService: RouteSnapshotService;
-  readonly readiness: () => Promise<ReadinessCheckResult>;
-  readonly telemetryBuffer: TelemetryBatchBuffer;
-  readonly resolveOAuthRefresher: (providerId: string) => Promise<OAuthTokenRefresher | undefined>;
-  readonly oauthRefreshService: OAuthRefreshService;
-  /** Graduated strikes for repeated invalid-model requests. */
-  readonly modelStrikes?: ModelStrikeService;
-  /**
-   * The console control plane. Optional so reduced compositions (route-only
-   * shell, console stubs) stay valid; production always mounts it. Without
-   * REDIS_URL the console runs on the in-memory backend like the data plane
-   * (OAuth-flow state and the quota cache fall back to process memory;
-   * sessions live in `console_sessions` in Postgres and CSRF is stateless).
-   */
-  readonly consoleApi?: ConsoleApiCompositionDeps;
-  /**
-   * The shared maintenance scheduler. The in-flight backstop sweep registers
-   * here rather than owning a private timer, so every periodic task in the
-   * process is visible in one place. Absent in reduced compositions, where the
-   * backstop is not mounted.
-   */
-  readonly scheduledTasks?: ScheduledTaskRegistry;
-  /** Memory sampler; bound to the request store created below. */
-  readonly runtimeMetricsSampler?: RuntimeMetricsSampler;
-  /** The real coordinator: production wires its abort hook and tracks requests. */
-  readonly shutdownCoordinator: ShutdownCoordinator;
-  readonly dashboardDist?: string;
-  readonly resolvePeerAddress?: (request: Request) => string | null;
-  readonly maxBodyBytes?: number;
-  readonly requestDeadlineMs?: number;
-  readonly verifiedHttps?: boolean;
-  /**
-   * Secret for the operator drain endpoint. When set (with `triggerDrain`),
-   * `POST /admin/drain` from loopback with a matching `x-drain-token` drains
-   * gracefully — the signal-free stop Windows needs.
-   */
-  readonly drainToken?: string;
-  readonly triggerDrain?: () => void;
-}
-
-/** Either app mode. The discriminant decides which builder path runs. */
-type GatewayAppDeps = GatewayShellDeps | ProductionAppDeps;
-
-function checkDatabaseConnection(): Promise<void> {
-  return getDbHandle()
-    .query("SELECT 1")
-    .then(() => undefined);
-}
-
-function checkRedisConnection(): Promise<void> {
-  // Memory backend is healthy by construction — there is no connection to
-  // probe — so readiness only pings a real client.
-  const redis = resolveRedisClient();
-  if (!redis) return Promise.resolve();
-  return redis.ping().then(() => undefined);
-}
-
-function runDependencyReadinessCheck(check: () => Promise<void>, label: string): Promise<void> {
-  return withTimeout(Promise.resolve().then(check), 2000, `${label} timeout after 2000ms`);
-}
-
-/**
- * Builds the public HTTP composition root with route ordering guarantee.
- * The one builder behind both modes: `deps.mode` selects which planes mount,
- * and each mode's dependency interface admits no partial set.
- */
-export function createGatewayApp(deps: GatewayAppDeps) {
-  const dbCheck =
-    deps.mode === "route-only"
-      ? (deps.checkDb ?? checkDatabaseConnection)
-      : checkDatabaseConnection;
-  const redisCheck =
-    deps.mode === "route-only"
-      ? (deps.checkRedis ?? checkRedisConnection)
-      : checkRedisConnection;
-  const registry = new SurfaceAdapterRegistry([
-    chatAdapter,
-    responsesAdapter,
-    messagesAdapter,
-    completionAdapter,
-  ]);
-  const dashboardDist = deps.dashboardDist ?? resolveDashboardDist();
-  const staticHandler = createStaticHandler({ buildDir: dashboardDist });
-  const peerAddresses = new WeakMap<Request, string>();
-  const serveDashboard = async ({ request }: { request: Request }): Promise<Response> => {
-    const pathname = fastPathname(request.url);
-    // The client's `accept-encoding` is what decides whether a precompressed
-    // `.gz` sibling can be served instead of the plain asset.
-    const result = await staticHandler(pathname, request.headers.get("accept-encoding"));
-    return new Response(result.body ? (result.body as unknown as BodyInit) : null, {
-      status: result.status,
-      headers: result.headers,
-    });
-  };
-  /**
-   * Root catch-all. Non-document namespaces (`/v1`, `/health`, `/metrics`) keep
-   * their JSON 404 so an unknown API path can never be answered with the SPA
-   * document; everything else resolves through the static handler.
-   */
-  const API_NAMESPACES = ["/v1", "/health", "/metrics"] as const;
-  const serveRootFallback = async ({ request }: { request: Request }): Promise<Response> => {
-    const pathname = fastPathname(request.url);
-    const reserved = API_NAMESPACES.some(
-      (prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`),
-    );
-    if (reserved) {
-      const notFound = new GatewayError("not_found", 404, "No endpoint exists at this path. Check the route against the API reference.");
-      return new Response(JSON.stringify(publicGatewayErrorBody(notFound)), {
-        status: notFound.status,
-        headers: {
-          "content-type": "application/json; charset=utf-8",
-          "cache-control": "no-store",
-          "content-security-policy": API_CONTENT_SECURITY_POLICY,
-          "x-frame-options": X_FRAME_OPTIONS,
-          "x-content-type-options": "nosniff",
-        },
-      });
-    }
-    return serveDashboard({ request });
-  };
-
-  // Build the Elysia app with strict route ordering.
-  const requestStateStore = new ProxyRequestStateStore(
-    deps.mode === "production" ? deps.shutdownCoordinator : undefined,
-  );
-  deps.runtimeMetricsSampler?.bindInFlight(() => requestStateStore.inFlightCount());
-  // The concurrency ceiling is derived (memory limit ÷ body budget), so it is
-  // published as a gauge: an operator reading "shedding at 16 in flight" needs
-  // to see that 16 IS the limit on this box, not that the process is broken.
-  deps.runtimeMetricsSampler?.bindConcurrencyLimit(defaultProcessConcurrencyController.limit());
-  // Shutdown ordering: abort in-flight proxy controllers first so the
-  // bounded drain observes cancellation and finalizers run before
-  // telemetry flush and pool close. The reason is threaded through so the
-  // streaming path emits a drain-aware terminal frame (`restart_for_update`
-  // vs `shutting_down`) instead of a bare abort that reads as a client drop.
-  // Only production has a coordinator to wire; the shell never drains.
-  if (deps.mode === "production") {
-    const coordinator = deps.shutdownCoordinator;
-    coordinator.setAbortInflight(() =>
-      requestStateStore.abortAll(shutdownError(coordinator.shutdownReason())),
-    );
-  }
-  // Backstop: the gauge must settle even if an abort path never fires (a
-  // half-closed socket that neither pulls, cancels, nor aborts). This sweep
-  // force-releases any flight past its deadline plus a grace window, so a
-  // missed release cannot leave a permanently wrong number. The grace is a
-  // safety margin over the request deadline, not a deployment knob.
-  const INFLIGHT_BACKSTOP_INTERVAL_MS = 30_000;
-  const INFLIGHT_BACKSTOP_GRACE_MS = 30_000;
-  const INFLIGHT_BACKSTOP_HARD_GRACE_MS = 120_000;
-  // Registered in every mode, not just production. The gauge is the operator's
-  // concurrency signal, and a cancelled request that never ran a finalizer
-  // leaves its flight behind — gating the only thing that reaps those on
-  // production made a permanently wrong count depend on how the gateway was
-  // started. The registry exists in every mode, so there is no mode where
-  // running this is wrong.
-  // `scheduledTasks` is declared on the production shape only, so it is
-  // narrowed rather than reached through the union — a shell composition
-  // without the registry simply skips the backstop, exactly as before.
-  const backstopTasks = "scheduledTasks" in deps ? deps.scheduledTasks : undefined;
-  backstopTasks?.register({
-    name: "inflight-backstop",
-    intervalMs: INFLIGHT_BACKSTOP_INTERVAL_MS,
-    run: () => {
-      requestStateStore.sweepOverdueInFlight(
-        Date.now(),
-        INFLIGHT_BACKSTOP_GRACE_MS,
-        INFLIGHT_BACKSTOP_HARD_GRACE_MS,
-      );
-    },
-  });
-  const app = new Elysia({ precompile: resolveElysiaPrecompile() })
-    .beforeHandle(
-      ({
-        request,
-        server,
-      }: {
-        request: Request;
-        server?: { requestIP(request: Request): { address: string } | null } | null;
-      }) => {
-        const address = server?.requestIP(request)?.address;
-        if (address) peerAddresses.set(request, address);
-      },
-    )
-    .get("/health", () => ({ status: "ok" as const }))
-    .get("/health/ready", async () => {
-      // A draining process reports not-ready so the orchestrator stops
-      // sending it traffic and the replacement takes over without the old
-      // one crashing first: SIGTERM → draining → 503 here → Docker routes
-      // to the new container → old one finishes in flight and exits 0.
-      // The reason distinguishes an ordinary stop from an in-place update,
-      // whose replacement is seconds away, so a probe consumer can back off
-      // briefly instead of treating the drain as a permanent outage.
-      if (deps.shutdownCoordinator?.isDraining()) {
-        const notice = shutdownNotice(deps.shutdownCoordinator.shutdownReason?.());
-        return new Response(JSON.stringify({ status: "not_ready" as const, reason: notice.code }), {
-          status: 503,
-          headers: { "content-type": "application/json" },
-        });
-      }
-      const readiness = deps.readiness ? await deps.readiness() : undefined;
-      const results = readiness
-        ? [
-            { status: readiness.db === "connected" ? "fulfilled" : "rejected" },
-            { status: readiness.redis !== "disconnected" ? "fulfilled" : "rejected" },
-          ]
-        : await Promise.allSettled([
-            runDependencyReadinessCheck(dbCheck, "db"),
-            runDependencyReadinessCheck(redisCheck, "redis"),
-          ]);
-      const dbOk = results[0]?.status === "fulfilled";
-      const redisOk = results[1]?.status === "fulfilled";
-      const migrationsOk = readiness ? readiness.migrations === "applied" : true;
-
-      if (dbOk && redisOk && migrationsOk) {
-        return {
-          status: "ready" as const,
-          db: "connected" as const,
-        };
-      }
-
-      return new Response(
-        JSON.stringify({
-          status: "not_ready" as const,
-          db: dbOk ? ("connected" as const) : ("disconnected" as const),
-          redis: redisOk ? ("connected" as const) : ("disconnected" as const),
-          ...(readiness ? { migrations: readiness.migrations } : {}),
-          reason: !migrationsOk
-            ? "database migrations pending"
-            : "dependency not ready",
-        }),
-        { status: 503, headers: { "content-type": "application/json" } },
-      );
-    })
-    .get("/metrics", () => {
-      const handle = getDbHandle();
-      // Pool gauges describe the external server's connection budget; the
-      // embedded backend has no pool to report.
-      if (isPgHandle(handle)) {
-        metrics.cartethyia_pg_pool_total.set(handle.pool.totalCount);
-        metrics.cartethyia_pg_pool_idle.set(handle.pool.idleCount);
-        metrics.cartethyia_pg_pool_waiting.set(handle.pool.waitingCount);
-      }
-      // No client means the memory backend, which is always up; a real client
-      // reports its own readiness so the scrape never throws.
-      const redisClient = resolveRedisClient();
-      metrics.cartethyia_redis_up.set(redisClient === undefined || redisClient.status === "ready" ? 1 : 0);
-      return new Response(metrics.render(), {
-        headers: { "content-type": "text/plain; version=0.0.4" },
-      });
-    });
-
-  if (deps.mode === "production") {
-    const transportPipeline = createTransportPipeline({
-      db: deps.db,
-      stateStore: requestStateStore,
-      surfaceRegistry: registry,
-      adapters: new Map<string, CanonicalAdapter>([
-        ["chat", chatAdapter],
-        ["responses", responsesAdapter],
-        ["messages", messagesAdapter],
-        ["completion", completionAdapter],
-      ]),
-      preparer: deps.proxyPreparer,
-      readiness: deps.readiness,
-      trustedProxyBoundary: deps.trustedProxyBoundary,
-      ...(deps.resolvePeerAddress ? { resolvePeerAddress: deps.resolvePeerAddress } : {}),
-      ipAbuseProtection: deps.ipAbuseProtection,
-      ...(deps.maxBodyBytes === undefined ? {} : { maxBodyBytes: deps.maxBodyBytes }),
-      ...(deps.requestDeadlineMs === undefined ? {} : { requestDeadlineMs: deps.requestDeadlineMs }),
-      ...(deps.verifiedHttps ? { verifiedHttps: true } : {}),
-      shutdownCoordinator: deps.shutdownCoordinator,
-      telemetry: deps.telemetryBuffer,
-      ...(deps.modelStrikes ? { modelStrikes: deps.modelStrikes } : {}),
-      ...(deps.consoleApi?.redis ? { redis: deps.consoleApi.redis } : {}),
-      // Bound at construction so the guard holds the sampler's live snapshot
-      // rather than a value captured at boot.
-      ...(deps.runtimeMetricsSampler
-        ? { memorySnapshot: () => deps.runtimeMetricsSampler?.memorySnapshot() }
-        : {}),
-      // Reads the cached route snapshot, which the settings route invalidates
-      // when the switch is saved — so flipping it takes effect on the next
-      // request and adds no query to the proxy path.
-      isInvokeDisabled: async (tenantId) =>
-        (await deps.snapshotService.getSnapshot())?.invokeDisabledTenants?.has(tenantId),
-    });
-    transportPipeline.mountRoot(app);
-    const proxyDeps: ProviderProxyHandlerDeps = {
-      db: deps.db,
-      providerAdapters: deps.providerAdapters ?? new Map(),
-      resolveProviderAdapter: deps.resolveProviderAdapter,
-      stateStore: requestStateStore,
-      proxyPreparer: deps.proxyPreparer,
-      snapshotService: deps.snapshotService,
-      networkBindingFactory: deps.networkBindingFactory,
-      byokUpstreamHosts: deps.byokUpstreamHosts,
-      poolSelector: deps.poolSelector,
-      telemetryBuffer: deps.telemetryBuffer,
-      resolveOAuthRefresher: deps.resolveOAuthRefresher,
-      oauthRefreshService: deps.oauthRefreshService,
-    };
-    const proxyHandler = ({ request }: { request: Request }) =>
-      handleProviderProxyRequest(request, proxyDeps);
-
-    const publicModelStore = new PublicModelCatalogStore(deps.db);
-    const queryAllowedModels = (auth: {
-      snapshot: ApiKeyAuthorizationSnapshot;
-      tenantId: string | null;
-      modelPrefix?: string;
-    }): Promise<AllowedModelEntry[]> =>
-      publicModelStore.listPublicModels(auth.tenantId, auth.snapshot, auth.modelPrefix);
-
-    const handleModelsList = async ({ request }: { request: Request }): Promise<Response> => {
-      const state = requestStateStore.require(request);
-      const auth = state.authorization;
-      if (!auth) throw modelsListApiKeyError();
-      const data = await queryAllowedModels(auth);
-      return new Response(JSON.stringify({ object: "list", data }), {
-        headers: {
-          "content-type": "application/json",
-          "cache-control": "no-store",
-          "x-request-id": state.requestId,
-          "access-control-allow-origin": "*",
-        },
-      });
-    };
-
-    const handleModelsDetail = async ({
-      request,
-      params,
-    }: {
-      request: Request;
-      // Elysia omits `params` entirely for the literal `/models/info` route
-      // (it declares no path parameters), so this must stay optional.
-      params?: Record<string, string> | undefined;
-    }): Promise<Response> => {
-      const state = requestStateStore.require(request);
-      const auth = state.authorization;
-      if (!auth) throw modelsListApiKeyError();
-      const raw = params?.["*"] ?? params?.id ?? "";
-      const targetId = new URL(request.url).searchParams.get("id") ?? raw;
-      const found = await publicModelStore.getPublicModelDetail(
-        targetId,
-        auth.tenantId,
-        auth.snapshot,
-        auth.modelPrefix,
-      );
-      if (!found)
-        throw new GatewayError(
-          "model_not_found",
-          404,
-          `The model '${targetId}' does not exist or you do not have access to it.`,
-        );
-      return new Response(JSON.stringify(found), {
-        headers: {
-          "content-type": "application/json",
-          "cache-control": "no-store",
-          "x-request-id": state.requestId,
-          "access-control-allow-origin": "*",
-        },
-      });
-    };
-
-    const handleResponsesCompact = createResponsesCompactHandler({
-      db: deps.db,
-      providerAdapters: deps.providerAdapters ?? new Map(),
-      resolveProviderAdapter: deps.resolveProviderAdapter,
-      proxyPreparer: deps.proxyPreparer,
-      stateStore: requestStateStore,
-      poolSelector: deps.poolSelector,
-      networkBindingFactory: deps.networkBindingFactory,
-      snapshotService: deps.snapshotService,
-      resolveOAuthRefresher: deps.resolveOAuthRefresher,
-      oauthRefreshService: deps.oauthRefreshService,
-      // The compact handler completes its attempt through `completeAttempt`,
-      // which marks the request completed and finalizes telemetry itself —
-      // so the afterResponse lifecycle skips it. Without the buffer here the
-      // route would emit no telemetry row at all.
-      telemetryBuffer: deps.telemetryBuffer,
-    });
-
-    const handleSystemone = createSystemoneHandler({
-      db: deps.db,
-      providerAdapters: deps.providerAdapters ?? new Map(),
-      resolveProviderAdapter: deps.resolveProviderAdapter,
-      proxyPreparer: deps.proxyPreparer,
-      stateStore: requestStateStore,
-      poolSelector: deps.poolSelector,
-      networkBindingFactory: deps.networkBindingFactory,
-      snapshotService: deps.snapshotService,
-      resolveOAuthRefresher: deps.resolveOAuthRefresher,
-      oauthRefreshService: deps.oauthRefreshService,
-      // Same reasoning as compact: the handler finalizes telemetry itself, so
-      // the buffer must be threaded here or the route emits no row.
-      telemetryBuffer: deps.telemetryBuffer,
-    });
-
-    const handleWebsearch = createWebsearchHandler({
-      db: deps.db,
-      providerAdapters: deps.providerAdapters ?? new Map(),
-      resolveProviderAdapter: deps.resolveProviderAdapter,
-      proxyPreparer: deps.proxyPreparer,
-      stateStore: requestStateStore,
-      poolSelector: deps.poolSelector,
-      networkBindingFactory: deps.networkBindingFactory,
-      snapshotService: deps.snapshotService,
-      resolveOAuthRefresher: deps.resolveOAuthRefresher,
-      oauthRefreshService: deps.oauthRefreshService,
-      telemetryBuffer: deps.telemetryBuffer,
-    });
-
-    const generationDeps = {
-      db: deps.db,
-      providerAdapters: deps.providerAdapters ?? new Map(),
-      resolveProviderAdapter: deps.resolveProviderAdapter,
-      proxyPreparer: deps.proxyPreparer,
-      stateStore: requestStateStore,
-      poolSelector: deps.poolSelector,
-      networkBindingFactory: deps.networkBindingFactory,
-      snapshotService: deps.snapshotService,
-      resolveOAuthRefresher: deps.resolveOAuthRefresher,
-      oauthRefreshService: deps.oauthRefreshService,
-      telemetryBuffer: deps.telemetryBuffer,
-    };
-    const handleImageGeneration = createImageGenerationHandler(generationDeps);
-    // Mounted with no model behind it on purpose: the surface exists so it can
-    // be finished when an upstream is known, rather than 404ing like a typo.
-    const handleVideoGeneration = createVideoGenerationHandler(generationDeps);
-    // Passthrough surfaces: routed and accounted for, but never interpreted.
-    // No bundled adapter implements embeddings or audio, and inventing a wire
-    // for them would be a guess; what these need to be useful is the route, the
-    // pipeline, and a compatible upstream behind it.
-    const handleEmbedding = createEmbeddingHandler(generationDeps);
-    const handleAudioTranscription = createAudioTranscriptionHandler(generationDeps);
-    const handleAudioSpeech = createAudioSpeechHandler(generationDeps);
-    // Shares the generation dependency bundle: same pipeline, and a count is
-    // neither chat-shaped nor generation-shaped, so it needs exactly the same
-    // routing, leasing, and accounting surface.
-    const handleTokenCount = createTokenCountHandler(generationDeps);
-
-    // Gateway mounting: the pipeline owner composes stages, telemetry, and
-    // cleanup; app only registers the public route table.
-    app.use(
-      transportPipeline.createGateway((routes) => {
-        routes.post("/chat/completions", proxyHandler);
-        routes.post("/responses", proxyHandler);
-        routes.post("/responses/compact", handleResponsesCompact);
-        routes.post("/messages", proxyHandler);
-        // The token counter is a sibling of the chat route on the same model, and
-        // it is forwarded rather than estimated — see dispatch/token-count.ts.
-        routes.post("/messages/count_tokens", handleTokenCount);
-        routes.post("/completions", proxyHandler);
-        routes.post("/systemone", handleSystemone);
-        routes.post("/search", handleWebsearch);
-        routes.post("/images/generations", handleImageGeneration);
-        routes.post("/videos/generations", handleVideoGeneration);
-        routes.post("/embeddings", handleEmbedding);
-        routes.post("/audio/transcriptions", handleAudioTranscription);
-        routes.post("/audio/speech", handleAudioSpeech);
-        routes.get("/models", handleModelsList);
-        routes.get("/models/info", handleModelsDetail);
-        routes.get("/models/*", handleModelsDetail);
-      }),
-    );
-
-    // Operator drain endpoint. Registered before the SPA catch-all and only
-    // when a token is configured, so an unconfigured gateway has no such route
-    // at all. It is a graceful stop for platforms where a catchable signal
-    // cannot be delivered (Windows), and a second signal-free path elsewhere.
-    if (deps.drainToken && deps.triggerDrain) {
-      const drainHandler = createDrainHandler({
-        token: deps.drainToken,
-        triggerDrain: deps.triggerDrain,
-        resolvePeerAddress: (request) => peerAddresses.get(request) ?? null,
-      });
-      app.post("/admin/drain", drainHandler);
-    }
-
-    // Operator backup export. Same double gate as drain and reset, and no
-    // console password: the CLI already runs as the OS user who owns the
-    // database, and a forgotten password must not block the backup that is
-    // meant to rescue the install.
-    if (deps.drainToken) {
-      app.post(
-        "/admin/export-backup",
-        createBackupExportHandler({
-          db: deps.db,
-          token: deps.drainToken,
-          resolvePeerAddress: (request) => peerAddresses.get(request) ?? null,
-          resolveTenantId: async () => {
-            const [row] = await deps.db.select({ id: tenants.id }).from(tenants).limit(1);
-            return row?.id ?? null;
-          },
-        }),
-      );
-    }
-
-    // Console account reset. Same double gate as drain — loopback plus the
-    // token — because it deletes every operator credential on the install.
-    // Only authentication state goes; providers, keys, and routing stay.
-    if (deps.drainToken) {
-      app.post(
-        "/admin/reset-console-account",
-        createConsoleAccountResetHandler({
-          token: deps.drainToken,
-          resolvePeerAddress: (request) => peerAddresses.get(request) ?? null,
-          resetConsoleAccount: () => resetConsoleAuthState(deps.db),
-        }),
-      );
-    }
-
-    // Manual task trigger. Same gate as drain: loopback plus the drain token,
-    // so a leaked token still cannot reach it from outside the host. 202 once
-    // the run has started; 409 when that task is already mid-run, because the
-    // scheduler refuses to overlap a task with itself and a second trigger
-    // would otherwise look like it ran.
-    if (deps.drainToken && deps.scheduledTasks) {
-      const tasks = deps.scheduledTasks;
-      const token = deps.drainToken;
-      app.post("/admin/tasks/:name/run", async ({ request, params }) => {
-        // `policy_rejected`, not `invalid_request`: the request may be perfectly
-        // well-formed. What refused it is where it came from — the client asked
-        // for something only the local host may ask. `invalid_request` told an
-        // operator to fix the body, when the body was never the problem.
-        if (!isLoopbackPeer(peerAddresses.get(request) ?? null))
-          throw new GatewayError("policy_rejected", 403, "task trigger is only available from loopback");
-        if (!tokenMatches(request.headers.get("x-drain-token"), token))
-          throw new GatewayError("authentication_failed", 401, "invalid drain token");
-        const name = params.name;
-        if (!tasks.names().includes(name))
-          throw new GatewayError("invalid_request", 404, `no such task: ${name}`);
-        if (tasks.isRunning(name))
-          throw new GatewayError("invalid_request", 409, `${name} is already running`);
-        void tasks.runNow(name);
-        return new Response(JSON.stringify({ task: name, status: "started" }), {
-          status: 202,
-          headers: { "content-type": "application/json" },
-        });
-      });
-    }
-
-    // `peerAddresses` is populated by the root `beforeHandle` above from
-    // `server.requestIP`. The console login route needs it to key its lockout
-    // bucket, and the trusted-proxy boundary decides whether an
-    // `X-Forwarded-For` hop may override it — the same pair the transport
-    // pipeline receives, so console and proxy agree on client identity.
-    if (deps.consoleApi) {
-      app.use(
-        createConsoleRouter({
-          ...deps.consoleApi,
-          stateStore: requestStateStore,
-          resolvePeerAddress: (request) => peerAddresses.get(request) ?? null,
-          trustedProxyBoundary: deps.trustedProxyBoundary,
-        }),
-      );
-    }
-
-    // Public share API routes are registered before the SPA catch-all, and
-    // enrollment uses only the peer address captured by the trusted boundary.
-    app.use(
-      createShareRouter({
-        db: deps.db,
-        shareStore: new DrizzleShareLinkStore(deps.db),
-        stats: createShareStatsPort({ db: deps.db, redis: deps.consoleApi?.redis }),
-        resolveClientIp: (request) => {
-          const peer = peerAddresses.get(request);
-          return peer
-            ? resolveClientIdentity(request, deps.trustedProxyBoundary, peer)
-            : null;
-        },
-      }),
-    );
-  }
-
-  app.all("/", serveDashboard);
-  app.all("/share", serveDashboard);
-  app.all("/share/*", serveDashboard);
-  app.all("/console", serveDashboard);
-  app.all("/console/*", serveDashboard);
-  // Root-level build output (hashed bundles, chapter art, provider icons,
-  // favicons). Registered last so every real API route above wins.
-  app.all("/*", serveRootFallback);
-  return app;
-}
-
-/**
- * Route-only convenience wrapper. It earns its place (unlike a bare forwarder)
- * by defaulting `options` and injecting the discriminant, so callers never
- * write `mode` for the shell path.
- */
-export function createGatewayShell(options: Omit<GatewayShellDeps, "mode"> = {}) {
-  return createGatewayApp({ mode: "route-only", ...options });
-}
-
-/**
- * Elysia route-tree type for Eden Treaty dashboard consumption.
- *
-
- * inferred return type.
- */
-export type App = ReturnType<typeof createGatewayApp>;
+import { Elysia } from "elysia";
+import { resolveDashboardDist, resolveElysiaPrecompile } from "../config/runtime";
+import { createConsoleRouter, type ConsoleApiCompositionDeps } from "../console/console-router";
+import type { ScheduledTaskRegistry } from "../workers/scheduler";
+import { createStaticHandler } from "../console/dashboard-assets";
+import { createShareRouter } from "../console/share/share-router";
+import { createShareStatsPort } from "../console/share/share-stats";
+import { DrizzleShareLinkStore } from "../persistence/stores/share-store";
+import { chatAdapter } from "../transport/surface/chat/adapter";
+import { responsesAdapter } from "../transport/surface/responses/adapter";
+import { messagesAdapter } from "../transport/surface/messages/adapter";
+import { completionAdapter } from "../transport/surface/completion";
+import { SurfaceAdapterRegistry } from "../transport/surface/adapters";
+import { GatewayError, publicGatewayErrorBody } from "../protocol/gateway-error";
+import { shutdownError, shutdownNotice } from "../transport/shutdown-notice";
+import type { CanonicalAdapter } from "../transport/contracts";
+import type { ApiKeyAuthorizationSnapshot } from "../security/api-key-auth";
+import { modelsListApiKeyError } from "../security/api-key-auth";
+import { getDbHandle } from "../persistence/boot";
+import { isPgHandle } from "../persistence/db-pg";
+import { resolveRedisClient } from "../persistence/redis";
+import type { CartethyiaDatabase } from "../persistence/db-handle";
+import type { ProviderAdapter } from "../providers/provider-contracts";
+import type { OAuthTokenRefresher, OAuthRefreshService } from "../providers/authentication/oauth-refresh-service";
+import { withTimeout } from "./timeout";
+import type { ByokUpstreamHost } from "../providers/operations/provider-catalog-service";
+import type { NetworkPoolSelector } from "../network/pool/selector";
+import type { ProxyRequestPreparer } from "../transport/request/preparer";
+import { ProxyRequestStateStore } from "../transport/request/state";
+import { fastPathname } from "../transport/pathname";
+import {
+  handleProviderProxyRequest,
+  type ProviderProxyHandlerDeps,
+} from "../transport/dispatch/proxy-request";
+import { createResponsesCompactHandler } from "../transport/dispatch/responses-compact";
+import { createSystemoneHandler } from "../transport/dispatch/systemone";
+import { createWebsearchHandler } from "../transport/dispatch/websearch";
+import {
+  createAudioSpeechHandler,
+  createAudioTranscriptionHandler,
+  createEmbeddingHandler,
+  createImageGenerationHandler,
+  createVideoGenerationHandler,
+} from "../transport/dispatch/generation";
+import { createTokenCountHandler } from "../transport/dispatch/token-count";
+
+import { createTransportPipeline } from "../transport/guards/pipeline";
+import { createDrainHandler, isLoopbackPeer, tokenMatches } from "../transport/drain-endpoint";
+import { createConsoleAccountResetHandler } from "../console/auth/account-reset";
+import { resetConsoleAuthState } from "../console/auth/account-reset-store";
+import { createBackupExportHandler } from "../console/backup/export-endpoint";
+import { tenants } from "../persistence/schema";
+import { PublicModelCatalogStore, type AllowedModelEntry } from "../console/providers/catalog/public-model-store";
+import type { IpAbuseProtectionService } from "../security/abuse";
+import type { ReadinessCheckResult } from "../persistence/readiness";
+import type { RouteSnapshotService } from "../transport/routing/route-model";
+import type { TrustedProxyBoundary } from "../config/network";
+import { resolveClientIdentity } from "../security/ip-boundary";
+import type { ValidatedNetworkBindingFactory } from "../network/pool/resolver";
+import { metrics } from "../observability/metrics";
+import type { RuntimeMetricsSampler } from "../observability/runtime-metrics";
+import { API_CONTENT_SECURITY_POLICY, X_FRAME_OPTIONS } from "../security/outbound-headers";
+
+
+import type { TelemetryBatchBuffer } from "../observability/telemetry-buffer";
+import type { ShutdownCoordinator } from "./lifecycle";
+import type { ShutdownDrainSource } from "../transport/contracts";
+
+/**
+ * Route-only shell dependencies: the dashboard, `/health`, and `/metrics`
+ * without the transport pipeline. Used when no database is available (AOT
+ * manifest capture during `bun run build:aot`) and by tests that exercise
+ * routing and static serving in isolation.
+ *
+ * Only the knobs route-only mode actually reads appear here. Transport and
+ * console options (`db`, `resolvePeerAddress`, `trustedProxyBoundary`,
+ * `maxBodyBytes`, `requestDeadlineMs`, `verifiedHttps`) are deliberately
+ * absent: they are read inside the `mode === "production"` branches, where the
+ * discriminant narrows `deps` to `ProductionAppDeps`. Listing them here would
+ * let a caller pass a value the shell silently ignores.
+ */
+interface GatewayShellDeps {
+  readonly mode: "route-only";
+  readonly dashboardDist?: string;
+  readonly checkDb?: () => Promise<void>;
+  readonly checkRedis?: () => Promise<void>;
+  readonly readiness?: () => Promise<ReadinessCheckResult>;
+  /**
+   * Drain state the readiness route reads. The shell has no coordinator, so it
+   * takes the narrow read surface (`ShutdownDrainSource`) rather than a
+   * hand-maintained copy of the whole `ShutdownCoordinator`.
+   */
+  readonly shutdownCoordinator?: ShutdownDrainSource;
+  /**
+   * Memory sampler when the caller owns one. The shell never constructs it, so
+   * it stays optional; production always supplies it and binds its in-flight
+   * source to the request store below.
+   */
+  readonly runtimeMetricsSampler?: RuntimeMetricsSampler;
+}
+
+/**
+ * Full production dependencies. Every transport, pool, snapshot, telemetry,
+ * and console field is required — the composition root in
+ * `runtime/dependencies.ts` either supplies it or the app does not boot, so
+ * there is no runtime shape check to fall through.
+ */
+export interface ProductionAppDeps {
+  readonly mode: "production";
+  readonly db: CartethyiaDatabase;
+  readonly proxyPreparer: ProxyRequestPreparer;
+  readonly resolveProviderAdapter: (providerId: string) => Promise<ProviderAdapter | undefined>;
+  readonly providerAdapters?: ReadonlyMap<string, ProviderAdapter>;
+  /** Live lookup of a provider's SSRF-validated upstream host. */
+  readonly byokUpstreamHosts: { readonly get: (providerId: string) => ByokUpstreamHost | undefined };
+  readonly networkBindingFactory: ValidatedNetworkBindingFactory;
+  readonly ipAbuseProtection: IpAbuseProtectionService;
+  readonly trustedProxyBoundary: TrustedProxyBoundary;
+  readonly poolSelector: NetworkPoolSelector;
+  readonly snapshotService: RouteSnapshotService;
+  readonly readiness: () => Promise<ReadinessCheckResult>;
+  readonly telemetryBuffer: TelemetryBatchBuffer;
+  readonly resolveOAuthRefresher: (providerId: string) => Promise<OAuthTokenRefresher | undefined>;
+  readonly oauthRefreshService: OAuthRefreshService;
+  /** Graduated strikes for repeated invalid-model requests. */
+  /**
+   * The console control plane. Optional so reduced compositions (route-only
+   * shell, console stubs) stay valid; production always mounts it. Without
+   * REDIS_URL the console runs on the in-memory backend like the data plane
+   * (OAuth-flow state and the quota cache fall back to process memory;
+   * sessions live in `console_sessions` in Postgres and CSRF is stateless).
+   */
+  readonly consoleApi?: ConsoleApiCompositionDeps;
+  /**
+   * The shared maintenance scheduler. The in-flight backstop sweep registers
+   * here rather than owning a private timer, so every periodic task in the
+   * process is visible in one place. Absent in reduced compositions, where the
+   * backstop is not mounted.
+   */
+  readonly scheduledTasks?: ScheduledTaskRegistry;
+  /** Memory sampler; bound to the request store created below. */
+  readonly runtimeMetricsSampler?: RuntimeMetricsSampler;
+  /** The real coordinator: production wires its abort hook and tracks requests. */
+  readonly shutdownCoordinator: ShutdownCoordinator;
+  readonly dashboardDist?: string;
+  readonly resolvePeerAddress?: (request: Request) => string | null;
+  readonly maxBodyBytes?: number;
+  readonly requestDeadlineMs?: number;
+  readonly verifiedHttps?: boolean;
+  /**
+   * Secret for the operator drain endpoint. When set (with `triggerDrain`),
+   * `POST /admin/drain` from loopback with a matching `x-drain-token` drains
+   * gracefully — the signal-free stop Windows needs.
+   */
+  readonly drainToken?: string;
+  readonly triggerDrain?: () => void;
+}
+
+/** Either app mode. The discriminant decides which builder path runs. */
+type GatewayAppDeps = GatewayShellDeps | ProductionAppDeps;
+
+function checkDatabaseConnection(): Promise<void> {
+  return getDbHandle()
+    .query("SELECT 1")
+    .then(() => undefined);
+}
+
+function checkRedisConnection(): Promise<void> {
+  // Memory backend is healthy by construction — there is no connection to
+  // probe — so readiness only pings a real client.
+  const redis = resolveRedisClient();
+  if (!redis) return Promise.resolve();
+  return redis.ping().then(() => undefined);
+}
+
+function runDependencyReadinessCheck(check: () => Promise<void>, label: string): Promise<void> {
+  return withTimeout(Promise.resolve().then(check), 2000, `${label} timeout after 2000ms`);
+}
+
+/**
+ * Builds the public HTTP composition root with route ordering guarantee.
+ * The one builder behind both modes: `deps.mode` selects which planes mount,
+ * and each mode's dependency interface admits no partial set.
+ */
+export function createGatewayApp(deps: GatewayAppDeps) {
+  const dbCheck =
+    deps.mode === "route-only"
+      ? (deps.checkDb ?? checkDatabaseConnection)
+      : checkDatabaseConnection;
+  const redisCheck =
+    deps.mode === "route-only"
+      ? (deps.checkRedis ?? checkRedisConnection)
+      : checkRedisConnection;
+  const registry = new SurfaceAdapterRegistry([
+    chatAdapter,
+    responsesAdapter,
+    messagesAdapter,
+    completionAdapter,
+  ]);
+  const dashboardDist = deps.dashboardDist ?? resolveDashboardDist();
+  const staticHandler = createStaticHandler({ buildDir: dashboardDist });
+  const peerAddresses = new WeakMap<Request, string>();
+  const serveDashboard = async ({ request }: { request: Request }): Promise<Response> => {
+    const pathname = fastPathname(request.url);
+    // The client's `accept-encoding` is what decides whether a precompressed
+    // `.gz` sibling can be served instead of the plain asset.
+    const result = await staticHandler(pathname, request.headers.get("accept-encoding"));
+    return new Response(result.body ? (result.body as unknown as BodyInit) : null, {
+      status: result.status,
+      headers: result.headers,
+    });
+  };
+  /**
+   * Root catch-all. Non-document namespaces (`/v1`, `/health`, `/metrics`) keep
+   * their JSON 404 so an unknown API path can never be answered with the SPA
+   * document; everything else resolves through the static handler.
+   */
+  const API_NAMESPACES = ["/v1", "/health", "/metrics"] as const;
+  const serveRootFallback = async ({ request }: { request: Request }): Promise<Response> => {
+    const pathname = fastPathname(request.url);
+    const reserved = API_NAMESPACES.some(
+      (prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`),
+    );
+    if (reserved) {
+      const notFound = new GatewayError("not_found", 404, "No endpoint exists at this path. Check the route against the API reference.");
+      return new Response(JSON.stringify(publicGatewayErrorBody(notFound)), {
+        status: notFound.status,
+        headers: {
+          "content-type": "application/json; charset=utf-8",
+          "cache-control": "no-store",
+          "content-security-policy": API_CONTENT_SECURITY_POLICY,
+          "x-frame-options": X_FRAME_OPTIONS,
+          "x-content-type-options": "nosniff",
+        },
+      });
+    }
+    return serveDashboard({ request });
+  };
+
+  // Build the Elysia app with strict route ordering.
+  const requestStateStore = new ProxyRequestStateStore(
+    deps.mode === "production" ? deps.shutdownCoordinator : undefined,
+  );
+  deps.runtimeMetricsSampler?.bindInFlight(() => requestStateStore.inFlightCount());
+  // Shutdown ordering: abort in-flight proxy controllers first so the
+  // bounded drain observes cancellation and finalizers run before
+  // telemetry flush and pool close. The reason is threaded through so the
+  // streaming path emits a drain-aware terminal frame (`restart_for_update`
+  // vs `shutting_down`) instead of a bare abort that reads as a client drop.
+  // Only production has a coordinator to wire; the shell never drains.
+  if (deps.mode === "production") {
+    const coordinator = deps.shutdownCoordinator;
+    coordinator.setAbortInflight(() =>
+      requestStateStore.abortAll(shutdownError(coordinator.shutdownReason())),
+    );
+  }
+  // Backstop: the gauge must settle even if an abort path never fires (a
+  // half-closed socket that neither pulls, cancels, nor aborts). This sweep
+  // force-releases any flight past its deadline plus a grace window, so a
+  // missed release cannot leave a permanently wrong number. The grace is a
+  // safety margin over the request deadline, not a deployment knob.
+  const INFLIGHT_BACKSTOP_INTERVAL_MS = 30_000;
+  const INFLIGHT_BACKSTOP_GRACE_MS = 30_000;
+  const INFLIGHT_BACKSTOP_HARD_GRACE_MS = 120_000;
+  // Registered in every mode, not just production. The gauge is the operator's
+  // concurrency signal, and a cancelled request that never ran a finalizer
+  // leaves its flight behind — gating the only thing that reaps those on
+  // production made a permanently wrong count depend on how the gateway was
+  // started. The registry exists in every mode, so there is no mode where
+  // running this is wrong.
+  // `scheduledTasks` is declared on the production shape only, so it is
+  // narrowed rather than reached through the union — a shell composition
+  // without the registry simply skips the backstop, exactly as before.
+  const backstopTasks = "scheduledTasks" in deps ? deps.scheduledTasks : undefined;
+  backstopTasks?.register({
+    name: "inflight-backstop",
+    intervalMs: INFLIGHT_BACKSTOP_INTERVAL_MS,
+    run: () => {
+      requestStateStore.sweepOverdueInFlight(
+        Date.now(),
+        INFLIGHT_BACKSTOP_GRACE_MS,
+        INFLIGHT_BACKSTOP_HARD_GRACE_MS,
+      );
+    },
+  });
+  const app = new Elysia({ precompile: resolveElysiaPrecompile() })
+    .beforeHandle(
+      ({
+        request,
+        server,
+      }: {
+        request: Request;
+        server?: { requestIP(request: Request): { address: string } | null } | null;
+      }) => {
+        const address = server?.requestIP(request)?.address;
+        if (address) peerAddresses.set(request, address);
+      },
+    )
+    .get("/health", () => ({ status: "ok" as const }))
+    .get("/health/ready", async () => {
+      // A draining process reports not-ready so the orchestrator stops
+      // sending it traffic and the replacement takes over without the old
+      // one crashing first: SIGTERM → draining → 503 here → Docker routes
+      // to the new container → old one finishes in flight and exits 0.
+      // The reason distinguishes an ordinary stop from an in-place update,
+      // whose replacement is seconds away, so a probe consumer can back off
+      // briefly instead of treating the drain as a permanent outage.
+      if (deps.shutdownCoordinator?.isDraining()) {
+        const notice = shutdownNotice(deps.shutdownCoordinator.shutdownReason?.());
+        return new Response(JSON.stringify({ status: "not_ready" as const, reason: notice.code }), {
+          status: 503,
+          headers: { "content-type": "application/json" },
+        });
+      }
+      const readiness = deps.readiness ? await deps.readiness() : undefined;
+      const results = readiness
+        ? [
+            { status: readiness.db === "connected" ? "fulfilled" : "rejected" },
+            { status: readiness.redis !== "disconnected" ? "fulfilled" : "rejected" },
+          ]
+        : await Promise.allSettled([
+            runDependencyReadinessCheck(dbCheck, "db"),
+            runDependencyReadinessCheck(redisCheck, "redis"),
+          ]);
+      const dbOk = results[0]?.status === "fulfilled";
+      const redisOk = results[1]?.status === "fulfilled";
+      const migrationsOk = readiness ? readiness.migrations === "applied" : true;
+
+      if (dbOk && redisOk && migrationsOk) {
+        return {
+          status: "ready" as const,
+          db: "connected" as const,
+        };
+      }
+
+      return new Response(
+        JSON.stringify({
+          status: "not_ready" as const,
+          db: dbOk ? ("connected" as const) : ("disconnected" as const),
+          redis: redisOk ? ("connected" as const) : ("disconnected" as const),
+          ...(readiness ? { migrations: readiness.migrations } : {}),
+          reason: !migrationsOk
+            ? "database migrations pending"
+            : "dependency not ready",
+        }),
+        { status: 503, headers: { "content-type": "application/json" } },
+      );
+    })
+    .get("/metrics", () => {
+      const handle = getDbHandle();
+      // Pool gauges describe the external server's connection budget; the
+      // embedded backend has no pool to report.
+      if (isPgHandle(handle)) {
+        metrics.cartethyia_pg_pool_total.set(handle.pool.totalCount);
+        metrics.cartethyia_pg_pool_idle.set(handle.pool.idleCount);
+        metrics.cartethyia_pg_pool_waiting.set(handle.pool.waitingCount);
+      }
+      // No client means the memory backend, which is always up; a real client
+      // reports its own readiness so the scrape never throws.
+      const redisClient = resolveRedisClient();
+      metrics.cartethyia_redis_up.set(redisClient === undefined || redisClient.status === "ready" ? 1 : 0);
+      return new Response(metrics.render(), {
+        headers: { "content-type": "text/plain; version=0.0.4" },
+      });
+    });
+
+  if (deps.mode === "production") {
+    const transportPipeline = createTransportPipeline({
+      db: deps.db,
+      stateStore: requestStateStore,
+      surfaceRegistry: registry,
+      adapters: new Map<string, CanonicalAdapter>([
+        ["chat", chatAdapter],
+        ["responses", responsesAdapter],
+        ["messages", messagesAdapter],
+        ["completion", completionAdapter],
+      ]),
+      preparer: deps.proxyPreparer,
+      readiness: deps.readiness,
+      trustedProxyBoundary: deps.trustedProxyBoundary,
+      ...(deps.resolvePeerAddress ? { resolvePeerAddress: deps.resolvePeerAddress } : {}),
+      ipAbuseProtection: deps.ipAbuseProtection,
+      ...(deps.maxBodyBytes === undefined ? {} : { maxBodyBytes: deps.maxBodyBytes }),
+      ...(deps.requestDeadlineMs === undefined ? {} : { requestDeadlineMs: deps.requestDeadlineMs }),
+      ...(deps.verifiedHttps ? { verifiedHttps: true } : {}),
+      shutdownCoordinator: deps.shutdownCoordinator,
+      telemetry: deps.telemetryBuffer,
+      ...(deps.consoleApi?.redis ? { redis: deps.consoleApi.redis } : {}),
+      // Bound at construction so the guard holds the sampler's live snapshot
+      // rather than a value captured at boot.
+      ...(deps.runtimeMetricsSampler
+        ? { memorySnapshot: () => deps.runtimeMetricsSampler?.memorySnapshot() }
+        : {}),
+      // Reads the cached route snapshot, which the settings route invalidates
+      // when the switch is saved — so flipping it takes effect on the next
+      // request and adds no query to the proxy path.
+      isInvokeDisabled: async (tenantId) =>
+        (await deps.snapshotService.getSnapshot())?.invokeDisabledTenants?.has(tenantId),
+    });
+    transportPipeline.mountRoot(app);
+    const proxyDeps: ProviderProxyHandlerDeps = {
+      db: deps.db,
+      providerAdapters: deps.providerAdapters ?? new Map(),
+      resolveProviderAdapter: deps.resolveProviderAdapter,
+      stateStore: requestStateStore,
+      proxyPreparer: deps.proxyPreparer,
+      snapshotService: deps.snapshotService,
+      networkBindingFactory: deps.networkBindingFactory,
+      byokUpstreamHosts: deps.byokUpstreamHosts,
+      poolSelector: deps.poolSelector,
+      telemetryBuffer: deps.telemetryBuffer,
+      resolveOAuthRefresher: deps.resolveOAuthRefresher,
+      oauthRefreshService: deps.oauthRefreshService,
+    };
+    const proxyHandler = ({ request }: { request: Request }) =>
+      handleProviderProxyRequest(request, proxyDeps);
+
+    const publicModelStore = new PublicModelCatalogStore(deps.db);
+    const queryAllowedModels = (auth: {
+      snapshot: ApiKeyAuthorizationSnapshot;
+      tenantId: string | null;
+      modelPrefix?: string;
+    }): Promise<AllowedModelEntry[]> =>
+      publicModelStore.listPublicModels(auth.tenantId, auth.snapshot, auth.modelPrefix);
+
+    const handleModelsList = async ({ request }: { request: Request }): Promise<Response> => {
+      const state = requestStateStore.require(request);
+      const auth = state.authorization;
+      if (!auth) throw modelsListApiKeyError();
+      const data = await queryAllowedModels(auth);
+      return new Response(JSON.stringify({ object: "list", data }), {
+        headers: {
+          "content-type": "application/json",
+          "cache-control": "no-store",
+          "x-request-id": state.requestId,
+          "access-control-allow-origin": "*",
+        },
+      });
+    };
+
+    const handleModelsDetail = async ({
+      request,
+      params,
+    }: {
+      request: Request;
+      // Elysia omits `params` entirely for the literal `/models/info` route
+      // (it declares no path parameters), so this must stay optional.
+      params?: Record<string, string> | undefined;
+    }): Promise<Response> => {
+      const state = requestStateStore.require(request);
+      const auth = state.authorization;
+      if (!auth) throw modelsListApiKeyError();
+      const raw = params?.["*"] ?? params?.id ?? "";
+      const targetId = new URL(request.url).searchParams.get("id") ?? raw;
+      const found = await publicModelStore.getPublicModelDetail(
+        targetId,
+        auth.tenantId,
+        auth.snapshot,
+        auth.modelPrefix,
+      );
+      if (!found)
+        throw new GatewayError(
+          "model_not_found",
+          404,
+          `The model '${targetId}' does not exist or you do not have access to it.`,
+        );
+      return new Response(JSON.stringify(found), {
+        headers: {
+          "content-type": "application/json",
+          "cache-control": "no-store",
+          "x-request-id": state.requestId,
+          "access-control-allow-origin": "*",
+        },
+      });
+    };
+
+    const handleResponsesCompact = createResponsesCompactHandler({
+      db: deps.db,
+      providerAdapters: deps.providerAdapters ?? new Map(),
+      resolveProviderAdapter: deps.resolveProviderAdapter,
+      proxyPreparer: deps.proxyPreparer,
+      stateStore: requestStateStore,
+      poolSelector: deps.poolSelector,
+      networkBindingFactory: deps.networkBindingFactory,
+      snapshotService: deps.snapshotService,
+      resolveOAuthRefresher: deps.resolveOAuthRefresher,
+      oauthRefreshService: deps.oauthRefreshService,
+      // The compact handler completes its attempt through `completeAttempt`,
+      // which marks the request completed and finalizes telemetry itself —
+      // so the afterResponse lifecycle skips it. Without the buffer here the
+      // route would emit no telemetry row at all.
+      telemetryBuffer: deps.telemetryBuffer,
+    });
+
+    const handleSystemone = createSystemoneHandler({
+      db: deps.db,
+      providerAdapters: deps.providerAdapters ?? new Map(),
+      resolveProviderAdapter: deps.resolveProviderAdapter,
+      proxyPreparer: deps.proxyPreparer,
+      stateStore: requestStateStore,
+      poolSelector: deps.poolSelector,
+      networkBindingFactory: deps.networkBindingFactory,
+      snapshotService: deps.snapshotService,
+      resolveOAuthRefresher: deps.resolveOAuthRefresher,
+      oauthRefreshService: deps.oauthRefreshService,
+      // Same reasoning as compact: the handler finalizes telemetry itself, so
+      // the buffer must be threaded here or the route emits no row.
+      telemetryBuffer: deps.telemetryBuffer,
+    });
+
+    const handleWebsearch = createWebsearchHandler({
+      db: deps.db,
+      providerAdapters: deps.providerAdapters ?? new Map(),
+      resolveProviderAdapter: deps.resolveProviderAdapter,
+      proxyPreparer: deps.proxyPreparer,
+      stateStore: requestStateStore,
+      poolSelector: deps.poolSelector,
+      networkBindingFactory: deps.networkBindingFactory,
+      snapshotService: deps.snapshotService,
+      resolveOAuthRefresher: deps.resolveOAuthRefresher,
+      oauthRefreshService: deps.oauthRefreshService,
+      telemetryBuffer: deps.telemetryBuffer,
+    });
+
+    const generationDeps = {
+      db: deps.db,
+      providerAdapters: deps.providerAdapters ?? new Map(),
+      resolveProviderAdapter: deps.resolveProviderAdapter,
+      proxyPreparer: deps.proxyPreparer,
+      stateStore: requestStateStore,
+      poolSelector: deps.poolSelector,
+      networkBindingFactory: deps.networkBindingFactory,
+      snapshotService: deps.snapshotService,
+      resolveOAuthRefresher: deps.resolveOAuthRefresher,
+      oauthRefreshService: deps.oauthRefreshService,
+      telemetryBuffer: deps.telemetryBuffer,
+    };
+    const handleImageGeneration = createImageGenerationHandler(generationDeps);
+    // Mounted with no model behind it on purpose: the surface exists so it can
+    // be finished when an upstream is known, rather than 404ing like a typo.
+    const handleVideoGeneration = createVideoGenerationHandler(generationDeps);
+    // Passthrough surfaces: routed and accounted for, but never interpreted.
+    // No bundled adapter implements embeddings or audio, and inventing a wire
+    // for them would be a guess; what these need to be useful is the route, the
+    // pipeline, and a compatible upstream behind it.
+    const handleEmbedding = createEmbeddingHandler(generationDeps);
+    const handleAudioTranscription = createAudioTranscriptionHandler(generationDeps);
+    const handleAudioSpeech = createAudioSpeechHandler(generationDeps);
+    // Shares the generation dependency bundle: same pipeline, and a count is
+    // neither chat-shaped nor generation-shaped, so it needs exactly the same
+    // routing, leasing, and accounting surface.
+    const handleTokenCount = createTokenCountHandler(generationDeps);
+
+    // Gateway mounting: the pipeline owner composes stages, telemetry, and
+    // cleanup; app only registers the public route table.
+    app.use(
+      transportPipeline.createGateway((routes) => {
+        routes.post("/chat/completions", proxyHandler);
+        routes.post("/responses", proxyHandler);
+        routes.post("/responses/compact", handleResponsesCompact);
+        routes.post("/messages", proxyHandler);
+        // The token counter is a sibling of the chat route on the same model, and
+        // it is forwarded rather than estimated — see dispatch/token-count.ts.
+        routes.post("/messages/count_tokens", handleTokenCount);
+        routes.post("/completions", proxyHandler);
+        routes.post("/systemone", handleSystemone);
+        routes.post("/search", handleWebsearch);
+        routes.post("/images/generations", handleImageGeneration);
+        routes.post("/videos/generations", handleVideoGeneration);
+        routes.post("/embeddings", handleEmbedding);
+        routes.post("/audio/transcriptions", handleAudioTranscription);
+        routes.post("/audio/speech", handleAudioSpeech);
+        routes.get("/models", handleModelsList);
+        routes.get("/models/info", handleModelsDetail);
+        routes.get("/models/*", handleModelsDetail);
+      }),
+    );
+
+    // Operator drain endpoint. Registered before the SPA catch-all and only
+    // when a token is configured, so an unconfigured gateway has no such route
+    // at all. It is a graceful stop for platforms where a catchable signal
+    // cannot be delivered (Windows), and a second signal-free path elsewhere.
+    if (deps.drainToken && deps.triggerDrain) {
+      const drainHandler = createDrainHandler({
+        token: deps.drainToken,
+        triggerDrain: deps.triggerDrain,
+        resolvePeerAddress: (request) => peerAddresses.get(request) ?? null,
+      });
+      app.post("/admin/drain", drainHandler);
+    }
+
+    // Operator backup export. Same double gate as drain and reset, and no
+    // console password: the CLI already runs as the OS user who owns the
+    // database, and a forgotten password must not block the backup that is
+    // meant to rescue the install.
+    if (deps.drainToken) {
+      app.post(
+        "/admin/export-backup",
+        createBackupExportHandler({
+          db: deps.db,
+          token: deps.drainToken,
+          resolvePeerAddress: (request) => peerAddresses.get(request) ?? null,
+          resolveTenantId: async () => {
+            const [row] = await deps.db.select({ id: tenants.id }).from(tenants).limit(1);
+            return row?.id ?? null;
+          },
+        }),
+      );
+    }
+
+    // Console account reset. Same double gate as drain — loopback plus the
+    // token — because it deletes every operator credential on the install.
+    // Only authentication state goes; providers, keys, and routing stay.
+    if (deps.drainToken) {
+      app.post(
+        "/admin/reset-console-account",
+        createConsoleAccountResetHandler({
+          token: deps.drainToken,
+          resolvePeerAddress: (request) => peerAddresses.get(request) ?? null,
+          resetConsoleAccount: () => resetConsoleAuthState(deps.db),
+        }),
+      );
+    }
+
+    // Manual task trigger. Same gate as drain: loopback plus the drain token,
+    // so a leaked token still cannot reach it from outside the host. 202 once
+    // the run has started; 409 when that task is already mid-run, because the
+    // scheduler refuses to overlap a task with itself and a second trigger
+    // would otherwise look like it ran.
+    if (deps.drainToken && deps.scheduledTasks) {
+      const tasks = deps.scheduledTasks;
+      const token = deps.drainToken;
+      app.post("/admin/tasks/:name/run", async ({ request, params }) => {
+        // `policy_rejected`, not `invalid_request`: the request may be perfectly
+        // well-formed. What refused it is where it came from — the client asked
+        // for something only the local host may ask. `invalid_request` told an
+        // operator to fix the body, when the body was never the problem.
+        if (!isLoopbackPeer(peerAddresses.get(request) ?? null))
+          throw new GatewayError("policy_rejected", 403, "task trigger is only available from loopback");
+        if (!tokenMatches(request.headers.get("x-drain-token"), token))
+          throw new GatewayError("authentication_failed", 401, "invalid drain token");
+        const name = params.name;
+        if (!tasks.names().includes(name))
+          throw new GatewayError("invalid_request", 404, `no such task: ${name}`);
+        if (tasks.isRunning(name))
+          throw new GatewayError("invalid_request", 409, `${name} is already running`);
+        void tasks.runNow(name);
+        return new Response(JSON.stringify({ task: name, status: "started" }), {
+          status: 202,
+          headers: { "content-type": "application/json" },
+        });
+      });
+    }
+
+    // `peerAddresses` is populated by the root `beforeHandle` above from
+    // `server.requestIP`. The console login route needs it to key its lockout
+    // bucket, and the trusted-proxy boundary decides whether an
+    // `X-Forwarded-For` hop may override it — the same pair the transport
+    // pipeline receives, so console and proxy agree on client identity.
+    if (deps.consoleApi) {
+      app.use(
+        createConsoleRouter({
+          ...deps.consoleApi,
+          stateStore: requestStateStore,
+          resolvePeerAddress: (request) => peerAddresses.get(request) ?? null,
+          trustedProxyBoundary: deps.trustedProxyBoundary,
+        }),
+      );
+    }
+
+    // Public share API routes are registered before the SPA catch-all, and
+    // enrollment uses only the peer address captured by the trusted boundary.
+    app.use(
+      createShareRouter({
+        db: deps.db,
+        shareStore: new DrizzleShareLinkStore(deps.db),
+        stats: createShareStatsPort({ db: deps.db, redis: deps.consoleApi?.redis }),
+        resolveClientIp: (request) => {
+          const peer = peerAddresses.get(request);
+          return peer
+            ? resolveClientIdentity(request, deps.trustedProxyBoundary, peer)
+            : null;
+        },
+      }),
+    );
+  }
+
+  app.all("/", serveDashboard);
+  app.all("/share", serveDashboard);
+  app.all("/share/*", serveDashboard);
+  app.all("/console", serveDashboard);
+  app.all("/console/*", serveDashboard);
+  // Root-level build output (hashed bundles, chapter art, provider icons,
+  // favicons). Registered last so every real API route above wins.
+  app.all("/*", serveRootFallback);
+  return app;
+}
+
+/**
+ * Route-only convenience wrapper. It earns its place (unlike a bare forwarder)
+ * by defaulting `options` and injecting the discriminant, so callers never
+ * write `mode` for the shell path.
+ */
+export function createGatewayShell(options: Omit<GatewayShellDeps, "mode"> = {}) {
+  return createGatewayApp({ mode: "route-only", ...options });
+}
+
+/**
+ * Elysia route-tree type for Eden Treaty dashboard consumption.
+ *
+
+ * inferred return type.
+ */
+export type App = ReturnType<typeof createGatewayApp>;