@konneal/engine 0.1.0

package/workers/worker_public/src/pipeline.ts

@@ -0,0 +1,377 @@
+import { embed } from "./ai";
+import { P } from "./profile.ts";
+import { LIMITS, MODELS, DATASETS, THRESHOLDS, processExpansion } from "./config";
+import systemPromptText from "../prompts/system.md";
+import conversationalPromptText from "../prompts/conversational.md";
+import listwisePromptText from "../prompts/listwise.md";
+import { tableContext } from "./tablecontext";
+
+// the pinned refusal sentence lives with the canonicalizer in ./refusal
+// (refusals are never cached: a refusal says "retrieval found nothing",
+// which is a property of the moment, not of the question); re-exported
+// here so the existing import surface keeps working
+export { refusalAnswer } from "./refusal";
+
+/** Fill {{TOKEN}} placeholders in a prompt data file. Unknown/empty tokens
+ *  resolve to "" so optional lines vanish cleanly. */
+function fill(template: string, vars: Record<string, string>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_m, k: string) => (k in vars ? vars[k] : ""));
+}
+import { QueryFilters, toVectorizeFilter } from "./selfquery";
+import { lexicalPrefilter } from "./lexical";
+import { positionOrder } from "./structural";
+import { STAGES, 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
+// import surface keeps working
+export type { ChunkMeta, Hit } from "../../shared/chunk";
+import type { ChunkMeta, Hit } from "../../shared/chunk";
+import { portModelRunner } from "./env.ts";
+
+export interface Retrieved {
+  hits: Hit[];
+  filters: QueryFilters;
+  /** vocabulary link (the L2 nomenclature bridge): top defined-term
+   *  candidates for the question's subject — the answer model adjudicates
+   *  among them (dense retrieval alone binds everyday words to the wrong
+   *  term: measured "keeps drifting" → creep 0.69 vs durability 0.54) */
+  glossary?: GlossaryEntry[];
+}
+
+// Short follow-ups are usually elliptical ("and the limits?") — fold the
+// previous question into the RETRIEVAL query (generation still sees the
+// original wording). Purely structural (word count): whether a question
+// is elliptical is a semantic judgment, and semantics belong to the
+// understanding model, whose standalone_query takes precedence anyway.
+export function retrievalQuery(query: string, prev?: string): string {
+  if (!prev || !prev.trim()) return query;
+  const words = query.trim().split(/\s+/).length;
+  if (words <= 8) return `${prev.trim()} — ${query.trim()}`;
+  return query;
+}
+
+// colloquial process questions ("how do I get a device certified to R 60")
+// share almost no vocabulary with the B-series prose that answers them —
+// THRESHOLDS.processExpansion is appended to the retrieval query so the
+// window contains the certification-system documents at all
+
+// ── the retrieval pipeline (TODO.impl/02) ────────────────────────────────
+// retrieve() is COMPOSITION ONLY: build the context (the parallel
+// embed/lexical prelude — Option C's latency structure is load-bearing),
+// run the stage registry, project the result. Every mechanism lives in
+// its own stage module under src/stages/; the registry order and the
+// per-stage contracts are specified in docs/spec-pipeline.md.
+export async function retrieve(
+  env: any,
+  query: string,
+  opts: RetrieveOptions = {},
+): Promise<Retrieved> {
+  const u = opts.understanding ?? null;
+  // Filters and process-intent come ONLY from query understanding — no
+  // regex floor, no union. When understanding is unavailable the query
+  // runs unfiltered and unexpanded (vanilla retrieval); meaning is never
+  // decided by string matching.
+  // The declared context's HARD scope outranks the understanding's routing
+  // opinion: a certificate chip that says R 60:2021 keeps its dense filter
+  // even when the question's vocabulary makes the classifier emit
+  // process_intent (certification wording is the chip's subject, not the
+  // question's). Without this, dense runs unfiltered, the certification
+  // corpus floods the pool, and the pool-level seal — which must stay hard —
+  // cuts it to zero (the ctx-entity refusal, diagnosed 2026-09-08).
+  const scope: QueryFilters | null =
+    u && !u.process_intent && u.doc_number
+      ? { doc_number: u.doc_number, ...(u.edition ? { edition: u.edition } : {}) }
+      : opts.sealScope
+        ? { doc_number: opts.sealScope.doc_number, ...(opts.sealScope.edition ? { edition: opts.sealScope.edition } : {}) }
+        : null;
+  const filters: QueryFilters | null = scope;
+  const filter = filters ? toVectorizeFilter(filters) : null;
+  const folded = retrievalQuery(query, opts.prev);
+  let rq = opts.queryOverride?.trim() || u?.standalone_query?.trim() || folded;
+  if (u?.process_intent) rq += processExpansion();
+  // Dense embed + full-corpus BM25 prefilter in parallel (G-ETSI-1 /
+  // arXiv:2604.09868 §II-B5). Lexical must scan the whole corpus — the
+  // old keywordRank only re-ordered dense hits and could not recover
+  // exact-jargon misses. Fail-open: empty lexical list leaves dense alone.
+  // Option C: when the query is unchanged (rq === folded) the optimistic
+  // vector is already resolved — never await a fresh embed for it.
+  const vectorP =
+    rq === folded && opts.optimisticVec
+      ? Promise.resolve(opts.optimisticVec)
+      : rq === folded && opts.warmEmbed
+        ? opts.warmEmbed.then((w) => w ?? embed(portModelRunner(env), MODELS.embed, rq))
+        : embed(portModelRunner(env), MODELS.embed, rq);
+  const lexicalP = lexicalPrefilter(env, rq).catch(() => [] as Hit[]);
+  const [vector, lexicalHits0] = await Promise.all([vectorP, lexicalP]);
+  // The declared context's seal binds the lexical lane at the SOURCE: the
+  // RRF fusion mixes the full-corpus lexical ranking straight into the
+  // final hits — past the pool-level seal — so under a seal the lexical
+  // lane is the FAMILY's lexical hits only.
+  const lexicalHits = opts.sealScope
+    ? lexicalHits0.filter((h) => h.metadata.doc_number === opts.sealScope!.doc_number && (!opts.sealScope!.edition || h.metadata.edition === opts.sealScope!.edition))
+    : lexicalHits0;
+  if (lexicalHits.length) console.log("lexical prefilter:", lexicalHits.length, "hits");
+
+  const ctx: PipelineContext = {
+    env, query, rq, folded, u, filters, filter, vector, lexicalHits,
+    matches: [], hits: [], finalHits: [], glossary: [], opts, lane: {},
+  };
+  await runStages(STAGES, ctx);
+  return {
+    hits: ctx.finalHits,
+    filters: ctx.filters ?? {},
+    ...(ctx.glossary?.length ? { glossary: ctx.glossary } : {}),
+  };
+}
+
+export interface HistoryTurn {
+  role: "user" | "assistant";
+  content: string;
+}
+
+// ── context budget ─────────────────────────────────────────────────────
+// The model window is finite; without a cap, a long conversation plus 8
+// clause chunks (tables can be huge) overflows and the request FAILS
+// outright. Everything is estimated (never exact) and stays well under
+// the smallest context our models accept. Priority when the budget is
+// tight: system + query always fit → newest history gets a bounded slice
+// → passages fill the rest, best-ranked first, worst-ranked dropped.
+
+function estTokens(s: string): number {
+  // CJK/Arabic/Indic scripts ≈ 1 token per char; Latin ≈ 1 per 4 chars
+  const wide = (s.match(/[؀-ۿݐ-ݿऀ-ॿ぀-ヿ㐀-䶿一-鿿가-힯]/g) || []).length;
+  return wide + Math.ceil((s.length - wide) / 4);
+}
+
+function clipToTokens(s: string, maxTok: number): string {
+  if (maxTok < 40 || estTokens(s) <= maxTok) return s;
+  const wide = (s.match(/[؀-ۿݐ-ݿऀ-ॿ぀-ヿ㐀-䶿一-鿿가-힯]/g) || []).length;
+  const latinChars = Math.max(0, maxTok - wide) * 4;
+  return s.slice(0, Math.min(s.length, wide + latinChars)).trimEnd() + " …";
+}
+
+export interface BuiltMessages {
+  messages: { role: string; content: string }[];
+  usedHits: Hit[]; // passages actually included (citations must match these)
+}
+
+/** System instruction for a conversational (non-knowledge) turn: the
+ *  service facts the model speaks from, composed from the DATASETS
+ *  catalog — the same SSOT /api/datasets serves. Routing is decided by
+ *  query UNDERSTANDING (understanding.ts), never by string matching. */
+export function identityNote(member: boolean): string {
+  const corpora = DATASETS().filter((d) => !d.session || member)
+    .map((d) => `- ${d.label}: ${d.description}`)
+    .join("\n");
+  const locked = DATASETS().filter((d) => d.session && !member);
+  const upsell = locked.length
+    ? `Signed-in members additionally search: ${locked.map((d) => `${d.label} (${d.description})`).join("; ")}.`
+    : "";
+  return fill(conversationalPromptText, { CORPORA: corpora, UPSELL: upsell })
+    .split("\n")
+    .filter((l) => l.trim())
+    .join("\n");
+}
+
+/** Split history into the turns that fit the budget slice (kept, newest)
+ *  and the older ones that must be compacted into a summary (overflow). */
+export function splitHistory(
+  history: HistoryTurn[],
+  budgetTokens: number,
+): { kept: HistoryTurn[]; overflow: HistoryTurn[] } {
+  const historyBudget = Math.floor(budgetTokens * THRESHOLDS.historyBudgetShare);
+  let used = 0;
+  let cut = 0; // everything before `cut` overflows
+  for (let i = history.length - 1; i >= 0; i--) {
+    const t = Math.min(estTokens(history[i].content), 600);
+    if (used + t > historyBudget) {
+      cut = i + 1;
+      break;
+    }
+    used += t;
+  }
+  return { kept: history.slice(cut), overflow: history.slice(0, cut) };
+}
+
+
+/** Final-tier LLM listwise rerank: jointly reorders the top passages for
+ *  hard queries (cascade stage after the cross-encoder). Null = keep the
+ *  incoming order (timeout/parse failure never blocks serving). */
+export async function listwiseRerank(
+  env: any,
+  model: string,
+  query: string,
+  hits: Hit[],
+): Promise<Hit[] | null> {
+  if (hits.length < 4) return null;
+  try {
+    const listing = hits
+      .map((h, i) => {
+        const label = `${h.metadata.docidentifier || h.metadata.doc_id}:${h.metadata.edition || ""} §${h.metadata.clause_anchor || ""}`;
+        return `[${i + 1}] ${label.replace(/(:|§)+$/g, "")} — ${h.text.replace(/\s+/g, " ").slice(0, 220)}`;
+      })
+      .join("\n");
+    // bounded to 2.5s: this call sits serially before generation starts —
+    // a slow reorder must never hold the first token hostage; the
+    // cross-encoder order is the fallback and is already good
+    const timeout = new Promise<null>((r) => setTimeout(() => r(null), 2500));
+    const call = (async () => {
+      const res: any = await env.AI.run(model, {
+        messages: [
+          { role: "system", content: listwisePromptText.trimEnd() },
+          { role: "user", content: `Question: ${query}\n\nPassages:\n${listing}` },
+        ],
+        max_tokens: 700,
+        reasoning_effort: "low",
+      });
+      const text = typeof res?.response === "string" ? res.response : res?.choices?.[0]?.message?.content;
+      const m = (text ?? "").match(/\[[\s\S]*?\]/);
+      if (!m) return null;
+      const order = JSON.parse(m[0]);
+      if (!Array.isArray(order) || order.length !== hits.length) return null;
+      const idx = order.map((n: unknown) => Number(n) - 1);
+      if (idx.some((n: number) => !Number.isInteger(n) || n < 0 || n >= hits.length) || new Set(idx).size !== hits.length) return null;
+      return idx.map((n: number) => hits[n]);
+    })();
+    return await Promise.race([call, timeout]);
+  } catch {
+    return null;
+  }
+}
+
+export function buildMessages(
+  query: string,
+  hits: Hit[],
+  lang?: string,
+  history: HistoryTurn[] = [],
+  retrievalNote?: string,
+  conversationSummary?: string,
+  budgetTokens: number = LIMITS.inputTokenBudget,
+): BuiltMessages {
+  // per-corpus guidance travels WITH the dataset (config.ts): every
+  // dataset whose corpus appears in the passages contributes its note —
+  // new corpora need a catalog entry, never pipeline changes
+  const corpusNotes = DATASETS().filter(
+    (d) => d.note && hits.some((h) => (h.metadata as any).corpus === d.id),
+  )
+    .map((d) => d.note!)
+    .join("\n");
+
+  // the prompt itself is data (prompts/system.md); one rule per line,
+  // joined with spaces exactly as the original array form
+  const system = fill(systemPromptText, {
+    ...P().prompts.vars,
+    HISTORY_CONTEXT: history.length
+      ? " Earlier turns of this conversation are provided for context — answer the LATEST question, treating the passages below as the source of truth for facts and citations."
+      : "",
+    CORPUS_NOTES: corpusNotes,
+    LANG_CLAUSE: lang ? ` (explicitly requested: ${lang})` : "",
+  })
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .join(" ");
+
+  // history: newest-first into a bounded slice (oldest dropped first);
+  // each turn is clipped so accounting and content agree
+  const historyBudget = Math.floor(budgetTokens * THRESHOLDS.historyBudgetShare);
+  const keptHistory: { role: "user" | "assistant"; content: string }[] = [];
+  let historyUsed = 0;
+  for (let i = history.length - 1; i >= 0; i--) {
+    const content = clipToTokens(history[i].content, 600);
+    const t = estTokens(content);
+    if (historyUsed + t > historyBudget) break;
+    keptHistory.unshift({ role: history[i].role, content });
+    historyUsed += t;
+  }
+
+  // passages: best-ranked first into whatever remains
+  const summaryBlock = conversationSummary
+    ? `Earlier in this conversation (summarized for continuity):\n${conversationSummary}`
+    : "";
+  let remain =
+    budgetTokens - estTokens(system) - estTokens(retrievalNote ?? "") - estTokens(summaryBlock) - estTokens(`Question: ${query}\n\nContext passages:\n`) - historyUsed - 120; // slack for estimator error + output framing
+  const passageParts: string[] = [];
+  const usedHits: Hit[] = [];
+  // Passage label as the MODEL should cite it (it copies these into
+  // answers): drop OIML language markers, append the edition only when
+  // the identifier doesn't already carry it ("B 18:2025 (E)" + "2025" →
+  // no ":2025"; "PD-06 Edition 4" + "4" → no ":4"), and never show a
+  // producer UUID as a clause anchor — cite the clause title instead.
+  const passageLabel = (m: ChunkMeta): string => {
+    const id = (m.docidentifier || m.doc_id || "source").replace(/\s*\(([A-Z])\)\s*$/, "").trim();
+    const edition = m.edition && !id.includes(m.edition) ? ":" + m.edition : "";
+    const raw = String(m.clause_anchor ?? "");
+    const garbage = /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(raw) || (raw.startsWith("_") && raw.length > 12);
+    const anchor = garbage || !raw ? "" : ` §${raw}`;
+    return `${id}${edition}${anchor}`;
+  };
+  // passages in document reading order (FABLE NodeFusion): same-doc
+  // clauses read top-to-bottom, docs by best rank — synthesis quality
+  // depends on arrangement, not just the selected set
+  for (const h of positionOrder(hits)) {
+    const st = h.metadata.status === "withdrawn" || h.metadata.status === "superseded" ? ` [${h.metadata.status}]` : "";
+    const label = `${passageLabel(h.metadata)}${st}`;
+    // answer contract v2: typed passages declare their unit id so the
+    // model can reference [[u:<id>]] instead of retyping the object
+    const unitTag = (h.metadata as any).unit_id ? ` unit ${(h.metadata as any).unit_id}${(h.metadata as any).block ? ` (${(h.metadata as any).block})` : ""}` : "";
+    const head = `[${usedHits.length + 1}] ${label}${unitTag} ${h.metadata.clause_title ? "— " + h.metadata.clause_title : ""}\n`;
+    // tables: schema-aware pruning from the producer payload; the
+    // stored text is the fallback (pruning never goes below baseline)
+    const pruned = (h.metadata as any).block === "table" ? tableContext(h.metadata, query) : null;
+    const body = clipToTokens(pruned ?? h.text, LIMITS.maxPassageTokens);
+    const t = estTokens(head) + estTokens(body);
+    if (t <= remain) {
+      passageParts.push(head + body);
+      usedHits.push(h);
+      remain -= t;
+    } else if (usedHits.length < 2) {
+      // always keep at least the two best passages, truncated to fit
+      passageParts.push(head + clipToTokens(h.text, Math.max(150, remain - estTokens(head))));
+      usedHits.push(h);
+      remain = 0;
+      break;
+    } else break;
+  }
+  const context = passageParts.join("\n\n") || "(no passages)";
+
+  return {
+    messages: [
+      { role: "system", content: system },
+      ...(retrievalNote ? [{ role: "system", content: retrievalNote }] : []),
+      ...(summaryBlock ? [{ role: "system", content: summaryBlock }] : []),
+      ...keptHistory.map((h) => ({ role: h.role, content: h.content })),
+      { role: "user", content: `Question: ${query}\n\nContext passages:\n${context}` },
+    ],
+    usedHits,
+  };
+}
+
+function oimlPublicationUrl(meta: ChunkMeta): string | undefined {
+  if (!meta.doctype || !meta.doc_number) return undefined;
+  const typeMap: Record<string, string> = { R: "r", D: "d", B: "b", G: "g", E: "e" };
+  const t = typeMap[meta.doctype];
+  if (!t) return undefined;
+  return `https://www.oiml.org/en/publications/${t}${meta.doc_number}`;
+}
+
+export function citations(hits: Hit[]) {
+  const rank = (s?: string) => (s === "in-force" || s === "joint" ? 0 : s === "unknown" || !s ? 1 : 2);
+  return [...hits]
+    .map((h) => ({
+      doc_id: h.metadata.doc_id,
+      docidentifier: h.metadata.docidentifier,
+      edition: h.metadata.edition,
+      language: h.metadata.language,
+      clause_anchor: h.metadata.clause_anchor,
+      clause_title: h.metadata.clause_title,
+      status: h.metadata.status ?? "unknown",
+      superseded_by: h.metadata.superseded_by || undefined,
+      corpus: h.metadata.corpus || "oiml",
+      url: oimlPublicationUrl(h.metadata),
+      snippet: h.text.slice(0, 400),
+      score: h.rerank_score ?? h.score,
+    }))
+    .sort((a, b) => rank(a.status) - rank(b.status)); // in-force first, withdrawn last
+}

package/workers/worker_public/src/ports/blobs.ts

@@ -0,0 +1,7 @@
+/** Blobs — immutable object storage (unit assets, rendered documents).
+ *  Every mainstream provider speaks S3; the reference adapter speaks
+ *  R2's binding API. Objects are content-typed and read by key. */
+export interface Blobs {
+  get(key: string): Promise<{ body: ReadableStream | null; contentType?: string } | null>;
+  put(key: string, value: string | ReadableStream | ArrayBuffer, contentType?: string): Promise<void>;
+}

package/workers/worker_public/src/ports/cloudflare/adapters.ts

@@ -0,0 +1,177 @@
+/** The Cloudflare reference adapters — the ONLY module where provider
+ *  APIs appear. Domain modules import the port interfaces; the purity
+ *  lint (npm run lint:ports) fails any other file that names a
+ *  provider binding type. Zero runtime change: each adapter forwards
+ *  to the binding the call sites used to touch directly. */
+import type { ModelRunner, GenerateRequest, GenerateResult } from "../model.ts";
+import type { VectorIndex, VectorMatch, VectorQuery, VectorUpsert } from "../vector.ts";
+import type { Kv } from "../kv.ts";
+import type { Blobs } from "../blobs.ts";
+import type { Runtime } from "../runtime.ts";
+
+// Embedding request/response shapes vary across model generations; the
+// probes below try the known shapes in order and remember the winner
+// for the isolate's lifetime. Every wrong-shape attempt burns AI rate
+// budget, so the verified shape goes first. Total failure THROWS — an
+// empty vector would surface downstream as an opaque Vectorize 40006
+// (the 2026-09-14 regression: a probe-less adapter returned [] and the
+// index rejected the 0-dimension query).
+
+type EmbedRequestShape = (texts: string[]) => unknown;
+
+const EMBED_REQUEST_SHAPES: Record<string, EmbedRequestShape> = {
+  // "text" first: the verified request shape for qwen3-embedding-0.6b
+  text: (texts) => ({ text: texts }),
+  "input.input": (texts) => ({ input: { input: texts } }),
+  array: (texts) => ({ input: texts }),
+};
+
+let embedRequestWinner: string | null = null;
+
+function extractVecBatch(res: unknown, n: number): number[][] | null {
+  const r = res as any;
+  const d = r?.data ?? r?.result?.data;
+  const rows = Array.isArray(d) ? d : Array.isArray(r?.embedding) ? [r.embedding] : null;
+  if (!rows) return null;
+  const out: number[][] = [];
+  for (const row of rows.slice(0, n)) {
+    const vec = Array.isArray(row) ? row : Array.isArray(row?.embedding) ? row.embedding : null;
+    if (!vec || vec.length === 0) return null;
+    out.push(vec.map(Number));
+  }
+  return out.length === n ? out : null;
+}
+
+const by20 = <T>(xs: T[]): T[][] => {
+  const out: T[][] = [];
+  for (let i = 0; i < xs.length; i += 20) out.push(xs.slice(i, i + 20));
+  return out;
+};
+
+const RERANK_SHAPES = (query: string, texts: string[]) => [
+  { query, contexts: texts.map((t) => ({ text: t })) },
+  { query, contexts: texts },
+  { query, candidates: texts.map((t, i) => ({ id: String(i), text: t })) },
+  { query, passages: texts },
+];
+
+export function cfModelRunner(ai: unknown): ModelRunner {
+  const A = ai as any;
+  return {
+    async embed(texts: string[]) {
+      const order = embedRequestWinner ? [embedRequestWinner] : Object.keys(EMBED_REQUEST_SHAPES);
+      for (const name of order) {
+        for (let attempt = 0; attempt < 3; attempt++) {
+          try {
+            const res = await A.run("@cf/qwen/qwen3-embedding-0.6b", EMBED_REQUEST_SHAPES[name](texts));
+            const vecs = extractVecBatch(res, texts.length);
+            if (vecs) {
+              embedRequestWinner = name;
+              return vecs;
+            }
+          } catch {
+            // retry the same shape, then fall through to the next
+          }
+          await new Promise((r) => setTimeout(r, 250 * (attempt + 1)));
+        }
+      }
+      throw new Error(`embedding failed for all request shapes (${texts.length} text(s))`);
+    },
+    async rerank(model, query, texts) {
+      for (const body of RERANK_SHAPES(query, texts)) {
+        try {
+          const res: any = await A.run(model, body);
+          const raw = res?.data ?? res?.result?.data ?? res?.response;
+          if (!Array.isArray(raw)) continue;
+          const scores: number[] = new Array(texts.length).fill(NaN);
+          raw.forEach((x: any, i: number) => {
+            if (typeof x === "number") {
+              scores[i] = x;
+              return;
+            }
+            const id = Number(x?.id ?? x?.index ?? i);
+            const s = Number(x?.score ?? x?.relevance_score);
+            if (Number.isInteger(id) && id >= 0 && id < texts.length && Number.isFinite(s)) scores[id] = s;
+          });
+          if (scores.some((s) => Number.isFinite(s))) return scores;
+        } catch {
+          // next shape
+        }
+      }
+      return null;
+    },
+    async run(req: GenerateRequest): Promise<GenerateResult> {
+      const res: any = await (ai as any).run(req.model, {
+        messages: req.messages,
+        max_tokens: req.maxTokens,
+        ...(req.effort ? { reasoning_effort: req.effort } : {}),
+        ...(req.temperature != null ? { temperature: req.temperature } : {}),
+        ...(req.topP != null ? { top_p: req.topP } : {}),
+        ...(req.topK != null ? { top_k: req.topK } : {}),
+        ...(req.stream ? { stream: true } : {}),
+      });
+      if (req.stream && res && typeof res.getReader === "function") return { text: null, stream: res };
+      if (req.stream && res?.body && typeof res.body.getReader === "function") return { text: null, stream: res.body };
+      const text = typeof res?.response === "string" ? res.response : res?.choices?.[0]?.message?.content;
+      return { text: typeof text === "string" ? text : null };
+    },
+  };
+}
+
+export function cfVectorIndex(index: unknown): VectorIndex {
+  const ix = index as any;
+  return {
+    async query(q: VectorQuery) {
+      const r = await ix.query(q.vector, {
+        topK: q.topK,
+        returnMetadata: "all",
+        ...(q.filter ? { filter: q.filter } : {}),
+      });
+      return (r.matches ?? r).map((m: any) => ({ id: m.id, score: m.score, metadata: m.metadata ?? null }));
+    },
+    async upsert(vectors: VectorUpsert[]) {
+      // the adapter law: batches above the provider cap go in chunks
+      for (const group of by20(vectors)) await ix.upsert(group);
+    },
+    async getByIds(ids: string[]) {
+      // getByIds above ~20 returns EMPTY silently — chunk, always
+      const out: VectorMatch[] = [];
+      for (const group of by20(ids)) {
+        const got = await ix.getByIds(group);
+        out.push(...(got ?? []).map((m: any) => ({ id: m.id, score: 0, metadata: m.metadata ?? null })));
+      }
+      return out;
+    },
+  };
+}
+
+export function cfKv(ns: unknown): Kv {
+  const kv = ns as any;
+  return {
+    get: (key) => kv.get(key),
+    put: (key, value, opts) => kv.put(key, value, opts?.ttlSec ? { expirationTtl: opts.ttlSec } : undefined),
+  };
+}
+
+export function cfBlobs(bucket: unknown): Blobs {
+  const r2 = bucket as any;
+  return {
+    async get(key) {
+      const obj = await r2.get(key);
+      if (!obj) return null;
+      return { body: obj.body, contentType: obj.httpMetadata?.contentType };
+    },
+    async put(key, value, contentType) {
+      await r2.put(key, value, contentType ? { httpMetadata: { contentType } } : undefined);
+    },
+  };
+}
+
+export function cfRuntime(ctx: { waitUntil(p: Promise<unknown>): void } | undefined): Runtime {
+  return {
+    defer(fn) {
+      if (ctx) ctx.waitUntil(fn());
+      else void fn();
+    },
+  };
+}

package/workers/worker_public/src/ports/kv.ts

@@ -0,0 +1,8 @@
+/** Kv — the hot read path's get/put with TTL. Ephemeral by contract:
+ *  answer caches and quota counters treat this as disposable state
+ *  (generation stamps + TTLs), so any adapter that honors the two
+ *  operations is conformant. */
+export interface Kv {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, opts?: { ttlSec?: number }): Promise<void>;
+}

