@konneal/engine 0.1.0

package/workers/worker_public/src/profile.gen.ts

@@ -0,0 +1,101 @@
+// GENERATED from profile/*.yaml — regenerate: node scripts/gen_profile.mjs
+// (never edit; the drift test compares this file to the sources)
+export const PROFILE = {
+  "publisher": {
+    "id": "fixture",
+    "name": "Fixture",
+    "full_name": "The Fixture Publisher",
+    "product_name": "Fixture Answers",
+    "description": "A minimal publisher profile exercising every declared surface: an open dataset, a permission-gated dataset, production and lane corpora, prompt vars and retrieval vocabulary.",
+    "domains": {
+      "public": "fixture.example.org"
+    },
+    "identity": {
+      "issuer": "https://id.fixture.example.org"
+    },
+    "codec": "plain-slug"
+  },
+  "datasets": [
+    {
+      "id": "pub",
+      "label": "Fixture Publications",
+      "description": "The fixture publisher's corpus",
+      "corpora": [
+        "pub",
+        "dirty",
+        "clean",
+        "synthetic"
+      ],
+      "note": "Some passages come from the fixture corpus — cite them the same way as every other passage."
+    },
+    {
+      "id": "internal",
+      "label": "Internal corpus",
+      "description": "An access-restricted corpus proving the permission gate",
+      "session": true,
+      "permission": "preview",
+      "corpora": [
+        "internal"
+      ]
+    }
+  ],
+  "corpora": {
+    "production": [
+      "pub",
+      "dirty",
+      "clean",
+      "synthetic",
+      "model"
+    ],
+    "lanes": {
+      "exp_a": [
+        "exp_a"
+      ],
+      "exp_b": [
+        "exp_b"
+      ],
+      "glossary": [
+        "glossary"
+      ]
+    }
+  },
+  "sources": {
+    "corpora": {
+      "clean": {
+        "repo": "fixtures/corpus",
+        "note": "the engine's fixture corpus"
+      }
+    },
+    "bibliography": {},
+    "terminology": {},
+    "models": {}
+  },
+  "ui": {
+    "suggestions": [
+      "What is in the fixture corpus?",
+      "Which documents does the fixture publisher issue?"
+    ],
+    "models_disclosure": [
+      {
+        "role": "Answers",
+        "model": "fixture-answer-model"
+      }
+    ],
+    "smoke": [
+      {
+        "label": "sanity",
+        "query": "What is in the fixture corpus?",
+        "expect": "fixture"
+      }
+    ]
+  },
+  "retrieval": {
+    "process_expansion": " fixture certification system framework application evaluation"
+  },
+  "prompts": {
+    "vars": {
+      "assistant_identity": "the fixture assistant — a public service answering questions about the fixture publisher's documents",
+      "refusal_sentence": "I don't have information on this in the indexed fixture documents."
+    }
+  }
+} as const;

package/workers/worker_public/src/profile.ts

@@ -0,0 +1,16 @@
+// The profile registry (konneal item 06/09): a deployment injects its
+// OWN publisher profile at the entry (setProfile) before the first
+// request; every read goes through P() at request time so module-eval
+// order can never bake the wrong profile. The default is the engine's
+// fixture, so the engine runs and tests pass standalone.
+import { PROFILE as FIXTURE } from "./profile.gen.ts";
+
+let current: unknown = FIXTURE;
+
+export function setProfile(profile: unknown): void {
+  current = profile;
+}
+
+export function P<T = any>(): T {
+  return current as T;
+}

package/workers/worker_public/src/projects.ts

