@konneal/engine 0.2.153 → 0.2.157

package/dist/answerGuards.d.ts

@@ -0,0 +1,4 @@
+export declare function toolNarration(t: string): boolean;
+export declare const TOOL_NARRATION_NOTICE = "Correction notice: your draft narrated an internal tool call ('the \u2026 tool returned \u2026') instead of answering. Rewrite: answer the question directly from the retrieved passages, cite the clauses, and never mention tools, queries, wire formats, or JSON.";
+export declare function intentPreamble(t: string): boolean;
+export declare const INTENT_PREAMBLE_NOTICE = "Correction notice: your draft announced a plan ('I'll look up \u2026') instead of answering. Do not narrate intent \u2014 answer the question NOW from the retrieved passages: give the values, clause references and citations the question asks for.";

package/dist/{ask-UIIE5LD2.js → ask-IC5A5LIN.js}

@@ -1,6 +1,6 @@
 import {
   handleAsk
-} from "./chunk-I6HU3EM6.js";
+} from "./chunk-S3O7QZQ7.js";
 import "./chunk-ECOYO7EX.js";
 import "./chunk-VYEMFSU5.js";
 import "./chunk-G2RE4XRV.js";

package/dist/{chunk-I6HU3EM6.js → chunk-S3O7QZQ7.js}

@@ -1637,7 +1637,7 @@ async function extractNameplate(ai, model, image) {
   return null;
 }
 
-// workers/worker_public/src/ask.ts
+// workers/worker_public/src/answerGuards.ts
 function toolNarration(t) {
   return /^(?:the\s+)?[a-z][a-z_.]*\.[a-z_]+ tool returned\b/i.test(t.slice(0, 200)) || /tool returned,? for the query\b/i.test(t.slice(0, 300));
 }
@@ -1649,6 +1649,8 @@ function intentPreamble(t) {
   return !/\[\[u:|\[\^?\d+\]|\b\d+\.\d+\b/.test(s);
 }
 var INTENT_PREAMBLE_NOTICE = "Correction notice: your draft announced a plan ('I'll look up \u2026') instead of answering. Do not narrate intent \u2014 answer the question NOW from the retrieved passages: give the values, clause references and citations the question asks for.";
+
+// workers/worker_public/src/ask.ts
 function userImageDataUrl(body) {
   const img = body?.image;
   if (img == null) return null;
@@ -2912,7 +2914,25 @@ Answer account questions from these records ONLY: name the record when you use i
       ...h.metadata.table_selection ? { sel: h.metadata.table_selection } : {}
     }));
     const tq = await chargeAnswerTokens(env, bucketId, void 0, messageChars(messages), answer.length, probeTokensUsed);
