@konneal/engine 0.2.1 → 0.2.3

package/dist/profile.gen.d.ts

@@ -54,6 +54,13 @@ export declare const PROFILE: {
         readonly bibliography: {};
         readonly terminology: {};
         readonly models: {};
+        readonly licensed: readonly [{
+            readonly key: "std:fixture-60068-2-30";
+            readonly package: "fixture-60068-2-30";
+            readonly doc_number: "60068-2-30";
+            readonly title: "FIXTURE environmental testing — damp heat, cyclic";
+            readonly edition: "2005";
+        }];
     };
     readonly ui: {
         readonly suggestions: readonly ["What is in the fixture corpus?", "Which documents does the fixture publisher issue?"];
@@ -85,6 +92,8 @@ export declare const PROFILE: {
             readonly docid_example: "FIXTURE 1-2";
             readonly spelling_examples: "\"f1\", \"FIXTURE 1\"";
             readonly process_vocab: "the fixture certification system framework";
+            readonly license_declare_pointer: "org admin → Settings → Standards licenses";
+            readonly license_posture: "Some indexed publications are LICENSED. When a license boundary note names the question's publication, obey it: answer at the citation level only — the standard's title and edition, and the invoking clause the public passages carry — never state, paraphrase or \"summarize from memory\" any procedure of the licensed text, and point at the declare flow the note names. Public content (the Recommendations' own models, applicability and references) stays fully answerable.";
         };
     };
 };

package/dist/prompts/system.md

@@ -14,6 +14,7 @@ Synthesize practical answers from the passages: definitions, procedures and rule
 MANDATORY: when the question asks how to do something (get certified, apply, comply, register, test) and the passages describe the governing system or procedure, ALWAYS answer with that procedure citing the governing documents. Refusing such a question because the passages do not name the specific publication is WRONG — the publication sets technical requirements; the HOW is governed by the certification-system documents in the passages.
 If the passages cover only part of the question, answer the covered part fully, then state precisely what the indexed publications do not cover — do not pad with outside knowledge.
 Refuse ONLY when no passage relates to the question's topic. Use exactly this sentence: {{REFUSAL_SENTENCE}} Then add one short line naming what you can answer instead, so the refusal redirects rather than dead-ends.
+{{LICENSE_POSTURE}}
 {{CORPUS_NOTES}}
 Lead with the direct answer, then supporting detail; no preamble like 'Based on the passages'. Use short paragraphs or bullets for multi-part answers. Be concise and precise. Answer in the question's language{{LANG_CLAUSE}}.
 - HARD RULE — typed units: passages whose header shows `unit u:xxxx (table)` contain a typed table. If your answer presents that table's data, you MUST write the token `[[u:xxxx]]` where the table belongs and MUST NOT render the table as markdown or reproduce more than ONE of its rows inline. Summarize the pattern in prose ("classes A–D with lower limits from 100 to 50 000"), cite the clause normally, and let `[[u:xxxx]]` stand for the full table — the interface renders it exactly from the source. The same rule applies to `unit u:xxxx (formula|figure|term)` objects.

package/dist/requestScope.d.ts

