@konneal/engine 0.2.2 → 0.2.4

package/workers/worker_public/src/requestScope.ts

@@ -1,10 +1,12 @@
 // 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
+// toggles, server-intersected with session permissions), which memory
+// files ride it, and which LICENSED standards the caller's organization
+// is entitled to — plus the answer-cache SALT all three selections
 // produce. Pure: D1 access stays with the caller (memoryNote); this
 // module only derives.
 import { DATASETS, datasetAllowed } from "./config.ts";
+import { P } from "./profile.ts";
 
 export interface RequestScope {
   /** dataset ids the request may search */
@@ -18,6 +20,37 @@ export interface RequestScope {
   isoOn: boolean;
   /** raw (validated) memory ids from the body — empty for anon */
   memoryIds: string[];
+  /** raw (validated) license entitlement keys from the body — empty for
+   *  anon and for requests that carry none (TODO.external-refs/08) */
+  standardKeys: Set<string>;
+}
+
+/** The deployment's declared licensed standards (profile sources.yaml
+ *  `licensed:` — key/package/doc_number rows). Empty = the deployment
+ *  serves public content only and the entitlement scope is inert. */
+export function licenseDeclared(): boolean {
+  return (P().sources?.licensed?.length ?? 0) > 0;
+}
+
+/** The request's entitlement set, VALIDATED against the declared
+ *  whitelist: unknown keys drop (a forged key can never widen scope past
+ *  the standards the deployment actually keys). Absent field = empty set
+ *  — the fail-closed default for a deployment that declares licensed
+ *  content. */
+export function standardKeysFrom(body: any): Set<string> {
+  const declared = new Set<string>((P().sources?.licensed ?? []).map((l: any) => String(l.key)));
+  const raw = Array.isArray(body?.licensed_standards) ? body.licensed_standards : [];
+  return new Set(
+    raw.filter((x: unknown): x is string => typeof x === "string" && declared.has(x)),
+  );
+}
+
+/** The RetrieveOptions value for the hard scope: null when the
+ *  deployment declares no licensed content (inert — zero behavior
+ *  change); otherwise the caller's validated set, EMPTY INCLUDED (the
+ *  unentitled caller: licensed chunks hidden, citation metadata stays). */
+export function entitlementScope(keys: Set<string>): Set<string> | null {
+  return licenseDeclared() ? keys : null;
 }
 
 /** Validate + intersect. Returns { error } when the request explicitly
@@ -54,18 +87,27 @@ export function resolveRequestScope(body: any, member: unknown): RequestScope |
     // federation flag: any session-gated (federated) dataset in scope
     isoOn: scopeIds.some((id) => DATASETS().find((x) => x.id === id)?.session === true),
     memoryIds,
+    standardKeys: standardKeysFrom(body),
   };
 }
 
 /** 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. */
+ *  the answer (dataset scope, memory selection, license entitlements —
+ *  the licensed tier changes the grounding, so two callers asking the
+ *  same question must never share an entry). Requests differing only in
+ *  salt share query text — an unsalted key would serve a scoped (or
+ *  memory-flavored, or licensed-tier) answer to a plain ask. Null =
+ *  default scope, no memory, no entitlement effect: 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;
+  const licensed = licenseDeclared();
+  if (!scope.narrowed && !memoryUsed.length && !licensed) return null;
   return JSON.stringify({
     ...(scope.narrowed ? { d: [...scope.corpora].sort() } : {}),
     ...(memoryUsed.length ? { m: [...memoryUsed].sort() } : {}),
+    // the entitlement set rides whenever the deployment keys content at
+    // all — an unentitled ask and an entitled ask of the same text are
+    // different answers even when the set is empty
+    ...(licensed ? { s: [...scope.standardKeys].sort() } : {}),
   });
 }

package/workers/worker_public/src/search.ts

@@ -4,6 +4,7 @@ import { portModelRunner } from "./env.ts";
 import type { Background } from "./ports/runtime.ts";
 import { retrieve } from "./pipeline";
 import { understandQuery } from "./understand";
