@konneal/engine 0.1.4 → 0.2.1

package/dist/worker_public/src/profile.js

@@ -1,7 +1,7 @@
 import {
   P,
   setProfile
-} from "../../chunk-35ODH64W.js";
+} from "../../chunk-Q327B27J.js";
 export {
   P,
   setProfile

package/dist/worker_public/src/refusal.js

@@ -1,8 +1,8 @@
 import {
   canonicalRefusal,
   refusalAnswer
-} from "../../chunk-CAEHIVG5.js";
-import "../../chunk-35ODH64W.js";
+} from "../../chunk-WGXATDXY.js";
+import "../../chunk-Q327B27J.js";
 export {
   canonicalRefusal,
   refusalAnswer

package/dist/worker_public/src/requestScope.js

@@ -1,9 +1,9 @@
 import {
   requestSalt,
   resolveRequestScope
-} from "../../chunk-EHJEELVB.js";
-import "../../chunk-OCNLV7Q7.js";
-import "../../chunk-35ODH64W.js";
+} from "../../chunk-LNSDBEKS.js";
+import "../../chunk-Q6LI4T7M.js";
+import "../../chunk-Q327B27J.js";
 export {
   requestSalt,
   resolveRequestScope

package/docs/spec-api.md

@@ -1,9 +1,13 @@
 # API surface spec
 
-The worker's complete HTTP inventory, mirrored 1:1 by the `ROUTES`
-registry in `workers/worker_public/src/index.ts` (dispatched by
-`lib/router.ts`'s `matchRoute`). Adding a route = one registry entry +
-its handler; this document changes with it. Request/response details
+The worker's complete HTTP inventory. The API routes are generated from
+the OpenAPI document `workers/worker_public/openapi.yaml`
+(`scripts/gen-openapi-routes.mjs` → `src/openapi-surface.gen.ts`), and
+`index.ts`'s `OPENAPI_HANDLERS` binds every operation to its handler;
+`tests/openapi-surface.test.ts` pins the bijection, and the non-API
+routes (pages, unit assets, rendered documents) are declared in
+`INFRA_ROUTES`. Adding a route = the yaml entry + one handler binding +
+regenerate; this document changes with it. Request/response details
 beyond the inventory: [API.md](API.md).
 
 ## Conventions
@@ -27,13 +31,19 @@ beyond the inventory: [API.md](API.md).
 | `/auth/callback` | GET | none | `handleCallback` | OIDC callback; mints the session cookie; bubble mode postMessages the token to the validated origin. |
 | `/auth/me` | GET | session | `handleMe` | `{ authenticated, name, email, roles, tier }`. |
 | `/auth/logout` | GET, POST | none | `handleLogout` | Clears the session. |
-| `/api/conversations` | * | session | `conversationsRoute` → `handleConversations` | List (GET) / create (POST) / delete (DELETE) the signed-in user's conversations. |
-| `/api/conversations/:id` | * | session (owner) | `conversationsRoute` | One conversation (GET) / delete (DELETE). |
+| `/api/conversations` | GET, POST | session | `conversationsRoute` → `handleConversations` | List / create the signed-in member's conversations. |
+| `/api/conversations/:id` | GET, PATCH, DELETE | session (owner) | `conversationsRoute` | One conversation: read / rename / delete. |
 | `/api/conversations/:id/messages` | POST | session (owner) | `appendMessageRoute` → `handleAppendMessage` | Append a message turn. |
 | `/api/conversations/:id/share` | POST | session (owner) | `shareRoute` → `handleShareConversation` | Publish a conversation to an unlisted share slug. (Was shadowed by the compound conversations branch pre-route-table — the pattern inventory made the collision visible and fixed it.) |
 | `/api/shared/:slug` | GET | none | `getSharedRoute` → `handleGetShared` | Read a shared conversation. |
+| `/api/projects` | GET, POST | session | `projectsRoute` → `handleProjects` | Contexts (#187): list / create / rename by id / file a conversation by `conversation_id` + `project_id` (null unfiles — membership-as-move). |
+| `/api/projects/:id` | DELETE | session (owner) | `projectsRoute` | Delete a context: files detached, conversations returned to the general list. |
+| `/api/projects/:id/files` | GET, POST | session (owner) | `projectFilesRoute` → `handleProjectFiles` | List / attach (or replace by id) a context's files; POST names the context by `project_id` in the body. |
+| `/api/project-files/:id` | DELETE | session (owner) | `projectFilesRoute` | Detach one file. |
 | `/api/datasets` | GET | none (session enriches) | `datasetsRoute` | The corpus catalog + starter questions (the UI's empty state — content from the API, never hardcoded in the client). Session-gated datasets carry `requires` (the estate permission, e.g. `the ai-preview permission (id.oimlsmart.org)`) and `enabled` reflects the permission, not just login. |
-| `/api/memories` | * | session | `memoriesRoute` → `handleMemories` | Personalized memory files (#171): GET list / POST create-update (≤10 files × 8k chars) / DELETE by id — every query owner-filtered by the session sub. Selected ids ride `/api/ask` as `memories: [id…]` (≤4 per ask, injected as one bounded trusted-user-facts note; the selection salts the answer cache). |
+| `/api/memories` | GET, POST | session | `memoriesRoute` → `handleMemories` | Personalized memory files (#171): GET list / POST create-or-replace by id (≤10 files × 8k chars) — every query owner-filtered by the session sub. Selected ids ride `/api/ask` as `memories: [id…]` (≤4 per ask, injected as one bounded trusted-user-facts note; the selection salts the answer cache). |
+| `/api/memories/:id` | DELETE | session (owner) | `memoriesRoute` | Delete one memory file. |
+| `/mcp` | POST | tier | `mcpRoute` → `handleMcp` | The Model Context Protocol server (JSON-RPC 2025-06-18, streamable HTTP); tools: `ask`, `retrieve`. |
 | `/health` | GET | none | `healthRoute` | Liveness + deployed `index_version` (the deploy-drift guard reads this). |
 | `/api/ask`, `/v1/ask` | POST | tier | `askRoute` → `handleAsk` | The answer contract: streamed or JSON answer, citations, typed blocks, context echo. Quotas per tier. Optional `datasets: [id…]` narrows the corpora searched (server-intersected with session permissions; an explicitly-empty list is a 400); optional `memories: [id…]` selects the member's memory files to inject. Both selections salt the answer cache — a scoped or memory-flavored answer never serves a plain ask. |
 | `/api/absence`, `/v1/absence` | POST | tier | `absenceRoute` | Provable absence: exhaustive enumeration over a standard's model plane; `{ verdict: absent \| present, enumerated, matches }`. |
@@ -50,10 +60,11 @@ beyond the inventory: [API.md](API.md).
 | `/admin/judge`, `/v1/admin/judge` | POST | ADMIN_TOKEN | `handleJudge` | LLM-as-judge scoring (promotion gates). |
 | `/v1/admin/keys` | POST | ADMIN_TOKEN | `handleCreateKey` | Issue an API key (`oiml_<hex>`, shown once). |
 | `/v1/admin/keys` | GET | ADMIN_TOKEN | `handleListKeys` | List keys (no secrets). |
+| `/v1/admin/keys/:id` | DELETE | ADMIN_TOKEN | `handleRevokeKey` | Revoke a key. |
 | `/v1/admin/stats` | GET | ADMIN_TOKEN | `adminStatsRoute` | 7-day telemetry: queries/day/tier, spend by model, feedback, error rate; prunes >90d rows. |
 | `/docs/:slug.html`, `/docs/:slug.anchors.json` | GET | public | `docsRoute` | Rendered publication documents (metanorma-mirror layer 1) served from R2 under `docs/`, immutable cache; the anchors map (clause number → heading anchor id) powers citation deep links. Public OIML content only. |
 | `/admin/enrich` | POST | ADMIN_TOKEN | `handleEnrich` | modes: default (context+embed+upsert in place), `context` (generate only, KV-cached), `ab` (generate at an explicit effort with NO side effects — the experiment lane; accepts an admin-gated prompt override for judged comparisons). |
-| anything else | any | — | — | `404 not_found`. |
+| anything else | any | — | — | `404 not_found`; a known path under an undeclared method answers `405 method_not_allowed`. |
 
 ## Request semantics worth naming
 
@@ -63,11 +74,14 @@ beyond the inventory: [API.md](API.md).
 ## Dispatch semantics
 
 `fetch` = OPTIONS preflight (204) → `matchRoute(ROUTES, method, path)` →
-handler with `{ env, req, ctx, url, path, params }` → 404. Patterns are
-segment-exact with `:param` capture and a trailing `*` wildcard
-(`/assets/*`); entry order is irrelevant because no pattern overlaps
-another. The `/api` and `/v1` twins deliberately share one handler so
-the tier split can never diverge between the two publications.
+handler with `{ env, req, ctx, url, path, params }` → 405 when the path
+is served under another method → 404. `ROUTES` is `INFRA_ROUTES` +
+`OPENAPI_SURFACE` (generated from the yaml) mapped through
+`OPENAPI_HANDLERS`. Patterns are segment-exact with `:param` capture and
+a trailing `*` wildcard (`/assets/*`); entry order is irrelevant because
+no pattern overlaps another. The `/api` and `/v1` twins deliberately
+share one handler so the tier split can never diverge between the two
+publications.
 
 ## Isolation invariants (binding lint, `npm run lint:wrangler`)
 

package/package.json

@@ -14,7 +14,8 @@
     "test:ui": "node tests/ui.mjs",
     "test:bridge": "node --test tests/bridge.test.mjs",
     "test:units": "node --test --experimental-strip-types tests/*.test.ts",
-    "build": "rm -rf dist dist-types && esbuild workers/worker_mcp/src/index.ts workers/worker_public/src/index.ts workers/worker_public/src/config.ts workers/worker_public/src/refusal.ts workers/worker_public/src/profile.ts workers/worker_public/src/requestScope.ts --bundle --format=esm --splitting --platform=neutral --outdir=dist --loader:.md=text && tsc -p tsconfig.build.json && cp dist-types/worker_public/src/*.d.ts dist/ && mkdir -p dist/worker_mcp/src && cp dist-types/worker_mcp/src/*.d.ts dist/worker_mcp/src/ && mkdir -p dist/prompts && cp workers/worker_public/prompts/*.md dist/prompts/",
+    "gen:openapi-types": "node scripts/gen-openapi-types.mjs",
+    "build": "rm -rf dist dist-types && esbuild workers/worker_mcp/src/index.ts workers/worker_public/src/index.ts workers/worker_public/src/config.ts workers/worker_public/src/refusal.ts workers/worker_public/src/profile.ts workers/worker_public/src/requestScope.ts --bundle --format=esm --splitting --platform=neutral --outdir=dist --loader:.md=text && tsc -p tsconfig.build.json && cp dist-types/worker_public/src/*.d.ts dist/ && mkdir -p dist/worker_mcp/src && cp dist-types/worker_mcp/src/*.d.ts dist/worker_mcp/src/ && mkdir -p dist/prompts && cp workers/worker_public/prompts/*.md dist/prompts/ && node scripts/gen-openapi-types.mjs",
     "prepare": "npm run build",
     "lint:ports": "node scripts/lint-ports.mjs",
     "lint:publisher": "node scripts/lint-publisher-leak.mjs",
@@ -24,14 +25,18 @@
     "@cloudflare/workers-types": "^5.20260911.1",
     "esbuild": "^0.28.2",
     "jsdom": "^29.1.1",
+    "openapi-typescript": "^7.13.0",
     "playwright": "^1.62.1",
     "yaml": "^2.9.1"
   },
   "dependencies": {
     "@astrojs/markdown-satteri": "^0.4.1",
-    "@astrojs/mdx": "^4.3.14"
+    "@astrojs/mdx": "^4.3.14",
+    "@konneal/client": "github:konneal/client#22ce599",
+    "@konneal/engine": "github:konneal/engine#2d6c39b",
+    "@oimlsmart/oiml-pubid": "^1.2.1"
   },
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "The Konneal engine: the publisher-agnostic build pipeline and API plane for standards intelligence (retrieval, answer contract, verdicts, evaluation).",
   "license": "BSD-3-Clause",
   "type": "module",
@@ -57,6 +62,10 @@
       "types": "./dist/requestScope.d.ts",
       "default": "./dist/worker_public/src/requestScope.js"
     },
+    "./openapi": "./workers/worker_public/openapi.yaml",
+    "./openapi-types": {
+      "types": "./dist/openapi-types.d.ts"
+    },
     "./mcp": "./dist/worker_mcp/src/index.js"
   },
   "files": [

package/profile/prompts.yaml

@@ -1,4 +1,7 @@
 vars:
+  publisher_identity: >-
+    the Fixture Organization — a worldwide organization that publishes
+    the fixture corpus
   assistant_identity: >-
     the fixture assistant — a public service answering questions about
     the fixture publisher's documents

package/workers/shared/router.ts

@@ -21,25 +21,32 @@ export interface Route {
   handler: RouteHandler;
 }
 
-export function matchRoute(routes: Route[], method: string, path: string): { route: Route; params: Record<string, string> } | null {
+/** The path half of the match, method-blind: segment-exact with :param
+ *  capture and a trailing * wildcard. Returns the captured params when
+ *  the pattern fits, null otherwise. The 405 probe uses it to tell a
+ *  known path under a wrong method from an unknown path. */
+export function routeMatchesPath(pattern: string, path: string): Record<string, string> | null {
   const segments = path.split("/").filter(Boolean);
+  const patternSegs = pattern.split("/").filter(Boolean);
+  if (patternSegs.length !== segments.length && !patternSegs[patternSegs.length - 1]?.startsWith("*")) return null;
+  const params: Record<string, string> = {};
+  for (let i = 0; i < patternSegs.length; i++) {
+    const ps = patternSegs[i];
+    if (ps.startsWith("*")) return params; // wildcard matches rest
+    if (ps.startsWith(":")) {
+      params[ps.slice(1)] = segments[i];
+    } else if (ps !== segments[i]) {
+      return null;
+    }
+  }
+  return params;
+}
+
+export function matchRoute(routes: Route[], method: string, path: string): { route: Route; params: Record<string, string> } | null {
   for (const route of routes) {
     if (route.method !== method && route.method !== "*") continue;
-    const patternSegs = route.pattern.split("/").filter(Boolean);
-    if (patternSegs.length !== segments.length && !patternSegs[patternSegs.length - 1]?.startsWith("*")) continue;
-    const params: Record<string, string> = {};
-    let matched = true;
-    for (let i = 0; i < patternSegs.length; i++) {
-      const ps = patternSegs[i];
-      if (ps.startsWith("*")) break; // wildcard matches rest
-      if (ps.startsWith(":")) {
-        params[ps.slice(1)] = segments[i];
-      } else if (ps !== segments[i]) {
-        matched = false;
-        break;
-      }
-    }
-    if (matched) return { route, params };
+    const params = routeMatchesPath(route.pattern, path);
+    if (params) return { route, params };
   }
   return null;
 }

package/workers/worker_public/migrations/0014_usage_cache.sql

@@ -0,0 +1,5 @@
+-- Usage telemetry (2026-09-17): the cache mix on the queries ledger.
+-- 'exact' | 'semantic' for served-from-cache answers, NULL for a live
+-- generation — the answer-cache story (hit rates per tier) becomes
+-- measurable instead of inferred.
+ALTER TABLE queries ADD COLUMN cache TEXT;