@@ -10,7 +10,25 @@ 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 declare function licenseDeclared(): boolean;
+/** 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 declare function standardKeysFrom(body: any): Set<string>;
+/** 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 declare 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,
@@ -19,8 +37,11 @@ export declare function resolveRequestScope(body: any, member: unknown): Request
     error: "empty-datasets";
 };
 /** 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 declare function requestSalt(scope: RequestScope, memoryUsed: string[]): string | null;

package/dist/search-7TO2RWQE.js

@@ -0,0 +1,12 @@
+import {
+  handleSearch
+} from "./chunk-THSHLUOS.js";
+import "./chunk-RLT4W2VX.js";
+import "./chunk-EFQALN2Z.js";
+import "./chunk-DBBGOOMZ.js";
+import "./chunk-5MBWE7WD.js";
+import "./chunk-ADXV2DPK.js";
+import "./chunk-TJRTVJW5.js";
+export {
+  handleSearch
+};

package/dist/selfquery.d.ts

@@ -5,3 +5,9 @@ export interface QueryFilters {
     language?: string;
 }
 export declare function toVectorizeFilter(f: QueryFilters): Record<string, string> | undefined;
+/** 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 declare function standardKeyAllowed(meta: {
+    standard_key?: string;
+}, keys: ReadonlySet<string> | null | undefined): boolean;

package/dist/worker_mcp/src/index.js

@@ -1,11 +1,11 @@
 import {
   authenticate
-} from "../../chunk-SN3ANQ3Y.js";
-import "../../chunk-Q6LI4T7M.js";
+} from "../../chunk-EFQALN2Z.js";
+import "../../chunk-ADXV2DPK.js";
 import {
   P,
   setProfile
-} from "../../chunk-Q327B27J.js";
+} from "../../chunk-TJRTVJW5.js";
 
 // workers/worker_mcp/src/index.ts
 var PROTOCOL_VERSION = "2025-06-18";

package/dist/worker_public/src/config.js

@@ -16,8 +16,8 @@ import {
   roleModel,
   sha256Hex,
   today
-} from "../../chunk-Q6LI4T7M.js";
-import "../../chunk-Q327B27J.js";
+} from "../../chunk-ADXV2DPK.js";
+import "../../chunk-TJRTVJW5.js";
 export {
   DATASETS,
   LIMITS,

package/dist/worker_public/src/index.js

@@ -1,14 +1,13 @@
 import {
   handleSearch
-} from "../../chunk-VJZLVU3S.js";
+} from "../../chunk-THSHLUOS.js";
 import {
   checkQuoteAnchors,
   handleAsk,
   handleMemories,
   scoreJudge,
   standardForDocNumber
-} from "../../chunk-3OXSQH7Y.js";
-import "../../chunk-LNSDBEKS.js";
+} from "../../chunk-OGFH3RDM.js";
 import {
   buildMessages,
   citations,
@@ -30,7 +29,7 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "../../chunk-6GOSMLRH.js";
+} from "../../chunk-RLT4W2VX.js";
 import {
   authenticate,
   corsHeaders,
@@ -39,10 +38,14 @@ import {
   readJson,
   validateQuery,
   withCors
-} from "../../chunk-SN3ANQ3Y.js";
+} from "../../chunk-EFQALN2Z.js";
 import {
   canonicalRefusal
-} from "../../chunk-WGXATDXY.js";
+} from "../../chunk-DBBGOOMZ.js";
+import {
+  entitlementScope,
+  standardKeysFrom
+} from "../../chunk-5MBWE7WD.js";
 import {
   LIMITS,
   MODELS,
@@ -53,11 +56,11 @@ import {
   roleModel,
   sha256Hex,
   today
-} from "../../chunk-Q6LI4T7M.js";
+} from "../../chunk-ADXV2DPK.js";
 import {
   P,
   setProfile
-} from "../../chunk-Q327B27J.js";
+} from "../../chunk-TJRTVJW5.js";
 
 // workers/worker_public/src/conversations.ts
 var ID_RE = /^[a-zA-Z0-9_-]{8,64}$/;
@@ -282,11 +285,31 @@ async function handleShareConversation(env, ownerSub, title, messages) {
   if (count >= 10) return err(429, "rate_limited", "Daily share limit reached");
   await env.CACHE.put(`sh:${day}:${ownerSub.slice(0, 20)}`, String(count + 1), { expirationTtl: 9e4 });
   const slug = makeSlug();
-  const cleanMessages = messages.slice(0, 50).map((m) => ({
-    role: m.role === "user" ? "user" : "assistant",
-    content: (m.content ?? "").slice(0, LIMITS.maxOutputTokens * 2),
-    citations: m.citations ? JSON.parse(m.citations) : null
-  }));
+  const cleanMessages = messages.slice(0, 50).map((m) => {
+    const citations2 = Array.isArray(m.citations) ? m.citations : typeof m.citations === "string" ? (() => {
+      try {
+        return JSON.parse(m.citations);
+      } catch {
+        return null;
+      }
+    })() : null;
+    const read = m.read && typeof m.read === "object" ? {
+      intent: String(m.read.intent ?? ""),
+      doc: m.read.doc ?? null,
+      edition: m.read.edition ?? null,
+      term: m.read.term ?? null,
+      terms: Array.isArray(m.read.terms) ? m.read.terms.slice(0, 4).map(String) : [],
+      lang: m.read.lang ?? null
+    } : void 0;
+    return {
+      role: m.role === "user" ? "user" : "assistant",
+      content: (m.content ?? "").slice(0, LIMITS.maxOutputTokens * 2),
+      citations: citations2,
+      ...m.model ? { model: String(m.model).slice(0, 80) } : {},
+      ...Array.isArray(m.blocks) ? { blocks: m.blocks.slice(0, 12) } : {},
+      ...read ? { read } : {}
+    };
+  });
   await env.DB.prepare(
     "INSERT INTO shared_conversations (slug, owner_sub, title, messages, created_at) VALUES (?1,?2,?3,?4,?5)"
   ).bind(slug, ownerSub, title.slice(0, 120), JSON.stringify(cleanMessages), (/* @__PURE__ */ new Date()).toISOString()).run();
