@konneal/engine 0.2.104 → 0.2.109

package/workers/worker_public/src/ask.ts

@@ -6,7 +6,7 @@
 import { LIMITS, MODELS, THRESHOLDS, num, sha256Hex, roleModel, answerEffort, requestEffort, effortBudget } from "./config";
 import { portModelRunner } from "./env.ts";
 import { refCodec } from "./codecs";
-import { buildMessages, citations, retrieve, retrievalQuery, identityNote, splitHistory, listwiseRerank, refusalAnswer, Hit } from "./pipeline";
+import { buildMessages, citations, fill, promptVars, retrieve, retrievalQuery, identityNote, splitHistory, listwiseRerank, refusalAnswer, Hit } from "./pipeline";
 import { sessionFrom } from "./auth";
 import { retrieveInternal } from "./internal_gateway";
 import { understandQuery } from "./understand";
@@ -34,6 +34,11 @@ import { memoryNote } from "./memories";
 import { entitlementScope, resolveRequestScope, requestSalt, standardKeysFrom } from "./requestScope";
 import { rawSessionToken, type SessionClaims } from "./session";
 import { cacheKeyMaterial, corpusGen, exactCacheKey, freshRequested } from "./answercache";
+import { parseAblate } from "./ablate";
+import { STAGE_NAMES } from "./stages/index.ts";
+import { routeFor, fastRouteStages } from "./route.ts";
+import { partitionSubsets, type Partitionable } from "./speculative.ts";
+import speculativeVerifyPrompt from "../prompts/speculative-verify.md";
 import type { Env } from "./env";
 export type { Env };
 import { json, err, corsHeaders, readJson, validateQuery, type ApiKey } from "./lib/http";
@@ -59,6 +64,57 @@ function userImageDataUrl(body: any): string | null {
   return img;
 }
 
