@corgelabs/corge 0.0.1 → 1.0.0

package/src/router/service.ts

@@ -0,0 +1,453 @@
+import { getRequestListener } from '@hono/node-server'
+import { defineSecret } from 'firebase-functions/params'
+import { onRequest } from 'firebase-functions/v2/https'
+import { onTaskDispatched } from 'firebase-functions/v2/tasks'
+import { Hono, type Context } from 'hono'
+import { bodyLimit } from 'hono/body-limit'
+import { cors } from 'hono/cors'
+import { z } from 'zod'
+import { coreAttachmentsRoutes, getRegisteredAttachmentTypes, registerAttachmentTypes } from '../attachments'
+import { coreAuthRoutes } from '../auth'
+import { coreChatRoutes, mcpRoute } from '../chat'
+import { CORE_CONFIG, SECRET_NAMES, type AppBindings, type AppEnv, type DbRole } from '../config'
+import { registerCollections, type EntryId } from '../db'
+import { coreEmailRoutes, registerEmailTemplates } from '../emails'
+import { coreFilesRoutes } from '../files'
+import { Core } from '../index'
+import { corePaymentRoutes, registerPlans, registerProducts } from '../payments'
+import {
+  buildHealthRoute, buildRoutesListRoute, buildTaskCancelRoute, buildTaskSignalRoute, buildTaskStatusRoute,
+  TaskWaitDetachedSignal, type RouteRegistryItem, type StepRunner, type WorkflowRuntimeEntry, type WorkflowTaskPayload
+} from '../tasks'
+import { isRespondAsyncPreferred, mergeCoreAndDomainRoutes, RouterGuardEngine } from './guard'
+import {
+  type CoreAppInit, type CoreRouteId, type RouteConfig, type RouteExecutionContext, type RouteMode, type WorkflowRegistryEntry
+} from './schema'
+
+export class RouterService {
+  readonly #core: Core
+  readonly #guard: RouterGuardEngine
+
+  constructor(coreClient: Core) {
+    this.#core = coreClient
+    this.#guard = new RouterGuardEngine(coreClient)
+  }
+
+  readonly applyRateLimit = (
+    ...args: Parameters<RouterGuardEngine['applyRateLimit']>
+  ): ReturnType<RouterGuardEngine['applyRateLimit']> => this.#guard.applyRateLimit(...args)
+
+  readonly authenticateRequest = (
+    ...args: Parameters<RouterGuardEngine['authenticateRequest']>
+  ): ReturnType<RouterGuardEngine['authenticateRequest']> => this.#guard.authenticateRequest(...args)
+
+  #createCloudFunctions = (
+    app: Hono<AppEnv>,
+    devApp: Hono<AppEnv>,
+    workflowRegistry: Record<string, WorkflowRuntimeEntry>
+  ) => {
+    const emailProvider = CORE_CONFIG.emails.provider
+    const paymentProvider = CORE_CONFIG.payments.provider
+    const emailSecrets: string[] = [
+      ...(emailProvider === 'resend' ? ['RESEND_API_KEY', 'EMAIL_WEBHOOK_SECRET'] : []),
+      ...(emailProvider === 'sendgrid' ? ['SENDGRID_API_KEY', 'EMAIL_WEBHOOK_SECRET'] : [])
+    ]
+    const paymentSecrets: string[] = [
+      ...(paymentProvider === 'stripe' ? ['STRIPE_API_KEY', 'STRIPE_WEBHOOK_SECRET', 'STRIPE_SANDBOX_API_KEY', 'STRIPE_SANDBOX_WEBHOOK_SECRET'] : []),
+      ...(paymentProvider === 'dodo' ? ['DODO_API_KEY', 'DODO_WEBHOOK_SECRET', 'DODO_SANDBOX_API_KEY', 'DODO_SANDBOX_WEBHOOK_SECRET'] : [])
+    ]
+    const secretNames = [...new Set<string>([...SECRET_NAMES, ...emailSecrets, ...paymentSecrets, ...CORE_CONFIG.secrets])]
+    const sharedOpts = {
+      region: CORE_CONFIG.region,
+      memory: CORE_CONFIG.cloudRun.memory,
+      cpu: CORE_CONFIG.cloudRun.cpu,
+      secrets: secretNames.map((name) => defineSecret(name))
+    }
+    const httpOpts = { ...sharedOpts, ...CORE_CONFIG.cloudRun.http }
+    const workerOpts = { ...sharedOpts, ...CORE_CONFIG.cloudRun.worker }
+
+    const httpHandler = onRequest(httpOpts, getRequestListener((req) => app.fetch(req)))
+    const devHttpHandler = onRequest(httpOpts, getRequestListener((req) => devApp.fetch(req)))
+
+    const workerConfig = {
+      ...workerOpts,
+      invoker: [CORE_CONFIG.serviceAccount, CORE_CONFIG.computeAccount],
+      retryConfig: { maxAttempts: CORE_CONFIG.tasks.maxAttempts, minBackoffSeconds: 2, maxBackoffSeconds: 20 },
+      rateLimits: { maxConcurrentDispatches: 1000, maxDispatchesPerSecond: 500 }
+    }
+
+    const tasksHandler = onTaskDispatched<WorkflowTaskPayload>(workerConfig, async (req) => {
+      try {
+        await this.#core.internals.workflows.execute({ ...req.data, isDev: false }, workflowRegistry)
+      } catch (err) {
+        if (!this.#core.errors.isStaleWorkerEpochError(err)) throw err
+      }
+    })
+    const devTasksHandler = onTaskDispatched<WorkflowTaskPayload>(workerConfig, async (req) => {
+      try {
+        await this.#core.internals.workflows.execute({ ...req.data, isDev: true }, workflowRegistry)
+      } catch (err) {
+        if (!this.#core.errors.isStaleWorkerEpochError(err)) throw err
+      }
+    })
+
+    const fnName = CORE_CONFIG.gcpProject
+    const functions: Record<string, unknown> = {
+      [fnName]: httpHandler,
+      [`${fnName}-dev`]: devHttpHandler,
+      [`${fnName}-tasks`]: tasksHandler,
+      [`${fnName}-tasks-dev`]: devTasksHandler
+    }
+
+    return { httpHandler, devHttpHandler, tasksHandler, devTasksHandler, functions }
+  }
+
+  #makeCtx = <I, P = Record<string, string>, Q = Record<string, string>>(
+    env: AppBindings,
+    userId: EntryId,
+    role: DbRole,
+    mode: RouteMode,
+    input: I,
+    step: StepRunner = this.#core.internals.workflows.createStepRunner('rest'),
+    c?: Context<AppEnv>,
+    params?: P,
+    query?: Q,
+    rawBody?: string
+  ): RouteExecutionContext<I, P, Q> => ({
+    core: new Core({ env, userId, role, step }),
+    c: c as Context<AppEnv>,
+    env,
+    userId,
+    role,
+    mode,
+    step,
+    allWithRollback: this.#core.internals.workflows.allWithRollback,
+    input,
+    params: (params ?? (c ? c.req.param() : {})) as P,
+    query: (query ?? (c ? c.req.query() : {})) as Q,
+    ...(rawBody !== undefined ? { rawBody } : {})
+  })
+
+  #respondAsync202 = (c: Context<AppEnv> | undefined, taskId: string) => {
+    if (c) {
+      c.header('Preference-Applied', 'respond-async')
+      c.header('Location', `/api/tasks/${taskId}`)
+      return c.json({ taskId, status: 'running', pollUrl: `/api/tasks/${taskId}` }, 202)
+    }
+    return { taskId, status: 'running', pollUrl: `/api/tasks/${taskId}` }
+  }
+
+  #executeRouteCore = async (opts: {
+    key: string
+    wfName: string
+    cfg: RouteConfig
+    mode: RouteMode
+    runTask: (taskInput: unknown, step: StepRunner) => Promise<unknown>
+    parseOut: (out: unknown) => unknown
+    env: AppBindings
+    userId: EntryId
+    role: DbRole
+    parsed: unknown
+    parsedParams: Record<string, string>
+    parsedQuery: Record<string, string>
+    rawBody?: string
+    c?: Context<AppEnv>
+    wait: boolean
+  }): Promise<unknown> => {
+    const { key, wfName, cfg, mode, runTask, parseOut, env, userId, role, parsed, parsedParams, parsedQuery, rawBody, c, wait } =
+      opts
+    await this.#guard.enforceGuard(c, cfg, userId, parsed, role)
+    const dedupeKey =
+      (cfg.idempotencyKey ? cfg.idempotencyKey(parsed, { userId }) : undefined) ??
+      (c?.req.header('idempotency-key')?.trim() || undefined)
+    const runWithStep = <T>(m: RouteMode, fn: (ctx: RouteExecutionContext) => Promise<T> | T): Promise<T> => {
+      const step = this.#core.internals.workflows.createStepRunner(m)
+      return this.#core.internals.context.run({ env, userId, role, step }, async () =>
+        fn(this.#makeCtx(env, userId, role, m, parsed, step, c, parsedParams, parsedQuery, rawBody))
+      )
+    }
+
+    if (mode === 'rest') {
+      const executeRest = () => runWithStep('rest', cfg.handler)
+      const out = dedupeKey
+        ? await this.#guard.withHttpIdempotency(key, dedupeKey, userId, Boolean(env.isDev), executeRest)
+        : await executeRest()
+      return parseOut(out)
+    }
+
+    const cached = cfg.shortCircuit ? await runWithStep('workflow', cfg.shortCircuit) : undefined
+    if (cached !== undefined && cached !== null) return parseOut(cached)
+
+    try {
+      const dispatched = await this.#core.internals.workflows.dispatch(wfName, runTask, parsed, {
+        mode: 'workflow',
+        ...(cfg.timeout !== undefined ? { timeout: cfg.timeout } : {}),
+        ...(dedupeKey ? { dedupeKey } : {}),
+        wait,
+        ...(wait && c ? { maxWaitMs: CORE_CONFIG.limits.maxWaitMs, signal: c.req.raw?.signal } : {}),
+        userId,
+        userRole: role
+      })
+      return !wait ? this.#respondAsync202(c, (dispatched as { taskId: string }).taskId) : parseOut(dispatched)
+    } catch (err) {
+      if (err instanceof TaskWaitDetachedSignal) return this.#respondAsync202(c, err.taskId)
+      throw err
+    }
+  }
+
+  #registerRouteSpecAndTools = (
+    key: string,
+    wfName: string,
+    mode: RouteMode,
+    cfg: RouteConfig,
+    description: string,
+    inputSchema: z.ZodType<any>,
+    runTask: (taskInput: unknown, step: StepRunner) => Promise<unknown>,
+    invoke: WorkflowRegistryEntry['invoke'],
+    workflowRegistry: Record<string, WorkflowRegistryEntry>,
+    routeRegistryItems: RouteRegistryItem[]
+  ): void => {
+    const method = (cfg.method ?? 'POST').toUpperCase()
+    const path = cfg.path ?? `/${key}`
+    const deadlineSeconds = cfg.timeout
+      ? Math.max(15, Math.ceil(this.#core.errors.parseDuration(cfg.timeout, 540_000) / 1000))
+      : undefined
+
+    routeRegistryItems.push({
+      id: key,
+      mode,
+      method,
+      path,
+      ...(mode === 'workflow' || cfg.workflowName ? { workflowName: wfName } : {}),
+      auth: cfg.auth ?? 'user',
+      description,
+      mcp: cfg.mcp === true,
+      tool: cfg.tool !== false,
+      ...(cfg.input ? { input: cfg.input } : {}),
+      ...(cfg.output ? { output: cfg.output } : {}),
+      ...(cfg.guard ? { guard: cfg.guard } : {})
+    })
+
+    if (mode === 'workflow' || cfg.workflowName) {
+      workflowRegistry[wfName] = {
+        name: wfName,
+        description,
+        input: inputSchema,
+        output: cfg.output,
+        mode,
+        ...(deadlineSeconds !== undefined ? { deadlineSeconds } : {}),
+        guard: cfg.guard,
+        runTask,
+        invoke
+      }
+    }
+
+    if (cfg.tool !== false || cfg.mcp === true || mode === 'workflow' || cfg.workflowName) {
+      const registerToolUnder = (toolName: string, mcp: boolean, tool: boolean) =>
+        this.#core.internals.registry.registerWorkflowTool(toolName, {
+          description,
+          input: inputSchema,
+          mcp,
+          tool,
+          execute: (inp, u) => invoke(inp, u)
+        })
+      registerToolUnder(wfName, cfg.mcp === true, cfg.tool !== false)
+      if (key !== wfName && cfg.tool !== false) registerToolUnder(key, false, true)
+    }
+  }
+
+  #buildRouteInvoker = (
+    key: string,
+    cfg: RouteConfig,
+    workflowRegistry: Record<string, WorkflowRegistryEntry>,
+    routeRegistryItems: RouteRegistryItem[]
+  ): WorkflowRegistryEntry['invoke'] => {
+    const mode: RouteMode = cfg.mode ?? 'rest'
+    const wfName = cfg.workflowName ?? key
+    const inputSchema = (cfg.input ?? z.object({})) as z.ZodType<any>
+    const description = cfg.description ?? wfName
+    const parseOut = (out: unknown) => (out instanceof Response ? out : cfg.output ? cfg.output.parse(out) : out)
+
+    const runTask = async (taskInput: unknown, step: StepRunner) => {
+      const current = new Core()
+      const uid = current.userId || CORE_CONFIG.auth.adminUserId
+      return cfg.handler(this.#makeCtx(current.env, uid, current.role, mode, taskInput, step))
+    }
+
+    const invoke = async (
+      rawInput: unknown,
+      userId: EntryId,
+      c?: Context<AppEnv>,
+      explicitRole?: DbRole,
+      opts?: { wait?: boolean; rawBody?: string }
+    ) => {
+      const env = c?.env ?? this.#core.env
+      const authLevel = cfg.auth ?? 'user'
+      const role = this.#core.internals.auth.resolveUserRole(userId, explicitRole ?? (c?.get('userRole') as DbRole | undefined))
+
+      if (authLevel !== 'public' && authLevel !== 'none' && authLevel !== false && !userId) {
+        return this.#core.errors.httpError(401, 'Unauthorized', 'UNAUTHORIZED')
+      }
+      if ((authLevel === 'admin' || authLevel === 'api-key') && role !== 'admin' && userId !== CORE_CONFIG.auth.adminUserId) {
+        return this.#core.errors.httpError(403, 'Forbidden', 'FORBIDDEN')
+      }
+
+      const parsedParams = cfg.params && c ? cfg.params.parse(c.req.param()) : c?.req.param() ?? {}
+      const parsedQuery = cfg.query && c ? cfg.query.parse(c.req.query()) : c?.req.query() ?? {}
+      const parsed = cfg.input ? cfg.input.parse(rawInput ?? {}) : rawInput
+
+      return this.#core.internals.context.run({ env, userId, role }, () =>
+        this.#executeRouteCore({ key, wfName, cfg, mode, runTask, parseOut, env, userId, role, parsed, parsedParams, parsedQuery, rawBody: opts?.rawBody, c, wait: opts?.wait !== false })
+      )
+    }
+
+    this.#registerRouteSpecAndTools(key, wfName, mode, cfg, description, inputSchema, runTask, invoke, workflowRegistry, routeRegistryItems)
+    return invoke
+  }
+
+  #mountRoute = (app: Hono<AppEnv>, cfg: RouteConfig, invoke: WorkflowRegistryEntry['invoke']): void => {
+    const method = (cfg.method ?? 'POST').toLowerCase() as 'get' | 'post' | 'put' | 'patch' | 'delete' | 'all'
+    const routePath = cfg.path ?? '/'
+
+    app[method](routePath, async (c) => {
+      const userId = await this.authenticateRequest(c, cfg)
+      const role = this.#core.internals.auth.resolveUserRole(userId, c.get('userRole') as DbRole | undefined)
+      let rawInput: unknown
+      let rawText: string | undefined
+      if (cfg.rawBody && method !== 'get') {
+        rawText = await c.req.text().catch(() => '')
+        if (cfg.input) {
+          try {
+            rawInput = rawText ? JSON.parse(rawText) : {}
+          } catch {
+            rawInput = {}
+          }
+        } else {
+          rawInput = rawText
+        }
+      } else if (cfg.input && method !== 'get') {
+        rawInput = await c.req.json().catch(() => ({}))
+      }
+      const wait = !(cfg.mode === 'workflow' && isRespondAsyncPreferred(c))
+      const out = await invoke(rawInput, userId, c, role, {
+        wait,
+        ...(rawText !== undefined ? { rawBody: rawText } : {})
+      })
+      return out instanceof Response ? out : c.json(out)
+    })
+  }
+
+  #createHonoApp = (
+    isDev: boolean,
+    allRoutes: Record<string, RouteConfig>,
+    routeInvokers: Map<RouteConfig, WorkflowRegistryEntry['invoke']>
+  ): Hono<AppEnv> => {
+    const app = new Hono<AppEnv>().basePath('/api')
+    app.use(
+      '*',
+      cors({
+        origin: (origin, c) => {
+          if (!origin) return undefined
+          if (
+            CORE_CONFIG.auth.allowedOrigins.some((p: string | RegExp) =>
+              typeof p === 'string' ? p === origin : p.test(origin)
+            )
+          ) {
+            return origin
+          }
+          try {
+            if (origin === new URL(c.req.url).origin) return origin
+          } catch {}
+          return null
+        },
+        credentials: true
+      })
+    )
+    app.use(
+      '*',
+      bodyLimit({
+        maxSize: CORE_CONFIG.limits.maxBodyBytes,
+        onError: () => this.#core.errors.httpError(413, 'Payload too large (max 25MiB)', 'PAYLOAD_TOO_LARGE')
+      })
+    )
+    app.onError((err) => this.#core.errors.toHttpError(err).getResponse())
+    app.use('*', async (c, next) => {
+      const env: AppBindings = { ...this.#core.env, ...(c.env ?? {}), isDev }
+      c.env = env
+      await this.#core.internals.context.run(
+        { env, userId: CORE_CONFIG.auth.adminUserId, role: 'admin' },
+        () => next()
+      )
+    })
+
+    for (const r of Object.values(allRoutes)) this.#mountRoute(app, r, routeInvokers.get(r)!)
+
+    app.all('/mcp', async (c) => {
+      const userId = await this.authenticateRequest(c, { path: '/mcp', auth: 'user' })
+      return mcpRoute(c.req.raw, userId, this.#core.internals.context.getMcpTools())
+    })
+
+    return app
+  }
+
+  createApp = (init: CoreAppInit = {}) => {
+    if (init.emailTemplates) registerEmailTemplates(init.emailTemplates, true)
+    if (init.plans) registerPlans(init.plans, true)
+    if (init.products) registerProducts(init.products, true)
+
+    registerCollections(init.collections ?? {}, true)
+    this.#core.internals.registry.registerAgents(init.agents ?? {}, true)
+    if (init.attachmentTypes) registerAttachmentTypes(init.attachmentTypes)
+    this.#core.internals.registry.registerContextCatalog(init.context ?? [], true)
+    this.#core.internals.registry.clearWorkflowTools()
+
+    const overrides = init.coreRouteOverrides ?? {}
+    const workflowRegistry: Record<string, WorkflowRegistryEntry> = {}
+    const routeRegistryItems: RouteRegistryItem[] = []
+
+    const attachmentTypesDesc = Object.entries(getRegisteredAttachmentTypes())
+      .map(([k, v]) => `${k} (${v.description})`)
+      .join('; ')
+
+    const rawCoreRoutes: Record<CoreRouteId, Partial<RouteConfig>> = {
+      health: buildHealthRoute(),
+      ...coreAuthRoutes,
+      ...coreFilesRoutes,
+      ...coreChatRoutes,
+      ...coreAttachmentsRoutes,
+      ...coreEmailRoutes,
+      ...corePaymentRoutes,
+      'routes.list': buildRoutesListRoute(() => routeRegistryItems),
+      'tasks.status': buildTaskStatusRoute(),
+      'tasks.signal': buildTaskSignalRoute(),
+      'tasks.cancel': buildTaskCancelRoute()
+    }
+
+    const allRoutes = mergeCoreAndDomainRoutes(
+      rawCoreRoutes,
+      overrides,
+      attachmentTypesDesc,
+      init.routes ?? {}
+    )
+    const routeInvokers = new Map<RouteConfig, WorkflowRegistryEntry['invoke']>()
+    for (const [id, r] of Object.entries(allRoutes)) {
+      routeInvokers.set(r, this.#buildRouteInvoker(id, r, workflowRegistry, routeRegistryItems))
+    }
+
+    this.#core.internals.workflows.registerRuntime(workflowRegistry)
+
+    const createApp = (isDev = false) => this.#createHonoApp(isDev, allRoutes, routeInvokers)
+    const app = createApp(false)
+    const devApp = createApp(true)
+    const cloudFunctions = this.#createCloudFunctions(app, devApp, workflowRegistry)
+
+    return {
+      createApp,
+      app,
+      devApp,
+      workflowRegistry,
+      agents: this.#core.internals.registry.getRegisteredAgents(),
+      ...cloudFunctions
+    }
+  }
+}

package/src/tasks/index.ts

@@ -0,0 +1,11 @@
+export * from './schema'
+export { TasksService } from './service'
+export {
+  buildHealthRoute,
+  buildRoutesIntrospection,
+  buildRoutesListRoute,
+  buildTaskCancelRoute,
+  buildTaskSignalRoute,
+  buildTaskStatusRoute,
+  renderApiContractMarkdown
+} from './routes'

package/src/tasks/routes.ts

@@ -0,0 +1,230 @@
+import type { Context } from 'hono'
+import type { z } from 'zod'
+import { CORE_CONFIG, type AppEnv } from '../config'
+import { collectionRegistry, getEffectiveRbac } from '../db'
+import { core } from '../index'
+import { CORE_ROUTE_DEFAULTS, type BaseRouteConfig } from '../router'
+import {
+  signalTaskBody,
+  type RouteIntrospectionItem,
+  type RouteRegistryItem,
+  type RoutesIntrospectionResponse
+} from './schema'
+import { zodToJsonSchemaSafe } from './utils'
+
+export {
+  signalTaskBody,
+  zodToJsonSchemaSafe,
+  type RouteIntrospectionItem,
+  type RouteRegistryItem,
+  type RoutesIntrospectionResponse
+}
+
+const summarizeGuards = (g?: BaseRouteConfig['guard']): string[] => {
+  if (!g) return []
+  const guards: string[] = []
+  if (g.checkFileRef) guards.push('checkFileRef')
+  if (g.checkUserId) guards.push('checkUserId')
+  if (g.checkCollectionField) {
+    guards.push(`checkCollectionField:${g.checkCollectionField.collection}.${g.checkCollectionField.param}`)
+  }
+  if (g.requireEmailVerified) guards.push('requireEmailVerified')
+  if (g.custom) guards.push('custom')
+  return guards
+}
+
+export const buildRoutesIntrospection = (
+  routeItems: RouteRegistryItem[],
+  scope: 'all' | 'custom' | 'core' = 'all'
+): RoutesIntrospectionResponse => {
+  const filtered = routeItems.filter((r) => {
+    const isCore = r.id in CORE_ROUTE_DEFAULTS
+    if (scope === 'core') return isCore
+    if (scope === 'custom') return !isCore
+    return true
+  })
+
+  const routes: RouteIntrospectionItem[] = filtered.map((r) => ({
+    id: r.id,
+    method: r.method,
+    path: `/api${r.path}`,
+    mode: r.mode,
+    ...(r.workflowName ? { workflowName: r.workflowName } : {}),
+    auth: r.auth ?? 'user',
+    description: r.description,
+    mcp: Boolean(r.mcp),
+    tool: r.tool !== false,
+    guards: summarizeGuards(r.guard),
+    inputSchema: zodToJsonSchemaSafe(r.input),
+    outputSchema: zodToJsonSchemaSafe(r.output)
+  }))
+
+  const collections: NonNullable<RoutesIntrospectionResponse['collections']> = {}
+  for (const [name, def] of collectionRegistry) {
+    collections[name] = {
+      relationType: def.userRelation?.type ?? '1:N',
+      rbac: getEffectiveRbac(name) as Record<string, unknown>,
+      schema: zodToJsonSchemaSafe(def.schema)
+    }
+  }
+
+  return {
+    appName: CORE_CONFIG.appName,
+    generatedAt: new Date().toISOString(),
+    routes,
+    collections
+  }
+}
+
+export const renderApiContractMarkdown = (meta: RoutesIntrospectionResponse): string => {
+  const coreRoutes = meta.routes.filter((r) => r.id in CORE_ROUTE_DEFAULTS)
+  const domainRoutes = meta.routes.filter((r) => !(r.id in CORE_ROUTE_DEFAULTS))
+
+  const renderRouteBlock = (r: RouteIntrospectionItem) => {
+    const lines: string[] = [
+      `### ${r.method} ${r.path}`,
+      `- **ID:** \`${r.id}\`${r.workflowName ? ` (Workflow: \`${r.workflowName}\`)` : ''}`,
+      `- **Mode:** \`${r.mode}\` | **Auth:** \`${String(r.auth)}\` | **Guards:** \`${r.guards.join(', ') || 'none'}\` | **MCP:** \`${r.mcp}\` | **Tool:** \`${r.tool}\``,
+      `- **Description:** ${r.description}`
+    ]
+    if (r.inputSchema) {
+      lines.push('', '**Input JSON Schema:**', '```json', JSON.stringify(r.inputSchema, null, 2), '```')
+    }
+    if (r.outputSchema) {
+      lines.push('', '**Output JSON Schema:**', '```json', JSON.stringify(r.outputSchema, null, 2), '```')
+    }
+    return lines.join('\n')
+  }
+
+  const collectionLines: string[] = []
+  for (const [name, col] of Object.entries(meta.collections ?? {})) {
+    collectionLines.push(
+      `### Collection: \`${name}\``,
+      `- **User Relation:** \`${col.relationType}\``,
+      `- **RBAC Matrix:** \`${JSON.stringify(col.rbac ?? {})}\``,
+      ...(col.schema ? ['', '```json', JSON.stringify(col.schema, null, 2), '```'] : [])
+    )
+  }
+
+  return [
+    `# API Contract & Schema Reference — ${meta.appName}`,
+    '',
+    `> **Generated At:** \`${meta.generatedAt}\``,
+    '> **Agent Instruction:** This document is deterministically generated from runtime Zod schemas and route definitions. Treat it as the single source of truth for all HTTP endpoints, payloads, authentication levels, and Firestore collection models.',
+    '',
+    '## 1. Core Protocol & Architecture Conventions',
+    '',
+    '### 1.1. Authentication & Sessions (`auth`)',
+    '- **`public` / `none` / `false`**: No authentication required.',
+    '- **`user`**: Requires `Authorization: Bearer <idToken | SDK_API_KEY>` or HTTP-only `session` cookie.',
+    '- **`strict`**: Requires revocation-checked session verification (`verifySessionCookie(..., true)` / `_system/auth_revocations`).',
+    '- **`admin`**: Requires admin role (`SDK_API_KEY` or admin user claim).',
+    '- **Social OAuth & Account Recovery**: Use `POST /api/auth/sign-in/social` (`google` | `apple`), `POST /api/auth/email/send-verification`, `POST /api/auth/email/verify`, `POST /api/auth/password/forgot`, `POST /api/auth/password/reset`, `POST /api/auth/recovery-email/set`, `POST /api/auth/recovery-email/verify`, `POST /api/auth/account-recovery/initiate`, and `POST /api/auth/account-recovery/complete`.',
+    '',
+    '### 1.2. Content-Addressed Files (`FileRef`)',
+    '- All uploaded files use content-addressed IDs formatted as `<userId>_<sha256_24>` matching `/^[A-Za-z0-9_-]{1,128}_[a-f0-9]{24}$/`.',
+    '- Upload files via `POST /api/files` (`multipart/form-data` field `file`) before passing `ref` or `refs` to downstream endpoints.',
+    '',
+    '### 1.3. Execution Modes (`mode: "rest"` vs `mode: "workflow"`)',
+    '- **`mode: "rest"`**: Synchronous `200 OK` JSON response.',
+    '- **`mode: "workflow"`**: Durable Cloud Tasks workflow. May return `200 OK` directly (if resolved via `shortCircuit` cache or within wait budget) **OR** `202 Accepted` (`{ taskId, status: "running", pollUrl: "/api/tasks/<taskId>" }`) when `Prefer: respond-async` / `?wait=false` is passed.',
+    '- Poll task progress via `GET /api/tasks/:taskId`, send signals via `POST /api/tasks/:taskId/signal`, or cancel via `DELETE /api/tasks/:taskId`.',
+    '',
+    '### 1.4. Thin-Client AI Chat Streaming (`POST /api/chats/:chatId`)',
+    '- Send `{ message: { id?, role: "user", content, parts?, attachments? }, agentId?, model? }` to stream SSE responses and cancel active streams via `POST /api/chats/:chatId/cancel`.',
+    '',
+    '## 2. Core Endpoints Catalog',
+    '',
+    ...coreRoutes.map(renderRouteBlock),
+    '',
+    '## 3. Domain Endpoints Catalog',
+    '',
+    ...(domainRoutes.length > 0 ? domainRoutes.map(renderRouteBlock) : ['_No custom domain routes registered._']),
+    '',
+    '## 4. Registered Firestore Collections Catalog',
+    '',
+    ...collectionLines
+  ].join('\n')
+}
+
+export const buildHealthRoute = () => ({
+  mode: 'rest' as const,
+  handler: async () => ({
+    ok: true,
+    status: 'healthy' as const,
+    service: CORE_CONFIG.appName,
+    env: core.env.isDev ? ('dev' as const) : ('prod' as const),
+    timestamp: new Date().toISOString()
+  })
+})
+
+export const buildRoutesListRoute = (routeItems: () => RouteRegistryItem[]) => ({
+  mode: 'rest' as const,
+  handler: async ({ c }: { c: Context<AppEnv> }) => {
+    const rawScope = c?.req.query('scope')
+    const scope: 'all' | 'custom' | 'core' =
+      rawScope === 'custom' || rawScope === 'core' ? rawScope : 'all'
+    const format = c?.req.query('format')
+    const accept = c?.req.header('accept') ?? ''
+    const meta = buildRoutesIntrospection(routeItems(), scope)
+
+    if (format === 'md' || accept.includes('text/markdown')) {
+      return new Response(renderApiContractMarkdown(meta), {
+        status: 200,
+        headers: { 'content-type': 'text/markdown; charset=utf-8' }
+      })
+    }
+    return meta
+  }
+})
+
+export const buildTaskStatusRoute = () => ({
+  mode: 'rest' as const,
+  handler: async ({ c }: { c: Context<AppEnv> }) => {
+    const taskId = c.req.param('taskId') ?? ''
+    const status = await core.tasks.status(taskId)
+    if (
+      status.status === 'running' ||
+      status.status === 'sleeping' ||
+      status.status === 'waiting_signal' ||
+      status.status === 'compensating'
+    ) {
+      return c.json(
+        {
+          taskId,
+          status: status.status,
+          ...(status.progress ? { progress: status.progress } : {}),
+          pollUrl: `/api/tasks/${taskId}`
+        },
+        202
+      )
+    }
+    if (status.status === 'errored') {
+      return core.errors.httpError(502, status.error ?? 'Workflow task failed', 'WORKFLOW_ERROR')
+    }
+    if (status.status === 'cancelled') {
+      return core.errors.httpError(409, status.error ?? 'Workflow task cancelled', 'TASK_CANCELLED')
+    }
+    if (c.req.query('envelope') === 'true') {
+      return status
+    }
+    return status.response
+  }
+})
+
+export const buildTaskSignalRoute = () => ({
+  mode: 'rest' as const,
+  input: signalTaskBody,
+  handler: async ({ c, input }: { c: Context<AppEnv>; input: z.infer<typeof signalTaskBody> }) => {
+    const taskId = c.req.param('taskId') ?? ''
+    return core.tasks.signal(taskId, input.signal, input.payload)
+  }
+})
+
+export const buildTaskCancelRoute = () => ({
+  mode: 'rest' as const,
+  handler: async ({ c }: { c: Context<AppEnv> }) => {
+    const taskId = c.req.param('taskId') ?? ''
+    return core.tasks.cancel(taskId)
+  }
+})