@konneal/engine 0.2.5 → 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/worker_public/src/index.js

@@ -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.5",
+  "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_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 },