@@ -956,7 +979,7 @@ async function handleMcp(env, ctx, req, tier, key) {
       // stream:false forces the JSON lane (anon defaults to SSE)
       body: JSON.stringify({ ...args, stream: false })
     });
-    const res = name === "ask" ? await (await import("../../ask-47RNGK2R.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-OMPBMZT4.js")).handleSearch(env, ctx, inner, tier, key);
+    const res = name === "ask" ? await (await import("../../ask-YCDXMIZ4.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-7TO2RWQE.js")).handleSearch(env, ctx, inner, tier, key);
     return res.json().catch(() => ({ error: { message: "tool transport failed", status: res.status } }));
   });
   if (out.ok && "accepted" in out) return new Response(null, { status: 202 });
@@ -1415,7 +1438,7 @@ async function verifyRoute(c) {
   if (!answer || !query) return err(400, "invalid_input", "answer and query are required");
   try {
     const u = await understandQuery(env.AI, roleModel(env, "understand"), query, [], []);
-    const retrieved = await retrieve(env, query, { understanding: u });
+    const retrieved = await retrieve(env, query, { understanding: u, standardKeys: entitlementScope(standardKeysFrom(body)) });
     const passages = retrieved.hits.map((h) => h.text);
     const anchors = checkQuoteAnchors(answer, passages);
     const refs = [...answer.matchAll(/\[\[u:([^\]]+)\]\]/g)].map((m) => m[1]);

package/dist/worker_public/src/profile.js

@@ -1,7 +1,7 @@
 import {
   P,
   setProfile
-} from "../../chunk-Q327B27J.js";
+} from "../../chunk-TJRTVJW5.js";
 export {
   P,
   setProfile

package/dist/worker_public/src/refusal.js

@@ -1,8 +1,8 @@
 import {
   canonicalRefusal,
   refusalAnswer
-} from "../../chunk-WGXATDXY.js";
-import "../../chunk-Q327B27J.js";
+} from "../../chunk-DBBGOOMZ.js";
+import "../../chunk-TJRTVJW5.js";
 export {
   canonicalRefusal,
   refusalAnswer

package/dist/worker_public/src/requestScope.js

@@ -1,10 +1,16 @@
 import {
+  entitlementScope,
+  licenseDeclared,
   requestSalt,
-  resolveRequestScope
-} from "../../chunk-LNSDBEKS.js";
-import "../../chunk-Q6LI4T7M.js";
-import "../../chunk-Q327B27J.js";
+  resolveRequestScope,
+  standardKeysFrom
+} from "../../chunk-5MBWE7WD.js";
+import "../../chunk-ADXV2DPK.js";
+import "../../chunk-TJRTVJW5.js";
 export {
+  entitlementScope,
+  licenseDeclared,
   requestSalt,
-  resolveRequestScope
+  resolveRequestScope,
+  standardKeysFrom
 };

package/docs/spec-pipeline.md

@@ -47,6 +47,7 @@ candidate lanes → pool open → pool-level merges → refinement → window as
 | 9 | `lexical-union` | `lexicalHits.length` | blocking | appends `hits` | Full-corpus BM25 hits dense missed (dense metadata wins on id collision). |
 | 10 | `federate` | `opts.federate` | additive (callback catches transport) | appends `hits` | Internal ISO/IEC passages at `federateDiscount`. |
 | 11 | `seal` | `opts.sealScope` | blocking | filters `hits` | The declared context's hard cut: nothing outside the declared family reaches rerank. (The lexical lane is sealed at the SOURCE, in the prelude — not here.) |