+import { entitlementScope, standardKeysFrom } from "./requestScope";
 import { sessionFrom } from "./auth";
 import { err, json, corsHeaders, readJson, validateQuery, type ApiKey } from "./lib/http";
 import { checkQuota, clientIp, telemetry } from "./quota";
@@ -32,9 +33,14 @@ export async function handleSearch(
 
   const understanding = await understandQuery(portModelRunner(env), MODELS.understand, q.query, []);
   const graphDocNumbers = await graphExpand(env, understanding);
+  // the license entitlement set rides the body exactly as it does on the
+  // ask path (TODO.external-refs/08): request-scoped, whitelist-validated,
+  // fail-closed — a retrieval with an empty set returns zero licensed
+  // chunks at the transport level
+  const standardKeys = entitlementScope(standardKeysFrom(body));
   let retrieved;
   try {
-    retrieved = await retrieve(env, q.query, { understanding, graphDocNumbers });
+    retrieved = await retrieve(env, q.query, { understanding, graphDocNumbers, standardKeys });
   } catch {
     return err(503, "retrieval_unavailable", "Search is briefly busy — please retry in a moment.");
   }

package/workers/worker_public/src/selfquery.ts

@@ -23,3 +23,29 @@ export function toVectorizeFilter(f: QueryFilters): Record<string, string> | und
   }
   return undefined;
 }
+
+// ── the license entitlement scope (TODO.external-refs/08) ────────────────
+// A chunk's `standard_key` metadata carries the licensed package's
+// entitlement key; public content carries none. The scope is a HARD
+// FILTER (a hit never reaches ranking when its key is outside the
+// caller's set) — but it deliberately does NOT translate into a
+// Vectorize metadata predicate: the wire has no "field missing OR in-set"
+// operator, so a `standard_key $in […]` push-down would exclude every
+// public chunk (they predate the field). The scope binds pool-level
+// (stages/licenseScope.ts, before rerank) and at the lexical lane's
+// source (pipeline.ts, the sealScope posture) instead; the single-doc
+// post-seal fetches (section-descent, typed-pin parent, edition-cover)
+// are doc-scoped and a document's key is a per-document constant, so
+// they cannot re-admit a dropped key.
+
+/** The one entitlement predicate: no key = public = always allowed; a key
+ *  outside the caller's set = never allowed. `null`/undefined keys (the
+ *  deployment declares no licensed content) disable the scope entirely. */
+export function standardKeyAllowed(
+  meta: { standard_key?: string },
+  keys: ReadonlySet<string> | null | undefined,
+): boolean {
+  if (!keys) return true;
+  const k = meta.standard_key;
+  return !k || keys.has(k);
+}

package/workers/worker_public/src/stages/citationProbe.ts

@@ -14,6 +14,7 @@
 import type { Stage } from "./types.ts";
 import { namedDocumentIn } from "../context.ts";
 import { refCodec } from "../codecs.ts";
+import { standardKeyAllowed } from "../selfquery.ts";
 import type { Hit } from "../../../shared/chunk.ts";
 
 const CITE_PATTERN = /\b(?:cite[sd]?|citing|referenc(?:e|es|ed|ing)|list[s]?|quote[sd]?)\b/i;
