@konneal/engine 0.1.1 → 0.1.2

package/README.md

@@ -6,8 +6,109 @@ typed tables/formulas/figures, conformance checking by execution, and
 the measurement gates that keep it honest. Konneal builds the databases
 and serves the API; publishers own their content, profile and frontend.
 
-Architecture and plan: docs/konneal-extraction-plan.md (and
-docs/multi-sdo-architecture.md). The reference deployment is OIML SMART
-AI (oimlsmart/ai — the reference profile). This repository was born
-from it with history preserved (git filter-repo over the engine
-subtrees); the README seed commit was replaced by the extraction.
+```
+npm install @konneal/engine
+```
+
+BSD-3-Clause. The reference deployment is
+[OIML SMART AI](https://ai.oimlsmart.org).
+
+## What a deployment looks like
+
+A publisher's worker is ten lines:
+
+```ts
+// workers/worker_public/src/index.ts — the deployment entry
+import worker, { setProfile } from "@konneal/engine";
+import { PROFILE } from "./profile.gen.ts";
+
+setProfile(PROFILE);
+
+export default worker;
+```
+
+Everything the publisher owns lives in `profile/*.yaml` — identity,
+datasets, corpora, prompts, thresholds, eval cases. The codegen
+(`gen_profile.mjs`, included) turns the YAML into a committed
+TypeScript module; a drift test keeps both sides honest. The engine
+reads the profile at request time; no publisher fact is hardcoded.
+
+The engine also ships the ingest CLI (Python): parse → embed → upsert,
+reading the same profile for its corpora declarations.
+
+## The three packages
+
+| Package | What it is |
+|---|---|
+| `@konneal/engine` | The serving Worker + the ingest CLI (this package) |
+| `@konneal/client` | The publisher-site contract: wire types, SSE client, citation chips, typed blocks |
+| `@konneal/create-publisher` | `npm create @konneal/publisher` — scaffolds the whole deployment |
+
+Start with the scaffolder: `npm create @konneal/publisher my-sdo
+-- --with-site` writes the profile, the worker entry, the Cloudflare
+wiring, the profile codegen, and (with `--with-site`) a minimal
+Astro+Vue frontend consuming `@konneal/client`.
+
+## The profile (the publisher's single edit surface)
+
+| File | Declares |
+|---|---|
+| `publisher.yaml` | id, name, domains, identity issuer, codec, session cookie, features |
+| `datasets.yaml` | what users can scope to (public vs session-gated), per-corpus prompt notes |
+| `corpora.yaml` | the corpus registry — which corpora exist, which indexes serve them |
+| `sources.yaml` | upstream repos the tooling reads (clean corpus, bibliography, terminology, models) |
+| `ui.yaml` | suggestions, model disclosure, smoke probes |
+| `retrieval.yaml` | steering vocabulary, process-intent notes |
+| `prompts.yaml` | the publisher's prompt voice (identity, refusal, examples) |
+| `evals/` | golden cases, annealment probes, ladder — the promotion-gate data |
+
+## Serving architecture
+
+- **Retrieval** is a stage registry; the ask path owns composition only
+- **HTTP** is a route table dispatched by both workers
+- Every steering number lives in `THRESHOLDS`; the chunk wire type is
+  shared with the Python producer by a contract test
+- **Ports** (`ports/`): ModelRunner, VectorIndex, Kv, Blobs, Runtime —
+  the Cloudflare adapters are the only provider-typed module; a purity
+  lint enforces it in CI
+- **Publisher purity**: a CI lint fails any publisher string in
+  `workers/` outside the codec registry (the identifier grammars)
+- **Feature gates**: `drafts` and `model_plane` are profile-declared,
+  off by default
+
+## The ingest CLI
+
+```bash
+pip install git+https://github.com/konneal/engine.git
+python -m ingest.cli parse     # corpora → chunks.jsonl + manifest
+python -m ingest.cli embed     # embed via the binding's model
+python -m ingest.cli upsert    # push vectors + metadata to Vectorize
+```
+
+## MCP server
+
+The package exports `./mcp` — a ten-line entry per deployment serves
+the publisher's public corpus to MCP clients (agent ecosystems).
+Auth is required: the MCP client presents one of the deployment's API
+keys; the same token rides outbound so spend and quota charge that
+key.
+
+## Promotion gates
+
+The engine ships the gate harness: a deployment's golden cases and
+annealment probes live in `profile/evals/`; the gate runs them against
+production before any promotion. Answers are witness-checked (the
+answer must contain the expected span, not just score well).
+
+## Repository
+
+- `workers/worker_public/` — the public-facing Worker
+- `workers/worker_mcp/` — the MCP server Worker
+- `workers/shared/` — the router, chunk wire type, session
+- `ports/` — the provider seam (interfaces + Cloudflare adapters)
+- `profile/` — the engine's fixture profile (a real deployment carries
+  its own; this one exists so tests run against declared data)
+- `profile2/` — the reference matrix's second fixture (a different
+  publisher shape; CI proves the engine serves declared profiles)
+- `ingest/` — the Python ingest CLI
+- `tests/` — unit suites (plain node, no network)