+| 11b | `license-scope` | `opts.standardKeys` | blocking | filters `hits` | The license entitlement hard cut (TODO.external-refs/08): a chunk carrying a `standard_key` outside the caller's set never reaches rerank; public chunks (no key) always pass. (The lexical lane is bound at the SOURCE, in the prelude — the lexical union AND the post-rerank lexical-rrf consume the bound list. The post-scope single-document 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; citation-probe filters its bibliography push by the same predicate.) |
 | 12 | `overview-demote` | — | blocking | mutates `hits[].score` | Overview boilerplate demotion (`overviewDemotion`). |
 | 13 | `family-boost` | boost only under `filter.doc_number`; sort always | blocking | mutates `hits[].score`, sorts | Family chunks decisively boosted for doc-scoped queries; the sort establishes the rerank-failure fallback order. |
 | 14 | `rerank` | `hits.length > 1` | additive | `hits[].rerank_score`, sorts, family pin | Cross-encoder scores; vector order is the designed fallback. Post-rerank family pin for doc-scoped queries. |

package/package.json

@@ -36,7 +36,7 @@
     "@konneal/engine": "github:konneal/engine#2d6c39b",
     "@oimlsmart/oiml-pubid": "^1.2.1"
   },
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "The Konneal engine: the publisher-agnostic build pipeline and API plane for standards intelligence (retrieval, answer contract, verdicts, evaluation).",
   "license": "BSD-3-Clause",
   "type": "module",

package/profile/prompts.yaml

@@ -17,3 +17,17 @@ vars:
   docid_example: "FIXTURE 1-2"
   spelling_examples: '"f1", "FIXTURE 1"'
   process_vocab: "the fixture certification system framework"
+  # the license declare flow (TODO.external-refs/08): where an org admin
+  # declares a standards license — the boundary refusal's pointer
+  license_declare_pointer: "org admin → Settings → Standards licenses"
+  # the licensed-content posture (TODO.external-refs/08): how the answer
+  # model behaves when a question hits the license boundary (the
+  # per-question note rides the retrieval-note channel)
+  license_posture: >-
+    Some indexed publications are LICENSED. When a license boundary note
+    names the question's publication, obey it: answer at the citation
+    level only — the standard's title and edition, and the invoking clause
+    the public passages carry — never state, paraphrase or "summarize from
+    memory" any procedure of the licensed text, and point at the declare
+    flow the note names. Public content (the Recommendations' own models,
+    applicability and references) stays fully answerable.

package/profile/sources.yaml

@@ -3,3 +3,12 @@ corpora:
 bibliography: {}
 terminology: {}
 models: {}
+# the licensed-standards declaration (TODO.external-refs/08): the
+# entitlement keys the deployment's index may carry (`standard_key` chunk
+# metadata, from the packages' license_key facet) — this list is the
+# whitelist the request's entitlement set validates against, and the
+# package/doc-number mapping the ask path gates model bindings with.
+# Absent or empty = the deployment serves public content only. The
+# fixture declares one so the license scope rides every engine test.
+licensed:
+  - { key: "std:fixture-60068-2-30", package: "fixture-60068-2-30", doc_number: "60068-2-30", title: "FIXTURE environmental testing — damp heat, cyclic", edition: "2005" }

package/workers/shared/chunk.ts

