@konneal/engine 0.1.0

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

@@ -0,0 +1,88 @@
+// Edition steering, family-relative: when the query does not pin an
+// edition, chunks from an OLDER edition of a publication are demoted
+// whenever a NEWER edition of the SAME publication is in the pool.
+// Superseded editions match archaic phrasing strongly (their wording is
+// what the question echoes) and the per-doc diversity cap then fills
+// the publication's slots with them — observed: R 76-1:1992/1988
+// passages displacing the current R 76-1:2006 on complex unfiltered
+// queries. Cross-publication recency is deliberately NOT touched: a
+// 1992 publication that is still current must not be demoted because
+// some unrelated 2024 document exists. Scaled to the live rerank spread
+// — the scores cluster within ~0.001.
+import { THRESHOLDS } from "../config.ts";
+import type { Stage } from "./types.ts";
+
+export const editionSteer: Stage = {
+  name: "edition-steer",
+  when: (c) => !c.filters?.edition && c.hits.length > 1,
+  run: (c) => {
+    const year = (s?: string) => (/^(19|20)\d{2}$/.test(s ?? "") ? Number(s) : null);
+    // the FAMILY key (doctype + base number): "R 60", "R 60 (Annexes)"
+    // and "R 60-1/-2/-3" are one publication whose current shape is the
+    // 2021 PARTS — the 2017 monolith lives under other identifiers, so
+    // docidentifier-level steering never sees it against 2021
+    const family = (m: any) => `${m.doctype}|${String(m.doc_number ?? "").split("-")[0]}|${m.language}`;
+    const scored = c.hits.map((h) => h.rerank_score ?? h.score);
+    const spread = Math.max(...scored) - Math.min(...scored);
+    if (spread > 0) {
+      const newest = new Map<string, number>();
+      const famNewest = new Map<string, number>();
+      let anyYear = 0;
+      for (const h of c.hits) {
+        const y = year(h.metadata.edition);
+        if (!y || y < 1990) continue;
+        const k = `${h.metadata.docidentifier}|${h.metadata.language}`;
+        newest.set(k, Math.max(newest.get(k) ?? 0, y));
+        const fk = family(h.metadata);
+        famNewest.set(fk, Math.max(famNewest.get(fk) ?? 0, y));
+        anyYear = Math.max(anyYear, y);
+      }
+      // cross-publication tie-break: a current-edition publication ranks
+      // over stale ones (load-bearing — par-prepackaged: R 87:2004 must
+      // outrank 1990s texts); composed WITH the family-relative demotion
+      // below, which dominates for same-publication duplicates
+      if (anyYear > 1990) {
+        for (const h of c.hits) {
+          const y = year(h.metadata.edition);
+          if (y && y >= 1990) {
+            h.rerank_score = (h.rerank_score ?? h.score) + spread * THRESHOLDS.crossPubRecencySpread * ((y - 1990) / (anyYear - 1990));
+          }
+        }
+      }
+      let demoted = 0;
+      for (const h of c.hits) {
+        const y = year(h.metadata.edition);
+        // (a) same-identifier: the successor of THIS document is in the
+        // pool — FULL strength, because ordering is load-bearing here:
+        // the diversity cap keeps ONE overview per publication and
+        // near-tied editions otherwise hand the slot to the older one
+        // (observed: R 60's 2017 parts displacing the current 2021
+        // parts). A lone older edition (successor not in the pool)
+        // passes undemoted — superseded content stays citable when it
+        // alone carries the clause
+        const max = newest.get(`${h.metadata.docidentifier}|${h.metadata.language}`);
+        if (y && max && y < max) {
+          h.rerank_score = (h.rerank_score ?? h.score) - spread * THRESHOLDS.familyDemoteSpread;
+          demoted++;
+          continue;
+        }
+        // (b) family-wide, status-gated: a superseded/unknown-status
+        // edition demotes against the FAMILY's newest even under a
+        // different identifier — the corpus's own status carries the
+        // supersession the registry link missed. in-force documents are
+        // exempt: a newer part-2 must never demote a current part-1
+        const fmax = famNewest.get(family(h.metadata));
+        if (y && fmax && y < fmax && (h.metadata.status === "superseded" || h.metadata.status === "unknown")) {
+          h.rerank_score = (h.rerank_score ?? h.score) - spread * THRESHOLDS.familyDemoteSpread;
+          demoted++;
+        }
+      }
+      if (demoted) {
+        console.log("edition steering: demoted", demoted, "superseded-edition chunks (family-relative)");
+        c.hits.sort((a, b) => (b.rerank_score ?? -Infinity) - (a.rerank_score ?? -Infinity));
+      } else if (anyYear > 1990) {
+        c.hits.sort((a, b) => (b.rerank_score ?? -Infinity) - (a.rerank_score ?? -Infinity));
+      }
+    }
+  },
+};

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

