@konneal/engine 0.2.33 → 0.2.35

package/workers/worker_public/src/context.ts

@@ -12,6 +12,30 @@
 // answer depends on the declaration, not just the query) and is never
 // written into them — the caches stay context-clean by construction.
 
+/** One act the declared entity's lifecycle machine offers at its current
+ *  state, FOR THE DECLARING USER'S ROLE (the platform filters before
+ *  publishing; the wire is advisory — the platform re-validates every
+ *  proposed act authoritatively on the way back). */
+export interface MachineAct {
+  /** the machine's own action id (the model's vocabulary) */
+  action: string;
+  /** the state the act lands the entity on */
+  to: string;
+  /** the declared guard (the caller-supplied computed input the
+   *  transition requires), when the transition declares one */
+  guard?: string;
+}
+
+/** The affordance channel (TODO.ai-platform/08): the entity declaration's
+ *  machine facet — the lifecycle machine's current state (the fact,
+ *  published even when the role fires nothing) + the acts offered to the
+ *  declaring user's role (EMPTY means "the user can read but not act").
+ *  Only ever present on the entity kind. */
+export interface MachineContext {
+  state: string;
+  acts: MachineAct[];
+}
+
 export interface DeclaredContext {
   kind: "page" | "entity" | "document" | "account";
   /** display label ("this certificate R60/2021-A-EX1-26.01") — echoed
@@ -24,6 +48,8 @@ export interface DeclaredContext {
    *  (urn:oiml:pub:r:60-1:2021) or the plain docidentifier */
   doc?: string;
   edition?: string;
+  /** the affordance channel's machine facet (entity kind only) */
+  machine?: MachineContext;
 }
 
 /** The account context's live-read echo (TODO.ai-platform/03): WHEN the
@@ -55,10 +81,47 @@ export interface AppliedContext {
    *  chip grounded this answer in the model node itself — its constraint,
    *  its provenance, its tests */
   model?: { node_id: string; kind: string; standard: string; clause?: string };
+  /** the affordance channel's echo (TODO.ai-platform/08): the declared
+   *  machine's state + how many acts it offered the declaring user's role
+   *  — the panel's honest context line reads THIS, never its own copy */
+  machine?: { state: string; offered: number };
 }
 
 export const NO_CONTEXT: AppliedContext = { kind: "none", scoped_to: null };
 
+/** The affordance channel's bounds (TODO.ai-platform/08): the machine
+ *  facet is a hint from the panel, so it parses bounded and degrades to
+ *  undefined (no facet) on any malformation — never to an error. The
+ *  state is the fact; the acts may be EMPTY (the role fires nothing at
+ *  this state — the honest "read but not act"). */
+const MACHINE_STATE_MAX = 60;
+const MACHINE_ACT_MAX = 24;
+const MACHINE_FIELD_MAX = 60;
+
+export function parseMachine(v: any): MachineContext | undefined {
+  if (!v || typeof v !== "object") return undefined;
+  const state = typeof v.state === "string" ? v.state.trim().slice(0, MACHINE_STATE_MAX) : "";
+  if (!state) return undefined;
+  const acts: MachineAct[] = [];
+  for (const a of Array.isArray(v.acts) ? v.acts.slice(0, MACHINE_ACT_MAX) : []) {
+    const action = typeof a?.action === "string" ? a.action.trim().slice(0, MACHINE_FIELD_MAX) : "";
+    const to = typeof a?.to === "string" ? a.to.trim().slice(0, MACHINE_FIELD_MAX) : "";
+    if (!action || !to) continue;
+    const guard = typeof a?.guard === "string" && a.guard.trim() ? a.guard.trim().slice(0, MACHINE_FIELD_MAX) : undefined;
+    acts.push({ action, to, ...(guard ? { guard } : {}) });
+  }
+  return { state, acts };
+}
+
+/** The proposal bound (TODO.ai-platform/08): a draft act the offered set
+ *  does not carry is never proposed. An absent facet is not a bound (the
+ *  page publishes none); a present facet with an empty acts array bounds
+ *  to NOTHING — the user can read but not act. */
+export function machineOffers(machine: MachineContext | undefined, action: string): boolean {
+  if (!machine) return false;
+  return machine.acts.some((a) => a.action === action);
+}
+
 /** Parse + bound the ask body's optional `context` field. Anything
  *  malformed degrades to null (no context), never to a 400 — a context
  *  the service can't parse is a context it must not apply. */
