@konneal/engine 0.1.0

package/scripts/gen_profile.mjs

@@ -0,0 +1,33 @@
+// Profile codegen (multi-SDO): profile/*.yaml → the compile-time profile
+// modules (workers + site). The generated files are committed; the drift
+// test (tests/profile.test.ts) fails CI when someone edits one side
+// without regenerating — the same discipline as the estate's gen:data.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import YAML from "yaml";
+
+const HEADER =
+  "// GENERATED from profile/*.yaml — regenerate: node scripts/gen_profile.mjs\n" +
+  "// (never edit; the drift test compares this file to the sources)\n";
+
+const render = (profileDir = "profile") => {
+  const read = (f) => YAML.parse(readFileSync(`${profileDir}/${f}`, "utf8"));
+  const publisher = read("publisher.yaml");
+  const datasets = read("datasets.yaml").datasets;
+  const corpora = read("corpora.yaml");
+  const sources = read("sources.yaml");
+  const ui = read("ui.yaml");
+  const retrieval = read("retrieval.yaml");
+  const prompts = read("prompts.yaml");
+  const body = JSON.stringify({ publisher, datasets, corpora, sources, ui, retrieval, prompts }, null, 2);
+  return `${HEADER}export const PROFILE = ${body} as const;\n`;
+};
+
+if (process.argv[1].endsWith("gen_profile.mjs") && !process.env.PROFILE_RENDER_ONLY) {
+  for (const out of ["workers/worker_public/src/profile.gen.ts", "site/src/profile.gen.ts"]) {
+    if (out.startsWith("site/") && !existsSync("site")) continue; // engine repo: no site plane
+    writeFileSync(out, render());
+    console.log(`generated ${out}`);
+  }
+}
+
+export { render };

package/workers/shared/ai.ts

@@ -0,0 +1,21 @@
+// Shared AI helper: embed with retry.
+const EMBED_MODEL = "@cf/qwen/qwen3-embedding-0.6b";
+
+export async function embed(ai: any, text: string): Promise<number[]> {
+  const shapes = [{ text: [text] }, { input: { input: [text] } }];
+  for (let attempt = 0; attempt < 3; attempt++) {
+    for (const body of shapes) {
+      try {
+        const res: any = await ai.run(EMBED_MODEL, body);
+        const d = res?.data ?? res?.result?.data;
+        if (Array.isArray(d)) {
+          const first = d[0];
+          if (Array.isArray(first)) return first.map(Number);
+          if (first?.embedding) return first.embedding.map(Number);
+        }
+        if (Array.isArray(res?.embedding)) return res.embedding.map(Number);
+      } catch { /* next shape */ }
+    }
+  }
+  throw new Error("embedding failed");
+}

package/workers/shared/auth.ts

@@ -0,0 +1,16 @@
+// Shared auth: session validation + role constants used by both workers.
+import { readSession } from "./session";
+
+// Two tiers: anonymous (public) and member (both). No role gates.
+
+export function authConfig(env: any) {
+  const sessionSecret = env.SESSION_SECRET;
+  if (!sessionSecret) return null;
+  return { sessionSecret };
+}
+
+export async function sessionFrom(req: Request, env: any) {
+  const cfg = authConfig(env);
+  if (!cfg) return null;
+  return readSession(req, cfg.sessionSecret);
+}

package/workers/shared/chunk.ts