@@ -0,0 +1,22 @@
+// Family boost + pool sort. Family chunks carry the multi-part structure
+// (which parts/annexes exist) — they must reach the model for 'what is
+// R 60' / 'how many parts' queries. Vector similarity alone won't rank
+// them because they're short structural summaries competing with
+// content-heavy clause text. Boost them decisively for doc-scoped
+// queries, then sort the pool by score (the cross-encoder re-sorts
+// after; this order is the rerank-failure fallback).
+import type { Stage } from "./types.ts";
+
+export const familyBoost: Stage = {
+  name: "family-boost",
+  run: (c) => {
+    if (c.filter?.doc_number) {
+      for (const h of c.hits) {
+        if (h.metadata.clause_anchor === "family") {
+          h.score = Math.max(h.score, ...c.hits.map((x) => x.score)) + 1;
+        }
+      }
+    }
+    c.hits.sort((a, b) => b.score - a.score);
+  },
+};

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

@@ -0,0 +1,22 @@
+// Federated ISO/IEC tier (additive by contract — the federate callback
+// catches its own transport failures). Members get passages from the
+// internal index (service binding) merged into the same candidate pool;
+// the shared reranker + fusion below sort it out. Slight discount: the
+// public corpus answers by default.
+import { THRESHOLDS } from "../config.ts";
+import type { Stage } from "./types.ts";
+
+export const federate: Stage = {
+  name: "federate",
+  when: (c) => !!c.opts.federate,
+  run: async (c) => {
+    const fed = await c.opts.federate!(c.rq).catch(() => []);
+    const seen = new Set(c.hits.map((h) => h.id));
+    for (const h of fed) {
+      if (!seen.has(h.id)) {
+        c.hits.push({ ...h, score: h.score * THRESHOLDS.federateDiscount });
+        seen.add(h.id);
+      }
+    }
+  },
+};

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

@@ -0,0 +1,65 @@
+// Vocabulary link — the L2 nomenclature bridge (additive). Everyday
+// words don't match defined terms — the one gap every comparison lane
+// fails. Dense candidates + cross-encoder rerank, and the ANSWER model
+// adjudicates among the top-3 (the entity-linking pattern: retrieval
+// proposes, generation disambiguates — naive top-1 dense binding picks
+// the wrong term). Computed BEFORE the pool closes, because the
+// candidates' defining publications also ROUTE the pool: a question
+// whose concept link lands in a family the primary lanes missed
+// (colloquial "bag of flour sold by weight" → the prepackage domain)
+// gets that family's passages merged like the graph lane does — the
+// concept link is a family router, not just a note.
+import { rerank } from "../ai.ts";
+import { portModelRunner, portIndex, hasLane } from "../env.ts";
+import { MODELS, THRESHOLDS } from "../config.ts";
+import type { Stage } from "./types.ts";
+
+interface GlossaryCand {
+  term: string;
+  definition: string;
+  docidentifier: string;
+  doc_number: string;
+  score: number;
+}
+
+export const glossary: Stage = {
+  name: "glossary",
+  failure: "additive",
+  when: (c) => hasLane(c.env, "glossary") && c.vector.length > 0,
+  prefetch: (c) => {
+    c.lane.glossary = (async () => {
+      const g = await portIndex(c.env, "glossary").query({ vector: c.vector, topK: 5 });
+      const cands = g.filter((m) => m.score >= THRESHOLDS.glossaryCosineFloor);
+      if (!cands.length) return [] as GlossaryCand[];
+      const texts = cands.map((m: any) => String(m.metadata?.chunk_text ?? ""));
+      const rs = await rerank(portModelRunner(c.env), MODELS.rerank, c.query, texts);
+      return cands
+        .map((m: any, i: number) => ({
+          term: String(m.metadata?.clause_title ?? "").trim(),
+          definition: String(m.metadata?.chunk_text ?? "").split(" — ").slice(1).join(" — ").slice(0, 300),
+          docidentifier: String(m.metadata?.docidentifier ?? ""),
+          doc_number: String(m.metadata?.doc_number ?? ""),
+          score: rs ? rs[i] : m.score,
+        }))
+        .filter((x: any) => x.term && x.definition);
+    })();
+  },
+  run: async (c) => {
+    const ranked = (await c.lane.glossary!) as GlossaryCand[];
+    // one entry per DISTINCT CONCEPT, and only candidates the
+    // cross-encoder actually deems relevant (score > 0). Distinctness
+    // is spelling-normalized: "Weigh labeler"/"Weigh labeller" are
+    // one concept in two spellings — without normalization the note's
+    // slots burn on variants while the domain-bridging concept one
+    // rank down ("actual quantity" — the PREPACKAGE domain) never
+    // reaches the adjudicator.
+    const norm = (t: string) => t.toLowerCase().replace(/[^a-z0-9 ]/g, "").replace(/labeler\b/g, "labeller").replace(/\s+/g, " ").trim();
+    const byTerm = new Map<string, GlossaryCand>();
+    for (const r of ranked) if (r.score > 0) {
+      const k = norm(r.term);
+      if (!byTerm.has(k)) byTerm.set(k, r);
+    }
+    c.glossary = [...byTerm.values()].sort((a, b) => b.score - a.score).slice(0, 3);
+    if (c.glossary.length) console.log("glossary link:", c.glossary.map((g2) => g2.term).join(", "));
+  },
+};

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

