@konneal/engine 0.2.4 → 0.2.6

package/README.md

@@ -1,5 +1,7 @@
 # Konneal Engine
 
+**New here?** Read [docs/ADOPTION.md](docs/ADOPTION.md) — adopt Konneal for your own standards and your own identity service.
+
 The publisher-agnostic serving layer for standards intelligence: hybrid
 retrieval over clause-structured corpora, citation-grounded answers,
 typed tables/formulas/figures, conformance checking by execution, and

package/dist/{ask-YCDXMIZ4.js → ask-RX3W5JJW.js}

@@ -1,7 +1,7 @@
 import {
   handleAsk
-} from "./chunk-OGFH3RDM.js";
-import "./chunk-RLT4W2VX.js";
+} from "./chunk-7K5XP4PB.js";
+import "./chunk-GCL73ZLT.js";
 import "./chunk-EFQALN2Z.js";
 import "./chunk-DBBGOOMZ.js";
 import "./chunk-5MBWE7WD.js";

package/dist/{chunk-OGFH3RDM.js → chunk-7K5XP4PB.js}

@@ -27,7 +27,7 @@ import {
   syntheticUnderstanding,
   telemetry,
   understandQuery
-} from "./chunk-RLT4W2VX.js";
+} from "./chunk-GCL73ZLT.js";
 import {
   corsHeaders,
   err,

package/dist/{chunk-RLT4W2VX.js → chunk-GCL73ZLT.js}

@@ -1939,6 +1939,7 @@ ${context}` }
   };
 }
 function publicationUrl(meta) {
+  if (meta.corpus && !["oiml", "dirty", "clean"].includes(meta.corpus)) return void 0;
   const tpl = P().publisher.catalog_url_template;
   if (!tpl || !meta.doctype || !meta.doc_number) return void 0;
   return tpl.replace("{type}", meta.doctype.toLowerCase()) + meta.doc_number;

package/dist/{chunk-THSHLUOS.js → chunk-NRC4FBDQ.js}

@@ -7,7 +7,7 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "./chunk-RLT4W2VX.js";
+} from "./chunk-GCL73ZLT.js";
 import {
   corsHeaders,
   err,

package/dist/{search-7TO2RWQE.js → search-OXHXXT5S.js}

@@ -1,7 +1,7 @@
 import {
   handleSearch
-} from "./chunk-THSHLUOS.js";
-import "./chunk-RLT4W2VX.js";
+} from "./chunk-NRC4FBDQ.js";
+import "./chunk-GCL73ZLT.js";
 import "./chunk-EFQALN2Z.js";
 import "./chunk-DBBGOOMZ.js";
 import "./chunk-5MBWE7WD.js";

package/dist/worker_public/src/index.js

@@ -1,13 +1,13 @@
 import {
   handleSearch
-} from "../../chunk-THSHLUOS.js";
+} from "../../chunk-NRC4FBDQ.js";
 import {
   checkQuoteAnchors,
   handleAsk,
   handleMemories,
   scoreJudge,
   standardForDocNumber
-} from "../../chunk-OGFH3RDM.js";
+} from "../../chunk-7K5XP4PB.js";
 import {
   buildMessages,
   citations,
@@ -29,7 +29,7 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "../../chunk-RLT4W2VX.js";
+} from "../../chunk-GCL73ZLT.js";
 import {
   authenticate,
   corsHeaders,
@@ -979,7 +979,7 @@ async function handleMcp(env, ctx, req, tier, key) {
       // stream:false forces the JSON lane (anon defaults to SSE)
       body: JSON.stringify({ ...args, stream: false })
     });
-    const res = name === "ask" ? await (await import("../../ask-YCDXMIZ4.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-7TO2RWQE.js")).handleSearch(env, ctx, inner, tier, key);
+    const res = name === "ask" ? await (await import("../../ask-RX3W5JJW.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-OXHXXT5S.js")).handleSearch(env, ctx, 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 });
@@ -1585,9 +1585,46 @@ async function researchRoute(c) {
   const session = c.env.SESSION_SECRET ? await sessionFrom(c.req, c.env) : null;
   return handleResearch(c.env, c.ctx, c.req, session);
 }
+function permissionsCatalog() {
+  const groups = [];
+  const perms = [];
+  for (const d of P().datasets ?? []) {
+    if (d.session && d.permission) {
+      perms.push({
+        id: "ai.dataset.externally-licensed",
+        description: `Access the ${d.label} dataset (federated, externally licensed content)`
+      });
+    }
+  }
+  if (P().publisher.features?.drafts) {
+    perms.push({ id: "ai.drafts", description: "Ask the assistant to prepare draft acts" });
+  }
+  perms.push({ id: "ai.memories", description: "Personalized memory files on the assistant" });
+  perms.push({ id: "ai.research", description: "Deep-research multi-pass questions" });
+  perms.push({ id: "ai.keys.admin", description: "Create and revoke API keys" });
+  groups.push({ id: "ai", description: "The publications assistant's gated capabilities", permissions: perms });
+  return {
+    version: 1,
+    verbs: ["read", "write", "admin"],
+    groups
+  };
+}
+async function openapiCatalogRoute(c) {
+  return json(
+    {
+      openapi: "3.1.0",
+      info: { title: `${P().publisher.product_name} API`, version: c.env.INDEX_VERSION ?? "0" },
+      paths: {},
+      "x-oiml-permissions-catalog": permissionsCatalog()
+    },
+    200,
+    corsHeaders(c.req)
+  );
+}
 var INFRA_ROUTES = [
   { method: "GET", pattern: "/", handler: serveIndexPage },
   { method: "GET", pattern: "/api/", handler: serveIndexPage },
+  { method: "GET", pattern: "/api/openapi.json", handler: openapiCatalogRoute },
   { method: "GET", pattern: "/index.html", handler: serveIndexPage },
   { method: "GET", pattern: "/assets/*", handler: unitAssetRoute },
   { method: "GET", pattern: "/docs/*", handler: docsRoute }

package/docs/ADOPTION.md

@@ -0,0 +1,61 @@
+# Adopting Konneal: your own standards-intelligence site
+
+Konneal is a publisher-agnostic engine: clause-cited, verifiable answers
+over your own Metanorma documents and Primmel models — deployed on your
+own infrastructure, with licensed third-party content (IEC, ISO and
+peers) gated behind your identity service.
+
+## Start
+
+    npm create @konneal/publisher my-sdo
+
+The scaffolder interviews you for your publisher's facts — id, name,
+domains, identity issuer, first dataset — and writes the whole
+deployment skeleton: the worker, the site, the profile, the ingest
+pipeline, CI. Every generated file is ordinary reviewable code.
+
+Then the four declarations:
+
+1. **Your profile** (`profile/*.yaml`): publisher identity, domains,
+   datasets, the corpora registry, the licensed-standards catalog,
+   prompt variables, smoke probes. Everything the serving surface knows
+   about you is this data, never engine code.
+2. **Your corpus** (`sources/`): your Metanorma documents. The ingest
+   pipeline chunks along the documents' own clause boundaries, embeds,
+   and upserts into your indexes.
+3. **Your models** (Primmel packages): the machine-readable layer —
+   requirements, constraints with threshold expressions, severity
+   condition sets — so answers can carry server-computed verdicts, not
+   paraphrases.
+4. **Your identity**: any discovery-compliant OIDC provider. Register
+   the site (authorization code + PKCE), map roles to datasets and
+   groups to licensed keys in the provider's configuration — revoking a
+   role removes access on the next request, no deploy.
+
+## Licensed content, gated
+
+Licensed standards are fail-closed by construction: each licensed
+package carries a license key; the deployment's profile declares the
+whitelist; a request without an entitled scope never sees the licensed
+text — it is filtered before the model reads anything. An anonymous
+request cannot reach internal indexes at all: the public surface holds
+no binding to them, and the internal worker re-verifies every session
+itself.
+
+## The proof
+
+Your golden suite gates every promotion: content witnesses, refusal
+legs, licensed pairs in both directions (entitled content serves;
+unentitled never appears), context-utilization and verdict legs. The
+nightly runs unattended against production and fails loudly on drift.
+
+## Ask it from your terminal
+
+The konneal CLI ships with the client package: npm i -g @konneal/client, then KONNEAL_BASE and KONNEAL_KEY in the environment give you konneal ask, konneal search and konneal keys list — streaming answers with citations and verdict blocks, the same API the site uses behind the same tiering.
+
+## The path
+
+`npm create @konneal/publisher` → declare the profile → ingest your
+corpus → author one model package and one golden leg → map identity →
+promote through the gate. Adoption is done when your team runs the
+nightly and reads the gate without help.

package/package.json

@@ -34,7 +34,7 @@
     "@oimlsmart/oiml-pubid": "^1.2.1"
   },
   "dependencies": {},
-  "version": "0.2.4",
+  "version": "0.2.6",
   "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_internal/src/index.ts

@@ -17,6 +17,7 @@ export interface Env {
   AI: any;
   PUBLIC: any; // idx_oiml_public_v2
   INTERNAL: any; // idx_iso_internal
+  DOCS: any; // rag-internal-docs — the internal renderings
   CACHE: KVNamespace;
   SESSION_SECRET: string;
   INDEX_VERSION: string;
@@ -137,10 +138,38 @@ async function retrieveRoute(c: RouteContext): Promise<Response> {
   }
 }
 
+// The internal corpus's document door: rendered publications and their
+// clause-anchor maps, session-gated like retrieval (the admin token also
+// opens it for ops verification). Only docs/<name> shapes are served —
+// html and the anchors map, nothing else.
+async function docRoute(c: RouteContext): Promise<Response> {
+  const { env, req } = c;
+  const file = c.params.file ?? "";
+  if (!/^docs\/[a-z0-9-]+\.(html|anchors\.json)$/.test(`docs/${file}`)) {
+    return err(400, "invalid_input", "docs/<slug>.html or docs/<slug>.anchors.json");
+  }
+  const session = await sessionFrom(req, env as any);
+  const admin = env.ADMIN_TOKEN && req.headers.get("x-admin-token") === env.ADMIN_TOKEN;
+  if (!session && !admin) return err(401, "unauthorized", "Sign in required — internal corpus documents are member content.");
+  try {
+    const obj = await env.DOCS.get(`docs/${file}`);
+    if (!obj) return err(404, "not_found", "No rendered document at this address.");
+    return new Response(obj.body, {
+      headers: {
+        "content-type": file.endsWith(".json") ? "application/json" : "text/html; charset=utf-8",
+        "cache-control": "private, max-age=86400",
+      },
+    });
+  } catch {
+    return err(503, "docs_unavailable", "The document store is briefly busy.");
+  }
+}
+
 // the same declarative route table the public worker dispatches through
 // (TODO.impl/31) — one HTTP idiom across workers.
 const ROUTES: Route[] = [
   { method: "GET", pattern: "/health", handler: healthRoute },
+  { method: "GET", pattern: "/docs/:file", handler: docRoute },
   { method: "POST", pattern: "/admin/sync", handler: adminSyncRoute },
   { method: "POST", pattern: "/retrieve", handler: retrieveRoute },
   { method: "POST", pattern: "/api/retrieve", handler: retrieveRoute },

package/workers/worker_public/src/index.ts

@@ -398,9 +398,54 @@ async function researchRoute(c: RouteContext): Promise<Response> {
 // 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.
+
+// The service's own permission catalog (TODO.openapi/03): the identity
+// service FETCHES this endpoint to verify every permission grant for
+// this client — it never holds a copy. The catalog derives from the
+// profile's own declarations (gated datasets, feature flags), so a
+// deployment's catalog cannot drift from what it enforces.
+function permissionsCatalog(): Record<string, unknown> {
+  const groups: Record<string, unknown>[] = [];
+  const perms: Record<string, unknown>[] = [];
+  for (const d of P().datasets ?? []) {
+    if (d.session && d.permission) {
+      perms.push({
+        id: "ai.dataset.externally-licensed",
+        description: `Access the ${d.label} dataset (federated, externally licensed content)`,
+      });
+    }
+  }
+  if (P().publisher.features?.drafts) {
+    perms.push({ id: "ai.drafts", description: "Ask the assistant to prepare draft acts" });
+  }
+  perms.push({ id: "ai.memories", description: "Personalized memory files on the assistant" });
+  perms.push({ id: "ai.research", description: "Deep-research multi-pass questions" });
+  perms.push({ id: "ai.keys.admin", description: "Create and revoke API keys" });
+  groups.push({ id: "ai", description: "The publications assistant's gated capabilities", permissions: perms });
+  return {
+    version: 1,
+    verbs: ["read", "write", "admin"],
+    groups,
+  };
+}
+
+async function openapiCatalogRoute(c: RouteContext): Promise<Response> {
+  return json(
+    {
+      openapi: "3.1.0",
+      info: { title: `${P().publisher.product_name} API`, version: c.env.INDEX_VERSION ?? "0" },
+      paths: {},
+      "x-oiml-permissions-catalog": permissionsCatalog(),
+    },
+    200,
+    corsHeaders(c.req),
+  );
+}
+
 const INFRA_ROUTES: Route[] = [
   { method: "GET", pattern: "/", handler: serveIndexPage },
   { method: "GET", pattern: "/api/", handler: serveIndexPage },
+  { method: "GET", pattern: "/api/openapi.json", handler: openapiCatalogRoute },
   { method: "GET", pattern: "/index.html", handler: serveIndexPage },
   { method: "GET", pattern: "/assets/*", handler: unitAssetRoute },
   { method: "GET", pattern: "/docs/*", handler: docsRoute },

package/workers/worker_public/src/pipeline.ts

@@ -380,6 +380,11 @@ export function buildMessages(
  *  URL template ({type} = lowercase doctype, then the number); no
  *  template, no catalog link. */
 function publicationUrl(meta: ChunkMeta): string | undefined {
+  // the catalog template names THIS publisher's store - an internal or
+  // foreign-corpus chunk has no entry in it, and a fabricated url is
+  // worse than none (the door for internal renderings is the internal
+  // origin, wired by the site's doc-base configuration)
+  if (meta.corpus && !["oiml", "dirty", "clean"].includes(meta.corpus)) return undefined;
   const tpl = P().publisher.catalog_url_template;
   if (!tpl || !meta.doctype || !meta.doc_number) return undefined;
   return tpl.replace("{type}", meta.doctype.toLowerCase()) + meta.doc_number;