@@ -0,0 +1,108 @@
+// The chunk wire contract — the shape of every Vectorize vector's
+// metadata, shared by both workers. The CANONICAL producer definition is
+// ingest/vector_adapter.py (ChunkMetaModel, pydantic); this module is its
+// serving-side mirror, and tests/chunkmeta.test.ts fails when either side
+// drifts. Change a field → change vector_adapter.py and this file in the
+// same commit.
+
+export interface ChunkMeta {
+  doc_id: string;
+  docidentifier: string;
+  doctype: string;
+  doc_number: string;
+  edition: string;
+  language: string;
+  clause_anchor: string;
+  clause_title: string;
+  tier: string;
+  corpus: string;
+  text_ref: string;
+  status?: string;
+  superseded_by?: string;
+  /** answer contract v2: typed MKO units carry their unit id + block type */
+  unit_id?: string;
+  block?: string;
+  unit_hash?: string;
+  producer?: string;
+  source_lane?: string;
+  linked_clause?: string;
+  linked_document?: string;
+  /** document order (metanorma-document#56): reading order is a sort */
+  ordinal?: number;
+  /** the model plane (retrieval-export derivation): unit versioning and
+   *  identity, canonical per primmel/primmel-ts#65 */
+  model_version?: string;
+  model_node?: string;
+  model_kind?: string;
+  standard?: string;
+  /** section-summary unit (FABLE multi-granularity, arXiv:2601.18116): a
+   *  depth-1 clause summary vector — a navigation node whose children
+   *  (child_anchors CSV) are quotable leaf clauses. The corpus's real
+   *  chunks start at depth 2, so these nodes cannot collide with them. */
+  section_summary?: string;
+  child_anchors?: string;
+  /** contextual enrichment (one-time corpus spend, KV-cached) */
+  ctx?: string;
+  /** the capped chunk text riding inside vector metadata */
+  chunk_text?: string;
+}
+
+export interface Hit {
+  id: string;
+  score: number;
+  rerank_score?: number;
+  metadata: ChunkMeta;
+  text: string;
+}
+
+// Runtime manifest of ChunkMeta's keys — the bridge the contract test
+// reads (interfaces erase at runtime; this array does not).
+export const CHUNK_META_FIELDS = [
+  "doc_id",
+  "docidentifier",
+  "doctype",
+  "doc_number",
+  "edition",
+  "language",
+  "clause_anchor",
+  "clause_title",
+  "tier",
+  "corpus",
+  "text_ref",
+  "status",
+  "superseded_by",
+  "unit_id",
+  "block",
+  "unit_hash",
+  "producer",
+  "source_lane",
+  "linked_clause",
+  "linked_document",
+  "ordinal",
+  "model_version",
+  "model_node",
+  "model_kind",
+  "standard",
+  "section_summary",
+  "child_anchors",
+  "ctx",
+  "chunk_text",
+] as const;
+
+/** Vectorize match list → Hit list (the wire conversion both workers
+ *  perform; one definition, like the type above it). */
+export function toHits(matches: any[]): Hit[] {
+  return matches.map((m) => ({
+    id: m.id,
+    score: m.score,
+    metadata: (m.metadata ?? {}) as ChunkMeta,
+    text: (m.metadata?.chunk_text as string) ?? "",
+  }));
+}
+
+// Compile-time: the manifest and the interface are the same set — both
+// directions. A mismatch fails typecheck here, not at the wire.
+type AssertNever<T extends never> = T;
+type ManifestField = (typeof CHUNK_META_FIELDS)[number];
+export type _manifestMissingFromInterface = AssertNever<Exclude<ManifestField, keyof ChunkMeta>>;
+export type _interfaceMissingFromManifest = AssertNever<Exclude<keyof ChunkMeta, ManifestField>>;

package/workers/shared/oidc.ts