@@ -0,0 +1,31 @@
+// Graph lane (additive): the caller-resolved document numbers (relaton
+// family/successor resolution done in index.ts) merge their top
+// candidates at a discount.
+import { THRESHOLDS } from "../config.ts";
+import type { Stage } from "./types.ts";
+
+export const graphLane: Stage = {
+  name: "graph-lane",
+  failure: "additive",
+  when: (c) => !!c.opts.graphDocNumbers?.length && c.vector.length > 0,
+  prefetch: (c) => {
+    c.lane["graph-lane"] = c.env.VECTORIZE.query(c.vector, {
+      topK: 15,
+      returnMetadata: "all",
+      filter: { doc_number: { $in: c.opts.graphDocNumbers } },
+    });
+  },
+  run: async (c) => {
+    const g = (await c.lane["graph-lane"]!) as any;
+    const seenIds = new Set(c.matches.map((m: any) => m.id));
+    let merged = 0;
+    for (const m of (g.matches ?? []).slice(0, 10)) {
+      if (!seenIds.has(m.id)) {
+        c.matches.push({ id: m.id, score: m.score * THRESHOLDS.graphLaneDiscount, metadata: m.metadata });
+        seenIds.add(m.id);
+        merged++;
+      }
+    }
+    console.log("graph lane:", g.matches?.length ?? 0, "hits,", merged, "merged");
+  },
+};

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

@@ -0,0 +1,29 @@
+// HyDE — Hypothetical Document Embeddings (additive): embed the
+// hypothetical answer and search with it — its vocabulary matches the
+// corpus better than the question's. Only for non-filtered queries (a
+// filter would nullify the benefit).
+// Ref: arXiv 2212.10496; arXiv 2507.16754 (adaptive HyDE)
+import { embed } from "../ai.ts";
+import { portModelRunner } from "../env.ts";
+import { MODELS, THRESHOLDS } from "../config.ts";
+import type { Stage } from "./types.ts";
+
+export const hyde: Stage = {
+  name: "hyde",
+  failure: "additive",
+  when: (c) => !!c.u?.hypothetical_answer && !c.filter,
+  prefetch: (c) => {
+    c.lane.hyde = embed(portModelRunner(c.env), MODELS.embed, c.u!.hypothetical_answer!)
+      .then((hv) => c.env.VECTORIZE.query(hv, { topK: 20, returnMetadata: "all" }));
+  },
+  run: async (c) => {
+    const hres = (await c.lane.hyde!) as any;
+    const seenIds = new Set(c.matches.map((m: any) => m.id));
+    for (const m of (hres.matches ?? []).slice(0, 10)) {
+      if (!seenIds.has(m.id)) {
+        c.matches.push({ id: m.id, score: m.score * THRESHOLDS.hydeDiscount, metadata: m.metadata });
+        seenIds.add(m.id);
+      }
+    }
+  },
+};

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

