@konneal/engine 0.1.0

package/workers/worker_public/src/auth.ts

@@ -0,0 +1,252 @@
+// Auth routes: OIDC authorization-code + PKCE against the estate OP
+// (id.oimlsmart.org), per docs/identity-service.md. The OP declares WHO
+// the user is; quota tiers (what they may do here) are ours.
+
+import {
+  buildAuthorizationUrl,
+  buildEndSessionUrl,
+  discoverIssuer,
+  exchangeCode,
+  generatePkce,
+  randomToken,
+  validateIdToken,
+  fetchUserinfo,
+  OidcError,
+} from "./oidc";
+import { clearSessionCookie, mintSessionCookie, mintSessionToken, rawSessionToken, readSession, sessionCookieFromToken, SessionClaims } from "./session";
+import { bubbleConfirmPage, isAllowedBubbleOrigin } from "./bubble";
+import { dropOpAccessToken, retainOpAccessToken } from "./livedata";
+
+const PLAIN_LANGUAGE: Record<string, string> = {
+  not_configured: "Sign-in is not configured for this service yet.",
+  discovery: "The sign-in service could not be reached. Please try again shortly.",
+  issuer_mismatch: "The sign-in service answered from an unexpected address. Sign-in was refused.",
+  exchange: "The sign-in service refused the sign-in. Please try again.",
+  state: "That sign-in link has expired. Please start again.",
+  token_malformed: "The sign-in service returned an unreadable token. Please try again.",
+  token_alg: "The sign-in service returned a token in an unsupported format.",
+  token_signature: "The sign-in token could not be verified. Sign-in was refused.",
+  token_issuer: "The sign-in token was issued by an unexpected party. Sign-in was refused.",
+  token_audience: "The sign-in token was not issued for this service. Sign-in was refused.",
+  token_expired: "The sign-in window expired. Please sign in again.",
+  token_nonce: "The sign-in response failed its replay check. Please sign in again.",
+  origin_not_allowed: "That site may not connect the assistant to your account.",
+};
+
+function authErrorText(reason: string): string {
+  return PLAIN_LANGUAGE[reason] ?? "Sign-in failed. Please try again.";
+}
+
+// Two tiers only: anonymous (public index) and member (both indexes).
+// Estate roles (mc_member, etc.) are identity claims, NOT access gates
+// here — any authenticated user is a member.
+export interface AuthConfig {
+  issuer: string;
+  clientId: string;
+  redirectUri: string;
+  sessionSecret: string;
+}
+
+function authConfig(env: any): AuthConfig | null {
+  const issuer = env.OIDC_ISSUER ?? "https://id.oimlsmart.org";
+  const clientId = env.OIDC_CLIENT_ID;
+  const redirectUri = env.OIDC_REDIRECT_URI ?? "https://ai.oimlsmart.org/auth/callback";
+  const sessionSecret = env.SESSION_SECRET;
+  if (!clientId || !sessionSecret) return null;
+  return { issuer, clientId, redirectUri, sessionSecret };
+}
+
+const redirectWithError = (reason: string) =>
+  new Response(null, {
+    status: 302,
+    headers: { location: `/?auth_error=${reason}&auth_msg=${encodeURIComponent(authErrorText(reason))}` },
+  });
+
+export async function handleLogin(env: any, req: Request): Promise<Response> {
+  const cfg = authConfig(env);
+  if (!cfg) return redirectWithError("not_configured");
+  // Bubble bridge (bubble.ts): the embedded panel's sign-in. The origin
+  // is validated NOW, at flow start, and bound to the state — the
+  // callback hands the session token to exactly that origin, never to
+  // wherever the request happens to come from later.
+  const url0 = new URL(req.url);
+  const bubbleMode = url0.searchParams.get("mode") === "bubble";
+  const bubbleOrigin = url0.searchParams.get("origin") ?? "";
+  if (bubbleMode && !isAllowedBubbleOrigin(bubbleOrigin)) return redirectWithError("origin_not_allowed");
+  try {
+    const meta = await discoverIssuer(cfg.issuer);
+    const state = randomToken();
+    const nonce = randomToken();
+    const pkce = await generatePkce();
+    await env.CACHE.put(
+      `oa:${state}`,
+      JSON.stringify({ nonce, verifier: pkce.verifier, ...(bubbleMode ? { mode: "bubble", origin: bubbleOrigin } : {}) }),
+      {
+        expirationTtl: 600,
+      },
+    );
+    const url = buildAuthorizationUrl(meta, {
+      clientId: cfg.clientId,
+      redirectUri: cfg.redirectUri,
+      scopes: "openid profile email roles",
+      state,
+      nonce,
+      codeChallenge: pkce.challenge,
+    });
+    return new Response(null, { status: 302, headers: { location: url } });
+  } catch (e) {
+    return redirectWithError(e instanceof OidcError ? e.reason : "discovery");
+  }
+}
+
+export async function handleCallback(env: any, req: Request): Promise<Response> {
+  const cfg = authConfig(env);
+  if (!cfg) return redirectWithError("not_configured");
+  const url = new URL(req.url);
+  const opError = url.searchParams.get("error");
+  if (opError) {
+    // the OP redirected back with its own failure (user denied consent,
+    // session expired at the OP, …) — fail closed, in plain language
+    const msg =
+      opError === "access_denied"
+        ? "Sign-in was cancelled."
+        : opError === "temporarily_unavailable"
+          ? "The sign-in service is busy. Please try again in a moment."
+          : "The sign-in service reported a problem. Please try again.";
+    return new Response(null, {
+      status: 302,
+      headers: { location: `/?auth_error=${encodeURIComponent(opError)}&auth_msg=${encodeURIComponent(msg)}` },
+    });
+  }
+  const code = url.searchParams.get("code") ?? "";
+  const state = url.searchParams.get("state") ?? "";
+  if (!code || !state) return redirectWithError("state");
+
+  const stored = await env.CACHE.get(`oa:${state}`, "json");
+  if (!stored) return redirectWithError("state");
+  // one-time: the state is consumed whether or not the exchange succeeds
+  await env.CACHE.delete(`oa:${state}`);
+
+  try {
+    const meta = await discoverIssuer(cfg.issuer);
+    const token = await exchangeCode(meta, {
+      clientId: cfg.clientId,
+      clientSecret: env.OIDC_CLIENT_SECRET,
+      code,
+      redirectUri: cfg.redirectUri,
+      codeVerifier: stored.verifier,
+    });
+    const claims = await validateIdToken(token.id_token, {
+      issuer: cfg.issuer,
+      clientId: cfg.clientId,
+      nonce: stored.nonce,
+      jwksUri: meta.jwks_uri,
+    });
+    const roles = Array.isArray(claims.roles) ? claims.roles.map(String) : [];
+    // `picture` is a userinfo claim on this OP (the ID token carries the
+    // profile contract only) — fall back to userinfo, sub-checked, when
+    // the token happens to omit it
+    let picture = typeof claims.picture === "string" ? claims.picture : undefined;
+    if (!picture && typeof token.access_token === "string") {
+      const ui = await fetchUserinfo(meta, token.access_token);
+      if (ui.sub === claims.sub && typeof ui.picture === "string" && ui.picture) picture = ui.picture;
+    }
+    const sessionClaims = {
+      sub: claims.sub,
+      name: typeof claims.name === "string" ? claims.name : undefined,
+      email: typeof claims.email === "string" ? claims.email : undefined,
+      picture,
+      roles,
+    };
+    // Mint ONCE — the cookie and the bubble's Bearer carry the same
+    // session token, so the live-data window (TODO.ai-platform/03) keyed
+    // off it holds for both presentations.
+    const session = await mintSessionToken(cfg.sessionSecret, sessionClaims);
+    const cookie = sessionCookieFromToken(session.token);
+    // TODO.ai-platform/03: retain the OP access token for the session's
+    // exchange window (the "my account" live-data delegation exchanges
+    // it per the identity service's RFC 8693 §9b) — KV only, TTL = the
+    // OP token's own life, never D1, never past the window.
+    if (typeof token.access_token === "string" && typeof token.expires_in === "number") {
+      await retainOpAccessToken(env, session.token, token.access_token, token.expires_in);
+    }
+    // Bubble bridge: hand the session to the embedded panel as a Bearer
+    // token via the confirm page — postMessage to the validated origin
+    // ONLY, and only on the user's explicit click (bubble.ts). The
+    // cookie still sets, so ai.oimlsmart.org itself is signed in too.
+    if (stored.mode === "bubble" && typeof stored.origin === "string" && isAllowedBubbleOrigin(stored.origin)) {
+      return new Response(
+        bubbleConfirmPage({
+          name: sessionClaims.name ?? sessionClaims.email ?? "member",
+          origin: stored.origin,
+          token: session.token,
+          expiresAt: session.expiresAt,
+        }),
+        { status: 200, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "set-cookie": cookie } },
+      );
+    }
+    return new Response(null, { status: 302, headers: { location: "/", "set-cookie": cookie } });
+  } catch (e) {
+    if (e instanceof OidcError) console.error("auth callback:", e.reason, "—", e.message.slice(0, 200));
+    return redirectWithError(e instanceof OidcError ? e.reason : "exchange");
+  }
+}
+
+export async function sessionFrom(req: Request, env: any): Promise<SessionClaims | null> {
+  return readSession(req, authConfig(env)?.sessionSecret);
+}
+
+export async function handleMe(env: any, req: Request): Promise<Response> {
+  const cfg = authConfig(env);
+  const session = cfg ? await readSession(req, cfg.sessionSecret) : null;
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  // sliding renewal: a session older than a day re-mints on sight, so
+  // active users never hit the 7-day wall mid-conversation
+  if (session && cfg && Date.now() - session.iat > 24 * 3600 * 1000) {
+    headers["set-cookie"] = await mintSessionCookie(cfg.sessionSecret, {
+      sub: session.sub,
+      name: session.name,
+      email: session.email,
+      picture: session.picture,
+      roles: session.roles,
+    });
+  }
+  return new Response(
+    JSON.stringify({
+      authenticated: !!session,
+      name: session?.name ?? null,
+      email: session?.email ?? null,
+      picture: session?.picture ?? null,
+      roles: session?.roles ?? [],
+      tier: session ? "member" : "anon",
+      sign_in_available: !!cfg,
+    }),
+    { headers },
+  );
+}
+
+export async function handleLogout(env: any, req: Request): Promise<Response> {
+  const cfg = authConfig(env);
+  const headers: Record<string, string> = { "set-cookie": clearSessionCookie() };
+  // The live-data window closes WITH the session (TODO.ai-platform/03 —
+  // deliberately, never by the TTL alone).
+  const presented = rawSessionToken(req);
+  if (presented) await dropOpAccessToken(env, presented);
+  if (cfg) {
+    try {
+      const meta = await discoverIssuer(cfg.issuer);
+      const end = buildEndSessionUrl(meta, {
+        clientId: cfg.clientId,
+        postLogoutRedirectUri: env.OIDC_REDIRECT_URI ?? "https://ai.oimlsmart.org/",
+      });
+      if (end) {
+        headers.location = end;
+        return new Response(null, { status: 302, headers });
+      }
+    } catch {
+      // OP-side logout is best-effort; the local session is already cleared
+    }
+  }
+  headers.location = "/";
+  return new Response(null, { status: 302, headers });
+}