+// drafts are candidates, not the answer: half the window budget keeps
+// each draft short and keeps the parallel leg inside the single-call
+// latency it must beat
+const DRAFT_TOKEN_BUDGET = 1600;
+
+/** The verifier's passage listing: the same [n] label grammar the
+ *  answer path builds (the final answer cites against it). */
+function speculativeListing(hits: Hit[]): string {
+  return hits
+    .map((h, i) => {
+      const id = (h.metadata.docidentifier || h.metadata.doc_id || "source").replace(/\s*\(([A-Z])\)\s*$/, "").trim();
+      const edition = h.metadata.edition && !id.includes(h.metadata.edition) ? ":" + h.metadata.edition : "";
+      const anchor = h.metadata.clause_anchor ? ` §${h.metadata.clause_anchor}` : "";
+      return `[${i + 1}] ${id}${edition}${anchor} ${h.text.replace(/\s+/g, " ").slice(0, 700)}`;
+    })
+    .join("\n\n");
+}
+
+/** Speculative draft-verify: draft per diversified subset (parallel,
+ *  cheap model, contract-shaped messages), then ONE strong call
+ *  verifies every candidate against the FULL window and produces the
+ *  final answer. Null on any failure — the caller's normal generation
+ *  stands. */
+async function speculativeDraftVerify(
+  env: Env,
+  opts: { query: string; hits: Hit[]; lang?: string | null; draftModel: string; verifierModel: string },
+): Promise<{ answer: string; chosen: number; nDrafts: number } | null> {
+  const subsets = partitionSubsets(opts.hits as unknown as Partitionable[]);
+  if (!subsets) return null;
+  const draftSets = subsets.map((subset) =>
+    buildMessages(opts.query, subset as unknown as Hit[], opts.lang ?? undefined, [], undefined, undefined, DRAFT_TOKEN_BUDGET).messages,
+  );
+  const drafts = await Promise.all(
+    draftSets.map((m) => generateOnce(env, opts.draftModel, m, "low").catch(() => null)),
+  );
+  const candidates = drafts
+    .map((d) => (d ?? "").trim())
+    .filter((d) => d.length > 0);
+  if (!candidates.length) return null;
+  const candidateText = candidates
+    .map((d, i) => `<candidate ${i + 1} (prepared from a partial view)>\n${d}\n</candidate ${i + 1}>`)
+    .join("\n\n");
+  const system = fill(speculativeVerifyPrompt.trimEnd(), promptVars({}));
+  const answer = await generateOnce(env, opts.verifierModel, [
+    { role: "system", content: system },
+    { role: "user", content: `Question: ${opts.query}\n\nCandidate draft answers:\n${candidateText}\n\nFull context passages:\n${speculativeListing(opts.hits)}` },
+  ], "low").catch(() => null);
+  if (!answer || !answer.trim()) return null;
+  return { answer, chosen: candidates.length, nDrafts: drafts.length };
+}
+
 async function cacheGet(env: Env, gen: string, ns: string, query: string, lang?: string, salt?: string | null) {
   const key = exactCacheKey(env.INDEX_VERSION, gen, ns, await sha256Hex(cacheKeyMaterial(query, lang, salt)));
   const hit = await env.CACHE.get(key, "json");
@@ -298,6 +354,12 @@ async function handleAsk(
   const body = await readJson(req);
   const q = validateQuery(body);
   if (!q) return err(400, "invalid_input", `query is required (1-${LIMITS.maxInputChars} chars)`);
+  // the ablation boundary (TODO.sota/09): a runner-scored configuration
+  // rides the body behind the admin credential. Failures are loud — a
+  // runner must never mistake a rejected configuration for a measured one.
+  const ablated = parseAblate(body, env.ADMIN_TOKEN, req.headers.get("x-admin-token"), STAGE_NAMES);
+  if (!ablated.ok) return err(ablated.status, ablated.code, ablated.message);
+  const ablate = ablated.config;
 
   // The declared context (TODO.ai-platform/02): the panel's opt-in chips.
   // A declared context makes the answer depend on MORE than the query, so
@@ -339,6 +401,13 @@ async function handleAsk(
       : null);
   // resolved before the quota check: the effort choice prices the ask
   const effort = requestEffort(env, member, (body as any)?.effort);
+  // the fast route floors GENERATION effort at low (a scoped or
+  // definitional question needs no deep reasoning; the caller's
+  // declared effort always wins). Quota keeps the declared weight —
+  // the floor is a serving decision, not a billing one.
+  const declaredEffort = (body as any)?.effort;
+  const routeEffort = (route: "fast" | "deep") =>
+    route === "fast" && !declaredEffort ? ("low" as const) : effort;
 
   const limit =
     tier === "key" ? key!.day_limit : tier === "member" || member ? num(env as any, "MEMBER_DAY_ASK", 300) : num(env as any, "ANON_DAY_ASK", 20);
@@ -469,7 +538,7 @@ async function handleAsk(
   // cache.py) and old-generation entries miss (oimlsmart/rag#72)
   const gen = await corpusGen(env.CACHE);
   const withImage = effectiveImage || storedImage;
-  const cached = fresh || contextual || declaredCtx || draftAct || apiCallIntent || withImage ? null : await cacheGet(env, gen, ns, q.query, q.lang, salt);
+  const cached = fresh || contextual || declaredCtx || draftAct || apiCallIntent || withImage || ablate ? null : await cacheGet(env, gen, ns, q.query, q.lang, salt);
   const wantsStream = body?.stream === true || (tier === "anon" && body?.stream !== false);
 
   if (cached) {
@@ -877,7 +946,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
   // the worker EXECUTES the bound node's machine checks against the
   // question's stated values; the model narrates the computed verdict
   // and the verdict BLOCK is server-built — data, never generated prose
-  const machineVerdict = boundModel && !boundModel.gated ? machineEvaluate(boundModel.content, q.query) : null;
+  const machineVerdict = boundModel && !boundModel.gated && !ablate?.noVerdict ? machineEvaluate(boundModel.content, q.query) : null;
   const machineNote = machineVerdict && boundModel ? verdictNote(machineVerdict, boundModel) : undefined;
   // ── condition-set membership (konneal/engine#90): the test-method
   // packages' severity menus as machine-verifiable membership. Fires
@@ -903,7 +972,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
   };
   let conditionVerdict: ConditionVerdict | null = null;
   let conditionStandard: string | null = null;
-  if (!machineVerdict && !boundModel && P().publisher.features?.model_plane) {
+  if (!machineVerdict && !boundModel && !ablate?.noVerdict && P().publisher.features?.model_plane) {
     const ql = q.query.toLowerCase();
     const severityWord = /\b(severity|test|valid|tolerance|condition|within)\b/.test(ql);
     const stated = quantitiesIn(q.query);
@@ -1055,6 +1124,18 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
       boundaryNote = boundaryNoteText(match, citing);
     }
   }
+  // ── the adaptive route (TODO.sota/05): understanding's features pick
+  // fast (the registry minus the expansion lanes) or deep (full). The
+  // ablation override wins when present — the grid measures the routes
+  // by forcing them; adaptive is the serving default. The decision
+  // reads the FINAL understanding (the declared-context and text-naming
+  // reconciliations above may have written the scope the router trusts).
+  const routeMode = ablate?.route ?? "adaptive";
+  const routed = routeMode === "adaptive"
+    ? routeFor(understanding, q.query)
+    : { route: routeMode, features: [`forced-${routeMode}`] };
+  const routeSubset = ablate?.stages ?? (routed.route === "fast" ? fastRouteStages(STAGE_NAMES) : null);
+  if (routeSubset) console.log("route:", routed.route, routed.features.join("+"), "—", STAGE_NAMES.length - routeSubset.length, "lanes dropped");
   try {
     const tR = Date.now();
     // ── The "my account" live read (TODO.ai-platform/03) — resolved
@@ -1111,7 +1192,8 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
     // publications there).
     retrieved = await retrieve(env, q.query, { prev, understanding, federate, warmEmbed, graphDocNumbers,
       sealScope: declaredScoped ? docScope : null, optimisticHits, optimisticVec,
-      datasetScope: narrowed ? corpora : null, standardKeys, lexicalBoost, licensedDocNumbers });
+      datasetScope: narrowed ? corpora : null, standardKeys, lexicalBoost, licensedDocNumbers,
+      ...(routeSubset ? { stageSubset: routeSubset } : {}) });
     stageTiming["retrieve-core"] = Date.now() - tR;
     console.log("stage: retrieve", Date.now() - tR, "ms");
     // ── TTFT surgery: the two post-retrieval LLM calls run IN PARALLEL —
@@ -1145,7 +1227,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
     if (grade === "weak" && understanding?.docidentifier) {
       const broaden = `${understanding.standalone_query || q.query} ${understanding.docidentifier}`.trim();
       const tc = Date.now();
-      const second = await retrieve(env, q.query, { prev, understanding, queryOverride: broaden, federate, datasetScope: narrowed ? corpora : null, standardKeys, sealScope: declaredScoped ? docScope : null, lexicalBoost });
+      const second = await retrieve(env, q.query, { prev, understanding, queryOverride: broaden, federate, datasetScope: narrowed ? corpora : null, standardKeys, sealScope: declaredScoped ? docScope : null, lexicalBoost, ...(routeSubset ? { stageSubset: routeSubset } : {}) });
       const grade2 = await gradeRetrieval(env.AI, roleModel(env, "grader"), q.query, second.hits.map((h: Hit) => h.text));
       stageTiming.corrective = Date.now() - tc;
       if (grade2 === "good") retrieved = second; // corrective retry must be strictly better
@@ -1163,7 +1245,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
     // point at the declare flow
     const answer =
       licenseBoundaryRefusal(modelDocHint?.doc_number ?? understanding?.doc_number ?? null, standardKeys) ?? refusalAnswer();
-    const out = { answer, citations: [], model, query_hash: await sha256Hex(q.query), context_applied: ctxApplied };
+    const out = { answer, citations: [], model, query_hash: await sha256Hex(q.query), context_applied: ctxApplied, ...(ablate ? { ablate } : {}), route: { route: routed.route, features: routed.features } };
     telemetry(env, ctx, tier, "ask", model, true, answer.length, out.query_hash, q.lang, undefined, telemetryMeta());
     return json({ ...out, quota, });
   }
@@ -1304,7 +1386,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
   const cites = boundModel ? [modelCitation(boundModel), ...citations(usedHits)] : citations(usedHits);
 
   if (wantsStream) {
-    const stream = await generateStream(env, model, messages, effort);
+    const stream = await generateStream(env, model, messages, routeEffort(routed.route));
     if (stream) {
       const encoder = new TextEncoder();
       const sse = new ReadableStream({
@@ -1349,7 +1431,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
               ...messages.slice(0, -1),
               { role: "user", content: "The photograph was attached and the register note lists actual matching certificate rows. Present those rows — number, holder, model, status, and every document link — as the answer. Do not claim that nothing was provided." },
               messages[messages.length - 1],
-            ], effort);
+            ], routeEffort(routed.route));
             if (regen) {
               full = "";
               try {
@@ -1401,7 +1483,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
           if (streamed.violations.length > 0) {
             console.log("anchors:", streamed.violations.length, "of", streamed.total, "unverified — not caching");
           }
-          if (streamed.violations.length === 0 && canonical.length > 0 && !contextual && !declaredCtx && !canonical.includes(refusalAnswer())) {
+          if (streamed.violations.length === 0 && canonical.length > 0 && !contextual && !declaredCtx && !canonical.includes(refusalAnswer()) && !ablate) {
             ctx.waitUntil(
               env.CACHE.put(exactCacheKey(env.INDEX_VERSION, gen, ns, await sha256Hex(cacheKeyMaterial(q.query, q.lang, salt))), JSON.stringify({ answer: canonical, citations: cites, model, query_hash: queryHash, ...(sourceQuality ? { source_quality: sourceQuality, confidence_note: streamedNote || qualityNote(sourceQuality) } : {}), ...(streamedEntailment ? { entailment: streamedEntailment } : {}) }), { expirationTtl: LIMITS.cacheTtlSec }),
             );
@@ -1421,7 +1503,28 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
   }
 
   const tGen = Date.now();
-  let answer = await generateOnce(env, model, messages, effort);
+  // ── speculative draft-verify (TODO.sota/02 row 2): when the ablation
+  // config arms it, the cheap model drafts per diversified subset in
+  // parallel and one strong call verifies against the FULL window. The
+  // seam replaces only the primary generation call — the contract
+  // checks below run on the verifier's output exactly as on any answer —
+  // and any failure falls through to the normal single-shot path.
+  let answer: string | null = null;
+  if (ablate?.speculative) {
+    const spec = await speculativeDraftVerify(env, {
+      query: q.query, hits: usedHits, lang: q.lang,
+      draftModel: MODELS.member, verifierModel: roleModel(env, "verifier"),
+    }).catch((e: unknown) => {
+      console.log("speculative: failed, falling through —", String(e).slice(0, 120));
+      return null;
+    });
+    if (spec) {
+      answer = spec.answer;
+      stageTiming.speculative = Date.now() - tGen;
+      console.log("speculative:", spec.nDrafts, "drafts,", spec.chosen, "viable — verified");
+    }
+  }
+  if (!answer) answer = await generateOnce(env, model, messages, routeEffort(routed.route));
   if (answer === null) {
     generateRetries += 1;
     // the fallback is a text-only model: image parts must be flattened
@@ -1441,7 +1544,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
           ? m
           : { ...m, content: m.content.filter((p: any) => p?.type === "text").map((p: any) => (p?.text ?? "").replace(/\n?\(The user attached an image with this question; interpret it directly when answering\.\)/, "")).join("\n") },
       );
-    answer = await generateOnce(env, MODELS.fallback, flat, effort);
+    answer = await generateOnce(env, MODELS.fallback, flat, routeEffort(routed.route));
   }
   if (answer) answer = canonicalRefusal(answer);
   stageTiming.generate = Date.now() - tGen;
@@ -1479,7 +1582,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
         ? `Correction notice: your draft reproduced a table as markdown or presented a served table's data without its reference. Rewrite the answer: describe the table in prose, cite the clause, and write the reference token [[u:${tableUnitId ?? "<unit id>"}]] exactly where the table belongs. Do not render any table as markdown.`
         : ANCHOR_CORRECTION_NOTE;
       generateRetries += 1;
-      const corrected = await generateOnce(env, model, [...messages, { role: "system", content: note }], effort);
+      const corrected = await generateOnce(env, model, [...messages, { role: "system", content: note }], routeEffort(routed.route));
       if (corrected) {
         const correctedAnswer = canonicalRefusal(corrected);
         const retryAnchors = checkQuoteAnchors(correctedAnswer, used.map((h: Hit) => h.text));
@@ -1519,10 +1622,11 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
         sealScope: declaredScoped ? docScope : null,
         datasetScope: narrowed ? corpora : null,
         standardKeys,
+        ...(routeSubset ? { stageSubset: routeSubset } : {}),
       });
       if (retryRetrieve.hits.length > 0) {
         const { messages: retryMessages, usedHits: retryUsed } = buildMessages(q.query, retryRetrieve.hits, q.lang, keptHistory, undefined, summary, budget);
-        const retryAnswer = await generateOnce(env, model, retryMessages, effort);
+        const retryAnswer = await generateOnce(env, model, retryMessages, routeEffort(routed.route));
         // the answer now comes from the retry passages — citations must follow
         if (retryAnswer) {
           answer = canonicalRefusal(retryAnswer);
@@ -1602,8 +1706,8 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
       if (v.support !== "supported") console.log("entailment:", v.support, raced.score, raced.ungrounded_claims?.slice(0, 2));
     }
   }
-  const out = { answer, citations: finalCites, ...(jsonQuality ? { source_quality: jsonQuality, confidence_note: entailmentNote || qualityNote(jsonQuality), ...(entailment ? { entailment } : {}), ...(jsonQuality === "ocr" ? { experimental_sources: experimentalSourceLabels(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 cacheable = !contextual && !declaredCtx && !answer.includes(refusalAnswer()) && finalAnchors.violations.length === 0;
+  const out = { answer, citations: finalCites, ...(jsonQuality ? { source_quality: jsonQuality, confidence_note: entailmentNote || qualityNote(jsonQuality), ...(entailment ? { entailment } : {}), ...(jsonQuality === "ocr" ? { experimental_sources: experimentalSourceLabels(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 } : {}), ...(ablate ? { ablate } : {}), route: { route: routed.route, features: routed.features } };
+  const cacheable = !contextual && !declaredCtx && !ablate && !answer.includes(refusalAnswer()) && finalAnchors.violations.length === 0;
   if (cacheable) {
     const ck = exactCacheKey(env.INDEX_VERSION, gen, ns, await sha256Hex(cacheKeyMaterial(q.query, q.lang, salt)));
     ctx.waitUntil(env.CACHE.put(ck, JSON.stringify(out), { expirationTtl: LIMITS.cacheTtlSec }));

package/workers/worker_public/src/config.ts

@@ -24,6 +24,11 @@ export const MODELS = {
   listwise: "@cf/zai-org/glm-4.7-flash",
   // deep-research loop (G10): bounded agentic iterations, members-only
   research: "@cf/zai-org/glm-5.3-flash",
+  // speculative draft-verify (TODO.sota/02 row 2): the strong verifier
+  // over the cheap drafts — the research-tier model verifies; the drafter
+  // is the standard answer model (MODELS.member). VERIFIER_MODEL swaps it
+  // live, same lever as every role.
+  verifier: "@cf/zai-org/glm-5.2",
 } as const;
 
 export const LIMITS = {
@@ -62,6 +67,11 @@ export const THRESHOLDS = {
    *  pool below the primary dense lane; they must earn their window
    *  slot under the cross-encoder, not by graph membership alone. */
   graphLaneDiscount: 0.75,
+  /** The PPR lane's merge discount (TODO.sota/06, catalog row 4): graph-
+   *  propagated candidates arrive at the same half-discount the narrowed
+   *  graph lane pays (rag#137's law — flooding dilutes the pool), and
+   *  only the cross-encoder's preference survives the cut. */
+  pprDiscount: 0.375,
   licensedLaneScore: 0.5,
   /** The entailment gate (TODO.new-era/10): the faithfulness scorer
    *  promoted from eval-only onto the serving path. The confidence line

package/workers/worker_public/src/pipeline.ts

@@ -36,7 +36,7 @@ import { QueryFilters, toVectorizeFilter, standardKeyAllowed } from "./selfquery
 import { hitQuality } from "./quality";
 import { lexicalPrefilter } from "./lexical";
 import { positionOrder } from "./structural";
-import { STAGES, runStages } from "./stages";
+import { STAGES, projectStages, runStages } from "./stages";
 import type { PipelineContext, RetrieveOptions, GlossaryEntry } from "./stages/types";
 // the chunk wire contract lives with its pydantic twin (workers/shared/
 // chunk.ts ↔ ingest/vector_adapter.py); re-exported here so the existing
@@ -144,7 +144,10 @@ export async function retrieve(
     env, query, rq, folded, u, filters, filter, vector, lexicalHits,
     matches: [], hits: [], finalHits: [], glossary: [], notes: [], opts, lane: {},
   };
-  await runStages(STAGES, ctx);
+  // the registry IS the switch: an ablation configuration projects the
+  // SAME registry (same modules, same order) to its named subset — a
+  // narrower pipeline, never a forked one
+  await runStages(opts.stageSubset?.length ? projectStages(opts.stageSubset) : STAGES, ctx);
   return {
     hits: ctx.finalHits,
     filters: ctx.filters ?? {},

package/workers/worker_public/src/route.ts

@@ -0,0 +1,77 @@
+// ── The adaptive router (TODO.sota/05, the catalog's row 1) ──
+//
+// Query features (understanding's own output, never string hacks) pick
+// the route: FAST drops the candidate-expansion lanes (hyde, multi-
+// query, sub-query — each costs extra embeds and Vectorize queries, and
+// for a scoped, definitional, or short question they rarely fire); DEEP
+// keeps the full registry. The stage registry IS the switch: the route
+// is a projection of the same registry, never a second pipeline.
+//
+// The policy is deliberately conservative — ambiguous questions route
+// DEEP, and the caller-declared effort always wins — because the
+// routing frontier is a measured claim (TODO.sota/09's grid scores
+// route-fast, route-deep and adaptive on the dev half; the policy
+// thresholds tune after that evidence, never before).
+//
+// Self-contained (no imports) so the unit tests run on plain node type
+// stripping, like ablate/answercache/verdict.
+
+export type Route = "fast" | "deep";
+
+/** Minimal structural shape of the understanding the router reads —
+ *  the full contract lives in understandContract.ts; this subset keeps
+ *  the module self-contained. */
+export interface RouteFeatures {
+  complexity?: "simple" | "complex" | null;
+  doc_number?: string | null;
+  term?: string | null;
+  defined_terms?: string[];
+  sub_queries?: string[];
+  process_intent?: boolean;
+}
+
+/** THRESHOLDS-adjacent policy numbers (declared here until the grid
+ *  measures them; every steering number lives in one place — this is
+ *  the router's place). */
+export const ROUTE_FAST_WORD_CAP = 10;
+
+/** The candidate-expansion lanes the fast route drops (the stage
+ *  names in the registry). */
+export const ROUTE_FAST_DROPS = ["hyde", "multi-query", "sub-query"];
+
+/** Route one question from its understanding features. Returns the
+ *  route and the fired features — the response echoes both, which is
+ *  the telemetry the routing-accuracy analysis reads (TODO.sota/05). */
+export function routeFor(u: RouteFeatures | null, query: string): {
+  route: Route;
+  features: string[];
+} {
+  const features: string[] = [];
+  const words = query.trim().split(/\s+/).filter(Boolean).length;
+
+  // DEEP features — complexity is the understanding model's own
+  // multi-perspective judgment; sub-queries and process intent both
+  // need the widest candidate pool
+  if (u?.complexity === "complex") features.push("complex");
+  if ((u?.sub_queries ?? []).length > 0) features.push("sub-queries");
+  if (u?.process_intent) features.push("process-intent");
+  if (words > ROUTE_FAST_WORD_CAP) features.push("long-question");
+  if (features.length) return { route: "deep", features };
+
+  // FAST — everything else: a question within the word cap rides the
+  // fast registry. The conservative direction is structural here: the
+  // long, the complex, the multi-perspective and the process-shaped all
+  // routed deep above; under-routing costs accuracy, over-routing costs
+  // only latency, and the grid prices both.
+  if (u?.doc_number) features.push("doc-scoped");
+  if (u?.term) features.push("definitional");
+  if ((u?.defined_terms ?? []).length > 0) features.push("terminology");
+  features.push("short-question");
+  return { route: "fast", features };
+}
+
+/** The fast route's stage list: the registry minus the expansion lanes.
+ *  projectStages owns the ordering and validation semantics. */
+export function fastRouteStages(registry: readonly string[]): string[] {
+  return registry.filter((n) => !ROUTE_FAST_DROPS.includes(n));
+}

package/workers/worker_public/src/speculative.ts

@@ -0,0 +1,39 @@
+// ── Speculative draft-verify, the geometry (TODO.sota/02, row 2) ──
+//
+// The partition of the answer window into DIVERSIFIED subsets: hits
+// group by document (first-seen order), the groups deal round-robin
+// into the subsets, and each subset keeps reading order. Fewer than two
+// distinct documents means nothing to diversify — the orchestration
+// (ask.ts) falls through to the normal single-shot generation.
+//
+// Self-contained (no imports) so the unit tests run on plain node type
+// stripping, like ablate/answercache/verdict. The LLM legs (draft per
+// subset, the strong verifier) live in ask.ts beside the other
+// ask-path mechanisms; their gate is the ablation grid (TODO.sota/09),
+// never the unit suite.
+
+export const SPECULATIVE_SUBSETS = 3;
+
+/** Minimal structural shape the partition reads. */
+export interface Partitionable {
+  metadata: { docidentifier?: string; doc_id?: string };
+}
+
+export function partitionSubsets<T extends Partitionable>(
+  hits: T[],
+  k: number = SPECULATIVE_SUBSETS,
+): T[][] | null {
+  const groups: T[][] = [];
+  const byDoc = new Map<string, T[]>();
+  for (const h of hits) {
+    const key = h.metadata.docidentifier || h.metadata.doc_id || "";
+    const arr = byDoc.get(key) ?? [];
+    arr.push(h);
+    if (arr.length === 1) groups.push(arr);
+    byDoc.set(key, arr);
+  }
+  if (groups.length < 2) return null;
+  const subsets: T[][] = Array.from({ length: Math.min(k, groups.length) }, () => []);
+  groups.forEach((g, i) => subsets[i % subsets.length].push(...g));
+  return subsets;
+}

package/workers/worker_public/src/stages/graphPpr.ts

@@ -0,0 +1,189 @@
+// Graph PPR lane (additive, TODO.sota/06 — the catalog's row 4,
+// HippoRAG-style multi-hop memory): Personalized-PageRank over the D1
+// graph projection, seeded from the query's resolved entities — the
+// vocabulary link's concepts and the understood publication's family
+// node — spreading over the domain's own law edges (defines, successor,
+// part_of, variant_of, amends, cites). Documents ranked by stationary
+// mass merge their query-relevant candidates like the graph lane does:
+// multi-hop neighborhoods (a term defined by R 87, whose family cites
+// R 61) surface without any hand-written traversal.
+//
+// The neighborhood is bounded (two hops, capped frontier) and the
+// iteration is deterministic power iteration over the undirected
+// adjacency — same query, same ranks, always.
+import { THRESHOLDS } from "../config.ts";
+import { lexicalWithin } from "../lexical.ts";
+import { refCodec } from "../codecs.ts";
+import { portStore } from "../env.ts";
+import type { StoreQuery } from "../ports/store.ts";
+import type { Stage } from "./types.ts";
+
+const EDGE_KINDS = "('defines','successor','part_of','variant_of','amends','cites')";
+const PPR_DAMPING = 0.85;
+const PPR_ITERATIONS = 12;
+const PPR_FRONTIER_CAP = 24;
+
+/** Deterministic Personalized-PageRank: uniform teleport over the
+ *  seeds, propagation over the UNDIRECTED adjacency (typed direction
+ *  matters for semantics, not for spread — a doc defines a concept as
+ *  much as the concept is defined by the doc). Pure: the unit tests
+ *  pin the convergence and the seed preference. */
+export function pageRank(
+  edges: [string, string][],
+  seeds: string[],
+  opts: { damping?: number; iterations?: number } = {},
+): Map<string, number> {
+  const damping = opts.damping ?? PPR_DAMPING;
+  const iterations = opts.iterations ?? PPR_ITERATIONS;
+  const adj = new Map<string, string[]>();
+  for (const [a, b] of edges) {
+    if (!adj.has(a)) adj.set(a, []);
+    if (!adj.has(b)) adj.set(b, []);
+    adj.get(a)!.push(b);
+    adj.get(b)!.push(a);
+  }
+  const live = seeds.filter((s) => adj.has(s));
+  if (!live.length) return new Map();
+  const base = 1 / live.length;
+  let rank = new Map<string, number>(live.map((s) => [s, base]));
+  for (let it = 0; it < iterations; it++) {
+    const next = new Map<string, number>();
+    for (const s of live) next.set(s, (1 - damping) * base);
+    for (const [node, r] of rank) {
+      const nbrs = adj.get(node);
+      if (!nbrs?.length) {
+        // a dangling node returns its mass to the seeds
+        for (const s of live) next.set(s, (next.get(s) ?? 0) + damping * r * base);
+        continue;
+      }
+      const share = (damping * r) / nbrs.length;
+      for (const n of nbrs) next.set(n, (next.get(n) ?? 0) + share);
+    }
+    rank = next;
+  }
+  return rank;
+}
+
+/** Seed node ids for a query: the glossary's concepts (label match,
+ *  the concept-graph lane's resolution) and the understood
+ *  publication's family node. */
+async function seedNodes(store: StoreQuery, glossary: { term: string }[], docidentifier: string | null): Promise<string[]> {
+  const jobs: Promise<string[]>[] = [];
+  for (const gl of glossary.slice(0, 3)) {
+    if (gl.term.length < 3) continue;
+    jobs.push(
+      store.prepare(
+        "SELECT id FROM graph_nodes WHERE kind = 'concept' AND (label = ?1 OR label LIKE ?2) LIMIT 6",
+      )
+        .bind(gl.term, `%${gl.term}%`)
+        .all()
+        .then((r: any) => (r.results ?? []).map((x: any) => String(x.id)))
+        .catch(() => [] as string[]),
+    );
+  }
+  const fam = docidentifier ? refCodec().familyOf(docidentifier) : null;
+  if (fam) {
+    jobs.push(
+      store.prepare("SELECT id FROM graph_nodes WHERE kind = 'family' AND id = ?1")
+        .bind(`family:${fam}`)
+        .first()
+        .then((r: any) => (r?.id ? [String(r.id)] : []))
+        .catch(() => [] as string[]),
+    );
+  }
+  const settled = await Promise.all(jobs);
+  return [...new Set(settled.flat())].slice(0, 4);
+}
+
+/** Two bounded hops of the seed neighborhood: the edge list and the
+ *  frontier's node kinds (doc nodes are what retrieval can use). */
+async function neighborhood(store: StoreQuery, seeds: string[]): Promise<{ edges: [string, string][]; kinds: Map<string, string> }> {
+  const seenEdges = new Set<string>();
+  const edges: [string, string][] = [];
+  let frontier = seeds.slice(0, PPR_FRONTIER_CAP);
+  const visited = new Set(seeds);
+  for (let hop = 0; hop < 2 && frontier.length; hop++) {
+    const marks = frontier.map(() => "?").join(",");
+    const rows = (await store.prepare(
+      `SELECT src, dst FROM graph_edges WHERE kind IN ${EDGE_KINDS} AND (src IN (${marks}) OR dst IN (${marks})) LIMIT 400`,
+    )
+      .bind(...frontier)
+      .all()
+      .catch(() => ({ results: [] }))) as any;
+    const next: string[] = [];
+    for (const r of rows.results ?? []) {
+      const key = `${r.src}>${r.dst}`;
+      if (seenEdges.has(key)) continue;
+      seenEdges.add(key);
+      edges.push([String(r.src), String(r.dst)]);
+      for (const n of [String(r.src), String(r.dst)]) {
+        if (!visited.has(n)) {
+          visited.add(n);
+          if (next.length < PPR_FRONTIER_CAP) next.push(n);
+        }
+      }
+    }
+    frontier = next;
+  }
+  const nodeIds = [...visited].slice(0, 60);
+  const kinds = new Map<string, string>();
+  for (let i = 0; i < nodeIds.length; i += 30) {
+    const chunk = nodeIds.slice(i, i + 30);
+    const marks = chunk.map(() => "?").join(",");
+    const rows = (await store.prepare(`SELECT id, kind FROM graph_nodes WHERE id IN (${marks})`)
+      .bind(...chunk)
+      .all()
+      .catch(() => ({ results: [] }))) as any;
+    for (const r of rows.results ?? []) kinds.set(String(r.id), String(r.kind));
+  }
+  return { edges, kinds };
+}
+
+/** The ranked document numbers for the query's seeds: PPR mass over
+ *  the neighborhood, doc nodes only, rendered through the codec. */
+export async function pprDocuments(
+  store: StoreQuery,
+  glossary: { term: string }[],
+  docidentifier: string | null,
+): Promise<string[]> {
+  const seeds = await seedNodes(store, glossary, docidentifier);
+  if (!seeds.length) return [];
+  const { edges, kinds } = await neighborhood(store, seeds);
+  if (!edges.length) return [];
+  const rank = pageRank(edges, seeds);
+  const docs = [...rank.entries()]
+    .filter(([id, mass]) => kinds.get(id) === "doc" && mass > 0)
+    .sort((a, b) => b[1] - a[1])
+    .map(([id]) => refCodec().graphDocNumber(id))
+    .filter((n): n is string => !!n);
+  return [...new Set(docs)].slice(0, 6);
+}
+
+export const graphPpr: Stage = {
+  name: "graph-ppr",
+  failure: "additive",
+  // no raw-binding guard: a deployment without the store degrades
+  // through the prefetch's own catch (the lane stays silent)
+  when: (c) => (c.glossary.length > 0 || !!c.u?.docidentifier) && c.vector.length > 0,
+  prefetch: (c) => {
+    c.lane["graph-ppr"] = pprDocuments(portStore(c.env), c.glossary, c.u?.docidentifier ?? null).catch(() => [] as string[]);
+  },
+  run: async (c) => {
+    const docs = (await c.lane["graph-ppr"]!) as string[];
+    if (!docs?.length) return;
+    // same identity resolution and narrowing law as the graph lane
+    // (rag#137): BM25-within-set candidates at the half discount, five
+    // at most, cross-encoder preference decides
+    const g = await lexicalWithin(c.env, c.rq || c.query, docs, 6);
+    const seenIds = new Set(c.matches.map((m: any) => m.id));
+    let merged = 0;
+    for (const m of (g ?? []).slice(0, 5)) {
+      if (!seenIds.has(m.id)) {
+        c.matches.push({ id: m.id, score: m.score * THRESHOLDS.pprDiscount, metadata: m.metadata });
+        seenIds.add(m.id);
+        merged++;
+      }
+    }
+    if (merged) console.log("graph ppr:", docs.join(","), "— merged", merged);
+  },
+};