@@ -0,0 +1,69 @@
+// The stage registry (TODO.impl/02): the pipeline is this ordered list.
+// Adding a mechanism = writing a stage module and appending one entry —
+// no edits to existing stages, the runner, or retrieve() (OCP). Ordering
+// invariants and per-stage contracts: docs/spec-pipeline.md.
+//
+// Phase structure:
+//   candidate lanes (dense → glossary-graph lanes → fusion lanes)
+//   → pool open → pool-level merges (lexical/federate/seal)
+//   → refinement (demotion, rerank, steering, propagation, diversity)
+//   → window assembly (typed pin, section descent, dedup, floor)
+import type { Stage } from "./types.ts";
+export { runStages } from "./types.ts";
+export type { PipelineContext, RetrieveOptions, GlossaryEntry, Stage } from "./types.ts";
+import { dense } from "./dense.ts";
+import { hyde } from "./hyde.ts";
+import { glossary } from "./glossary.ts";
+import { conceptGraph } from "./conceptGraph.ts";
+import { graphLane } from "./graphLane.ts";
+import { multiQuery } from "./multiQuery.ts";
+import { subQuery } from "./subQuery.ts";
+import { poolOpen } from "./poolOpen.ts";
+import { lexicalUnion } from "./lexicalUnion.ts";
+import { federate } from "./federate.ts";
+import { seal } from "./seal.ts";
+import { corpusScope } from "./corpusScope.ts";
+import { editionCover } from "./editionCover.ts";
+import { stdRefNudge } from "./stdRefNudge.ts";
+import { overviewDemote } from "./overviewDemote.ts";
+import { familyBoost } from "./familyBoost.ts";
+import { rerankStage, lexicalRrf } from "./rerank.ts";
+import { termNudge } from "./termNudge.ts";
+import { conceptSteer } from "./conceptSteer.ts";
+import { editionSteer } from "./editionSteer.ts";
+import { propagate } from "./propagate.ts";
+import { diversity } from "./diversity.ts";
+import { typedPin } from "./typedPin.ts";
+import { sectionDescent } from "./sectionDescent.ts";
+import { dedup } from "./dedup.ts";
+import { windowFloor } from "./windowFloor.ts";
+
+export const STAGES: Stage[] = [
+  dense,
+  hyde,
+  glossary,
+  conceptGraph,
+  graphLane,
+  multiQuery,
+  subQuery,
+  poolOpen,
+  lexicalUnion,
+  federate,
+  seal,
+  overviewDemote,
+  familyBoost,
+  rerankStage,
+  lexicalRrf,
+  corpusScope,
+  editionCover,
+  stdRefNudge,
+  termNudge,
+  conceptSteer,
+  editionSteer,
+  propagate,
+  diversity,
+  typedPin,
+  sectionDescent,
+  dedup,
+  windowFloor,
+];

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

@@ -0,0 +1,21 @@
+// Lexical union: union full-corpus lexical hits that dense missed
+// (G-ETSI-1). Prefer dense metadata/text when both sources return the
+// same id.
+import type { Stage } from "./types.ts";
+
+export const lexicalUnion: Stage = {
+  name: "lexical-union",
+  when: (c) => c.lexicalHits.length > 0,
+  run: (c) => {
+    const seen = new Set(c.hits.map((h) => h.id));
+    let added = 0;
+    for (const h of c.lexicalHits) {
+      if (!seen.has(h.id)) {
+        c.hits.push(h);
+        seen.add(h.id);
+        added++;
+      }
+    }
+    if (added) console.log("lexical union:", added, "new candidates");
+  },
+};

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

