@superatomai/sdk-node 0.0.56-dsp → 0.0.57-dsp

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   DEFAULT_AGENT_CONFIG: () => DEFAULT_AGENT_CONFIG,
   LLM: () => LLM,
   MainAgent: () => MainAgent,
+  MissingRequestContextError: () => MissingRequestContextError,
   STORAGE_CONFIG: () => STORAGE_CONFIG,
   ScriptMatcher: () => ScriptMatcher,
   ScriptStore: () => ScriptStore,
@@ -47,36 +48,53 @@ __export(index_exports, {
   UserManager: () => UserManager,
   anthropicLLM: () => anthropicLLM,
   assertReadOnlySql: () => assertReadOnlySql,
+  bindContext: () => bindContext,
+  captureContext: () => captureContext,
+  clearContextTokens: () => clearContextTokens,
+  contextTokenCount: () => contextTokenCount,
   createCodexSession: () => createCodexSession,
   createCodingAgentSession: () => createCodingAgentSession,
   dashboardConversationHistory: () => dashboardConversationHistory,
   dataFingerprint: () => dataFingerprint,
+  describeContext: () => describeContext,
   describeTriggers: () => describeTriggers,
   emitAgentEvent: () => emitAgentEvent,
   extractNamedExport: () => extractNamedExport,
   geminiLLM: () => geminiLLM,
   getCodingAgent: () => getCodingAgent,
   getCodingAgentsConfig: () => getCodingAgentsConfig,
+  getRequestContext: () => getRequestContext,
   groqLLM: () => groqLLM,
   hybridRerank: () => hybridRerank,
+  isUserContext: () => isUserContext,
   listCodingAgents: () => listCodingAgents,
   llmUsageLogger: () => llmUsageLogger,
   logger: () => logger,
+  mintContextToken: () => mintContextToken,
   normalizeScriptBody: () => normalizeScriptBody,
   onAgentRun: () => onAgentRun,
   openaiLLM: () => openaiLLM,
+  policiesFromConfig: () => policiesFromConfig,
   queryCache: () => queryCache,
   registerCodingAgentCollection: () => registerCodingAgentCollection,
   registerCodingAgents: () => registerCodingAgents,
   registerDashboardAgentCollection: () => registerDashboardAgentCollection,
+  requireRequestContext: () => requireRequestContext,
   rerankChromaResults: () => rerankChromaResults,
   rerankConversationResults: () => rerankConversationResults,
+  resolveContextToken: () => resolveContextToken,
   resolveScriptRecipeStore: () => resolveScriptRecipeStore,
+  revokeContextToken: () => revokeContextToken,
+  runAsSystem: () => runAsSystem,
+  runAsUser: () => runAsUser,
   runCodingAgent: () => runCodingAgent,
   runScript: () => runScript,
+  runWithContext: () => runWithContext,
+  runWithMessageIdentity: () => runWithMessageIdentity,
   startAgentTriggers: () => startAgentTriggers,
   stopAgentTriggers: () => stopAgentTriggers,
   userPromptErrorLogger: () => userPromptErrorLogger,
+  withCapturedContext: () => withCapturedContext,
   writeBridgeShims: () => writeBridgeShims
 });
 module.exports = __toCommonJS(index_exports);
@@ -360,11 +378,17 @@ var UserPromptRequestPayloadSchema = import_zod3.z.object({
   }).optional(),
   responseMode: import_zod3.z.enum(["component", "text"]).optional()
 });