@@ -0,0 +1,108 @@
+// Projects (#187 design): a container owning memory files and a set of
+// conversations. Every query is owner-filtered through the owning
+// project's sub; file caps mirror the personal-memory tier (10 × 8k).
+// Membership is a MOVE (conversations.project_id set/clear) — the next
+// answer re-scopes, history keeps its recorded grounding.
+import { json, err } from "./lib/http";
+
+const MAX_FILES = 10;
+const MAX_CONTENT = 8_000;
+const MAX_NAME = 64;
+const PROJECT_ID_RE = /^p:[a-f0-9]{16}$/;
+const FILE_ID_RE = /^pf:[a-f0-9]{16}$/;
+
+const hex16 = () => [...crypto.getRandomValues(new Uint8Array(8))].map((b) => b.toString(16).padStart(2, "0")).join("");
+
+async function ownedProject(env: any, sub: string, id: string) {
+  if (!PROJECT_ID_RE.test(id)) return null;
+  return await env.DB.prepare("SELECT id, name, created_at FROM projects WHERE id = ?1 AND sub = ?2").bind(id, sub).first();
+}
+
+export async function handleProjects(env: any, sub: string, req: Request, route: { method: string; id?: string }): Promise<Response> {
+  const { method, id } = route;
+  if (method === "GET") {
+    const rows = (await env.DB.prepare(
+      "SELECT p.id, p.name, p.created_at, (SELECT COUNT(*) FROM project_files f WHERE f.project_id = p.id) AS file_count, "
+      + "(SELECT COUNT(*) FROM conversations c WHERE c.project_id = p.id) AS conversation_count "
+      + "FROM projects p WHERE p.sub = ?1 ORDER BY p.created_at DESC",
+    ).bind(sub).all()).results ?? [];
+    return json({ projects: rows });
+  }
+  if (method === "POST") {
+    const body: any = await req.json().catch(() => null);
+    if (typeof body?.project_id === "string") {
+      // move a conversation in/out of a project (membership-as-move)
+      const convId = String(body.conversation_id ?? "");
+      if (!/^[a-zA-Z0-9_-]{8,64}$/.test(convId)) return err(400, "invalid_input", "bad conversation id");
+      const target = body.project_id === null ? null : String(body.project_id);
+      if (target && !(await ownedProject(env, sub, target))) return err(404, "not_found", "no such project");
+      const r = await env.DB.prepare("UPDATE conversations SET project_id = ?1 WHERE id = ?2 AND sub = ?3").bind(target, convId, sub).run();
+      if (!r.meta?.changes) return err(404, "not_found", "no such conversation");
+      return json({ ok: true });
+    }
+    if (typeof body?.id === "string" && PROJECT_ID_RE.test(body.id)) {
+      if (!(await ownedProject(env, sub, body.id))) return err(404, "not_found", "no such project");
+      const name = typeof body.name === "string" ? body.name.trim().slice(0, MAX_NAME) : "";
+      if (!name) return err(400, "invalid_input", "name required");
+      await env.DB.prepare("UPDATE projects SET name = ?1 WHERE id = ?2 AND sub = ?3").bind(name, body.id, sub).run();
+      return json({ ok: true, id: body.id });
+    }
+    const name = typeof body?.name === "string" ? body.name.trim().slice(0, MAX_NAME) : "";
+    if (!name) return err(400, "invalid_input", "name required");
+    const pid = "p:" + hex16();
+    await env.DB.prepare("INSERT INTO projects (id, sub, name, created_at) VALUES (?1, ?2, ?3, ?4)").bind(pid, sub, name, Date.now()).run();
+    return json({ ok: true, id: pid });
+  }
+  if (method === "DELETE") {
+    if (!id || !PROJECT_ID_RE.test(id)) return err(400, "invalid_input", "bad project id");
+    if (!(await ownedProject(env, sub, id))) return err(404, "not_found", "no such project");
+    await env.DB.batch([
+      env.DB.prepare("UPDATE conversations SET project_id = NULL WHERE project_id = ?1 AND sub = ?2").bind(id, sub),
+      env.DB.prepare("DELETE FROM project_files WHERE project_id = ?1").bind(id),
+      env.DB.prepare("DELETE FROM projects WHERE id = ?1 AND sub = ?2").bind(id, sub),
+    ]);
+    return json({ ok: true });
+  }
+  return err(405, "method_not_allowed", "GET, POST or DELETE");
+}
+
+export async function handleProjectFiles(env: any, sub: string, req: Request, route: { method: string; id?: string }): Promise<Response> {
+  const { method, id } = route;
+  if (method === "GET") {
+    if (!id || !PROJECT_ID_RE.test(id)) return err(400, "invalid_input", "bad project id");
+    if (!(await ownedProject(env, sub, id))) return err(404, "not_found", "no such project");
+    const rows = (await env.DB.prepare("SELECT id, name, content, updated_at FROM project_files WHERE project_id = ?1 ORDER BY updated_at DESC").bind(id).all()).results ?? [];
+    return json({ files: rows });
+  }
+  if (method === "POST") {
+    const body: any = await req.json().catch(() => null);
+    const projectId = typeof body?.project_id === "string" ? body.project_id : "";
+    if (!PROJECT_ID_RE.test(projectId) || !(await ownedProject(env, sub, projectId))) return err(404, "not_found", "no such project");
+    const name = typeof body?.name === "string" ? body.name.trim().slice(0, MAX_NAME) : "";
+    const content = typeof body?.content === "string" ? body.content.slice(0, MAX_CONTENT) : "";
+    if (!name || !content.trim()) return err(400, "invalid_input", "name and content are required");
+    const now = Date.now();
+    if (typeof body?.id === "string" && FILE_ID_RE.test(body.id)) {
+      const r = await env.DB.prepare(
+        "UPDATE project_files SET name = ?1, content = ?2, updated_at = ?3 WHERE id = ?4 AND project_id = ?5",
+      ).bind(name, content, now, body.id, projectId).run();
+      if (!r.meta?.changes) return err(404, "not_found", "no such file");
+      return json({ ok: true, id: body.id });
+    }
+    const count = Number((await env.DB.prepare("SELECT COUNT(*) AS n FROM project_files WHERE project_id = ?1").bind(projectId).first() as any)?.n ?? 0);
+    if (count >= MAX_FILES) return err(400, "quota_exceeded", `at most ${MAX_FILES} files per project`);
+    const fid = "pf:" + hex16();
+    await env.DB.prepare(
+      "INSERT INTO project_files (id, project_id, name, content, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, ?5, ?5)",
+    ).bind(fid, projectId, name, content, now).run();
+    return json({ ok: true, id: fid });
+  }
+  if (method === "DELETE") {
+    if (!id || !FILE_ID_RE.test(id)) return err(400, "invalid_input", "bad file id");
+    await env.DB.prepare(
+      "DELETE FROM project_files WHERE id = ?1 AND project_id IN (SELECT id FROM projects WHERE sub = ?2)",
+    ).bind(id, sub).run();
+    return json({ ok: true });
+  }
+  return err(405, "method_not_allowed", "GET, POST or DELETE");
+}