@@ -0,0 +1,57 @@
+// Multi-Query RAG-Fusion: generate 2-3 alternative phrasings, retrieve
+// for each, fuse via RRF. Different phrasings surface documents the
+// original query misses.
+// Ref: RAG-Fusion paper (Semantic Scholar b4d1da74); dev.to 2026 blueprint
+import { embed } from "../ai.ts";
+import { LIMITS, MODELS } from "../config.ts";
+import { toHits, type Stage } from "./types.ts";
+import type { Hit } from "../../../shared/chunk.ts";
+
+const RRF_K = 60;
+
+export const multiQuery: Stage = {
+  name: "multi-query",
+  when: (c) => !!c.u?.query_variants?.length,
+  prefetch: (c) => {
+    const { env, filter, u } = c;
+    // the variants are independent queries — embed + search them in
+    // PARALLEL (and ahead of the dense lane, via prefetch); a serial
+    // loop paid 2 x (embed + query) round trips on the hot path for
+    // zero quality difference (same candidate set)
+    c.lane["multi-query"] = Promise.all(
+      u!.query_variants!.slice(0, 3).map(async (variant) => {
+        try {
+          const vv = await embed(env.AI, MODELS.embed, variant);
+          const vres = await env.VECTORIZE.query(vv, { topK: 20, returnMetadata: "all", ...(filter ? { filter } : {}) });
+          return toHits(vres.matches ?? []);
+        } catch {
+          return [] as never[]; // variant retrieval failure — primary results stand
+        }
+      }),
+    );
+  },
+  run: async (c) => {
+    const variantResults = ((await c.lane["multi-query"]!) as Hit[][]).filter((r) => r.length > 0);
+    // RRF fuse: primary ranking + each variant ranking
+    if (variantResults.length > 0) {
+      const allRankings = [toHits(c.matches), ...variantResults];
+      // simple RRF across all rankings
+      const scores = new Map<string, number>();
+      const byId = new Map<string, (typeof allRankings)[number][number]>();
+      allRankings.forEach((ranking) => {
+        ranking.forEach((h, i) => {
+          scores.set(h.id, (scores.get(h.id) ?? 0) + 1 / (RRF_K + i + 1));
+          byId.set(h.id, h);
+        });
+      });
+      const fused = [...scores.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, LIMITS.retrieveK)
+        .map(([id]) => byId.get(id)!)
+        .filter(Boolean);
+      if (fused.length > 0) {
+        c.matches = fused.map((h) => ({ id: h.id, score: h.score, metadata: h.metadata }));
+      }
+    }
+  },
+};

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

@@ -0,0 +1,14 @@
+// Overview demotion: overview chunks repeat the title/doctype boilerplate
+// and embed strongly for name-like queries, crowding clause chunks out of
+// the rerank window.
+import { THRESHOLDS } from "../config.ts";
+import type { Stage } from "./types.ts";
+
+export const overviewDemote: Stage = {
+  name: "overview-demote",
+  run: (c) => {
+    for (const h of c.hits) {
+      if (h.metadata.clause_anchor === "overview") h.score *= THRESHOLDS.overviewDemotion;
+    }
+  },
+};

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

@@ -0,0 +1,10 @@
+// Pool open: the candidate pool closes its lane-merge phase and becomes
+// the ranked Hit list every refinement stage operates on.
+import { toHits, type Stage } from "./types.ts";
+
+export const poolOpen: Stage = {
+  name: "pool-open",
+  run: (c) => {
+    c.hits = toHits(c.matches);
+  },
+};

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

@@ -0,0 +1,15 @@
+// Structural propagation (FABLE TreeExpansion, arXiv:2601.18116): the
+// corpus IS a tree — clause anchors chain parent→child, so a hit's
+// score blends with its ancestors' (topic continuity) and descendants'
+// (subtopic heat) — a section whose clauses are collectively hot rises,
+// and a hot section lifts its clauses. Pure post-retrieval re-scoring
+// over metadata the chunks already carry; no new index lane required.
+import { structuralPropagation } from "../structural.ts";
+import type { Stage } from "./types.ts";
+
+export const propagate: Stage = {
+  name: "structural-propagate",
+  run: (c) => {
+    c.hits = structuralPropagation(c.hits);
+  },
+};

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

