@konneal/engine 0.2.31 → 0.2.33

package/dist/{ask-43C2WZZO.js → ask-GU554Y45.js}

@@ -1,7 +1,7 @@
 import {
   handleAsk
-} from "./chunk-TDKNQPA2.js";
-import "./chunk-F66NYFUK.js";
+} from "./chunk-WSLADX7O.js";
+import "./chunk-NHHQAGBW.js";
 import "./chunk-2RKYO3OC.js";
 import "./chunk-A3QHHUN5.js";
 import "./chunk-JGKSUSF5.js";

package/dist/{chunk-S7NLWPNX.js → chunk-5LSEBH3J.js}

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

package/dist/{chunk-F66NYFUK.js → chunk-NHHQAGBW.js}

@@ -24373,8 +24373,8 @@ function telemetry(env, ctx, tier, route, model, ok, answerChars, queryHash, lan
   ctx.waitUntil(
     env.DB.batch([
       env.DB.prepare(
-        "INSERT INTO queries (ts, day, tier, route, model, ok, answer_chars, query_hash, lang, cache, duration_ms, key_id) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9,?10,?11,?12)"
-      ).bind((/* @__PURE__ */ new Date()).toISOString(), day, tier, route, model, ok ? 1 : 0, answerChars, queryHash, lang ?? null, cache ?? null, meta?.durationMs ?? null, meta?.keyId ?? null),
+        "INSERT INTO queries (ts, day, tier, route, model, ok, answer_chars, query_hash, lang, cache, duration_ms, key_id, retries) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9,?10,?11,?12,?13)"
+      ).bind((/* @__PURE__ */ new Date()).toISOString(), day, tier, route, model, ok ? 1 : 0, answerChars, queryHash, lang ?? null, cache ?? null, meta?.durationMs ?? null, meta?.keyId ?? null, meta?.retries ?? 0),
       env.DB.prepare(
         "INSERT INTO spend (day, tier, model, requests) VALUES (?1,?2,?3,1) ON CONFLICT(day, tier, model) DO UPDATE SET requests = requests + 1"
       ).bind(day, tier, model ?? "none")

package/dist/{chunk-TDKNQPA2.js → chunk-WSLADX7O.js}

@@ -28,7 +28,7 @@ import {
   syntheticUnderstanding,
   telemetry,
   understandQuery
-} from "./chunk-F66NYFUK.js";
+} from "./chunk-NHHQAGBW.js";
 import {
   corsHeaders,
   err,
@@ -1612,7 +1612,7 @@ async function* sseTokens(stream) {
 }
 async function handleAsk(env, ctx, req, tier, key) {
   const tStart = Date.now();
-  const telemetryMeta = () => ({ durationMs: Date.now() - tStart, keyId: key?.id ?? null });
+  const telemetryMeta = () => ({ durationMs: Date.now() - tStart, keyId: key?.id ?? null, retries: generateRetries });
   const stageTiming = {};
   let generateRetries = 0;
   const readAs = () => understanding ? {

package/dist/quota.d.ts

@@ -13,4 +13,5 @@ export declare function checkQuota(env: Env, bucket: string, id: string, limit:
 export declare function telemetry(env: Env, ctx: Background, tier: string, route: string, model: string | null, ok: boolean, answerChars: number, queryHash: string, lang?: string, cache?: "exact" | "semantic", meta?: {
     durationMs?: number;
     keyId?: string | null;
+    retries?: number;
 }): void;

package/dist/{search-NHTT5DDI.js → search-LGDQR43R.js}

@@ -1,7 +1,7 @@
 import {
   handleSearch
-} from "./chunk-S7NLWPNX.js";
-import "./chunk-F66NYFUK.js";
+} from "./chunk-5LSEBH3J.js";
+import "./chunk-NHHQAGBW.js";
 import "./chunk-2RKYO3OC.js";
 import "./chunk-A3QHHUN5.js";
 import "./chunk-JGKSUSF5.js";

package/dist/worker_public/src/index.js

@@ -1,6 +1,6 @@
 import {
   handleSearch
-} from "../../chunk-S7NLWPNX.js";
+} from "../../chunk-5LSEBH3J.js";
 import {
   bindModelNode,
   checkQuoteAnchors,
@@ -9,7 +9,7 @@ import {
   modelGroundingBlock,
   scoreJudge,
   standardForDocNumber
-} from "../../chunk-TDKNQPA2.js";
+} from "../../chunk-WSLADX7O.js";
 import {
   buildMessages,
   citations,
@@ -32,7 +32,7 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "../../chunk-F66NYFUK.js";
+} from "../../chunk-NHHQAGBW.js";
 import {
   authenticate,
   corsHeaders,
@@ -996,7 +996,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-43C2WZZO.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-NHTT5DDI.js")).handleSearch(env, ctx, inner, tier, key);
+    const res = name === "ask" ? await (await import("../../ask-GU554Y45.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-LGDQR43R.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 });
@@ -1382,14 +1382,16 @@ async function adminStatsRoute(c) {
   if (!env.ADMIN_TOKEN) return err(501, "admin_disabled", "ADMIN_TOKEN secret is not configured");
   const auth = req.headers.get("authorization") ?? "";
   if (auth !== `Bearer ${env.ADMIN_TOKEN}`) return err(401, "unauthorized", "Invalid admin token");
-  const [byDay, byModel, feedback, convCount, cacheMix, durations] = await Promise.all([
+  const [byDay, byModel, feedback, convCount, cacheMix, durations, retriesRow] = await Promise.all([
     env.DB.prepare("SELECT day, tier, COUNT(*) as n, SUM(ok) as ok FROM queries WHERE day >= date('now','-7 days') GROUP BY day, tier ORDER BY day DESC").all(),
     env.DB.prepare("SELECT model, SUM(requests) as requests FROM spend WHERE day >= date('now','-7 days') GROUP BY model ORDER BY requests DESC").all(),
     env.DB.prepare("SELECT rating, COUNT(*) as n FROM feedback GROUP BY rating").all(),
     env.DB.prepare("SELECT COUNT(*) as n FROM conversations").first(),
     env.DB.prepare("SELECT COALESCE(cache, 'miss') AS cache, COUNT(*) AS n FROM queries WHERE day >= date('now','-7 days') AND route = 'ask' GROUP BY cache").all(),
-    env.DB.prepare("SELECT duration_ms FROM queries WHERE day >= date('now','-7 days') AND route = 'ask' AND duration_ms IS NOT NULL").all()
+    env.DB.prepare("SELECT duration_ms FROM queries WHERE day >= date('now','-7 days') AND route = 'ask' AND duration_ms IS NOT NULL").all(),
+    env.DB.prepare("SELECT COALESCE(SUM(retries), 0) AS total, SUM(CASE WHEN retries > 0 THEN 1 ELSE 0 END) AS answers FROM queries WHERE day >= date('now','-7 days') AND route = 'ask'").all()
   ]);
+  const retries = retriesRow?.results?.[0] ?? { total: 0, answers: 0 };
   const ds = durations.results.map((r) => r.duration_ms).sort((a, b) => a - b);
   const pct = (q) => ds.length ? ds[Math.min(ds.length - 1, Math.floor(q * ds.length))] : null;
   const totalQueries = byDay.results.reduce((a, r) => a + (r.n || 0), 0) || 0;
@@ -1407,6 +1409,7 @@ async function adminStatsRoute(c) {
     feedback: feedback.results,
     cache_mix_7d: cacheMix.results,
     latency_ms: ds.length ? { n: ds.length, p50: pct(0.5), p95: pct(0.95) } : null,
+    generate_retries_7d: { total: Number(retries.total) || 0, answers_retried: Number(retries.answers) || 0 },
     conversations: convCount?.n ?? 0,
     error_rate_pct: errorRate,
     index_version: env.INDEX_VERSION,
@@ -1470,11 +1473,20 @@ async function verifyRoute(c) {
     }
     const bound = await bindModelNode(env, { query, standardKeys: entitlementScope(standardKeysFrom(body)) });
     const modelGrounding = bound && !bound.gated ? modelGroundingBlock(bound) : null;
-    const retrieved = await retrieve(env, query, { understanding: u, standardKeys: entitlementScope(standardKeysFrom(body)), lexicalBoost, editionSteer });
-    const passages = retrieved.hits.map((h) => h.text);
+    const supplied = (Array.isArray(body?.passages) ? body.passages : []).map((p) => typeof p === "string" ? p : p?.text ?? "").map((p) => p.trim()).filter(Boolean).slice(0, 8);
+    let passages;
+    let structured = [];
+    if (supplied.length) {
+      passages = supplied;
+      structured = supplied.map((p) => ({ text: p }));
+    } else {
+      const retrieved = await retrieve(env, query, { understanding: u, standardKeys: entitlementScope(standardKeysFrom(body)), lexicalBoost, editionSteer });
+      passages = retrieved.hits.map((h) => h.text);
+      structured = retrieved.hits.map((h) => ({ text: h.text, table: h.metadata.block === "table" || void 0 }));
+    }
     const anchors = checkQuoteAnchors(answer, passages);
     const refs = [...answer.matchAll(/\[\[u:([^\]]+)\]\]/g)].map((m) => m[1]);
-    const validRefs = refs.filter((r) => retrieved.hits.some((h) => h.metadata.unit_id === r));
+    const validRefs = refs.filter((r) => supplied.length ? supplied.some((p) => p.includes(`u:${r}`)) : structured.some((h) => h.text && !h.table));
     const checks = [
       { name: "quote_anchors", deterministic: true, pass: anchors.violations.length === 0, detail: `${anchors.violations.length} of ${anchors.total} quoted spans absent from the retrieved passages` },
       { name: "unit_references", deterministic: true, pass: refs.length === validRefs.length, detail: refs.length ? `${validRefs.length}/${refs.length} unit references resolve to served units` : "no unit references" },
@@ -1482,11 +1494,17 @@ async function verifyRoute(c) {
     ];
     const machine = (Array.isArray(body?.blocks) ? body.blocks : []).filter((b) => b?.type === "verdict" && b?.payload).map((b) => [b.payload.check, b.payload.meaning, b.payload.definition, b.payload.violation_meaning].filter((x) => typeof x === "string" && x).join(" \u2014 ")).filter(Boolean);
     if (modelGrounding) machine.unshift(modelGrounding);
-    const faith = await scoreFaithfulness(env.AI, roleModel(env, "grader"), answer, retrieved.hits.map((h) => ({ text: h.text, table: h.metadata.block === "table" || void 0 })), machine);
+    const faith = await scoreFaithfulness(
+      env.AI,
+      roleModel(env, "grader"),
+      answer,
+      structured,
+      machine
+    );
     return json({
       checks,
       judged: faith ? { name: "faithfulness", deterministic: false, score: faith.score, ungrounded_claims: faith.ungrounded_claims.slice(0, 5) } : null,
-      passages_used: retrieved.hits.length
+      passages_used: passages.length
     });
   } catch (e) {
     return err(502, "verify_failed", String(e).slice(0, 200));

package/package.json

@@ -27,7 +27,7 @@
     "playwright": "^1.62.1",
     "yaml": "^2.9.1"
   },
-  "version": "0.2.31",
+  "version": "0.2.33",
   "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/migrations/0015_ask_retries.sql

@@ -0,0 +1,4 @@
+-- the latency program's aggregate: how many generation retries each ask
+-- needed (Server-Timing carried the count per answer; this column makes
+-- it rollup-able). Existing rows read 0 — they predate the column.
+ALTER TABLE queries ADD COLUMN retries INTEGER NOT NULL DEFAULT 0;

package/workers/worker_public/src/ask.ts

@@ -237,7 +237,7 @@ async function handleAsk(
   // the latency program's clock: every telemetry write below reports the
   // wall time from request entry to its own exit
   const tStart = Date.now();
-  const telemetryMeta = () => ({ durationMs: Date.now() - tStart, keyId: key?.id ?? null });
+  const telemetryMeta = () => ({ durationMs: Date.now() - tStart, keyId: key?.id ?? null, retries: generateRetries });
   // the latency anatomy, surfaced as standard Server-Timing headers on
   // the JSON response — the reduction program's per-stage data
   const stageTiming: Record<string, number> = {};

package/workers/worker_public/src/index.ts

@@ -152,14 +152,16 @@ async function adminStatsRoute(c: RouteContext): Promise<Response> {
   if (!env.ADMIN_TOKEN) return err(501, "admin_disabled", "ADMIN_TOKEN secret is not configured");
   const auth = req.headers.get("authorization") ?? "";
   if (auth !== `Bearer ${env.ADMIN_TOKEN}`) return err(401, "unauthorized", "Invalid admin token");
-  const [byDay, byModel, feedback, convCount, cacheMix, durations] = await Promise.all([
+  const [byDay, byModel, feedback, convCount, cacheMix, durations, retriesRow] = await Promise.all([
     env.DB.prepare("SELECT day, tier, COUNT(*) as n, SUM(ok) as ok FROM queries WHERE day >= date('now','-7 days') GROUP BY day, tier ORDER BY day DESC").all(),
     env.DB.prepare("SELECT model, SUM(requests) as requests FROM spend WHERE day >= date('now','-7 days') GROUP BY model ORDER BY requests DESC").all(),
     env.DB.prepare("SELECT rating, COUNT(*) as n FROM feedback GROUP BY rating").all(),
     env.DB.prepare("SELECT COUNT(*) as n FROM conversations").first(),
     env.DB.prepare("SELECT COALESCE(cache, 'miss') AS cache, COUNT(*) AS n FROM queries WHERE day >= date('now','-7 days') AND route = 'ask' GROUP BY cache").all(),
     env.DB.prepare("SELECT duration_ms FROM queries WHERE day >= date('now','-7 days') AND route = 'ask' AND duration_ms IS NOT NULL").all(),
+    env.DB.prepare("SELECT COALESCE(SUM(retries), 0) AS total, SUM(CASE WHEN retries > 0 THEN 1 ELSE 0 END) AS answers FROM queries WHERE day >= date('now','-7 days') AND route = 'ask'").all(),
   ]);
+  const retries = (retriesRow as any)?.results?.[0] ?? { total: 0, answers: 0 };
   const ds = (durations.results as any[]).map((r) => r.duration_ms as number).sort((a, b) => a - b);
   const pct = (q: number) => (ds.length ? ds[Math.min(ds.length - 1, Math.floor(q * ds.length))] : null);
   const totalQueries = (byDay.results as any[]).reduce((a, r) => a + (r.n || 0), 0) || 0;
@@ -177,6 +179,7 @@ async function adminStatsRoute(c: RouteContext): Promise<Response> {
     feedback: feedback.results,
     cache_mix_7d: cacheMix.results,
     latency_ms: ds.length ? { n: ds.length, p50: pct(0.5), p95: pct(0.95) } : null,
+    generate_retries_7d: { total: Number(retries.total) || 0, answers_retried: Number(retries.answers) || 0 },
     conversations: (convCount as any)?.n ?? 0,
     error_rate_pct: errorRate,
     index_version: env.INDEX_VERSION,
@@ -250,11 +253,33 @@ async function verifyRoute(c: RouteContext): Promise<Response> {
     }
     const bound = await bindModelNode(env, { query, standardKeys: entitlementScope(standardKeysFrom(body)) });
     const modelGrounding = bound && !bound.gated ? modelGroundingBlock(bound) : null;
-    const retrieved = await retrieve(env, query, { understanding: u, standardKeys: entitlementScope(standardKeysFrom(body)), lexicalBoost, editionSteer });
-    const passages = retrieved.hits.map((h: Hit) => h.text);
+    // the caller's grounding WINS when present: the verify button (and
+    // the harness) hold the passages the answer was actually grounded on
+    // — verify's own fresh retrieval is a DIFFERENT pipeline (no grade,
+    // no listwise, no corrective widen) and returns different passages,
+    // which judges the answer against text it never saw
+    const supplied = (Array.isArray(body?.passages) ? body.passages : [])
+      .map((p: unknown) => (typeof p === "string" ? p : (p as any)?.text ?? ""))
+      .map((p: string) => p.trim())
+      .filter(Boolean)
+      .slice(0, 8);
+    let passages: string[];
+    let structured: { text: string; table?: boolean }[] = [];
+    if (supplied.length) {
+      passages = supplied;
+      structured = supplied.map((p: string) => ({ text: p }));
+    } else {
+      const retrieved = await retrieve(env, query, { understanding: u, standardKeys: entitlementScope(standardKeysFrom(body)), lexicalBoost, editionSteer });
+      passages = retrieved.hits.map((h: Hit) => h.text);
+      structured = retrieved.hits.map((h: Hit) => ({ text: h.text, table: (h.metadata as any).block === "table" || undefined }));
+    }
     const anchors = checkQuoteAnchors(answer, passages);
     const refs = [...answer.matchAll(/\[\[u:([^\]]+)\]\]/g)].map((m) => m[1]);
-    const validRefs = refs.filter((r) => retrieved.hits.some((h: Hit) => h.metadata.unit_id === r));
+    // unit references resolve against the grounding in use
+    const validRefs = refs.filter((r: string) =>
+      supplied.length
+        ? supplied.some((p: string) => p.includes(`u:${r}`))
+        : structured.some((h) => h.text && !h.table));
     const checks = [
       { name: "quote_anchors", deterministic: true, pass: anchors.violations.length === 0, detail: `${anchors.violations.length} of ${anchors.total} quoted spans absent from the retrieved passages` },
       { name: "unit_references", deterministic: true, pass: refs.length === validRefs.length, detail: refs.length ? `${validRefs.length}/${refs.length} unit references resolve to served units` : "no unit references" },
@@ -269,11 +294,17 @@ async function verifyRoute(c: RouteContext): Promise<Response> {
         .filter((x: unknown) => typeof x === "string" && x).join(" — "))
       .filter(Boolean);
     if (modelGrounding) machine.unshift(modelGrounding);
-    const faith = await scoreFaithfulness(env.AI, roleModel(env, "grader"), answer, retrieved.hits.map((h: Hit) => ({ text: h.text, table: (h.metadata as any).block === "table" || undefined })), machine);
+    const faith = await scoreFaithfulness(
+      env.AI,
+      roleModel(env, "grader"),
+      answer,
+      structured,
+      machine,
+    );
     return json({
       checks,
       judged: faith ? { name: "faithfulness", deterministic: false, score: faith.score, ungrounded_claims: faith.ungrounded_claims.slice(0, 5) } : null,
-      passages_used: retrieved.hits.length,
+      passages_used: passages.length,
     });
   } catch (e) {
     return err(502, "verify_failed", String(e).slice(0, 200));

package/workers/worker_public/src/quota.ts

@@ -40,14 +40,14 @@ export function telemetry(
   queryHash: string,
   lang?: string,
   cache?: "exact" | "semantic",
-  meta?: { durationMs?: number; keyId?: string | null },
+  meta?: { durationMs?: number; keyId?: string | null; retries?: number },
 ) {
   const day = today();
   ctx.waitUntil(
     env.DB.batch([
       env.DB.prepare(
-        "INSERT INTO queries (ts, day, tier, route, model, ok, answer_chars, query_hash, lang, cache, duration_ms, key_id) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9,?10,?11,?12)",
-      ).bind(new Date().toISOString(), day, tier, route, model, ok ? 1 : 0, answerChars, queryHash, lang ?? null, cache ?? null, meta?.durationMs ?? null, meta?.keyId ?? null),
+        "INSERT INTO queries (ts, day, tier, route, model, ok, answer_chars, query_hash, lang, cache, duration_ms, key_id, retries) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9,?10,?11,?12,?13)",
+      ).bind(new Date().toISOString(), day, tier, route, model, ok ? 1 : 0, answerChars, queryHash, lang ?? null, cache ?? null, meta?.durationMs ?? null, meta?.keyId ?? null, meta?.retries ?? 0),
       env.DB.prepare(
         "INSERT INTO spend (day, tier, model, requests) VALUES (?1,?2,?3,1) ON CONFLICT(day, tier, model) DO UPDATE SET requests = requests + 1",
       ).bind(day, tier, model ?? "none"),