@kb-labs/gateway-app 0.2.0

package/src/auth/middleware.ts

@@ -0,0 +1,50 @@
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import type { ICache } from '@kb-labs/core-platform';
+import type { AuthContext } from '@kb-labs/gateway-contracts';
+import type { JwtConfig } from '@kb-labs/gateway-auth';
+import { resolveToken, extractBearerToken } from './tokens.js';
+
+// Routes that don't require auth (handle their own auth internally)
+const PUBLIC_ROUTES = new Set([
+  '/health',
+  '/hosts/register',
+  // /hosts/connect and /clients/connect are handled at the HTTP upgrade level
+  // by gateway-ws.ts (raw ws) — they never reach Fastify routing.
+  '/auth/register',
+  '/auth/token',
+  '/auth/refresh',
+  '/internal/dispatch', // has its own x-internal-secret auth
+  '/internal/resolve-host', // has its own x-internal-secret auth
+]);
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    authContext?: AuthContext;
+  }
+}
+
+export function createAuthMiddleware(cache: ICache, jwtConfig: JwtConfig) {
+  return async function authMiddleware(
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ): Promise<void> {
+    const rawPath = new URL(request.url, 'http://localhost').pathname;
+    const routePath = rawPath.replace(/\/+/g, '/').replace(/\/+$/, '') || '/';
+    if (PUBLIC_ROUTES.has(routePath)) {return;}
+
+    // Bearer header takes precedence; fall back to ?access_token= for SSE
+    // connections where browsers cannot set custom headers.
+    const queryToken = (request.query as Record<string, string | undefined>)['access_token'];
+    const token = extractBearerToken(request.headers.authorization) ?? queryToken ?? null;
+    if (!token) {
+      return reply.code(401).send({ error: 'Unauthorized', message: 'Missing Authorization header' });
+    }
+
+    const authContext = await resolveToken(token, cache, jwtConfig);
+    if (!authContext) {
+      return reply.code(401).send({ error: 'Unauthorized', message: 'Invalid token' });
+    }
+
+    request.authContext = authContext;
+  };
+}

package/src/auth/routes.ts

@@ -0,0 +1,57 @@
+/**
+ * Auth routes — public endpoints for agent registration and token management.
+ * POST /auth/register  — register new agent, get clientId + clientSecret
+ * POST /auth/token     — exchange credentials for JWT pair
+ * POST /auth/refresh   — rotate refresh token, get new pair
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { AuthService } from '@kb-labs/gateway-auth';
+import {
+  RegisterRequestSchema,
+  TokenRequestSchema,
+  RefreshRequestSchema,
+} from '@kb-labs/gateway-contracts';
+
+export function registerAuthRoutes(app: FastifyInstance, authService: AuthService): void {
+  // Register new agent
+  app.post('/auth/register', { schema: { tags: ['Auth'], summary: 'Register new agent and get credentials' } }, async (request, reply) => {
+    const parsed = RegisterRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: 'Bad Request', issues: parsed.error.issues });
+    }
+
+    const result = await authService.register(parsed.data);
+    return reply.code(201).send(result);
+  });
+
+  // Issue token pair
+  app.post('/auth/token', { schema: { tags: ['Auth'], summary: 'Issue JWT token pair' } }, async (request, reply) => {
+    const parsed = TokenRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: 'Bad Request', issues: parsed.error.issues });
+    }
+
+    const tokens = await authService.issueTokens(parsed.data.clientId, parsed.data.clientSecret);
+    if (!tokens) {
+      return reply.code(401).send({ error: 'Unauthorized', message: 'Invalid credentials' });
+    }
+
+    return reply.send(tokens);
+  });
+
+  // Refresh token pair
+  app.post('/auth/refresh', { schema: { tags: ['Auth'], summary: 'Refresh JWT token pair' } }, async (request, reply) => {
+    const parsed = RefreshRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: 'Bad Request', issues: parsed.error.issues });
+    }
+
+    const tokens = await authService.refreshTokens(parsed.data.refreshToken);
+    if (!tokens) {
+      return reply.code(401).send({ error: 'Unauthorized', message: 'Invalid or expired refresh token' });
+    }
+
+    return reply.send(tokens);
+  });
+}

package/src/auth/tokens.ts

@@ -0,0 +1,41 @@
+import type { ICache } from '@kb-labs/core-platform';
+import type { AuthContext } from '@kb-labs/gateway-contracts';
+import { AuthService, type JwtConfig } from '@kb-labs/gateway-auth';
+
+/**
+ * Resolve a Bearer token to an AuthContext.
+ * Tries JWT verification first, falls back to static machine token (dev compat).
+ */
+export async function resolveToken(
+  token: string,
+  cache: ICache,
+  jwtConfig: JwtConfig,
+): Promise<AuthContext | null> {
+  const authService = new AuthService(cache, jwtConfig);
+
+  // Try JWT first (v2)
+  const jwtContext = await authService.verify(token);
+  if (jwtContext) {return jwtContext;}
+
+  // Fallback: static machine token in ICache (v1 compat — dev-studio-token etc.)
+  const machineEntry = await cache.get<{ hostId: string; namespaceId: string }>(
+    `host:token:${token}`,
+  );
+  if (machineEntry) {
+    return {
+      type: 'machine',
+      userId: machineEntry.hostId,
+      namespaceId: machineEntry.namespaceId,
+      tier: 'free',
+      permissions: ['host:connect'],
+    };
+  }
+
+  return null;
+}
+
+export function extractBearerToken(authHeader: string | undefined): string | null {
+  if (!authHeader) {return null;}
+  const match = authHeader.match(/^Bearer\s+(.+)$/i);
+  return match ? (match[1] ?? null) : null;
+}