@@ -70,7 +133,9 @@ export function parseContext(body: any): DeclaredContext | null {
   const route = typeof c.route === "string" && c.route.trim() ? c.route.trim().slice(0, 200) : undefined;
   const doc = typeof c.doc === "string" && c.doc.trim() ? c.doc.trim().slice(0, 80) : undefined;
   const edition = typeof c.edition === "string" && /^\d{4}$/.test(c.edition.trim()) ? c.edition.trim() : undefined;
-  return { kind: c.kind, label, ...(route ? { route } : {}), ...(doc ? { doc } : {}), ...(edition ? { edition } : {}) };
+  // the machine facet rides the entity kind only (the channel's contract)
+  const machine = c.kind === "entity" ? parseMachine(c.machine) : undefined;
+  return { kind: c.kind, label, ...(route ? { route } : {}), ...(doc ? { doc } : {}), ...(edition ? { edition } : {}), ...(machine ? { machine } : {}) };
 }
 
 import { refCodec, type DocScope } from "./codecs.ts";
@@ -132,6 +197,10 @@ export function appliedContext(
     scoped_to: scope ? scope.label : null,
     ...(note ? { note } : {}),
     ...(live ? { live } : {}),
+    // the affordance echo (TODO.ai-platform/08): the machine's state +
+    // the offered-act COUNT (the acts themselves are the platform's
+    // vocabulary, echoed back only bounded on the draft path)
+    ...(declared.machine ? { machine: { state: declared.machine.state, offered: declared.machine.acts.length } } : {}),
   };
 }
 
@@ -165,7 +234,14 @@ export function parseAppliedContext(v: any): AppliedContext | null {
           ...(typeof v.model.clause === "string" && v.model.clause.trim() ? { clause: v.model.clause.slice(0, 120) } : {}),
         }
       : undefined;