+var MessageAuthContextSchema = import_zod3.z.object({
+  userId: import_zod3.z.string(),
+  orgId: import_zod3.z.string().optional(),
+  role: import_zod3.z.string().optional()
+});
 var UserPromptRequestMessageSchema = import_zod3.z.object({
   id: import_zod3.z.string(),
   from: MessageParticipantSchema,
   type: import_zod3.z.literal("USER_PROMPT_REQ"),
-  payload: UserPromptRequestPayloadSchema
+  payload: UserPromptRequestPayloadSchema,
+  authContext: MessageAuthContextSchema.optional()
 });
 var UserPromptAbortRequestPayloadSchema = import_zod3.z.object({
   uiBlockId: import_zod3.z.string(),
@@ -814,7 +838,8 @@ var DashCompRequestMessageSchema = import_zod3.z.object({
   id: import_zod3.z.string(),
   from: MessageParticipantSchema,
   type: import_zod3.z.literal("DASH_COMP_REQ"),
-  payload: DashCompRequestPayloadSchema
+  payload: DashCompRequestPayloadSchema,
+  authContext: MessageAuthContextSchema.optional()
 });
 var DashboardAgentRequestPayloadSchema = import_zod3.z.object({
   prompt: import_zod3.z.string(),
@@ -887,7 +912,8 @@ var ReportCompRequestMessageSchema = import_zod3.z.object({
   id: import_zod3.z.string(),
   from: MessageParticipantSchema,
   type: import_zod3.z.literal("REPORT_COMP_REQ"),
-  payload: ReportCompRequestPayloadSchema
+  payload: ReportCompRequestPayloadSchema,
+  authContext: MessageAuthContextSchema.optional()
 });
 var ReportCompAbortRequestPayloadSchema = import_zod3.z.object({
   reportId: import_zod3.z.string()
@@ -1681,6 +1707,101 @@ var ThreadManager = class _ThreadManager {
 
 // src/utils/query-cache.ts
 var import_crypto3 = __toESM(require("crypto"));
+
+// src/utils/request-context.ts
+var import_async_hooks = require("async_hooks");
+var STORAGE_KEY = Symbol.for("superatom.requestContext.v1");
+function getStorage() {
+  const g = globalThis;
+  let store = g[STORAGE_KEY];
+  if (!store) {
+    store = new import_async_hooks.AsyncLocalStorage();
+    g[STORAGE_KEY] = store;
+  }
+  return store;
+}
+function enforcementApplies() {
+  return (process.env.SA_SQL_REWRITE_MODE || "").toLowerCase() === "enforce";
+}
+function getRequestContext() {
+  return getStorage().getStore();
+}
+function requireRequestContext(what = "this operation") {
+  const ctx = getStorage().getStore();
+  if (!ctx) {
+    throw new MissingRequestContextError(
+      `No request context for ${what}. The caller must establish one with runWithContext() or declare itself trusted with runAsSystem().`
+    );
+  }
+  return ctx;
+}
+var MissingRequestContextError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MissingRequestContextError";
+  }
+};
+function runWithContext(ctx, fn) {
+  return getStorage().run(ctx, fn);
+}
+function runAsUser(user, fn) {
+  const { userId, orgId, role, projectId, requestId, policies } = user;
+  return runWithContext(
+    { principal: { kind: "user", userId, orgId, role }, projectId, requestId, policies },
+    fn
+  );
+}
+function runAsSystem(reason, fn, opts) {
+  if (!reason || !reason.trim()) {
+    throw new Error("runAsSystem() requires a non-empty reason \u2014 it identifies the path in the audit log.");
+  }
+  return runWithContext(
+    { principal: { kind: "system", reason: reason.trim() }, projectId: opts?.projectId, requestId: opts?.requestId },
+    fn
+  );
+}
+function captureContext() {
+  return getStorage().getStore();
+}
+function withCapturedContext(ctx, fn) {
+  return ctx ? runWithContext(ctx, fn) : fn();
+}
+function bindContext(fn) {
+  const captured = captureContext();
+  return (...args) => withCapturedContext(captured, () => fn(...args));
+}
+function describeContext(ctx = getRequestContext()) {
+  if (!ctx) return "anonymous";
+  return ctx.principal.kind === "user" ? `user:${ctx.principal.userId}` : `system:${ctx.principal.reason}`;
+}
+function isUserContext(ctx = getRequestContext()) {
+  return ctx?.principal.kind === "user";
+}
+
+// src/utils/query-cache.ts
+var fingerprints = /* @__PURE__ */ new WeakMap();
+function canonicalPolicies(policies) {
+  const norm = policies.map((p) => ({
+    s: p.sourceId ?? "*",
+    t: [...p.readableTables ?? []].sort(),
+    f: (p.rowFilters ?? []).map((f) => ({
+      t: f.table ?? "*",
+      c: f.column,
+      o: f.op ?? "in",
+      v: [...f.values ?? []].map((v) => String(v)).sort()
+    })).sort((a, b) => `${a.t}.${a.c}.${a.o}`.localeCompare(`${b.t}.${b.c}.${b.o}`))
+  }));
+  norm.sort((a, b) => a.s.localeCompare(b.s));
+  return JSON.stringify(norm);
+}
+function policyFingerprint(policies) {
+  const memo = fingerprints.get(policies);
+  if (memo !== void 0) return memo;
+  const fp = import_crypto3.default.createHash("sha256").update(canonicalPolicies(policies)).digest("hex").slice(0, 16);
+  fingerprints.set(policies, fp);
+  return fp;
+}
+var warnedNoContext = false;
 var QueryCache = class {
   constructor() {
     this.cache = /* @__PURE__ */ new Map();
@@ -1712,6 +1833,31 @@ var QueryCache = class {
   getTTL() {
     return this.ttlMs / 60 / 1e3;
   }
+  /**
+   * Which access bucket this call reads and writes.
+   *
+   * `''` means the unrestricted bucket and produces a key identical to the one
+   * used before authorization existed. `null` means do not touch the cache.
+   */
+  scope() {
+    if (!enforcementApplies()) return "";
+    const ctx = getRequestContext();
+    if (!ctx) {
+      if (!warnedNoContext) {
+        warnedNoContext = true;
+        logger.warn("[QueryCache] bypassed \u2014 no request context under SA_SQL_REWRITE_MODE=enforce");
+      }
+      return null;
+    }
+    const policies = ctx.policies ?? [];
+    return policies.length ? policyFingerprint(policies) : "";
+  }
+  /** The stored key: the scope namespace, then the caller's key. NUL cannot occur in SQL. */
+  scopedKey(query) {
+    const s = this.scope();
+    if (s === null) return null;
+    return s ? `${s}\0${query}` : query;
+  }
   /**
    * Store query result in data cache.
    * If the key already exists, it's removed first so the re-insert places it
@@ -1719,12 +1865,14 @@ var QueryCache = class {
    * a genuinely new key past the size limit.
    */
   set(query, data) {
-    this.cache.delete(query);
+    const key = this.scopedKey(query);
+    if (key === null) return;
+    this.cache.delete(key);
     if (this.cache.size >= this.maxCacheSize) {
       const oldestKey = this.cache.keys().next().value;
       if (oldestKey) this.cache.delete(oldestKey);
     }
-    this.cache.set(query, {
+    this.cache.set(key, {
       query,
       data,
       timestamp: Date.now()
@@ -1737,14 +1885,16 @@ var QueryCache = class {
    * iteration order — turning FIFO eviction into true LRU.
    */
   get(query) {
-    const entry = this.cache.get(query);
+    const key = this.scopedKey(query);
+    if (key === null) return null;
+    const entry = this.cache.get(key);
     if (!entry) return null;
     if (Date.now() - entry.timestamp > this.ttlMs) {
-      this.cache.delete(query);
+      this.cache.delete(key);
       return null;
     }
-    this.cache.delete(query);
-    this.cache.set(query, entry);
+    this.cache.delete(key);
+    this.cache.set(key, entry);
     logger.info(`[QueryCache] Cache HIT for query (${query.substring(0, 50)}...)`);
     return entry.data;
   }
@@ -1758,7 +1908,8 @@ var QueryCache = class {
    * Remove a specific query from cache
    */
   delete(query) {
-    this.cache.delete(query);
+    const key = this.scopedKey(query);
+    if (key !== null) this.cache.delete(key);
   }
   /**
    * Clear all cached entries
@@ -2261,6 +2412,96 @@ function buildDirectToolCacheKey(toolId, parameters) {
   return `et-direct:${toolId}:${stableStringify(parameters || {})}`;
 }
 
+// src/handlers/request-identity.ts
+function policiesFromConfig(config2) {
+  const entries = Array.isArray(config2) ? config2 : [config2];
+  const out = [];
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    const e = entry;
+    const rawFilters = Array.isArray(e.rowFilters) ? e.rowFilters : [];
+    const rowFilters = [];
+    for (const f of rawFilters) {
+      if (!f || typeof f !== "object") continue;
+      const rf = f;
+      if (typeof rf.column !== "string" || !rf.column) continue;
+      if (!Array.isArray(rf.values) || rf.values.length === 0) continue;
+      const op = typeof rf.op === "string" ? rf.op.toLowerCase() : "in";
+      if (op !== "in" && op !== "not_in" && op !== "eq" && op !== "ne") continue;
+      rowFilters.push({
+        table: typeof rf.table === "string" && rf.table ? rf.table : void 0,
+        column: rf.column,
+        op,
+        values: rf.values,
+        label: typeof rf.label === "string" && rf.label.trim() ? rf.label.trim() : void 0
+      });
+    }
+    const readableTables = Array.isArray(e.readableTables) ? e.readableTables.filter((t) => typeof t === "string" && !!t) : [];
+    if (rowFilters.length === 0 && readableTables.length === 0) continue;
+    const label = typeof e.label === "string" && e.label.trim() ? e.label.trim() : void 0;
+    if (!label && rowFilters.some((f) => !f.label) && !warnedUnlabelled) {
+      warnedUnlabelled = true;
+      logger.warn(
+        '[RequestIdentity] An access policy has no "label" \u2014 the agent will describe it to the user as a raw SQL predicate. Add a short noun phrase, e.g. "label": "Hyderabad branch".'
+      );
+    }
+    out.push({
+      sourceId: typeof e.sourceId === "string" && e.sourceId ? e.sourceId : null,
+      label,
+      rowFilters,
+      readableTables
+    });
+  }
+  return out;
+}
+var warnedUntrusted = false;
+var warnedAnonymous = false;
+var warnedUnlabelled = false;
+var announcedVerified = false;
+var reportedIdMismatches = /* @__PURE__ */ new Set();
+function runWithMessageIdentity(message, fn) {
+  const verified = message?.authContext;
+  const requestId = message?.id;
+  const policies = policiesFromConfig(message?.payload?.config);
+  if (verified?.userId) {
+    const claimedId = message?.payload?.userId;
+    if (!announcedVerified) {
+      announcedVerified = true;
+      logger.info(
+        `[RequestIdentity] Using the relay-verified authContext as the principal (userId ${verified.userId})${claimedId ? `; client claimed ${claimedId === verified.userId ? "the same id" : claimedId}` : ""}.`
+      );
+    }
+    if (claimedId && claimedId !== verified.userId) {
+      const pair = `${verified.userId}<-${claimedId}`;
+      if (!reportedIdMismatches.has(pair) && reportedIdMismatches.size < 100) {
+        reportedIdMismatches.add(pair);
+        logger.warn(
+          `[RequestIdentity] IDENTITY MISMATCH: the verified session says userId=${verified.userId} but the client sent payload.userId=${claimedId}. The verified id wins. Anything keyed on the principal (conversation history, threads, bookmarks) will look EMPTY for this user until the two agree.`
+        );
+      }
+    }
+    return runAsUser(
+      { userId: verified.userId, orgId: verified.orgId, role: verified.role, requestId, policies },
+      fn
+    );
+  }
+  const claimed = message?.payload?.userId;
+  if (typeof claimed === "string" && claimed) {
+    if (!warnedUntrusted) {
+      warnedUntrusted = true;
+      logger.warn(
+        "[RequestIdentity] Using the client-supplied payload.userId as the principal \u2014 the relay is not stamping a verified authContext yet, so this identity is NOT trustworthy. Fine for plumbing; do not enable policy enforcement until the relay change lands."
+      );
+    }
+    return runAsUser({ userId: claimed, requestId, policies }, fn);
+  }
+  if (!warnedAnonymous) {
+    warnedAnonymous = true;
+    logger.info("[RequestIdentity] No user identity on this message \u2014 running without a request context.");
+  }
+  return fn();
+}
+
 // src/handlers/data-request.ts
 function getQueryCacheKey(query) {
   if (typeof query === "string") {
@@ -2300,6 +2541,9 @@ function getCacheKey(collection, op, params, tools) {
   return "";
 }
 async function handleDataRequest(data, collections, sendMessage, tools) {
+  return runWithMessageIdentity(data, () => handleDataRequestInner(data, collections, sendMessage, tools));
+}
+async function handleDataRequestInner(data, collections, sendMessage, tools) {
   let requestId;
   let collection;
   let op;
@@ -7157,7 +7401,6 @@ Rules: state ONLY filters you actually applied (do not claim a filter you didn't
 ### Knowledge Base Context
 {{KNOWLEDGE_BASE_CONTEXT}}
 
-### User Access Scope
 {{USER_ACCESS_CONTEXT}}
 
 ### Conversation History
@@ -7187,7 +7430,6 @@ Your job is to fetch the requested data using the available tool.
 
 ### Critical Rules
 - **CRITICAL: Always apply the filtering rules from the Global Knowledge Base and Knowledge Base Context sections below.** These define how business entities should be filtered in queries. If a knowledge base entry specifies column conditions for an entity, ALWAYS include those conditions as WHERE clauses.
-- **CRITICAL: Always apply the restrictions in the User Access Scope section below \u2014 unlike other defaults in this prompt, this is NOT overridden by an explicit user request.** If it names a value for a dimension (e.g. a location/branch id) and this table has a column representing that dimension, ALWAYS filter on it, inferring the matching column from the schema. If the user explicitly asks for a different value on that dimension, do NOT fetch it \u2014 say they don't have access to it.
 - **CRITICAL: Follow ALL the database-specific SQL rules above.** These prevent syntax errors specific to this database engine. Violating them will cause query failures.
 - **CRITICAL ROW LIMIT: Every query MUST limit results to {{MAX_ROWS}} rows maximum.** {{ROW_LIMIT_SYNTAX}}. Queries without a row limit will be rejected. For UNION queries, apply the limit to the outermost query or to each branch.
 
@@ -7231,7 +7473,6 @@ Your job is to fetch the requested data using the available tool.
 ### Knowledge Base Context
 {{KNOWLEDGE_BASE_CONTEXT}}
 
-### User Access Scope
 {{USER_ACCESS_CONTEXT}}`,
     user: `Current Date and Time: {{CURRENT_DATETIME}}
 
@@ -9212,9 +9453,9 @@ var PromptLoader = class {
     const rulesPath = import_path3.default.join(this.promptsDir, "database-rules", `${this.databaseType}.md`);
     try {
       if (import_fs4.default.existsSync(rulesPath)) {
-        const rules = import_fs4.default.readFileSync(rulesPath, "utf-8");
-        this.databaseRulesCache.set(this.databaseType, rules);
-        return rules;
+        const rules2 = import_fs4.default.readFileSync(rulesPath, "utf-8");
+        this.databaseRulesCache.set(this.databaseType, rules2);
+        return rules2;
       }
     } catch (error) {
       logger.warn(`Could not load database rules for '${this.databaseType}' from file system: ${error}`);
@@ -9255,9 +9496,9 @@ var PromptLoader = class {
     const rulesPath = import_path3.default.join(this.promptsDir, "database-rules", `${dbType}.md`);
     try {
       if (import_fs4.default.existsSync(rulesPath)) {
-        const rules = import_fs4.default.readFileSync(rulesPath, "utf-8");
-        this.databaseRulesCache.set(dbType, rules);
-        return rules;
+        const rules2 = import_fs4.default.readFileSync(rulesPath, "utf-8");
+        this.databaseRulesCache.set(dbType, rules2);
+        return rules2;
       }
     } catch (error) {
       logger.warn(`Could not load database rules for '${dbType}' from file system: ${error}`);
@@ -9955,6 +10196,57 @@ function validateAndFixSqlQuery(query, dbType) {
   };
 }
 
+// src/userResponse/agents/access-section.ts
+var HEADING = "### User Access Scope";
+var enforced = enforcementApplies;
+var EMPTY_RESULT_RULE = `**An EMPTY result is not evidence of absence.** Zero rows under a restriction usually means the records are outside the user's access, not that they do not exist. Never report it as "no data found", "there are none", or "no records exist" \u2014 say the data is outside their access.`;
+function mainRule() {
+  return enforced() ? "**These restrictions are applied automatically to every query before it runs.** Do NOT write them into your SQL, into an INTENT you dispatch to a source, or into a saved script \u2014 a scope you add is redundant, and it goes stale the moment this user's access changes. Dispatch the question as the user asked it; the scope is enforced for you.\n**If the user names a value outside this scope** (by name or via a resolved id), do not query it \u2014 say they lack access. For a question mixing in-scope and out-of-scope items (a comparison, say), answer the part you can and state plainly which part you cannot.\n" + EMPTY_RESULT_RULE : "**CRITICAL: Apply this on every question and every dispatch \u2014 it overrides an explicit user request AND a resolved entity id.** If the user names a value outside this scope (by name or via a resolved id), do not query it \u2014 say they lack access. For a question mixing in-scope and out-of-scope items (a comparison, say), answer the part you can and state plainly which part you cannot.\n" + EMPTY_RESULT_RULE;
+}
+function sourceRule() {
+  return (enforced() ? "**These restrictions are already applied to every query before it runs.** Do NOT add them to your SQL \u2014 a filter you write is redundant at best, and stale the moment this user's access changes. Write the query as if unrestricted; the scope is enforced for you.\n" : "**CRITICAL: Apply these restrictions on every query \u2014 they override both an explicit user request AND a RESOLVED ENTITIES id.** If a restriction names a value for a dimension (e.g. a location/branch id) and the table you are querying has a column representing that dimension, ALWAYS filter on it, inferring the matching column from the schema. Never use the user's or a resolved id's value where it conflicts. On conflict, refuse and say the user lacks access \u2014 do not fetch.\n") + EMPTY_RESULT_RULE;
+}
+function editRule() {
+  return enforced() ? "**CRITICAL: this overrides the edit instruction.** The scope below is applied automatically on every run. If the script hardcodes any of it \u2014 as a SQL predicate or in its text \u2014 REMOVE it: a baked-in scope returns zero rows the moment this user's access changes. Never add one." : '**CRITICAL: this overrides the edit instruction.** A filter that conflicts with the scope below is not "correct as-is" \u2014 fix it regardless of what the edit instruction named.';
+}
+var rules = () => ({
+  main: mainRule(),
+  source: sourceRule(),
+  edit: editRule()
+});
+function buildAccessSection(renderedConfig, variant) {
+  const body = (renderedConfig || "").trim();
+  if (!body) return "";
+  return `${HEADING}
+${rules()[variant]}
+${body}`;
+}
+function buildAccessBodyContract(renderedConfig) {
+  if (!(renderedConfig || "").trim()) return "";
+  return `
+
+### Access policy \u2014 never write it into the script
+
+A query result may report that an authorization policy restricted it. That restriction is enforced
+automatically on every run, including replays. So:
+
+- **Never put a policy predicate in your SQL** (e.g. a branch/tenant/region id you were told was
+  applied). It is redundant, and it goes stale the moment that user's access changes \u2014 the recipe
+  would keep filtering on the old scope while the live policy applies the new one, giving zero rows.
+- **Never hardcode the scope in text.** \`getAnalysis\` and \`getComponents\` receive the restrictions
+  that actually applied to THIS run as their 6th argument, \`scope: string[]\`. Use it:
+
+\`\`\`js
+export function getAnalysis(data, params, fmt, datasets, entities, scope) {
+  const limitedTo = scope.length ? \` (\${scope.join('; ')})\` : '';
+  return { analysis: \`**\${fmt.num(data[0].Total)} records**\${limitedTo}.\` };
+}
+\`\`\`
+
+\`scope\` is empty when no policy applied, so the same body is correct for restricted and
+unrestricted users alike.`;
+}
+
 // src/userResponse/agents/source-agent.ts
 var SourceAgent = class {
   constructor(tool, config2, streamBuffer, options) {
@@ -10141,6 +10433,21 @@ Analyze the error and try again with a corrected query.`;
             name: this.tool.name,
             params: cappedInput,
             result: {
+              // The query was restricted before it ran. The agent cannot see
+              // this from the SQL it wrote — it wrote no such restriction — so
+              // without being told it labels the answer as if unrestricted.
+              // Confirmed live: a branch-scoped count reported as covering
+              // every branch, plus a wasted turn trying to remove a
+              // restriction that is re-applied to every query.
+              //
+              // The WORDING is a fixed, generic frame; the restrictions
+              // themselves are whatever the deployment's policy produced.
+              // Every client shares this code, so nothing here may assume a
+              // policy TYPE (row filter, masked column, restricted table) or
+              // any client's vocabulary.
+              ...result.metadata?.appliedPolicies?.length ? {
+                _ACCESS_POLICY_APPLIED: `An authorization policy restricted this query before it ran: ${result.metadata.appliedPolicies.join("; ")}. These results are ONLY what this user is permitted to see. State the restriction in titles, analysis and method lines; never present the figures as complete, overall, or covering everything. The policy is re-applied to every query, so rewriting without the restriction returns the same result \u2014 do not retry to widen it.`
+              } : {},
               ...hitFetchCap ? {
                 _WARNING_TRUNCATED: `This result FILLED the ${this.config.maxRowsFetched}-row fetch cap \u2014 it is a PARTIAL head slice, NOT the full result. There are almost certainly more rows, and (if ordered) often all from just the first few groups (e.g. the first districts alphabetically). Treat the set of districts/categories/entities and any count/total shown here as INCOMPLETE \u2014 never as the full set.`
               } : {},
@@ -10166,7 +10473,9 @@ Analyze the error and try again with a corrected query.`;
           const formatted = typeof formattedResult === "string" ? formattedResult : JSON.stringify(formattedResult);
           const followUpNote = successfulQueries < 2 ? "STOP now and return this data \u2014 it satisfies the intent in the common case. Make a second query ONLY if a column or row the intent explicitly requires is verifiably MISSING from these results (not merely to widen, re-sort, or double-check). A redundant follow-up wastes a full round-trip." : "Maximum queries reached. Use the data you have.";
           const capWarning = hitFetchCap ? ` \u26A0\uFE0F This filled the ${this.config.maxRowsFetched}-row fetch cap \u2014 a partial head slice; the groups/values shown are NOT the complete set.` : "";
-          return `\u2705 Query executed successfully. ${resultData.length} rows returned.${capWarning} ${followUpNote}
+          const emptyUnderPolicy = resultData.length === 0;
+          const policyNote = result.metadata?.appliedPolicies?.length ? ` \u{1F512} An authorization policy restricted this query before it ran: ${result.metadata.appliedPolicies.join("; ")}. These rows are ONLY what this user may see. ` + (emptyUnderPolicy ? `It returned ZERO rows UNDER THAT RESTRICTION \u2014 that is NOT evidence the records do not exist; they are most likely outside this user's access. Say that; never report it as "no data found" or "there are none". ` : "") + `Work that restriction into your wording naturally (e.g. "\u2026 for <restriction>"); never paste it in as a raw filter expression, and never call the figures complete or overall. The policy re-applies to every query, so re-running without it returns the same rows. Do NOT copy the restriction into your SQL or into a saved script: it is enforced automatically, and a policy written into a script goes stale the moment this user's access changes.` : "";
+          return `\u2705 Query executed successfully. ${resultData.length} rows returned.${capWarning}${policyNote} ${followUpNote}
 
 ${formatted}`;
         } catch (execError) {
@@ -10385,7 +10694,7 @@ Even if a table appears in the detailed schema above, search_schema returns samp
       logger.warn(`[SourceAgent:${this.tool.name}] Trace capture failed for schemaSearchInstructionsText (non-blocking): ${traceErr}`);
     }
     const displaySourceType = sourceType === "excel" || sourceType === "csv" ? `${sourceType} \u2014 uses DuckDB SQL engine` : sourceType;
-    const userAccessContextText = this.config.userAccessContext || "No user-specific access restrictions.";
+    const userAccessContextText = buildAccessSection(this.config.userAccessContext ?? "", "source");
     try {
       if (this.traceSchemaEntry) this.traceSchemaEntry.userAccessContextText = userAccessContextText;
     } catch (traceErr) {
@@ -10574,6 +10883,55 @@ var LineSplitter = class {
   }
 };
 
+// src/utils/context-token.ts
+var import_crypto5 = require("crypto");
+var DEFAULT_TTL_MS = 30 * 6e4;
+var KEY = Symbol.for("superatom.contextTokens.v1");
+function registry() {
+  const g = globalThis;
+  let m = g[KEY];
+  if (!m) {
+    m = /* @__PURE__ */ new Map();
+    g[KEY] = m;
+  }
+  return m;
+}
+function sweep(now = Date.now()) {
+  const reg = registry();
+  for (const [token, entry] of reg) {
+    if (entry.expiresAt <= now) reg.delete(token);
+  }
+}
+function mintContextToken(ttlMs = DEFAULT_TTL_MS) {
+  const ctx = captureContext();
+  if (!ctx) return void 0;
+  sweep();
+  const token = (0, import_crypto5.randomBytes)(24).toString("base64url");
+  registry().set(token, { ctx, expiresAt: Date.now() + ttlMs });
+  return token;
+}
+function resolveContextToken(token) {
+  if (!token) return void 0;
+  const entry = registry().get(token);
+  if (!entry) return void 0;
+  if (entry.expiresAt <= Date.now()) {
+    registry().delete(token);
+    logger.warn("[ContextToken] Rejected an expired token \u2014 the script outlived its context grant.");
+    return void 0;
+  }
+  return entry.ctx;
+}
+function revokeContextToken(token) {
+  if (token) registry().delete(token);
+}
+function contextTokenCount() {
+  sweep();
+  return registry().size;
+}
+function clearContextTokens() {
+  registry().clear();
+}
+
 // src/userResponse/scripts/script-runner.ts
 var fmtConfig;
 function setFmtConfig(cfg) {
@@ -10699,7 +11057,8 @@ FIX: pass every required parameter to execute_script, or give it a default in wr
       // analysisData: getData produces it
       void 0,
       // analysisDatasets: ctx.emit produces them
-      options.entities
+      options.entities,
+      options.appliedPolicies
     );
     const totalMs = Date.now() - startedAt;
     if (result.kind === "ok") {
@@ -10747,10 +11106,11 @@ FIX: pass every required parameter to execute_script, or give it a default in wr
     scriptSemaphore.release();
   }
 }
-function executeInSubprocess(scriptPath, params, paramSchema, externalTools, streamBuffer, timeoutMs, signal, mode, analysisData, analysisDatasets, entities) {
+function executeInSubprocess(scriptPath, params, paramSchema, externalTools, streamBuffer, timeoutMs, signal, mode, analysisData, analysisDatasets, entities, appliedPolicies) {
   return new Promise((resolve2) => {
     const tsxBin = resolveTsxBinary();
     const bootstrap = resolveBootstrapPath();
+    const contextToken = mintContextToken();
     const child = (0, import_child_process.spawn)(
       process.execPath,
       // node — tsx runs via its own cli, we invoke it with node
@@ -10769,7 +11129,12 @@ function executeInSubprocess(scriptPath, params, paramSchema, externalTools, str
         env: {
           ...process.env,
           // Keep the child quiet about dotenv etc.
-          NODE_NO_WARNINGS: "1"
+          NODE_NO_WARNINGS: "1",
+          // Identity for the bridge calls the script will make. The async
+          // context cannot cross a process boundary, so it travels as a
+          // token instead. Absent when the run has no context — the bridge
+          // then treats the queries as anonymous, which is the truth.
+          ...contextToken ? { SA_CONTEXT_TOKEN: contextToken } : {}
         }
       }
     );
@@ -10777,6 +11142,7 @@ function executeInSubprocess(scriptPath, params, paramSchema, externalTools, str
     let executedQueries = [];
     let stderrBuffer = "";
     const cleanup = () => {
+      revokeContextToken(contextToken);
       if (child.killed) return;
       const pid = child.pid;
       if (pid && process.platform !== "win32") {
@@ -10881,7 +11247,8 @@ function executeInSubprocess(scriptPath, params, paramSchema, externalTools, str
       ...analysisData ? { data: analysisData } : {},
       ...analysisDatasets && Object.keys(analysisDatasets).length ? { datasets: analysisDatasets } : {},
       ...fmtConfig ? { fmt: fmtConfig } : {},
-      ...entities && entities.length ? { entities } : {}
+      ...entities && entities.length ? { entities } : {},
+      ...appliedPolicies && appliedPolicies.length ? { appliedPolicies } : {}
     });
     child.stdin.write(init);
     function handleChildMessage(msg) {
@@ -10966,7 +11333,12 @@ function enrichQueries(queries, externalTools) {
       count: q.count,
       totalCount: q.totalCount,
       executionTimeMs: q.executionTimeMs,
-      virtual: q.virtual
+      virtual: q.virtual,
+      // Carried through explicitly: this rebuilds each query field by field,
+      // so anything not listed is silently dropped. Losing it here left
+      // getAnalysis's `scope` empty while the query WAS restricted — the
+      // analysis then described a branch-scoped count as system-wide.
+      appliedPolicies: q.appliedPolicies
     };
   });
 }
@@ -11058,7 +11430,8 @@ async function runComponentsOnly(recipe, scriptPath, params, data, options, data
       "components",
       data,
       datasets,
-      options.entities
+      options.entities,
+      options.appliedPolicies
     );
     if (result.kind === "ok") {
       return { components: result.components, componentsError: result.componentsError };
@@ -11091,7 +11464,8 @@ async function runAnalysisOnly(recipe, scriptPath, params, data, options, datase
       "analysis",
       data,
       datasets,
-      options.entities
+      options.entities,
+      options.appliedPolicies
     );
     if (result.kind === "ok") {
       return { analysis: result.analysis, analysisError: result.analysisError };
@@ -11288,7 +11662,7 @@ function resolveScriptRecipeStore(collections) {
 // src/userResponse/scripts/script-store.ts
 var fs6 = __toESM(require("fs"));
 var path6 = __toESM(require("path"));
-var import_crypto5 = require("crypto");
+var import_crypto6 = require("crypto");
 var DEFAULT_STORE_DIR = "scripts-store";
 function stripAnalysisExport(body) {
   return stripNamedExport(body, "getAnalysis");
@@ -11315,7 +11689,7 @@ function stripNamedExport(body, fnName) {
 function dataFingerprint(scriptBody, parameters) {
   const data = extractNamedExport(scriptBody, "getData") ?? scriptBody;
   const params = (parameters ?? []).map((p) => `${p.name}:${p.type}:${JSON.stringify(p.default ?? null)}`).sort().join("|");
-  return (0, import_crypto5.createHash)("sha256").update(`${data.trim()}\0${params}`).digest("hex");
+  return (0, import_crypto6.createHash)("sha256").update(`${data.trim()}\0${params}`).digest("hex");
 }
 function extractNamedExport(body, fnName) {
   const start = body.search(new RegExp(`export\\s+(?:async\\s+)?function\\s+${fnName}\\b`));
@@ -11500,7 +11874,7 @@ var ScriptStore = class {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const existing = input.recipeId ? await this.store.getById(input.recipeId) : null;
     const reuse = existing && existing.status === "draft" && existing.turnId === input.turnId;
-    const id = reuse ? existing.id : `script_${Date.now()}_${(0, import_crypto5.randomBytes)(3).toString("hex")}`;
+    const id = reuse ? existing.id : `script_${Date.now()}_${(0, import_crypto6.randomBytes)(3).toString("hex")}`;
     const fileBase = reuse ? existing.fileBase : input.parentId ? `${this.toSlug(input.name)}-${id.slice(-6)}` : await this.computeFileBase(input.name, id);
     let normalized = normalizeScriptBody(input.scriptBody);
     if (reuse) {
@@ -11863,7 +12237,7 @@ ${carried.trim()}
     return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "unnamed-script";
   }
   hash(body) {
-    return (0, import_crypto5.createHash)("sha256").update(body).digest("hex");
+    return (0, import_crypto6.createHash)("sha256").update(body).digest("hex");
   }
   /**
    * Attach getComponents to the recipe body. The stored `components` column is
@@ -11871,6 +12245,32 @@ ${carried.trim()}
    * specs, a stale spec array beside a live program is how the wrong one gets
    * read later. See backend/docs/COMPONENTS-AS-PROGRAM-DESIGN.md § 4.4.
    */
+  /**
+   * Body text as it stands now, for reverting an attach that turns out to be
+   * invalid.
+   *
+   * getComponents can only be VALIDATED by running it, and it can only be run
+   * once it is on disk — so attachComponents necessarily writes before anyone
+   * knows whether the body is good. Without a revert, a rejected body stays
+   * attached: promote() then sees the recipe "exports getComponents", clears
+   * the specs the fallback generator produced, and the recipe is verified with
+   * component code that was already rejected. Confirmed live on
+   * "Total Bookings by Branch", which shipped a sourceRef of 'computed:_final'
+   * that validateSpecs had refused.
+   */
+  async snapshotBody(recipeId) {
+    const recipe = await this.get(recipeId);
+    if (!recipe?.fileBase) return null;
+    return this.readBody(recipe.fileBase) || null;
+  }
+  /** Put back a body captured by {@link snapshotBody}. */
+  async restoreBody(recipeId, body) {
+    const recipe = await this.get(recipeId);
+    if (!recipe?.fileBase) return false;
+    this.writeBody(recipe.fileBase, body);
+    logger.info(`[ScriptStore] Reverted body of "${recipe.name}" (${recipeId}) after a rejected attach`);
+    return true;
+  }
   async attachComponents(recipeId, componentsBody) {
     const recipe = await this.get(recipeId);
     if (!recipe) {
@@ -11949,7 +12349,7 @@ ${analysisBody.trim()}
   writeArchive(fileBase, version, body) {
     if (!fs6.existsSync(this.archiveDir)) fs6.mkdirSync(this.archiveDir, { recursive: true });
     const finalPath = path6.join(this.archiveDir, `${fileBase}.v${version}.ts`);
-    const tmpPath = `${finalPath}.tmp-${(0, import_crypto5.randomBytes)(4).toString("hex")}`;
+    const tmpPath = `${finalPath}.tmp-${(0, import_crypto6.randomBytes)(4).toString("hex")}`;
     fs6.writeFileSync(tmpPath, body);
     fs6.renameSync(tmpPath, finalPath);
   }
@@ -11976,7 +12376,7 @@ ${analysisBody.trim()}
   writeBody(fileBase, normalizedBody) {
     if (!fs6.existsSync(this.storeDir)) fs6.mkdirSync(this.storeDir, { recursive: true });
     const finalPath = this.bodyPath(fileBase);
-    const tmpPath = `${finalPath}.tmp-${(0, import_crypto5.randomBytes)(4).toString("hex")}`;
+    const tmpPath = `${finalPath}.tmp-${(0, import_crypto6.randomBytes)(4).toString("hex")}`;
     fs6.writeFileSync(tmpPath, normalizedBody);
     fs6.renameSync(tmpPath, finalPath);
   }
@@ -12801,7 +13201,7 @@ ${catalog}`,
       return "write_components requires data: run write_script then execute_script successfully first.";
     }
     if (this.renderComponentAttempts >= MAX_RENDER_COMPONENT_ATTEMPTS) {
-      return `Reached the max of ${MAX_RENDER_COMPONENT_ATTEMPTS} write_components attempts. Stop calling it and write your answer \u2014 the system will build the dashboard.`;
+      return `Reached the max of ${MAX_RENDER_COMPONENT_ATTEMPTS} write_components attempts. Stop calling it \u2014 the system will build the dashboard. This limit is write_components only; if you have not called write_analysis, call it now.`;
     }
     this.renderComponentAttempts++;
     const hardcodedAggregates = findHardcodedAggregates(body);
@@ -12829,6 +13229,10 @@ STILL UNCHANGED FROM THE LAST ATTEMPT: ${repeatedList}. Restating the same reaso
     const recipeId = this.scriptState.recipeId;
     const draft = recipeId ? await this.scriptStore.get(recipeId) : null;
     if (!recipeId || !draft) return "Draft was lost from the store. Call write_script again.";
+    const snapshot = await this.scriptStore.snapshotBody(recipeId);
+    const revert = async () => {
+      if (snapshot) await this.scriptStore.restoreBody(recipeId, snapshot);
+    };
     const attached = await this.scriptStore.attachComponents(recipeId, body);
     if (!attached) return "Could not attach getComponents to the draft. Call render-free: write your answer and the system will build the dashboard.";
     const datasets = {};
@@ -12842,12 +13246,13 @@ STILL UNCHANGED FROM THE LAST ATTEMPT: ${repeatedList}. Restating the same reaso
       this.scriptStore.getScriptPath(draft),
       {},
       result.data,
-      { externalTools: this.externalTools, signal: this.abortSignal, entities: this.resolvedEntities },
+      { externalTools: this.externalTools, signal: this.abortSignal, entities: this.resolvedEntities, appliedPolicies: this.observedPolicies() },
       datasets
     );
     if (componentsError || !components?.length) {
       const why = componentsError || "it returned no components";
       logger.warn(`[MainAgent] write_components failed: ${why}`);
+      await revert();
       return `getComponents failed: ${why}
 
 Fix the body and call write_components again. It receives (data, params, fmt, datasets) and must RETURN an array of component specs.`;
@@ -12856,6 +13261,14 @@ Fix the body and call write_components again. It receives (data, params, fmt, da
     if (findings.length > 0) {
       logger.warn(`[MainAgent] write_components rejected (attempt ${this.renderComponentAttempts}): ${findings.length} finding(s)`);
       findings.forEach((f) => logger.warn(`[MainAgent]   ${f.code} ${f.componentType}: ${f.message}`));
+      await revert();
+      if (this.renderComponentAttempts >= MAX_RENDER_COMPONENT_ATTEMPTS && accepted.length > 0) {
+        this.componentSpecs = accepted;
+        this.componentLayout = { title: input?.layoutTitle || "Dashboard", description: input?.layoutDescription };
+        const dropped = findings.map((f) => `${f.componentType} (${f.code})`).join(", ");
+        logger.warn(`[MainAgent] write_components out of attempts \u2014 keeping ${accepted.length} valid spec(s), dropping ${findings.length}: ${dropped}`);
+        return `Out of write_components attempts. Kept ${accepted.length} valid component(s); dropped ${findings.length} (${dropped}). Stop calling write_components and write your answer.`;
+      }
       return formatFindingsForAgent(findings);
     }
     this.componentSpecs = accepted;
@@ -12871,6 +13284,20 @@ Now write your answer for the user. Do not restate the component list.`;
   // ============================================
   // Script-authoring tool handlers
   // ============================================
+  /**
+   * Restrictions the seam reported while this run's queries executed.
+   *
+   * getData does NOT re-run for write_components/write_analysis, so the child
+   * cannot observe these itself — the parent hands them across, exactly as it
+   * does for `entities`.
+   */
+  observedPolicies() {
+    const seen = /* @__PURE__ */ new Set();
+    for (const q of this.scriptState.lastSuccessfulResult?.executedQueries ?? []) {
+      for (const p of q?.appliedPolicies ?? []) seen.add(p);
+    }
+    return [...seen];
+  }
   /**
    * Author the answer as a program. Runs after execute_script, so the body is
    * written with the result already known and can react to what it found.
@@ -12904,14 +13331,16 @@ Now write your answer for the user. Do not restate the component list.`;
     const lintError = formatLintError(violations);
     if (lintError) {
       const named = violations.map((v) => `"${v.text}"`).join(", ");
+      const budget = `
+Attempt ${this.scriptState.analysisAttempts} of ${MAX_ANALYSIS_ATTEMPTS}. Fix the value(s) and call write_analysis again \u2014 do not switch to prose while attempts remain.`;
       if (this.scriptState.analysisAttempts < MAX_ANALYSIS_ATTEMPTS) {
         logger.warn(`[MainAgent] write_analysis rejected \u2014 ${violations.length} hardcoded value(s): ${named}`);
         if (repeatedTexts.length > 0) {
           const repeatedList = repeatedTexts.map((t) => `"${t}"`).join(", ");
           return `${lintError}
-STILL UNCHANGED FROM THE LAST ATTEMPT: ${repeatedList}. Restating the same reason won't help a second time \u2014 this is almost certainly a parameter or an already-resolved value, not something to compute fresh: if it's an id, use \`params.<name>\` directly; if it's a name, read it from \`data\`/\`datasets\` (e.g. \`datasets.summary?.[0]?.<field>\`). Replace the literal itself, not the wording around it.`;
+STILL UNCHANGED FROM THE LAST ATTEMPT: ${repeatedList}. Restating the same reason won't help a second time \u2014 this is almost certainly a parameter or an already-resolved value, not something to compute fresh: if it's an id, use \`params.<name>\` directly; if it's a name, read it from \`data\`/\`datasets\` (e.g. \`datasets.summary?.[0]?.<field>\`). Replace the literal itself, not the wording around it.` + budget;
         }
-        return lintError;
+        return lintError + budget;
       }
       logger.warn(`[MainAgent] write_analysis accepted on the final attempt DESPITE ${violations.length} hardcoded value(s): ${named} \u2014 a computed answer with a frozen figure beats LLM prose. Those value(s) will not track the data on replay.`);
     }
@@ -12931,7 +13360,7 @@ STILL UNCHANGED FROM THE LAST ATTEMPT: ${repeatedList}. Restating the same reaso
       this.scriptStore.getScriptPath(draft),
       {},
       verified.data,
-      { externalTools: this.externalTools, signal: this.abortSignal, entities: this.resolvedEntities },
+      { externalTools: this.externalTools, signal: this.abortSignal, entities: this.resolvedEntities, appliedPolicies: this.observedPolicies() },
       datasets
     );
     if (analysisError || !analysis?.analysis) {
@@ -13232,11 +13661,26 @@ The verified script is intact. You can still call write_analysis and write_compo
    */
   buildResolvedEntitiesBlock() {
     if (!this.resolvedEntities.length) return "";
-    const lines = this.resolvedEntities.map((e) => {
+    const render = (e) => {
       const scopeSql = e.attrs?.scopeSql;
       const scopePart = typeof scopeSql === "string" && scopeSql.trim() ? ` \u2014 READY-MADE SCOPE (use this directly, do not re-derive it): ${scopeSql}` : "";
       return `- "${e.mention}" \u2192 ${e.entityType} id ${e.instanceId} (name in DB: ${e.displayName})${scopePart}`;
-    });
+    };
+    const byMention = /* @__PURE__ */ new Map();
+    for (const e of this.resolvedEntities) {
+      const group = byMention.get(e.mention) ?? [];
+      group.push(e);
+      byMention.set(e.mention, group);
+    }
+    const lines = [];
+    for (const [mention, group] of byMention) {
+      if (group.length === 1) {
+        lines.push(render(group[0]));
+        continue;
+      }
+      lines.push(`- "${mention}" matched ${group.length} entity types at the same confidence \u2014 CHOOSE the one the question means and filter on that id ALONE, never on more than one:`);
+      for (const e of group) lines.push(`  ${render(e).slice(2)}`);
+    }
     return `
 
 RESOLVED ENTITIES \u2014 these were looked up already. Filter on the ids; do NOT search for them by name. Where a name must appear in output or a comparison, use the "name in DB" spelling EXACTLY as given. Where a READY-MADE SCOPE is given, paste it into the query as-is instead of writing your own join/city-match/lookup for the same thing:
@@ -13556,9 +14000,25 @@ ${r.body}`).join("\n\n");
       logger.info(
         `[MainAgent] resolve_entities: ${res?.resolved?.length ?? 0} resolved, ${res?.unresolved?.length ?? 0} unresolved, ${Object.keys(res?.entityMap || {}).length} concept(s)`
       );
+      const TIE_EPSILON = 0.05;
+      const key = (e) => `${e.entityType}::${e.instanceId}`;
+      const add = (mention, c) => {
+        if (!c?.instanceId) return;
+        if (this.resolvedEntities.some((e) => key(e) === key(c))) return;
+        this.resolvedEntities.push({
+          mention: String(mention ?? ""),
+          entityType: String(c.entityType ?? ""),
+          instanceId: String(c.instanceId),
+          displayName: String(c.displayName ?? mention ?? ""),
+          attrs: c.attrs && typeof c.attrs === "object" ? c.attrs : void 0
+        });
+      };
       for (const r of Array.isArray(res?.resolved) ? res.resolved : []) {
         if (!r?.instanceId) continue;
-        const key = (e) => `${e.entityType}::${e.instanceId}`;
+        for (const a of Array.isArray(r.alternatives) ? r.alternatives : []) {
+          const tied = typeof r.score !== "number" || typeof a?.score !== "number" ? false : r.score - a.score <= TIE_EPSILON;
+          if (tied) add(r.mention, a);
+        }
         if (this.resolvedEntities.some((e) => key(e) === key(r))) continue;
         this.resolvedEntities.push({
           mention: String(r.mention ?? ""),
@@ -13817,7 +14277,7 @@ ${propLines}` : ""
     const scriptBodyContract = await promptLoader.loadScriptBodyContract({
       MAX_ROWS_RENDERED: String(MAX_ROWS_RENDERED),
       MAX_ROWS_FETCHED: String(MAX_ROWS_FETCHED)
-    });
+    }) + buildAccessBodyContract(this.config.userAccessContext ?? "");
     try {
       if (this.config.trace) this.config.trace.scriptBodyContractText = scriptBodyContract;
     } catch (traceErr) {
@@ -13835,7 +14295,9 @@ ${propLines}` : ""
       GLOBAL_KNOWLEDGE_BASE: this.config.globalKnowledgeBase || "No global knowledge base available.",
       CURRENT_DATETIME: getCurrentDateTimeForPrompt(),
       KNOWLEDGE_BASE_CONTEXT: this.config.knowledgeBaseContext || "No additional knowledge base context available.",
-      USER_ACCESS_CONTEXT: this.config.userAccessContext || "No user-specific access restrictions.",
+      // '' when the user has no policy — the whole section disappears rather
+      // than rendering a heading over "no restrictions". See access-section.ts.
+      USER_ACCESS_CONTEXT: buildAccessSection(this.config.userAccessContext ?? "", this.editMode ? "edit" : "main"),
       ENTITY_CATALOG: entityCatalogText || "No entity catalog available \u2014 resolve_entities may still be called with mentions.",
       CONCEPT_CATALOG: conceptCatalogText || "No concept catalog available \u2014 derive definitions from the schema and say that you did.",
       // Bodies, not names: an invariant is injected precisely because it
@@ -14040,8 +14502,20 @@ Execution time: ${metadata.executionTimeMs}ms
       rows: t?.result?._mainAgentRows ?? t?.result?._sampleData ?? [],
       summary: t?.result?._summary,
       total: t?.result?._totalRecords,
-      shown: t?.result?._recordsShown
+      shown: t?.result?._recordsShown,
+      policy: t?.result?._ACCESS_POLICY_APPLIED
     })).filter((q) => Boolean(q.sql));
+    const policyNotes = [...new Set(queries.map((q) => q.policy).filter(Boolean))];
+    if (policyNotes.length) {
+      output += `
+\u{1F512} ACCESS POLICY \u2014 applies to EVERY figure below:
+${policyNotes.map((n) => `- ${n}`).join("\n")}
+Reflect this in the answer: name the restriction in component titles, the analysis, and the method line \u2014 phrased naturally as part of the sentence, never pasted in as a raw filter expression. Do not describe these numbers as complete, overall, or covering everything.
+If a query came back EMPTY, that is NOT evidence the records do not exist \u2014 under a restriction it usually means they are outside this user's access. Say so; never write "no data found" or "there are none".
+Do NOT copy the restriction into the script's SQL: it is enforced automatically on every run, and a value written into a recipe goes stale the moment this user's access changes. getAnalysis and getComponents receive what was actually applied as their 6th argument, \`scope: string[]\` \u2014 use that to name it, in BOTH functions.
+
+`;
+    }
     if (queries.length === 0) {
       output += "No data returned.";
       return output;
@@ -17480,16 +17954,37 @@ function storeScriptDatasetQuery(q, ctx) {
   return queryCache.storeQuery(q.sql, { data, count });
 }
 function buildUserAccessContext(userConfig) {
-  if (!userConfig || typeof userConfig !== "object") return "";
-  const { prompt, ...rest } = userConfig;
-  const parts = [];
-  if (Object.keys(rest).length > 0) {
-    parts.push(JSON.stringify(rest));
-  }
-  if (typeof prompt === "string" && prompt.trim()) {
-    parts.push(prompt.trim());
+  const entries = Array.isArray(userConfig) ? userConfig : [userConfig];
+  const restrictions = [];
+  const prompts = [];
+  let anyRestriction = false;
+  for (const e of entries) {
+    if (!e || typeof e !== "object") continue;
+    const rowFilters = Array.isArray(e.rowFilters) ? e.rowFilters : [];
+    const readableTables = Array.isArray(e.readableTables) ? e.readableTables.filter((t) => typeof t === "string" && !!t) : [];
+    const realFilters = rowFilters.filter(
+      (f) => f && typeof f === "object" && f.column && Array.isArray(f.values) && f.values.length > 0
+    );
+    if (realFilters.length || readableTables.length) {
+      anyRestriction = true;
+      if (enforcementApplies()) {
+        const clean = (v) => typeof v === "string" ? v.replace(/\s+/g, " ").trim() : "";
+        const labels = [
+          .../* @__PURE__ */ new Set([
+            ...realFilters.map((f) => clean(f.label)).filter(Boolean),
+            ...clean(e.label) ? [clean(e.label)] : []
+          ])
+        ];
+        restrictions.push(labels.length ? labels.join("; ") : "This user's data access is restricted.");
+      } else {
+        const { prompt: _p, ...rest } = e;
+        restrictions.push(JSON.stringify(rest));
+      }
+    }
+    if (typeof e.prompt === "string" && e.prompt.trim()) prompts.push(e.prompt.trim());
   }
-  return parts.join("\n\n");
+  if (!anyRestriction && prompts.length === 0) return "";
+  return [...restrictions, ...prompts].join("\n\n");
 }
 var get_agent_user_response = async (prompt, components, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, conversationHistory, streamCallback, collections, externalTools, userId, mainAgentModel, sourceAgentModel, workflows, signal, activeBindings, userConfig) => {
   const startTime = Date.now();
@@ -19252,7 +19747,7 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
   };
 };
 async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows) {
-  const response = await get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows);
+  const response = await runWithMessageIdentity(data, () => get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows));
   if (response.data?.component?.props?.config?.components) {
     response.data.component.props.config.components = response.data.component.props.config.components.map((comp) => ({
       ...comp,
@@ -22353,9 +22848,9 @@ async function loadDatabaseRulesForTools(tools) {
   }
   const sections = await Promise.all(
     dbTypes.map(async (dbType) => {
-      const rules = await promptLoader.loadDatabaseRulesForType(dbType);
+      const rules2 = await promptLoader.loadDatabaseRulesForType(dbType);
       return `## ${dbType.toUpperCase()} Rules (apply ONLY to ${dbType} tools \u2014 check each tool's ID prefix)
-${rules}`;
+${rules2}`;
     })
   );
   return sections.join("\n\n---\n\n");
@@ -23406,7 +23901,7 @@ var processDashCompRequest = async (data, components, _sendMessage, anthropicApi
   };
 };
 async function handleDashCompRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, tools, dashCompModels) {
-  const response = await processDashCompRequest(
+  const response = await runWithMessageIdentity(data, () => processDashCompRequest(
     data,
     components,
     sendMessage,
@@ -23418,7 +23913,7 @@ async function handleDashCompRequest(data, components, sendMessage, anthropicApi
     collections,
     tools,
     dashCompModels
-  );
+  ));
   sendDashCompResponse(
     response.id || data.id,
     {
@@ -25400,7 +25895,7 @@ var processReportCompRequest = async (data, components, _sendMessage, anthropicA
   };
 };
 async function handleReportCompRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, tools, modelConfig) {
-  const response = await processReportCompRequest(
+  const response = await runWithMessageIdentity(data, () => processReportCompRequest(
     data,
     components,
     sendMessage,
@@ -25412,7 +25907,7 @@ async function handleReportCompRequest(data, components, sendMessage, anthropicA
     collections,
     tools,
     modelConfig
-  );
+  ));
   sendReportCompResponse(
     response.id || data.id,
     {
@@ -28065,6 +28560,7 @@ var SuperatomSDK = class {
   DEFAULT_AGENT_CONFIG,
   LLM,
   MainAgent,
+  MissingRequestContextError,
   STORAGE_CONFIG,
   ScriptMatcher,
   ScriptStore,
@@ -28076,36 +28572,53 @@ var SuperatomSDK = class {
   UserManager,
   anthropicLLM,
   assertReadOnlySql,
+  bindContext,
+  captureContext,
+  clearContextTokens,
+  contextTokenCount,
   createCodexSession,
   createCodingAgentSession,
   dashboardConversationHistory,
   dataFingerprint,
+  describeContext,
   describeTriggers,
   emitAgentEvent,
   extractNamedExport,
   geminiLLM,
   getCodingAgent,
   getCodingAgentsConfig,
+  getRequestContext,
   groqLLM,
   hybridRerank,
+  isUserContext,
   listCodingAgents,
   llmUsageLogger,
   logger,
+  mintContextToken,
   normalizeScriptBody,
   onAgentRun,
   openaiLLM,
+  policiesFromConfig,
   queryCache,
   registerCodingAgentCollection,
   registerCodingAgents,
   registerDashboardAgentCollection,
+  requireRequestContext,
   rerankChromaResults,
   rerankConversationResults,
+  resolveContextToken,
   resolveScriptRecipeStore,
+  revokeContextToken,
+  runAsSystem,
+  runAsUser,
   runCodingAgent,
   runScript,
+  runWithContext,
+  runWithMessageIdentity,
   startAgentTriggers,
   stopAgentTriggers,
   userPromptErrorLogger,
+  withCapturedContext,
   writeBridgeShims
 });
 //# sourceMappingURL=index.js.map