@@ -123,9 +124,13 @@ export const citationProbe: Stage = {
     const [probes, citeRows] = (await c.lane["citation-probe"]) as [Hit[], CiteRow[]];
     const seen = new Set(c.hits.map((m: any) => m.id));
     let added = 0;
-    // only bibliography-shaped chunks (clause title or text mentions it)
+    // only bibliography-shaped chunks (clause title or text mentions it);
+    // the push rides the entitlement predicate — the probe runs past the
+    // pool-level license scope, and a licensed family's bibliography
+    // passages must obey the same hard scope as everything else
     for (const h of probes) {
       if (seen.has(h.id as any)) continue;
+      if (!standardKeyAllowed(h.metadata as any, c.opts.standardKeys)) continue;
       const title = String((h.metadata as any)?.clause_title ?? "");
       const text = String(h.text ?? "");
       if (/bibliograph|normative reference/i.test(title + " " + text.slice(0, 300))) {

package/workers/worker_public/src/stages/index.ts

@@ -23,6 +23,7 @@ import { poolOpen } from "./poolOpen.ts";
 import { lexicalUnion } from "./lexicalUnion.ts";
 import { federate } from "./federate.ts";
 import { seal } from "./seal.ts";
+import { licenseScope } from "./licenseScope.ts";
 import { corpusScope } from "./corpusScope.ts";
 import { editionCover } from "./editionCover.ts";
 import { stdRefNudge } from "./stdRefNudge.ts";
@@ -51,6 +52,7 @@ export const STAGES: Stage[] = [
   lexicalUnion,
   federate,
   seal,
+  licenseScope,
   overviewDemote,
   familyBoost,
   rerankStage,

package/workers/worker_public/src/stages/licenseScope.ts

@@ -0,0 +1,23 @@
+// The license entitlement hard scope (TODO.external-refs/08) — pool-level,
+// after every candidate lane has merged, BEFORE rerank + the top-N cut
+// (the `seal` posture, never the post-rerank corpus-scope drop). A chunk
+// whose `standard_key` lies outside the caller's entitlement set never
+// competes for the window: the model never sees licensed text the caller
+// cannot be shown, so no prompt-level leakage either. The predicate is
+// selfquery.standardKeyAllowed; the lane audit that binds every query
+// shape lives in its doc comment.
+import { standardKeyAllowed } from "../selfquery.ts";
+import type { Stage } from "./types.ts";
+
+export const licenseScope: Stage = {
+  name: "license-scope",
+  when: (c) => !!c.opts.standardKeys,
+  run: (c) => {
+    const keys = c.opts.standardKeys!;
+    const before = c.hits.length;
+    c.hits = c.hits.filter((h) => standardKeyAllowed(h.metadata, keys));
+    if (c.hits.length !== before) {
+      console.log("license scope:", before, "→", c.hits.length, "candidates within the caller's entitlement set");
+    }
+  },
+};

package/workers/worker_public/src/stages/types.ts

@@ -36,6 +36,17 @@ export interface RetrieveOptions {
    *  intersects the requested ids with session permissions before
    *  building this set. */
   datasetScope?: Set<string> | null;
+  /** The license entitlement set (TODO.external-refs/08): the standard
+   *  keys the caller's organization is entitled to, resolved
+   *  request-scoped by the deployment (never a client-tunable filter —
+   *  it arrives through the same trusted request context as the session,
+   *  and the profile's declared licensed list is the validation
+   *  whitelist). NON-NULL activates the hard scope: chunks carrying a
+   *  `standard_key` outside the set never reach ranking (an EMPTY set is
+   *  the unentitled caller — licensed content hidden, citation-level
+   *  metadata stays). Null = the deployment declares no licensed
+   *  content, the scope is inert. */
+  standardKeys?: Set<string> | null;
 }
 
 export interface GlossaryEntry {

package/dist/ask-VFSAF5WG.js

@@ -1,12 +0,0 @@
-import {
-  handleAsk
-} from "./chunk-PVHSBXZD.js";
-import "./chunk-LNSDBEKS.js";
-import "./chunk-6GOSMLRH.js";
-import "./chunk-SN3ANQ3Y.js";
-import "./chunk-WGXATDXY.js";
-import "./chunk-Q6LI4T7M.js";
-import "./chunk-Q327B27J.js";
-export {
-  handleAsk
-};

package/dist/search-OMPBMZT4.js

@@ -1,11 +0,0 @@
-import {
-  handleSearch
-} from "./chunk-VJZLVU3S.js";
-import "./chunk-6GOSMLRH.js";
-import "./chunk-SN3ANQ3Y.js";
-import "./chunk-WGXATDXY.js";
-import "./chunk-Q6LI4T7M.js";
-import "./chunk-Q327B27J.js";
-export {
-  handleSearch
-};