@konneal/engine 0.1.4 → 0.2.1

package/workers/worker_public/src/index.ts

@@ -1,4 +1,4 @@
-import { MODELS, datasetsFor, SUGGESTIONS, roleModel } from "./config";
+import { MODELS, datasetsFor, SUGGESTIONS, STARTERS, roleModel } from "./config";
 export { setProfile } from "./profile.ts";
 import { retrieve } from "./pipeline";
 import type { Hit } from "./pipeline";
@@ -19,18 +19,25 @@ export type { Env };
 import { json, err, corsHeaders, withCors, readJson, authenticate, type ApiKey } from "./lib/http";
 
 import { handleSearch } from "./search";
-import { handleEnrich, handleSectionUnit, handleCaption, handleVectors, handleJudge, handleCreateKey, handleListKeys, handleRevokeKey } from "./admin";
+import { handleEnrich, handleSectionUnit, handleCaption, handleVectors, handleJudge, handleCreateKey, handleListKeys, handleRevokeKey, handleKeyUsage } from "./admin";
 import { handleResearch } from "./research";
 import { handleAsk } from "./ask";
-
-// One named handler per HTTP route, declared in ROUTES below and
-// dispatched by lib/router.ts's matchRoute. Adding a route = one entry +
-// its handler; entry order is irrelevant (every pattern is
-// segment-exact). Dual-published routes (/api for the browser, /v1 for
-// keyed integrators) point at the SAME handler — the tier split is the
-// handler's, derived from the path. Mirrored in docs/spec-api.md.
-
-import { matchRoute, type RouteContext, type Route } from "./lib/router";
+import { handleMcp } from "./mcp";
+
+// The HTTP surface is the OpenAPI document (workers/worker_public/openapi.yaml):
+// scripts/gen-openapi-routes.mjs generates openapi-surface.gen.ts from it,
+// and OPENAPI_HANDLERS below binds every operation to its handler. The
+// Record<OpenApiOperationId, …> type makes the binding exhaustive at
+// typecheck, and tests/openapi-surface.test.ts pins the bijection. Adding
+// an endpoint = the yaml entry + one binding + regenerate. Dual-published
+// routes (/api for the browser, /v1 for keyed integrators) bind the SAME
+// handler — the tier split is the handler's, derived from the path.
+// Non-API routes (pages, unit assets, rendered documents) live in
+// INFRA_ROUTES. Mirrored in docs/spec-api.md.
+
+import { matchRoute, routeMatchesPath, type RouteContext, type Route, type RouteHandler } from "./lib/router";
+import { OPENAPI_SURFACE } from "./openapi-surface.gen";
+import type { OpenApiOperationId } from "./openapi-surface.gen";
 import { P } from "./profile.ts";
 
 async function serveIndexPage(c: RouteContext): Promise<Response> {
@@ -97,7 +104,7 @@ async function getSharedRoute(c: RouteContext): Promise<Response> {
 
 async function datasetsRoute(c: RouteContext): Promise<Response> {
   const session = await sessionFrom(c.req, c.env as any);
-  return json({ datasets: datasetsFor(session), suggestions: SUGGESTIONS() }, 200, corsHeaders(c.req));
+  return json({ datasets: datasetsFor(session), suggestions: SUGGESTIONS(), starters: STARTERS() }, 200, corsHeaders(c.req));
 }
 
 async function healthRoute(c: RouteContext): Promise<Response> {
@@ -120,6 +127,12 @@ async function tierFor(c: RouteContext): Promise<{ tier: "anon" | "key" | "membe
   return { tier, key };
 }
 
+async function mcpRoute(c: RouteContext): Promise<Response> {
+  const t = await tierFor(c);
+  if (t instanceof Response) return t;
+  return withCors(await handleMcp(c.env, c.ctx, c.req, t.tier, t.key), corsHeaders(c.req));
+}
+
 async function askRoute(c: RouteContext): Promise<Response> {
   const t = await tierFor(c);
   if (t instanceof Response) return t;
@@ -137,14 +150,18 @@ async function adminStatsRoute(c: RouteContext): Promise<Response> {
   if (!env.ADMIN_TOKEN) return err(501, "admin_disabled", "ADMIN_TOKEN secret is not configured");
   const auth = req.headers.get("authorization") ?? "";
   if (auth !== `Bearer ${env.ADMIN_TOKEN}`) return err(401, "unauthorized", "Invalid admin token");
-  const [byDay, byModel, feedback, convCount] = await Promise.all([
+  const [byDay, byModel, feedback, convCount, cacheMix, durations] = await Promise.all([
     env.DB.prepare("SELECT day, tier, COUNT(*) as n, SUM(ok) as ok FROM queries WHERE day >= date('now','-7 days') GROUP BY day, tier ORDER BY day DESC").all(),
     env.DB.prepare("SELECT model, SUM(requests) as requests FROM spend WHERE day >= date('now','-7 days') GROUP BY model ORDER BY requests DESC").all(),
     env.DB.prepare("SELECT rating, COUNT(*) as n FROM feedback GROUP BY rating").all(),
     env.DB.prepare("SELECT COUNT(*) as n FROM conversations").first(),
+    env.DB.prepare("SELECT COALESCE(cache, 'miss') AS cache, COUNT(*) AS n FROM queries WHERE day >= date('now','-7 days') AND route = 'ask' GROUP BY cache").all(),
+    env.DB.prepare("SELECT duration_ms FROM queries WHERE day >= date('now','-7 days') AND route = 'ask' AND duration_ms IS NOT NULL").all(),
   ]);
+  const ds = (durations.results as any[]).map((r) => r.duration_ms as number).sort((a, b) => a - b);
+  const pct = (q: number) => (ds.length ? ds[Math.min(ds.length - 1, Math.floor(q * ds.length))] : null);
   const totalQueries = (byDay.results as any[]).reduce((a, r) => a + (r.n || 0), 0) || 0;
-  const totalOk = (byDay.results as any[]).reduce((a, r) => a + (r.ok_count || 0), 0) || 0;
+  const totalOk = (byDay.results as any[]).reduce((a, r) => a + (r.ok || 0), 0) || 0;
   const errorRate = totalQueries > 0 ? (((totalQueries - totalOk) / totalQueries) * 100).toFixed(1) : "0";
   ctx.waitUntil(env.DB.batch([
     env.DB.prepare("DELETE FROM queries WHERE day < date('now','-90 days')"),
@@ -156,6 +173,8 @@ async function adminStatsRoute(c: RouteContext): Promise<Response> {
     queries_by_day: byDay.results,
     spend_by_model: byModel.results,
     feedback: feedback.results,
+    cache_mix_7d: cacheMix.results,
+    latency_ms: ds.length ? { n: ds.length, p50: pct(0.5), p95: pct(0.95) } : null,
     conversations: (convCount as any)?.n ?? 0,
     error_rate_pct: errorRate,
     index_version: env.INDEX_VERSION,
@@ -190,7 +209,7 @@ async function absenceRoute(c: RouteContext): Promise<Response> {
       enumerated: { model_nodes: nodes.length, smart_model_chunks: chunks?.n ?? 0 },
       matches: matches.slice(0, 20),
       verdict: matches.length === 0 ? "absent" : "present",
-      scope: `the model plane of ${standard} (all model nodes) — the enumeration is exhaustive over that scope; prose outside the modeled families is not claimed`,
+      scope: `the machine-readable model of ${standard} (all model nodes) — the enumeration is exhaustive over that scope; prose outside the modeled families is not claimed`,
     });
   } catch (e) {
     return err(502, "absence_failed", String(e).slice(0, 200));
@@ -375,54 +394,78 @@ async function researchRoute(c: RouteContext): Promise<Response> {
   return handleResearch(c.env, c.ctx, c.req, session);
 }
 
-export const ROUTES: Route[] = [
+// The non-API routes: the HTML pages, the unit-keyed figure assets and
+// the rendered publication documents. Everything else is generated from
+// the OpenAPI document.
+const INFRA_ROUTES: Route[] = [
   { method: "GET", pattern: "/", handler: serveIndexPage },
   { method: "GET", pattern: "/api/", handler: serveIndexPage },
   { method: "GET", pattern: "/index.html", handler: serveIndexPage },
-  { method: "GET", pattern: "/auth/login", handler: (c) => handleLogin(c.env as any, c.req) },
-  { method: "GET", pattern: "/auth/callback", handler: (c) => handleCallback(c.env as any, c.req) },
-  { method: "GET", pattern: "/auth/me", handler: async (c) => withCors(await handleMe(c.env as any, c.req), corsHeaders(c.req)) },
-  { method: "GET", pattern: "/auth/logout", handler: (c) => handleLogout(c.env as any, c.req) },
-  { method: "POST", pattern: "/auth/logout", handler: (c) => handleLogout(c.env as any, c.req) },
-  { method: "*", pattern: "/api/conversations", handler: conversationsRoute },
-  { method: "*", pattern: "/api/memories", handler: memoriesRoute },
-  { method: "*", pattern: "/api/projects", handler: projectsRoute },
-  { method: "*", pattern: "/api/projects/:id/files", handler: projectFilesRoute },
-  { method: "DELETE", pattern: "/api/project-files/:id", handler: projectFilesRoute },
-  { method: "*", pattern: "/api/memories/:id", handler: memoriesRoute },
-  { method: "*", pattern: "/api/conversations/:id", handler: conversationsRoute },
-  { method: "POST", pattern: "/api/conversations/:id/messages", handler: appendMessageRoute },
-  { method: "POST", pattern: "/api/conversations/:id/share", handler: shareRoute },
-  { method: "GET", pattern: "/api/shared/:slug", handler: getSharedRoute },
-  { method: "GET", pattern: "/api/datasets", handler: datasetsRoute },
-  { method: "GET", pattern: "/health", handler: healthRoute },
-  { method: "GET", pattern: "/v1/admin/stats", handler: adminStatsRoute },
-  { method: "POST", pattern: "/api/ask", handler: askRoute },
-  { method: "POST", pattern: "/v1/ask", handler: askRoute },
-  { method: "POST", pattern: "/api/absence", handler: absenceRoute },
-  { method: "POST", pattern: "/v1/absence", handler: absenceRoute },
-  { method: "POST", pattern: "/api/verify", handler: verifyRoute },
-  { method: "POST", pattern: "/v1/verify", handler: verifyRoute },
-  { method: "POST", pattern: "/api/lane", handler: laneRoute },
-  { method: "POST", pattern: "/v1/lane", handler: laneRoute },
-  { method: "POST", pattern: "/api/search", handler: searchRoute },
-  { method: "POST", pattern: "/v1/search", handler: searchRoute },
-  { method: "POST", pattern: "/api/feedback", handler: feedbackRoute },
-  { method: "POST", pattern: "/admin/enrich", handler: (c) => handleEnrich(c.env, c.ctx, c.req) },
-  { method: "POST", pattern: "/v1/admin/enrich", handler: (c) => handleEnrich(c.env, c.ctx, c.req) },
-  { method: "POST", pattern: "/admin/section", handler: (c) => handleSectionUnit(c.env, c.ctx, c.req) },
-  { method: "POST", pattern: "/v1/admin/section", handler: (c) => handleSectionUnit(c.env, c.ctx, c.req) },
-  { method: "POST", pattern: "/admin/vectors", handler: (c) => handleVectors(c.env, c.req) },
-  { method: "POST", pattern: "/admin/caption", handler: (c) => handleCaption(c.env, c.req) },
   { method: "GET", pattern: "/assets/*", handler: unitAssetRoute },
   { method: "GET", pattern: "/docs/*", handler: docsRoute },
-  { method: "POST", pattern: "/api/research", handler: researchRoute },
-  { method: "POST", pattern: "/v1/research", handler: researchRoute },
-  { method: "POST", pattern: "/admin/judge", handler: (c) => handleJudge(c.env, c.req) },
-  { method: "POST", pattern: "/v1/admin/judge", handler: (c) => handleJudge(c.env, c.req) },
-  { method: "POST", pattern: "/v1/admin/keys", handler: (c) => handleCreateKey(c.env, c.req) },
-  { method: "GET", pattern: "/v1/admin/keys", handler: (c) => handleListKeys(c.env, c.req) },
-  { method: "DELETE", pattern: "/v1/admin/keys/:id", handler: (c) => handleRevokeKey(c.env, c.req, c.params.id) },
+];
+
+const OPENAPI_HANDLERS: Record<OpenApiOperationId, RouteHandler> = {
+  askAnonymous: askRoute,
+  askKeyed: askRoute,
+  search: searchRoute,
+  searchKeyed: searchRoute,
+  absence: absenceRoute,
+  absenceKeyed: absenceRoute,
+  verify: verifyRoute,
+  verifyKeyed: verifyRoute,
+  research: researchRoute,
+  researchKeyed: researchRoute,
+  laneQuery: laneRoute,
+  laneKeyed: laneRoute,
+  mcp: mcpRoute,
+  feedback: feedbackRoute,
+  datasets: datasetsRoute,
+  keyUsage: async (c) => withCors(await handleKeyUsage(c.env, c.req), corsHeaders(c.req)),
+  health: healthRoute,
+  authLogin: (c) => handleLogin(c.env as any, c.req),
+  authCallback: (c) => handleCallback(c.env as any, c.req),
+  authMe: async (c) => withCors(await handleMe(c.env as any, c.req), corsHeaders(c.req)),
+  authLogout: (c) => handleLogout(c.env as any, c.req),
+  authLogoutLink: (c) => handleLogout(c.env as any, c.req),
+  listConversations: conversationsRoute,
+  createConversation: conversationsRoute,
+  getConversation: conversationsRoute,
+  renameConversation: conversationsRoute,
+  deleteConversation: conversationsRoute,
+  appendMessage: appendMessageRoute,
+  shareConversation: shareRoute,
+  getShared: getSharedRoute,
+  listMemories: memoriesRoute,
+  createMemory: memoriesRoute,
+  deleteMemory: memoriesRoute,
+  listProjects: projectsRoute,
+  createProject: projectsRoute,
+  deleteProject: projectsRoute,
+  listProjectFiles: projectFilesRoute,
+  attachProjectFile: projectFilesRoute,
+  detachProjectFile: projectFilesRoute,
+  adminStats: adminStatsRoute,
+  adminListKeys: (c) => handleListKeys(c.env, c.req),
+  adminCreateKey: (c) => handleCreateKey(c.env, c.req),
+  adminRevokeKey: (c) => handleRevokeKey(c.env, c.req, c.params.id),
+  adminEnrich: (c) => handleEnrich(c.env, c.ctx, c.req),
+  adminEnrichAlias: (c) => handleEnrich(c.env, c.ctx, c.req),
+  adminSection: (c) => handleSectionUnit(c.env, c.ctx, c.req),
+  adminSectionAlias: (c) => handleSectionUnit(c.env, c.ctx, c.req),
+  adminVectors: (c) => handleVectors(c.env, c.req),
+  adminCaption: (c) => handleCaption(c.env, c.req),
+  adminJudge: (c) => handleJudge(c.env, c.req),
+  adminJudgeAlias: (c) => handleJudge(c.env, c.req),
+};
+
+export const ROUTES: Route[] = [
+  ...INFRA_ROUTES,
+  ...OPENAPI_SURFACE.map((r) => ({
+    method: r.method,
+    pattern: r.pattern,
+    handler: OPENAPI_HANDLERS[r.operationId],
+  })),
 ];
 
 export default {
@@ -437,6 +480,11 @@ export default {
     if (matched) {
       return matched.route.handler({ env, req, ctx, url, path, params: matched.params });
     }
+    // the surface declares methods per path; a path that exists under
+    // another method is a 405, not a 404
+    if (ROUTES.some((r) => routeMatchesPath(r.pattern, path))) {
+      return err(405, "method_not_allowed", `The path is served, but not with ${req.method}`);
+    }
     return err(404, "not_found", "Unknown route");
   },
 };

package/workers/worker_public/src/lib/router.ts

@@ -1,4 +1,4 @@
 // The router lives with the shared cross-worker modules
 // (workers/shared/router.ts) — re-exported for worker_public's imports.
-export { matchRoute } from "../../../shared/router.ts";
+export { matchRoute, routeMatchesPath } from "../../../shared/router.ts";
 export type { RouteContext, Route, RouteHandler } from "../../../shared/router.ts";

package/workers/worker_public/src/mcp-proto.ts

@@ -0,0 +1,71 @@
+// The MCP protocol surface (JSON-RPC 2.0, streamable HTTP 2025-06-18),
+// dependency-free so plain node can load it for unit tests — the
+// route adapter (mcp.ts) owns the handler wiring.
+export const PROTOCOL_VERSION = "2025-06-18";
+
+export interface McpTool {
+  name: string;
+  description: string;
+  inputSchema: { type: "object"; properties: Record<string, unknown>; required: string[] };
+}
+
+export const TOOLS: McpTool[] = [
+  {
+    name: "ask",
+    description: "Ask the corpus a question; returns a citation-grounded answer with the passages it rests on.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "The question (1-8000 chars)" },
+        lang: { type: "string", description: "Answer language hint (e.g. en, fr)" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "retrieve",
+    description: "Retrieve the top passages for a query (hybrid dense + metadata steering, reranked).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        k: { type: "number", description: "Hits to return (default 5)" },
+      },
+      required: ["query"],
+    },
+  },
+];
+
+export type McpResult =
+  | { ok: true; result: unknown }
+  | { ok: true; accepted: true }
+  | { ok: false; code: number; message: string };
+
+/** Dispatch one JSON-RPC request; `callTool` adapts a tool call to the
+ *  real handlers (the route adapter's job). */
+export function dispatch(
+  method: string | null,
+  params: any,
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>,
+): Promise<McpResult> {
+  switch (method) {
+    case "initialize":
+      return Promise.resolve({ ok: true, result: { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: { name: "rag", version: "1.0.0" } } });
+    case "notifications/initialized":
+    case "ping":
+      return Promise.resolve({ ok: true, accepted: true });
+    case "tools/list":
+      return Promise.resolve({ ok: true, result: { tools: TOOLS } });
+    case "tools/call": {
+      const name = typeof params?.name === "string" ? params.name : "";
+      if (!TOOLS.some((t) => t.name === name)) {
+        return Promise.resolve({ ok: false, code: -32602, message: `unknown tool: ${name}` });
+      }
+      return callTool(name, params?.arguments ?? {}).then(
+        (payload) => ({ ok: true, result: { content: [{ type: "text", text: JSON.stringify(payload) }] } }) as McpResult,
+      );
+    }
+    default:
+      return Promise.resolve({ ok: false, code: -32601, message: `method not found: ${method}` });
+  }
+}

package/workers/worker_public/src/mcp.ts

@@ -0,0 +1,47 @@
+// The public-audience MCP server (streamable HTTP): the same
+// ask/retrieve surfaces as /v1, behind the same API-key tiering, for
+// agent ecosystems. A thin adapter by design — each tool call is an
+// internal Request to the exported route handler, so MCP can never
+// drift from the API contract; the protocol dispatch lives in
+// mcp-proto.ts (dependency-free, unit-tested). The internal-audience
+// server federates both indexes and lives in its own worker, never here.
+import { json, readJson, type ApiKey } from "./lib/http";
+import { P } from "./profile.ts";
+import { dispatch } from "./mcp-proto.ts";
+import type { Env } from "./env.ts";
+import type { Background } from "./ports/runtime.ts";
+
+export async function handleMcp(
+  env: Env,
+  // the port type, not the provider token — the handlers cast at their edge
+  ctx: Background,
+  req: Request,
+  tier: "anon" | "key" | "member",
+  key: ApiKey | null,
+): Promise<Response> {
+  const body = await readJson(req);
+  const method = typeof body?.method === "string" ? body.method : null;
+  const id = body?.id ?? null;
+
+  const out = await dispatch(method, body?.params, async (name, args) => {
+    const inner = new Request("https://internal/mcp", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      // stream:false forces the JSON lane (anon defaults to SSE)
+      body: JSON.stringify({ ...args, stream: false }),
+    });
+    // deferred so plain node can load mcp-proto without the handlers'
+    // .md prompt imports, which only the bundler resolves
+    const res = name === "ask"
+      ? await (await import("./ask")).handleAsk(env, ctx as any, inner, tier, key)
+      : await (await import("./search")).handleSearch(env, ctx as any, inner, tier, key);
+    return res.json().catch(() => ({ error: { message: "tool transport failed", status: res.status } }));
+  });
+
+  if (out.ok && "accepted" in out) return new Response(null, { status: 202 });
+  if (out.ok) {
+    if ((out.result as any)?.serverInfo) (out.result as any).serverInfo.name = `${P().publisher.id}-rag`;
+    return json({ jsonrpc: "2.0", id, result: out.result });
+  }
+  return json({ jsonrpc: "2.0", id, error: { code: out.code, message: out.message } });
+}

package/workers/worker_public/src/openapi-surface.gen.ts

@@ -0,0 +1,318 @@
+// GENERATED from workers/worker_public/openapi.yaml — do not edit.
+// Regenerate: node scripts/gen-openapi-routes.mjs
+export interface OpenApiRoute {
+  method: string
+  pattern: string
+  operationId: string
+}
+
+export type OpenApiOperationId =
+  | "askAnonymous"
+  | "askKeyed"
+  | "search"
+  | "searchKeyed"
+  | "absence"
+  | "absenceKeyed"
+  | "verify"
+  | "verifyKeyed"
+  | "research"
+  | "researchKeyed"
+  | "mcp"
+  | "datasets"
+  | "keyUsage"
+  | "health"
+  | "listConversations"
+  | "createConversation"
+  | "getConversation"
+  | "renameConversation"
+  | "deleteConversation"
+  | "appendMessage"
+  | "shareConversation"
+  | "getShared"
+  | "listMemories"
+  | "createMemory"
+  | "deleteMemory"
+  | "listProjects"
+  | "createProject"
+  | "deleteProject"
+  | "listProjectFiles"
+  | "attachProjectFile"
+  | "detachProjectFile"
+  | "laneQuery"
+  | "laneKeyed"
+  | "feedback"
+  | "adminEnrich"
+  | "adminEnrichAlias"
+  | "adminSection"
+  | "adminSectionAlias"
+  | "adminVectors"
+  | "adminCaption"
+  | "adminJudge"
+  | "adminJudgeAlias"
+  | "adminRevokeKey"
+  | "authMe"
+  | "authLogin"
+  | "authCallback"
+  | "authLogout"
+  | "authLogoutLink"
+  | "adminStats"
+  | "adminListKeys"
+  | "adminCreateKey"
+
+export const OPENAPI_SURFACE: readonly (Omit<OpenApiRoute, "operationId"> & { operationId: OpenApiOperationId })[] = [
+  {
+    "method": "POST",
+    "pattern": "/api/ask",
+    "operationId": "askAnonymous"
+  },
+  {
+    "method": "POST",
+    "pattern": "/v1/ask",
+    "operationId": "askKeyed"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/search",
+    "operationId": "search"
+  },
+  {
+    "method": "POST",
+    "pattern": "/v1/search",
+    "operationId": "searchKeyed"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/absence",
+    "operationId": "absence"
+  },
+  {
+    "method": "POST",
+    "pattern": "/v1/absence",
+    "operationId": "absenceKeyed"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/verify",
+    "operationId": "verify"
+  },
+  {
+    "method": "POST",
+    "pattern": "/v1/verify",
+    "operationId": "verifyKeyed"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/research",
+    "operationId": "research"
+  },
+  {
+    "method": "POST",
+    "pattern": "/v1/research",
+    "operationId": "researchKeyed"
+  },
+  {
+    "method": "POST",
+    "pattern": "/mcp",
+    "operationId": "mcp"
+  },
+  {
+    "method": "GET",
+    "pattern": "/api/datasets",
+    "operationId": "datasets"
+  },
+  {
+    "method": "GET",
+    "pattern": "/v1/usage",
+    "operationId": "keyUsage"
+  },
+  {
+    "method": "GET",
+    "pattern": "/health",
+    "operationId": "health"
+  },
+  {
+    "method": "GET",
+    "pattern": "/api/conversations",
+    "operationId": "listConversations"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/conversations",
+    "operationId": "createConversation"
+  },
+  {
+    "method": "GET",
+    "pattern": "/api/conversations/:id",
+    "operationId": "getConversation"
+  },
+  {
+    "method": "PATCH",
+    "pattern": "/api/conversations/:id",
+    "operationId": "renameConversation"
+  },
+  {
+    "method": "DELETE",
+    "pattern": "/api/conversations/:id",
+    "operationId": "deleteConversation"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/conversations/:id/messages",
+    "operationId": "appendMessage"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/conversations/:id/share",
+    "operationId": "shareConversation"
+  },
+  {
+    "method": "GET",
+    "pattern": "/api/shared/:slug",
+    "operationId": "getShared"
+  },
+  {
+    "method": "GET",
+    "pattern": "/api/memories",
+    "operationId": "listMemories"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/memories",
+    "operationId": "createMemory"
+  },
+  {
+    "method": "DELETE",
+    "pattern": "/api/memories/:id",
+    "operationId": "deleteMemory"
+  },
+  {
+    "method": "GET",
+    "pattern": "/api/projects",
+    "operationId": "listProjects"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/projects",
+    "operationId": "createProject"
+  },
+  {
+    "method": "DELETE",
+    "pattern": "/api/projects/:id",
+    "operationId": "deleteProject"
+  },
+  {
+    "method": "GET",
+    "pattern": "/api/projects/:id/files",
+    "operationId": "listProjectFiles"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/projects/:id/files",
+    "operationId": "attachProjectFile"
+  },
+  {
+    "method": "DELETE",
+    "pattern": "/api/project-files/:id",
+    "operationId": "detachProjectFile"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/lane",
+    "operationId": "laneQuery"
+  },
+  {
+    "method": "POST",
+    "pattern": "/v1/lane",
+    "operationId": "laneKeyed"
+  },
+  {
+    "method": "POST",
+    "pattern": "/api/feedback",
+    "operationId": "feedback"
+  },
+  {
+    "method": "POST",
+    "pattern": "/v1/admin/enrich",
+    "operationId": "adminEnrich"
+  },
+  {
+    "method": "POST",
+    "pattern": "/admin/enrich",
+    "operationId": "adminEnrichAlias"
+  },
+  {
+    "method": "POST",
+    "pattern": "/v1/admin/section",
+    "operationId": "adminSection"
+  },
+  {
+    "method": "POST",
+    "pattern": "/admin/section",
+    "operationId": "adminSectionAlias"
+  },
+  {
+    "method": "POST",
+    "pattern": "/admin/vectors",
+    "operationId": "adminVectors"
+  },
+  {
+    "method": "POST",
+    "pattern": "/admin/caption",
+    "operationId": "adminCaption"
+  },
+  {
+    "method": "POST",
+    "pattern": "/v1/admin/judge",
+    "operationId": "adminJudge"
+  },
+  {
+    "method": "POST",
+    "pattern": "/admin/judge",
+    "operationId": "adminJudgeAlias"
+  },
+  {
+    "method": "DELETE",
+    "pattern": "/v1/admin/keys/:id",
+    "operationId": "adminRevokeKey"
+  },
+  {
+    "method": "GET",
+    "pattern": "/auth/me",
+    "operationId": "authMe"
+  },
+  {
+    "method": "GET",
+    "pattern": "/auth/login",
+    "operationId": "authLogin"
+  },
+  {
+    "method": "GET",
+    "pattern": "/auth/callback",
+    "operationId": "authCallback"
+  },
+  {
+    "method": "POST",
+    "pattern": "/auth/logout",
+    "operationId": "authLogout"
+  },
+  {
+    "method": "GET",
+    "pattern": "/auth/logout",
+    "operationId": "authLogoutLink"
+  },
+  {
+    "method": "GET",
+    "pattern": "/v1/admin/stats",
+    "operationId": "adminStats"
+  },
+  {
+    "method": "GET",
+    "pattern": "/v1/admin/keys",
+    "operationId": "adminListKeys"
+  },
+  {
+    "method": "POST",
+    "pattern": "/v1/admin/keys",
+    "operationId": "adminCreateKey"
+  }
+] as const