package/src/bootstrap.ts

@@ -0,0 +1,98 @@
+import { logDiagnosticEvent } from '@kb-labs/core-platform';
+import { platform, createServiceBootstrap } from '@kb-labs/core-runtime';
+import { createCorrelatedLogger } from '@kb-labs/shared-http';
+import type { IHostStore } from '@kb-labs/gateway-contracts';
+import { SqliteHostStore } from '@kb-labs/gateway-core';
+import { loadGatewayConfig } from './config.js';
+import { createServer } from './server.js';
+import { HostRegistry } from './hosts/registry.js';
+
+export async function bootstrap(repoRoot: string = process.cwd()): Promise<void> {
+  // 1. Initialize platform (loads .env + adapters from kb.config.json)
+  await createServiceBootstrap({ appId: 'gateway', repoRoot });
+
+  const logger = createCorrelatedLogger(platform.logger, {
+    serviceId: 'gateway',
+    logsSource: 'gateway',
+    layer: 'gateway',
+    service: 'bootstrap',
+    operation: 'gateway.bootstrap',
+  });
+  logger.info('Platform initialized', { repoRoot });
+
+  // 2. Load gateway config — reads gateway.upstreams from kb.config.json
+  const config = await loadGatewayConfig(repoRoot);
+  logger.info('Gateway config loaded', {
+    port: config.port,
+    upstreams: Object.keys(config.upstreams),
+  });
+
+  // 3. Create persistent host store (SQLite if available, otherwise cache-only)
+  let hostStore: IHostStore | undefined;
+  const db = platform.getAdapter<import('@kb-labs/core-platform').ISQLDatabase>('sqlDatabase');
+  if (db) {
+    hostStore = new SqliteHostStore(db);
+    logger.info('Host store: SQLite (persistent)');
+  } else {
+    logger.warn('Host store: none (cache-only, hosts will be lost on restart)');
+  }
+
+  // 4. Create host registry with cache + store
+  const registry = new HostRegistry(platform.cache, hostStore);
+
+  // 5. Restore persisted hosts into cache
+  let restoredCount = 0;
+  try {
+    restoredCount = await registry.restore();
+  } catch (error) {
+    logDiagnosticEvent(platform.logger, {
+      domain: 'registry',
+      event: 'gateway.hosts.restore',
+      level: 'error',
+      reasonCode: 'registry_restore_failed',
+      message: 'Failed to restore gateway host registry',
+      outcome: 'failed',
+      error: error instanceof Error ? error : new Error(String(error)),
+      serviceId: 'gateway',
+      evidence: {
+        persistentStore: !!hostStore,
+      },
+    });
+    throw error;
+  }
+  if (restoredCount > 0) {
+    logger.info('Restored hosts from store', { count: restoredCount });
+  }
+
+  // 6. Seed static tokens into cache so resolveToken() accepts them
+  for (const [token, entry] of Object.entries(config.staticTokens)) {
+    await platform.cache.set(`host:token:${token}`, entry);
+    logger.info('Static token seeded', { hostId: entry.hostId, namespaceId: entry.namespaceId });
+  }
+
+  // 7. Build JWT config — secret from env, required in production
+  const jwtSecret = process.env.GATEWAY_JWT_SECRET;
+  if (!jwtSecret) {
+    logger.warn('GATEWAY_JWT_SECRET not set — using insecure default (dev only!)');
+  }
+  const jwtConfig = { secret: jwtSecret ?? 'dev-insecure-secret-change-me' };
+
+  // 8. Create server with injected registry
+  const server = await createServer(config, platform.cache, platform.logger, jwtConfig, registry);
+
+  // 9. Listen
+  const address = await server.listen({ port: config.port, host: '0.0.0.0' });
+  logger.info('Gateway listening', { address });
+
+  // 10. Graceful shutdown
+  const shutdown = async (signal: string) => {
+    logger.warn('Received shutdown signal', { signal });
+    await platform.shutdown();
+    await server.close();
+    logger.info('Gateway shutdown complete');
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}

package/src/clients/subscription-registry.ts

@@ -0,0 +1,137 @@
+/**
+ * @module gateway-app/clients/subscription-registry
+ *
+ * Tracks which client connections are subscribed to which executions.
+ * Gateway broadcasts ExecutionEvents to all subscribers of an execution.
+ *
+ * Lifecycle:
+ *   - client sends client:subscribe   → subscribe(connectionId, executionId)
+ *   - client sends client:unsubscribe → unsubscribe(connectionId, executionId)
+ *   - execution emits event           → broadcast(executionId, event) → all subscribers
+ *   - client disconnects              → removeConnection(connectionId) → cleanup
+ *
+ * The initiator of POST /api/v1/execute is NOT auto-subscribed here —
+ * they receive events inline via ndjson stream. This registry is for
+ * secondary observers joining an in-flight execution.
+ */
+
+import type { WebSocket } from '@fastify/websocket';
+import type { ExecutionEventMessage } from '@kb-labs/gateway-contracts';
+
+export interface ISubscriptionRegistry {
+  subscribe(connectionId: string, executionId: string): void;
+  unsubscribe(connectionId: string, executionId: string): void;
+  getSubscribers(executionId: string): ReadonlySet<string>;
+  getSubscriptions(connectionId: string): ReadonlySet<string>;
+  /** Called on client disconnect. Returns executionIds that now have zero subscribers. */
+  removeConnection(connectionId: string): string[];
+  broadcast(executionId: string, event: ExecutionEventMessage): void;
+}
+
+export class SubscriptionRegistry implements ISubscriptionRegistry {
+  /** executionId → Set<connectionId> */
+  private readonly byExecution = new Map<string, Set<string>>();
+  /** connectionId → Set<executionId> */
+  private readonly byConnection = new Map<string, Set<string>>();
+  /** connectionId → WebSocket (for sending events) */
+  private readonly sockets = new Map<string, WebSocket>();
+
+  /** Register a WebSocket for a connection. Must be called before subscribe(). */
+  registerSocket(connectionId: string, socket: WebSocket): void {
+    this.sockets.set(connectionId, socket);
+  }
+
+  /** Remove a connection's socket on disconnect. */
+  removeSocket(connectionId: string): void {
+    this.sockets.delete(connectionId);
+  }
+
+  subscribe(connectionId: string, executionId: string): void {
+    let executionSubs = this.byExecution.get(executionId);
+    if (!executionSubs) {
+      executionSubs = new Set();
+      this.byExecution.set(executionId, executionSubs);
+    }
+    executionSubs.add(connectionId);
+
+    let connectionSubs = this.byConnection.get(connectionId);
+    if (!connectionSubs) {
+      connectionSubs = new Set();
+      this.byConnection.set(connectionId, connectionSubs);
+    }
+    connectionSubs.add(executionId);
+  }
+
+  unsubscribe(connectionId: string, executionId: string): void {
+    this.byExecution.get(executionId)?.delete(connectionId);
+    this.byConnection.get(connectionId)?.delete(executionId);
+
+    // GC empty sets
+    if (this.byExecution.get(executionId)?.size === 0) {
+      this.byExecution.delete(executionId);
+    }
+    if (this.byConnection.get(connectionId)?.size === 0) {
+      this.byConnection.delete(connectionId);
+    }
+  }
+
+  getSubscribers(executionId: string): ReadonlySet<string> {
+    return this.byExecution.get(executionId) ?? new Set();
+  }
+
+  getSubscriptions(connectionId: string): ReadonlySet<string> {
+    return this.byConnection.get(connectionId) ?? new Set();
+  }
+
+  removeConnection(connectionId: string): string[] {
+    const subscriptions = this.byConnection.get(connectionId);
+    if (!subscriptions) {
+      this.sockets.delete(connectionId);
+      return [];
+    }
+
+    const orphaned: string[] = [];
+    for (const executionId of subscriptions) {
+      const subs = this.byExecution.get(executionId);
+      if (subs) {
+        subs.delete(connectionId);
+        if (subs.size === 0) {
+          this.byExecution.delete(executionId);
+          orphaned.push(executionId);
+        }
+      }
+    }
+
+    this.byConnection.delete(connectionId);
+    this.sockets.delete(connectionId);
+    return orphaned;
+  }
+
+  broadcast(executionId: string, event: ExecutionEventMessage): void {
+    const subscribers = this.byExecution.get(executionId);
+    if (!subscribers || subscribers.size === 0) { return; }
+
+    const payload = JSON.stringify(event);
+    for (const connectionId of subscribers) {
+      const socket = this.sockets.get(connectionId);
+      if (socket && socket.readyState === socket.OPEN) {
+        socket.send(payload);
+      }
+    }
+  }
+
+  get connectionCount(): number {
+    return this.byConnection.size;
+  }
+
+  get subscriptionCount(): number {
+    let total = 0;
+    for (const subs of this.byExecution.values()) {
+      total += subs.size;
+    }
+    return total;
+  }
+}
+
+/** Singleton — shared across Gateway process. */
+export const subscriptionRegistry = new SubscriptionRegistry();

package/src/clients/ws-handler.ts

@@ -0,0 +1,196 @@
+/**
+ * @module gateway-app/clients/ws-handler
+ *
+ * WebSocket handler for observer clients (CLI, Studio, IDE).
+ * Endpoint: GET /clients/connect (requires Bearer JWT)
+ *
+ * Supports:
+ *   - client:subscribe   — start receiving events for an executionId
+ *   - client:unsubscribe — stop receiving events
+ *   - client:cancel      — cancel an execution (proxied to ExecutionRegistry)
+ *
+ * Auth: same Bearer JWT as HTTP endpoints (user or machine token, NOT host machine token).
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { WebSocket } from 'ws';
+
+interface WsRequest {
+  headers: { authorization?: string };
+  url?: string;
+}
+import type { ICache, ILogger } from '@kb-labs/core-platform';
+import type { CancellationReason } from '@kb-labs/core-contracts';
+import {
+  ClientHelloSchema,
+  ClientSubscribeSchema,
+  ClientUnsubscribeSchema,
+  ClientCancelSchema,
+  CLIENT_PROTOCOL_VERSION,
+  type ClientOutboundMessage,
+} from '@kb-labs/gateway-contracts';
+import { type JwtConfig } from '@kb-labs/gateway-auth';
+import { extractBearerToken, resolveToken } from '../auth/tokens.js';
+import { executionRegistry } from '../execute/execution-registry.js';
+import { subscriptionRegistry } from './subscription-registry.js';
+
+const HELLO_TIMEOUT_MS = 5_000;
+
+function send(ws: WebSocket, msg: ClientOutboundMessage): void {
+  if (ws.readyState === ws.OPEN) {
+    ws.send(JSON.stringify(msg));
+  }
+}
+
+export function createClientWsHandler(cache: ICache, jwtConfig: JwtConfig, logger: ILogger) {
+  return async function clientWsHandler(
+    socket: WebSocket,
+    request: WsRequest,
+  ): Promise<void> {
+    // 1. Auth — Bearer JWT required (user or machine token)
+    const queryToken = new URL(request.url ?? '/', 'http://localhost').searchParams.get('access_token');
+    const token = extractBearerToken(request.headers.authorization)
+      ?? queryToken
+      ?? null;
+
+    if (!token) {
+      socket.close(1008, 'Missing Authorization');
+      return;
+    }
+
+    const authContext = await resolveToken(token, cache, jwtConfig);
+    if (!authContext) {
+      socket.close(1008, 'Invalid token');
+      return;
+    }
+
+    const connectionId = randomUUID();
+
+    // 2. Wait for client:hello (with timeout)
+    let helloDone = false;
+
+    await new Promise<void>((resolve, reject) => {
+      const helloTimeout = setTimeout(() => {
+        if (!helloDone) {
+          helloDone = true;
+          socket.close(1008, 'Hello timeout');
+          reject(new Error('Hello timeout'));
+        }
+      }, HELLO_TIMEOUT_MS);
+
+      socket.once('message', (raw) => {
+        if (helloDone) { return; }
+        helloDone = true;
+        clearTimeout(helloTimeout);
+
+        try {
+          const msg = ClientHelloSchema.parse(JSON.parse(raw.toString()));
+          void msg; // clientVersion logged below if needed
+          resolve();
+        } catch {
+          socket.close(1008, 'Invalid hello message');
+          reject(new Error('Invalid client:hello'));
+        }
+      });
+    }).catch(() => {
+      // socket already closed
+    });
+
+    if (!helloDone || socket.readyState !== socket.OPEN) { return; }
+
+    // 3. Register connection
+    subscriptionRegistry.registerSocket(connectionId, socket);
+
+    send(socket, {
+      type: 'client:connected',
+      protocolVersion: CLIENT_PROTOCOL_VERSION,
+      connectionId,
+    });
+
+    logger.debug('Client connected', { connectionId, namespaceId: authContext.namespaceId });
+
+    // 4. Message handler
+    socket.on('message', (raw) => {
+      let parsed: { type: string };
+      try {
+        parsed = JSON.parse(raw.toString()) as { type: string };
+      } catch {
+        send(socket, {
+          type: 'client:error',
+          code: 'INVALID_MESSAGE',
+          message: 'Malformed JSON',
+        });
+        return;
+      }
+
+      switch (parsed.type) {
+        case 'client:subscribe': {
+          const result = ClientSubscribeSchema.safeParse(parsed);
+          if (!result.success) {
+            send(socket, { type: 'client:error', code: 'INVALID_MESSAGE', message: 'Invalid subscribe message' });
+            return;
+          }
+          const { executionId } = result.data;
+
+          // Verify execution exists and belongs to this namespace
+          const execution = executionRegistry.get(executionId);
+          if (!execution) {
+            send(socket, { type: 'client:error', code: 'EXECUTION_NOT_FOUND', message: `Execution ${executionId} not found`, executionId });
+            return;
+          }
+          if (execution.namespaceId !== authContext.namespaceId) {
+            send(socket, { type: 'client:error', code: 'FORBIDDEN', message: 'Execution belongs to another namespace', executionId });
+            return;
+          }
+
+          subscriptionRegistry.subscribe(connectionId, executionId);
+          break;
+        }
+
+        case 'client:unsubscribe': {
+          const result = ClientUnsubscribeSchema.safeParse(parsed);
+          if (!result.success) {
+            send(socket, { type: 'client:error', code: 'INVALID_MESSAGE', message: 'Invalid unsubscribe message' });
+            return;
+          }
+          subscriptionRegistry.unsubscribe(connectionId, result.data.executionId);
+          break;
+        }
+
+        case 'client:cancel': {
+          const result = ClientCancelSchema.safeParse(parsed);
+          if (!result.success) {
+            send(socket, { type: 'client:error', code: 'INVALID_MESSAGE', message: 'Invalid cancel message' });
+            return;
+          }
+          const { executionId, reason } = result.data;
+
+          const execution = executionRegistry.get(executionId);
+          if (!execution) {
+            send(socket, { type: 'client:error', code: 'EXECUTION_NOT_FOUND', message: `Execution ${executionId} not found`, executionId });
+            return;
+          }
+          if (execution.namespaceId !== authContext.namespaceId) {
+            send(socket, { type: 'client:error', code: 'FORBIDDEN', message: 'Execution belongs to another namespace', executionId });
+            return;
+          }
+
+          const cancelled = executionRegistry.cancel(executionId, (reason ?? 'user') as CancellationReason);
+          if (!cancelled) {
+            send(socket, { type: 'client:error', code: 'CANCEL_FAILED', message: 'Execution already completed or cancelled', executionId });
+          }
+          break;
+        }
+
+        default:
+          send(socket, { type: 'client:error', code: 'INVALID_MESSAGE', message: `Unknown message type: ${String(parsed.type)}` });
+      }
+    });
+
+    // 5. Disconnect cleanup
+    socket.on('close', () => {
+      subscriptionRegistry.removeConnection(connectionId);
+      logger.debug('Client disconnected', { connectionId });
+    });
+  };
+}

package/src/config.ts

@@ -0,0 +1,20 @@
+import { findNearestConfig, readJsonWithDiagnostics } from '@kb-labs/core-config';
+import { GatewayConfigSchema, type GatewayConfig } from '@kb-labs/gateway-contracts';
+
+export async function loadGatewayConfig(repoRoot: string): Promise<GatewayConfig> {
+  const { path: configPath } = await findNearestConfig({
+    startDir: repoRoot,
+    filenames: ['.kb/kb.config.json', 'kb.config.json'],
+  });
+
+  if (!configPath) {
+    return GatewayConfigSchema.parse({});
+  }
+
+  const result = await readJsonWithDiagnostics<{ gateway?: unknown }>(configPath);
+  if (!result.ok || !result.data.gateway) {
+    return GatewayConfigSchema.parse({});
+  }
+
+  return GatewayConfigSchema.parse(result.data.gateway);
+}

package/src/docs/routes.ts

@@ -0,0 +1,70 @@
+/**
+ * @module gateway-app/docs/routes
+ * Aggregated OpenAPI documentation endpoints.
+ *
+ * GET /openapi-merged.json — merged spec from all upstream services
+ * GET /docs-all            — Swagger UI pointing at the merged spec
+ */
+
+import type { FastifyInstance } from 'fastify';
+import { mergeOpenAPISpecs } from '@kb-labs/core-registry';
+import type { ICache } from '@kb-labs/core-platform';
+
+const MERGED_CACHE_KEY = '__gateway_merged_openapi';
+const MERGED_CACHE_TTL = 30_000; // 30 second cache
+
+const UPSTREAM_SPEC_URLS = [
+  'http://localhost:5050/openapi.json',
+  'http://localhost:7778/openapi.json',
+];
+
+export function registerAggregatedDocsRoutes(app: FastifyInstance, cache?: ICache): void {
+  // Merged OpenAPI spec from all upstreams
+  app.get('/openapi-merged.json', async (_req, reply) => {
+    // Try cache first
+    if (cache) {
+      try {
+        const hit = await cache.get<Record<string, unknown>>(MERGED_CACHE_KEY);
+        if (hit) {
+          return reply.send(hit);
+        }
+      } catch { /* cache miss */ }
+    }
+
+    // Fetch all upstream specs in parallel
+    const results = await Promise.allSettled(
+      UPSTREAM_SPEC_URLS.map((url) =>
+        fetch(url, { signal: AbortSignal.timeout(3000) }).then((r) => r.json()),
+      ),
+    );
+
+    const specs = results
+      .filter((r): r is PromiseFulfilledResult<unknown> => r.status === 'fulfilled')
+      .map((r) => r.value);
+
+    const merged = mergeOpenAPISpecs(specs as Parameters<typeof mergeOpenAPISpecs>[0]);
+
+    // Cache result
+    if (cache) {
+      try {
+        await cache.set(MERGED_CACHE_KEY, merged as unknown as Record<string, unknown>, MERGED_CACHE_TTL);
+      } catch { /* cache write failure is non-critical */ }
+    }
+
+    return reply.send(merged);
+  });
+
+  // Second Swagger UI pointing at merged spec
+  // Registered last so /docs (gateway-native) is already bound at this point
+  app.register(async function docsAll(scope) {
+    const swaggerUi = await import('@fastify/swagger-ui');
+    await scope.register(swaggerUi.default ?? swaggerUi, {
+      routePrefix: '/docs-all',
+      uiConfig: {
+        url: '/openapi-merged.json',
+        docExpansion: 'list',
+        deepLinking: true,
+      },
+    });
+  });
+}