package/workers/worker_public/src/prompts.d.ts

@@ -0,0 +1,6 @@
+// Prompt data files (../prompts/*.md) are bundled by wrangler's Text
+// module rule and imported as strings.
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

package/workers/worker_public/src/quota.ts

@@ -0,0 +1,54 @@
+// Quota + telemetry: per-bucket daily counters (KV) and the D1
+// queries/spend ledger writes (TODO.impl/23).
+import { sha256Hex, today } from "./config";
+import type { Env } from "./env";
+import type { Background } from "./ports/runtime.ts";
+
+export async function kvIncr(cache: KVNamespace, key: string, step = 1): Promise<number> {
+  const cur = Number((await cache.get(key)) ?? "0");
+  const next = cur + step;
+  await cache.put(key, String(next), { expirationTtl: 90000 });
+  return next;
+}
+
+export function clientIp(req: Request): string {
+  return req.headers.get("cf-connecting-ip") ?? "unknown";
+}
+
+/** Daily ask quota. `weight` is the effort multiplier: a thorough
+ *  (elevated-effort) answer consumes more of the day's budget —
+ *  different reasoning efforts naturally cost different quota. */
+export async function checkQuota(
+  env: Env,
+  bucket: string,
+  id: string,
+  limit: number,
+  weight = 1,
+): Promise<{ ok: boolean; used: number; limit: number }> {
+  const used = await kvIncr(env.CACHE, `q:${today()}:${bucket}:${await sha256Hex(id)}`, weight);
+  return { ok: used <= limit, used, limit };
+}
+
+export function telemetry(
+  env: Env,
+  ctx: Background,
+  tier: string,
+  route: string,
+  model: string | null,
+  ok: boolean,
+  answerChars: number,
+  queryHash: string,
+  lang?: string,
+) {
+  const day = today();
+  ctx.waitUntil(
+    env.DB.batch([
+      env.DB.prepare(
+        "INSERT INTO queries (ts, day, tier, route, model, ok, answer_chars, query_hash, lang) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9)",
+      ).bind(new Date().toISOString(), day, tier, route, model, ok ? 1 : 0, answerChars, queryHash, lang ?? null),
+      env.DB.prepare(
+        "INSERT INTO spend (day, tier, model, requests) VALUES (?1,?2,?3,1) ON CONFLICT(day, tier, model) DO UPDATE SET requests = requests + 1",
+      ).bind(day, tier, model ?? "none"),
+    ]),
+  );
+}

