@konneal/engine 0.2.37 → 0.2.39

package/dist/{ask-J6NGXPOD.js → ask-UGTXNPPY.js}

@@ -1,7 +1,7 @@
 import {
   handleAsk
-} from "./chunk-SEOQWW77.js";
-import "./chunk-37FSCXBQ.js";
+} from "./chunk-OHYAHQQV.js";
+import "./chunk-NBE7BCQ7.js";
 import "./chunk-R2V3X6SQ.js";
 import "./chunk-A3QHHUN5.js";
 import "./chunk-4GJGBGJK.js";

package/dist/{chunk-YEAAGFHB.js → chunk-EVCERBIH.js}

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

package/dist/{chunk-37FSCXBQ.js → chunk-NBE7BCQ7.js}

@@ -61,6 +61,27 @@ async function generateOnce(env, model, messages, effort) {
   return null;
 }
 
+// workers/worker_public/src/quality.ts
+var ORDER = { verified: 0, curated: 1, ocr: 2 };
+function hitQuality(m) {
+  if (m.model_node || m.model_version || m.producer === "primmel") return "verified";
+  if (m.tier === "curated") return "curated";
+  return "ocr";
+}
+function answerQuality(qualities) {
+  let worst = null;
+  for (const q of qualities) {
+    if (!q) continue;
+    if (!worst || ORDER[q] > ORDER[worst]) worst = q;
+  }
+  return worst;
+}
+function qualityNote(q) {
+  if (q === "verified") return "Grounded in verified sources: this publication's requirements ride a machine-checkable data model.";
+  if (q === "curated") return "Grounded in the edited corpus: Metanorma-authored documents, chunked at clause boundaries.";
+  return "Partly grounded in experimental OCR text: verify quotations and table values against the official publication.";
+}
+
 // workers/worker_public/src/lexical.ts
 var LEXICAL_K = 40;
 function ftsMatchQuery(query) {
@@ -23515,6 +23536,7 @@ function citations(hits) {
     status: h.metadata.status ?? "unknown",
     superseded_by: h.metadata.superseded_by || void 0,
     corpus: h.metadata.corpus || P().publisher.id,
+    quality: hitQuality(h.metadata),
     url: publicationUrl(h.metadata),
     snippet: h.text.slice(0, 400),
     score: h.rerank_score ?? h.score
@@ -23814,13 +23836,23 @@ function opMemberCanWrite(member) {
   if (member.via !== "op-token") return true;
   return /\bwrite\b/.test(member.scope ?? "");
 }
-function opMemberFromIntrospection(answer, ids) {
+function opMemberFromIntrospection(answer, ids, patServices = []) {
   if (!answer?.active) return null;
-  const clientId = String(answer.client_id ?? "");
-  if (!ids.includes(clientId)) return null;
   const sub = String(answer.sub ?? "");
   if (!sub) return null;
-  return { sub, scope: String(answer.scope ?? ""), via: "op-token" };
+  const clientId = String(answer.client_id ?? "");
+  if (clientId) {
+    if (!ids.includes(clientId)) return null;
+    return { sub, scope: String(answer.scope ?? ""), via: "op-token" };
+  }
+  if (!patServices.length) return null;
+  const scope = String(answer.scope ?? "");
+  const services = scope.split(/\s+/).filter(Boolean).map((s8) => s8.split(":")[0]);
+  if (!services.some((s8) => patServices.includes(s8))) return null;
+  return { sub, scope, via: "op-token" };
+}
+function patServiceIds(env) {
+  return String(env.OIDC_PAT_SERVICES ?? "").split(/[\s,]+/).filter(Boolean);
 }
 async function opTokenMember(env, cfg, req) {
   const m = /^Bearer\s+(.+)$/i.exec((req.headers.get("Authorization") ?? "").trim());
@@ -23850,7 +23882,7 @@ async function opTokenMember(env, cfg, req) {
     } catch {
     }
   }
-  return opMemberFromIntrospection(answer, ids);
+  return opMemberFromIntrospection(answer, ids, patServiceIds(env));
 }
 
 // workers/worker_public/src/oidc.ts
@@ -24560,6 +24592,8 @@ async function editionNote(env, u) {
 export {
   embed,
   generateOnce,
+  answerQuality,
+  qualityNote,
   ftsMatchQuery,
   refCodec,
   NO_CONTEXT,

package/dist/{chunk-SEOQWW77.js → chunk-OHYAHQQV.js}

@@ -1,5 +1,6 @@
 import {
   NO_CONTEXT,
+  answerQuality,
   appliedContext,
   buildMessages,
   checkQuota,
@@ -21,6 +22,7 @@ import {
   parseContext,
   portModelRunner,
   portStore,
+  qualityNote,
   rawSessionToken,
   refCodec,
   resolveDocScope,
@@ -32,7 +34,7 @@ import {
   syntheticUnderstanding,
   telemetry,
   understandQuery
-} from "./chunk-37FSCXBQ.js";
+} from "./chunk-NBE7BCQ7.js";
 import {
   corsHeaders,
   err,
@@ -497,6 +499,7 @@ function modelCitation(node) {
     clause_title: `${node.kind.replace(/_/g, " ")} \u2014 ${node.name} (${node.node_id})`,
     status: "in-force",
     corpus: "smart-model",
+    quality: "verified",
     url: void 0,
     snippet: `${node.node_id}${node.clause ? ` \xB7 ${node.clause.urn}` : ""}${node.content?.statement ? ` \u2014 ${clip(node.content.statement, 240)}` : ""}`,
     score: 1
@@ -2471,7 +2474,8 @@ Answer account questions from these records ONLY: name the record when you use i
 
 `));
           send({ type: "read", read: readAs() });
-          send({ type: "citations", citations: cites, context_applied: ctxApplied, ...liveRecords ? { records: liveRecords } : {}, quota });
+          const sourceQuality = answerQuality(cites.map((c) => c.quality));
+          send({ type: "citations", citations: cites, context_applied: ctxApplied, ...sourceQuality ? { source_quality: sourceQuality, quality_note: qualityNote(sourceQuality) } : {}, ...liveRecords ? { records: liveRecords } : {}, quota });
           let full = "";
           try {
             for await (const tok of sseTokens(stream)) {
@@ -2604,7 +2608,8 @@ Answer account questions from these records ONLY: name the record when you use i
     if (completionBlocks.length) console.log("contract completion:", completionBlocks.length, "table block(s) attached server-side");
   }
   completionBlocks.push(...await completeFigures(env.DB, answer, [...c2ns.blocks, ...completionBlocks], used));
-  const out = { answer, citations: finalCites, model: MODELS.member, query_hash: queryHash, follow_ups: understanding?.follow_ups ?? [], blocks: [...c2ns.blocks, ...verdictBlock ? [verdictBlock] : [], ...conditionBlock ? [conditionBlock] : [], ...aggregationBlock ? [aggregationBlock] : [], ...completionBlocks], context_applied: ctxApplied, ...liveRecords ? { records: liveRecords } : {} };
+  const jsonQuality = answerQuality(finalCites.map((c) => c.quality));
+  const out = { answer, citations: finalCites, ...jsonQuality ? { source_quality: jsonQuality, quality_note: qualityNote(jsonQuality) } : {}, model: MODELS.member, query_hash: queryHash, follow_ups: understanding?.follow_ups ?? [], blocks: [...c2ns.blocks, ...verdictBlock ? [verdictBlock] : [], ...conditionBlock ? [conditionBlock] : [], ...aggregationBlock ? [aggregationBlock] : [], ...completionBlocks], context_applied: ctxApplied, ...liveRecords ? { records: liveRecords } : {} };
   const cacheable = !contextual && !declaredCtx && !answer.includes(refusalAnswer()) && finalAnchors.violations.length === 0;
   if (cacheable) {
     const warmVec = await warmEmbed ?? null;

package/dist/env.d.ts

@@ -36,6 +36,10 @@ export interface Env {
      *  deployment admits as member-read credentials via introspection.
      *  Empty/absent = the tier is off. */
     OIDC_DEVICE_CLIENT_IDS?: string;
+    /** the services whose OP-minted personal access tokens (the PAT form
+     *  of introspection — no client_id on the wire) this deployment admits
+     *  as member-read credentials. Empty/absent = PATs stay anonymous. */
+    OIDC_PAT_SERVICES?: string;
     SESSION_SECRET?: string;
     /** TODO.ai-platform/03 — the "my account" live-data delegation: the
      *  platform instance's API base + its client id at the OP (the

package/dist/livedata.d.ts

@@ -111,9 +111,17 @@ export declare function opMemberCanWrite(member: {
     scope?: string;
 } | null): boolean;
 /** The introspection answer → the member credential, judged against the
- *  deployment's allowlist. Inactive, foreign-client or subject-less
- *  answers all resolve to null — never to a widened guess. */
-export declare function opMemberFromIntrospection(answer: any, ids: string[]): OpMember | null;
+ *  deployment's two allowlists. The OP answers client-bearing tokens
+ *  WITH client_id (the access-token table, the machine JWTs) and its
+ *  PAT form WITHOUT one — a PAT's identity on the wire is its granted
+ *  SERVICES (the PAT grammar's whole vocabulary). So the deployment
+ *  names device-grant clients (OIDC_DEVICE_CLIENT_IDS) and, separately,
+ *  the services whose personal access tokens it admits
+ *  (OIDC_PAT_SERVICES). Both lists empty = the tier stays off; a token
+ *  matching neither list resolves to null — never a widened guess. */
+export declare function opMemberFromIntrospection(answer: any, ids: string[], patServices?: string[]): OpMember | null;
+/** The PAT-services allowlist (see opMemberFromIntrospection). */
+export declare function patServiceIds(env: any): string[];
 /** The Bearer read + introspection, KV-cached 45s keyed by the token's
  *  hash (an ask burst costs one introspection; a deactivation lands
  *  within a minute). The cached object is the OP's RAW answer — the

package/dist/modelplane.d.ts

@@ -87,6 +87,7 @@ export declare function modelCitation(node: BoundModelNode): {
     clause_title: string;
     status: string;
     corpus: string;
+    quality: string;
     url: undefined;
     snippet: string;
     score: number;

package/dist/pipeline.d.ts

@@ -61,6 +61,7 @@ export declare function citations(hits: Hit[]): {
     status: string;
     superseded_by: string | undefined;
     corpus: any;
+    quality: import("./quality").SourceQuality;
     url: string | undefined;
     snippet: string;
     score: number;

package/dist/quality.d.ts

@@ -0,0 +1,6 @@
+import type { ChunkMeta } from "../../shared/chunk.ts";
+export type SourceQuality = "verified" | "curated" | "ocr";
+export declare function hitQuality(m: ChunkMeta): SourceQuality;
+export declare function answerQuality(qualities: (SourceQuality | undefined)[]): SourceQuality | null;
+/** The one-line posture the interface renders under the answer. */
+export declare function qualityNote(q: SourceQuality): string;

package/dist/{search-V6M4KASL.js → search-G23CY5I6.js}

@@ -1,7 +1,7 @@
 import {
   handleSearch
-} from "./chunk-YEAAGFHB.js";
-import "./chunk-37FSCXBQ.js";
+} from "./chunk-EVCERBIH.js";
+import "./chunk-NBE7BCQ7.js";
 import "./chunk-R2V3X6SQ.js";
 import "./chunk-A3QHHUN5.js";
 import "./chunk-4GJGBGJK.js";

package/dist/worker_public/src/index.js

@@ -1,6 +1,6 @@
 import {
   handleSearch
-} from "../../chunk-YEAAGFHB.js";
+} from "../../chunk-EVCERBIH.js";
 import {
   bindModelNode,
   checkQuoteAnchors,
@@ -9,7 +9,7 @@ import {
   modelGroundingBlock,
   scoreJudge,
   standardForDocNumber
-} from "../../chunk-SEOQWW77.js";
+} from "../../chunk-OHYAHQQV.js";
 import {
   buildMessages,
   citations,
@@ -35,7 +35,7 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "../../chunk-37FSCXBQ.js";
+} from "../../chunk-NBE7BCQ7.js";
 import {
   authenticate,
   corsHeaders,
@@ -999,7 +999,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-J6NGXPOD.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-V6M4KASL.js")).handleSearch(env, ctx, inner, tier, key);
+    const res = name === "ask" ? await (await import("../../ask-UGTXNPPY.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-G23CY5I6.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 });

package/package.json

@@ -27,7 +27,7 @@
     "playwright": "^1.62.1",
     "yaml": "^2.9.1"
   },
-  "version": "0.2.37",
+  "version": "0.2.39",
   "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/ask.ts

@@ -25,6 +25,7 @@ import { evaluate as machineEvaluate, verdictNote } from "./verdict";
 import { evaluateConditionSets, quantitiesIn, type ConditionVerdict } from "./conditions";
 import { evaluateAggregation, type AggregationVerdict } from "./aggregation";
 import { matchLicensedTopic, boundaryNoteText } from "./boundary";
+import { answerQuality, qualityNote } from "./quality";
 import { detectDraftIntent, prepareDraft } from "./drafts";
 import { detectApiCallIntent, prepareApiCall } from "./apicalls";
 import { memoryNote } from "./memories";
@@ -1145,7 +1146,8 @@ async function handleAsk(
           // the reading arrives first: the interpretation that steered
           // retrieval, before a single token of the answer
           send({ type: "read", read: readAs() });
-          send({ type: "citations", citations: cites, context_applied: ctxApplied, ...(liveRecords ? { records: liveRecords } : {}), quota, });
+          const sourceQuality = answerQuality(cites.map((c: any) => c.quality));
+          send({ type: "citations", citations: cites, context_applied: ctxApplied, ...(sourceQuality ? { source_quality: sourceQuality, quality_note: qualityNote(sourceQuality) } : {}), ...(liveRecords ? { records: liveRecords } : {}), quota, });
           let full = "";
           try {
             for await (const tok of sseTokens(stream)) {
@@ -1339,7 +1341,8 @@ async function handleAsk(
   // figure completion (#172) — see ./completion for the rationale
   completionBlocks.push(...(await completeFigures(env.DB, answer, [...c2ns.blocks, ...completionBlocks], used)));
 
-  const out = { answer, citations: finalCites, model: MODELS.member, query_hash: queryHash, follow_ups: understanding?.follow_ups ?? [], blocks: [...c2ns.blocks, ...(verdictBlock ? [verdictBlock] : []), ...(conditionBlock ? [conditionBlock] : []), ...(aggregationBlock ? [aggregationBlock] : []), ...completionBlocks], context_applied: ctxApplied, ...(liveRecords ? { records: liveRecords } : {}) };
+  const jsonQuality = answerQuality(finalCites.map((c: any) => c.quality));
+  const out = { answer, citations: finalCites, ...(jsonQuality ? { source_quality: jsonQuality, quality_note: qualityNote(jsonQuality) } : {}), model: MODELS.member, query_hash: queryHash, follow_ups: understanding?.follow_ups ?? [], blocks: [...c2ns.blocks, ...(verdictBlock ? [verdictBlock] : []), ...(conditionBlock ? [conditionBlock] : []), ...(aggregationBlock ? [aggregationBlock] : []), ...completionBlocks], context_applied: ctxApplied, ...(liveRecords ? { records: liveRecords } : {}) };
   const cacheable = !contextual && !declaredCtx && !answer.includes(refusalAnswer()) && finalAnchors.violations.length === 0;
   if (cacheable) {
     const warmVec = (await warmEmbed) ?? null;

package/workers/worker_public/src/env.ts

@@ -38,6 +38,10 @@ export interface Env {
    *  deployment admits as member-read credentials via introspection.
    *  Empty/absent = the tier is off. */
   OIDC_DEVICE_CLIENT_IDS?: string;
+  /** the services whose OP-minted personal access tokens (the PAT form
+   *  of introspection — no client_id on the wire) this deployment admits
+   *  as member-read credentials. Empty/absent = PATs stay anonymous. */
+  OIDC_PAT_SERVICES?: string;
   SESSION_SECRET?: string;
   /** TODO.ai-platform/03 — the "my account" live-data delegation: the
    *  platform instance's API base + its client id at the OP (the

package/workers/worker_public/src/livedata.ts

@@ -431,15 +431,35 @@ export function opMemberCanWrite(member: { via?: string; scope?: string } | null
 }
 
 /** The introspection answer → the member credential, judged against the
- *  deployment's allowlist. Inactive, foreign-client or subject-less
- *  answers all resolve to null — never to a widened guess. */
-export function opMemberFromIntrospection(answer: any, ids: string[]): OpMember | null {
+ *  deployment's two allowlists. The OP answers client-bearing tokens
+ *  WITH client_id (the access-token table, the machine JWTs) and its
+ *  PAT form WITHOUT one — a PAT's identity on the wire is its granted
+ *  SERVICES (the PAT grammar's whole vocabulary). So the deployment
+ *  names device-grant clients (OIDC_DEVICE_CLIENT_IDS) and, separately,
+ *  the services whose personal access tokens it admits
+ *  (OIDC_PAT_SERVICES). Both lists empty = the tier stays off; a token
+ *  matching neither list resolves to null — never a widened guess. */
+export function opMemberFromIntrospection(answer: any, ids: string[], patServices: string[] = []): OpMember | null {
   if (!answer?.active) return null;
-  const clientId = String(answer.client_id ?? "");
-  if (!ids.includes(clientId)) return null;
   const sub = String(answer.sub ?? "");
   if (!sub) return null;
-  return { sub, scope: String(answer.scope ?? ""), via: "op-token" };
+  const clientId = String(answer.client_id ?? "");
+  if (clientId) {
+    if (!ids.includes(clientId)) return null;
+    return { sub, scope: String(answer.scope ?? ""), via: "op-token" };
+  }
+  if (!patServices.length) return null;
+  const scope = String(answer.scope ?? "");
+  const services = scope.split(/\s+/).filter(Boolean).map((s) => s.split(":")[0]);
+  if (!services.some((s) => patServices.includes(s))) return null;
+  return { sub, scope, via: "op-token" };
+}
+
+/** The PAT-services allowlist (see opMemberFromIntrospection). */
+export function patServiceIds(env: any): string[] {
+  return String(env.OIDC_PAT_SERVICES ?? "")
+    .split(/[\s,]+/)
+    .filter(Boolean);
 }
 
 /** The Bearer read + introspection, KV-cached 45s keyed by the token's
@@ -482,5 +502,5 @@ export async function opTokenMember(
       /* cacheless = introspect per ask */
     }
   }
-  return opMemberFromIntrospection(answer, ids);
+  return opMemberFromIntrospection(answer, ids, patServiceIds(env));
 }

package/workers/worker_public/src/modelplane.ts

@@ -287,6 +287,7 @@ export function modelCitation(node: BoundModelNode) {
     clause_title: `${node.kind.replace(/_/g, " ")} — ${node.name} (${node.node_id})`,
     status: "in-force",
     corpus: "smart-model",
+    quality: "verified",
     url: undefined,
     snippet: `${node.node_id}${node.clause ? ` · ${node.clause.urn}` : ""}${node.content?.statement ? ` — ${clip(node.content.statement, 240)}` : ""}`,
     score: 1,

package/workers/worker_public/src/pipeline.ts

@@ -33,6 +33,7 @@ export function fill(template: string, vars: Record<string, string>): string {
   return template.replace(/\{\{(\w+)\}\}/g, (_m, k: string) => (k in vars ? vars[k] : ""));
 }
 import { QueryFilters, toVectorizeFilter, standardKeyAllowed } from "./selfquery";
+import { hitQuality } from "./quality";
 import { lexicalPrefilter } from "./lexical";
 import { positionOrder } from "./structural";
 import { STAGES, runStages } from "./stages";
@@ -404,6 +405,7 @@ export function citations(hits: Hit[]) {
       status: h.metadata.status ?? "unknown",
       superseded_by: h.metadata.superseded_by || undefined,
       corpus: h.metadata.corpus || P().publisher.id,
+      quality: hitQuality(h.metadata),
       url: publicationUrl(h.metadata),
       snippet: h.text.slice(0, 400),
       score: h.rerank_score ?? h.score,

package/workers/worker_public/src/quality.ts

@@ -0,0 +1,48 @@
+// The answer-quality ladder (TODO.rag/13): every citation states what
+// kind of text grounds it, so the answer states how far to trust it.
+// Three rungs, derived from provenance the chunk wire already carries —
+// no new ingest state:
+//
+//   verified — the model plane: the chunk rides a primmel data model
+//     (model_node/model_version), the Recommendation's semantics are
+//     machine-checkable and the golden set measures them (R 60 is the
+//     gauge). The answer can be WRONG, but it is wrong against a
+//     contract we can see.
+//   curated  — the edited corpus: Metanorma-authored documents
+//     (mn-samples-oiml and the editors' own), clause-boundary chunks,
+//     enrichment applied.
+//   ocr      — the experimental OCR corpus: the broad coverage lane,
+//     text recovered from scans; quote anchors may wobble, tables can
+//     be mangled. Useful, and marked as experimental on purpose.
+//
+// The answer's tier is the WORST rung its citations stand on: one OCR
+// citation makes the whole answer experimental, because the reader
+// cannot tell which sentence leaned on which chunk.
+
+import type { ChunkMeta } from "../../shared/chunk.ts";
+
+export type SourceQuality = "verified" | "curated" | "ocr";
+
+const ORDER: Record<SourceQuality, number> = { verified: 0, curated: 1, ocr: 2 };
+
+export function hitQuality(m: ChunkMeta): SourceQuality {
+  if (m.model_node || m.model_version || m.producer === "primmel") return "verified";
+  if (m.tier === "curated") return "curated";
+  return "ocr";
+}
+
+export function answerQuality(qualities: (SourceQuality | undefined)[]): SourceQuality | null {
+  let worst: SourceQuality | null = null;
+  for (const q of qualities) {
+    if (!q) continue;
+    if (!worst || ORDER[q] > ORDER[worst]) worst = q;
+  }
+  return worst;
+}
+
+/** The one-line posture the interface renders under the answer. */
+export function qualityNote(q: SourceQuality): string {
+  if (q === "verified") return "Grounded in verified sources: this publication's requirements ride a machine-checkable data model.";
+  if (q === "curated") return "Grounded in the edited corpus: Metanorma-authored documents, chunked at clause boundaries.";
+  return "Partly grounded in experimental OCR text: verify quotations and table values against the official publication.";
+}