package/dist/worker_mcp/src/index.js

@@ -17,7 +17,7 @@ var rpcError = (id, code, message) => json({ jsonrpc: "2.0", id, error: { code,
 var publisherId = () => P().publisher.id;
 var bearer = (req) => (req.headers.get("authorization") ?? "").replace(/^Bearer\s+/i, "").trim();
 var publisherName = () => P().publisher.name;
-var TOOLS = [
+var tools = () => [
   {
     name: `${publisherId()}_search`,
     description: `Search the ${publisherName()} publications corpus. Returns ranked passages with publication identifier, edition, clause and snippet.`,
@@ -107,7 +107,7 @@ var src_default = {
         server: "rag-mcp",
         transport: "streamable-http",
         endpoint: "/mcp",
-        tools: TOOLS.map((t) => t.name)
+        tools: tools().map((t) => t.name)
       });
     }
     if (url.pathname !== "/mcp") return json({ error: "not_found" }, 404);
@@ -130,7 +130,7 @@ var src_default = {
             serverInfo: { name: "rag-mcp", version: "1.0.0", title: `${P().publisher.product_name} \u2014 public corpus` }
           });
         case "tools/list":
-          return rpcResult(msg.id, { tools: TOOLS });
+          return rpcResult(msg.id, { tools: tools() });
         case "tools/call": {
           const out = await callTool(env, bearer(req), String(msg.params?.name ?? ""), msg.params?.arguments ?? {});
           return rpcResult(msg.id, out);

package/package.json

@@ -31,7 +31,7 @@
     "@astrojs/markdown-satteri": "^0.4.1",
     "@astrojs/mdx": "^4.3.14"
   },
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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",

package/workers/worker_mcp/src/index.ts

@@ -39,7 +39,7 @@ const rpcError = (id: unknown, code: number, message: string) =>
 const publisherId = () => P().publisher.id;
 const bearer = (req: Request) => (req.headers.get("authorization") ?? "").replace(/^Bearer\s+/i, "").trim();
 const publisherName = () => P().publisher.name;
-const TOOLS = [
+const tools = () => [
   {
     name: `${publisherId()}_search`,
     description:
@@ -138,7 +138,7 @@ export default {
         server: "rag-mcp",
         transport: "streamable-http",
         endpoint: "/mcp",
-        tools: TOOLS.map((t) => t.name),
+        tools: tools().map((t) => t.name),
       });
     }
 
@@ -168,7 +168,7 @@ export default {
             serverInfo: { name: "rag-mcp", version: "1.0.0", title: `${P().publisher.product_name} — public corpus` },
           });
         case "tools/list":
-          return rpcResult(msg.id, { tools: TOOLS });
+          return rpcResult(msg.id, { tools: tools() });
         case "tools/call": {
           const out = await callTool(env, bearer(req), String(msg.params?.name ?? ""), msg.params?.arguments ?? {});
           return rpcResult(msg.id, out);