package/workers/worker_public/src/reflect.ts

@@ -0,0 +1,67 @@
+// Self-RAG style reflection loop: after generating the answer, the model
+// critiques whether every claim is grounded in the passages. If NOT, it
+// identifies what's missing and the system retries retrieval.
+// Ref: selfrag.github.io; Meilisearch self-RAG guide
+
+// The prompt is data (prompts/reflect.md), bundled as text.
+import reflectPrompt from "../prompts/reflect.md";
+
+export interface ReflectionResult {
+  grounded: boolean;
+  missing_info: string;
+}
+
+export async function reflect(
+  ai: any,
+  model: string,
+  question: string,
+  answer: string,
+  passages: string[],
+): Promise<ReflectionResult | null> {
+  if (!answer || !passages.length) return null;
+  const ctx = passages
+    .slice(0, 8)
+    .map((p, i) => `[${i + 1}] ${p.replace(/\s+/g, " ").slice(0, 300)}`)
+    .join("\n");
+
+  const timeout = new Promise<null>((r) => setTimeout(() => r(null), 6000));
+  const call = (async () => {
+    const res: any = await ai.run(model, {
+      messages: [
+        {
+          role: "system",
+          content: reflectPrompt.trimEnd(),
+        },
+        {
+          role: "user",
+          content: `Question: ${question}\n\nAnswer:\n${answer.slice(0, 1500)}\n\nPassages:\n${ctx}`,
+        },
+      ],
+      // reasoning shares this budget — starved budgets silently disable
+      // the reflection layer (null = no retry ever fires); DeepSeek-V4
+      // card: keep reasoning on with headroom + temp 1.0 / top_p 1.0
+      max_tokens: 3072,
+      reasoning_effort: "low",
+      temperature: 1.0,
+      top_p: 1.0,
+    });
+    const text = typeof res?.response === "string" ? res.response : res?.choices?.[0]?.message?.content;
+    const m = (text ?? "").match(/\{[\s\S]*\}/);
+    if (!m) return null;
+    try {
+      const raw = JSON.parse(m[0]);
+      return {
+        grounded: raw.grounded === true,
+        missing_info: typeof raw.missing_info === "string" ? raw.missing_info.slice(0, 200) : "",
+      };
+    } catch {
+      return null;
+    }
+  })();
+
+  try {
+    return await Promise.race([call, timeout]);
+  } catch {
+    return null;
+  }
+}

package/workers/worker_public/src/refs.ts