package/workers/worker_public/src/ports/model.ts

@@ -0,0 +1,28 @@
+/** ModelRunner — the port over every model call. Adapters translate
+ *  into provider catalogs and own provider-specific call shaping:
+ *  request-shape probing (rerank variants), sampling quirks, the
+ *  effort-budget coupling. Domain modules never see a provider body.
+ *
+ *  multi-SDO / multi-cloud: docs/konneal-extraction-plan.md §5. */
+export interface GenerateRequest {
+  model: string;
+  messages: unknown[];
+  effort?: string;
+  maxTokens?: number;
+  temperature?: number;
+  topP?: number;
+  topK?: number;
+  stream?: boolean;
+}
+export interface GenerateResult {
+  text: string | null;
+  stream?: ReadableStream<Uint8Array> | null;
+}
+
+export interface ModelRunner {
+  embed(texts: string[]): Promise<number[][]>;
+  /** rerank with adapter-side request-shape probing; returns one score
+   *  per text, or null when the provider degraded (caller falls back) */
+  rerank(model: string, query: string, texts: string[]): Promise<number[] | null>;
+  run(req: GenerateRequest): Promise<GenerateResult>;
+}

package/workers/worker_public/src/ports/runtime.ts

@@ -0,0 +1,13 @@
+/** Runtime — background work after the response. The semantic is
+ *  fire-and-forget best effort: adapters may await or schedule; the
+ *  domain must never depend on completion for correctness. */
+export interface Runtime {
+  defer(fn: () => Promise<void>): void;
+}
+
+/** Background — the raw waitUntil surface. ExecutionContext satisfies
+ *  this structurally; telemetry and other edge utilities depend on the
+ *  shape, never on the provider type. */
+export interface Background {
+  waitUntil(p: Promise<unknown>): void;
+}