-  return { kind: v.kind, ...(label ? { label } : {}), scoped_to: scoped, ...(note ? { note } : {}), ...(live ? { live } : {}), ...(model ? { model } : {}) };
+  // The machine echo round-trips bounded too (TODO.ai-platform/08): a
+  // resumed session keeps the "the machine offers N acts at this state"
+  // honesty.
+  const machine =
+    v.machine && typeof v.machine === "object" && typeof v.machine.state === "string" && typeof v.machine.offered === "number"
+      ? { state: v.machine.state.slice(0, MACHINE_STATE_MAX), offered: Math.min(Math.max(0, Math.floor(v.machine.offered)), MACHINE_ACT_MAX) }
+      : undefined;
+  return { kind: v.kind, ...(label ? { label } : {}), scoped_to: scoped, ...(note ? { note } : {}), ...(live ? { live } : {}), ...(model ? { model } : {}), ...(machine ? { machine } : {}) };
 }
 
 /** The prompt note the declared context contributes (rides the
@@ -185,9 +261,18 @@ export function contextNote(declared: DeclaredContext | null, scope: DocScope |
     return `Context note: the user is viewing ${declared.label || "a page"}${declared.route ? ` (${declared.route})` : ""} in the ${P().publisher.product_name} platform. The passages come from the general corpus; frame procedural guidance for that page when relevant.`;
   }
   if (declared.kind === "entity") {
+    // The affordance channel's sentence (TODO.ai-platform/08): the
+    // machine's state is a fact the answer may use; the offered acts are
+    // the proposal bound — an act the set does not offer is never
+    // proposed, and an empty set is the honest "read but not act".
+    const machineSentence = declared.machine
+      ? declared.machine.acts.length
+        ? ` The entity's lifecycle machine is at ${declared.machine.state}; the acts it offers this user's role there are exactly: ${declared.machine.acts.map((a) => a.action).join(", ")}. Never propose an act outside that set.`
+        : ` The entity's lifecycle machine is at ${declared.machine.state}, and it offers this user's role NO acts there — the user can read but not act; say so when they ask for an act, and propose nothing.`
+      : "";
     return scope
-      ? `Context note: the user is asking about ${declared.label || "an entity"} — the passages are scoped to ${scope.label}, the publication that governs it. You do NOT have the entity's own data; answer what the publication requires and say when the question needs the record itself.`
-      : `Context note: the user is asking about ${declared.label || "an entity"}. You do NOT have the entity's own data; answer from the corpus passages and say when the question needs the record itself.`;
+      ? `Context note: the user is asking about ${declared.label || "an entity"} — the passages are scoped to ${scope.label}, the publication that governs it. You do NOT have the entity's own data; answer what the publication requires and say when the question needs the record itself.${machineSentence}`
+      : `Context note: the user is asking about ${declared.label || "an entity"}. You do NOT have the entity's own data; answer from the corpus passages and say when the question needs the record itself.${machineSentence}`;
   }
   return scope
     ? `Context note: the user scoped this question to ${scope.label} — the passages come from that publication. If they cannot answer the question, say so instead of drawing on other documents.`

package/workers/worker_public/src/delegated.ts

@@ -0,0 +1,83 @@
+// The delegated bearer (TODO.ai-platform/12 — the session bridge): the
+// platform-embedded bubble rides the app's own OIDC session. The
+// platform's same-origin proxy exchanges the retained OP access token
+// (RFC 8693, the identity RP guide §9b) and forwards the ask with the
+// OP-minted delegated JWT as the Bearer. This module admits THAT
+// credential as the member principal:
+//
+//   - verified against the OP's JWKS — signature, issuer, expiry
+//     (oidc.ts's verifier; discovery + JWKS ride the shared caches);
+//   - the delegation marker is REQUIRED: act.sub names the delegating
+//     surface (the platform instance's OP client), and the deployment
+//     declares the surfaces it trusts (publisher.identity.delegators) —
+//     a plain access token without the act claim is NOT a member
+//     credential here; the delegation is the contract;
+//   - the JWT's sub is the user; the standing re-judgment stays ours —
+//     the roles cone honored is THIS service's
+//     (service_roles[<our client id>] when the exchange scoped us in),
+//     never the delegator's.
+//
+// Every failure resolves to null — the anonymous tier, never an error
+// page. The feature is profile-gated (publisher.features.delegated_bearer):
+// the standalone site's own session bridge is untouched by default.
+
+import { discoverIssuer, verifyJwtSignature } from "./oidc.ts";
+import { P } from "./profile.ts";
+import type { SessionClaims } from "./session.ts";
+
+const EXPIRY_LEEWAY_MS = 60_000;
+
+/** The delegated JWT's claim shape (the OP's delegationTokenClaims):
+ *  sub the user, aud the scoped services, scope the granted cone,
+ *  service_roles per service, act.sub the delegating client. */
+interface DelegatedJwtClaims {
+  iss?: string;
+  sub?: string;
+  aud?: string | string[];
+  iat?: number;
+  exp?: number;
+  scope?: string;
+  name?: string;
+  email?: string;
+  service_roles?: Record<string, unknown>;
+  act?: { sub?: unknown };
+}
+
+export async function delegatedBearerFrom(req: Request, env: any): Promise<SessionClaims | null> {
+  if (!P().publisher.features?.delegated_bearer) return null;
+  const issuer = (env.OIDC_ISSUER ?? "").trim();
+  if (!issuer) return null;
+  const m = (req.headers.get("authorization") ?? "").match(/^Bearer\s+(.+)$/i);
+  if (!m) return null;
+  const token = m[1].trim();
+  // the service session is a two-segment HMAC token; three segments mark
+  // the JWT candidate (anything else never reaches the verifier)
+  if (token.split(".").length !== 3) return null;
+  // fail closed: a deployment opting in names its delegating surfaces
+  const delegators = P().publisher.identity?.delegators;
+  if (!Array.isArray(delegators) || delegators.length === 0) return null;
+  try {
+    const meta = await discoverIssuer(issuer);
+    const { claims } = await verifyJwtSignature(token, meta.jwks_uri);
+    const c = claims as DelegatedJwtClaims;
+    if (c.iss?.replace(/\/$/, "") !== meta.issuer.replace(/\/$/, "")) return null;
+    if (typeof c.exp !== "number" || c.exp * 1000 + EXPIRY_LEEWAY_MS < Date.now()) return null;
+    const actSub = typeof c.act?.sub === "string" ? c.act.sub : null;
+    if (!actSub || !delegators.includes(actSub)) return null;
+    if (typeof c.sub !== "string" || !c.sub) return null;
+    const ourRoles = c.service_roles?.[env.OIDC_CLIENT_ID];
+    return {
+      sub: c.sub,
+      name: typeof c.name === "string" ? c.name : undefined,
+      email: typeof c.email === "string" ? c.email : undefined,
+      roles: Array.isArray(ourRoles) ? ourRoles.filter((r): r is string => typeof r === "string") : [],
+      iat: typeof c.iat === "number" ? c.iat * 1000 : Date.now(),
+      exp: c.exp * 1000,
+      scope: typeof c.scope === "string" ? c.scope : undefined,
+      via: "delegated",
+      delegator: actSub,
+    };
+  } catch {
+    return null;
+  }
+}