@@ -0,0 +1,107 @@
+// Answer contract v2 — symbolic unit references (SymGen-style,
+// arXiv:2311.09188): the model may write [[u:<id>]] tokens pointing at
+// typed MKO units among the passages. Every reference is VALIDATED
+// against the units actually present in usedHits; invalid refs are
+// dropped from the rendered text (logged, never shown). The payload
+// data itself never passes through the LLM — blocks are resolved from
+// the producer-validated D1 unit_payloads table.
+
+import type { StoreQuery } from "./ports/store.ts";
+export interface ResolvedBlock {
+  unit_id: string;
+  type: string;
+  docidentifier: string;
+  edition?: string;
+  payload: Record<string, unknown>;
+}
+
+const REF = /\[\[(u:[A-Za-z0-9_-]+)\]\]/g;
+
+/** unit ids the passages actually contain (chunk metadata carries
+ *  unit_id on typed MKO chunks). */
+export function availableUnitIds(hits: ReadonlyArray<{ metadata: { unit_id?: string | undefined } }>): Set<string> {
+  const ids = new Set<string>();
+  for (const h of hits) {
+    const u = h.metadata?.unit_id;
+    if (u) ids.add(u);
+  }
+  return ids;
+}
+
+export function parseRefs(text: string): string[] {
+  return [...text.matchAll(REF)].map((m) => m[1]);
+}
+
+/** Drop refs that don't resolve to a used passage unit — a dangling ref
+ *  renders as nothing (the token removed), and the violation is logged. */
+export function sanitizeRefs(text: string, available: ReadonlySet<string>): { text: string; dropped: string[] } {
+  const dropped: string[] = [];
+  const out = text.replace(REF, (full, id: string) => {
+    if (available.has(id)) return full;
+    dropped.push(id);
+    return "";
+  });
+  return { text: out, dropped };
+}
+
+/** Resolve validated refs to producer payloads from D1 (unit_payloads).
+ *  Unknown-to-D1 ids are skipped — a ref without a payload renders as a
+ *  plain token, never as fabricated data. */
+export async function resolveBlocks(
+  db: StoreQuery,
+  refs: string[],
+): Promise<ResolvedBlock[]> {
+  if (!refs.length) return [];
+  const uniq = [...new Set(refs)].slice(0, 12);
+  const blocks: ResolvedBlock[] = [];
+  for (let i = 0; i < uniq.length; i += 20) {
+    const batch = uniq.slice(i, i + 20);
+    const placeholders = batch.map((_, n) => `?${n + 1}`).join(",");
+    try {
+      const res = await db
+        .prepare(`SELECT unit_id, type, docidentifier, edition, payload FROM unit_payloads WHERE unit_id IN (${placeholders})`)
+        .bind(...batch)
+        .all<{ unit_id: string; type: string; docidentifier: string | null; edition: string | null; payload: string }>();
+      for (const r of res.results) {
+        let payload: Record<string, unknown> = {};
+        try {
+          payload = JSON.parse(String(r.payload));
+        } catch {
+          continue;
+        }
+        blocks.push({
+          unit_id: String(r.unit_id),
+          type: String(r.type),
+          docidentifier: String(r.docidentifier ?? ""),
+          edition: r.edition ? String(r.edition) : undefined,
+          payload,
+        });
+      }
+    } catch (e) {
+      console.log("resolveBlocks failed:", String(e).slice(0, 150));
+    }
+  }
+  return blocks;
+}
+
+/** One pass: validate + resolve + strip invalid tokens. */
+export async function contractV2(
+  db: StoreQuery,
+  answer: string,
+  usedHits: ReadonlyArray<{ metadata: { unit_id?: string | undefined } }>,
+): Promise<{ text: string; blocks: ResolvedBlock[]; dropped: string[] }> {
+  const available = availableUnitIds(usedHits);
+  const { text, dropped } = sanitizeRefs(answer, available);
+  if (dropped.length) console.log("refs: dropped", dropped.length, "invalid (not in passages)");
+  const refs = parseRefs(text);
+  const blocks = await resolveBlocks(db, refs);
+  return { text, blocks, dropped };
+}
+
+/** Detect table-retyping: a markdown table in the answer while a typed
+ *  table unit was available to reference. Enforcement signal for the
+ *  corrective regen (same pattern as quote-anchor violations). */
+export function tableRetyped(text: string, availableTable: boolean): boolean {
+  if (!availableTable) return false;
+  return /(^|\n)\s*\|[^\n]+\|\s*(\n\s*\|[-: |]+\|\s*)?(\n|$)/.test(text) && (text.match(/\|/g) ?? []).length >= 6;
+}