package/workers/worker_public/src/ports/store.ts

@@ -0,0 +1,20 @@
+/** StoreQuery — the transitional relational port. The engine's
+ *  repositories speak prepared statements (prepare/bind/first/all/
+ *  batch); the Cloudflare adapter exposes D1 directly, and a Postgres
+ *  adapter implements the same five methods over its driver. When the
+ *  repository extraction completes, this narrows to semantic
+ *  repositories (documents, sessions, memories…) and the SQL dialect
+ *  disappears from the port entirely. */
+export interface StoreQuery {
+  prepare(sql: string): {
+    bind(...values: unknown[]): { first<T = unknown>(): Promise<T | null>; all<T = unknown>(): Promise<{ results: T[] }>; run(): Promise<unknown> };
+    first<T = unknown>(): Promise<T | null>;
+    all<T = unknown>(): Promise<{ results: T[] }>;
+    run(): Promise<unknown>;
+  };
+  batch(statements: unknown[]): Promise<unknown[]>;
+}
+
+// the glossary lane's vector probe: the port view of a lane index
+import type { VectorIndex } from "./vector.ts";
+export type { VectorIndex };

package/workers/worker_public/src/ports/vector.ts

@@ -0,0 +1,26 @@
+/** VectorIndex — dense search with metadata filters. The port contract
+ *  IS the wire law: metadata values are scalars or string arrays
+ *  (API error 40017 otherwise); getByIds returns empty above its
+ *  batch cap, so adapters chunk. Lexical search stays ENGINE-side —
+ *  adapters need only dense+filters, the weakest common denominator. */
+export interface VectorMatch {
+  id: string;
+  score: number;
+  metadata: Record<string, unknown> | null;
+}
+export interface VectorQuery {
+  vector: number[];
+  topK: number;
+  filter?: Record<string, unknown>;
+}
+export interface VectorUpsert {
+  id: string;
+  values: number[];
+  metadata: Record<string, unknown>;
+}
+
+export interface VectorIndex {
+  query(q: VectorQuery): Promise<VectorMatch[]>;
+  upsert(vectors: VectorUpsert[]): Promise<void>;
+  getByIds(ids: string[]): Promise<VectorMatch[]>;
+}