@@ -0,0 +1,47 @@
+// Cross-encoder rerank (additive — vector order is the fallback, by
+// design) + the post-rerank family pin. The pre-rerank family boost does
+// not survive re-sorting — short structural summaries always lose to
+// content-heavy clauses under a cross-encoder. For doc-scoped queries
+// pin family chunks AFTER rerank: 'what is R 60' must lead with the
+// family summary, not an annex definition that happens to match the
+// words.
+//
+// lexical-rrf: RRF with the FULL-CORPUS lexical ranking (not a re-score
+// of the dense shortlist). ETSI §II-B7: dense+sparse fusion lifts
+// precision and MRR on standards jargon without changing recall. Runs
+// after rerank even when rerank failed (the monolith's try/catch left
+// the fuse outside it — preserved by the runner's additive semantics).
+import { rerank } from "../ai.ts";
+import { portModelRunner } from "../env.ts";
+import { LIMITS, MODELS } from "../config.ts";
+import { rrfFuse } from "../hybrid.ts";
+import type { Stage } from "./types.ts";
+
+export const rerankStage: Stage = {
+  name: "rerank",
+  failure: "additive",
+  when: (c) => c.hits.length > 1,
+  run: async (c) => {
+    const tRerank = Date.now();
+    const scores = await rerank(portModelRunner(c.env), MODELS.rerank, c.query, c.hits.map((h) => h.text));
+    console.log("stage: rerank", Date.now() - tRerank, "ms over", c.hits.length, "candidates");
+    if (scores) {
+      c.hits.forEach((h, i) => (h.rerank_score = scores[i]));
+      c.hits.sort((a, b) => (b.rerank_score ?? -Infinity) - (a.rerank_score ?? -Infinity));
+      if (c.filter?.doc_number) {
+        const families = c.hits.filter((h) => h.metadata.clause_anchor === "family");
+        if (families.length) {
+          c.hits = [...families, ...c.hits.filter((h) => h.metadata.clause_anchor !== "family")];
+        }
+      }
+    }
+  },
+};
+
+export const lexicalRrf: Stage = {
+  name: "lexical-rrf",
+  when: (c) => c.hits.length > 1 && c.lexicalHits.length > 0,
+  run: (c) => {
+    c.hits = rrfFuse(c.hits, c.lexicalHits, LIMITS.retrieveK);
+  },
+};

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

@@ -0,0 +1,16 @@
+// The declared context's hard seal (TODO.ai-platform/02) — pool-level,
+// after every lane has merged, before rerank + the top-N cut. Nothing
+// outside the declared family competes for the window; everything
+// inside it does.
+import type { Stage } from "./types.ts";
+
+export const seal: Stage = {
+  name: "seal",
+  when: (c) => !!c.opts.sealScope,
+  run: (c) => {
+    const before = c.hits.length;
+    const scope = c.opts.sealScope!;
+        c.hits = c.hits.filter((h) => h.metadata.doc_number === scope.doc_number && (!scope.edition || h.metadata.edition === scope.edition));
+    console.log("context seal:", before, "→", c.hits.length, "candidates within", `doc#${scope.doc_number}${scope.edition ? "@" + scope.edition : ""}`);
+  },
+};

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

@@ -0,0 +1,61 @@
+// Section-summary units → leaf evidence (FABLE multi-granularity): a
+// depth-1 summary vector that ranked is a navigation node, not quotable
+// evidence: fetch its top child clauses (metadata-filtered, same query
+// vector) so the model gets source text to cite, then retire the
+// synthetic summary — the answer contract grounds claims in source
+// clauses, never in our own summaries. The summary stays only when no
+// child answered (it is then the doc's sole representative).
+import { THRESHOLDS } from "../config.ts";
+import type { ChunkMeta } from "../../../shared/chunk";
+import type { Hit } from "../../../shared/chunk";
+import type { Stage } from "./types.ts";
+
+export const sectionDescent: Stage = {
+  name: "section-descent",
+  failure: "additive",
+  when: (c) =>
+    !!c.finalHits.find((h) => h.metadata.section_summary === "1" && h.metadata.child_anchors && h.score > 0) &&
+    c.vector.length > 0,
+  run: async (c) => {
+    const sectionHit = c.finalHits.find(
+      (h) => h.metadata.section_summary === "1" && h.metadata.child_anchors && h.score > 0,
+    )!;
+    const kids = sectionHit
+      .metadata.child_anchors!.split(",")
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .slice(0, 25);
+    if (kids.length) {
+      const cv = await c.env.VECTORIZE.query(c.vector, {
+        topK: 3,
+        returnMetadata: "all",
+        filter: {
+          $and: [
+            { doc_id: { $eq: sectionHit.metadata.doc_id } },
+            { clause_anchor: { $in: kids } },
+          ],
+        },
+      });
+      const childHits = (cv.matches ?? [])
+        .filter((m: any) => !m.metadata?.section_summary)
+        .map((m: any) => ({
+          id: m.id,
+          score: m.score * THRESHOLDS.sectionDescentDiscount,
+          metadata: m.metadata as ChunkMeta,
+          text: (m.metadata?.chunk_text as string) ?? "",
+        }))
+        .filter((x: Hit) => !c.finalHits.some((h) => h.id === x.id))
+        .slice(0, 2);
+      if (childHits.length) {
+        c.finalHits = [...c.finalHits.filter((h) => h !== sectionHit), ...childHits];
+        console.log(
+          "section descent:",
+          sectionHit.metadata.docidentifier,
+          "§" + sectionHit.metadata.clause_anchor,
+          "→",
+          childHits.map((x: Hit) => "§" + x.metadata.clause_anchor).join(", "),
+        );
+      }
+    }
+  },
+};

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