-    return json({ ...out, context: contextOut, read: readAs(), quota: { ...quota, ...tq, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } }, 200, { ...corsHeaders(req), "server-timing": serverTiming() });
+    const manifestOut = body?.manifest === true ? { manifest: {
+      index_version: env.INDEX_VERSION,
+      corpus_gen: gen,
+      model,
+      effort: answerEffort(env),
+      fresh,
+      citations: used.length,
+      retrieval: used.map((h, i) => ({
+        rank: i + 1,
+        doc_id: h.metadata.doc_id,
+        clause_anchor: h.metadata.clause_anchor ?? null,
+        score: h.score,
+        rerank_score: h.rerank_score ?? null
+      })),
+      stages: stageTiming,
+      generate_retries: generateRetries,
+      total_ms: Date.now() - tStart
+    } } : {};
+    return json({ ...out, context: contextOut, read: readAs(), ...manifestOut, quota: { ...quota, ...tq, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } }, 200, { ...corsHeaders(req), "server-timing": serverTiming() });
   };
   if (liveResponse) {
     void pipeline(live, q).catch(() => {

package/dist/enrichPolicy.d.ts

@@ -0,0 +1,29 @@
+/** The model's raw response → the situating context: trimmed, the
+ *  wrapping quotes stripped, capped at 400 chars. Empty string = the
+ *  model had nothing to say (the deterministic-empty class). */
+export declare function normalizeContext(raw: unknown): string;
+export type EnrichOutcome = {
+    action: "serve";
+    context: string;
+    cached: boolean;
+} | {
+    action: "serve-raw";
+} | {
+    action: "fail";
+    error: string;
+};
+/** The per-chunk decision, given the cache read and the generation.
+ *  - a context (cached or generated) serves enriched;
+ *  - an EMPTY generation in the production flow serves the chunk RAW
+ *    (the deterministic-empty class, 2026-10-20: real corpus content —
+ *    B 18's thin terms sections, two R 134-1 clauses — must not vanish
+ *    from the index because its enrichment has nothing to say; a later
+ *    forced re-enrich overwrites the vector in place);
+ *  - an empty generation in mode:context / mode:ab FAILS: those
+ *    builders want the signal, not a side-effecting write. */
+export declare function enrichOutcome(opts: {
+    cached: string | null;
+    generated: string;
+    contextOnly: boolean;
+    abMode: boolean;
+}): EnrichOutcome;

package/dist/worker_public/src/index.js

@@ -4,7 +4,7 @@ import {
   handleMemories,
   scoreFaithfulness,
   scoreJudge
-} from "../../chunk-I6HU3EM6.js";
+} from "../../chunk-S3O7QZQ7.js";
 import "../../chunk-ECOYO7EX.js";
 import {
   TOOLS_REGISTRY,
@@ -351,6 +351,18 @@ async function handleGetShared(env, slug) {
 // workers/worker_public/prompts/enrichment.md
 var enrichment_default = "You write a retrieval context for a passage from {{CORPUS_KIND}}. The context is prepended to the passage before embedding so a semantic search can locate the passage even when the query uses different vocabulary than the passage itself.\n\nWrite ONE concise sentence (at most 40 words) that situates the passage: name the publication by its exact {{PUBLISHER_NAME}} identifier (including part or annex when applicable) and what the passage covers \u2014 paraphrasing the topic in words DIFFERENT from the passage's own. Do not copy the passage verbatim, do not add facts that are not derivable from the passage or its header, do not answer or explain the content. Reply with the context sentence only \u2014 no quotes, no preamble.\n";
 
+// workers/worker_public/src/enrichPolicy.ts
+function normalizeContext(raw) {
+  return typeof raw === "string" ? raw.trim().replace(/^["\']|["']$/g, "").slice(0, 400) : "";
+}
+function enrichOutcome(opts) {
+  const fromCache = typeof opts.cached === "string" && opts.cached;
+  if (fromCache) return { action: "serve", context: fromCache, cached: true };
+  if (opts.generated) return { action: "serve", context: opts.generated, cached: false };
+  if (opts.contextOnly || opts.abMode) return { action: "fail", error: "empty enrichment" };
+  return { action: "serve-raw" };
+}
+
 // workers/worker_public/prompts/doc-summary.md
 var doc_summary_default = "You write the document-level summary for a legal-metrology publication in {{PUBLISHER_NAME}}'s retrieval index. The section summaries below cover the publication clause by clause. Write one compact abstract, three to five sentences: what the publication regulates or provides, its scope and applicability, and the structure a reader should know (parts, annexes, where the normative core sits). Use the publication's own terms exactly. No preamble, no headings.\n";
 
@@ -408,10 +420,15 @@ ${c.text.slice(0, 1500)}` }
             reasoning_effort: abMode ? effort : "high"
           });
           const raw = typeof res?.response === "string" && res.response.trim() ? res.response : res?.choices?.[0]?.message?.content;
-          context = typeof raw === "string" ? raw.trim().replace(/^["\']|[\"']$/g, "").slice(0, 400) : "";
+          context = normalizeContext(raw);
           if (!context) {
             console.log("enrich raw keys:", Object.keys(res ?? {}), "sample:", JSON.stringify(res).slice(0, 300));
-            return { id: c.id, ok: false, error: "empty enrichment" };
+            const outcome = enrichOutcome({ cached: null, generated: "", contextOnly, abMode });
+            if (outcome.action === "fail") return { id: c.id, ok: false, error: outcome.error };
+            const rawText = typeof c.metadata.chunk_text === "string" && c.metadata.chunk_text ? c.metadata.chunk_text : c.text;
+            const rawVector = await embed(portModelRunner(env), MODELS.embed, rawText.slice(0, 6e3));
+            await env.VECTORIZE.upsert([{ id: c.id, values: rawVector, metadata: { ...c.metadata, chunk_text: rawText } }]);
+            return { id: c.id, ok: true, raw: true, cached: false, context: "" };
           }
           if (res?.usage) {
             usage.prompt_tokens += Number(res.usage.prompt_tokens ?? 0);
@@ -1107,7 +1124,7 @@ async function callToolOnce(env, ctx, _req, tier, key, name, args, t0) {
       const r = await runTool({ ...env, DB: env.DB }, { name, args }, "mcp");
       payload = r ? { tool: r.name, query: r.query, result: r.output } : { error: { message: `tool ${name} returned nothing for the given arguments` } };
     } else {
-      const res = name === "ask" ? await (await import("../../ask-UIIE5LD2.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-GAU5SEZI.js")).handleSearch(env, ctx, inner, tier, key);
+      const res = name === "ask" ? await (await import("../../ask-IC5A5LIN.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-GAU5SEZI.js")).handleSearch(env, ctx, inner, tier, key);
       payload = await res.json().catch(() => ({ error: { message: "tool transport failed", status: res.status } }));
     }
     telemetry(env, ctx, tier, `mcp:${name}`, null, !payload?.error, JSON.stringify(payload).length, await sha256Hex(`${name}:${JSON.stringify(args ?? {})}`), void 0, void 0, { durationMs: Date.now() - t0 });

package/package.json

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

@@ -6,6 +6,7 @@ import { embed } from "./ai";
 import { err, json, corsHeaders, readJson, authenticate } from "./lib/http";
 import type { Env } from "./env";
 import enrichmentPrompt from "../prompts/enrichment.md";
+import { normalizeContext, enrichOutcome } from "./enrichPolicy.ts";
 import docSummaryPrompt from "../prompts/doc-summary.md";
 import familySummaryPrompt from "../prompts/family-summary.md";
 import sectionSummaryPrompt from "../prompts/section-summary.md";
@@ -75,10 +76,18 @@ export async function handleEnrich(env: Env, ctx: ExecutionContext, req: Request
           const raw = typeof res?.response === "string" && res.response.trim()
             ? res.response
             : res?.choices?.[0]?.message?.content;
-          context = typeof raw === "string" ? raw.trim().replace(/^["\']|[\"']$/g, "").slice(0, 400) : "";
+          context = normalizeContext(raw);
           if (!context) {
             console.log("enrich raw keys:", Object.keys(res ?? {}), "sample:", JSON.stringify(res).slice(0, 300));
-            return { id: c.id, ok: false, error: "empty enrichment" };
+            // serve-raw: the chunk's own text is real corpus content —
+            // embed it without the context band, upsert without the ctx
+            // marker; a later forced re-enrich overwrites in place.
+            const outcome = enrichOutcome({ cached: null, generated: "", contextOnly, abMode });
+            if (outcome.action === "fail") return { id: c.id, ok: false, error: outcome.error };
+            const rawText = typeof c.metadata.chunk_text === "string" && c.metadata.chunk_text ? c.metadata.chunk_text : c.text;
+            const rawVector = await embed(portModelRunner(env), MODELS.embed, rawText.slice(0, 6000));
+            await env.VECTORIZE.upsert([{ id: c.id, values: rawVector, metadata: { ...c.metadata, chunk_text: rawText } }]);
+            return { id: c.id, ok: true, raw: true, cached: false, context: "" };
           }
           if (res?.usage) {
             usage.prompt_tokens += Number(res.usage.prompt_tokens ?? 0);

package/workers/worker_public/src/answerGuards.ts

@@ -0,0 +1,36 @@
+// The answer-contract's text guards, dependency-free so plain node can
+// load them for unit tests (ask.ts imports .md prompts that only the
+// bundler resolves — the guards were module-local there and rode e2e
+// alone). Both lanes share them: the JSON lane's contract retry and the
+// streamed lane's 80-char head ruling.
+
+// The tool-narration leak (2026-10-14, the R 134-1 probe): the answer
+// model sometimes NARRATES the agent loop's call in prose — 'The
+// db.find tool returned, for the query "…": {…json…}' — instead of
+// answering. The TOOL-line scrub cannot catch prose. The JSON lane
+// regenerates through the contract retry; the streamed lane buffers
+// the head and sends the retry sentinel (the blind-answer guard's
+// client contract) before streaming the fresh answer. One bounded
+// restart per lane.
+export function toolNarration(t: string): boolean {
+  return /^(?:the\s+)?[a-z][a-z_.]*\.[a-z_]+ tool returned\b/i.test(t.slice(0, 200)) ||
+    /tool returned,? for the query\b/i.test(t.slice(0, 300));
+}
+export const TOOL_NARRATION_NOTICE =
+  "Correction notice: your draft narrated an internal tool call ('the … tool returned …') instead of answering. Rewrite: answer the question directly from the retrieved passages, cite the clauses, and never mention tools, queries, wire formats, or JSON.";
+
+// The intent preamble (2026-10-19, the ~200-word technical-file
+// question): the draft is a PLAN, not an answer — "I'll look up the R
+// 76-1 MPE clause and classification details in the corpus." — shipped
+// while ten citations rode the same response. Narrow by construction:
+// it must OPEN with a first-person intent verb AND carry no substance —
+// short, no clause citation, no normative numbers (a real answer's
+// opening names values or clauses).
+export function intentPreamble(t: string): boolean {
+  const s = (t ?? "").trim();
+  if (s.length > 240) return false;
+  if (!/^(?:i'll|i will|let me|let's|i'm going to|i am going to)\b/i.test(s)) return false;
+  return !/\[\[u:|\[\^?\d+\]|\b\d+\.\d+\b/.test(s);
+}
+export const INTENT_PREAMBLE_NOTICE =
+  "Correction notice: your draft announced a plan ('I'll look up …') instead of answering. Do not narrate intent — answer the question NOW from the retrieved passages: give the values, clause references and citations the question asks for.";

package/workers/worker_public/src/ask.ts

@@ -49,37 +49,8 @@ import { TOOL_DECLARATION, parseToolCall, runTool, toolNote } from "./tools";
 import { operationsLane } from "./operations.ts";
 import { extractNameplate, nameplateRegisterQuery } from "./nameplate.ts";
 import { P } from "./profile.ts";
+import { toolNarration, intentPreamble, TOOL_NARRATION_NOTICE, INTENT_PREAMBLE_NOTICE } from "./answerGuards.ts";
 
-// the tool-narration leak (2026-10-14, the R 134-1 probe): the answer
-// model sometimes NARRATES the agent loop's call in prose — 'The
-// db.find tool returned, for the query "…": {…json…}' — instead of
-// answering. The TOOL-line scrub cannot catch prose. The JSON lane
-// regenerates through the contract retry; the streamed lane buffers
-// the head and sends the retry sentinel (the blind-answer guard's
-// client contract) before streaming the fresh answer. One bounded
-// restart per lane.
-function toolNarration(t: string): boolean {
-  return /^(?:the\s+)?[a-z][a-z_.]*\.[a-z_]+ tool returned\b/i.test(t.slice(0, 200)) ||
-    /tool returned,? for the query\b/i.test(t.slice(0, 300));
-}
-const TOOL_NARRATION_NOTICE =
-  "Correction notice: your draft narrated an internal tool call ('the … tool returned …') instead of answering. Rewrite: answer the question directly from the retrieved passages, cite the clauses, and never mention tools, queries, wire formats, or JSON.";
-
-// The intent preamble (2026-10-19, the ~200-word technical-file
-// question): the draft is a PLAN, not an answer — "I'll look up the R
-// 76-1 MPE clause and classification details in the corpus." — shipped
-// while ten citations rode the same response. Narrow by construction:
-// it must OPEN with a first-person intent verb AND carry no substance —
-// short, no clause citation, no normative numbers (a real answer's
-// opening names values or clauses).
-function intentPreamble(t: string): boolean {
-  const s = (t ?? "").trim();
-  if (s.length > 240) return false;
-  if (!/^(?:i'll|i will|let me|let's|i'm going to|i am going to)\b/i.test(s)) return false;
-  return !/\[\[u:|\[\^?\d+\]|\b\d+\.\d+\b/.test(s);
-}
-const INTENT_PREAMBLE_NOTICE =
-  "Correction notice: your draft announced a plan ('I'll look up …') instead of answering. Do not narrate intent — answer the question NOW from the retrieved passages: give the values, clause references and citations the question asks for.";
 
 /** User-uploaded image for multimodal questions: a data URL
  *  (data:image/(png|jpeg|webp|gif);base64,…) up to 6 MB of payload. The
@@ -1998,7 +1969,33 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
     ...((h.metadata as any).table_selection ? { sel: (h.metadata as any).table_selection } : {}),
   }));
   const tq = await chargeAnswerTokens(env, bucketId, undefined, messageChars(messages!), answer!.length, probeTokensUsed);
-  return json({ ...out, context: contextOut, read: readAs(), quota: { ...quota, ...tq, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } }, 200, { ...corsHeaders(req), "server-timing": serverTiming() });
+  // the reproducibility manifest (TODO.sota/14.6, v1): an opt-in, one-object
+  // derivation record — the served snapshot identity, the answer model, the
+  // retrieval anatomy (rank, corpus score, rerank score per used passage),
+  // the stage timings, and the enforcement counters. Everything here is
+  // already computed; the flag only ASSEMBLES it for the harness and for
+  // external auditors. v2 names the CRAG grades per passage.
+  const manifestOut = body?.manifest === true
+    ? { manifest: {
+        index_version: env.INDEX_VERSION,
+        corpus_gen: gen,
+        model,
+        effort: answerEffort(env),
+        fresh,
+        citations: used.length,
+        retrieval: used.map((h: Hit, i: number) => ({
+          rank: i + 1,
+          doc_id: h.metadata.doc_id,
+          clause_anchor: h.metadata.clause_anchor ?? null,
+          score: h.score,
+          rerank_score: h.rerank_score ?? null,
+        })),
+        stages: stageTiming,
+        generate_retries: generateRetries,
+        total_ms: Date.now() - tStart,
+      } }
+    : {};
+  return json({ ...out, context: contextOut, read: readAs(), ...manifestOut, quota: { ...quota, ...tq, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } }, 200, { ...corsHeaders(req), "server-timing": serverTiming() });
   }
 
   // THE DISPATCH: the streamed lane's response went out at the top — the

package/workers/worker_public/src/enrichPolicy.ts

@@ -0,0 +1,40 @@
+// The enrichment route's decision policy, dependency-free so plain node
+// can load it for unit tests (admin.ts imports .md prompts that only
+// the bundler resolves — the serve-raw policy rode the live
+// verification alone until this extraction). The handler keeps the
+// I/O: cache, generation, embedding, upsert; this module owns the
+// DECISION table — what a chunk's outcome is, given what came back.
+
+/** The model's raw response → the situating context: trimmed, the
+ *  wrapping quotes stripped, capped at 400 chars. Empty string = the
+ *  model had nothing to say (the deterministic-empty class). */
+export function normalizeContext(raw: unknown): string {
+  return typeof raw === "string" ? raw.trim().replace(/^["\']|["']$/g, "").slice(0, 400) : "";
+}
+
+export type EnrichOutcome =
+  | { action: "serve"; context: string; cached: boolean }
+  | { action: "serve-raw" }
+  | { action: "fail"; error: string };
+
+/** The per-chunk decision, given the cache read and the generation.
+ *  - a context (cached or generated) serves enriched;
+ *  - an EMPTY generation in the production flow serves the chunk RAW
+ *    (the deterministic-empty class, 2026-10-20: real corpus content —
+ *    B 18's thin terms sections, two R 134-1 clauses — must not vanish
+ *    from the index because its enrichment has nothing to say; a later
+ *    forced re-enrich overwrites the vector in place);
+ *  - an empty generation in mode:context / mode:ab FAILS: those
+ *    builders want the signal, not a side-effecting write. */
+export function enrichOutcome(opts: {
+  cached: string | null;
+  generated: string;
+  contextOnly: boolean;
+  abMode: boolean;
+}): EnrichOutcome {
+  const fromCache = typeof opts.cached === "string" && opts.cached;
+  if (fromCache) return { action: "serve", context: fromCache, cached: true };
+  if (opts.generated) return { action: "serve", context: opts.generated, cached: false };
+  if (opts.contextOnly || opts.abMode) return { action: "fail", error: "empty enrichment" };
+  return { action: "serve-raw" };
+}