@promptev/context-engine 0.0.0 → 0.0.1

package/dist/index.js

@@ -1,19 +1,21 @@
 import { francAll } from 'franc';
 import OpenAI from 'openai';
+import { randomBytes, createCipheriv, createDecipheriv, randomUUID, createHash, createHmac } from 'crypto';
 import { jsonrepair } from 'jsonrepair';
 import { load } from 'cheerio';
 import ExcelJS from 'exceljs';
 import JSZip from 'jszip';
 import mammoth from 'mammoth';
 import PostalMime from 'postal-mime';
+import { z } from 'zod';
 import { getDocumentProxy, extractText, renderPageAsImage, extractImages } from 'unpdf';
 import { createRequire } from 'module';
-import { randomBytes, createCipheriv, createDecipheriv, randomUUID, createHash, createHmac } from 'crypto';
 import { readFileSync, openSync, readSync, closeSync } from 'fs';
 import { join, basename, dirname } from 'path';
-import { z } from 'zod';
 import { fileURLToPath } from 'url';
 import { getEncoding } from 'js-tiktoken';
+import { promises } from 'dns';
+import { isIP } from 'net';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -775,6 +777,14 @@ function emitError(hooks, exc, ctx) {
     log2.warn("onError callback raised; swallowing");
   }
 }