package/workers/worker_public/src/refusal.ts

@@ -0,0 +1,65 @@
+import { P } from "./profile.ts";
+/** The one sanctioned refusal sentence (also in prompts/system.md).
+ *  Refusals are never cached: a refusal says "retrieval found nothing",
+ *  which is a property of the moment, not of the question. */
+export function refusalAnswer(): string {
+  return P().prompts.vars.refusal_sentence;
+}
+
+// the model occasionally paraphrases the refusal sentence ("...information
+// on how to make lasagna in the indexed..."); the API contract is the
+// exact canonical sentence — normalize variants, keep the redirect tail
+const REFUSAL_VARIANT = /^\s*I don[’']?t have information on .{1,120}? in the indexed OIML(?: \w+){0,2} (?:publications|passages|documents|corpus)\.?/i;
+
+// Upstream wording drift (rag#88, the golden refusal pin recalibrated
+// 2026-09-01): the model now also refuses with no pinned sentence at all —
+// a "can't help" redirect naming the OIML publications, or a "no real
+// answer to give" paraphrase. The runtime and the harness pins
+// (scripts/eval.mjs, tests/e2e.mjs, tests/eval-suite.mjs) carry the SAME
+// family: every shape the tests accept canonicalizes to the pinned
+// sentence here, and nothing else does.
+const REFUSAL_DRIFT: RegExp[] = [
+  /\b(can'?t|cannot|couldn'?t|unable)\b[^.]{0,120}?\b(indexed )?OIML(?: \w+){0,2} publications\b/i,
+  /\bno real answer to give\b[^.]{0,120}?\bOIML\b/i,
+  /\b(?:falls|well) outside\b[^.]{0,120}?\b(?:what I can answer|my scope|the scope of)\b/i,
+  /\boutside (?:of )?what (?:I|this service) can answer\b/i,
+  // "I can't answer that — weather forecasting is outside my scope":
+  // requires the refusal verb, so a scope DISCUSSION inside a real answer
+  // ("this exemption is outside the scope of R 60") never matches
+  /\bI can[’']?t answer\b[^.]{0,100}?\bscope\b/i,
+  /^\s*I don[’']?t have any indexed OIML \w+(?:s)? (?:covering|about|on)\b/im,
+];
+
+/** Start of the sentence containing offset `i` (after the nearest ". ",
+ *  "! ", "? ", or newline before it, else the string start). */
+function sentenceStart(answer: string, i: number): number {
+  let s = 0;
+  for (const sep of [". ", "! ", "? ", "\n"]) {
+    const j = answer.lastIndexOf(sep, i);
+    if (j >= 0) s = Math.max(s, j + sep.length);
+  }
+  return s;
+}
+
+/** End (terminator included) of the sentence containing offset `i`. */
+function sentenceEnd(answer: string, i: number): number {
+  const m = /[.!?\n]/.exec(answer.slice(i));
+  return m ? i + m.index + 1 : answer.length;
+}
+
+/** Normalize a refusal-shaped answer to the pinned sentence. A drift
+ *  refusal occupies its own sentence: swap that sentence (preface
+ *  included) for the pinned one — the redirect tail survives. An answer
+ *  outside the refusal family is returned byte-identical. */
+export function canonicalRefusal(answer: string): string {
+  const CANON = refusalAnswer();
+  if (answer.includes(CANON)) return answer;
+  const variant = answer.match(REFUSAL_VARIANT);
+  if (variant) return answer.replace(variant[0], CANON);
+  for (const drift of REFUSAL_DRIFT) {
+    const m = drift.exec(answer);
+    if (!m) continue;
+    return answer.slice(0, sentenceStart(answer, m.index)) + CANON + answer.slice(sentenceEnd(answer, m.index));
+  }
+  return answer;
+}

package/workers/worker_public/src/requestScope.ts

@@ -0,0 +1,71 @@
+// The per-request scope model (MECE: ask.ts orchestrates, this module
+// owns the derivation): which DATASETS the request searches (the sidebar
+// toggles, server-intersected with session permissions) and which
+// memory files ride it — plus the answer-cache SALT both selections
+// produce. Pure: D1 access stays with the caller (memoryNote); this
+// module only derives.
+import { DATASETS, datasetAllowed } from "./config.ts";
+
+export interface RequestScope {
+  /** dataset ids the request may search */
+  scopeIds: string[];
+  /** corpus values the scope maps to (for the corpus-scope stage) */
+  corpora: Set<string>;
+  /** true when the scope is narrower than the session default — the
+   *  stage only runs when narrowed (the default costs nothing) */
+  narrowed: boolean;
+  /** ISO federation on? (gates the internal binding) */
+  isoOn: boolean;
+  /** raw (validated) memory ids from the body — empty for anon */
+  memoryIds: string[];
+}
+
+/** Validate + intersect. Returns { error } when the request explicitly
+ *  disables every dataset (a user error, not a scope). The corpora a
+ *  dataset searches travel WITH the declaration (profile datasets.yaml,
+ *  `corpora:`) — the engine maps no publisher names. */
+export function resolveRequestScope(body: any, member: unknown): RequestScope | { error: "empty-datasets" } {
+  const allIds = DATASETS().map((d) => d.id);
+  const requested = Array.isArray(body?.datasets)
+    ? (body.datasets as unknown[]).filter((x): x is string => typeof x === "string" && allIds.includes(x))
+    : null;
+  if (requested !== null && requested.length === 0) return { error: "empty-datasets" };
+  const permittedIds = allIds.filter((id) => {
+    const d = DATASETS().find((x) => x.id === id)!;
+    return d.session ? datasetAllowed(d, member) : true;
+  });
+  // requested ∩ permitted — an explicit request NEVER widens past the
+  //  session's permissions (a member without ai-preview asking
+  //  datasets:["iso"] intersects to nothing, exactly like the default
+  //  path; the intersection, not the caller, is the gate)
+  const scopeIds = (requested ?? permittedIds).filter((id) => permittedIds.includes(id));
+  const corpora = new Set<string>();
+  for (const id of scopeIds) {
+    const d = DATASETS().find((x) => x.id === id);
+    for (const v of d?.corpora ?? [id]) corpora.add(v);
+  }
+  const memoryIds = member && Array.isArray(body?.memories)
+    ? (body.memories as unknown[]).filter((x): x is string => typeof x === "string").slice(0, 4)
+    : [];
+  return {
+    scopeIds,
+    corpora,
+    narrowed: scopeIds.length < permittedIds.length,
+    // federation flag: any session-gated (federated) dataset in scope
+    isoOn: scopeIds.some((id) => DATASETS().find((x) => x.id === id)?.session === true),
+    memoryIds,
+  };
+}
+
+/** The answer-cache salt: request-scoped context that materially changes
+ *  the answer (dataset scope, memory selection). Requests differing only
+ *  in salt share query text — an unsalted key would serve a scoped (or
+ *  memory-flavored) answer to a plain ask. Null = default scope, no
+ *  memory: keys stay byte-identical to the pre-salt era. */
+export function requestSalt(scope: RequestScope, memoryUsed: string[]): string | null {
+  if (!scope.narrowed && !memoryUsed.length) return null;
+  return JSON.stringify({
+    ...(scope.narrowed ? { d: [...scope.corpora].sort() } : {}),
+    ...(memoryUsed.length ? { m: [...memoryUsed].sort() } : {}),
+  });
+}