@@ -0,0 +1,35 @@
+// Standard-reference nudge (L5): when the question asks which ISO/IEC
+// standard a document invokes, the answer IS the clause carrying the
+// citation — but generic family prose (definitions, certification
+// passages) otherwise fills the window and the citing clause never
+// reaches the answer (measured: l5a-iso-humidity flips ~1/6 runs).
+// Lexical ranking signal, same design as term-nudge: query mentions the
+// standard family, chunks whose text carries an ISO/IEC identifier get
+// a spread-scaled boost. Typed table units (serialized payloads) compete
+// on the same signal.
+import { THRESHOLDS } from "../config.ts";
+import type { Stage } from "./types.ts";
+
+const ASKS_ABOUT_STD = /\b(iso|iec|astm|en\s?\d{2,5})\b/i;
+const CITES_STD = /\b(?:ISO|IEC|ASTM|EN)[ /]?\d{3,6}(?:[-–]\d+)?\b/;
+
+export const stdRefNudge: Stage = {
+  name: "std-ref-nudge",
+  when: (c) => ASKS_ABOUT_STD.test(c.query) && c.hits.length > 1,
+  run: (c) => {
+    const scored = c.hits.map((h) => h.rerank_score ?? h.score);
+    const spread = Math.max(...scored) - Math.min(...scored);
+    if (spread <= 0) return;
+    let nudged = 0;
+    for (const h of c.hits) {
+      if (CITES_STD.test(h.text) || CITES_STD.test(h.metadata.clause_title ?? "")) {
+        h.rerank_score = (h.rerank_score ?? h.score) + spread * THRESHOLDS.stdRefNudgeSpread;
+        nudged++;
+      }
+    }
+    if (nudged) {
+      c.hits.sort((a, b) => (b.rerank_score ?? -Infinity) - (a.rerank_score ?? -Infinity));
+      console.log("std-ref nudge:", nudged, "chunks carrying standard citations");
+    }
+  },
+};

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

@@ -0,0 +1,42 @@
+// Multi-hop decomposition for complex questions (additive per sub-query):
+// retrieve for each sub-question and merge the top results.
+// Ref: Agent-Orchestrated Adaptive RAG (arXiv 2606.05658)
+import { embed } from "../ai.ts";
+import { MODELS, THRESHOLDS } from "../config.ts";
+import { toHits, type Stage } from "./types.ts";
+import type { Hit } from "../../../shared/chunk.ts";
+
+export const subQuery: Stage = {
+  name: "sub-query",
+  when: (c) => c.u?.complexity === "complex" && !!c.u?.sub_queries?.length,
+  prefetch: (c) => {
+    const { env, u } = c;
+    // sub-questions are independent — parallel rounds, ahead of the
+    // dense lane (prefetch), same as variants
+    c.lane["sub-query"] = Promise.all(
+      u!.sub_queries!.slice(0, 4).map(async (sub) => {
+        try {
+          const sv = await embed(env.AI, MODELS.embed, sub);
+          const sres = await env.VECTORIZE.query(sv, { topK: 15, returnMetadata: "all" });
+          return toHits(sres.matches ?? []);
+        } catch {
+          return [] as never[]; // sub-query failure — primary results stand
+        }
+      }),
+    );
+  },
+  run: async (c) => {
+    const subResults = ((await c.lane["sub-query"]!) as Hit[][]).filter((r) => r.length > 0);
+    // merge sub-results into the candidate pool (union, no RRF — these
+    // are complementary perspectives, not alternatives)
+    const seenIds = new Set(c.matches.map((m: any) => m.id));
+    for (const sr of subResults) {
+      for (const h of sr.slice(0, 8)) {
+        if (!seenIds.has(h.id)) {
+          c.matches.push({ id: h.id, score: h.score * THRESHOLDS.subQueryDiscount, metadata: h.metadata });
+          seenIds.add(h.id);
+        }
+      }
+    }
+  },
+};