package/workers/worker_public/src/drafts.ts

@@ -231,6 +231,16 @@ const norm = (s: string) =>
 /** The document-name normalization: whitespace-free ("R 60" ≡ "R60"). */
 const docNorm = (s: string) => norm(s).replace(/\s+/g, "");
 
+/** The traceability primitive, shared with the api_call act's body guard
+ *  (apicalls.ts): a value traces when it appears in the user's own
+ *  messages (normalized). The proposing model never gets the benefit of
+ *  the doubt — the user's words are the only source. */
+export function valueTracesToUser(value: unknown, userTurns: string[]): boolean {
+  if (typeof value !== "string" || !value.trim()) return false;
+  const haystack = norm(userTurns.join("\n"));
+  return haystack.includes(norm(value));
+}
+
 export interface GuardedFields {
   standard?: string;
   family_designation?: string;

package/workers/worker_public/src/env.ts

@@ -48,12 +48,13 @@ export interface Env {
 // Domain modules import `portModelRunner(env)` etc. — never env.AI
 // directly; the purity lint enforces it. Zero runtime change: the
 // adapters forward to the same bindings the call sites used before.
-import { cfModelRunner, cfVectorIndex, cfKv, cfBlobs, cfRuntime } from "./ports/cloudflare/adapters.ts";
+import { cfModelRunner, cfVectorIndex, cfKv, cfBlobs, cfRuntime, cfStore } from "./ports/cloudflare/adapters.ts";
 import type { ModelRunner } from "./ports/model.ts";
 import type { VectorIndex } from "./ports/vector.ts";
 import type { Kv } from "./ports/kv.ts";
 import type { Blobs } from "./ports/blobs.ts";
 import type { Runtime } from "./ports/runtime.ts";
+import type { StoreQuery } from "./ports/store.ts";
 
 export function portModelRunner(env: Env): ModelRunner {
   return cfModelRunner(env.AI);
@@ -76,6 +77,9 @@ export function portKv(env: Env): Kv {
 export function portBlobs(env: Env): Blobs {
   return cfBlobs(env.UNIT_ASSETS);
 }
+export function portStore(env: Env): StoreQuery {
+  return cfStore(env.DB);
+}
 /** Does the deployment bind this lane index? Presence wiring stays in
  *  the ports layer so domain stages never touch raw bindings. */
 export function hasLane(env: Env, which: "glossary"): boolean {

package/workers/worker_public/src/index.ts

@@ -125,7 +125,10 @@ async function tierFor(c: RouteContext): Promise<{ tier: "anon" | "key" | "membe
     if (!key) return err(401, "unauthorized", `Provide a valid API key: Authorization: Bearer ${P().publisher.id}_...`);
   }
   let tier: "anon" | "key" | "member" = isApi ? "key" : "anon";
-  if (!isApi && c.env.SESSION_SECRET && (await sessionFrom(c.req, c.env as any))) tier = "member";
+  // No SESSION_SECRET precondition: the delegated bearer (the platform
+  // bubble's OP-minted JWT, delegated.ts) admits the member lane on its
+  // own — sessionFrom returns null honestly when neither lane applies.
+  if (!isApi && (await sessionFrom(c.req, c.env as any))) tier = "member";
   return { tier, key };
 }
 

package/workers/worker_public/src/livedata.ts

@@ -186,6 +186,28 @@ export async function exchangeForLiveToken(env: any, sessionRaw: string): Promis
   return { ok: true, token: granted.access_token };
 }
 
+/** The live read token for one ask (TODO.ai-platform/12 — the session
+ *  bridge): when the member arrived on the delegated bearer, the Bearer
+ *  IS already the OP-minted platform-scoped JWT — the platform exchanged
+ *  it before forwarding, so a second exchange here would have no subject
+ *  token to ride (the bubble never signed into THIS service). If the
+ *  token's scope cone covers the platform read, present it directly;
+ *  otherwise (a service session, or a delegation that never scoped the
+ *  platform in) fall through to the RFC 8693 exchange. */
+export async function liveTokenFor(
+  env: any,
+  sessionRaw: string,
+  member: { via?: string; scope?: string } | null,
+): Promise<LiveTokenVerdict> {
+  const cfg = liveDataConfig(env);
+  if (!cfg) return { ok: false, reason: "not_configured" };
+  if (member?.via === "delegated" && typeof member.scope === "string") {
+    const need = `${cfg.platformClientId}:read`;
+    if (member.scope.split(/\s+/).includes(need)) return { ok: true, token: sessionRaw };
+  }
+  return exchangeForLiveToken(env, sessionRaw);
+}
+
 // ── the platform reads (the records the answer grounds in) ───────────
 
 export interface LiveRecord {
@@ -357,12 +379,12 @@ export type LiveAccount =
 export async function resolveLiveAccount(
   env: any,
   sessionRaw: string | null,
-  member: { sub: string } | null,
+  member: { sub: string; via?: string; scope?: string } | null,
 ): Promise<LiveAccount> {
   if (!member || !sessionRaw) return { status: "unavailable", reason: "sign_in_required" };
   const cfg = liveDataConfig(env);
   if (!cfg) return { status: "unavailable", reason: "not_configured" };
-  const exchanged = await exchangeForLiveToken(env, sessionRaw);
+  const exchanged = await liveTokenFor(env, sessionRaw, member);
   if (!exchanged.ok) return { status: "unavailable", reason: exchanged.reason };
   const read = await readMyAccount(env, cfg, exchanged.token);
   if (!read.ok) return { status: "unavailable", reason: read.reason };

package/workers/worker_public/src/oidc.ts

@@ -18,9 +18,11 @@ export type OidcFailureReason =
   | 'token_nonce';
 
 export class OidcError extends Error {
-  constructor(readonly reason: OidcFailureReason, message: string) {
+  readonly reason: OidcFailureReason;
+  constructor(reason: OidcFailureReason, message: string) {
     super(message);
     this.name = "OidcError";
+    this.reason = reason;
   }
 }
 
@@ -252,31 +254,36 @@ export interface OidcIdTokenClaims {
 
 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(".");
+/** Decode + signature-verify a JWT against the issuer's JWKS (RS256 or
+ *  ES256; the JWKS fetch caches an hour and force-refreshes once on a
+ *  miss). Claim semantics (issuer, audience, expiry, nonce) are the
+ *  CALLER's — the ID token and the delegated bearer check different
+ *  claim sets over the same verified signature. */
+export async function verifyJwtSignature(
+  token: string,
+  jwksUri: string,
+): Promise<{ header: { alg?: string; kid?: string }; claims: Record<string, unknown> }> {
+  const parts = token.split(".");
   if (parts.length !== 3) {
-    throw new OidcError("token_malformed", "the ID token is not a three-part JWT");
+    throw new OidcError("token_malformed", "the token is not a three-part JWT");
   }
   let header: { alg?: string; kid?: string };
-  let claims: OidcIdTokenClaims;
+  let claims: Record<string, unknown>;
   try {
     header = JSON.parse(new TextDecoder().decode(base64urlDecode(parts[0])));
-    claims = JSON.parse(new TextDecoder().decode(base64urlDecode(parts[1]))) as OidcIdTokenClaims;
+    claims = JSON.parse(new TextDecoder().decode(base64urlDecode(parts[1]))) as Record<string, unknown>;
   } catch {
-    throw new OidcError("token_malformed", "the ID token header/claims are not JSON");
+    throw new OidcError("token_malformed", "the 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"}`);
+    throw new OidcError("token_alg", `the 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 keys = await fetchJwks(jwksUri, force);
     const candidates = keys.filter(
       (k) => (!header.kid || k.kid === header.kid) && (header.alg === "RS256" ? k.kty === "RSA" : k.kty === "EC"),
     );
@@ -303,26 +310,35 @@ export async function validateIdToken(
     if (verified) break;
   }
   if (!verified) {
-    throw new OidcError("token_signature", "the ID token signature does not verify against the issuer's published keys");
+    throw new OidcError("token_signature", "the token signature does not verify against the issuer's published keys");
   }
+  return { header, claims };
+}
+
+export async function validateIdToken(
+  idToken: string,
+  expectations: { issuer: string; clientId: string; nonce: string; jwksUri: string },
+): Promise<OidcIdTokenClaims> {
+  const { claims } = await verifyJwtSignature(idToken, expectations.jwksUri);
+  const idClaims = claims as OidcIdTokenClaims;
 
-  if (claims.iss?.replace(/\/$/, "") !== expectations.issuer.replace(/\/$/, "")) {
+  if (idClaims.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];
+  const audiences = Array.isArray(idClaims.aud) ? idClaims.aud : [idClaims.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) {
+  if (audiences.length > 1 && idClaims.azp && idClaims.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()) {
+  if (typeof idClaims.exp !== "number" || idClaims.exp * 1000 + EXPIRY_LEEWAY_MS < Date.now()) {
     throw new OidcError("token_expired", "the ID token has expired");
   }
-  if (claims.nonce !== expectations.nonce) {
+  if (idClaims.nonce !== expectations.nonce) {
     throw new OidcError("token_nonce", "the ID token's nonce does not match the request");
   }
-  return claims;
+  return idClaims;
 }
 
 export function buildEndSessionUrl(

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

@@ -167,6 +167,14 @@ export function cfBlobs(bucket: unknown): Blobs {
   };
 }
 
+// The transitional relational port (ports/store.ts): D1 IS the
+// adapter — the port narrows to semantic repositories when the
+// repository extraction completes.
+import type { StoreQuery } from "../store.ts";
+export function cfStore(db: unknown): StoreQuery {
+  return db as StoreQuery;
+}
+
 export function cfRuntime(ctx: { waitUntil(p: Promise<unknown>): void } | undefined): Runtime {
   return {
     defer(fn) {

package/workers/worker_public/src/requestScope.ts

@@ -56,8 +56,14 @@ export function entitlementScope(keys: Set<string>): Set<string> | null {
 /** 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" } {
+ *  `corpora:`) — the engine maps no publisher names.
+ *
+ *  `opts.keyWithEntitlements` (the key-tier licensed federation): an
+ *  API-key caller whose request carries a VALIDATED entitlement set is
+ *  admitted to the session-gated (federated) datasets — the key's
+ *  entitlement set is the licensed scope the internal lane honors; the
+ *  internal worker re-validates the key server-side before it answers. */
+export function resolveRequestScope(body: any, member: unknown, opts?: { keyWithEntitlements?: boolean }): 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))
@@ -65,7 +71,7 @@ export function resolveRequestScope(body: any, member: unknown): RequestScope |
   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;
+    return d.session ? datasetAllowed(d, member) || !!opts?.keyWithEntitlements : true;
   });
   // requested ∩ permitted — an explicit request NEVER widens past the
   //  session's permissions (a member without ai-preview asking

package/dist/ask-GU554Y45.js

@@ -1,12 +0,0 @@
-import {
-  handleAsk
-} from "./chunk-WSLADX7O.js";
-import "./chunk-NHHQAGBW.js";
-import "./chunk-2RKYO3OC.js";
-import "./chunk-A3QHHUN5.js";
-import "./chunk-JGKSUSF5.js";
-import "./chunk-OMXAE27N.js";
-import "./chunk-3FYJM7LH.js";
-export {
-  handleAsk
-};

package/dist/search-LGDQR43R.js

@@ -1,12 +0,0 @@
-import {
-  handleSearch
-} from "./chunk-5LSEBH3J.js";
-import "./chunk-NHHQAGBW.js";
-import "./chunk-2RKYO3OC.js";
-import "./chunk-A3QHHUN5.js";
-import "./chunk-JGKSUSF5.js";
-import "./chunk-OMXAE27N.js";
-import "./chunk-3FYJM7LH.js";
-export {
-  handleSearch
-};