@@ -35,6 +35,12 @@ export interface ChunkMeta {
   model_node?: string;
   model_kind?: string;
   standard?: string;
+  /** The license entitlement key (the package's `license_key` facet, e.g.
+   *  `std:iec-60068-2-30`) — present ONLY when the chunk's content comes
+   *  from a licensed package; public content carries none. The ask path's
+   *  hard scope (stages/licenseScope.ts) drops chunks whose key is absent
+   *  from the caller's entitlement set, before ranking. */
+  standard_key?: 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
@@ -83,6 +89,7 @@ export const CHUNK_META_FIELDS = [
   "model_node",
   "model_kind",
   "standard",
+  "standard_key",
   "section_summary",
   "child_anchors",
   "ctx",

package/workers/worker_internal/src/index.ts

@@ -85,7 +85,7 @@ async function adminSyncRoute(c: RouteContext): Promise<Response> {
     if (Array.isArray(body?.upserts)) {
       for (let i = 0; i < body.upserts.length; i += 100) {
         const batch = body.upserts.slice(i, i + 100).filter((v: any) => v?.id && Array.isArray(v?.values) && v?.metadata);
-        if (batch.length) await env.PUBLIC.upsert(batch);
+        if (batch.length) await env.INTERNAL.upsert(batch);
         out.upserted += batch.length;
       }
     }
@@ -94,14 +94,14 @@ async function adminSyncRoute(c: RouteContext): Promise<Response> {
       for (let i = 0; i < todo.length; i += 16) {
         const batch = todo.slice(i, i + 16);
         const vectors = await Promise.all(batch.map((b: any) => embed(env.AI, b.text.slice(0, 6000))));
-        await env.PUBLIC.upsert(batch.map((b: any, j: number) => ({ id: b.id, values: vectors[j], metadata: b.metadata })));
+        await env.INTERNAL.upsert(batch.map((b: any, j: number) => ({ id: b.id, values: vectors[j], metadata: b.metadata })));
         out.embedded += batch.length;
       }
     }
     if (Array.isArray(body?.deletes)) {
       const ids = body.deletes.filter((x: any) => typeof x === "string");
       for (let i = 0; i < ids.length; i += 100) {
-        await env.PUBLIC.deleteByIds(ids.slice(i, i + 100));
+        await env.INTERNAL.deleteByIds(ids.slice(i, i + 100));
         out.deleted += Math.min(100, ids.length - i);
       }
     }

package/workers/worker_public/openapi.yaml

@@ -102,7 +102,8 @@ paths:
         Identical to /api/ask, with authentication by API key and a
         per-key daily allowance. Streaming responses are available by
         setting stream to true, which returns a server-sent event stream
-        whose events carry citations, tokens and the completion marker.
+        whose first event is the reading, then the citations, then the
+        answer tokens, and finally the completion marker.
       operationId: askKeyed
       security:
         - bearerAuth: []
@@ -1103,8 +1104,10 @@ components:
           type: boolean
           default: false
           description: >-
-            When true, the response is a server-sent event stream whose
-            events carry citations, tokens and the completion marker.
+            When true, the response is a server-sent event stream. The
+            first event is the reading (how the service interpreted the
+            question), then the citations, then the answer tokens, and
+            finally the completion marker.
         fresh:
           type: boolean
           default: false
@@ -1164,6 +1167,28 @@ components:
         query_hash:
           type: string
           description: The hash of the question, used for feedback.
+        read:
+          type: object
+          description: >-
+            How the service read the question — the interpretation that
+            steered retrieval. Present on fresh answers; absent on exact
+            cache hits, which never re-ran understanding.
+          properties:
+            intent: { type: string }
+            doc: { type: string, nullable: true }
+            edition: { type: string, nullable: true }
+            term: { type: string, nullable: true }
+            terms:
+              type: array
+              items: { type: string }
+            lang: { type: string, nullable: true }
+        served_from:
+          type: string
+          enum: [cache, similar]
+          description: >-
+            Present when the answer was served from the answer cache for
+            an identical or similar earlier question. The cache stores the
+            answer and never the passages.
         quota:
           type: object
           description: The remaining daily allowance.

package/workers/worker_public/prompts/system.md

@@ -14,6 +14,7 @@ Synthesize practical answers from the passages: definitions, procedures and rule
 MANDATORY: when the question asks how to do something (get certified, apply, comply, register, test) and the passages describe the governing system or procedure, ALWAYS answer with that procedure citing the governing documents. Refusing such a question because the passages do not name the specific publication is WRONG — the publication sets technical requirements; the HOW is governed by the certification-system documents in the passages.
 If the passages cover only part of the question, answer the covered part fully, then state precisely what the indexed publications do not cover — do not pad with outside knowledge.
 Refuse ONLY when no passage relates to the question's topic. Use exactly this sentence: {{REFUSAL_SENTENCE}} Then add one short line naming what you can answer instead, so the refusal redirects rather than dead-ends.
+{{LICENSE_POSTURE}}
 {{CORPUS_NOTES}}
 Lead with the direct answer, then supporting detail; no preamble like 'Based on the passages'. Use short paragraphs or bullets for multi-part answers. Be concise and precise. Answer in the question's language{{LANG_CLAUSE}}.
 - HARD RULE — typed units: passages whose header shows `unit u:xxxx (table)` contain a typed table. If your answer presents that table's data, you MUST write the token `[[u:xxxx]]` where the table belongs and MUST NOT render the table as markdown or reproduce more than ONE of its rows inline. Summarize the pattern in prose ("classes A–D with lower limits from 100 to 50 000"), cite the clause normally, and let `[[u:xxxx]]` stand for the full table — the interface renders it exactly from the source. The same rule applies to `unit u:xxxx (formula|figure|term)` objects.

package/workers/worker_public/src/ask.ts

@@ -19,11 +19,11 @@ import { contractV2, tableRetyped } from "./refs";
 import { completeTables, completeFigures } from "./completion";
 import { NO_CONTEXT, appliedContext, contextNote, namedDocumentIn, parseContext, resolveDocScope, syntheticUnderstanding } from "./context";
 import { exchangeForLiveToken, liveDataConfig, resolveLiveAccount, type LiveRecord } from "./livedata";
-import { bindModelNode, modelCitation, modelEcho, modelGroundingBlock, modelNodeRefIn, standardForDocNumber } from "./modelplane";
+import { bindModelNode, licenseBoundaryNote, licenseBoundaryRefusal, modelCitation, modelEcho, modelGroundingBlock, modelNodeRefIn, standardForDocNumber } from "./modelplane";
 import { evaluate as machineEvaluate, verdictNote } from "./verdict";
 import { detectDraftIntent, prepareDraft } from "./drafts";
 import { memoryNote } from "./memories";
-import { resolveRequestScope, requestSalt } from "./requestScope";
+import { entitlementScope, resolveRequestScope, requestSalt } from "./requestScope";
 import { rawSessionToken } from "./session";
 import { cacheKeyMaterial, corpusGen, exactCacheKey, freshRequested, semanticCacheKey } from "./answercache";
 import type { Env } from "./env";
@@ -308,6 +308,13 @@ async function handleAsk(
   const scope = resolveRequestScope(body, member);
   if ("error" in scope) return err(400, "invalid_input", "datasets: at least one dataset must stay enabled");
   const { corpora, narrowed, isoOn } = scope;
+  // The license entitlement set (TODO.external-refs/08): request-scoped,
+  // validated against the profile's declared licensed list; the hard
+  // retrieval scope it feeds is fail-closed (an unentitled ask — empty
+  // set, the anon default — never sees licensed chunks, citation-level
+  // metadata stays). It salts the answer cache with the effort segment
+  // below.
+  const standardKeys = entitlementScope(scope.standardKeys);
   // Personalized memory files (#171): member-scoped, selected per ask;
   // the note rides buildMessages as a trusted-user-facts preamble, and
   // the selections SALT the answer cache (requestScope.requestSalt).
@@ -551,9 +558,14 @@ async function handleAsk(
         telemetry(env, ctx, tier, "ask", null, true, sc.answer.length, sc.query_hash, q.lang, "semantic", telemetryMeta());
         const cctx = sc.context_applied ?? NO_CONTEXT;
         if (wantsStream) {
-          return sseResponse([{ type: "citations", citations: sc.citations ?? [], context_applied: cctx }, { type: "token", v: sc.answer }, { type: "done", model: sc.model, query_hash: sc.query_hash, similar: true, served_from: "similar", context_applied: cctx }], corsHeaders(req));
+          return sseResponse([
+            ...(readAs() ? [{ type: "read", read: readAs() }] : []),
+            { type: "citations", citations: sc.citations ?? [], context_applied: cctx },
+            { type: "token", v: sc.answer },
+            { type: "done", model: sc.model, query_hash: sc.query_hash, similar: true, served_from: "similar", context_applied: cctx, read: readAs() },
+          ], corsHeaders(req));
         }
-        return json({ ...sc, similar: true, context_applied: cctx, quota, });
+        return json({ ...sc, similar: true, context_applied: cctx, read: readAs(), quota, });
       }
     }
   }
@@ -579,6 +591,8 @@ async function handleAsk(
         const sse = new ReadableStream({
           async start(controller) {
             const send = (obj: unknown) => controller.enqueue(encoder.encode(`data: ${JSON.stringify(obj)}\n\n`));
+            // the reading arrives first — a conversational turn is still a reading
+            if (readAs()) send({ type: "read", read: readAs() });
             send({ type: "citations", citations: [], context_applied: NO_CONTEXT, quota, });
             let full = "";
             try {
@@ -589,7 +603,7 @@ async function handleAsk(
             } catch {
               // stream ended prematurely — deliver what we have
             }
-            send({ type: "done", model, query_hash: queryHash, context_applied: NO_CONTEXT });
+            send({ type: "done", model, query_hash: queryHash, context_applied: NO_CONTEXT, read: readAs() });
             telemetry(env, ctx, tier, "ask", model, true, full.length, queryHash, q.lang, undefined, telemetryMeta());
             controller.close();
           },
@@ -606,7 +620,7 @@ async function handleAsk(
       return err(502, "generation_failed", "The generation model is unavailable; please retry.");
     }
     telemetry(env, ctx, tier, "ask", model, true, answer.length, queryHash, q.lang, undefined, telemetryMeta());
-    return json({ answer, citations: [], model, query_hash: queryHash, follow_ups: [], context_applied: NO_CONTEXT, quota, });
+    return json({ answer, citations: [], model, query_hash: queryHash, follow_ups: [], context_applied: NO_CONTEXT, read: readAs(), quota, });
   }
 
   // ── The draft act (TODO.ai-platform/04) — the assistant PREPARES, the
@@ -652,14 +666,15 @@ async function handleAsk(
     if (wantsStream) {
       return sseResponse(
         [
+          ...(readAs() ? [{ type: "read", read: readAs() }] : []),
           { type: "citations", citations, context_applied: draftCtxApplied, ...(draftPayload ? { draft: draftPayload } : {}), quota, },
           { type: "token", v: verdict.answer },
-          { type: "done", model, query_hash: queryHash, context_applied: draftCtxApplied },
+          { type: "done", model, query_hash: queryHash, context_applied: draftCtxApplied, read: readAs() },
         ],
         corsHeaders(req),
       );
     }
-    return json({ answer: verdict.answer, citations, model, query_hash: queryHash, follow_ups: [], context_applied: draftCtxApplied, ...(draftPayload ? { draft: draftPayload } : {}), quota, });
+    return json({ answer: verdict.answer, citations, model, query_hash: queryHash, follow_ups: [], context_applied: draftCtxApplied, read: readAs(), ...(draftPayload ? { draft: draftPayload } : {}), quota, });
   }
 
   // (declared before the retrieval try: the account block, the refusal
@@ -684,18 +699,23 @@ async function handleAsk(
         label: declaredCtx?.label,
         query: q.query,
         standard: standardForDocNumber(modelDocHint?.doc_number),
+        standardKeys,
       })
     : null;
   if (boundModel) {
     ctxApplied = { ...ctxApplied, model: modelEcho(boundModel) };
-    console.log("model plane: bound", boundModel.node_id, `[${boundModel.standard}]`, boundModel.clause?.urn ?? "no-clause");
+    console.log("model plane: bound", boundModel.node_id, `[${boundModel.standard}]`, boundModel.clause?.urn ?? "no-clause", boundModel.gated ? "(gated: license)" : "");
   }
-  const modelNote = boundModel ? modelGroundingBlock(boundModel) : undefined;
+  // A GATED binding (licensed package, unentitled caller) keeps its
+  // citation + echo — metadata the honesty posture keeps — and withholds
+  // the grounding block and the verdict engine: no licensed machine
+  // content enters the prompt by the binding lane either.
+  const modelNote = boundModel && !boundModel.gated ? modelGroundingBlock(boundModel) : undefined;
   // ── the verdict engine (TODO.era3/01) ──
   // the worker EXECUTES the bound node's machine checks against the
   // question's stated values; the model narrates the computed verdict
   // and the verdict BLOCK is server-built — data, never generated prose
-  const machineVerdict = boundModel ? machineEvaluate(boundModel.content, q.query) : null;
+  const machineVerdict = boundModel && !boundModel.gated ? machineEvaluate(boundModel.content, q.query) : null;
   const machineNote = machineVerdict && boundModel ? verdictNote(machineVerdict, boundModel) : undefined;
   const verdictBlock = machineVerdict
     ? {
@@ -768,7 +788,7 @@ async function handleAsk(
     // publications there).
     retrieved = await retrieve(env, q.query, { prev, understanding, federate, warmEmbed, graphDocNumbers,
       sealScope: declaredScoped ? docScope : null, optimisticHits, optimisticVec,
-      datasetScope: narrowed ? corpora : null });
+      datasetScope: narrowed ? corpora : null, standardKeys });
     stageTiming["retrieve-core"] = Date.now() - tR;
     console.log("stage: retrieve", Date.now() - tR, "ms");
     // ── TTFT surgery: the two post-retrieval LLM calls run IN PARALLEL —
@@ -802,7 +822,7 @@ async function handleAsk(
     if (grade === "weak" && understanding?.docidentifier) {
       const broaden = `${understanding.standalone_query || q.query} ${understanding.docidentifier}`.trim();
       const tc = Date.now();
-      const second = await retrieve(env, q.query, { prev, understanding, queryOverride: broaden, federate, datasetScope: narrowed ? corpora : null });
+      const second = await retrieve(env, q.query, { prev, understanding, queryOverride: broaden, federate, datasetScope: narrowed ? corpora : null, standardKeys, sealScope: declaredScoped ? docScope : null });
       const grade2 = await gradeRetrieval(env.AI, roleModel(env, "grader"), q.query, second.hits.map((h: Hit) => h.text));
       stageTiming.corrective = Date.now() - tc;
       if (grade2 === "good") retrieved = second; // corrective retry must be strictly better
@@ -813,8 +833,13 @@ async function handleAsk(
     return err(503, "retrieval_unavailable", "Search is briefly busy — please retry in a moment.");
   }
   const { hits } = retrieved;
-  if (hits.length === 0 && !liveRecords?.length && !boundModel) {
-    const answer = refusalAnswer();
+  if (hits.length === 0 && !liveRecords?.length && (!boundModel || boundModel.gated)) {
+    // the license boundary refusal (TODO.external-refs/08) outranks the
+    // plain "no information" sentence when the question's publication is
+    // licensed and unentitled: name the standard, state the boundary,
+    // point at the declare flow
+    const answer =
+      licenseBoundaryRefusal(modelDocHint?.doc_number ?? understanding?.doc_number ?? null, standardKeys) ?? refusalAnswer();
     const out = { answer, citations: [], model, query_hash: await sha256Hex(q.query), context_applied: ctxApplied };
     telemetry(env, ctx, tier, "ask", model, true, answer.length, out.query_hash, q.lang, undefined, telemetryMeta());
     return json({ ...out, quota, });
@@ -823,6 +848,11 @@ async function handleAsk(
   const processNote = understanding?.process_intent
     ? P().retrieval.process_note
     : undefined;
+  // the license boundary (TODO.external-refs/08): the question's named or
+  // understood publication is licensed and the caller's set lacks the key
+  // — the refusal-class note rides the retrieval-note channel beside the
+  // other structured facts
+  const licenseNote = licenseBoundaryNote(modelDocHint?.doc_number ?? understanding?.doc_number ?? null, standardKeys);
   // the vocabulary binding (L2): the corpus's defined-term candidates for
   // the question's subject — the model adjudicates among them and uses
   // the corpus term (with its defining publication) when it names the
@@ -851,7 +881,7 @@ async function handleAsk(
     q.lang,
     keptHistory,
     // stage-extracted graph facts (GraphRAG) ride the same note channel
-    [processNote, eNote, contextNote(declaredCtx, docScope), accountNote, modelNote, vocabNote, memNote, machineNote, ...(retrieved.notes ?? [])].filter(Boolean).join("\n") || undefined,
+    [processNote, eNote, contextNote(declaredCtx, docScope), accountNote, modelNote, vocabNote, memNote, machineNote, licenseNote, ...(retrieved.notes ?? [])].filter(Boolean).join("\n") || undefined,
     summary,
     budget,
   );
@@ -886,6 +916,9 @@ async function handleAsk(
       const sse = new ReadableStream({
         async start(controller) {
           const send = (obj: unknown) => controller.enqueue(encoder.encode(`data: ${JSON.stringify(obj)}\n\n`));
+          // the reading arrives first: the interpretation that steered
+          // retrieval, before a single token of the answer
+          send({ type: "read", read: readAs() });
           send({ type: "citations", citations: cites, context_applied: ctxApplied, ...(liveRecords ? { records: liveRecords } : {}), quota, });
           let full = "";
           try {
@@ -1035,6 +1068,7 @@ async function handleAsk(
         understanding: { ...understanding, standalone_query: `${understanding?.standalone_query || q.query} ${reflection.missing_info}` } as any,
         sealScope: declaredScoped ? docScope : null,
         datasetScope: narrowed ? corpora : null,
+        standardKeys,
       });
       if (retryRetrieve.hits.length > 0) {
         const { messages: retryMessages, usedHits: retryUsed } = buildMessages(q.query, retryRetrieve.hits, q.lang, keptHistory, undefined, summary, budget);