+function emitProgress(hooks, event) {
+  if (!hooks?.onProgress) return;
+  try {
+    hooks.onProgress(event);
+  } catch {
+    log2.warn("onProgress callback raised; swallowing");
+  }
+}
 function emitToolCall(hooks, event) {
   if (!hooks?.onToolCall) return;
   try {
@@ -796,6 +806,8 @@ var init_hooks = __esm({
 // src/providers/llm.ts
 var llm_exports = {};
 __export(llm_exports, {
+  CALL_TIMEOUT_MS: () => CALL_TIMEOUT_MS,
+  GEMINI_CALL_TIMEOUT_MS: () => GEMINI_CALL_TIMEOUT_MS,
   LLMClient: () => LLMClient,
   TIMEOUT_MS: () => TIMEOUT_MS,
   buildLlmClient: () => buildLlmClient,
@@ -838,7 +850,7 @@ async function loadGeminiChatClient(apiKey) {
   if (!Ctor) {
     throw new ExtraMissingError("gemini", specifier, "gemini llm");
   }
-  return new Ctor({ apiKey: apiKey ?? null });
+  return new Ctor({ apiKey: apiKey ?? null, httpOptions: { timeout: GEMINI_CALL_TIMEOUT_MS } });
 }
 async function loadBedrockSdk() {
   const specifier = "@aws-sdk/client-bedrock-runtime";
@@ -875,11 +887,13 @@ async function callLlm(cfg2, opts) {
     await owned.aclose();
   }
 }
-var TIMEOUT_MS, ANTHROPIC_VERSION, ANTHROPIC_MAX_TOKENS, OPENAI_FAMILY, LLMClient;
+var CALL_TIMEOUT_MS, TIMEOUT_MS, GEMINI_CALL_TIMEOUT_MS, ANTHROPIC_VERSION, ANTHROPIC_MAX_TOKENS, OPENAI_FAMILY, LLMClient;
 var init_llm = __esm({
   "src/providers/llm.ts"() {
     init_errors();
-    TIMEOUT_MS = 3e4;
+    CALL_TIMEOUT_MS = 24e4;
+    TIMEOUT_MS = CALL_TIMEOUT_MS;
+    GEMINI_CALL_TIMEOUT_MS = CALL_TIMEOUT_MS;
     ANTHROPIC_VERSION = "2023-06-01";
     ANTHROPIC_MAX_TOKENS = 4096;
     OPENAI_FAMILY = /* @__PURE__ */ new Set(["openai", "azure_openai", "custom"]);
@@ -907,22 +921,30 @@ var init_llm = __esm({
         await this.aclose();
       }
       async call(opts) {
-        const { system, user, jsonMode = false, images = null } = opts;
+        const {
+          system,
+          user,
+          jsonMode = false,
+          images = null,
+          maxTokens = null,
+          thinkingBudget = null,
+          temperature = null
+        } = opts;
         if (this.provider === "anthropic") {
-          return this.callAnthropic(system, user, jsonMode, images);
+          return this.callAnthropic(system, user, jsonMode, images, maxTokens, thinkingBudget, temperature);
         }
         if (OPENAI_FAMILY.has(this.provider)) {
-          return this.callOpenAI(system, user, jsonMode, images);
+          return this.callOpenAI(system, user, jsonMode, images, maxTokens, temperature);
         }
         if (this.provider === "gemini") {
-          return this.callGemini(system, user, jsonMode, images);
+          return this.callGemini(system, user, jsonMode, images, maxTokens, thinkingBudget, temperature);
         }
         if (this.provider === "bedrock") {
-          return this.callBedrock(system, user, jsonMode, images);
+          return this.callBedrock(system, user, jsonMode, images, maxTokens, thinkingBudget, temperature);
         }
         throw new Error(`unknown llm provider: ${JSON.stringify(this.provider)}`);
       }
-      async callAnthropic(system, user, jsonMode, images) {
+      async callAnthropic(system, user, jsonMode, images, maxTokens, thinkingBudget = null, temperature = null) {
         if (!this.fetchImpl) {
           throw new Error("anthropic llm client has no fetch implementation");
         }
@@ -943,26 +965,27 @@ Respond with valid JSON only.`;
           });
         }
         content.push({ type: "text", text: user });
-        const data = await postJson(
-          this.fetchImpl,
-          "https://api.anthropic.com/v1/messages",
-          {
-            model: this.model,
-            max_tokens: ANTHROPIC_MAX_TOKENS,
-            system,
-            messages: [{ role: "user", content }]
-          },
-          {
-            "x-api-key": this.cfg.apiKey ?? "",
-            "anthropic-version": ANTHROPIC_VERSION,
-            "content-type": "application/json"
-          }
-        );
+        const body = {
+          model: this.model,
+          max_tokens: maxTokens ?? ANTHROPIC_MAX_TOKENS,
+          system,
+          messages: [{ role: "user", content }]
+        };
+        if (thinkingBudget) {
+          body.thinking = { type: "enabled", budget_tokens: thinkingBudget };
+        } else if (temperature !== null) {
+          body.temperature = temperature;
+        }
+        const data = await postJson(this.fetchImpl, "https://api.anthropic.com/v1/messages", body, {
+          "x-api-key": this.cfg.apiKey ?? "",
+          "anthropic-version": ANTHROPIC_VERSION,
+          "content-type": "application/json"
+        });
         const text = data.content[0].text;
         const usage = data.usage ?? {};
         return [text, { input: usage.input_tokens ?? 0, output: usage.output_tokens ?? 0 }];
       }
-      async callOpenAI(system, user, jsonMode, images) {
+      async callOpenAI(system, user, jsonMode, images, maxTokens, temperature = null) {
         if (!this.client) {
           throw new Error("openai-family llm client has no client");
         }
@@ -983,12 +1006,18 @@ Respond with valid JSON only.`;
         if (jsonMode) {
           body.response_format = { type: "json_object" };
         }
+        if (maxTokens) {
+          body.max_completion_tokens = maxTokens;
+        }
+        if (temperature !== null) {
+          body.temperature = temperature;
+        }
         const resp = await this.client.chat.completions.create(body);
         const text = resp.choices[0]?.message?.content ?? "";
         const usage = resp.usage;
         return [text, { input: usage?.prompt_tokens ?? 0, output: usage?.completion_tokens ?? 0 }];
       }
-      async callGemini(system, user, jsonMode, images) {
+      async callGemini(system, user, jsonMode, images, maxTokens, thinkingBudget = null, temperature = null) {
         if (!this.genaiClient) {
           this.genaiClient = await loadGeminiChatClient(this.cfg.apiKey);
         }
@@ -997,10 +1026,30 @@ Respond with valid JSON only.`;
           parts.push({ inlineData: { mimeType: "image/png", data: toBase64(img) } });
         }
         parts.push({ text: user });
-        const config = { systemInstruction: system };
+        const config = {
+          systemInstruction: system,
+          // ALWAYS off, and not as a preference. Automatic function calling means
+          // the SDK itself EXECUTES a callable it was handed as a tool and loops
+          // on the result — up to ten round trips — before returning anything.
+          // This package passes declarations only, so today nothing is executable;
+          // but that depends on every future caller continuing to do the same, and
+          // an application that gates tool execution behind human approval would
+          // have that gate bypassed silently, by a library, with the loop already
+          // run before it could object.
+          automaticFunctionCalling: { disable: true }
+        };
         if (jsonMode) {
           config.responseMimeType = "application/json";
         }
+        if (maxTokens) {
+          config.maxOutputTokens = maxTokens;
+        }
+        if (temperature !== null) {
+          config.temperature = temperature;
+        }
+        if (thinkingBudget !== null) {
+          config.thinkingConfig = { thinkingBudget };
+        }
         const resp = await this.genaiClient.models.generateContent({
           model: this.model,
           contents: parts,
@@ -1012,7 +1061,7 @@ Respond with valid JSON only.`;
         const outputTokens = usageMeta?.candidatesTokenCount ?? usageMeta?.candidates_token_count ?? 0;
         return [text, { input: inputTokens || 0, output: outputTokens || 0 }];
       }
-      async callBedrock(system, user, jsonMode, images) {
+      async callBedrock(system, user, jsonMode, images, maxTokens, thinkingBudget = null, temperature = null) {
         const { BedrockRuntimeClient, ConverseCommand } = await loadBedrockSdk();
         if (jsonMode) {
           system = `${system}
@@ -1036,7 +1085,21 @@ Respond with valid JSON only.`;
             new ConverseCommand({
               modelId: this.model,
               system: [{ text: system }],
-              messages: [{ role: "user", content }]
+              messages: [{ role: "user", content }],
+              ...maxTokens || temperature !== null ? {
+                inferenceConfig: {
+                  ...maxTokens ? { maxTokens } : {},
+                  ...temperature !== null ? { temperature } : {}
+                }
+              } : {},
+              // Anthropic-style passthrough — Converse forwards it to the model.
+              // Zero (the vision transcription contract) sends nothing: thinking
+              // is opt-in for the anthropic models bedrock hosts.
+              ...thinkingBudget ? {
+                additionalModelRequestFields: {
+                  thinking: { type: "enabled", budget_tokens: thinkingBudget }
+                }
+              } : {}
             })
           );
           const text = result.output?.message?.content?.[0]?.text ?? "";
@@ -1049,6 +1112,302 @@ Respond with valid JSON only.`;
     };
   }
 });
+function encryptDict(data, key) {
+  const nonce = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, nonce);
+  const plaintext = Buffer.from(JSON.stringify(data), "utf8");
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([nonce, ciphertext, tag]).toString("base64");
+}
+function decryptDict(token, key) {
+  const raw = Buffer.from(token, "base64");
+  const nonce = raw.subarray(0, 12);
+  const tag = raw.subarray(raw.length - 16);
+  const ciphertext = raw.subarray(12, raw.length - 16);
+  const decipher = createDecipheriv("aes-256-gcm", key, nonce);
+  decipher.setAuthTag(tag);
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return JSON.parse(plaintext.toString("utf8"));
+}
+function getSecretKey(config) {
+  const secretKey = config.secretKey;
+  if (!secretKey) {
+    throw new Error(
+      "ContextEngineConfig.secretKey (env CE_SECRET_KEY) is not configured \u2014 a base64url-encoded 32-byte AES key is required to encrypt/decrypt tool configs that hold secrets."
+    );
+  }
+  return Buffer.from(secretKey, "base64url");
+}
+function hmacSha256Hex(key, value) {
+  const k = typeof key === "string" ? Buffer.from(key) : key;
+  return createHmac("sha256", k).update(value, "utf8").digest("hex");
+}
+var init_crypto = __esm({
+  "src/crypto.ts"() {
+  }
+});
+
+// src/redaction.ts
+function spansFrom(re, text) {
+  const out = [];
+  re.lastIndex = 0;
+  let m = re.exec(text);
+  while (m !== null) {
+    out.push([m.index, m.index + m[0].length]);
+    if (m[0].length === 0) re.lastIndex++;
+    m = re.exec(text);
+  }
+  return out;
+}
+function luhnOk(digits) {
+  let total = 0;
+  const rev = [...digits].reverse();
+  for (let i = 0; i < rev.length; i++) {
+    let d = Number(rev[i]);
+    if (i % 2 === 1) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    total += d;
+  }
+  return total % 10 === 0;
+}
+function detectCreditCard(text) {
+  const spans = [];
+  for (const [start, end] of spansFrom(CARD_RE, text)) {
+    const digits = text.slice(start, end).replace(/[ -]/g, "");
+    if (digits.length >= 13 && digits.length <= 19 && luhnOk(digits)) {
+      spans.push([start, end]);
+    }
+  }
+  return spans;
+}
+function looksLikeGenericSecret(token) {
+  if (UUID_RE.test(token)) return false;
+  let hasUpper = false;
+  let hasLower = false;
+  let hasDigit = false;
+  for (const c of token) {
+    if (c >= "A" && c <= "Z") hasUpper = true;
+    else if (c >= "a" && c <= "z") hasLower = true;
+    else if (c >= "0" && c <= "9") hasDigit = true;
+  }
+  return hasUpper && hasLower && hasDigit;
+}
+function detectApiKey(text) {
+  const spans = spansFrom(API_KEY_PREFIX_RE, text);
+  for (const [start, end] of spansFrom(API_KEY_GENERIC_RE, text)) {
+    if (spans.some(([s, e]) => start < e && s < end)) continue;
+    if (looksLikeGenericSecret(text.slice(start, end))) spans.push([start, end]);
+  }
+  return spans;
+}
+function detectBuiltin(name, text) {
+  const detector = BUILTIN[name];
+  if (!detector) throw new Error(`unknown built-in detector: ${name}`);
+  if (!text) return [];
+  return detector(text).sort((a, b) => a[0] - b[0]);
+}
+function ruleApplies(rule, opts) {
+  if (rule.applyAt !== "both" && rule.applyAt !== opts.phase) return false;
+  if (opts.phase === "ingest") return true;
+  if (!rule.unless.length) return true;
+  if (opts.principals === null) return false;
+  const held = new Set(opts.principals);
+  return !rule.unless.some((p) => held.has(p));
+}
+function spansForRule(rule, text, policy) {
+  if (rule.pattern !== null) {
+    const re = rule.patternRe() ?? new RegExp(rule.pattern, "g");
+    return spansFrom(re, text);
+  }
+  if (rule.detector !== null) {
+    const custom = policy.customDetectors[rule.detector];
+    if (custom) return [...custom(text)];
+    return detectBuiltin(rule.detector, text);
+  }
+  return [];
+}
+function hashToken(value, secretKey) {
+  const key = Buffer.isBuffer(secretKey) ? secretKey : Buffer.from(String(secretKey ?? ""));
+  return hmacSha256Hex(key, value).slice(0, HASH_TOKEN_CHARS);
+}
+function applyRedaction(text, policy, opts) {
+  if (!text || policy.isEmpty()) return [text, {}];
+  const principals = opts.principals ?? null;
+  const collected = [];
+  const fired = [];
+  const failed = [];
+  for (const rule of policy.rules) {
+    if (!ruleApplies(rule, { phase: opts.phase, principals })) continue;
+    if (rule.action === "hash" && !opts.secretKey) {
+      throw new Error(
+        `rule '${rule.name}': action='hash' requires a non-empty secretKey (an unkeyed HMAC is a reversible pseudonym, not a redaction)`
+      );
+    }
+    try {
+      const raw = spansForRule(rule, text, policy);
+      const ruleSpans = [];
+      let invalid = false;
+      for (const item of raw) {
+        const start = item?.[0];
+        const end = item?.[1];
+        if (typeof start !== "number" || typeof end !== "number") {
+          invalid = true;
+          continue;
+        }
+        if (!(start >= 0 && start < end && end <= text.length)) {
+          invalid = true;
+          continue;
+        }
+        ruleSpans.push([start, end]);
+      }
+      if (invalid) failed.push(rule.name);
+      for (const [s, e] of ruleSpans) collected.push([s, e, rule]);
+    } catch (exc) {
+      failed.push(rule.name);
+      if (opts.hooks) emitError(opts.hooks, exc, { stage: "redaction", rule: rule.name });
+    }
+  }
+  if (!collected.length) {
+    if (failed.length) return [text, { rules_fired: [], spans: 0, rules_failed: failed }];
+    return [text, {}];
+  }
+  collected.sort((a, b) => a[0] - b[0] || b[1] - b[0] - (a[1] - a[0]));
+  const merged = [];
+  for (const [start, end, rule] of collected) {
+    const last = merged[merged.length - 1];
+    if (last && start < last[1]) {
+      if (end > last[1]) last[1] = end;
+      continue;
+    }
+    merged.push([start, end, rule]);
+  }
+  const out = [];
+  let cursor = 0;
+  for (const [start, end, rule] of merged) {
+    out.push(text.slice(cursor, start));
+    const original = text.slice(start, end);
+    if (rule.action === "mask") out.push(rule.effectivePlaceholder());
+    else if (rule.action === "hash") {
+      out.push(`[${rule.name.toUpperCase()}:${hashToken(original, opts.secretKey)}]`);
+    }
+    if (!fired.includes(rule.name)) fired.push(rule.name);
+    cursor = end;
+  }
+  out.push(text.slice(cursor));
+  const note = { rules_fired: fired, spans: merged.length };
+  if (failed.length) note.rules_failed = failed;
+  return [out.join(""), note];
+}
+var BUILTIN_DETECTOR_NAMES, RedactionRule, RedactionPolicy, EMAIL_RE, PHONE_RE, SSN_RE, CARD_RE, IBAN_RE, API_KEY_ALNUM, API_KEY_PREFIX_RE, API_KEY_GENERIC_RE, UUID_RE, BUILTIN, HASH_TOKEN_CHARS;
+var init_redaction = __esm({
+  "src/redaction.ts"() {
+    init_crypto();
+    init_hooks();
+    BUILTIN_DETECTOR_NAMES = /* @__PURE__ */ new Set(["email", "phone", "ssn", "credit_card", "iban", "api_key"]);
+    RedactionRule = class {
+      name;
+      detector;
+      pattern;
+      field;
+      action;
+      placeholder;
+      applyAt;
+      unless;
+      compiled = null;
+      constructor(init) {
+        this.name = init.name;
+        this.detector = init.detector ?? null;
+        this.pattern = init.pattern ?? null;
+        this.field = init.field ?? null;
+        this.action = init.action ?? "mask";
+        this.placeholder = init.placeholder ?? null;
+        this.applyAt = init.applyAt ?? "output";
+        this.unless = init.unless ?? [];
+        this.validate();
+      }
+      validate() {
+        if (this.field !== null) {
+          throw new Error(
+            `rule '${this.name}': field-targeted rules are not implemented yet; use detector or pattern instead`
+          );
+        }
+        const targets = [this.detector, this.pattern].filter((t) => t !== null);
+        if (targets.length !== 1) {
+          throw new Error(`rule '${this.name}': exactly one of detector/pattern must be set`);
+        }
+        if (this.pattern !== null) {
+          try {
+            this.compiled = new RegExp(this.pattern, "g");
+          } catch (exc) {
+            throw new Error(`rule '${this.name}': invalid regex: ${exc}`);
+          }
+        }
+        if (this.unless.length && this.applyAt === "ingest") {
+          throw new Error(
+            `rule '${this.name}': unless is output-time only and cannot be set on an applyAt='ingest' rule`
+          );
+        }
+      }
+      patternRe() {
+        return this.compiled;
+      }
+      effectivePlaceholder() {
+        return this.placeholder || `[${this.name.toUpperCase()}]`;
+      }
+    };
+    RedactionPolicy = class {
+      rules;
+      customDetectors;
+      constructor(init = {}) {
+        this.rules = (init.rules ?? []).map((r) => r instanceof RedactionRule ? r : new RedactionRule(r));
+        this.customDetectors = init.customDetectors ?? {};
+        const seen = /* @__PURE__ */ new Set();
+        for (const rule of this.rules) {
+          if (seen.has(rule.name)) throw new Error(`duplicate rule name: '${rule.name}'`);
+          seen.add(rule.name);
+          if (rule.detector !== null) {
+            const known = BUILTIN_DETECTOR_NAMES.has(rule.detector) || rule.detector in this.customDetectors;
+            if (!known) {
+              throw new Error(
+                `rule '${rule.name}': unknown detector '${rule.detector}' (not built-in and not in customDetectors)`
+              );
+            }
+          }
+        }
+      }
+      isEmpty() {
+        return this.rules.length === 0;
+      }
+    };
+    EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+    PHONE_RE = /\+\d[\d\s-]{7,17}\d/g;
+    SSN_RE = /(?<!\d)\d{3}-\d{2}-\d{4}(?!\d)/g;
+    CARD_RE = /(?<!\d)(?:\d[ -]?){12,18}\d(?!\d)/g;
+    IBAN_RE = /(?<![A-Za-z0-9])[A-Z]{2}\d{2}[A-Z0-9]{10,30}(?![A-Za-z0-9])/g;
+    API_KEY_ALNUM = "A-Za-z0-9_\\-+/=";
+    API_KEY_PREFIX_RE = new RegExp(
+      `(?<![${API_KEY_ALNUM}])(?:(?:AKIA|ASIA)[0-9A-Z]{16}|sk-[A-Za-z0-9]{20,}|gh[opsu]_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9\\-]{10,}|AIza[0-9A-Za-z_\\-]{35})(?![${API_KEY_ALNUM}])`,
+      "g"
+    );
+    API_KEY_GENERIC_RE = new RegExp(
+      `(?<![${API_KEY_ALNUM}])[${API_KEY_ALNUM}]{24,}(?![${API_KEY_ALNUM}])`,
+      "g"
+    );
+    UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+    BUILTIN = {
+      email: (t) => spansFrom(EMAIL_RE, t),
+      phone: (t) => spansFrom(PHONE_RE, t),
+      ssn: (t) => spansFrom(SSN_RE, t),
+      credit_card: detectCreditCard,
+      iban: (t) => spansFrom(IBAN_RE, t),
+      api_key: detectApiKey
+    };
+    HASH_TOKEN_CHARS = 16;
+  }
+});
 function stripFences(text) {
   let t = text.trim();
   const fenced = /^```(?:json)?\s*([\s\S]*?)\s*```$/i.exec(t);
@@ -1084,17 +1443,38 @@ var init_json = __esm({
   "src/extraction/json.ts"() {
   }
 });
-function getFileExtension(filename) {
-  if (!filename?.includes(".")) return "";
-  return filename.slice(filename.lastIndexOf(".")).toLowerCase();
-}
-function isNonIngestibleMedia(filename, mime) {
-  const m = (mime || "").toLowerCase();
-  if (m.startsWith("audio/") || m.startsWith("video/")) return true;
-  return NON_INGESTIBLE_MEDIA_EXTS.has(getFileExtension(filename));
-}
-function isZip(content) {
-  return content.length >= 4 && content.subarray(0, 4).equals(ZIP_MAGIC);
+
+// src/extras.ts
+async function tryImport(specifier) {
+  try {
+    return await import(specifier);
+  } catch {
+    return null;
+  }
+}
+async function requireExtra(specifier, extra, what) {
+  try {
+    return await import(specifier);
+  } catch (_err) {
+    throw new ExtraMissingError(extra, specifier, what);
+  }
+}
+var init_extras = __esm({
+  "src/extras.ts"() {
+    init_errors();
+  }
+});
+function getFileExtension(filename) {
+  if (!filename?.includes(".")) return "";
+  return filename.slice(filename.lastIndexOf(".")).toLowerCase();
+}
+function isNonIngestibleMedia(filename, mime) {
+  const m = (mime || "").toLowerCase();
+  if (m.startsWith("audio/") || m.startsWith("video/")) return true;
+  return NON_INGESTIBLE_MEDIA_EXTS.has(getFileExtension(filename));
+}
+function isZip(content) {
+  return content.length >= 4 && content.subarray(0, 4).equals(ZIP_MAGIC);
 }
 function decodeXmlEntities(s) {
   return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
@@ -1474,25 +1854,182 @@ var init_files = __esm({
     XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
   }
 });
-
-// src/extras.ts
-async function tryImport(specifier) {
-  try {
-    return await import(specifier);
-  } catch {
-    return null;
+function camelize(key) {
+  return key.toLowerCase().replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function loadCeEnv() {
+  const root = {};
+  for (const [raw, value] of Object.entries(process.env)) {
+    if (!raw.startsWith("CE_") || value === void 0) continue;
+    const path = raw.slice(3).split("__").map(camelize);
+    let cur = root;
+    for (let i = 0; i < path.length - 1; i++) {
+      const k = path[i];
+      const next = cur[k];
+      if (typeof next !== "object" || next === null) cur[k] = {};
+      cur = cur[k];
+    }
+    cur[path[path.length - 1]] = coerceEnv(value);
   }
+  return root;
 }
-async function requireExtra(specifier, extra, what) {
-  try {
-    return await import(specifier);
-  } catch (_err) {
-    throw new ExtraMissingError(extra, specifier, what);
+function coerceEnv(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (/^-?\d+$/.test(value)) return Number(value);
+  if (/^-?\d+\.\d+$/.test(value)) return Number(value);
+  return value;
+}
+function deepMerge(a, b) {
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    if (v === void 0) continue;
+    const existing = out[k];
+    if (v && typeof v === "object" && !Array.isArray(v) && existing && typeof existing === "object" && !Array.isArray(existing)) {
+      out[k] = deepMerge(existing, v);
+    } else {
+      out[k] = v;
+    }
   }
+  return out;
 }
-var init_extras = __esm({
-  "src/extras.ts"() {
-    init_errors();
+var embeddingSchema, llmSchema, graphSchema, rerankerSchema, fusionSchema, storageSchema, extractionSchema, ContextEngineConfig;
+var init_config = __esm({
+  "src/config.ts"() {
+    init_redaction();
+    embeddingSchema = z.object({
+      provider: z.enum(["openai", "azure_openai", "gemini", "voyage", "cohere", "custom"]),
+      model: z.string(),
+      dim: z.number().int().positive().nullable().optional().default(null),
+      apiKey: z.string().nullable().optional().default(null),
+      baseUrl: z.string().nullable().optional().default(null)
+    });
+    llmSchema = z.object({
+      provider: z.enum(["anthropic", "openai", "azure_openai", "gemini", "bedrock", "custom"]),
+      model: z.string(),
+      apiKey: z.string().nullable().optional().default(null),
+      baseUrl: z.string().nullable().optional().default(null)
+    });
+    graphSchema = z.object({
+      enabled: z.boolean().default(false),
+      neo4jUri: z.string().nullable().optional().default(null),
+      neo4jUser: z.string().default("neo4j"),
+      neo4jPassword: z.string().nullable().optional().default(null),
+      neo4jDatabase: z.string().default("neo4j"),
+      extractionLlm: llmSchema.nullable().optional().default(null)
+    });
+    rerankerSchema = z.object({
+      enabled: z.boolean().default(false),
+      provider: z.enum(["cohere", "voyage", "jina", "custom"]).nullable().optional().default(null),
+      model: z.string().nullable().optional().default(null),
+      apiKey: z.string().nullable().optional().default(null),
+      baseUrl: z.string().nullable().optional().default(null),
+      candidates: z.number().int().positive().default(50)
+    });
+    fusionSchema = z.object({
+      method: z.literal("rrf").default("rrf"),
+      k: z.number().int().positive().default(60),
+      weights: z.record(z.string(), z.number()).default({ fts: 1, trgm: 0.8, ann: 1, graph: 1 })
+    });
+    storageSchema = z.object({
+      backend: z.literal("postgres").default("postgres"),
+      annExactThreshold: z.number().int().positive().default(5e4),
+      // Connection pool, passed straight through to `pg.Pool`. Sizing is a
+      // deployment decision (how many workers times how many concurrent searches
+      // each runs, against what the database allows), so these are pg's own
+      // defaults rather than a guess at your topology. (`pg` has no pre-ping.)
+      //
+      // Connections kept open in the pool.
+      poolMax: z.number().int().positive().default(10),
+      // Milliseconds an idle connection is kept before it is closed.
+      poolIdleTimeoutMs: z.number().int().nonnegative().default(1e4),
+      // Milliseconds a caller waits for a connection before the attempt fails.
+      poolConnectionTimeoutMs: z.number().int().nonnegative().default(3e4)
+    });
+    extractionSchema = z.object({
+      // Ceiling on an image's LONG EDGE in pixels, for rendered PDF pages and
+      // for images sent to the vision LLM.
+      maxRenderPx: z.number().int().positive().default(2e3),
+      // Ceiling on ONE vision batch's transcription, in output tokens — a reply
+      // far past a batch's honest bound is a repetition loop. Raising it is the
+      // fix if very dense pages come back truncated.
+      visionMaxOutputTokens: z.number().int().positive().default(16e3),
+      // Pages per vision-LLM call. Smaller batches mean more calls but more
+      // concurrency and less risk of hitting the output ceiling or a provider
+      // deadline; larger batches the reverse. Measure on your own corpus.
+      pagesPerVisionBatch: z.number().int().positive().default(5),
+      // Language hint for the Tesseract OCR fallback ('en', 'ur', 'mixed', any
+      // Tesseract code, or 'auto' for script detection). null (the default)
+      // detects the document's language from its usable text-layer pages and
+      // falls back to 'auto' when there is nothing to sample.
+      ocrLanguage: z.string().nullable().default(null)
+    });
+    ContextEngineConfig = class _ContextEngineConfig {
+      databaseUrl;
+      storage;
+      defaultMode;
+      embedding;
+      llm;
+      visionLlm;
+      graph;
+      reranker;
+      fusion;
+      extraction;
+      enableCodeExecution;
+      secretKey;
+      /**
+       * Lets http tools and probes reach loopback/private/link-local/metadata
+       * addresses. Off by default — an http tool is registered by a caller, and a
+       * private destination is server-side request forgery. See `tools/egress.ts`.
+       */
+      allowPrivateEgress;
+      redaction;
+      constructor(init) {
+        this.databaseUrl = init.databaseUrl;
+        this.storage = storageSchema.parse(init.storage ?? {});
+        this.defaultMode = init.defaultMode ?? "hybrid";
+        this.embedding = embeddingSchema.parse(init.embedding);
+        this.llm = init.llm ? llmSchema.parse(init.llm) : null;
+        this.visionLlm = init.visionLlm ? llmSchema.parse(init.visionLlm) : null;
+        this.graph = graphSchema.parse(init.graph ?? {});
+        this.reranker = rerankerSchema.parse(init.reranker ?? {});
+        this.fusion = fusionSchema.parse(init.fusion ?? {});
+        this.extraction = extractionSchema.parse(init.extraction ?? {});
+        this.enableCodeExecution = init.enableCodeExecution ?? false;
+        this.secretKey = init.secretKey ?? null;
+        this.allowPrivateEgress = init.allowPrivateEgress ?? false;
+        this.redaction = init.redaction instanceof RedactionPolicy ? init.redaction : new RedactionPolicy(init.redaction ?? {});
+        this.validate();
+      }
+      validate() {
+        if (this.graph.enabled && !(this.graph.neo4jUri && this.graph.neo4jPassword && this.graph.extractionLlm)) {
+          throw new Error("graph enabled but neo4jUri/neo4jPassword/extractionLlm missing");
+        }
+        if (this.reranker.enabled && !(this.reranker.provider && this.reranker.apiKey)) {
+          throw new Error("reranker enabled but provider/apiKey missing");
+        }
+        if (this.defaultMode === "graph" && !this.graph.enabled) {
+          throw new Error("defaultMode is 'graph' but graph enabled is false");
+        }
+        for (const rule of this.redaction.rules) {
+          if (rule.action === "hash" && !this.secretKey) {
+            throw new Error(
+              `redaction rule '${rule.name}': action='hash' requires ContextEngineConfig.secretKey to be set`
+            );
+          }
+        }
+      }
+      static fromEnv(overrides = {}) {
+        const env = loadCeEnv();
+        const merged = deepMerge(env, overrides);
+        if (!merged.databaseUrl || !merged.embedding) {
+          throw new Error(
+            "ContextEngineConfig.fromEnv requires CE_DATABASE_URL and CE_EMBEDDING__PROVIDER/MODEL (or explicit overrides)"
+          );
+        }
+        return new _ContextEngineConfig(merged);
+      }
+    };
   }
 });
 
@@ -1921,8 +2458,26 @@ __export(pdf_exports, {
   embeddedTextPerPage: () => embeddedTextPerPage,
   extract: () => extract,
   extractPdf: () => extract,
+  ocrLanguageHint: () => ocrLanguageHint,
   pageCount: () => pageCount
 });
+function ocrLanguageHint(texts, override) {
+  if (override) return override;
+  let sample = "";
+  const indices = [...texts.keys()].sort((a, b) => a - b).slice(0, 3);
+  for (const idx of indices) {
+    sample += texts.get(idx) ?? "";
+    if (sample.length >= OCR_LANG_SAMPLE_MIN) break;
+  }
+  if (sample.length >= OCR_LANG_SAMPLE_MIN) {
+    try {
+      const detected = detectLanguage(sample, 30);
+      if (detected) return detected;
+    } catch {
+    }
+  }
+  return "auto";
+}
 function isCcControl(ch) {
   if (ch === "\n" || ch === "\r" || ch === "	") return false;
   const cp = ch.codePointAt(0);
@@ -1975,16 +2530,27 @@ async function extract(content, opts) {
   const { pages, structured: structuredMarkdown } = await classifyPages(content);
   const providerTokens = {};
   let visionMarkdown = false;
+  let benignBlank = /* @__PURE__ */ new Set();
   if (pages.needsOcr.length) {
     if (opts.visionLlm) {
       try {
         const vision = await Promise.resolve().then(() => (init_vision(), vision_exports));
-        const [visionTexts, tokens] = await vision.extractPdfPages(content, pages.needsOcr, {
-          visionLlm: opts.visionLlm
+        const [visionTexts, tokens, outcomes] = await vision.extractPdfPages(content, pages.needsOcr, {
+          visionLlm: opts.visionLlm,
+          extraction: opts.extraction
         });
         for (const [idx, text] of Object.entries(visionTexts)) {
           pages.texts.set(Number(idx), text);
         }
+        benignBlank = new Set(
+          Object.entries(outcomes).filter(([, o]) => o.status === "blank").map(([idx]) => Number(idx))
+        );
+        const failed = Object.entries(outcomes).filter(([, o]) => o.status === "failed");
+        if (failed.length) {
+          console.warn(
+            `[pdf] vision failed on ${failed.length} of ${pages.needsOcr.length} pages: ` + failed.map(([idx, o]) => `page ${Number(idx) + 1}: ${o.error}`).join("; ")
+          );
+        }
         visionMarkdown = Object.keys(visionTexts).length > 0;
         for (const [key, val] of Object.entries(tokens)) {
           providerTokens[key] = (providerTokens[key] ?? 0) + val;
@@ -1996,9 +2562,17 @@ async function extract(content, opts) {
       try {
         const ocr = await Promise.resolve().then(() => (init_ocr(), ocr_exports));
         const vision = await Promise.resolve().then(() => (init_vision(), vision_exports));
-        const rendered = await vision.renderPdfPagesAsImages(content, pages.needsOcr);
+        const rendered = await vision.renderPdfPagesAsImages(
+          content,
+          pages.needsOcr,
+          150,
+          opts.extraction?.maxRenderPx ?? vision.MAX_RENDER_PX
+        );
+        const ocrConfig = {
+          language: ocrLanguageHint(pages.texts, opts.extraction?.ocrLanguage)
+        };
         for (const [idx, pngBytes] of rendered) {
-          const result = await ocr.extractImageTextOcr(pngBytes);
+          const result = await ocr.extractImageTextOcr(pngBytes, ocrConfig);
           if (result.text.trim()) pages.texts.set(idx, result.text.trim());
         }
       } catch (exc) {
@@ -2016,31 +2590,38 @@ async function extract(content, opts) {
     if (t) textParts.push(`--- Page ${i + 1} ---
 ${t}`);
   }
+  const unread = pages.needsOcr.filter((i) => !pages.texts.get(i) && !benignBlank.has(i));
   return new Extracted2({
     text: textParts.join("\n\n"),
     pages: pages.total,
     slides: null,
     mediaOnly: false,
     providerTokens,
-    isMarkdown: visionMarkdown || structuredMarkdown
+    isMarkdown: visionMarkdown || structuredMarkdown,
+    unreadableReason: unread.length ? opts.visionLlm ? "vision_failed" : "needs_vision" : null,
+    unreadablePages: unread.length
   });
 }
-var GARBAGE_SCAN_LIMIT, MIN_USABLE_TEXT_LEN;
+var GARBAGE_SCAN_LIMIT, MIN_USABLE_TEXT_LEN, OCR_LANG_SAMPLE_MIN;
 var init_pdf = __esm({
   "src/extraction/pdf.ts"() {
     init_errors();
     init_hooks();
+    init_text();
     init_pdf_structure();
     GARBAGE_SCAN_LIMIT = 2e4;
     MIN_USABLE_TEXT_LEN = 50;
+    OCR_LANG_SAMPLE_MIN = 100;
   }
 });
 
 // src/extraction/vision.ts
 var vision_exports = {};
 __export(vision_exports, {
+  MAX_RENDER_PX: () => MAX_RENDER_PX,
   PAGES_PER_VISION_BATCH: () => PAGES_PER_VISION_BATCH,
   VISION_BATCH_ATTEMPTS: () => VISION_BATCH_ATTEMPTS,
+  VISION_MAX_OUTPUT_TOKENS: () => VISION_MAX_OUTPUT_TOKENS,
   assignBatchPages: () => assignBatchPages,
   coercePagesResult: () => coercePagesResult,
   detectPdfVisionPages: () => detectPdfVisionPages,
@@ -2057,6 +2638,17 @@ function pagesPrompt(nImages) {
 Return JSON: {"pages": [{"page": 1, "text": "<markdown for this page>"}]}
 Return exactly ${nImages} page entries numbered 1 to ${nImages} in the order the images are given \u2014 IGNORE any page numbers printed on the pages.`;
 }
+function asText(value) {
+  if (typeof value === "string") return value;
+  if (value == null || typeof value === "boolean") return "";
+  if (Array.isArray(value)) {
+    return value.filter((v) => v != null && v !== "").map(asText).join("\n");
+  }
+  if (typeof value === "object") {
+    return Object.values(value).filter((v) => v != null && v !== "").map(asText).join("\n");
+  }
+  return String(value);
+}
 function coercePagesResult(parsed) {
   let base;
   let rawPages;
@@ -2076,7 +2668,7 @@ function coercePagesResult(parsed) {
       const rec = entry;
       pages.push({
         page: typeof rec.page === "number" ? rec.page : i + 1,
-        text: typeof rec.text === "string" ? rec.text : ""
+        text: asText(rec.text)
       });
     } else if (typeof entry === "string") {
       pages.push({ page: i + 1, text: entry });
@@ -2107,16 +2699,28 @@ function parsePagesResponse(rawText) {
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
-async function extractTextFromImages(images, opts) {
-  if (!images.length) return [[], {}];
-  const maxConcurrent = opts.maxConcurrent ?? 8;
-  const batches = [];
-  for (let i = 0; i < images.length; i += PAGES_PER_VISION_BATCH) {
-    batches.push(images.slice(i, i + PAGES_PER_VISION_BATCH));
+async function capped(image, canvas, maxPx) {
+  if (!canvas) return image;
+  try {
+    const img = await canvas.loadImage(image);
+    const longEdge = Math.max(img.width, img.height);
+    if (longEdge <= maxPx) return image;
+    const ratio = maxPx / longEdge;
+    const w = Math.max(Math.round(img.width * ratio), 1);
+    const h = Math.max(Math.round(img.height * ratio), 1);
+    const out = canvas.createCanvas(w, h);
+    out.getContext("2d").drawImage(img, 0, 0, w, h);
+    return out.toBuffer("image/png");
+  } catch {
+    return image;
   }
-  const results = Array.from({ length: images.length }, () => "");
+}
+async function runBatches(batchSource, opts) {
+  const started = Date.now();
+  const results = /* @__PURE__ */ new Map();
+  const outcomes = /* @__PURE__ */ new Map();
   const tokensTotal = { input: 0, output: 0 };
-  const semaphore = new Semaphore(maxConcurrent);
+  const maxConcurrent = opts.maxConcurrent ?? 8;
   let lock = Promise.resolve();
   const withLock = async (fn) => {
     const prev = lock;
@@ -2132,66 +2736,183 @@ async function extractTextFromImages(images, opts) {
     }
   };
   const client = buildLlmClient(opts.visionLlm);
-  const processBatch = async (batchIdx, batchImages) => {
-    await semaphore.acquire();
-    try {
-      const nImages = batchImages.length;
-      const prompt = pagesPrompt(nImages);
-      for (let attempt = 1; attempt <= VISION_BATCH_ATTEMPTS; attempt++) {
-        try {
-          const [rawText, usage] = await callLlm(opts.visionLlm, {
-            system: VISION_SYSTEM_PROMPT,
-            user: prompt,
-            jsonMode: true,
-            images: batchImages,
-            client
+  let total = 0;
+  let nBatches = 0;
+  const queue = new BoundedQueue(maxConcurrent);
+  const processBatch = async (batchNum, baseIdx, batchImages) => {
+    const batchStarted = Date.now();
+    let pendingLocal = batchImages.map((_, i) => i);
+    for (let attempt = 1; attempt <= VISION_BATCH_ATTEMPTS; attempt++) {
+      const ask = pendingLocal.map((i) => batchImages[i]);
+      try {
+        const [rawText, usage] = await callLlm(opts.visionLlm, {
+          system: VISION_SYSTEM_PROMPT,
+          user: pagesPrompt(ask.length),
+          jsonMode: true,
+          images: ask,
+          maxTokens: opts.extCfg.visionMaxOutputTokens,
+          // Transcription is not reasoning, and on a thinking model the two
+          // compete for the SAME budget — see `LlmCallOpts.thinkingBudget`.
+          // Zero, not small: there is nothing here to reason ABOUT, the model
+          // is being asked what is on the page. `temperature: 0` for the same
+          // reason — one scan must transcribe to the same text twice.
+          thinkingBudget: 0,
+          temperature: 0,
+          client
+        });
+        if (!rawText?.trim()) throw new Error("empty vision response");
+        const [, pages] = parsePagesResponse(rawText);
+        const assigned = assignBatchPages(pages, ask.length);
+        const batchSeconds = (Date.now() - batchStarted) / 1e3;
+        const stillMissing = [];
+        await withLock(() => {
+          tokensTotal.input += usage.input ?? 0;
+          tokensTotal.output += usage.output ?? 0;
+          pendingLocal.forEach((localIdx, position) => {
+            const pageText = assigned[position];
+            if (pageText === void 0) {
+              stillMissing.push(localIdx);
+              return;
+            }
+            results.set(baseIdx + localIdx, pageText);
+            outcomes.set(baseIdx + localIdx, {
+              status: pageText.trim() ? "read" : "blank",
+              attempts: attempt,
+              error: null,
+              seconds: batchSeconds
+            });
           });
-          if (!rawText?.trim()) throw new Error("empty vision response");
-          const [, pages] = parsePagesResponse(rawText);
-          const assigned = assignBatchPages(pages, nImages);
+        });
+        pendingLocal = stillMissing;
+        if (pendingLocal.length === 0) return;
+        if (attempt < VISION_BATCH_ATTEMPTS) {
+          console.warn(
+            `[vision] batch ${batchNum} attempt ${attempt} answered ${ask.length - pendingLocal.length} of ${ask.length} pages \u2014 asking again for ${pendingLocal.length}`
+          );
+          continue;
+        }
+        console.error(
+          `[vision] batch ${batchNum}: ${pendingLocal.length} page(s) never came back after ${attempt} attempts`
+        );
+        await withLock(() => {
+          for (const localIdx of pendingLocal) {
+            outcomes.set(baseIdx + localIdx, {
+              status: "failed",
+              attempts: attempt,
+              error: "page missing from batch response",
+              seconds: batchSeconds
+            });
+          }
+        });
+        return;
+      } catch (exc) {
+        if (attempt < VISION_BATCH_ATTEMPTS) {
+          console.warn(`[vision] batch ${batchNum} attempt ${attempt} failed: ${exc} \u2014 retrying`);
+          await sleep(2e3 * attempt);
+        } else {
+          console.error(`[vision] batch ${batchNum} failed after ${VISION_BATCH_ATTEMPTS} attempts: ${exc}`);
+          const batchSeconds = (Date.now() - batchStarted) / 1e3;
           await withLock(() => {
-            for (const [localIdx, pageText] of Object.entries(assigned)) {
-              const globalIdx = batchIdx * PAGES_PER_VISION_BATCH + Number(localIdx);
-              if (globalIdx >= 0 && globalIdx < results.length) results[globalIdx] = pageText;
+            for (const localIdx of pendingLocal) {
+              outcomes.set(baseIdx + localIdx, {
+                status: "failed",
+                attempts: attempt,
+                error: String(exc),
+                seconds: batchSeconds
+              });
             }
-            tokensTotal.input += usage.input ?? 0;
-            tokensTotal.output += usage.output ?? 0;
           });
-          return;
-        } catch (exc) {
-          if (attempt < VISION_BATCH_ATTEMPTS) {
-            console.warn(`[vision] batch ${batchIdx} attempt ${attempt} failed: ${exc} \u2014 retrying`);
-            await sleep(2e3 * attempt);
-          } else {
-            console.error(
-              `[vision] batch ${batchIdx} failed after ${VISION_BATCH_ATTEMPTS} attempts: ${exc}`
-            );
-          }
         }
       }
-    } finally {
-      semaphore.release();
     }
   };
+  const worker = async () => {
+    for (; ; ) {
+      const item = await queue.get();
+      if (item === null) return;
+      await processBatch(...item);
+    }
+  };
+  const workers = Array.from({ length: maxConcurrent }, () => worker());
   try {
-    await Promise.all(batches.map((b, i) => processBatch(i, b)));
+    for await (const [baseIdx, batchImages] of batchSource) {
+      if (!batchImages.length) continue;
+      for (let j = 0; j < batchImages.length; j++) {
+        outcomes.set(baseIdx + j, { status: "failed", attempts: 0, error: "never attempted", seconds: 0 });
+      }
+      total = Math.max(total, baseIdx + batchImages.length);
+      await queue.put([nBatches, baseIdx, batchImages]);
+      nBatches += 1;
+    }
+    queue.close();
+    await Promise.all(workers);
+  } catch (exc) {
+    queue.abort();
+    await Promise.allSettled(workers);
+    throw exc;
   } finally {
     await client.aclose();
   }
-  return [results, tokensTotal];
+  const texts = Array.from({ length: total }, (_, i) => results.get(i) ?? "");
+  const outcomeList = Array.from(
+    { length: total },
+    (_, i) => outcomes.get(i) ?? { status: "failed", attempts: 0, error: "never attempted", seconds: 0 }
+  );
+  const counts = { read: 0, blank: 0, failed: 0 };
+  for (const o of outcomeList) counts[o.status] += 1;
+  console.info(
+    `[vision] ${total} pages, ${nBatches} batches, ${((Date.now() - started) / 1e3).toFixed(1)}s, ${tokensTotal.input} in / ${tokensTotal.output} out tokens, ${counts.read} read / ${counts.blank} blank / ${counts.failed} failed`
+  );
+  return [texts, tokensTotal, outcomeList];
+}
+async function extractTextFromImages(images, opts) {
+  if (!images.length) return [[], {}, []];
+  const extCfg = opts.extraction ?? EXTRACTION_DEFAULTS;
+  const canvasModule = await tryImport("@napi-rs/canvas");
+  const sendable = await Promise.all(images.map((img) => capped(img, canvasModule, extCfg.maxRenderPx)));
+  const batchSize = extCfg.pagesPerVisionBatch ?? PAGES_PER_VISION_BATCH;
+  async function* batches() {
+    for (let i = 0; i < sendable.length; i += batchSize) {
+      yield [i, sendable.slice(i, i + batchSize)];
+    }
+  }
+  return runBatches(batches(), {
+    visionLlm: opts.visionLlm,
+    extCfg,
+    maxConcurrent: opts.maxConcurrent
+  });
 }
 async function extractPdfPages(content, pageIndices, opts) {
-  const rendered = await renderPdfPagesAsImages(content, pageIndices);
-  const images = rendered.map(([, png]) => png);
-  const [texts, tokens] = await extractTextFromImages(images, { visionLlm: opts.visionLlm });
+  const extCfg = opts.extraction ?? EXTRACTION_DEFAULTS;
+  const batchSize = extCfg.pagesPerVisionBatch ?? PAGES_PER_VISION_BATCH;
+  const pageOrder = [];
+  async function* renderedBatches() {
+    let pos = 0;
+    for (let start = 0; start < pageIndices.length; start += batchSize) {
+      const group = pageIndices.slice(start, start + batchSize);
+      const rendered = await renderPdfPagesAsImages(content, group, 150, extCfg.maxRenderPx);
+      if (!rendered.length) continue;
+      pageOrder.push(...rendered.map(([idx]) => idx));
+      yield [pos, rendered.map(([, png]) => png)];
+      pos += rendered.length;
+    }
+  }
+  const [texts, tokens, outcomes] = await runBatches(renderedBatches(), {
+    visionLlm: opts.visionLlm,
+    extCfg
+  });
   const pageTexts = {};
-  for (let i = 0; i < rendered.length; i++) {
+  const pageOutcomes = {};
+  for (let i = 0; i < pageOrder.length; i++) {
     const text = texts[i];
-    if (text?.trim()) pageTexts[rendered[i][0]] = text;
+    if (text?.trim()) pageTexts[pageOrder[i]] = text;
+    const outcome = outcomes[i];
+    if (outcome) pageOutcomes[pageOrder[i]] = outcome;
   }
-  return [pageTexts, tokens];
+  return [pageTexts, tokens, pageOutcomes];
 }
-async function renderPdfPagesAsImages(content, pageIndices, dpi = 150) {
+async function renderPdfPagesAsImages(content, pageIndices, dpi = 150, maxPx = MAX_RENDER_PX) {
+  const started = Date.now();
   const scale = dpi / 72;
   const data = new Uint8Array(content);
   const pdf = await getDocumentProxy(data);
@@ -2200,9 +2921,12 @@ async function renderPdfPagesAsImages(content, pageIndices, dpi = 150) {
   for (const idx of pageIndices) {
     if (idx < 0 || idx >= pdf.numPages) continue;
     try {
+      const page = await pdf.getPage(idx + 1);
+      const viewport = page.getViewport({ scale: 1 });
+      const pageScale = Math.min(scale, maxPx / Math.max(viewport.width, viewport.height, 1));
       const buf = await renderPageAsImage(pdf, idx + 1, {
         canvasImport: canvasImport ? async () => canvasImport : void 0,
-        scale
+        scale: pageScale
       });
       const bytes = buf instanceof ArrayBuffer ? new Uint8Array(buf) : new Uint8Array(buf);
       results.push([idx, Buffer.from(bytes)]);
@@ -2210,6 +2934,7 @@ async function renderPdfPagesAsImages(content, pageIndices, dpi = 150) {
       console.warn(`[vision] failed to render PDF page ${idx}:`, exc);
     }
   }
+  console.info(`[pdf] rastered ${results.length} pages in ${((Date.now() - started) / 1e3).toFixed(1)}s`);
   return results;
 }
 async function detectPdfVisionPages(content) {
@@ -2231,7 +2956,13 @@ async function detectPdfVisionPages(content) {
   return visionPages;
 }
 async function extractDocxImages(content) {
-  const zip = await JSZip.loadAsync(content);
+  let zip;
+  try {
+    zip = await JSZip.loadAsync(content);
+  } catch (exc) {
+    console.warn(`[vision] cannot open DOCX for images: ${exc}`);
+    return [];
+  }
   const rels = zip.file("word/_rels/document.xml.rels");
   if (!rels) return [];
   const xml = await rels.async("string");
@@ -2257,7 +2988,13 @@ async function extractDocxImages(content) {
   return images;
 }
 async function extractPptxImages(content) {
-  const zip = await JSZip.loadAsync(content);
+  let zip;
+  try {
+    zip = await JSZip.loadAsync(content);
+  } catch (exc) {
+    console.warn(`[vision] cannot open PPTX for images: ${exc}`);
+    return [];
+  }
   const slideNames = Object.keys(zip.files).filter((n) => /^ppt\/slides\/slide\d+\.xml$/.test(n)).sort((a, b) => {
     const na = Number(/slide(\d+)/.exec(a)?.[1] ?? 0);
     const nb = Number(/slide(\d+)/.exec(b)?.[1] ?? 0);
@@ -2290,12 +3027,22 @@ async function extractPptxImages(content) {
 }
 async function extractImage(content, opts) {
   const { Extracted: Extracted2 } = await Promise.resolve().then(() => (init_extraction(), extraction_exports));
+  const extCfg = opts.extraction ?? EXTRACTION_DEFAULTS;
+  const canvasModule = await tryImport("@napi-rs/canvas");
+  const image = await capped(content, canvasModule, extCfg.maxRenderPx);
   const [rawText, usage] = await callLlm(opts.visionLlm, {
     system: VISION_SYSTEM_PROMPT,
     user: `${MARKDOWN_RULES}
 
 Transcribe this single image. Return the Markdown only.`,
-    images: [content]
+    images: [image],
+    maxTokens: extCfg.visionMaxOutputTokens,
+    // Same contract as the batched path (see processBatch): with the output
+    // cap in place, default-on thinking bills against it — an all-thinking
+    // truncated-empty reply lands as vision_failed. Transcription is not
+    // reasoning, and it must be deterministic.
+    thinkingBudget: 0,
+    temperature: 0
   });
   const text = (rawText || "").trim();
   return new Extracted2({
@@ -2304,37 +3051,75 @@ Transcribe this single image. Return the Markdown only.`,
     slides: null,
     mediaOnly: !text,
     providerTokens: usage ?? {},
-    isMarkdown: Boolean(text)
+    isMarkdown: Boolean(text),
+    // A configured reader that returns nothing (refusal, filter, truncation)
+    // is the same "reader read nothing" state the PDF path labels
+    // vision_failed — not a blank image with no explanation.
+    unreadableReason: text ? null : "vision_failed",
+    unreadablePages: text ? 0 : 1
   });
 }
-var PAGES_PER_VISION_BATCH, VISION_BATCH_ATTEMPTS, VISION_SYSTEM_PROMPT, MARKDOWN_RULES, Semaphore;
+var VISION_BATCH_ATTEMPTS, EXTRACTION_DEFAULTS, MAX_RENDER_PX, VISION_MAX_OUTPUT_TOKENS, PAGES_PER_VISION_BATCH, VISION_SYSTEM_PROMPT, MARKDOWN_RULES, BoundedQueue;
 var init_vision = __esm({
   "src/extraction/vision.ts"() {
+    init_config();
     init_extras();
     init_llm();
     init_json();
     init_pdf();
-    PAGES_PER_VISION_BATCH = 5;
     VISION_BATCH_ATTEMPTS = 3;
+    EXTRACTION_DEFAULTS = extractionSchema.parse({});
+    MAX_RENDER_PX = EXTRACTION_DEFAULTS.maxRenderPx;
+    VISION_MAX_OUTPUT_TOKENS = EXTRACTION_DEFAULTS.visionMaxOutputTokens;
+    PAGES_PER_VISION_BATCH = EXTRACTION_DEFAULTS.pagesPerVisionBatch;
     VISION_SYSTEM_PROMPT = "You are a precise document transcription engine. You transcribe page images into clean GitHub-flavored Markdown that preserves tables, headings, and reading order \u2014 verbatim, never summarizing, translating, or inventing content.";
     MARKDOWN_RULES = "Transcribe into clean Markdown that PRESERVES structure:\n- TABLES: reproduce as GitHub-flavored Markdown tables \u2014 one row per line, real column separators, keep EVERY cell (empty cell for blanks; put a spanning cell's value in its top-left position). NEVER flatten a table into a sentence.\n- HEADINGS/TITLES: mark with #/##/### by visual hierarchy.\n- LISTS: use - or 1. as printed.\n- FIGURES/CHARTS: add a short italic caption line, e.g. *Figure: bar chart of ...*.\n- Follow natural reading order (multi-column pages: finish the left column, then the right).\n- Transcribe VERBATIM \u2014 every word, number, label, caption. Do not summarize, translate, or invent.";
-    Semaphore = class {
-      n;
-      waiters = [];
-      constructor(max) {
-        this.n = max;
-      }
-      async acquire() {
-        if (this.n > 0) {
-          this.n -= 1;
-          return;
+    BoundedQueue = class {
+      constructor(maxsize) {
+        this.maxsize = maxsize;
+      }
+      maxsize;
+      items = [];
+      putters = [];
+      getters = [];
+      closed = false;
+      async put(item) {
+        while (!this.closed && this.items.length >= this.maxsize) {
+          await new Promise((resolve) => this.putters.push(resolve));
+        }
+        if (this.closed) return;
+        this.items.push(item);
+        this.getters.shift()?.();
+      }
+      /** `null` once the queue is closed AND drained — the worker's exit signal. */
+      async get() {
+        for (; ; ) {
+          if (this.items.length) {
+            const item = this.items.shift();
+            this.putters.shift()?.();
+            return item;
+          }
+          if (this.closed) return null;
+          await new Promise((resolve) => this.getters.push(resolve));
         }
-        await new Promise((resolve) => this.waiters.push(resolve));
       }
-      release() {
-        const next = this.waiters.shift();
-        if (next) next();
-        else this.n += 1;
+      close() {
+        this.closed = true;
+        for (const wake of this.getters.splice(0)) wake();
+        for (const wake of this.putters.splice(0)) wake();
+      }
+      /**
+       * Like `close()`, but for the error path: DISCARDS whatever is still
+       * queued rather than letting it drain. A batch already in a worker's hands
+       * keeps running (there is no cancelling that), but one that only ever sat
+       * in the queue must never start — the source has already failed, so
+       * spending a full vision-LLM retry budget on it buys nothing.
+       */
+      abort() {
+        this.closed = true;
+        this.items.length = 0;
+        for (const wake of this.getters.splice(0)) wake();
+        for (const wake of this.putters.splice(0)) wake();
       }
     };
   }
@@ -2344,7 +3129,8 @@ var init_vision = __esm({
 var extraction_exports = {};
 __export(extraction_exports, {
   Extracted: () => Extracted,
-  extract: () => extract2
+  extract: () => extract2,
+  extractEmbeddedImagesText: () => extractEmbeddedImagesText
 });
 function isPdf(ext, mime) {
   return ext === ".pdf" || mime === "application/pdf";
@@ -2352,14 +3138,50 @@ function isPdf(ext, mime) {
 function isImage(ext, mime) {
   return mime.startsWith("image/") || IMAGE_EXTS.has(ext);
 }
-async function extractEmbeddedImagesText(images, visionLlm, hooks) {
+async function officeUnreadable(text, images, visionLlm) {
+  if (text.trim()) return { reason: null, unread: 0 };
+  let readable = 0;
+  for (const img of images) {
+    if (!await embeddedImageIsNegligible(img.imageBytes)) readable += 1;
+  }
+  if (!readable) return { reason: null, unread: 0 };
+  return { reason: visionLlm ? "vision_failed" : "needs_vision", unread: readable };
+}
+async function embeddedImageIsNegligible(data) {
+  if (data.length < MIN_EMBEDDED_IMAGE_BYTES) return true;
+  const canvas = await tryImport("@napi-rs/canvas");
+  if (!canvas) return false;
+  try {
+    const img = await canvas.loadImage(data);
+    return Math.max(img.width, img.height) < MIN_EMBEDDED_IMAGE_PX;
+  } catch {
+    return false;
+  }
+}
+async function extractEmbeddedImagesText(images, visionLlm, hooks, extraction) {
   if (!images.length) return [[], {}];
   try {
     const vision = await Promise.resolve().then(() => (init_vision(), vision_exports));
-    return await vision.extractTextFromImages(
-      images.map((img) => img.imageBytes),
-      { visionLlm }
-    );
+    const { createHash: createHash3 } = await import('crypto');
+    const keys = [];
+    const firstAt = /* @__PURE__ */ new Map();
+    const send = [];
+    for (const img of images) {
+      const blob = img.imageBytes;
+      if (await embeddedImageIsNegligible(blob)) {
+        keys.push(null);
+        continue;
+      }
+      const digest = createHash3("sha256").update(blob).digest("hex");
+      if (!firstAt.has(digest)) {
+        firstAt.set(digest, send.length);
+        send.push(blob);
+      }
+      keys.push(digest);
+    }
+    if (!send.length) return [images.map(() => ""), {}];
+    const [texts, tokens] = await vision.extractTextFromImages(send, { visionLlm, extraction });
+    return [keys.map((k) => k == null ? "" : texts[firstAt.get(k)] ?? ""), tokens];
   } catch (exc) {
     emitError(hooks, exc, { stage: "embedded_image_vision" });
     return [[], {}];
@@ -2370,22 +3192,35 @@ async function extract2(content, filename, mime, opts) {
   const ext = getFileExtension(filename);
   const visionLlm = opts.visionLlm ?? null;
   const hooks = opts.hooks;
+  const extraction = opts.extraction ?? null;
   try {
     if (isNonIngestibleMedia(filename, m)) {
       return new Extracted({ text: "", mediaOnly: true });
     }
     if (isPdf(ext, m)) {
       const pdf = await Promise.resolve().then(() => (init_pdf(), pdf_exports));
-      return await pdf.extract(content, { visionLlm, hooks });
+      return await pdf.extract(content, { visionLlm, hooks, extraction });
     }
     if (isImage(ext, m)) {
-      if (!visionLlm) return new Extracted({ text: "", mediaOnly: true });
+      if (!visionLlm) {
+        return new Extracted({
+          text: "",
+          mediaOnly: true,
+          unreadableReason: "needs_vision",
+          unreadablePages: 1
+        });
+      }
       try {
         const vision = await Promise.resolve().then(() => (init_vision(), vision_exports));
-        return await vision.extractImage(content, { visionLlm });
+        return await vision.extractImage(content, { visionLlm, extraction });
       } catch (exc) {
         emitError(hooks, exc, { stage: "image_vision", filename });
-        return new Extracted({ text: "", mediaOnly: true });
+        return new Extracted({
+          text: "",
+          mediaOnly: true,
+          unreadableReason: "vision_failed",
+          unreadablePages: 1
+        });
       }
     }
     if (ext === ".docx" || m === DOCX_MIME) {
@@ -2393,10 +3228,11 @@ async function extract2(content, filename, mime, opts) {
       let providerTokens = {};
       let llmPictures = 0;
       let combined = text;
+      let images = [];
       if (visionLlm) {
         const vision = await Promise.resolve().then(() => (init_vision(), vision_exports));
-        const images = await vision.extractDocxImages(content);
-        const [texts, tokens] = await extractEmbeddedImagesText(images, visionLlm, hooks);
+        images = await vision.extractDocxImages(content);
+        const [texts, tokens] = await extractEmbeddedImagesText(images, visionLlm, hooks, extraction);
         for (let i = 0; i < texts.length; i++) {
           const imgText = texts[i];
           if (imgText) {
@@ -2407,12 +3243,18 @@ ${imgText}`;
           }
         }
         providerTokens = tokens;
+      } else if (!text.trim()) {
+        const vision = await Promise.resolve().then(() => (init_vision(), vision_exports));
+        images = await vision.extractDocxImages(content);
       }
+      const { reason, unread } = await officeUnreadable(combined, images, visionLlm);
       return new Extracted({
         text: combined,
         pages: await countDocxPages(content),
         providerTokens,
-        llmPictures
+        llmPictures,
+        unreadableReason: reason,
+        unreadablePages: unread
       });
     }
     if (ext === ".pptx" || m === PPTX_MIME) {
@@ -2420,10 +3262,11 @@ ${imgText}`;
       let providerTokens = {};
       let llmPictures = 0;
       let combined = text;
+      let images = [];
       if (visionLlm) {
         const vision = await Promise.resolve().then(() => (init_vision(), vision_exports));
-        const images = await vision.extractPptxImages(content);
-        const [texts, tokens] = await extractEmbeddedImagesText(images, visionLlm, hooks);
+        images = await vision.extractPptxImages(content);
+        const [texts, tokens] = await extractEmbeddedImagesText(images, visionLlm, hooks, extraction);
         for (let i = 0; i < texts.length; i++) {
           const imgText = texts[i];
           if (imgText) {
@@ -2435,12 +3278,18 @@ ${imgText}`;
           }
         }
         providerTokens = tokens;
+      } else if (!text.trim()) {
+        const vision = await Promise.resolve().then(() => (init_vision(), vision_exports));
+        images = await vision.extractPptxImages(content);
       }
+      const { reason, unread } = await officeUnreadable(combined, images, visionLlm);
       return new Extracted({
         text: combined,
         slides: await countPptxSlides(content),
         providerTokens,
-        llmPictures
+        llmPictures,
+        unreadableReason: reason,
+        unreadablePages: unread
       });
     }
     if (ext === ".xlsx" || m === XLSX_MIME) {
@@ -2464,9 +3313,10 @@ ${imgText}`;
     return new Extracted({ text: content.toString("utf8") });
   }
 }
-var IMAGE_EXTS, Extracted;
+var IMAGE_EXTS, Extracted, MIN_EMBEDDED_IMAGE_BYTES, MIN_EMBEDDED_IMAGE_PX;
 var init_extraction = __esm({
   "src/extraction/index.ts"() {
+    init_extras();
     init_hooks();
     init_files();
     IMAGE_EXTS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".bmp", ".tiff", ".tif", ".webp"]);
@@ -2478,6 +3328,10 @@ var init_extraction = __esm({
       providerTokens;
       llmPictures;
       isMarkdown;
+      /** See `UnreadableReason`. `mediaOnly` is the same idea for whole files and
+       *  stays set alongside this, so existing callers keep working. */
+      unreadableReason;
+      unreadablePages;
       constructor(init) {
         this.text = init.text;
         this.pages = init.pages ?? null;
@@ -2486,8 +3340,12 @@ var init_extraction = __esm({
         this.providerTokens = init.providerTokens ?? {};
         this.llmPictures = init.llmPictures ?? 0;
         this.isMarkdown = init.isMarkdown ?? false;
+        this.unreadableReason = init.unreadableReason ?? null;
+        this.unreadablePages = init.unreadablePages ?? 0;
       }
     };
+    MIN_EMBEDDED_IMAGE_BYTES = 3 * 1024;
+    MIN_EMBEDDED_IMAGE_PX = 100;
   }
 });
 
@@ -2532,6 +3390,9 @@ __export(db_exports, {
 function stripSqlNoise(sql) {
   return sql.replace(SQL_NOISE_RE, (m) => " ".repeat(m.length));
 }
+function stripSqlNoiseBackslash(sql) {
+  return sql.replace(SQL_NOISE_BACKSLASH_RE, (m) => " ".repeat(m.length));
+}
 function hasKeyword(sqlUpper, keyword) {
   return new RegExp(`\\b${keyword}\\b`).test(sqlUpper);
 }
@@ -2660,24 +3521,28 @@ async function executeQueryAsync(config, sql, maxRows, accessModeRaw) {
       `Invalid access_mode ${JSON.stringify(accessModeRaw)}; must be one of ${ALLOWED_ACCESS_MODES}`
     );
   }
-  const sqlUpper = stripSqlNoise(sql).trim().toUpperCase();
+  const sqlVariants = [
+    stripSqlNoise(sql).trim().toUpperCase(),
+    stripSqlNoiseBackslash(sql).trim().toUpperCase()
+  ];
+  const sqlUpper = sqlVariants[0];
   for (const keyword of ALWAYS_BLOCKED) {
-    if (hasKeyword(sqlUpper, keyword)) {
+    if ([...sqlVariants, sql.toUpperCase()].some((v) => hasKeyword(v, keyword))) {
       return { success: false, error: `${keyword} queries are not allowed` };
     }
   }
   if (accessMode === "readonly") {
-    if (!sqlUpper.startsWith("SELECT") && !sqlUpper.startsWith("WITH")) {
+    if (!sqlVariants.every((v) => v.startsWith("SELECT") || v.startsWith("WITH"))) {
       return { success: false, error: "Only SELECT queries are allowed in read-only mode" };
     }
     for (const keyword of READONLY_BLOCKED) {
-      if (hasKeyword(sqlUpper, keyword)) {
+      if (sqlVariants.some((v) => hasKeyword(v, keyword))) {
         return { success: false, error: `${keyword} queries are not allowed in read-only mode` };
       }
     }
   } else if (accessMode === "readwrite") {
     for (const keyword of READWRITE_BLOCKED) {
-      if (hasKeyword(sqlUpper, keyword)) {
+      if (sqlVariants.some((v) => hasKeyword(v, keyword))) {
         return { success: false, error: `${keyword} queries are not allowed in read-write mode` };
       }
     }
@@ -2811,7 +3676,7 @@ async function getSchemaText(config, selectedTables) {
   }
   return rowsToText(schemaRows);
 }
-var require2, MAX_ROWS, CONNECT_TIMEOUT, QUERY_TIMEOUT_MS, ALWAYS_BLOCKED, READONLY_BLOCKED, READWRITE_BLOCKED, ALLOWED_ACCESS_MODES, SQL_NOISE_RE;
+var require2, MAX_ROWS, CONNECT_TIMEOUT, QUERY_TIMEOUT_MS, ALWAYS_BLOCKED, READONLY_BLOCKED, READWRITE_BLOCKED, ALLOWED_ACCESS_MODES, SQL_NOISE_RE, SQL_NOISE_BACKSLASH_RE;
 var init_db = __esm({
   "src/tools/executors/db.ts"() {
     init_errors();
@@ -2820,10 +3685,22 @@ var init_db = __esm({
     CONNECT_TIMEOUT = 10;
     QUERY_TIMEOUT_MS = 3e4;
     ALWAYS_BLOCKED = ["GRANT", "REVOKE"];
-    READONLY_BLOCKED = ["INSERT", "UPDATE", "DELETE", "DROP", "ALTER", "CREATE", "TRUNCATE"];
-    READWRITE_BLOCKED = ["DELETE", "DROP", "TRUNCATE"];
+    READONLY_BLOCKED = [
+      "INSERT",
+      "UPDATE",
+      "DELETE",
+      "MERGE",
+      "DROP",
+      "ALTER",
+      "CREATE",
+      "TRUNCATE",
+      "DO",
+      "CALL"
+    ];
+    READWRITE_BLOCKED = ["DELETE", "DROP", "TRUNCATE", "DO", "CALL"];
     ALLOWED_ACCESS_MODES = ["readonly", "readwrite", "full"];
-    SQL_NOISE_RE = /'(?:[^']|'')*'|\$([A-Za-z_]\w*)?\$.*?\$\1?\$|--[^\n]*|\/\*[\s\S]*?\*\//g;
+    SQL_NOISE_RE = /\b[eE]'(?:[^'\\]|\\[\s\S]|'')*'|'(?:[^']|'')*'|--[^\n]*|\/\*[\s\S]*?\*\//g;
+    SQL_NOISE_BACKSLASH_RE = /'(?:[^'\\]|\\[\s\S]|'')*'|--[^\n]*|\/\*[\s\S]*?\*\//g;
   }
 });
 function mulberry322(seed) {
@@ -3655,7 +4532,8 @@ var retrieval_exports = {};
 __export(retrieval_exports, {
   buildGraphRanked: () => buildGraphRanked,
   corpusIsAclUniform: () => corpusIsAclUniform,
-  shouldUseCommunitySummaries: () => shouldUseCommunitySummaries
+  shouldUseCommunitySummaries: () => shouldUseCommunitySummaries,
+  vectorSeedIds: () => vectorSeedIds
 });
 function vecLiteral(vector) {
   return `[${vector.map((x) => Number(x)).join(",")}]`;
@@ -3681,8 +4559,8 @@ async function deriveQueryEntities(pool, chunkIds, opts) {
      JOIN context_engine_chunks c ON c.id = ce.chunk_id
      WHERE ce.chunk_id = ANY($1::uuid[]) ${SCOPE2}
      GROUP BY e.normalized_name, e.name, e.type
-     ORDER BY freq DESC LIMIT $4`,
-    [chunkIds, opts.sourceIds, opts.principals, ENTITY_LIMIT]
+     ORDER BY freq DESC LIMIT $5`,
+    [chunkIds, opts.sourceIds, opts.documentIds ?? null, opts.principals, ENTITY_LIMIT]
   );
   return result.rows.map((r) => ({
     normalized_name: r.normalized_name,
@@ -3747,8 +4625,8 @@ async function computeCommunityScores(pool, chunkIds, vector, opts) {
     `SELECT ce.chunk_id::text, ce.entity_id::text
      FROM context_engine_chunk_entities ce
      JOIN context_engine_chunks c ON c.id = ce.chunk_id
-     WHERE ce.chunk_id = ANY($1::uuid[]) AND ce.entity_id = ANY($4::uuid[]) ${SCOPE2}`,
-    [chunkIds, opts.sourceIds, opts.principals, Object.keys(entityScore)]
+     WHERE ce.chunk_id = ANY($1::uuid[]) AND ce.entity_id = ANY($5::uuid[]) ${SCOPE2}`,
+    [chunkIds, opts.sourceIds, opts.documentIds ?? null, opts.principals, Object.keys(entityScore)]
   );
   const chunkScores = {};
   for (const row of result.rows) {
@@ -3757,13 +4635,29 @@ async function computeCommunityScores(pool, chunkIds, vector, opts) {
   return chunkScores;
 }
 async function vectorSeedIds(pool, vector, opts) {
-  const result = await pool.query(
-    `SELECT c.id::text FROM context_engine_chunks c
-     WHERE c.embedding IS NOT NULL ${SCOPE2}
-     ORDER BY c.embedding <=> CAST($1 AS vector) LIMIT $4`,
-    [vecLiteral(vector), opts.sourceIds, opts.principals, SEED_LIMIT]
-  );
-  return result.rows.map((r) => String(r.id));
+  const binds = [opts.sourceIds, opts.documentIds ?? null, opts.principals];
+  const scoped = binds.some((v) => v !== null);
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    await opts.backend?.tuneAnnScan?.(client, SEED_LIMIT, scoped);
+    const result = await client.query(
+      `SELECT c.id::text FROM context_engine_chunks c
+       WHERE c.embedding IS NOT NULL ${SCOPE2}
+       ORDER BY c.embedding <=> CAST($1 AS vector) LIMIT $5`,
+      [vecLiteral(vector), ...binds, SEED_LIMIT]
+    );
+    await client.query("COMMIT");
+    return result.rows.map((r) => String(r.id));
+  } catch (err) {
+    try {
+      await client.query("ROLLBACK");
+    } catch {
+    }
+    throw err;
+  } finally {
+    client.release();
+  }
 }
 async function buildGraphRanked(query, opts) {
   try {
@@ -3772,11 +4666,18 @@ async function buildGraphRanked(query, opts) {
     const vector = vectors[0] ? [...vectors[0]] : null;
     if (!vector) return [];
     const sourceIds = opts.sourceIds ?? null;
+    const documentIds = opts.documentIds ?? null;
     const principals = opts.principals ?? null;
-    const seeds = await vectorSeedIds(opts.pool, vector, { sourceIds, principals });
+    const seeds = await vectorSeedIds(opts.pool, vector, {
+      sourceIds,
+      documentIds,
+      principals,
+      backend: opts.backend
+    });
     if (!seeds.length) return [];
     const queryEntities = await deriveQueryEntities(opts.pool, seeds.slice(0, TOP_SEEDS_FOR_ENTITIES), {
       sourceIds,
+      documentIds,
       principals
     });
     const entityNorms = queryEntities.map((e) => String(e.normalized_name));
@@ -3798,6 +4699,7 @@ async function buildGraphRanked(query, opts) {
     const relScores = await computeRelationshipScores(opts.pool, allIds, entityNorms);
     const commScores = await computeCommunityScores(opts.pool, allIds, vector, {
       sourceIds,
+      documentIds,
       principals,
       useSummaries
     });
@@ -3849,7 +4751,8 @@ var init_retrieval = __esm({
     TOP_SEEDS_FOR_ENTITIES = 20;
     SCOPE2 = `
   AND ($2::text[] IS NULL OR c.source_id = ANY($2::text[]))
-  AND ($3::text[] IS NULL OR c.acl IS NULL OR c.acl && $3::text[])
+  AND ($3::uuid[] IS NULL OR c.document_id = ANY($3::uuid[]))
+  AND ($4::text[] IS NULL OR c.acl IS NULL OR c.acl && $4::text[])
 `;
   }
 });
@@ -4434,381 +5337,96 @@ function splitIntoChunks(text, maxWords = 180, overlap = 18) {
   for (const ln of (text || "").split(/\r\n|\n|\r/)) {
     const stripped = ln.trim();
     if (!stripped) {
-      pendingBlank = units.length > 0;
-      continue;
-    }
-    const lineSep = pendingBlank ? "\n\n" : "\n";
-    pendingBlank = false;
-    if (HEADING_OR_BULLET_RE.test(ln) || stripped.length <= 120) {
-      units.push([lineSep, stripped, tokenize(stripped).length]);
-    } else {
-      let first = true;
-      for (const sent of splitSentences(ln)) {
-        const s = sent.trim();
-        if (s) {
-          units.push([first ? lineSep : " ", s, tokenize(s).length]);
-          first = false;
-        }
-      }
-    }
-  }
-  const normalizedUnits = [];
-  for (const [uSep, uText, uTokens] of units) {
-    if (uTokens <= maxWords) {
-      normalizedUnits.push([uSep, uText, uTokens]);
-      continue;
-    }
-    const windowChars = maxWords * 4;
-    const uChars = [...uText];
-    let pos = 0;
-    let pieceSep = uSep;
-    while (pos < uChars.length) {
-      let pieceChars = uChars.slice(pos, pos + windowChars);
-      let piece = pieceChars.join("");
-      if (pos + windowChars < uChars.length) {
-        const ws = piece.lastIndexOf(" ");
-        if (ws > Math.floor(windowChars / 2)) {
-          piece = piece.slice(0, ws);
-          pieceChars = [...piece];
-        }
-      }
-      let pieceTokens = tokenize(piece);
-      if (pieceTokens.length > maxWords) {
-        piece = pieceChars.slice(0, maxWords).join("");
-        pieceTokens = tokenize(piece);
-      }
-      normalizedUnits.push([pieceSep, piece, pieceTokens.length]);
-      pos += codePointLength(piece);
-      pieceSep = "";
-    }
-  }
-  if (!normalizedUnits.some(([, , t]) => t)) return [];
-  const chunks = [];
-  let lastKept = null;
-  let cur = [];
-  let curTokens = 0;
-  const flush = () => {
-    const chunk = assembleUnits(cur);
-    if (chunk && (lastKept === null || jaccardSim(chunk, lastKept) < 0.92)) {
-      chunks.push(chunk);
-      lastKept = chunk;
-    }
-    const carried = [];
-    let carriedTokens = 0;
-    for (let i = cur.length - 1; i >= 0; i--) {
-      const prev = cur[i];
-      if (prev[2] === 0 || carriedTokens + prev[2] > overlap) break;
-      carried.unshift(prev);
-      carriedTokens += prev[2];
-    }
-    cur = carried;
-    curTokens = carriedTokens;
-  };
-  for (const unit of normalizedUnits) {
-    if (cur.length && curTokens + unit[2] > maxWords) flush();
-    cur.push(unit);
-    curTokens += unit[2];
-  }
-  if (cur.length) {
-    const chunk = assembleUnits(cur);
-    if (chunk && (lastKept === null || jaccardSim(chunk, lastKept) < 0.92)) {
-      chunks.push(chunk);
-    }
-  }
-  return chunks;
-}
-
-// src/actions.ts
-init_errors();
-init_hooks();
-init_llm();
-function encryptDict(data, key) {
-  const nonce = randomBytes(12);
-  const cipher = createCipheriv("aes-256-gcm", key, nonce);
-  const plaintext = Buffer.from(JSON.stringify(data), "utf8");
-  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
-  const tag = cipher.getAuthTag();
-  return Buffer.concat([nonce, ciphertext, tag]).toString("base64");
-}
-function decryptDict(token, key) {
-  const raw = Buffer.from(token, "base64");
-  const nonce = raw.subarray(0, 12);
-  const tag = raw.subarray(raw.length - 16);
-  const ciphertext = raw.subarray(12, raw.length - 16);
-  const decipher = createDecipheriv("aes-256-gcm", key, nonce);
-  decipher.setAuthTag(tag);
-  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-  return JSON.parse(plaintext.toString("utf8"));
-}
-function getSecretKey(config) {
-  const secretKey = config.secretKey;
-  if (!secretKey) {
-    throw new Error(
-      "ContextEngineConfig.secretKey (env CE_SECRET_KEY) is not configured \u2014 a base64url-encoded 32-byte AES key is required to encrypt/decrypt tool configs that hold secrets."
-    );
-  }
-  return Buffer.from(secretKey, "base64url");
-}
-function hmacSha256Hex(key, value) {
-  const k = typeof key === "string" ? Buffer.from(key) : key;
-  return createHmac("sha256", k).update(value, "utf8").digest("hex");
-}
-
-// src/redaction.ts
-init_hooks();
-var BUILTIN_DETECTOR_NAMES = /* @__PURE__ */ new Set(["email", "phone", "ssn", "credit_card", "iban", "api_key"]);
-var RedactionRule = class {
-  name;
-  detector;
-  pattern;
-  field;
-  action;
-  placeholder;
-  applyAt;
-  unless;
-  compiled = null;
-  constructor(init) {
-    this.name = init.name;
-    this.detector = init.detector ?? null;
-    this.pattern = init.pattern ?? null;
-    this.field = init.field ?? null;
-    this.action = init.action ?? "mask";
-    this.placeholder = init.placeholder ?? null;
-    this.applyAt = init.applyAt ?? "output";
-    this.unless = init.unless ?? [];
-    this.validate();
-  }
-  validate() {
-    if (this.field !== null) {
-      throw new Error(
-        `rule '${this.name}': field-targeted rules are not implemented yet; use detector or pattern instead`
-      );
-    }
-    const targets = [this.detector, this.pattern].filter((t) => t !== null);
-    if (targets.length !== 1) {
-      throw new Error(`rule '${this.name}': exactly one of detector/pattern must be set`);
-    }
-    if (this.pattern !== null) {
-      try {
-        this.compiled = new RegExp(this.pattern, "g");
-      } catch (exc) {
-        throw new Error(`rule '${this.name}': invalid regex: ${exc}`);
-      }
-    }
-    if (this.unless.length && this.applyAt === "ingest") {
-      throw new Error(
-        `rule '${this.name}': unless is output-time only and cannot be set on an applyAt='ingest' rule`
-      );
-    }
-  }
-  patternRe() {
-    return this.compiled;
-  }
-  effectivePlaceholder() {
-    return this.placeholder || `[${this.name.toUpperCase()}]`;
-  }
-};
-var RedactionPolicy = class {
-  rules;
-  customDetectors;
-  constructor(init = {}) {
-    this.rules = (init.rules ?? []).map((r) => r instanceof RedactionRule ? r : new RedactionRule(r));
-    this.customDetectors = init.customDetectors ?? {};
-    const seen = /* @__PURE__ */ new Set();
-    for (const rule of this.rules) {
-      if (seen.has(rule.name)) throw new Error(`duplicate rule name: '${rule.name}'`);
-      seen.add(rule.name);
-      if (rule.detector !== null) {
-        const known = BUILTIN_DETECTOR_NAMES.has(rule.detector) || rule.detector in this.customDetectors;
-        if (!known) {
-          throw new Error(
-            `rule '${rule.name}': unknown detector '${rule.detector}' (not built-in and not in customDetectors)`
-          );
-        }
-      }
-    }
-  }
-  isEmpty() {
-    return this.rules.length === 0;
-  }
-};
-var EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
-var PHONE_RE = /\+\d[\d\s-]{7,17}\d/g;
-var SSN_RE = /(?<!\d)\d{3}-\d{2}-\d{4}(?!\d)/g;
-var CARD_RE = /(?<!\d)(?:\d[ -]?){12,18}\d(?!\d)/g;
-var IBAN_RE = /(?<![A-Za-z0-9])[A-Z]{2}\d{2}[A-Z0-9]{10,30}(?![A-Za-z0-9])/g;
-var API_KEY_ALNUM = "A-Za-z0-9_\\-+/=";
-var API_KEY_PREFIX_RE = new RegExp(
-  `(?<![${API_KEY_ALNUM}])(?:(?:AKIA|ASIA)[0-9A-Z]{16}|sk-[A-Za-z0-9]{20,}|gh[opsu]_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9\\-]{10,}|AIza[0-9A-Za-z_\\-]{35})(?![${API_KEY_ALNUM}])`,
-  "g"
-);
-var API_KEY_GENERIC_RE = new RegExp(
-  `(?<![${API_KEY_ALNUM}])[${API_KEY_ALNUM}]{24,}(?![${API_KEY_ALNUM}])`,
-  "g"
-);
-var UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
-function spansFrom(re, text) {
-  const out = [];
-  re.lastIndex = 0;
-  let m = re.exec(text);
-  while (m !== null) {
-    out.push([m.index, m.index + m[0].length]);
-    if (m[0].length === 0) re.lastIndex++;
-    m = re.exec(text);
-  }
-  return out;
-}
-function luhnOk(digits) {
-  let total = 0;
-  const rev = [...digits].reverse();
-  for (let i = 0; i < rev.length; i++) {
-    let d = Number(rev[i]);
-    if (i % 2 === 1) {
-      d *= 2;
-      if (d > 9) d -= 9;
-    }
-    total += d;
-  }
-  return total % 10 === 0;
-}
-function detectCreditCard(text) {
-  const spans = [];
-  for (const [start, end] of spansFrom(CARD_RE, text)) {
-    const digits = text.slice(start, end).replace(/[ -]/g, "");
-    if (digits.length >= 13 && digits.length <= 19 && luhnOk(digits)) {
-      spans.push([start, end]);
-    }
-  }
-  return spans;
-}
-function looksLikeGenericSecret(token) {
-  if (UUID_RE.test(token)) return false;
-  let hasUpper = false;
-  let hasLower = false;
-  let hasDigit = false;
-  for (const c of token) {
-    if (c >= "A" && c <= "Z") hasUpper = true;
-    else if (c >= "a" && c <= "z") hasLower = true;
-    else if (c >= "0" && c <= "9") hasDigit = true;
-  }
-  return hasUpper && hasLower && hasDigit;
-}
-function detectApiKey(text) {
-  const spans = spansFrom(API_KEY_PREFIX_RE, text);
-  for (const [start, end] of spansFrom(API_KEY_GENERIC_RE, text)) {
-    if (spans.some(([s, e]) => start < e && s < end)) continue;
-    if (looksLikeGenericSecret(text.slice(start, end))) spans.push([start, end]);
-  }
-  return spans;
-}
-var BUILTIN = {
-  email: (t) => spansFrom(EMAIL_RE, t),
-  phone: (t) => spansFrom(PHONE_RE, t),
-  ssn: (t) => spansFrom(SSN_RE, t),
-  credit_card: detectCreditCard,
-  iban: (t) => spansFrom(IBAN_RE, t),
-  api_key: detectApiKey
-};
-function detectBuiltin(name, text) {
-  const detector = BUILTIN[name];
-  if (!detector) throw new Error(`unknown built-in detector: ${name}`);
-  if (!text) return [];
-  return detector(text).sort((a, b) => a[0] - b[0]);
-}
-function ruleApplies(rule, opts) {
-  if (rule.applyAt !== "both" && rule.applyAt !== opts.phase) return false;
-  if (opts.phase === "ingest") return true;
-  if (!rule.unless.length) return true;
-  if (opts.principals === null) return false;
-  const held = new Set(opts.principals);
-  return !rule.unless.some((p) => held.has(p));
-}
-function spansForRule(rule, text, policy) {
-  if (rule.pattern !== null) {
-    const re = rule.patternRe() ?? new RegExp(rule.pattern, "g");
-    return spansFrom(re, text);
-  }
-  if (rule.detector !== null) {
-    const custom = policy.customDetectors[rule.detector];
-    if (custom) return [...custom(text)];
-    return detectBuiltin(rule.detector, text);
-  }
-  return [];
-}
-var HASH_TOKEN_CHARS = 16;
-function hashToken(value, secretKey) {
-  const key = Buffer.isBuffer(secretKey) ? secretKey : Buffer.from(String(secretKey ?? ""));
-  return hmacSha256Hex(key, value).slice(0, HASH_TOKEN_CHARS);
-}
-function applyRedaction(text, policy, opts) {
-  if (!text || policy.isEmpty()) return [text, {}];
-  const principals = opts.principals ?? null;
-  const collected = [];
-  const fired = [];
-  const failed = [];
-  for (const rule of policy.rules) {
-    if (!ruleApplies(rule, { phase: opts.phase, principals })) continue;
-    if (rule.action === "hash" && !opts.secretKey) {
-      throw new Error(
-        `rule '${rule.name}': action='hash' requires a non-empty secretKey (an unkeyed HMAC is a reversible pseudonym, not a redaction)`
-      );
+      pendingBlank = units.length > 0;
+      continue;
     }
-    try {
-      const raw = spansForRule(rule, text, policy);
-      const ruleSpans = [];
-      let invalid = false;
-      for (const item of raw) {
-        const start = item?.[0];
-        const end = item?.[1];
-        if (typeof start !== "number" || typeof end !== "number") {
-          invalid = true;
-          continue;
-        }
-        if (!(start >= 0 && start < end && end <= text.length)) {
-          invalid = true;
-          continue;
+    const lineSep = pendingBlank ? "\n\n" : "\n";
+    pendingBlank = false;
+    if (HEADING_OR_BULLET_RE.test(ln) || stripped.length <= 120) {
+      units.push([lineSep, stripped, tokenize(stripped).length]);
+    } else {
+      let first = true;
+      for (const sent of splitSentences(ln)) {
+        const s = sent.trim();
+        if (s) {
+          units.push([first ? lineSep : " ", s, tokenize(s).length]);
+          first = false;
         }
-        ruleSpans.push([start, end]);
       }
-      if (invalid) failed.push(rule.name);
-      for (const [s, e] of ruleSpans) collected.push([s, e, rule]);
-    } catch (exc) {
-      failed.push(rule.name);
-      if (opts.hooks) emitError(opts.hooks, exc, { stage: "redaction", rule: rule.name });
     }
   }
-  if (!collected.length) {
-    if (failed.length) return [text, { rules_fired: [], spans: 0, rules_failed: failed }];
-    return [text, {}];
-  }
-  collected.sort((a, b) => a[0] - b[0] || b[1] - b[0] - (a[1] - a[0]));
-  const merged = [];
-  for (const [start, end, rule] of collected) {
-    const last = merged[merged.length - 1];
-    if (last && start < last[1]) {
-      if (end > last[1]) last[1] = end;
+  const normalizedUnits = [];
+  for (const [uSep, uText, uTokens] of units) {
+    if (uTokens <= maxWords) {
+      normalizedUnits.push([uSep, uText, uTokens]);
       continue;
     }
-    merged.push([start, end, rule]);
+    const windowChars = maxWords * 4;
+    const uChars = [...uText];
+    let pos = 0;
+    let pieceSep = uSep;
+    while (pos < uChars.length) {
+      let pieceChars = uChars.slice(pos, pos + windowChars);
+      let piece = pieceChars.join("");
+      if (pos + windowChars < uChars.length) {
+        const ws = piece.lastIndexOf(" ");
+        if (ws > Math.floor(windowChars / 2)) {
+          piece = piece.slice(0, ws);
+          pieceChars = [...piece];
+        }
+      }
+      let pieceTokens = tokenize(piece);
+      if (pieceTokens.length > maxWords) {
+        piece = pieceChars.slice(0, maxWords).join("");
+        pieceTokens = tokenize(piece);
+      }
+      normalizedUnits.push([pieceSep, piece, pieceTokens.length]);
+      pos += codePointLength(piece);
+      pieceSep = "";
+    }
   }
-  const out = [];
-  let cursor = 0;
-  for (const [start, end, rule] of merged) {
-    out.push(text.slice(cursor, start));
-    const original = text.slice(start, end);
-    if (rule.action === "mask") out.push(rule.effectivePlaceholder());
-    else if (rule.action === "hash") {
-      out.push(`[${rule.name.toUpperCase()}:${hashToken(original, opts.secretKey)}]`);
+  if (!normalizedUnits.some(([, , t]) => t)) return [];
+  const chunks = [];
+  let lastKept = null;
+  let cur = [];
+  let curTokens = 0;
+  const flush = () => {
+    const chunk = assembleUnits(cur);
+    if (chunk && (lastKept === null || jaccardSim(chunk, lastKept) < 0.92)) {
+      chunks.push(chunk);
+      lastKept = chunk;
     }
-    if (!fired.includes(rule.name)) fired.push(rule.name);
-    cursor = end;
+    const carried = [];
+    let carriedTokens = 0;
+    for (let i = cur.length - 1; i >= 0; i--) {
+      const prev = cur[i];
+      if (prev[2] === 0 || carriedTokens + prev[2] > overlap) break;
+      carried.unshift(prev);
+      carriedTokens += prev[2];
+    }
+    cur = carried;
+    curTokens = carriedTokens;
+  };
+  for (const unit of normalizedUnits) {
+    if (cur.length && curTokens + unit[2] > maxWords) flush();
+    cur.push(unit);
+    curTokens += unit[2];
   }
-  out.push(text.slice(cursor));
-  const note = { rules_fired: fired, spans: merged.length };
-  if (failed.length) note.rules_failed = failed;
-  return [out.join(""), note];
+  if (cur.length) {
+    const chunk = assembleUnits(cur);
+    if (chunk && (lastKept === null || jaccardSim(chunk, lastKept) < 0.92)) {
+      chunks.push(chunk);
+    }
+  }
+  return chunks;
 }
 
+// src/actions.ts
+init_errors();
+init_hooks();
+init_llm();
+init_redaction();
+
 // src/sandbox.ts
 init_errors();
 var DEFAULT_TIMEOUT = 30;
@@ -5347,6 +5965,39 @@ async function nearestField(pool, vector, sourceIds, docType) {
   if (similarity < FIELD_RESOLUTION_SIMILARITY_FLOOR) return null;
   return String(row.key_norm);
 }
+
+// src/sentinels.ts
+var UNSET = /* @__PURE__ */ Symbol.for("context_engine.UNSET");
+var TRUSTED = /* @__PURE__ */ Symbol.for("context_engine.TRUSTED");
+var warnedMethods = /* @__PURE__ */ new Set();
+function resolvePrincipals(value, method) {
+  if (value === TRUSTED) return null;
+  if (value === void 0 || value === null) {
+    if (!warnedMethods.has(method)) {
+      warnedMethods.add(method);
+      process.emitWarning(
+        `${method}(principals=${value === null ? "null" : "undefined"}) means TRUSTED CALLER \u2014 access control is disabled and every document is returned. If that is what you want, pass principals=TRUSTED (from @promptev/context-engine) to say so explicitly. If you meant 'no authenticated user', pass principals=[] instead. Passing null/omitting will raise in 1.0.`,
+        { type: "DeprecationWarning", code: "CE_PRINCIPALS_NULL" }
+      );
+    }
+    return null;
+  }
+  if (!Array.isArray(value)) {
+    throw new TypeError(
+      `${method}(principals=...) must be an array of principal strings, [] for an anonymous caller, or TRUSTED \u2014 got ${typeof value}. A non-array value must never silently disable ACL filtering.`
+    );
+  }
+  return value;
+}
+
+// src/tools/acl.ts
+function aclVisible(acl, principals) {
+  if (principals === null || principals === TRUSTED) return true;
+  if (acl == null) return true;
+  if (!acl.length) return false;
+  const held = new Set(principals ?? []);
+  return acl.some((p) => held.has(p));
+}
 init_extraction();
 init_hooks();
 var TIMEOUT_MS2 = 3e4;
@@ -5434,6 +6085,7 @@ async function pollEmbeddingBatch(cfg2, batchId, opts = {}) {
 }
 
 // src/ingest.ts
+init_redaction();
 init_usage();
 var MODE_RANK = { hybrid: 0, graph: 1 };
 var EMBED_BATCH = 256;
@@ -5520,7 +6172,9 @@ async function prepare(opts) {
       mediaOnly: false,
       providerTokens: {},
       contentHash: calculateContentHash({ fullText: clean }),
-      isMarkdown: false
+      isMarkdown: false,
+      unreadableReason: null,
+      unreadablePages: 0
     };
   }
   const content = opts.content;
@@ -5528,11 +6182,12 @@ async function prepare(opts) {
   const mime = mimeForFilename(fname) || "";
   const extracted = await extract2(content, fname, mime || null, {
     visionLlm: opts.config.visionLlm,
+    extraction: opts.config.extraction,
     hooks: opts.hooks
   });
   let body = sanitizeText(extracted.text || "") || "";
   const effectiveMime = mime || inferMime(body, fname) || DEFAULT_MIME;
-  if (effectiveMime === "application/pdf" && body) body = dedupLines(body);
+  if (effectiveMime === "application/pdf" && body && !extracted.isMarkdown) body = dedupLines(body);
   return {
     text: body,
     mime: effectiveMime,
@@ -5543,7 +6198,9 @@ async function prepare(opts) {
     mediaOnly: Boolean(extracted.mediaOnly),
     providerTokens: { ...extracted.providerTokens ?? {} },
     contentHash: calculateContentHash({ docBytes: content }),
-    isMarkdown: Boolean(extracted.isMarkdown)
+    isMarkdown: Boolean(extracted.isMarkdown),
+    unreadableReason: extracted.unreadableReason ?? null,
+    unreadablePages: extracted.unreadablePages ?? 0
   };
 }
 function computeUnits(prepared) {
@@ -5721,7 +6378,11 @@ async function decide(pool, opts) {
   }
   const same = stored != null && incoming != null && (Buffer.isBuffer(stored) && Buffer.isBuffer(incoming) ? Buffer.compare(stored, incoming) === 0 : stored === incoming);
   if (!same) return { action: "process", documentId: existingId };
-  if (existing.status === "skipped") return { action: "skip", documentId: existingId };
+  if (existing.status === "skipped") {
+    const metaData = existing.meta_data;
+    if (metaData?.unreadable_reason) return { action: "process", documentId: existingId };
+    return { action: "skip", documentId: existingId };
+  }
   const reqMode = opts.request.mode ?? "hybrid";
   if ((MODE_RANK[reqMode] ?? 0) <= (MODE_RANK[existing.mode || "hybrid"] ?? 0)) {
     return { action: "skip", documentId: existingId };
@@ -6012,6 +6673,22 @@ function singleReport(doc) {
 async function maybeAwait(value) {
   return value;
 }
+function progress(hooks, request, displayName, documentId, stage, state, detail = {}) {
+  emitProgress(hooks, {
+    sourceId: request.sourceId ?? null,
+    externalId: request.externalId ?? null,
+    documentId: documentId == null ? null : String(documentId),
+    name: displayName,
+    stage,
+    state,
+    detail: { ...detail }
+  });
+}
+function extractMethod(prepared, text) {
+  if (text != null) return "text";
+  if (Object.keys(prepared.providerTokens).length || prepared.isMarkdown) return "vision";
+  return "parser";
+}
 async function runModeUpgrade(request, opts) {
   await refreshOnSkip(request, {
     pool: opts.pool,
@@ -6025,6 +6702,7 @@ async function runModeUpgrade(request, opts) {
   let chunkCount = 0;
   try {
     if (request.mode === "graph" && opts.graphStage) {
+      progress(opts.hooks, request, opts.displayName, opts.documentId, "graph", "started");
       graphUnits2 = Number(
         await maybeAwait(
           opts.graphStage({
@@ -6035,6 +6713,9 @@ async function runModeUpgrade(request, opts) {
           })
         ) || 0
       );
+      progress(opts.hooks, request, opts.displayName, opts.documentId, "graph", "done", {
+        graph_units: graphUnits2
+      });
     }
     chunkCount = await upgradeMode(opts.pool, opts.documentId, request.mode ?? "hybrid");
   } catch (exc) {
@@ -6124,6 +6805,7 @@ async function runIngest(request, opts) {
       );
     }
   }
+  progress(opts.hooks, request, displayName, null, "extract", "started");
   const prepared = await prepare({
     content,
     filename,
@@ -6132,6 +6814,11 @@ async function runIngest(request, opts) {
     config: opts.config,
     hooks: opts.hooks
   });
+  progress(opts.hooks, request, displayName, null, "extract", "done", {
+    pages: prepared.pages,
+    method: extractMethod(prepared, text),
+    mime: prepared.mime
+  });
   const ingestHash = sha256Bytes(prepared.text || "");
   const decision = await decide(opts.pool, {
     request: { ...request, mode },
@@ -6218,8 +6905,11 @@ async function runIngest(request, opts) {
   const metaUpdates = { ...request.metaData ?? {} };
   metaUpdates.mime_type = prepared.mime;
   if (prepared.contentHash) metaUpdates.content_hash = prepared.contentHash;
+  metaUpdates.unreadable_reason = prepared.unreadableReason;
+  metaUpdates.unreadable_pages = prepared.unreadablePages;
   const redactionFailed = [];
   let documentText;
+  progress(opts.hooks, request, displayName, documentId, "redact", "started");
   try {
     documentText = redactDocumentText(
       prepared.text,
@@ -6232,6 +6922,9 @@ async function runIngest(request, opts) {
     await finalizeDocument(opts.pool, documentId, { status: "failed", error: String(exc) });
     throw exc;
   }
+  progress(opts.hooks, request, displayName, documentId, "redact", "done", {
+    rules_failed: redactionFailed.length
+  });
   if (!prepared.text.trim() || prepared.mediaOnly || looksMostlyBoilerplate(prepared.text)) {
     const reason = prepared.mediaOnly ? "media-only (no extractable text)" : "no extractable text";
     await opts.backend.upsertChunks(documentId, request.sourceId ?? null, request.acl ?? null, []);
@@ -6257,7 +6950,13 @@ async function runIngest(request, opts) {
       graphUnits: 0,
       providerTokens: {},
       error: reason,
-      redactionFailed
+      redactionFailed,
+      // Extraction RAN here — an unreadable scan is exactly what lands in
+      // this branch, so this is the report that has to say why. The
+      // dedup-skip/upgrade sites stay at the defaults: they never extracted
+      // and would be claiming blind.
+      unreadableReason: prepared.unreadableReason,
+      unreadablePages: prepared.unreadablePages
     });
   }
   const units = computeUnits(prepared);
@@ -6267,18 +6966,26 @@ async function runIngest(request, opts) {
   let rows = [];
   let effectiveMime = prepared.mime;
   try {
+    progress(opts.hooks, request, displayName, documentId, "chunk", "started");
     [rows, effectiveMime] = buildChunks(prepared, request.name, {
       policy: opts.config.redaction,
       secretKey: opts.config.secretKey,
       hooks: opts.hooks,
       failed: redactionFailed
     });
+    progress(opts.hooks, request, displayName, documentId, "chunk", "done", { chunks: rows.length });
+    progress(opts.hooks, request, displayName, documentId, "embed", "started");
     if (request.batch) {
       await opts.backend.upsertChunks(documentId, request.sourceId ?? null, request.acl ?? null, rows);
       const batchId = await submitEmbeddingBatch(
         opts.config.embedding,
         rows.map((r) => r.text)
       );
+      progress(opts.hooks, request, displayName, documentId, "embed", "done", {
+        batch: true,
+        batch_id: batchId,
+        chunks: rows.length
+      });
       metaUpdates.mime_type = effectiveMime;
       metaUpdates.batch = {
         id: batchId,
@@ -6308,15 +7015,26 @@ async function runIngest(request, opts) {
         graphUnits: 0,
         providerTokens,
         error: null,
-        redactionFailed
+        redactionFailed,
+        // Extraction RAN here just like the skipped/failed/completed sites —
+        // this report has to say why pages were unreadable too, not leave
+        // the caller to re-derive it later from listDocuments.
+        unreadableReason: prepared.unreadableReason,
+        unreadablePages: prepared.unreadablePages
       });
     }
     const embeddingTokens = await embedChunks(opts.embedder, rows);
     if (embeddingTokens) providerTokens.embedding_tokens = embeddingTokens;
     await recordEmbeddingDim(opts.pool, opts.embedder.dim);
     await opts.backend.upsertChunks(documentId, request.sourceId ?? null, request.acl ?? null, rows);
+    progress(opts.hooks, request, displayName, documentId, "embed", "done", {
+      batch: false,
+      chunks: rows.length,
+      tokens: embeddingTokens
+    });
     const structuredKw = {};
     if (request.extractStructured && opts.config.llm) {
+      progress(opts.hooks, request, displayName, documentId, "structured", "started");
       const extraction = await extractStructuredData(documentText, {
         llmCfg: opts.config.llm,
         fieldHints: request.fieldHints
@@ -6357,9 +7075,15 @@ async function runIngest(request, opts) {
           document: displayName
         });
       }
+      progress(opts.hooks, request, displayName, documentId, "structured", "done", {
+        document_type: extraction.documentType,
+        keys: extraction.keysNormalized.length,
+        quality: extraction.quality
+      });
     }
     let graphUnits2 = 0;
     if (mode === "graph" && opts.graphStage) {
+      progress(opts.hooks, request, displayName, documentId, "graph", "started");
       graphUnits2 = Number(
         await maybeAwait(
           opts.graphStage({
@@ -6370,6 +7094,7 @@ async function runIngest(request, opts) {
           })
         ) || 0
       );
+      progress(opts.hooks, request, displayName, documentId, "graph", "done", { graph_units: graphUnits2 });
     }
     metaUpdates.mime_type = effectiveMime;
     await finalizeDocument(opts.pool, documentId, {
@@ -6409,7 +7134,9 @@ async function runIngest(request, opts) {
       graphUnits: graphUnits2,
       providerTokens,
       error: null,
-      redactionFailed
+      redactionFailed,
+      unreadableReason: prepared.unreadableReason,
+      unreadablePages: prepared.unreadablePages
     });
   } catch (exc) {
     emitError(opts.hooks, exc, { stage: "ingest", document: displayName });
@@ -6424,7 +7151,9 @@ async function runIngest(request, opts) {
       graphUnits: 0,
       providerTokens,
       error: String(exc),
-      redactionFailed
+      redactionFailed,
+      unreadableReason: prepared.unreadableReason,
+      unreadablePages: prepared.unreadablePages
     });
   }
 }
@@ -6521,12 +7250,7 @@ function parseDocumentId(documentId) {
   }
   return raw;
 }
-function visible(acl, principals) {
-  if (principals === null) return true;
-  if (acl == null) return true;
-  const held = new Set(principals);
-  return acl.some((p) => held.has(p));
-}
+var visible = aclVisible;
 function scopeSql(sourceIds, principals, params) {
   const where = [];
   if (sourceIds != null) {
@@ -6615,7 +7339,9 @@ async function getDocumentRow(pool, documentId, principals) {
     createdAt: doc.created_at,
     updatedAt: doc.updated_at,
     startedAt: doc.started_at,
-    completedAt: doc.completed_at
+    completedAt: doc.completed_at,
+    unreadableReason: doc.meta_data?.unreadable_reason ?? null,
+    unreadablePages: doc.meta_data?.unreadable_pages ?? 0
   };
 }
 async function stats(pool, sourceId) {
@@ -6672,7 +7398,7 @@ async function listDocuments(opts) {
   params.push(limit + 1);
   const { rows } = await opts.pool.query(
     `SELECT id, source_id, external_id, name, description, mode, mime_type, lang, status,
-            document_type, created_at, updated_at, acl
+            document_type, created_at, updated_at, acl, meta_data
      FROM context_engine_documents
      ${where}
      ORDER BY created_at DESC, id DESC
@@ -6697,7 +7423,15 @@ async function listDocuments(opts) {
       hooks: opts.hooks
     }),
     createdAt: doc.created_at instanceof Date ? doc.created_at.toISOString() : doc.created_at,
-    updatedAt: doc.updated_at instanceof Date ? doc.updated_at.toISOString() : doc.updated_at
+    updatedAt: doc.updated_at instanceof Date ? doc.updated_at.toISOString() : doc.updated_at,
+    unreadableReason: doc.meta_data?.unreadable_reason ?? null,
+    unreadablePages: doc.meta_data?.unreadable_pages ?? 0,
+    // WHO can see this. Stored, enforced on every query and editable through
+    // updateDocument — and, until this line, invisible to every caller,
+    // because this serializer builds a FIXED object. `null` is UNRESTRICTED
+    // and must stay null; an empty array would read as "nobody", which is the
+    // opposite claim.
+    acl: doc.acl ?? null
   }));
   const result = {
     documents,
@@ -6855,9 +7589,9 @@ async function compute(instruction, opts) {
     return `mime_type ILIKE $${params.length}`;
   }).join(" OR ");
   where = where ? `${where} AND (${mimeClause})` : `WHERE (${mimeClause})`;
-  if (opts.docIds?.length) {
+  if (opts.documentIds?.length) {
     const parsedIds = [];
-    for (const did of opts.docIds) {
+    for (const did of opts.documentIds) {
       try {
         parsedIds.push(parseDocumentId(did));
       } catch {
@@ -6885,13 +7619,13 @@ async function compute(instruction, opts) {
   }
   if (tabular.length > MAX_COMPUTE_DOCUMENTS) {
     throw new EngineActionError(
-      `more than ${MAX_COMPUTE_DOCUMENTS} tabular documents are in scope for compute() \u2014 narrow the request with docIds or sourceIds`
+      `more than ${MAX_COMPUTE_DOCUMENTS} tabular documents are in scope for compute() \u2014 narrow the request with documentIds or sourceIds`
     );
   }
   const totalChars = tabular.reduce((n, d) => n + String(d.text ?? "").length, 0);
   if (totalChars > MAX_COMPUTE_TEXT_CHARS) {
     throw new EngineActionError(
-      `in-scope spreadsheet text too large to load (${totalChars} chars > ${MAX_COMPUTE_TEXT_CHARS} cap) \u2014 narrow the request with docIds or sourceIds`
+      `in-scope spreadsheet text too large to load (${totalChars} chars > ${MAX_COMPUTE_TEXT_CHARS} cap) \u2014 narrow the request with documentIds or sourceIds`
     );
   }
   const dfs = {};
@@ -6931,182 +7665,52 @@ ${schemaLines.join("\n")}`;
       user: userPrompt,
       jsonMode: false
     });
-  } catch (exc) {
-    emitError(opts.hooks, exc, { stage: "compute_codegen", instruction: instruction.slice(0, 200) });
-    throw exc;
-  }
-  const code = stripCodeFences(rawCode);
-  const execResult = await executeSafeCode(code, { dfs, documents }, { timeout });
-  if (!execResult.success) {
-    let maskedCode;
-    try {
-      maskedCode = redactValueRecursive(code.slice(0, 500), opts.config.redaction, {
-        principals,
-        secretKey: opts.config.secretKey,
-        hooks: opts.hooks
-      });
-    } catch {
-      maskedCode = "<redaction failed: code omitted>";
-    }
-    emitError(opts.hooks, new Error(execResult.error || "compute execution failed"), {
-      stage: "compute_exec",
-      code: maskedCode
-    });
-  }
-  const result = {
-    success: execResult.success,
-    result: execResult.result,
-    code,
-    stdout: execResult.stdout ?? "",
-    error: execResult.error,
-    executionTime: execResult.executionTime,
-    documentsUsed: documents.map((d) => d.id),
-    providerTokens: {
-      llm_input: tokens?.input ?? 0,
-      llm_output: tokens?.output ?? 0
-    }
-  };
-  return redactValueRecursive(result, opts.config.redaction, {
-    principals,
-    secretKey: opts.config.secretKey,
-    hooks: opts.hooks
-  });
-}
-var embeddingSchema = z.object({
-  provider: z.enum(["openai", "azure_openai", "gemini", "voyage", "cohere", "custom"]),
-  model: z.string(),
-  dim: z.number().int().positive().nullable().optional().default(null),
-  apiKey: z.string().nullable().optional().default(null),
-  baseUrl: z.string().nullable().optional().default(null)
-});
-var llmSchema = z.object({
-  provider: z.enum(["anthropic", "openai", "azure_openai", "gemini", "bedrock", "custom"]),
-  model: z.string(),
-  apiKey: z.string().nullable().optional().default(null),
-  baseUrl: z.string().nullable().optional().default(null)
-});
-var graphSchema = z.object({
-  enabled: z.boolean().default(false),
-  neo4jUri: z.string().nullable().optional().default(null),
-  neo4jUser: z.string().default("neo4j"),
-  neo4jPassword: z.string().nullable().optional().default(null),
-  neo4jDatabase: z.string().default("neo4j"),
-  extractionLlm: llmSchema.nullable().optional().default(null)
-});
-var rerankerSchema = z.object({
-  enabled: z.boolean().default(false),
-  provider: z.enum(["cohere", "voyage", "jina", "custom"]).nullable().optional().default(null),
-  model: z.string().nullable().optional().default(null),
-  apiKey: z.string().nullable().optional().default(null),
-  baseUrl: z.string().nullable().optional().default(null),
-  candidates: z.number().int().positive().default(50)
-});
-var fusionSchema = z.object({
-  method: z.literal("rrf").default("rrf"),
-  k: z.number().int().positive().default(60),
-  weights: z.record(z.string(), z.number()).default({ fts: 1, trgm: 0.8, ann: 1, graph: 1 })
-});
-var storageSchema = z.object({
-  backend: z.literal("postgres").default("postgres"),
-  annExactThreshold: z.number().int().positive().default(5e4)
-});
-var ContextEngineConfig = class _ContextEngineConfig {
-  databaseUrl;
-  storage;
-  defaultMode;
-  embedding;
-  llm;
-  visionLlm;
-  graph;
-  reranker;
-  fusion;
-  enableCodeExecution;
-  secretKey;
-  redaction;
-  constructor(init) {
-    this.databaseUrl = init.databaseUrl;
-    this.storage = storageSchema.parse(init.storage ?? {});
-    this.defaultMode = init.defaultMode ?? "hybrid";
-    this.embedding = embeddingSchema.parse(init.embedding);
-    this.llm = init.llm ? llmSchema.parse(init.llm) : null;
-    this.visionLlm = init.visionLlm ? llmSchema.parse(init.visionLlm) : null;
-    this.graph = graphSchema.parse(init.graph ?? {});
-    this.reranker = rerankerSchema.parse(init.reranker ?? {});
-    this.fusion = fusionSchema.parse(init.fusion ?? {});
-    this.enableCodeExecution = init.enableCodeExecution ?? false;
-    this.secretKey = init.secretKey ?? null;
-    this.redaction = init.redaction instanceof RedactionPolicy ? init.redaction : new RedactionPolicy(init.redaction ?? {});
-    this.validate();
-  }
-  validate() {
-    if (this.graph.enabled && !(this.graph.neo4jUri && this.graph.neo4jPassword && this.graph.extractionLlm)) {
-      throw new Error("graph enabled but neo4jUri/neo4jPassword/extractionLlm missing");
-    }
-    if (this.reranker.enabled && !(this.reranker.provider && this.reranker.apiKey)) {
-      throw new Error("reranker enabled but provider/apiKey missing");
-    }
-    if (this.defaultMode === "graph" && !this.graph.enabled) {
-      throw new Error("defaultMode is 'graph' but graph enabled is false");
-    }
-    for (const rule of this.redaction.rules) {
-      if (rule.action === "hash" && !this.secretKey) {
-        throw new Error(
-          `redaction rule '${rule.name}': action='hash' requires ContextEngineConfig.secretKey to be set`
-        );
-      }
-    }
-  }
-  static fromEnv(overrides = {}) {
-    const env = loadCeEnv();
-    const merged = deepMerge(env, overrides);
-    if (!merged.databaseUrl || !merged.embedding) {
-      throw new Error(
-        "ContextEngineConfig.fromEnv requires CE_DATABASE_URL and CE_EMBEDDING__PROVIDER/MODEL (or explicit overrides)"
-      );
-    }
-    return new _ContextEngineConfig(merged);
-  }
-};
-function camelize(key) {
-  return key.toLowerCase().replace(/_([a-z])/g, (_, c) => c.toUpperCase());
-}
-function loadCeEnv() {
-  const root = {};
-  for (const [raw, value] of Object.entries(process.env)) {
-    if (!raw.startsWith("CE_") || value === void 0) continue;
-    const path = raw.slice(3).split("__").map(camelize);
-    let cur = root;
-    for (let i = 0; i < path.length - 1; i++) {
-      const k = path[i];
-      const next = cur[k];
-      if (typeof next !== "object" || next === null) cur[k] = {};
-      cur = cur[k];
-    }
-    cur[path[path.length - 1]] = coerceEnv(value);
-  }
-  return root;
-}
-function coerceEnv(value) {
-  if (value === "true") return true;
-  if (value === "false") return false;
-  if (/^-?\d+$/.test(value)) return Number(value);
-  if (/^-?\d+\.\d+$/.test(value)) return Number(value);
-  return value;
-}
-function deepMerge(a, b) {
-  const out = { ...a };
-  for (const [k, v] of Object.entries(b)) {
-    if (v === void 0) continue;
-    const existing = out[k];
-    if (v && typeof v === "object" && !Array.isArray(v) && existing && typeof existing === "object" && !Array.isArray(existing)) {
-      out[k] = deepMerge(existing, v);
-    } else {
-      out[k] = v;
+  } catch (exc) {
+    emitError(opts.hooks, exc, { stage: "compute_codegen", instruction: instruction.slice(0, 200) });
+    throw exc;
+  }
+  const code = stripCodeFences(rawCode);
+  const execResult = await executeSafeCode(code, { dfs, documents }, { timeout });
+  if (!execResult.success) {
+    let maskedCode;
+    try {
+      maskedCode = redactValueRecursive(code.slice(0, 500), opts.config.redaction, {
+        principals,
+        secretKey: opts.config.secretKey,
+        hooks: opts.hooks
+      });
+    } catch {
+      maskedCode = "<redaction failed: code omitted>";
     }
+    emitError(opts.hooks, new Error(execResult.error || "compute execution failed"), {
+      stage: "compute_exec",
+      code: maskedCode
+    });
   }
-  return out;
+  const result = {
+    success: execResult.success,
+    result: execResult.result,
+    code,
+    stdout: execResult.stdout ?? "",
+    error: execResult.error,
+    executionTime: execResult.executionTime,
+    documentsUsed: documents.map((d) => d.id),
+    providerTokens: {
+      llm_input: tokens?.input ?? 0,
+      llm_output: tokens?.output ?? 0
+    }
+  };
+  return redactValueRecursive(result, opts.config.redaction, {
+    principals,
+    secretKey: opts.config.secretKey,
+    hooks: opts.hooks
+  });
 }
 
+// src/index.ts
+init_config();
+init_crypto();
+
 // src/db.ts
 init_errors();
 var VERSION_TABLE = "context_engine_alembic_version";
@@ -7189,6 +7793,7 @@ async function runMigrate(databaseUrl, opts = {}) {
       recorded = rev;
       done.add(rev);
     }
+    await client.query(loadSql("0004_acl_indexes", dim));
     const meta = await client.query("SELECT embedding_dim FROM context_engine_meta WHERE id = 1");
     if (!meta.rows.length) {
       await client.query("INSERT INTO context_engine_meta (id, embedding_dim) VALUES (1, $1)", [dim]);
@@ -7365,7 +7970,7 @@ async function loadGeminiEmbedClient(apiKey) {
   if (!Ctor) {
     throw new ExtraMissingError("gemini", specifier, "gemini embeddings");
   }
-  return new Ctor({ apiKey: apiKey ?? null });
+  return new Ctor({ apiKey: apiKey ?? null, httpOptions: { timeout: TIMEOUT_MS3 } });
 }
 function buildEmbedder(cfg2, opts) {
   if (opts?.client || opts?.fetch || opts?.fetchImpl) {
@@ -7383,6 +7988,9 @@ function buildEmbedder(cfg2, opts) {
   throw new Error(`unknown embedding provider: ${JSON.stringify(cfg2.provider)}`);
 }
 
+// src/engine.ts
+init_redaction();
+
 // src/compression.ts
 init_text();
 var TOKENS_PER_CHAR = 0.25;
@@ -8686,6 +9294,7 @@ async function rerank(cfg2, query, docs, opts = {}) {
 }
 
 // src/search.ts
+init_redaction();
 var MIN_LEG_CANDIDATES = 50;
 var MAX_LEG_CANDIDATES = 500;
 var UNITS_PER_SCOPE_HYBRID = 1;
@@ -8895,6 +9504,7 @@ async function runSearch(query, opts) {
   const topK = Math.max(1, Math.trunc(opts.topK ?? 10));
   const scope = {
     sourceIds: opts.sourceIds != null ? [...opts.sourceIds] : null,
+    documentIds: opts.documentIds != null ? [...opts.documentIds] : null,
     principals: opts.principals != null ? [...opts.principals] : null,
     limit: legLimit(topK, opts.config)
   };
@@ -8915,13 +9525,8 @@ async function runSearch(query, opts) {
   let degraded = null;
   if (mode === "graph" && !graphLeg) {
     degraded = "graph_leg_unavailable";
-    emitError(
-      opts.hooks,
-      new GraphLegUnavailable(
-        "search(mode='graph') ran the hybrid legs only: no graph ranked list was supplied (the graph retrieval leg is not implemented yet). Results are hybrid and billed as hybrid."
-      ),
-      { stage: "graph_leg", mode, degraded }
-    );
+    const reason = opts.graphRanked?.length ? "search(mode='graph') ran the hybrid legs only: the supplied graph ranked list was filtered to nothing by the search scope (source/document/ACL) \u2014 every candidate lies outside it. Results are hybrid and billed as hybrid." : "search(mode='graph') ran the hybrid legs only: graph retrieval supplied no candidates. Results are hybrid and billed as hybrid.";
+    emitError(opts.hooks, new GraphLegUnavailable(reason), { stage: "graph_leg", mode, degraded });
   }
   const fused = rrfFuse(ranked, { k: opts.config.fusion.k, weights: opts.config.fusion.weights });
   const window = opts.config.reranker.enabled ? Math.max(topK, opts.config.reranker.candidates) : topK;
@@ -8996,31 +9601,6 @@ async function runSearch(query, opts) {
   return { hits, usage };
 }
 
-// src/sentinels.ts
-var UNSET = /* @__PURE__ */ Symbol.for("context_engine.UNSET");
-var TrustedSentinel = class {
-  [Symbol.toStringTag] = "TRUSTED";
-  toString() {
-    return "TRUSTED";
-  }
-  valueOf() {
-    return true;
-  }
-};
-var TRUSTED = Object.freeze(new TrustedSentinel());
-function resolvePrincipals(value, method) {
-  if (value === TRUSTED) return null;
-  if (value === void 0) return null;
-  if (value === null) {
-    process.emitWarning(
-      `${method}(principals=null) means TRUSTED CALLER \u2014 access control is disabled and every document is returned. If that is what you want, pass principals=TRUSTED (from @promptev/context-engine) to say so explicitly. If you meant 'no authenticated user', pass principals=[] instead; null returns the entire corpus. Passing null will raise in 1.0.`,
-      "DeprecationWarning"
-    );
-    return null;
-  }
-  return Array.isArray(value) ? value : null;
-}
-
 // src/storage.ts
 init_text();
 var MIN_ITERATIVE_SCAN_VERSION = [0, 8];
@@ -9059,25 +9639,26 @@ function trigramThreshold(query) {
 }
 var SCOPE = `
   AND ($1::text[] IS NULL OR c.source_id = ANY($1))
-  AND ($2::text[] IS NULL OR c.acl IS NULL OR c.acl && $2)
+  AND ($2::uuid[] IS NULL OR c.document_id = ANY($2::uuid[]))
+  AND ($3::text[] IS NULL OR c.acl IS NULL OR c.acl && $3)
 `;
 var SQL_FTS = `
 SELECT c.id::text
 FROM context_engine_chunks c
 WHERE c.text IS NOT NULL
-  AND c.text_search @@ websearch_to_tsquery('simple'::regconfig, $3)
+  AND c.text_search @@ websearch_to_tsquery('simple'::regconfig, $4)
   ${SCOPE}
-ORDER BY ts_rank_cd(c.text_search, websearch_to_tsquery('simple'::regconfig, $3)) DESC, c.id
-LIMIT $4
+ORDER BY ts_rank_cd(c.text_search, websearch_to_tsquery('simple'::regconfig, $4)) DESC, c.id
+LIMIT $5
 `;
 var SQL_TRGM = `
 SELECT c.id::text
 FROM context_engine_chunks c
 WHERE c.text IS NOT NULL
-  AND c.text_trgm_norm % $3
+  AND c.text_trgm_norm % $4
   ${SCOPE}
-ORDER BY similarity(c.text_trgm_norm, $3) DESC, c.id
-LIMIT $4
+ORDER BY similarity(c.text_trgm_norm, $4) DESC, c.id
+LIMIT $5
 `;
 var SQL_COUNT_ELIGIBLE = `
 SELECT count(*)::int AS count FROM (
@@ -9085,13 +9666,13 @@ SELECT count(*)::int AS count FROM (
   FROM context_engine_chunks c
   WHERE c.embedding IS NOT NULL
     ${SCOPE}
-  LIMIT $3
+  LIMIT $4
 ) probe
 `;
 var SQL_FILTER_IDS = `
 SELECT c.id::text
 FROM context_engine_chunks c
-WHERE c.id = ANY($3::uuid[])
+WHERE c.id = ANY($4::uuid[])
   ${SCOPE}
 `;
 var UUID_RE4 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -9110,7 +9691,7 @@ FROM context_engine_chunks c
 WHERE c.embedding IS NOT NULL
   ${SCOPE}
 ORDER BY c.embedding <=> ${vec}
-LIMIT $3
+LIMIT $4
 `;
 }
 function sqlAnnExact(vec) {
@@ -9123,7 +9704,7 @@ WITH eligible AS MATERIALIZED (
 )
 SELECT id::text FROM eligible
 ORDER BY embedding <=> ${vec}
-LIMIT $3
+LIMIT $4
 `;
 }
 function idsOf(rows) {
@@ -9150,24 +9731,26 @@ var PostgresBackend = class {
    * mean different things.
    */
   scopeParams(scope) {
-    return [
-      scope.sourceIds != null ? [...scope.sourceIds] : null,
-      scope.principals != null ? [...scope.principals] : null,
-      Math.max(1, Math.trunc(scope.limit ?? 50))
-    ];
+    return {
+      binds: [
+        scope.sourceIds != null ? [...scope.sourceIds] : null,
+        scope.documentIds != null ? [...scope.documentIds] : null,
+        scope.principals != null ? [...scope.principals] : null
+      ],
+      lim: Math.max(1, Math.trunc(scope.limit ?? 50))
+    };
   }
   async upsertChunks(documentId, sourceId, acl, chunks) {
     const client = await this.pool.connect();
     try {
       await client.query("BEGIN");
       await client.query("DELETE FROM context_engine_chunks WHERE document_id = $1", [documentId]);
-      for (const c of chunks) {
-        const emb = c.embedding != null ? vectorLiteral2(c.embedding) : "NULL";
-        await client.query(
-          `INSERT INTO context_engine_chunks
-            (id, document_id, source_id, acl, idx, text, lang, embedding, meta_data)
-           VALUES ($1, $2, $3, $4, $5, $6, $7, ${emb}, $8::jsonb)`,
-          [
+      const BATCH = 500;
+      for (let start = 0; start < chunks.length; start += BATCH) {
+        const batch = chunks.slice(start, start + BATCH);
+        const params = [];
+        const rows = batch.map((c) => {
+          params.push(
             randomUUID(),
             documentId,
             sourceId,
@@ -9176,7 +9759,16 @@ var PostgresBackend = class {
             c.text,
             c.lang ?? null,
             JSON.stringify(c.meta ?? {})
-          ]
+          );
+          const p = params.length;
+          const emb = c.embedding != null ? vectorLiteral2(c.embedding) : "NULL";
+          return `($${p - 7}, $${p - 6}, $${p - 5}, $${p - 4}, $${p - 3}, $${p - 2}, $${p - 1}, ${emb}, $${p}::jsonb)`;
+        });
+        await client.query(
+          `INSERT INTO context_engine_chunks
+            (id, document_id, source_id, acl, idx, text, lang, embedding, meta_data)
+           VALUES ${rows.join(", ")}`,
+          params
         );
       }
       await client.query("COMMIT");
@@ -9241,19 +9833,19 @@ var PostgresBackend = class {
       }
     }
     if (!parsed.length) return [];
-    const [src, principals] = this.scopeParams(scope);
-    const { rows } = await this.pool.query(SQL_FILTER_IDS, [src, principals, parsed]);
+    const { binds } = this.scopeParams(scope);
+    const { rows } = await this.pool.query(SQL_FILTER_IDS, [...binds, parsed]);
     const visible2 = new Set(idsOf(rows));
     return chunkIds.filter((cid) => visible2.has(String(cid))).map(String);
   }
   async ftsSearch(query, scope) {
-    const [src, principals, lim] = this.scopeParams(scope);
-    const { rows } = await this.pool.query(SQL_FTS, [src, principals, query, lim]);
+    const { binds, lim } = this.scopeParams(scope);
+    const { rows } = await this.pool.query(SQL_FTS, [...binds, query, lim]);
     return idsOf(rows);
   }
   async trgmSearch(query, scope) {
     const threshold = trigramThreshold(query);
-    const [src, principals, lim] = this.scopeParams(scope);
+    const { binds, lim } = this.scopeParams(scope);
     const client = await this.pool.connect();
     let previous = null;
     let usedSetLimit = false;
@@ -9262,7 +9854,7 @@ var PostgresBackend = class {
       const applied = await this.applyTrgmThreshold(client, threshold);
       previous = applied.previous;
       usedSetLimit = applied.usedSetLimit;
-      const { rows } = await client.query(SQL_TRGM, [src, principals, query, lim]);
+      const { rows } = await client.query(SQL_TRGM, [...binds, query, lim]);
       if (usedSetLimit) await this.restoreTrgmLimit(client, previous);
       await client.query("COMMIT");
       return idsOf(rows);
@@ -9308,18 +9900,18 @@ var PostgresBackend = class {
   }
   async annSearch(vector, scope) {
     const literal = vectorLiteral2(vector);
-    const [src, principals, lim] = this.scopeParams(scope);
-    const scoped = src !== null || principals !== null;
+    const { binds, lim } = this.scopeParams(scope);
+    const scoped = binds.some((v) => v !== null);
     const client = await this.pool.connect();
     try {
       await client.query("BEGIN");
-      if (scoped && await this.eligibleIsSmall(client, src, principals)) {
-        const { rows: rows2 } = await client.query(sqlAnnExact(literal), [src, principals, lim]);
+      if (scoped && await this.eligibleIsSmall(client, binds)) {
+        const { rows: rows2 } = await client.query(sqlAnnExact(literal), [...binds, lim]);
         await client.query("COMMIT");
         return idsOf(rows2);
       }
       await this.tuneAnnScan(client, lim, scoped);
-      const { rows } = await client.query(sqlAnn(literal), [src, principals, lim]);
+      const { rows } = await client.query(sqlAnn(literal), [...binds, lim]);
       await client.query("COMMIT");
       return idsOf(rows);
     } catch (err) {
@@ -9332,11 +9924,17 @@ var PostgresBackend = class {
       client.release();
     }
   }
-  async eligibleIsSmall(client, src, principals) {
+  async eligibleIsSmall(client, binds) {
     const cap = this.exactThreshold + 1;
-    const { rows } = await client.query(SQL_COUNT_ELIGIBLE, [src, principals, cap]);
+    const { rows } = await client.query(SQL_COUNT_ELIGIBLE, [...binds, cap]);
     return Number(rows[0]?.count ?? 0) <= this.exactThreshold;
   }
+  /** Size the HNSW candidate budget, and make it iterative when filtered.
+   *
+   * Public because the graph leg's seed query (`graph/retrieval.ts`) is the
+   * same shape — an ANN walk with the scope predicate as a POST-filter — and
+   * must not carry a second copy of this. Call it inside a transaction on the
+   * client the query itself will run on: every setting here is `SET LOCAL`. */
   async tuneAnnScan(client, limit, scoped) {
     const efSearch = Math.min(Math.max(Math.trunc(limit) * 4, ANN_MIN_EF_SEARCH), ANN_MAX_EF_SEARCH);
     await client.query(`SET LOCAL hnsw.ef_search = ${efSearch}`);
@@ -9429,15 +10027,7 @@ function functionTool(fn) {
 // src/tools/governance.ts
 init_errors();
 init_hooks();
-
-// src/tools/acl.ts
-function aclVisible(acl, principals) {
-  if (principals === null) return true;
-  if (acl == null) return true;
-  if (!acl.length) return false;
-  const held = new Set(principals ?? []);
-  return acl.some((p) => held.has(p));
-}
+init_redaction();
 
 // src/tools/approval.ts
 init_errors();
@@ -9495,17 +10085,24 @@ function rowToRecord(row) {
     toolName: String(row.tool_name),
     toolArgsFrozen: row.tool_args_frozen ?? {},
     sourceId: row.source_id ?? null,
+    approvalScope: row.approval_scope ?? null,
     principals: row.principals,
     status: String(row.status),
     approver: row.approver ?? null,
     approverMeta: row.approver_meta ?? null,
-    expiresAt: row.expires_at ? new Date(String(row.expires_at)) : null,
-    resolvedAt: row.resolved_at ? new Date(String(row.resolved_at)) : null,
-    createdAt: row.created_at ? new Date(String(row.created_at)) : null
+    expiresAt: toDate(row.expires_at),
+    resolvedAt: toDate(row.resolved_at),
+    createdAt: toDate(row.created_at)
   };
 }
+function toDate(value) {
+  if (value == null) return null;
+  if (value instanceof Date) return value;
+  return new Date(String(value));
+}
 function visibilitySql(principals, paramIndex) {
-  if (principals === null) return { sql: "TRUE", params: [] };
+  if (principals === null || principals === TRUSTED) return { sql: "TRUE", params: [] };
+  principals = principals;
   if (!principals.length) {
     return { sql: `(principals IS NULL OR principals = 'null'::jsonb)`, params: [] };
   }
@@ -9514,41 +10111,95 @@ function visibilitySql(principals, paramIndex) {
     params: [principals]
   };
 }
-async function createPending(engine, opts) {
+function claimVisibilitySql(principals, paramIndex) {
+  if (principals === null || principals === TRUSTED) return { sql: "TRUE", params: [] };
+  const noWall = `principals IS NULL OR principals = 'null'::jsonb OR principals = '[]'::jsonb`;
+  principals = principals;
+  if (!principals.length) return { sql: `(${noWall})`, params: [] };
+  return { sql: `(${noWall} OR principals ?| $${paramIndex}::text[])`, params: [principals] };
+}
+function validateApprovalScope(approvalScope) {
+  if (approvalScope === null || approvalScope === void 0) return null;
+  if (typeof approvalScope !== "string") {
+    throw new TypeError(`approvalScope must be a non-empty string or null, got ${typeof approvalScope}`);
+  }
+  if (!approvalScope) throw new Error("approvalScope must be a non-empty string or null, got ''");
+  return approvalScope;
+}
+function pendingRow(opts, approvalScope) {
   const policy = opts.policy ?? {};
   const frozen = structuredClone(opts.args);
   const createdAt = opts.now ?? /* @__PURE__ */ new Date();
   const timeout = Number(policy.timeout_minutes ?? DEFAULT_TIMEOUT_MINUTES);
   const expiresAt = new Date(createdAt.getTime() + timeout * 6e4);
+  const principals = opts.principals === void 0 || opts.principals === TRUSTED ? null : opts.principals;
+  return { frozen, createdAt, expiresAt, principals, approvalScope };
+}
+async function insertPending(engine, opts, row) {
   const id = randomUUID();
   await engine.pool.query(
     `INSERT INTO context_engine_tool_approvals
-      (id, tool_name, tool_args_frozen, source_id, principals, status, expires_at, created_at)
-     VALUES ($1,$2,$3::jsonb,$4,$5::jsonb,'pending',$6,$7)`,
+      (id, tool_name, tool_args_frozen, source_id, approval_scope, principals, status, expires_at, created_at)
+     VALUES ($1,$2,$3::jsonb,$4,$5,$6::jsonb,'pending',$7,$8)`,
     [
       id,
       opts.toolName,
-      JSON.stringify(frozen),
+      JSON.stringify(row.frozen),
       opts.sourceId ?? null,
-      opts.principals === void 0 ? null : JSON.stringify(opts.principals),
-      expiresAt,
-      createdAt
+      row.approvalScope,
+      row.principals === null ? null : JSON.stringify(row.principals),
+      row.expiresAt,
+      row.createdAt
     ]
   );
   return {
     id,
     toolName: opts.toolName,
-    toolArgsFrozen: frozen,
+    toolArgsFrozen: row.frozen,
     sourceId: opts.sourceId ?? null,
-    principals: opts.principals ?? null,
+    approvalScope: row.approvalScope,
+    principals: row.principals,
     status: "pending",
     approver: null,
     approverMeta: null,
-    expiresAt,
+    expiresAt: row.expiresAt,
     resolvedAt: null,
-    createdAt
+    createdAt: row.createdAt
   };
 }
+async function createPending(engine, opts) {
+  const approvalScope = validateApprovalScope(opts.approvalScope);
+  return insertPending(engine, opts, pendingRow(opts, approvalScope));
+}
+async function findOrCreatePending(engine, opts) {
+  const approvalScope = validateApprovalScope(opts.approvalScope);
+  if (approvalScope === null)
+    throw new Error("findOrCreatePending requires an approvalScope; use createPending");
+  const row = pendingRow(opts, approvalScope);
+  const frozenJson = JSON.stringify(row.frozen);
+  const sameCall = `tool_name = $1 AND approval_scope = $2 AND tool_args_frozen = $3::jsonb`;
+  const params = [opts.toolName, approvalScope, frozenJson, row.createdAt];
+  await engine.pool.query(
+    `UPDATE context_engine_tool_approvals SET status = 'expired'
+     WHERE ${sameCall} AND status = 'pending' AND expires_at <= $4`,
+    params
+  );
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const found = await engine.pool.query(
+      `SELECT * FROM context_engine_tool_approvals
+       WHERE ${sameCall} AND status = 'pending' AND (expires_at IS NULL OR expires_at > $4)
+       ORDER BY created_at ASC LIMIT 1`,
+      params
+    );
+    if (found.rows[0]) return rowToRecord(found.rows[0]);
+    try {
+      return await insertPending(engine, opts, row);
+    } catch (exc) {
+      if (exc?.code !== "23505") throw exc;
+    }
+  }
+  throw new Error("findOrCreatePending: lost the insert race twice and found no live pending row");
+}
 async function resolveApproval(engine, approvalId, decision, approver, meta = null, opts = {}) {
   if (decision !== "approved" && decision !== "rejected") {
     throw new Error(`invalid decision: ${JSON.stringify(decision)} (expected 'approved' or 'rejected')`);
@@ -9696,6 +10347,10 @@ var ToolConfig = class _ToolConfig {
   requiresApproval;
   approvalPolicy;
   enabled;
+  /** Engine-opaque user metadata (documents have the same column). Stored
+   * and returned in CLEAR on the admin surface only — secrets go in
+   * `config`, which is encrypted. */
+  metaData;
   constructor(init) {
     this.id = init.id ?? null;
     this.name = init.name;
@@ -9707,6 +10362,7 @@ var ToolConfig = class _ToolConfig {
     this.requiresApproval = init.requiresApproval ?? init.requires_approval ?? false;
     this.approvalPolicy = init.approvalPolicy ?? init.approval_policy ?? {};
     this.enabled = init.enabled ?? true;
+    this.metaData = init.metaData ?? init.meta_data ?? {};
   }
   static fromUnknown(body) {
     if (!body || typeof body !== "object" || Array.isArray(body)) {
@@ -9729,7 +10385,8 @@ var ToolConfig = class _ToolConfig {
       acl: b.acl ?? null,
       requiresApproval: Boolean(b.requiresApproval ?? b.requires_approval ?? false),
       approvalPolicy: b.approvalPolicy ?? b.approval_policy ?? {},
-      enabled: b.enabled === void 0 ? true : Boolean(b.enabled)
+      enabled: b.enabled === void 0 ? true : Boolean(b.enabled),
+      metaData: b.metaData ?? b.meta_data ?? {}
     });
   }
 };
@@ -9748,9 +10405,26 @@ var SCHEMAS = {
         additionalProperties: { type: "string" },
         writeOnly: true
       },
+      // The request body TEMPLATE (the http executor reads it). Whether it
+      // round-trips is the USER's call — see `body_secret` and the
+      // conditional in `redactConfig`; listing it documents the shape, the
+      // redactor decides.
+      body: {
+        description: "Request body template; top-level keys merge with LLM parameters"
+      },
+      // Salman (2026-08-18): "give checkbox to user" — the author declares
+      // whether their body carries secrets. True (or ABSENT — every pre-flag
+      // row, fail closed) masks body values like headers; an explicit false
+      // round-trips the body in clear like `url`. The flag round-trips.
+      body_secret: {
+        type: "boolean",
+        description: "Body values are write-only (mask like headers)"
+      },
       parameters: {
         type: "object",
-        description: "Static/user-fixed parameters sent on every call"
+        description: "Static/user-fixed parameters sent on every call",
+        // The canonical home of a static api_key — secret by position.
+        writeOnly: true
       },
       llmParameters: {
         type: "object",
@@ -9781,7 +10455,13 @@ var SCHEMAS = {
         default: "readonly"
       },
       max_rows: { type: "integer", default: 1e3 },
-      selected_tables: { type: "array", items: { type: "string" } }
+      selected_tables: { type: "array", items: { type: "string" } },
+      // Dialect connection identifiers the db executor reads — same
+      // sensitivity class as `database`, listed so they round-trip instead
+      // of dying to redactConfig's default-deny.
+      service_name: { type: "string" },
+      schema_name: { type: "string" },
+      warehouse: { type: "string" }
     },
     required: ["engine", "database"]
   },
@@ -9813,11 +10493,245 @@ function configSchema(kind) {
   if (!schema) throw new Error(`unknown tool kind: ${JSON.stringify(kind)}`);
   return schema;
 }
+var REDACTED_SENTINEL = "__redacted__";
+var ConfigTemplateError = class extends Error {
+};
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function containsSentinel(value) {
+  if (typeof value === "string") return value === REDACTED_SENTINEL;
+  if (Array.isArray(value)) return value.some(containsSentinel);
+  if (isPlainObject(value)) return Object.values(value).some(containsSentinel);
+  return false;
+}
+function mergeRedacted(incoming, stored) {
+  const resolve = (value, kept, keptPresent, path) => {
+    if (isPlainObject(value)) {
+      const keptDict = isPlainObject(kept) ? kept : {};
+      const out2 = {};
+      for (const [k, v] of Object.entries(value)) {
+        out2[k] = resolve(v, keptDict[k], k in keptDict, path ? `${path}.${k}` : k);
+      }
+      return out2;
+    }
+    if (Array.isArray(value)) {
+      const keptList = Array.isArray(kept) ? kept : [];
+      return value.map((v, i) => resolve(v, keptList[i], i < keptList.length, `${path}[${i}]`));
+    }
+    if (value === REDACTED_SENTINEL) {
+      if (!keptPresent) {
+        throw new ConfigTemplateError(
+          `config.${path} is ${JSON.stringify(REDACTED_SENTINEL)} but there is no stored value to keep \u2014 re-enter the secret or omit the field`
+        );
+      }
+      return kept;
+    }
+    return value;
+  };
+  const keptRoot = stored ?? {};
+  const out = {};
+  for (const [k, v] of Object.entries(incoming)) {
+    out[k] = resolve(v, keptRoot[k], k in keptRoot, k);
+  }
+  return out;
+}
+
+// src/tools/crypto.ts
+init_crypto();
+var MAX_RESPONSE_BYTES = 1e6;
+var MAX_REDIRECTS = 5;
+function isRedirect(resp) {
+  return resp.status >= 300 && resp.status < 400 || resp.type === "opaqueredirect";
+}
+var EgressDenied = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EgressDenied";
+  }
+};
+var resolver = {
+  async lookup(host) {
+    const answers = await promises.lookup(host, { all: true, verbatim: true });
+    return answers.map((a) => a.address);
+  }
+};
+var V4_PRIVATE = [
+  ["0.0.0.0", 8],
+  // "this network" / unspecified
+  ["10.0.0.0", 8],
+  // RFC 1918
+  ["100.64.0.0", 10],
+  // RFC 6598 carrier-grade NAT — overlay VPNs, pod CIDRs
+  ["127.0.0.0", 8],
+  // loopback
+  ["169.254.0.0", 16],
+  // link-local, incl. the cloud metadata address
+  ["172.16.0.0", 12],
+  // RFC 1918
+  ["192.168.0.0", 16],
+  // RFC 1918
+  ["224.0.0.0", 4],
+  // multicast
+  ["240.0.0.0", 4],
+  // reserved
+  ["255.255.255.255", 32]
+  // broadcast (inside 240/4; spelled out anyway)
+];
+var V6_PRIVATE = [
+  ["::", 128],
+  // unspecified
+  ["::1", 128],
+  // loopback
+  ["::ffff:0:0", 96],
+  // IPv4-mapped — the wrapped v4 is checked too
+  ["64:ff9b::", 96],
+  // NAT64 — the wrapped v4 is checked too
+  ["2002::", 16],
+  // 6to4 — the wrapped v4 is checked too, and this is denied
+  ["fc00::", 7],
+  // unique local
+  ["fe80::", 10],
+  // link-local
+  ["fec0::", 10],
+  // site-local (deprecated, still configured)
+  ["ff00::", 8],
+  // multicast
+  ["3fff::", 20]
+  // documentation
+];
+function parseV4(text) {
+  const parts = text.split(".");
+  if (parts.length !== 4) return null;
+  const out = new Uint8Array(4);
+  for (let i = 0; i < 4; i++) {
+    const part = parts[i];
+    if (!/^\d{1,3}$/.test(part)) return null;
+    const value = Number(part);
+    if (value > 255) return null;
+    out[i] = value;
+  }
+  return out;
+}
+function parseV6(text) {
+  let body = text.split("%")[0] ?? "";
+  const lastColon = body.lastIndexOf(":");
+  if (lastColon < 0) return null;
+  const tail = body.slice(lastColon + 1);
+  if (tail.includes(".")) {
+    const v4 = parseV4(tail);
+    if (!v4) return null;
+    const hi = (v4[0] << 8 | v4[1]).toString(16);
+    const lo = (v4[2] << 8 | v4[3]).toString(16);
+    body = `${body.slice(0, lastColon + 1)}${hi}:${lo}`;
+  }
+  const halves = body.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const rest = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+  let groups;
+  if (halves.length === 1) {
+    if (head.length !== 8) return null;
+    groups = head;
+  } else {
+    const missing = 8 - head.length - rest.length;
+    if (missing < 0) return null;
+    groups = [...head, ...Array(missing).fill("0"), ...rest];
+  }
+  const out = new Uint8Array(16);
+  for (let i = 0; i < 8; i++) {
+    const group = groups[i];
+    if (!/^[0-9a-f]{1,4}$/i.test(group)) return null;
+    const value = Number.parseInt(group, 16);
+    out[2 * i] = value >> 8;
+    out[2 * i + 1] = value & 255;
+  }
+  return out;
+}
+function parseAddress(text) {
+  const family = isIP(text);
+  if (family === 4) return parseV4(text);
+  if (family === 6) return parseV6(text);
+  return null;
+}
+function inNet(addr, net, prefix) {
+  if (addr.length !== net.length) return false;
+  const whole = prefix >> 3;
+  for (let i = 0; i < whole; i++) if (addr[i] !== net[i]) return false;
+  const bits = prefix & 7;
+  if (bits === 0) return true;
+  const mask = 255 << 8 - bits;
+  return (addr[whole] & mask) === (net[whole] & mask);
+}
+function compile(table) {
+  return table.map(([cidr, prefix]) => {
+    const bytes = parseAddress(cidr);
+    if (!bytes) throw new Error(`egress: unparseable network ${cidr}`);
+    return [bytes, prefix];
+  });
+}
+var V4_NETS = compile(V4_PRIVATE);
+var V6_NETS = compile(V6_PRIVATE);
+var MAPPED_V4 = compile([["::ffff:0:0", 96]])[0];
+var NAT64 = compile([["64:ff9b::", 96]])[0];
+var SIXTOFOUR = compile([["2002::", 16]])[0];
+function embeddedV4(bytes) {
+  if (inNet(bytes, MAPPED_V4[0], MAPPED_V4[1]) || inNet(bytes, NAT64[0], NAT64[1])) {
+    return bytes.subarray(12, 16);
+  }
+  if (inNet(bytes, SIXTOFOUR[0], SIXTOFOUR[1])) return bytes.subarray(2, 6);
+  return null;
+}
+function addressIsPrivate(address) {
+  const bytes = parseAddress(address);
+  if (!bytes) return true;
+  if (bytes.length === 4) return V4_NETS.some(([net, prefix]) => inNet(bytes, net, prefix));
+  const embedded = embeddedV4(bytes);
+  if (embedded && V4_NETS.some(([net, prefix]) => inNet(embedded, net, prefix))) return true;
+  return V6_NETS.some(([net, prefix]) => inNet(bytes, net, prefix));
+}
+async function isPrivateAddress(host) {
+  let name = (host ?? "").trim().toLowerCase().replace(/^\.+|\.+$/g, "");
+  if (!name) return true;
+  if (name === "localhost") return true;
+  if (name.startsWith("[") && name.endsWith("]")) name = name.slice(1, -1);
+  if (isIP(name)) return addressIsPrivate(name);
+  let addresses;
+  try {
+    addresses = await resolver.lookup(name);
+  } catch {
+    return true;
+  }
+  if (!addresses.length) return true;
+  return addresses.some((address) => addressIsPrivate(address.split("%")[0] ?? address));
+}
+async function assertEgressAllowed(url, opts) {
+  let parsed;
+  try {
+    parsed = new URL(url ?? "");
+  } catch {
+    throw new EgressDenied(`egress denied: ${JSON.stringify(url)} is not a valid URL`);
+  }
+  const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
+  if (scheme !== "http" && scheme !== "https") {
+    throw new EgressDenied(
+      `egress denied: unsupported URL scheme ${JSON.stringify(scheme)} \u2014 http tools may only reach http/https`
+    );
+  }
+  if (opts.allowPrivate) return;
+  const host = parsed.hostname;
+  if (await isPrivateAddress(host)) {
+    throw new EgressDenied(
+      `egress denied: ${host || "(no host)"} is a private, loopback, link-local or metadata address; set allowPrivateEgress to permit it`
+    );
+  }
+}
 
 // src/tools/governance.ts
 init_db();
 
 // src/tools/executors/http.ts
+init_errors();
 var TIMEOUT_MS5 = 3e4;
 var SENSITIVE_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
   "set-cookie",
@@ -9826,6 +10740,8 @@ var SENSITIVE_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
   "proxy-authenticate",
   "www-authenticate"
 ]);
+var REDIRECT_STATUS = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
+var CROSS_ORIGIN_HEADERS = /* @__PURE__ */ new Set(["authorization", "proxy-authorization", "cookie"]);
 function percentEncode(value) {
   return encodeURIComponent(value).replace(
     /[!'()*]/g,
@@ -9856,10 +10772,38 @@ function withQuery(url, params) {
   if (!q) return url;
   return url.includes("?") ? `${url}&${q}` : `${url}?${q}`;
 }
+async function readCapped(resp) {
+  if (!resp.body) return { text: await resp.text(), truncated: false };
+  const reader = resp.body.getReader();
+  const chunks = [];
+  let size = 0;
+  let truncated = false;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      chunks.push(Buffer.from(value));
+      size += value.byteLength;
+    }
+    if (size > MAX_RESPONSE_BYTES) {
+      truncated = true;
+      await reader.cancel();
+      break;
+    }
+  }
+  const bytes = Buffer.concat(chunks);
+  return {
+    text: (truncated ? bytes.subarray(0, MAX_RESPONSE_BYTES) : bytes).toString("utf8"),
+    truncated
+  };
+}
 async function defaultRequest(init) {
   let url = init.url;
   if (init.params) url = withQuery(url, init.params);
   const headers = { ...init.headers ?? {} };
+  if (!Object.keys(headers).some((k) => k.toLowerCase() === "accept-encoding")) {
+    headers["Accept-Encoding"] = "identity";
+  }
   let body;
   if (init.json !== void 0) {
     headers["Content-Type"] = headers["Content-Type"] ?? headers["content-type"] ?? "application/json";
@@ -9871,25 +10815,47 @@ async function defaultRequest(init) {
     method: init.method,
     headers,
     body,
-    redirect: "follow",
+    // Redirects are followed by hand in `executeHttp` — an automatic follow
+    // would jump to a destination no egress check ever saw.
+    redirect: "manual",
     signal: AbortSignal.timeout(TIMEOUT_MS5)
   });
   const respHeaders = {};
   resp.headers.forEach((v, k) => {
     respHeaders[k] = v;
   });
-  const text = await resp.text();
+  const { text, truncated } = await readCapped(resp);
   return {
     status: resp.status,
     headers: respHeaders,
+    truncated,
     async json() {
-      return JSON.parse(text);
+      return JSON.parse(text.replace(/^/, ""));
     },
     async text() {
       return text;
     }
   };
 }
+function nextHop(init, status, location) {
+  const current = new URL(init.url);
+  const target = new URL(location, current);
+  let method = init.method;
+  if ((status === 302 || status === 303) && method !== "HEAD") method = "GET";
+  else if (status === 301 && method === "POST") method = "GET";
+  let headers = { ...init.headers ?? {} };
+  if (current.origin !== target.origin) {
+    headers = Object.fromEntries(
+      Object.entries(headers).filter(([k]) => !CROSS_ORIGIN_HEADERS.has(k.toLowerCase()))
+    );
+  }
+  const hop = { method, url: target.toString(), headers };
+  if (method === init.method) {
+    if (init.json !== void 0) hop.json = init.json;
+    if (init.content !== void 0) hop.content = init.content;
+  }
+  return hop;
+}
 async function executeHttp(config, args, opts = {}) {
   const method = String(config.method ?? "GET").toUpperCase();
   let url = config.url;
@@ -9910,7 +10876,7 @@ async function executeHttp(config, args, opts = {}) {
       }
     }
   }
-  const requestInit = {
+  let requestInit = {
     method,
     url: url ?? "",
     headers
@@ -9946,29 +10912,64 @@ async function executeHttp(config, args, opts = {}) {
     }
   }
   const client = opts.client;
-  const resp = client ? await client.request(requestInit) : await defaultRequest(requestInit);
+  const allowPrivate = opts.allowPrivate ?? false;
+  let resp;
+  let hops = 0;
+  for (; ; ) {
+    await assertEgressAllowed(requestInit.url, { allowPrivate });
+    resp = client ? await client.request(requestInit) : await defaultRequest(requestInit);
+    const location = resp.headers.location ?? resp.headers.Location;
+    if (!REDIRECT_STATUS.has(resp.status) || !location) break;
+    if (hops >= MAX_REDIRECTS) {
+      throw new EngineActionError(`too many redirects (more than ${MAX_REDIRECTS}) starting at ${url}`);
+    }
+    hops += 1;
+    requestInit = nextHop(requestInit, resp.status, location);
+  }
   const contentType = resp.headers["content-type"] ?? resp.headers["Content-Type"] ?? "";
-  let data;
+  let text = "";
   try {
-    data = contentType.includes("application/json") ? await resp.json() : await resp.text();
+    text = await resp.text();
   } catch {
-    data = await resp.text();
+    text = "";
+  }
+  const bytes = Buffer.from(text, "utf8");
+  const truncated = resp.truncated === true || bytes.byteLength > MAX_RESPONSE_BYTES;
+  let data;
+  if (truncated) {
+    data = bytes.subarray(0, MAX_RESPONSE_BYTES).toString("utf8");
+  } else {
+    try {
+      data = contentType.includes("application/json") ? await resp.json() : text;
+    } catch {
+      data = text;
+    }
   }
   const safeHeaders = {};
   for (const [k, v] of Object.entries(resp.headers)) {
     if (!SENSITIVE_RESPONSE_HEADERS.has(k.toLowerCase())) safeHeaders[k] = v;
   }
-  return {
+  const result = {
     status_code: resp.status,
     headers: safeHeaders,
     data
   };
+  if (truncated) result.truncated = true;
+  return result;
 }
 
 // src/version.ts
 var __version__ = "0.0.0";
 
 // src/tools/executors/mcp-client.ts
+async function checkEgress(url, allowPrivate) {
+  let checked = url;
+  const scheme = (/^([a-z0-9+.-]+):/i.exec(url ?? "")?.[1] ?? "").toLowerCase();
+  if (scheme === "ws") checked = `http:${url.slice(scheme.length + 1)}`;
+  else if (scheme === "wss") checked = `https:${url.slice(scheme.length + 1)}`;
+  await assertEgressAllowed(checked, { allowPrivate });
+}
+var REDIRECT_MESSAGE = "MCP server redirected; register the final URL";
 var MCPError = class _MCPError extends Error {
   code;
   data;
@@ -9997,10 +10998,12 @@ function parseSseBuffer(raw) {
 var HttpTransport = class {
   kind = "http";
   url;
+  allowPrivate;
   baseHeaders;
   sessionId = null;
-  constructor(url, headers) {
+  constructor(url, headers, allowPrivate = false) {
     this.url = url;
+    this.allowPrivate = allowPrivate;
     this.baseHeaders = {
       ...headers,
       "Content-Type": "application/json",
@@ -10008,6 +11011,7 @@ var HttpTransport = class {
     };
   }
   async connect() {
+    await checkEgress(this.url, this.allowPrivate);
   }
   async close() {
     this.sessionId = null;
@@ -10021,10 +11025,17 @@ var HttpTransport = class {
     const resp = await fetch(this.url, {
       method: "POST",
       headers: this.buildHeaders(),
-      body: JSON.stringify(msg)
+      body: JSON.stringify(msg),
+      // `redirect: "manual"`: a followed redirect would carry this POST —
+      // headers, Authorization and all — to a destination `connect()`'s
+      // check never saw. A 3xx is reported, never chased.
+      redirect: "manual"
     });
     const sid = resp.headers.get("Mcp-Session-Id");
     if (sid) this.sessionId = sid;
+    if (isRedirect(resp)) {
+      throw new MCPError(resp.status, REDIRECT_MESSAGE);
+    }
     if (resp.status >= 400) {
       const body = await resp.text();
       console.error(`[HTTP Transport] ${resp.status} from ${this.url}: ${body.slice(0, 300)}`);
@@ -10057,11 +11068,20 @@ var SseTransport = class {
   eventsUrl;
   baseUrl;
   headers;
+  allowPrivate;
+  /** Where the server told us to POST — it arrives in an `endpoint` event on
+   * the stream, so it is server-chosen and hence checked. Private: the only
+   * way in is the parser, which is the path a real server takes. */
   postUrl = null;
+  /** The last POST endpoint cleared by the egress check. The check costs a
+   * DNS resolution and the endpoint changes at most once per connection, so
+   * it is not repeated per message. */
+  checkedPostUrl = null;
   queue = [];
   waiters = [];
   abort = null;
-  constructor(url, headers) {
+  constructor(url, headers, allowPrivate = false) {
+    this.allowPrivate = allowPrivate;
     this.eventsUrl = url.replace(/\/$/, "");
     if (url.endsWith("/events")) this.baseUrl = url.slice(0, -7);
     else if (url.endsWith("/sse")) this.baseUrl = url.slice(0, -4);
@@ -10074,14 +11094,19 @@ var SseTransport = class {
     else this.queue.push(msg);
   }
   async connect() {
+    await checkEgress(this.eventsUrl, this.allowPrivate);
     this.abort = new AbortController();
     void this.listen();
   }
   async listen() {
     const resp = await fetch(this.eventsUrl, {
       headers: { ...this.headers, Accept: "text/event-stream" },
-      signal: this.abort?.signal
+      signal: this.abort?.signal,
+      redirect: "manual"
     });
+    if (isRedirect(resp)) {
+      throw new MCPError(resp.status, REDIRECT_MESSAGE);
+    }
     if (!resp.ok) throw new Error(`SSE ${resp.status}`);
     if (!resp.body) throw new Error("SSE response has no body");
     const reader = resp.body.getReader();
@@ -10133,11 +11158,19 @@ var SseTransport = class {
       }
     }
     const postUrl = this.postUrl || this.baseUrl;
+    if (postUrl !== this.checkedPostUrl) {
+      await checkEgress(postUrl, this.allowPrivate);
+      this.checkedPostUrl = postUrl;
+    }
     const resp = await fetch(postUrl, {
       method: "POST",
       headers: { ...this.headers, "Content-Type": "application/json" },
-      body: JSON.stringify(msg)
+      body: JSON.stringify(msg),
+      redirect: "manual"
     });
+    if (isRedirect(resp)) {
+      throw new MCPError(resp.status, REDIRECT_MESSAGE);
+    }
     if (!resp.ok) throw new Error(`SSE POST ${resp.status}`);
     try {
       const data = await resp.json();
@@ -10156,14 +11189,17 @@ var WsTransport = class {
   kind = "websocket";
   url;
   headers;
+  allowPrivate;
   ws = null;
   queue = [];
   waiters = [];
-  constructor(url, headers) {
+  constructor(url, headers, allowPrivate = false) {
     this.url = url;
+    this.allowPrivate = allowPrivate;
     this.headers = headers;
   }
   async connect() {
+    await checkEgress(this.url, this.allowPrivate);
     const WS = globalThis.WebSocket;
     if (!WS) throw new Error("WebSocket is not available in this runtime");
     this.ws = new WS(this.url);
@@ -10204,21 +11240,27 @@ var MCPClient = class _MCPClient {
   tools = [];
   resources = [];
   headers;
-  constructor(url, headers = null) {
+  allowPrivate;
+  constructor(url, headers = null, opts = {}) {
     this.url = url;
     this.headers = headers ?? {};
-    this.transport = _MCPClient.createTransport(url, this.headers);
+    this.allowPrivate = opts.allowPrivate ?? false;
+    this.transport = _MCPClient.createTransport(url, this.headers, this.allowPrivate);
   }
-  static createTransport(url, headers) {
+  static createTransport(url, headers, allowPrivate = false) {
     if (url.startsWith("stdio:") || url === "stdio") {
       throw new Error("stdio MCP transport is not supported (cloud deployments use SSE/HTTP/WebSocket)");
     }
-    if (url.startsWith("ws://") || url.startsWith("wss://")) return new WsTransport(url, headers);
+    if (url.startsWith("ws://") || url.startsWith("wss://")) {
+      return new WsTransport(url, headers, allowPrivate);
+    }
     if (url.startsWith("sse+http://") || url.startsWith("sse+https://") || url.endsWith("/events") || url.endsWith("/sse")) {
       const clean = url.replace("sse+http://", "http://").replace("sse+https://", "https://");
-      return new SseTransport(clean, headers);
+      return new SseTransport(clean, headers, allowPrivate);
+    }
+    if (url.startsWith("http://") || url.startsWith("https://")) {
+      return new HttpTransport(url, headers, allowPrivate);
     }
-    if (url.startsWith("http://") || url.startsWith("https://")) return new HttpTransport(url, headers);
     throw new Error(`Unsupported URL: ${url} (use http(s)://, ws(s)://, or .../sse)`);
   }
   nextId() {
@@ -10270,7 +11312,15 @@ var MCPClient = class _MCPClient {
     await this.transport.send({ jsonrpc: "2.0", method, params: params ?? {} });
   }
   async connect() {
-    await this.transport.connect();
+    try {
+      await this.transport.connect();
+    } catch (e) {
+      try {
+        await this.transport.close();
+      } catch {
+      }
+      throw e;
+    }
     if (!(this.transport instanceof HttpTransport)) {
       this.connected = true;
       void this.recvLoop();
@@ -10353,7 +11403,7 @@ var MCPClient = class _MCPClient {
     }
     this.id = 0;
     this.pending.clear();
-    this.transport = _MCPClient.createTransport(url, headers);
+    this.transport = _MCPClient.createTransport(url, headers, this.allowPrivate);
     await this.connect();
     await this.listTools();
   }
@@ -10361,11 +11411,11 @@ var MCPClient = class _MCPClient {
 var MCPRegistry = class {
   clients = /* @__PURE__ */ new Map();
   healthTask = null;
-  async connect(name, url, headers = null, token = null) {
+  async connect(name, url, headers = null, token = null, allowPrivate = false) {
     this.clients.delete(name);
     const hdrs = { ...headers ?? {} };
     if (token) hdrs.Authorization = hdrs.Authorization ?? `Bearer ${token}`;
-    const client = new MCPClient(url, hdrs);
+    const client = new MCPClient(url, hdrs, { allowPrivate });
     await client.connect();
     await client.listTools();
     this.clients.set(name, client);
@@ -10417,8 +11467,18 @@ var MCPRegistry = class {
 };
 var PromptevMCP = class {
   clients = new MCPRegistry();
+  allowPrivate;
+  /**
+   * `allowPrivate` is the operator knob `allowPrivateEgress`, carried down to
+   * every transport this facade builds. It defaults to `false`, so a
+   * construction site that forgets to pass it denies private destinations
+   * rather than permitting them.
+   */
+  constructor(opts = {}) {
+    this.allowPrivate = opts.allowPrivate ?? false;
+  }
   async addServer(name, url, opts = {}) {
-    await this.clients.connect(name, url, opts.headers ?? null, opts.token ?? null);
+    await this.clients.connect(name, url, opts.headers ?? null, opts.token ?? null, this.allowPrivate);
   }
   async shutdown() {
     await this.clients.shutdown();
@@ -10552,8 +11612,13 @@ var UPDATABLE_COLUMNS = /* @__PURE__ */ new Set([
   "requires_approval",
   "approvalPolicy",
   "approval_policy",
-  "enabled"
+  "enabled",
+  "metaData",
+  "meta_data"
 ]);
+function allowPrivateEgress(engine) {
+  return Boolean(engine?.config?.allowPrivateEgress);
+}
 function toolVisible(ct, principals) {
   return aclVisible(ct.acl, principals);
 }
@@ -10635,11 +11700,19 @@ function redactToolResult(result, policy, opts) {
   if (failed.length) note.rules_failed = failed;
   return [redacted, note];
 }
-function rowToToolConfig(row, engine) {
-  let config = {};
-  if (row.config_encrypted) {
-    config = decryptDict(String(row.config_encrypted), getSecretKey(engine.config));
+function cryptoKey(engine) {
+  const key = getSecretKey(engine.config);
+  if (key.length !== 32) {
+    throw new Error(`CE_SECRET_KEY is malformed: decoded to ${key.length} bytes, need 32`);
   }
+  return key;
+}
+function decryptRowConfig(row, engine) {
+  if (!row.config_encrypted) return {};
+  return decryptDict(String(row.config_encrypted), cryptoKey(engine));
+}
+function rowToToolConfig(row, engine, config) {
+  config ??= decryptRowConfig(row, engine);
   return new ToolConfig({
     id: String(row.id),
     name: String(row.name),
@@ -10650,9 +11723,24 @@ function rowToToolConfig(row, engine) {
     acl: row.acl != null ? [...row.acl] : null,
     requiresApproval: Boolean(row.requires_approval),
     approvalPolicy: row.approval_policy ?? {},
-    enabled: Boolean(row.enabled)
+    enabled: Boolean(row.enabled),
+    metaData: row.meta_data ?? {}
   });
 }
+function rowToToolConfigLenient(row, engine) {
+  if (!row.config_encrypted) return rowToToolConfig(row, engine, {});
+  const key = cryptoKey(engine);
+  let config;
+  try {
+    config = decryptDict(String(row.config_encrypted), key);
+  } catch {
+    console.warn(
+      `tool ${String(row.id)} (${String(row.name)}): config_error \u2014 its stored config could not be decrypted (was the secret key rotated?); leaving it out of the tool set`
+    );
+    return null;
+  }
+  return rowToToolConfig(row, engine, config);
+}
 async function loadPersistedCanonicals(engine, sourceId) {
   const params = [];
   let sql = `SELECT * FROM context_engine_tools WHERE enabled IS TRUE`;
@@ -10663,7 +11751,9 @@ async function loadPersistedCanonicals(engine, sourceId) {
   const result = await engine.pool.query(sql, params);
   const canonicals = [];
   for (const row of result.rows) {
-    canonicals.push(...canonicalFromConfig(rowToToolConfig(row, engine)));
+    const tc = rowToToolConfigLenient(row, engine);
+    if (tc === null) continue;
+    canonicals.push(...canonicalFromConfig(tc));
   }
   return canonicals;
 }
@@ -10683,13 +11773,18 @@ function canonicalToPublic(ct) {
 async function registerTool(engine, tc) {
   canonicalFromConfig(tc);
   const config = tc.config ?? {};
-  const configEncrypted = Object.keys(config).length ? encryptDict(config, getSecretKey(engine.config)) : null;
+  if (containsSentinel(config)) {
+    throw new ConfigTemplateError(
+      `config contains the ${JSON.stringify(REDACTED_SENTINEL)} placeholder \u2014 a redacted template cannot be registered as a new tool; re-enter the secret values`
+    );
+  }
+  const configEncrypted = Object.keys(config).length ? encryptDict(config, cryptoKey(engine)) : null;
   const id = randomUUID();
   await engine.pool.query(
     `INSERT INTO context_engine_tools
        (id, name, kind, description, source_id, acl, config_encrypted,
-        requires_approval, approval_policy, enabled)
-     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10)`,
+        requires_approval, approval_policy, enabled, meta_data)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10, $11::jsonb)`,
     [
       id,
       tc.name,
@@ -10700,7 +11795,8 @@ async function registerTool(engine, tc) {
       configEncrypted,
       tc.requiresApproval,
       JSON.stringify(tc.approvalPolicy ?? {}),
-      tc.enabled
+      tc.enabled,
+      JSON.stringify(tc.metaData ?? {})
     ]
   );
   return id;
@@ -10717,12 +11813,41 @@ async function updateTool(engine, id, opts) {
   let i = 1;
   for (const [key, value] of Object.entries(fields)) {
     if (key === "config") {
+      let config = value;
+      if (config && containsSentinel(config)) {
+        if (Object.hasOwn(fields, "kind") && fields.kind !== row.kind) {
+          throw new ConfigTemplateError(
+            "cannot change kind and keep redacted secrets in one PATCH \u2014 re-enter the config in full"
+          );
+        }
+        if (config.body_secret === false && containsSentinel(config.body)) {
+          throw new ConfigTemplateError(
+            `body_secret cannot be turned off while the body still contains ${JSON.stringify(REDACTED_SENTINEL)} \u2014 re-enter the body to declassify it`
+          );
+        }
+        if (!row.config_encrypted) {
+          throw new ConfigTemplateError(
+            `config contains ${JSON.stringify(REDACTED_SENTINEL)} but this tool has no stored config to keep \u2014 re-enter the secret values`
+          );
+        }
+        const key2 = cryptoKey(engine);
+        let stored;
+        try {
+          stored = decryptDict(String(row.config_encrypted), key2);
+        } catch (exc) {
+          throw new ConfigTemplateError(
+            `the stored config cannot be decrypted (was the secret key rotated?) \u2014 re-enter the config in full, without ${JSON.stringify(REDACTED_SENTINEL)} values`,
+            { cause: exc }
+          );
+        }
+        config = mergeRedacted(config, stored);
+      }
       sets.push(`config_encrypted = $${i++}`);
-      params.push(value ? encryptDict(value, getSecretKey(engine.config)) : null);
+      params.push(config && Object.keys(config).length ? encryptDict(config, cryptoKey(engine)) : null);
     } else if (UPDATABLE_COLUMNS.has(key)) {
-      const col = key === "sourceId" ? "source_id" : key === "requiresApproval" ? "requires_approval" : key === "approvalPolicy" ? "approval_policy" : key;
+      const col = key === "sourceId" ? "source_id" : key === "requiresApproval" ? "requires_approval" : key === "approvalPolicy" ? "approval_policy" : key === "metaData" ? "meta_data" : key;
       sets.push(`${col} = $${i++}`);
-      params.push(col === "approval_policy" ? JSON.stringify(value ?? {}) : value);
+      params.push(col === "approval_policy" || col === "meta_data" ? JSON.stringify(value ?? {}) : value);
     }
   }
   sets.push(`updated_at = now()`);
@@ -10731,7 +11856,8 @@ async function updateTool(engine, id, opts) {
     `UPDATE context_engine_tools SET ${sets.join(", ")} WHERE id = $${i} RETURNING *`,
     params
   );
-  return rowToToolConfig(updated.rows[0], engine);
+  const row_ = updated.rows[0];
+  return rowToToolConfigLenient(row_, engine) ?? rowToToolConfig(row_, engine, {});
 }
 async function deleteTool(engine, id, opts = {}) {
   const existing = await engine.pool.query(`SELECT * FROM context_engine_tools WHERE id = $1`, [id]);
@@ -10817,17 +11943,38 @@ function probeFailure(exc, kind) {
   console.warn(`test_tool(kind=${kind}) failed:`, exc, "->", category);
   return { ok: false, error: category };
 }
-async function testTool(_engine, tc) {
+async function testTool(engine, tc) {
   const kind = tc.kind;
   const config = tc.config ?? {};
+  if (containsSentinel(config)) {
+    throw new ConfigTemplateError(
+      `config contains the ${JSON.stringify(REDACTED_SENTINEL)} placeholder \u2014 a probe would send it verbatim as the credential; re-enter the secret values`
+    );
+  }
   if (kind === "http") {
     const url = config.url;
     if (!url) return { ok: false, error: "http config missing 'url'" };
     try {
-      const resp = await fetch(url, {
+      await assertEgressAllowed(url, { allowPrivate: allowPrivateEgress(engine) });
+    } catch (exc) {
+      if (exc instanceof EgressDenied) {
+        console.warn(`testTool(kind=http) refused: ${exc.message}`);
+        return { ok: false, error: "egress_denied" };
+      }
+      throw exc;
+    }
+    const client = engine?._toolHttpClient ?? null;
+    try {
+      const resp = client ? await client.request({
+        method: "HEAD",
+        url,
+        headers: config.headers ?? {}
+      }) : await fetch(url, {
         method: "HEAD",
         headers: config.headers ?? {},
-        redirect: "follow",
+        // No automatic follow: a redirect would reach a destination the
+        // check above never saw.
+        redirect: "manual",
         signal: AbortSignal.timeout(1e4)
       });
       return { ok: resp.status < 500, status_code: resp.status };
@@ -10848,12 +11995,16 @@ async function testTool(_engine, tc) {
     const url = config.url;
     if (!url) return { ok: false, error: "mcp config missing 'url'" };
     const token = config.oauth_token ?? config.bearer ?? config.access_token;
-    const mcp = new PromptevMCP();
+    const mcp = new PromptevMCP({ allowPrivate: allowPrivateEgress(engine) });
     try {
       await mcp.addServer(tc.name, url, { token: token ?? null });
       const client = mcp.clients.get(tc.name);
       return { ok: true, tools: client.tools.map((t) => t.name) };
     } catch (exc) {
+      if (exc instanceof EgressDenied) {
+        console.warn(`testTool(kind=mcp) refused: ${exc.message}`);
+        return { ok: false, error: "egress_denied" };
+      }
       return probeFailure(exc, "mcp");
     } finally {
       await mcp.shutdown();
@@ -10861,11 +12012,20 @@ async function testTool(_engine, tc) {
   }
   return { ok: false, error: `test_tool does not support kind=${JSON.stringify(kind)}` };
 }
-async function findAndClaimApproved(engine, toolName, args, sourceId) {
+async function findAndClaimApproved(engine, toolName, args, sourceId, principals, approvalScope) {
   const claimedAt = /* @__PURE__ */ new Date();
+  const params = [toolName];
+  let scopeSql2 = "approval_scope IS NULL";
+  if (approvalScope !== null) {
+    params.push(approvalScope);
+    scopeSql2 = `approval_scope = $${params.length}`;
+  }
+  const wall = claimVisibilitySql(principals, params.length + 1);
+  params.push(...wall.params);
   const candidates = await engine.pool.query(
-    `SELECT * FROM context_engine_tool_approvals WHERE tool_name = $1 AND status = 'approved'`,
-    [toolName]
+    `SELECT * FROM context_engine_tool_approvals
+     WHERE tool_name = $1 AND status = 'approved' AND ${scopeSql2} AND ${wall.sql}`,
+    params
   );
   for (const row of candidates.rows) {
     if ((row.source_id ?? null) !== (sourceId ?? null)) continue;
@@ -10882,7 +12042,7 @@ async function findAndClaimApproved(engine, toolName, args, sourceId) {
   }
   return null;
 }
-async function dispatchMcp(ct, config, args) {
+async function dispatchMcp(ct, config, args, opts = {}) {
   const url = config.url;
   if (!url) throw new EngineActionError(`mcp tool ${ct.callName} config missing 'url'`);
   const headers = { ...config.headers ?? {} };
@@ -10891,7 +12051,7 @@ async function dispatchMcp(ct, config, args) {
   if (token) headers.Authorization = `Bearer ${token}`;
   else if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
   const toolName = String(ct.raw?.tool_name ?? ct.displayName);
-  const mcp = new PromptevMCP();
+  const mcp = new PromptevMCP({ allowPrivate: opts.allowPrivate ?? false });
   try {
     await mcp.addServer(ct.callName, url, { headers: Object.keys(headers).length ? headers : null });
     const client = mcp.clients.get(ct.callName);
@@ -10902,7 +12062,10 @@ async function dispatchMcp(ct, config, args) {
 }
 async function dispatch(engine, ct, config, args) {
   if (ct.kind === "http") {
-    return executeHttp(config, args, { client: engine._toolHttpClient ?? null });
+    return executeHttp(config, args, {
+      client: engine._toolHttpClient ?? null,
+      allowPrivate: allowPrivateEgress(engine)
+    });
   }
   if (ct.kind === "db") {
     const query = String(args.query ?? "");
@@ -10917,7 +12080,9 @@ async function dispatch(engine, ct, config, args) {
     }
     return result;
   }
-  if (ct.kind === "mcp") return dispatchMcp(ct, config, args);
+  if (ct.kind === "mcp") {
+    return dispatchMcp(ct, config, args, { allowPrivate: allowPrivateEgress(engine) });
+  }
   if (ct.kind === "function") {
     const fn = ct.raw?.callable;
     if (!fn) throw new EngineActionError(`function tool ${ct.callName} has no callable`);
@@ -10938,10 +12103,20 @@ async function decryptCtConfig(engine, toolId) {
   ]);
   const row = result.rows[0];
   if (!row?.config_encrypted) return {};
-  return decryptDict(String(row.config_encrypted), getSecretKey(engine.config));
+  return decryptDict(String(row.config_encrypted), cryptoKey(engine));
+}
+var warnedUnscoped = /* @__PURE__ */ new Set();
+function warnUnscopedApproval(callName) {
+  if (warnedUnscoped.has(callName)) return;
+  warnedUnscoped.add(callName);
+  process.emitWarning(
+    `executeTool(${JSON.stringify(callName)}) needs an approval but was called without approvalScope. The record is opened and matched UNSCOPED (tool + args + sourceId, behind the principals wall). Pass approvalScope: <opaque string> (e.g. a run id) so approvals are claimable only within that scope; a gated call without one will be refused in the next release.`,
+    { type: "DeprecationWarning", code: "CE_APPROVAL_SCOPE_MISSING" }
+  );
 }
 async function executeTool(engine, callName, args, opts = {}) {
   const runtimeArgs = args ?? {};
+  const approvalScope = validateApprovalScope(opts.approvalScope);
   const ct = findTool(await mergedTools(engine, opts.sourceId ?? null), callName);
   if (!ct) throw new EngineActionError(`tool not found: ${callName}`);
   if (!toolVisible(ct, opts.principals ?? null)) {
@@ -10950,22 +12125,32 @@ async function executeTool(engine, callName, args, opts = {}) {
   const publicArgs = stripUnderscoreArgs(runtimeArgs);
   let approvalId = null;
   if (shouldRequireApproval(ct, publicArgs)) {
-    approvalId = await findAndClaimApproved(engine, ct.callName, publicArgs, opts.sourceId ?? null);
+    if (approvalScope === null) warnUnscopedApproval(callName);
+    approvalId = await findAndClaimApproved(
+      engine,
+      ct.callName,
+      publicArgs,
+      opts.sourceId ?? null,
+      opts.principals ?? null,
+      approvalScope
+    );
     if (approvalId == null) {
-      const record = await createPending(engine, {
+      const pendingOpts = {
         toolName: ct.callName,
         args: publicArgs,
         sourceId: opts.sourceId ?? null,
         principals: opts.principals ?? null,
         policy: ct.approvalPolicy ?? {}
-      });
+      };
+      const record = approvalScope === null ? await createPending(engine, pendingOpts) : await findOrCreatePending(engine, { ...pendingOpts, approvalScope });
       const reason = ct.requiresApproval ? "tool requires approval" : `approval policy condition met: ${ct.approvalPolicy?.condition}`;
       return {
         approval_required: {
           approval_id: String(record.id),
           tool_name: ct.callName,
           args: publicArgs,
-          reason
+          reason,
+          expires_at: record.expiresAt ? record.expiresAt.toISOString() : null
         }
       };
     }
@@ -10990,8 +12175,9 @@ async function executeTool(engine, callName, args, opts = {}) {
   let truncated = false;
   if (success) {
     try {
+      const redactPrincipals = opts.principals === TRUSTED ? null : opts.principals ?? null;
       const [redacted] = redactToolResult(rawResult, engine.config.redaction, {
-        principals: opts.principals ?? null,
+        principals: redactPrincipals,
         secretKey: engine.config.secretKey,
         hooks: engine.hooks
       });
@@ -11090,11 +12276,19 @@ var ContextEngine = class {
   _graphStore = null;
   constructor(config, opts = {}) {
     this.config = config;
-    this.hooks = { onUsage: opts.onUsage ?? null, onError: opts.onError ?? null };
+    this.hooks = {
+      onUsage: opts.onUsage ?? null,
+      onError: opts.onError ?? null,
+      onProgress: opts.onProgress ?? null
+    };
   }
   async ensurePool() {
     if (!this._pool) {
-      this._pool = await createPool(this.config.databaseUrl);
+      this._pool = await createPool(this.config.databaseUrl, {
+        max: this.config.storage.poolMax,
+        idleTimeoutMillis: this.config.storage.poolIdleTimeoutMs,
+        connectionTimeoutMillis: this.config.storage.poolConnectionTimeoutMs
+      });
       this.pool = this._pool;
     }
     if (!this.backend) {
@@ -11280,7 +12474,9 @@ var ContextEngine = class {
         graphStore: await this.getGraphStore(),
         hooks: this.hooks,
         sourceIds: opts.sourceIds ?? null,
-        principals
+        documentIds: opts.documentIds ?? null,
+        principals,
+        backend: this.backend
       });
     }
     return runSearch(query, {
@@ -11290,6 +12486,7 @@ var ContextEngine = class {
       embedder: this.embedder,
       pool,
       sourceIds: opts.sourceIds,
+      documentIds: opts.documentIds,
       principals,
       topK: opts.topK,
       mode: opts.mode,
@@ -11395,7 +12592,7 @@ var ContextEngine = class {
       hooks: this.hooks,
       sourceIds: opts.sourceIds,
       principals: resolvePrincipals(opts.principals, "compute"),
-      docIds: opts.docIds,
+      documentIds: opts.documentIds,
       modelCfg: opts.modelCfg,
       timeout: opts.timeout
     });
@@ -11448,7 +12645,8 @@ var ContextEngine = class {
       sourceId: opts.sourceId,
       principals: resolvePrincipals(opts.principals, "executeTool"),
       actor: opts.actor,
-      source: opts.source ?? "api"
+      source: opts.source ?? "api",
+      approvalScope: opts.approvalScope
     });
   }
 };
@@ -11461,18 +12659,83 @@ init_hooks();
 // src/mcp.ts
 init_errors();
 init_extras();
-
-// src/tools/mcp-tools.ts
+var HandlerError = class extends Error {
+  status;
+  detail;
+  constructor(status, detail) {
+    super(typeof detail === "string" ? detail : JSON.stringify(detail));
+    this.name = "HandlerError";
+    this.status = status;
+    this.detail = detail;
+  }
+};
+z.object({
+  text: z.string(),
+  name: z.string(),
+  source_id: z.string().nullable().optional(),
+  external_id: z.string().nullable().optional(),
+  description: z.string().nullable().optional(),
+  meta_data: z.record(z.unknown()).nullable().optional(),
+  acl: z.array(z.string()).nullable().optional(),
+  mode: z.enum(["hybrid", "graph"]).nullable().optional(),
+  extract_structured: z.boolean().optional().default(false),
+  batch: z.boolean().optional().default(false)
+}).strip();
+z.object({
+  acl: z.array(z.string()).nullable().optional(),
+  name: z.string().nullable().optional(),
+  description: z.string().nullable().optional(),
+  meta_data: z.record(z.unknown()).nullable().optional()
+}).strict();
+z.object({
+  query: z.string(),
+  source_ids: z.array(z.string()).nullable().optional(),
+  // Narrows WITHIN a source and INTERSECTS with source_ids — it can only
+  // shrink the result set (the ACL predicate still applies in the same SQL
+  // conjunction), so exposing it needs no authorizeAcl-style grant check.
+  document_ids: z.array(z.string()).nullable().optional(),
+  top_k: z.number().int().optional().default(10),
+  mode: z.enum(["hybrid", "graph"]).optional().default("hybrid"),
+  compress_to_tokens: z.number().int().nullable().optional()
+}).strip();
+var UUID_RE5 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function requireValidUuid(documentId) {
+  if (!UUID_RE5.test(String(documentId))) {
+    throw new HandlerError(400, `invalid document id: ${JSON.stringify(documentId)}`);
+  }
+}
+function resolveRequestPrincipals(value, opts) {
+  if (value === TRUSTED) return TRUSTED;
+  if (value == null) {
+    throw new HandlerError(
+      500,
+      `${opts.surface}: the \`principals\` dependency returned null, which means TRUSTED CALLER \u2014 it disables ACL filtering and skips the check that stops a caller filing documents under groups it does not hold. This mount is misconfigured: return [] for an unauthenticated caller, or pass TRUSTED explicitly (from @promptev/context-engine) if the surface really is trusted.`
+    );
+  }
+  if (!Array.isArray(value) || value.some((p) => typeof p !== "string")) {
+    throw new HandlerError(
+      500,
+      `${opts.surface}: the \`principals\` dependency must return a list of principal strings, [] for an anonymous caller, or TRUSTED \u2014 got ${typeof value}.`
+    );
+  }
+  return value;
+}
 var SCOPE_NOTE = " Results are scoped to the caller's permissions (resolved by the server's injected principals dependency \u2014 never a caller-supplied argument) and to the given source_ids, if any.";
 async function resolvePrincipalsFn(principals) {
   const result = await Promise.resolve(principals());
-  return result;
+  try {
+    return resolveRequestPrincipals(result, { surface: "the MCP `principals` dependency" });
+  } catch (exc) {
+    if (exc instanceof HandlerError) throw new Error(exc.message, { cause: exc });
+    throw exc;
+  }
 }
-function registerToolGateway(mcp, engine, principals) {
+function registerToolGateway(mcp, engine, principals, approvalScope = null) {
   mcp.tool(
     "search_tools",
     "Keyword search over the tools this deployment has registered (http/db/mcp/function) \u2014 the ACL-visible name, kind, description, and JSON Schema params of each match, so a caller can discover what it can then invoke with `execute_tool`." + SCOPE_NOTE,
-    { query: { type: "string" }, limit: { type: "number" } },
+    // Zod raw shape — see the note on the search tool in mcp.ts.
+    { query: z.string(), limit: z.number().int().optional() },
     async (...raw) => {
       const args = raw[0] ?? {};
       const callerPrincipals = await resolvePrincipalsFn(principals);
@@ -11486,13 +12749,15 @@ function registerToolGateway(mcp, engine, principals) {
   mcp.tool(
     "execute_tool",
     "Governed execution of a tool previously discovered via `search_tools` (ACL check, approval gate, audit). Returns `{result, usage}` on success, or an `approval_required` payload when the call needs a human approval that isn't already granted \u2014 the caller must not retry until that approval resolves." + SCOPE_NOTE,
-    { name: { type: "string" }, args: { type: "object" } },
+    { name: z.string(), args: z.record(z.unknown()).optional() },
     async (...raw) => {
       const body = raw[0] ?? {};
       const callerPrincipals = await resolvePrincipalsFn(principals);
+      const scope = approvalScope ? await Promise.resolve(approvalScope()) : null;
       return engine.executeTool(String(body.name), body.args ?? null, {
         principals: callerPrincipals,
-        source: "mcp"
+        source: "mcp",
+        approvalScope: scope
       });
     }
   );
@@ -11534,15 +12799,24 @@ async function createMcpApp(engine, opts) {
     "search_knowledge_base",
     `Hybrid search (full-text + trigram + vector, RRF-fused) over the ingested corpus. Returns the top-matching chunks with their source document.${SCOPE_NOTE}`,
     {
-      query: { type: "string" },
-      source_ids: { type: "array", items: { type: "string" } },
-      top_k: { type: "number" },
-      mode: { type: "string", enum: ["hybrid", "graph"] }
+      // Zod RAW SHAPES, not JSON schema: the SDK's isZodRawShape test
+      // rejects a plain schema object — on current SDK versions that made
+      // registration THROW at startup, and on 1.12.0 the object was consumed
+      // as annotations and every handler ran with NO arguments.
+      query: z.string(),
+      source_ids: z.array(z.string()).optional(),
+      document_ids: z.array(z.string()).optional(),
+      top_k: z.number().int().optional(),
+      mode: z.enum(["hybrid", "graph"]).optional()
     },
     async (args) => {
+      for (const did of args.document_ids ?? []) {
+        requireValidUuid(did);
+      }
       const callerPrincipals = await resolvePrincipalsFn(opts.principals);
       const result = await engine.search(String(args.query ?? ""), {
         sourceIds: args.source_ids,
+        documentIds: args.document_ids,
         principals: callerPrincipals,
         topK: args.top_k ?? 10,
         mode: args.mode ?? "hybrid"
@@ -11564,7 +12838,7 @@ async function createMcpApp(engine, opts) {
   tool(
     "get_document",
     `Fetch one document's full text and metadata by id.${SCOPE_NOTE}`,
-    { document_id: { type: "string" } },
+    { document_id: z.string() },
     async (args) => {
       const callerPrincipals = await resolvePrincipalsFn(opts.principals);
       return engine.getDocument(String(args.document_id), { principals: callerPrincipals });
@@ -11574,7 +12848,7 @@ async function createMcpApp(engine, opts) {
     tool(
       "query_structured",
       `Answer a question against documents' extracted structured data (only documents with structured data are candidates).${SCOPE_NOTE}`,
-      { question: { type: "string" }, source_ids: { type: "array", items: { type: "string" } } },
+      { question: z.string(), source_ids: z.array(z.string()).optional() },
       async (args) => {
         const callerPrincipals = await resolvePrincipalsFn(opts.principals);
         if (!engine.queryStructured) throw new Error("queryStructured is not available on this engine");
@@ -11588,7 +12862,7 @@ async function createMcpApp(engine, opts) {
       tool(
         "compute",
         `Run LLM-authored JavaScript over in-scope spreadsheet documents and return the computed result.${SCOPE_NOTE}`,
-        { instruction: { type: "string" }, source_ids: { type: "array", items: { type: "string" } } },
+        { instruction: z.string(), source_ids: z.array(z.string()).optional() },
         async (args) => {
           const callerPrincipals = await resolvePrincipalsFn(opts.principals);
           if (!engine.compute) throw new Error("compute is not available on this engine");
@@ -11607,7 +12881,8 @@ async function createMcpApp(engine, opts) {
       }
     },
     engine,
-    opts.principals
+    opts.principals,
+    opts.approvalScope ?? null
   );
   const handler = (async (req, res) => {
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
@@ -11620,6 +12895,9 @@ async function createMcpApp(engine, opts) {
 
 // src/providers/index.ts
 init_llm();
+
+// src/index.ts
+init_redaction();
 var InProcessRunner = class {
   registry = /* @__PURE__ */ new Map();
   /** Kept so the Promise isn't garbage-collected mid-flight. */
@@ -11671,6 +12949,6 @@ var CeleryRunner = class {
 // src/index.ts
 init_usage();
 
-export { ApprovalExpired, ApprovalNotPending, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, GraphLegUnavailable, InProcessRunner, LLMClient, PostgresBackend, RedactionPolicy, RedactionRule, TRUSTED, ToolConfig, UNSET, __version__, applyRedaction, buildEmbedder, buildLlmClient, callLlm, compute, configSchema, createMcpApp, decryptDict, emitError, emitToolCall, emitUsage, encryptDict, extract2 as extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, graphUnits, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, resolvePrincipals, rrfFuse, runMigrate, runSearch, shouldRequireApproval, unitsForFile, upsertRegistry };
+export { ApprovalExpired, ApprovalNotPending, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, GraphLegUnavailable, InProcessRunner, LLMClient, PostgresBackend, RedactionPolicy, RedactionRule, TRUSTED, ToolConfig, UNSET, __version__, applyRedaction, buildEmbedder, buildLlmClient, callLlm, compute, configSchema, createMcpApp, decryptDict, emitError, emitProgress, emitToolCall, emitUsage, encryptDict, extract2 as extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, graphUnits, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, resolvePrincipals, rrfFuse, runMigrate, runSearch, shouldRequireApproval, unitsForFile, upsertRegistry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map