@@ -0,0 +1,312 @@
+// OIDC relying-party half of the Authorization Code + PKCE flow,
+// hand-rolled on WebCrypto + fetch. Ported from the estate's reference
+// implementation (oimlsmart/smart packages/platform-server/src/oidc.ts)
+// per docs/identity-service.md — zero library dependencies by design.
+
+export type OidcFailureReason =
+  | 'not_configured'
+  | 'discovery'
+  | 'issuer_mismatch'
+  | 'exchange'
+  | 'state'
+  | 'token_malformed'
+  | 'token_alg'
+  | 'token_signature'
+  | 'token_issuer'
+  | 'token_audience'
+  | 'token_expired'
+  | 'token_nonce';
+
+export class OidcError extends Error {
+  constructor(readonly reason: OidcFailureReason, message: string) {
+    super(message);
+    this.name = "OidcError";
+  }
+}
+
+export interface OidcMetadata {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  jwks_uri: string;
+  end_session_endpoint?: string;
+  userinfo_endpoint?: string;
+}
+
+interface CachedMetadata {
+  metadata: OidcMetadata;
+  fetchedAt: number;
+}
+const metadataCache = new Map<string, CachedMetadata>();
+const METADATA_TTL_MS = 60 * 60 * 1000;
+
+export async function discoverIssuer(issuer: string): Promise<OidcMetadata> {
+  const cached = metadataCache.get(issuer);
+  if (cached && Date.now() - cached.fetchedAt < METADATA_TTL_MS) return cached.metadata;
+
+  const wellKnown = `${issuer.replace(/\/$/, "")}/.well-known/openid-configuration`;
+  let body: unknown;
+  try {
+    const res = await fetch(wellKnown);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    body = await res.json();
+  } catch (err) {
+    throw new OidcError("discovery", `could not fetch ${wellKnown}: ${(err as Error).message}`);
+  }
+  const meta = body as Partial<OidcMetadata>;
+  if (
+    typeof meta?.issuer !== "string" ||
+    typeof meta?.authorization_endpoint !== "string" ||
+    typeof meta?.token_endpoint !== "string" ||
+    typeof meta?.jwks_uri !== "string"
+  ) {
+    throw new OidcError("discovery", `the metadata at ${wellKnown} is incomplete`);
+  }
+  if (meta.issuer.replace(/\/$/, "") !== issuer.replace(/\/$/, "")) {
+    throw new OidcError("issuer_mismatch", `the metadata declares issuer ${meta.issuer}, not ${issuer}`);
+  }
+  const metadata: OidcMetadata = {
+    issuer: meta.issuer,
+    authorization_endpoint: meta.authorization_endpoint,
+    token_endpoint: meta.token_endpoint,
+    jwks_uri: meta.jwks_uri,
+    ...(typeof meta.end_session_endpoint === "string" ? { end_session_endpoint: meta.end_session_endpoint } : {}),
+    ...(typeof meta.userinfo_endpoint === "string" ? { userinfo_endpoint: meta.userinfo_endpoint } : {}),
+  };
+  metadataCache.set(issuer, { metadata, fetchedAt: Date.now() });
+  return metadata;
+}
+
+function base64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function base64urlDecode(s: string): Uint8Array {
+  const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice(0, (4 - (s.length % 4)) % 4);
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function randomToken(): string {
+  return base64url(crypto.getRandomValues(new Uint8Array(24)));
+}
+
+export interface PkcePair {
+  verifier: string;
+  challenge: string;
+}
+
+export async function generatePkce(): Promise<PkcePair> {
+  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64url(new Uint8Array(digest)) };
+}
+
+export function buildAuthorizationUrl(
+  metadata: OidcMetadata,
+  params: {
+    clientId: string;
+    redirectUri: string;
+    scopes: string;
+    state: string;
+    nonce: string;
+    codeChallenge: string;
+  },
+): string {
+  const url = new URL(metadata.authorization_endpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", params.clientId);
+  url.searchParams.set("redirect_uri", params.redirectUri);
+  url.searchParams.set("scope", params.scopes);
+  url.searchParams.set("state", params.state);
+  url.searchParams.set("nonce", params.nonce);
+  url.searchParams.set("code_challenge", params.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  return url.toString();
+}
+
+export interface OidcTokenResponse {
+  id_token: string;
+  access_token?: string;
+  token_type?: string;
+  expires_in?: number;
+}
+
+export async function exchangeCode(
+  metadata: OidcMetadata,
+  params: { clientId: string; clientSecret?: string; code: string; redirectUri: string; codeVerifier: string },
+): Promise<OidcTokenResponse> {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: params.code,
+    redirect_uri: params.redirectUri,
+    client_id: params.clientId,
+    code_verifier: params.codeVerifier,
+  });
+  const headers: Record<string, string> = { "content-type": "application/x-www-form-urlencoded" };
+  if (params.clientSecret) {
+    headers.authorization = `Basic ${btoa(`${encodeURIComponent(params.clientId)}:${encodeURIComponent(params.clientSecret)}`)}`;
+  }
+  let json: unknown;
+  try {
+    const res = await fetch(metadata.token_endpoint, { method: "POST", headers, body });
+    json = await res.json();
+    if (!res.ok) {
+      const err = (json as { error?: string; error_description?: string }) ?? {};
+      throw new Error(`HTTP ${res.status} ${err.error ?? ""} ${err.error_description ?? ""}`.trim());
+    }
+  } catch (err) {
+    throw new OidcError("exchange", `the token endpoint refused the exchange: ${(err as Error).message}`);
+  }
+  const token = json as Partial<OidcTokenResponse>;
+  if (typeof token?.id_token !== "string") {
+    throw new OidcError("exchange", "the token response carries no id_token");
+  }
+  return token as OidcTokenResponse;
+}
+
+interface Jwk {
+  kty: string;
+  kid?: string;
+  alg?: string;
+  use?: string;
+  n?: string;
+  e?: string;
+  x?: string;
+  y?: string;
+  crv?: string;
+}
+
+interface CachedJwks {
+  keys: Jwk[];
+  fetchedAt: number;
+}
+const jwksCache = new Map<string, CachedJwks>();
+const JWKS_TTL_MS = 60 * 60 * 1000;
+
+async function fetchJwks(jwksUri: string, force: boolean): Promise<Jwk[]> {
+  const cached = jwksCache.get(jwksUri);
+  if (!force && cached && Date.now() - cached.fetchedAt < JWKS_TTL_MS) return cached.keys;
+  let body: unknown;
+  try {
+    const res = await fetch(jwksUri);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    body = await res.json();
+  } catch (err) {
+    throw new OidcError("token_signature", `could not fetch the signing keys: ${(err as Error).message}`);
+  }
+  const keys = (body as { keys?: Jwk[] })?.keys;
+  if (!Array.isArray(keys)) {
+    throw new OidcError("token_signature", "the JWKS carries no keys array");
+  }
+  jwksCache.set(jwksUri, { keys, fetchedAt: Date.now() });
+  return keys;
+}
+
+export interface OidcIdTokenClaims {
+  iss: string;
+  sub: string;
+  aud: string | string[];
+  exp: number;
+  iat?: number;
+  nonce?: string;
+  azp?: string;
+  email?: string;
+  email_verified?: boolean;
+  name?: string;
+  roles?: string[];
+  groups?: string[];
+  org?: unknown;
+  [claim: string]: unknown;
+}
+
+const EXPIRY_LEEWAY_MS = 60_000;
+
+export async function validateIdToken(
+  idToken: string,
+  expectations: { issuer: string; clientId: string; nonce: string; jwksUri: string },
+): Promise<OidcIdTokenClaims> {
+  const parts = idToken.split(".");
+  if (parts.length !== 3) {
+    throw new OidcError("token_malformed", "the ID token is not a three-part JWT");
+  }
+  let header: { alg?: string; kid?: string };
+  let claims: OidcIdTokenClaims;
+  try {
+    header = JSON.parse(new TextDecoder().decode(base64urlDecode(parts[0])));
+    claims = JSON.parse(new TextDecoder().decode(base64urlDecode(parts[1]))) as OidcIdTokenClaims;
+  } catch {
+    throw new OidcError("token_malformed", "the ID token header/claims are not JSON");
+  }
+  if (header.alg !== "RS256" && header.alg !== "ES256") {
+    throw new OidcError("token_alg", `the ID token uses ${header.alg ?? "no declared algorithm"}`);
+  }
+
+  const signedContent = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+  const signature = base64urlDecode(parts[2]) as BufferSource;
+  let verified = false;
+  for (const force of [false, true]) {
+    const keys = await fetchJwks(expectations.jwksUri, force);
+    const candidates = keys.filter(
+      (k) => (!header.kid || k.kid === header.kid) && (header.alg === "RS256" ? k.kty === "RSA" : k.kty === "EC"),
+    );
+    for (const jwk of candidates) {
+      try {
+        const key = await crypto.subtle.importKey(
+          "jwk",
+          jwk as JsonWebKey,
+          header.alg === "RS256" ? { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" } : { name: "ECDSA", namedCurve: "P-256" },
+          false,
+          ["verify"],
+        );
+        verified = await crypto.subtle.verify(
+          header.alg === "RS256" ? { name: "RSASSA-PKCS1-v1_5" } : { name: "ECDSA", hash: "SHA-256" },
+          key,
+          signature,
+          signedContent,
+        );
+      } catch {
+        verified = false;
+      }
+      if (verified) break;
+    }
+    if (verified) break;
+  }
+  if (!verified) {
+    throw new OidcError("token_signature", "the ID token signature does not verify against the issuer's published keys");
+  }
+
+  if (claims.iss?.replace(/\/$/, "") !== expectations.issuer.replace(/\/$/, "")) {
+    throw new OidcError("token_issuer", "the ID token's issuer is not the configured issuer");
+  }
+  const audiences = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+  if (!audiences.includes(expectations.clientId)) {
+    throw new OidcError("token_audience", "the ID token was not issued for this application");
+  }
+  if (audiences.length > 1 && claims.azp && claims.azp !== expectations.clientId) {
+    throw new OidcError("token_audience", "the ID token's authorized party is not this application");
+  }
+  if (typeof claims.exp !== "number" || claims.exp * 1000 + EXPIRY_LEEWAY_MS < Date.now()) {
+    throw new OidcError("token_expired", "the ID token has expired");
+  }
+  if (claims.nonce !== expectations.nonce) {
+    throw new OidcError("token_nonce", "the ID token's nonce does not match the request");
+  }
+  return claims;
+}
+
+export function buildEndSessionUrl(
+  metadata: OidcMetadata,
+  params: { idTokenHint?: string | null; clientId: string; postLogoutRedirectUri: string },
+): string | null {
+  if (!metadata.end_session_endpoint) return null;
+  const url = new URL(metadata.end_session_endpoint);
+  if (params.idTokenHint) url.searchParams.set("id_token_hint", params.idTokenHint);
+  url.searchParams.set("client_id", params.clientId);
+  url.searchParams.set("post_logout_redirect_uri", params.postLogoutRedirectUri);
+  return url.toString();
+}

package/workers/shared/router.ts

@@ -0,0 +1,45 @@
+// The declarative router (shared by both workers — one HTTP idiom):
+// adding a route = adding an entry, never router modification. Each
+// entry declares its method, path pattern, and handler; matchRoute
+// dispatches by segment-exact match with :param capture and a trailing
+// * wildcard.
+
+export interface RouteContext {
+  env: any;
+  req: Request;
+  ctx: ExecutionContext;
+  url: URL;
+  path: string;
+  params: Record<string, string>;
+}
+
+export type RouteHandler = (c: RouteContext) => Promise<Response>;
+
+export interface Route {
+  method: string;
+  pattern: string; // "/api/conversations/:id/messages" — :name captures params
+  handler: RouteHandler;
+}
+
+export function matchRoute(routes: Route[], method: string, path: string): { route: Route; params: Record<string, string> } | null {
+  const segments = path.split("/").filter(Boolean);
+  for (const route of routes) {
+    if (route.method !== method && route.method !== "*") continue;
+    const patternSegs = route.pattern.split("/").filter(Boolean);
+    if (patternSegs.length !== segments.length && !patternSegs[patternSegs.length - 1]?.startsWith("*")) continue;
+    const params: Record<string, string> = {};
+    let matched = true;
+    for (let i = 0; i < patternSegs.length; i++) {
+      const ps = patternSegs[i];
+      if (ps.startsWith("*")) break; // wildcard matches rest
+      if (ps.startsWith(":")) {
+        params[ps.slice(1)] = segments[i];
+      } else if (ps !== segments[i]) {
+        matched = false;
+        break;
+      }
+    }
+    if (matched) return { route, params };
+  }
+  return null;
+}

package/workers/shared/session.ts

@@ -0,0 +1,104 @@
+// RAG's own session layer (the CANONICAL implementation — TODO.impl/16):
+// the OP's ID token is sign-in evidence, never a session
+// (docs/identity-service.md §5.5). We mint an HMAC-signed cookie with the
+// claims we act on; enforcement happens inside each worker. Both workers
+// import THIS module; worker_public/src/session.ts is a compat re-export.
+
+
+export interface SessionClaims {
+  sub: string;
+  name?: string;
+  email?: string;
+  /** OIDC picture claim (avatar URL) — present when the OP issues it */
+  picture?: string;
+  roles: string[];
+  iat: number;
+  exp: number;
+}
+
+export const SESSION_COOKIE = "rag_session";
+const SESSION_TTL_SEC = 7 * 24 * 3600;
+
+async function hmac(secret: string, data: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
+  return btoa(String.fromCharCode(...new Uint8Array(sig)))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export async function mintSessionToken(secret: string, claims: Omit<SessionClaims, "exp" | "iat">): Promise<{ token: string; expiresAt: number }> {
+  const full: SessionClaims = { ...claims, iat: Date.now(), exp: Date.now() + SESSION_TTL_SEC * 1000 };
+  const payload = btoa(JSON.stringify(full))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  const sig = await hmac(secret, payload);
+  return { token: `${payload}.${sig}`, expiresAt: full.exp };
+}
+
+export async function mintSessionCookie(secret: string, claims: Omit<SessionClaims, "exp" | "iat">): Promise<string> {
+  const { token } = await mintSessionToken(secret, claims);
+  return sessionCookieFromToken(token);
+}
+
+/** The Set-Cookie value for an already-minted session token (the sign-in
+ *  mints ONCE and both the cookie and the bubble Bearer carry it —
+ *  TODO.ai-platform/03's live-data window keys off the one token). */
+export function sessionCookieFromToken(token: string): string {
+  return `${SESSION_COOKIE}=${token}; Path=/; Max-Age=${SESSION_TTL_SEC}; HttpOnly; Secure; SameSite=Lax`;
+}
+
+function parseCookies(req: Request): Record<string, string> {
+  const out: Record<string, string> = {};
+  const header = req.headers.get("cookie") ?? "";
+  for (const part of header.split(";")) {
+    const i = part.indexOf("=");
+    if (i > 0) out[part.slice(0, i).trim()] = part.slice(i + 1).trim();
+  }
+  return out;
+}
+
+export async function readSession(req: Request, secret: string | undefined): Promise<SessionClaims | null> {
+  if (!secret) return null;
+  // The cookie is the same-origin posture; the Bearer form is the bubble
+  // bridge (bubble.ts) — the same signed payload, sent cross-origin by
+  // the embedded panel. Cookie first so a stale stored token never
+  // shadows a live cookie session on the ai property itself.
+  const raw = rawSessionToken(req);
+  if (!raw) return null;
+  const [payload, sig] = raw.split(".");
+  if (!payload || !sig) return null;
+  const expected = await hmac(secret, payload);
+  if (sig !== expected) return null;
+  try {
+    const b64 = payload.replace(/-/g, "+").replace(/_/g, "/") + "===".slice(0, (4 - (payload.length % 4)) % 4);
+    const claims = JSON.parse(atob(b64)) as SessionClaims;
+    if (typeof claims.sub !== "string" || typeof claims.exp !== "number") return null;
+    if (claims.exp + 60_000 < Date.now()) return null;
+    return claims;
+  } catch {
+    return null;
+  }
+}
+
+/** The raw session token as presented (the cookie wins the tie, exactly
+ *  as readSession) — the live-data window's KV key derives from it
+ *  (TODO.ai-platform/03; the key is the token's hash, never the token). */
+export function rawSessionToken(req: Request): string | null {
+  const raw =
+    parseCookies(req)[SESSION_COOKIE] ??
+    (req.headers.get("authorization") ?? "").match(/^Bearer\s+(.+)$/i)?.[1]?.trim();
+  return raw || null;
+}
+
+export function clearSessionCookie(): string {
+  return `${SESSION_COOKIE}=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`;
+}