package/workers/worker_public/src/bubble.ts

@@ -0,0 +1,111 @@
+// The bubble bridge (TODO.ai-platform/01 in the smart repo): the
+// assistant panel the shared chrome (@oimlsmart/site-shell's AiBubble)
+// embeds in every estate property cannot ride the rag_session cookie —
+// SameSite=Lax never crosses origins on fetch, and the estate bans
+// shared-domain cookies (the SSO doctrine, identity guide §8a: every
+// property keeps its OWN session, established by its own OP round-trip).
+//
+// The bridge: the panel opens /auth/login?mode=bubble&origin=<its own
+// origin> in a popup. The standard OIDC code+PKCE dance runs unchanged
+// (the OP session makes it one click); the callback then renders a
+// CONFIRM page — never auto-sends — that postMessages the session token
+// (the same HMAC-signed payload the cookie carries) to the requesting
+// origin only. The panel holds the token in memory (sessionStorage
+// survives reloads) and calls the API with `Authorization: Bearer`.
+// The token is the service's OWN session artifact — it can act on this
+// service only, never on the OP or other properties.
+
+/** The origins a bubble may ride from: the estate pattern (the same rule
+ *  corsHeaders applies) plus localhost for the local dev posture. */
+export function isAllowedBubbleOrigin(origin: string): boolean {
+  if (origin === "https://oimlsmart.org") return true;
+  if (/^https:\/\/[a-z0-9-]+(\.[a-z0-9-]+)*\.oimlsmart\.org$/.test(origin)) return true;
+  if (/^http:\/\/localhost(:\d{1,5})?$/.test(origin)) return true;
+  if (/^http:\/\/127\.0\.0\.1(:\d{1,5})?$/.test(origin)) return true;
+  return false;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/** The confirm page the callback renders in bubble mode. Static inline
+ *  HTML+JS, everything escaped, targetOrigin = the validated origin
+ *  (never "*"). The token leaves ONLY on the user's explicit Continue —
+ *  a popup the user never asked for (a page opening it under the OP's
+ *  SSO session) shows the request and stops here. */
+export function bubbleConfirmPage(opts: { name: string; origin: string; token: string; expiresAt: number }): string {
+  const who = escapeHtml(opts.name);
+  const host = escapeHtml(new URL(opts.origin).host);
+  // JSON embedded in a <script> block: escape `<` so a claim value can
+  // never close the element early (</script> breakout).
+  const jsSafe = (v: unknown) => JSON.stringify(v).replace(/</g, "\\u003c");
+  const payload = jsSafe({
+    type: "oimlsmart-ai-session",
+    token: opts.token,
+    name: opts.name,
+    expiresAt: opts.expiresAt,
+  });
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex" />
+<title>OIML SMART AI — sign in</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font-family: ui-sans-serif, system-ui, sans-serif; margin: 0; padding: 2rem 1.25rem;
+         background: #faf6ee; color: #0a1628; line-height: 1.5; }
+  main { max-width: 26rem; margin: 0 auto; }
+  h1 { font-size: 1.15rem; margin: 0 0 0.75rem; }
+  p { margin: 0 0 1rem; font-size: 0.925rem; }
+  .who { font-weight: 600; }
+  .row { display: flex; gap: 0.75rem; margin-top: 1.25rem; }
+  button { flex: 1; min-height: 44px; font: inherit; font-weight: 600; border-radius: 6px; cursor: pointer; }
+  .go { background: #004996; color: #fff; border: 1px solid #004996; }
+  .no { background: transparent; color: inherit; border: 1px solid #ddd2bd; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #0a1628; color: #f5efe4; }
+    .go { background: #89b4ef; color: #001230; border-color: #89b4ef; }
+    .no { border-color: #1f3357; }
+  }
+</style>
+</head>
+<body>
+<main>
+  <h1>Continue to the OIML SMART AI assistant?</h1>
+  <p>Signed in as <span class="who">${who}</span>. The page at <span class="who">${host}</span>
+     asked to connect the assistant to your account, so your conversations sync there.</p>
+  <p>The assistant can read the public OIML corpus and your own assistant conversations — nothing else.</p>
+  <div class="row">
+    <button type="button" class="no" id="cancel">Cancel</button>
+    <button type="button" class="go" id="go">Continue</button>
+  </div>
+  <p id="done" hidden>You can close this window.</p>
+</main>
+<script>
+  var TARGET = ${jsSafe(opts.origin)};
+  var PAYLOAD = ${payload};
+  var done = document.getElementById("done");
+  document.getElementById("cancel").addEventListener("click", function () { window.close(); done.hidden = false; });
+  document.getElementById("go").addEventListener("click", function () {
+    if (window.opener) {
+      window.opener.postMessage(PAYLOAD, TARGET);
+      window.close();
+    }
+    done.hidden = false;
+  });
+  if (!window.opener) {
+    document.querySelector(".row").hidden = true;
+    document.querySelector("h1").textContent = "Signed in.";
+    done.hidden = false;
+  }
+</script>
+</body>
+</html>`;
+}

package/workers/worker_public/src/completion.ts

@@ -0,0 +1,75 @@
+// Contract completion (MECE: ask.ts orchestrates, this module owns the
+// two post-generation completions). Both heal the same gap — the answer
+// references normative objects that contractV2 did not (or could not)
+// resolve into blocks — using the producer's own payloads:
+//
+//   table completion: the answer presents a numeric value from a table
+//     in the answer's document family → resolve and attach that table
+//   figure completion (#172): the model names figure units in PROSE as
+//     often as in [[u:…]] tokens, and token refs whose unit wasn't in
+//     the used passages drop — either way the answer shows no figure
+//     while the payload and asset exist; every u:fig mention in the
+//     final text (tokenized or not) resolves from D1
+//
+// Additive throughout: any failure returns what it has.
+import type { StoreQuery } from "./ports/store.ts";
+import { resolveBlocks, type ResolvedBlock } from "./refs.ts";
+import type { Hit } from "./pipeline.ts";
+
+export async function completeTables(
+  db: StoreQuery,
+  answer: string,
+  used: Hit[],
+): Promise<ResolvedBlock[]> {
+  const blocks: ResolvedBlock[] = [];
+  try {
+    const answerNums = new Set((answer.match(/\d[\d ,.]{1,8}\d/g) ?? []).map((x) => x.replace(/[ ,.]/g, "")));
+    if (!answerNums.size) return blocks;
+    // match by docidentifier (the chunks and unit_payloads use different
+    // doc_id schemes — 'dirty:r60-1-2006-eng' vs 'mko:oiml-r-60-1' — but
+    // both carry the publication name)
+    const fams = [...new Set(used.map((h) => h.metadata.docidentifier).filter(Boolean))].slice(0, 3);
+    for (const fam of fams) {
+      const base = String(fam).replace(/\s*\([A-Z]\)\s*$/, "").split(":")[0].trim();
+      const rows = await db
+        .prepare("SELECT unit_id, payload FROM unit_payloads WHERE type = 'table' AND docidentifier LIKE ?1 LIMIT 8")
+        .bind(`%${base}%`)
+        .all<{ unit_id: string; payload: string }>();
+      for (const r of rows.results ?? []) {
+        const tableNums = new Set((String(r.payload).match(/\d[\d ,.]{1,8}\d/g) ?? []).map((x) => x.replace(/[ ,.]/g, "")));
+        let hits = 0;
+        for (const n of answerNums) if (tableNums.has(n)) hits++;
+        if (hits >= 1) {
+          const resolved = await resolveBlocks(db, [r.unit_id]);
+          blocks.push(...resolved);
+          console.log("contract D1 completion: table", r.unit_id, "in", base, "—", hits, "matching values");
+          break;
+        }
+      }
+      if (blocks.length) break;
+    }
+  } catch {
+    // additive; primary results stand
+  }
+  return blocks;
+}
+
+export async function completeFigures(
+  db: StoreQuery,
+  answer: string,
+  alreadyAttached: ResolvedBlock[],
+): Promise<ResolvedBlock[]> {
+  // the model names figures BOTH ways: unit ids (u:fig-3) and bare
+  // producer anchors (fig-2a of D 36) — collect both forms; bare
+  // anchors get the unit prefix and D1 resolution drops every candidate
+  // that is not a real unit (a bare mention can never fabricate a block)
+  const unitForm = (answer.match(/u:fig[\w.-]*/g) ?? []).map((x) => x.replace(/[.,;:)]+$/, ""));
+  const bareForm = (answer.match(/\bfig-[\w.-]+\b/g) ?? []).map((x) => x.replace(/[.,;:)]+$/, ""));
+  const mentioned = [...new Set([...unitForm, ...bareForm.map((x) => (x.startsWith("u:") ? x : "u:" + x))])].slice(0, 6);
+  const have = new Set(alreadyAttached.map((b) => b.unit_id));
+  const missing = mentioned.filter((id) => !have.has(id));
+  if (!missing.length) return [];
+  const figs = await resolveBlocks(db, missing);
+  if (figs.length) console.log("figure completion:", figs.map((b) => b.unit_id).join(", "), "attached from D1");
+  return figs;
+}

package/workers/worker_public/src/config.ts

@@ -0,0 +1,238 @@
+import { P } from "./profile.ts";
+
+export const MODELS = {
+  embed: "@cf/qwen/qwen3-embedding-0.6b",  rerank: "@cf/baai/bge-reranker-base",
+  // ANSWER MODEL (all tiers, user decision 2026-08-29): glm-5.3-flash —
+  // natively multimodal (vision-unified contract), GLM family, flash tier.
+  // Vision image-parts land with answer contract v2; text answers work now.
+  anon: "@cf/zai-org/glm-5.3-flash",
+  member: "@cf/zai-org/glm-5.3-flash",
+  // hot-path understanding/summarize stays on the cheap Qwen (cost-first lane)
+  understand: "@cf/qwen/qwen3-30b-a3b-fp8",
+  // generation fallback when the answer model is unavailable
+  fallback: "@cf/qwen/qwen3-30b-a3b-fp8",
+  grader: "@cf/deepseek-ai/deepseek-v4-flash-0731", // CRAG grader + judges (unsuffixed slug was retired → silent 5018s)
+  // contextual enrichment is the QUALITY-FIRST lane (one-time spend over
+  // the corpus, its quality persists into every future retrieval)
+  enrich: "@cf/deepseek-ai/deepseek-v4-pro-0813",
+  // final-tier listwise reranker for hard/member queries (cascade:
+  // cross-encoder prunes, listwise orders jointly)
+  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",
+} as const;
+
+export const LIMITS = {
+  // input sizes: generous — real questions can be long (pasted scenarios,
+  // multi-part asks). The context BUDGET is the real governor of what the
+  // model sees; these caps only bound abuse.
+  maxInputChars: 8000,
+  maxOutputTokens: 3072, // qwen3-30b-a3b always reasons; 768 starved the answer entirely
+  retrieveK: 50, // Vectorize caps topK at 50 when returnMetadata=all
+  rerankKeep: 10, // 8 crowded out dirty-lane goldens once 3k enriched MKO clean chunks entered the pool
+  cacheTtlSec: 6 * 3600,
+  // context-window budget (estimated tokens) for the assembled prompt —
+  // system + summary + history slice + passages must fit or the model
+  // request fails. 16k is conservative for the qwen3 tier (pre-budget
+  // traffic at ~12k+ never hit a length error); raise via INPUT_TOKEN_BUDGET
+  // after watching logs for length rejections
+  inputTokenBudget: 16000,
+  maxPassageTokens: 900, // per-passage cap (clause chunks with tables can be huge)
+} as const;
+
+/** Tuned retrieval thresholds — every number the pipeline steers by.
+ *  Each carries the measurement that justifies it; changing one without
+ *  re-running the gates (golden ×3 + annealment ×6) is a guess. */
+export const THRESHOLDS = {
+  /** HyDE candidate score discount — hypothetical-answer vectors match
+   *  differently than question vectors; 0.7 keeps them competitive
+   *  without letting a bad hypothetical outrank the real query. */
+  hydeDiscount: 0.7,
+  /** Graph-lane candidate discount — graph-filtered chunks enter the
+   *  pool below the primary dense lane; they must earn their window
+   *  slot under the cross-encoder, not by graph membership alone. */
+  graphLaneDiscount: 0.75,
+  /** Concept-graph candidate discount — same rationale as the graph
+   *  lane: definitional content enters discounted. */
+  conceptGraphDiscount: 0.75,
+  /** Multi-hop sub-query discount — sub-question hits are unioned, not
+   *  RRF-fused; the discount keeps them from dominating the primary
+   *  ranking on their first appearance. */
+  subQueryDiscount: 0.8,
+  /** Federated-ISO discount — the public corpus answers by default;
+   *  internal ISO passages compete but don't preempt. */
+  federateDiscount: 0.95,
+  /** Standard-reference nudge (L5): when the question asks about an
+   *  invoked ISO/IEC standard, chunks that CARRY such a citation (their
+   *  text contains an ISO/IEC identifier) get a spread-scaled boost —
+   *  the citing clause is the answer, and generic family prose otherwise
+   *  fills the window (measured: l5a-iso-humidity flips ~1/6 runs). */
+  stdRefNudgeSpread: 0.35,
+  /** Edition cover — the score multiplier for current-edition chunks the
+   *  cover stage fetches when a pool holds ONLY stale editions of a
+   *  document. Just under the top: the point is REPRESENTATION (so
+   *  edition steering can demote the stale siblings and diversity keeps
+   *  the current overview), not free ranking. */
+  editionCoverDiscount: 0.9,
+  /** Overview-chunk demotion — overview chunks repeat title/doctype
+   *  boilerplate and embed strongly for name-like queries, crowding
+   *  clause chunks out of the rerank window. */
+  overviewDemotion: 0.85,
+  /** Glossary-link cosine floor — below this the dense match to a
+   *  defined term is noise, not a candidate. Calibrated on the
+   *  drifting→durability probe (durability-def 0.542, noise ~0.3). */
+  glossaryCosineFloor: 0.5,
+  /** Exact-term nudge (spread multiplier) — clause chunks whose head IS
+   *  the asked-for term get a decisive nudge because publication headers
+   *  contain the title words and the reranker alone is unreliable there;
+   *  >1 so it dominates the spread, unlike the additive steering boosts. */
+  termNudgeSpread: 1.5,
+  /** Concept-steering rerank boost (spread fraction) — the vocabulary
+   *  link's defining families get the edition-steering boost idiom.
+   *  0.15 is enough to lift in-family content past the cross-encoder's
+   *  vocabulary bias without overriding genuine relevance. */
+  conceptSteerSpread: 0.15,
+  /** Cross-publication recency boost (spread fraction) — a
+   *  current-edition publication ranks over stale ones; composed with
+   *  the family-relative demotion below. */
+  crossPubRecencySpread: 0.1,
+  /** Family-relative edition demotion (spread fraction) — superseded
+   *  editions are demoted when a newer edition of the same publication
+   *  is in the pool; a sibling one revision back still competes. */
+  familyDemoteSpread: 0.4,
+  /** Relevance-floored window — passages below this fraction of the
+   *  top rerank score leave the window (the evidence-budget principle;
+   *  structural units are exempt). */
+  windowFloorFraction: 0.25,
+  /** Small-to-big parent fetch discount — the parent clause enters at
+   *  a discount because it's supplementary grounding, not the answer. */
+  smallToBigDiscount: 0.7,
+  /** Section-descent child discount — children fetched from a ranked
+   *  depth-1 summary enter discounted. */
+  sectionDescentDiscount: 0.8,
+  /** History budget share — the fraction of the context budget the
+   *  conversation slice may consume; older turns overflow into the
+   *  compacted summary instead of starving the passages. */
+  historyBudgetShare: 0.3,
+} as const;
+
+/** Process-expansion — appended to process-intent queries; publisher
+ *  vocabulary from the profile (read at request time — see profile.ts). */
+export function processExpansion(): string {
+  return P().retrieval.process_expansion;
+}
+
+/** Per-deployment model override: <ROLE>_MODEL (e.g. UNDERSTAND_MODEL)
+ *  replaces the pinned default for that role. Ops lever for A/B-ing a
+ *  role's model without a code change; absent/invalid = the default. */
+export function roleModel(env: any, role: keyof typeof MODELS): string {
+  const ov = env[`${role.toUpperCase()}_MODEL`];
+  return typeof ov === "string" && ov.startsWith("@cf/") ? ov : MODELS[role];
+}
+
+const EFFORTS = new Set(["low", "medium", "high", "max"]);
+
+/** Per-deployment effort override for the answer lane (ANSWER_EFFORT).
+ *  The effort–accuracy curve is front-loaded (DeepSeek-V4.1-Flash report,
+ *  Fig. 9): serving pins "low" for latency, and any move up must be
+ *  measured on the golden set — this lever makes that measurable live,
+ *  same pattern as roleModel. Absent/invalid = "low". */
+export function answerEffort(env: any): string {
+  const v = env?.ANSWER_EFFORT;
+  return typeof v === "string" && EFFORTS.has(v) ? v : "low";
+}
+
+/** Per-request effort for the answer lane (the user-facing depth toggle).
+ *  The vocabulary is validated; elevated efforts (medium+) are a member
+ *  lane — same cost rule as research — and degrade to the deployment
+ *  lever for anonymous or silent requests. */
+/** Elevated effort reasons longer — the output budget must grow with it
+ *  or reasoning starves the content (the GLM-5 rule; measured
+ *  2026-09-12: medium at the flat 3072 budget scored 5/38 on the golden
+ *  set — empty answers — versus 37–38/38 at low). */
+export function effortBudget(effort: string): number {
+  if (effort === "medium") return LIMITS.maxOutputTokens * 2;
+  if (effort === "high" || effort === "max") return LIMITS.maxOutputTokens * 4;
+  return LIMITS.maxOutputTokens;
+}
+
+export function requestEffort(env: any, session: unknown, requested: unknown): string {
+  if (typeof requested !== "string" || !EFFORTS.has(requested)) return answerEffort(env);
+  if (requested === "low") return requested;
+  return session ? requested : answerEffort(env);
+}
+
+/** The corpus catalog — single source for /api/datasets, the assistant's
+ *  self-description, and per-corpus model guidance. `session: true`
+ *  datasets are enabled for signed-in members (federated via the internal
+ *  service binding). `note` (optional) is injected into the system prompt
+ *  when passages from this corpus are present — corpus behavior travels
+ *  with the dataset, not with pipeline code. */
+export interface Dataset {
+  id: string;
+  label: string;
+  description: string;
+  /** member-session gated (federated via the internal service binding) */
+  session?: boolean;
+  /** the estate permission (a role code set in the publisher's
+   *  identity provider) the session must carry for a session-gated
+   *  dataset — membership alone is not the bar */
+  permission?: string;
+  /** the corpora this dataset searches (profile datasets.yaml) — the
+   *  engine maps no publisher names */
+  corpora?: string[];
+  note?: string;
+}
+
+// The catalog is publisher data (profile/datasets.yaml, codegen into
+// profile.gen.ts) — the engine ships no publisher facts
+export function DATASETS(): readonly Dataset[] {
+  return P().datasets;
+}
+
+/** The estate permission gate: a session-gated dataset requires BOTH
+ *  membership and the named permission (a role code the account carries
+ *  in id.oimlsmart.org). Enforcement is server-side — the UI's lock is
+ *  cosmetic; /api/ask federation and the scope intersect here too. */
+export function hasPermission(session: unknown, code: string): boolean {
+  const roles = (session as { roles?: unknown } | null)?.roles;
+  return Array.isArray(roles) && roles.map(String).includes(code);
+}
+
+export function datasetAllowed(d: Dataset, session: unknown): boolean {
+  if (!d.session) return true;
+  if (!session) return false;
+  return hasPermission(session, d.permission ?? "ai-preview");
+}
+
+export function datasetsFor(session: unknown): unknown[] {
+  return DATASETS().map((d) => ({
+    id: d.id,
+    label: d.label,
+    description: d.description,
+    enabled: datasetAllowed(d, session),
+    ...(d.session
+      ? { requires: `the ${d.permission ?? "ai-preview"} permission (id.oimlsmart.org)`, authenticated: !!session }
+      : {}),
+  }));
+}
+
+/** Empty-state starter questions, served by /api/datasets — UI content
+ *  comes from the API, never hardcoded in the client. */
+export function SUGGESTIONS(): string[] {
+  return [...P().ui.suggestions];
+}
+
+export function num(env: Record<string, unknown>, key: string, fallback: number): number {
+  const v = Number(env[key]);
+  return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+export function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export async function sha256Hex(s: string): Promise<string> {
+  const d = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s));
+  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}