@promptev/context-engine 0.0.0 → 0.0.1

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { randomUUID, createHash, randomBytes, createCipheriv, createDecipheriv, createHmac } from 'crypto';
+import { z } from 'zod';
 import { readFileSync, existsSync, mkdirSync, writeFileSync, openSync, readSync, closeSync } from 'fs';
 import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
@@ -13,11 +14,12 @@ import mammoth from 'mammoth';
 import PostalMime from 'postal-mime';
 import { getDocumentProxy, extractText, renderPageAsImage, extractImages } from 'unpdf';
 import { getEncoding } from 'js-tiktoken';
+import { promises } from 'dns';
+import { isIP } from 'net';
 import { createRequire } from 'module';
 import { createServer } from 'http';
 import { homedir } from 'os';
 import { Command } from 'commander';
-import { z } from 'zod';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -82,6 +84,14 @@ function emitError(hooks, exc, ctx) {
     log.warn("onError callback raised; swallowing");
   }
 }
+function emitProgress(hooks, event) {
+  if (!hooks?.onProgress) return;
+  try {
+    hooks.onProgress(event);
+  } catch {
+    log.warn("onProgress callback raised; swallowing");
+  }
+}
 function emitToolCall(hooks, event) {
   if (!hooks?.onToolCall) return;
   try {
@@ -360,6 +370,184 @@ var init_redaction = __esm({
     HASH_TOKEN_CHARS = 16;
   }
 });
+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;
+    }
+  }
+  return out;
+}
+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);
+      }
+    };
+  }
+});
 
 // src/errors.ts
 var EngineActionError, DocumentNotFoundError, GraphLegUnavailable, ExtraMissingError;
@@ -462,6 +650,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]);
@@ -517,16 +706,116 @@ var init_extras = __esm({
   }
 });
 
-// src/tools/mcp-tools.ts
+// src/sentinels.ts
+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;
+}
+var UNSET, TRUSTED, warnedMethods;
+var init_sentinels = __esm({
+  "src/sentinels.ts"() {
+    UNSET = /* @__PURE__ */ Symbol.for("context_engine.UNSET");
+    TRUSTED = /* @__PURE__ */ Symbol.for("context_engine.TRUSTED");
+    warnedMethods = /* @__PURE__ */ new Set();
+  }
+});
+function requireValidUuid(documentId) {
+  if (!UUID_RE2.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 HandlerError, UUID_RE2;
+var init_routing_core = __esm({
+  "src/routing-core.ts"() {
+    init_sentinels();
+    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();
+    UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  }
+});
 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);
@@ -540,13 +829,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
       });
     }
   );
@@ -554,6 +845,7 @@ function registerToolGateway(mcp, engine, principals) {
 var SCOPE_NOTE;
 var init_mcp_tools = __esm({
   "src/tools/mcp-tools.ts"() {
+    init_routing_core();
     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.";
   }
 });
@@ -606,15 +898,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"
@@ -636,7 +937,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 });
@@ -646,7 +947,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");
@@ -660,7 +961,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");
@@ -679,7 +980,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 });
@@ -693,6 +995,7 @@ var init_mcp = __esm({
   "src/mcp.ts"() {
     init_errors();
     init_extras();
+    init_routing_core();
     init_mcp_tools();
     init_version();
   }
@@ -1967,6 +2270,8 @@ var init_chunkers = __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,
@@ -2009,7 +2314,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";
@@ -2046,11 +2351,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"]);
@@ -2078,22 +2385,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");
         }
@@ -2114,26 +2429,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");
         }
@@ -2154,12 +2470,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);
         }
@@ -2168,10 +2490,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,
@@ -2183,7 +2525,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}
@@ -2207,7 +2549,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 ?? "";
@@ -2802,6 +3158,20 @@ RETURN JSON SCHEMA (EXACT):
 }`;
   }
 });
+
+// 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));
+}
+var init_acl = __esm({
+  "src/tools/acl.ts"() {
+    init_sentinels();
+  }
+});
 function getFileExtension(filename) {
   if (!filename?.includes(".")) return "";
   return filename.slice(filename.lastIndexOf(".")).toLowerCase();
@@ -3618,8 +3988,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);
@@ -3672,16 +4060,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;
@@ -3693,9 +4092,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) {
@@ -3713,31 +4120,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,
@@ -3754,6 +4168,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;
@@ -3773,7 +4198,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 });
@@ -3804,16 +4229,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;
@@ -3829,66 +4266,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);
@@ -3897,9 +4451,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)]);
@@ -3907,6 +4464,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) {
@@ -3928,7 +4486,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");
@@ -3954,7 +4518,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);
@@ -3987,12 +4557,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({
@@ -4001,37 +4581,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();
       }
     };
   }
@@ -4041,7 +4659,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";
@@ -4049,14 +4668,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 [[], {}];
@@ -4067,22 +4722,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) {
@@ -4090,10 +4758,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) {
@@ -4104,12 +4773,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) {
@@ -4117,10 +4792,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) {
@@ -4132,12 +4808,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) {
@@ -4161,9 +4843,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"]);
@@ -4175,6 +4858,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;
@@ -4183,8 +4870,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;
   }
 });
 function checkProvider(cfg2) {
@@ -4362,7 +5053,9 @@ async function prepare(opts) {
       mediaOnly: false,
       providerTokens: {},
       contentHash: calculateContentHash({ fullText: clean }),
-      isMarkdown: false
+      isMarkdown: false,
+      unreadableReason: null,
+      unreadablePages: 0
     };
   }
   const content = opts.content;
@@ -4370,11 +5063,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,
@@ -4385,7 +5079,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) {
@@ -4563,7 +5259,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 };
@@ -4854,6 +5554,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,
@@ -4867,6 +5583,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({
@@ -4877,6 +5594,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) {
@@ -4966,6 +5686,7 @@ async function runIngest(request, opts) {
       );
     }
   }
+  progress(opts.hooks, request, displayName, null, "extract", "started");
   const prepared = await prepare({
     content,
     filename,
@@ -4974,6 +5695,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 },
@@ -5060,8 +5786,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,
@@ -5074,6 +5803,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, []);
@@ -5099,7 +5831,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);
@@ -5109,18 +5847,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,
@@ -5150,15 +5896,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
@@ -5199,9 +5956,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({
@@ -5212,6 +5975,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, {
@@ -5251,7 +6015,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 });
@@ -5266,7 +6032,9 @@ async function runIngest(request, opts) {
       graphUnits: 0,
       providerTokens,
       error: String(exc),
-      redactionFailed
+      redactionFailed,
+      unreadableReason: prepared.unreadableReason,
+      unreadablePages: prepared.unreadablePages
     });
   }
 }
@@ -5310,17 +6078,11 @@ var init_ingest = __esm({
 // src/actions.ts
 function parseDocumentId(documentId) {
   const raw = String(documentId ?? "").replace(/[ \n\t]/g, "").trim();
-  if (!UUID_RE2.test(raw)) {
+  if (!UUID_RE3.test(raw)) {
     throw new EngineActionError(`invalid document id: ${JSON.stringify(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));
-}
 function scopeSql(sourceIds, principals, params) {
   const where = [];
   if (sourceIds != null) {
@@ -5409,7 +6171,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) {
@@ -5458,7 +6222,7 @@ async function listDocuments(opts) {
   let where = scopeSql(sourceIds, principals, params);
   const cursorTime = parsedCursor?.time ?? parsedCursor?.created_at;
   const cursorId = parsedCursor?.id;
-  if (cursorTime && cursorId && UUID_RE2.test(String(cursorId))) {
+  if (cursorTime && cursorId && UUID_RE3.test(String(cursorId))) {
     params.push(cursorTime, cursorId);
     const extra = `(created_at < $${params.length - 1} OR (created_at = $${params.length - 1} AND id < $${params.length}::uuid))`;
     where = where ? `${where} AND ${extra}` : `WHERE ${extra}`;
@@ -5466,7 +6230,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
@@ -5491,7 +6255,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,
@@ -5649,9 +6421,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 {
@@ -5679,13 +6451,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 = {};
@@ -5766,7 +6538,7 @@ ${schemaLines.join("\n")}`;
     hooks: opts.hooks
   });
 }
-var MAX_LIST_LIMIT, MAX_COMPUTE_TEXT_CHARS, DEFAULT_COMPUTE_TIMEOUT, MAX_COMPUTE_DOCUMENTS, TABULAR_MIME_PATTERNS, UUID_RE2, WORD_RE, STOPWORDS, SHEET_MARKER_RE2, CODE_FENCE_RE, COMPUTE_SYSTEM_PROMPT;
+var MAX_LIST_LIMIT, MAX_COMPUTE_TEXT_CHARS, DEFAULT_COMPUTE_TIMEOUT, MAX_COMPUTE_DOCUMENTS, TABULAR_MIME_PATTERNS, UUID_RE3, WORD_RE, STOPWORDS, SHEET_MARKER_RE2, CODE_FENCE_RE, COMPUTE_SYSTEM_PROMPT, visible;
 var init_actions = __esm({
   "src/actions.ts"() {
     init_chunkers();
@@ -5776,13 +6548,14 @@ var init_actions = __esm({
     init_redaction();
     init_sandbox();
     init_structured();
+    init_acl();
     init_ingest();
     MAX_LIST_LIMIT = 200;
     MAX_COMPUTE_TEXT_CHARS = 2e6;
     DEFAULT_COMPUTE_TIMEOUT = 30;
     MAX_COMPUTE_DOCUMENTS = 50;
     TABULAR_MIME_PATTERNS = ["%csv%", "%sheet%", "%excel%", "%spreadsheetml%", "%tab-separated%"];
-    UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    UUID_RE3 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     WORD_RE = /[^\W\d_]+/gu;
     STOPWORDS = /* @__PURE__ */ new Set([
       "the",
@@ -5861,6 +6634,7 @@ Rules:
 1. Set a variable named \`result\` to the final answer (a number, string, array, or object).
 2. No file I/O, no network calls, no imports, no require, no process.
 3. Return ONLY the JavaScript code \u2014 no markdown fences, no explanation, no commentary.`;
+    visible = aclVisible;
   }
 });
 function estimatedTokens(texts) {
@@ -5899,7 +6673,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 (OPENAI_FAMILY2.has(cfg2.provider)) {
@@ -7447,10 +8221,10 @@ async function runLegs(query, opts) {
   return ranked;
 }
 async function hydrate(pool, chunkIds) {
-  const parsed = chunkIds.filter((id) => UUID_RE3.test(id));
+  const parsed = chunkIds.filter((id) => UUID_RE4.test(id));
   if (parsed.length !== chunkIds.length) {
     for (const cid of chunkIds) {
-      if (!UUID_RE3.test(cid)) {
+      if (!UUID_RE4.test(cid)) {
         console.warn("search: skipping unhydratable chunk id %s", cid);
       }
     }
@@ -7549,6 +8323,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)
   };
@@ -7569,13 +8344,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;
@@ -7649,7 +8419,7 @@ async function runSearch(query, opts) {
   });
   return { hits, usage };
 }
-var MIN_LEG_CANDIDATES, MAX_LEG_CANDIDATES, UNITS_PER_SCOPE_HYBRID, UNITS_PER_SCOPE_GRAPH, UUID_RE3;
+var MIN_LEG_CANDIDATES, MAX_LEG_CANDIDATES, UNITS_PER_SCOPE_HYBRID, UNITS_PER_SCOPE_GRAPH, UUID_RE4;
 var init_search = __esm({
   "src/search.ts"() {
     init_compression();
@@ -7662,37 +8432,7 @@ var init_search = __esm({
     MAX_LEG_CANDIDATES = 500;
     UNITS_PER_SCOPE_HYBRID = 1;
     UNITS_PER_SCOPE_GRAPH = 5;
-    UUID_RE3 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-  }
-});
-
-// src/sentinels.ts
-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;
-}
-var UNSET, TrustedSentinel, TRUSTED;
-var init_sentinels = __esm({
-  "src/sentinels.ts"() {
-    UNSET = /* @__PURE__ */ Symbol.for("context_engine.UNSET");
-    TrustedSentinel = class {
-      [Symbol.toStringTag] = "TRUSTED";
-      toString() {
-        return "TRUSTED";
-      }
-      valueOf() {
-        return true;
-      }
-    };
-    TRUSTED = Object.freeze(new TrustedSentinel());
+    UUID_RE4 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
   }
 });
 function isSpacelessQuery(query) {
@@ -7735,7 +8475,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) {
@@ -7748,13 +8488,13 @@ WITH eligible AS MATERIALIZED (
 )
 SELECT id::text FROM eligible
 ORDER BY embedding <=> ${vec}
-LIMIT $3
+LIMIT $4
 `;
 }
 function idsOf(rows) {
   return rows.map((r) => String(r.id));
 }
-var MIN_ITERATIVE_SCAN_VERSION, ANN_MIN_EF_SEARCH, ANN_MAX_EF_SEARCH, ANN_SCAN_FRACTION, ANN_SCAN_PER_ROW, ANN_MIN_SCAN_TUPLES, ANN_MAX_SCAN_TUPLES, ANN_SCAN_MEM_MULTIPLIER, ANN_EXACT_THRESHOLD, SCOPE, SQL_FTS, SQL_TRGM, SQL_COUNT_ELIGIBLE2, SQL_FILTER_IDS, UUID_RE4, PostgresBackend;
+var MIN_ITERATIVE_SCAN_VERSION, ANN_MIN_EF_SEARCH, ANN_MAX_EF_SEARCH, ANN_SCAN_FRACTION, ANN_SCAN_PER_ROW, ANN_MIN_SCAN_TUPLES, ANN_MAX_SCAN_TUPLES, ANN_SCAN_MEM_MULTIPLIER, ANN_EXACT_THRESHOLD, SCOPE, SQL_FTS, SQL_TRGM, SQL_COUNT_ELIGIBLE2, SQL_FILTER_IDS, UUID_RE5, PostgresBackend;
 var init_storage = __esm({
   "src/storage.ts"() {
     init_text();
@@ -7769,25 +8509,26 @@ var init_storage = __esm({
     ANN_EXACT_THRESHOLD = 5e4;
     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)
 `;
     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
 `;
     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
 `;
     SQL_COUNT_ELIGIBLE2 = `
 SELECT count(*)::int AS count FROM (
@@ -7795,16 +8536,16 @@ SELECT count(*)::int AS count FROM (
   FROM context_engine_chunks c
   WHERE c.embedding IS NOT NULL
     ${SCOPE}
-  LIMIT $3
+  LIMIT $4
 ) probe
 `;
     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}
 `;
-    UUID_RE4 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    UUID_RE5 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     PostgresBackend = class {
       supportsFts = true;
       supportsTrgm = true;
@@ -7826,24 +8567,26 @@ WHERE c.id = ANY($3::uuid[])
        * 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,
@@ -7852,7 +8595,16 @@ WHERE c.id = ANY($3::uuid[])
                 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");
@@ -7912,24 +8664,24 @@ WHERE c.id = ANY($3::uuid[])
         const parsed = [];
         for (const cid of chunkIds) {
           try {
-            if (UUID_RE4.test(String(cid))) parsed.push(String(cid));
+            if (UUID_RE5.test(String(cid))) parsed.push(String(cid));
           } catch {
           }
         }
         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;
@@ -7938,7 +8690,7 @@ WHERE c.id = ANY($3::uuid[])
           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);
@@ -7984,18 +8736,18 @@ WHERE c.id = ANY($3::uuid[])
       }
       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) {
@@ -8008,11 +8760,17 @@ WHERE c.id = ANY($3::uuid[])
           client.release();
         }
       }
-      async eligibleIsSmall(client, src, principals) {
+      async eligibleIsSmall(client, binds) {
         const cap = this.exactThreshold + 1;
-        const { rows } = await client.query(SQL_COUNT_ELIGIBLE2, [src, principals, cap]);
+        const { rows } = await client.query(SQL_COUNT_ELIGIBLE2, [...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}`);
@@ -8107,19 +8865,6 @@ var init_function = __esm({
   "src/tools/executors/function.ts"() {
   }
 });
-
-// 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));
-}
-var init_acl = __esm({
-  "src/tools/acl.ts"() {
-  }
-});
 function coerceValue(raw) {
   const trimmed = raw.trim();
   if (trimmed.length >= 2 && trimmed[0] === trimmed[trimmed.length - 1] && (trimmed[0] === "'" || trimmed[0] === '"')) {
@@ -8166,45 +8911,121 @@ function shouldRequireApproval(ct, args) {
   if (!condition) return false;
   return evaluateCondition(condition, args ?? {});
 }
-async function createPending(engine, opts) {
+function rowToRecord(row) {
+  return {
+    id: String(row.id),
+    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: 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 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");
+}
 var DEFAULT_TIMEOUT_MINUTES, CONDITION_RE;
 var init_approval = __esm({
   "src/tools/approval.ts"() {
     init_errors();
+    init_sentinels();
     init_acl();
     DEFAULT_TIMEOUT_MINUTES = 60;
     CONDITION_RE = /^\s*(?<field>[A-Za-z_][A-Za-z0-9_.]*)\s*(?<op>>=|<=|==|!=|>|<)\s*(?<value>.+?)\s*$/;
@@ -8315,8 +9136,48 @@ var init_audit = __esm({
 });
 
 // src/tools/config.ts
-var KINDS, ToolConfig;
-var init_config = __esm({
+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;
+}
+var KINDS, ToolConfig, REDACTED_SENTINEL, ConfigTemplateError;
+var init_config2 = __esm({
   "src/tools/config.ts"() {
     KINDS = ["http", "db", "mcp", "function"];
     ToolConfig = class _ToolConfig {
@@ -8330,6 +9191,10 @@ var init_config = __esm({
       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;
@@ -8341,6 +9206,7 @@ var init_config = __esm({
         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)) {
@@ -8363,10 +9229,14 @@ var init_config = __esm({
           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 ?? {}
         });
       }
     };
+    REDACTED_SENTINEL = "__redacted__";
+    ConfigTemplateError = class extends Error {
+    };
   }
 });
 
@@ -8376,6 +9246,198 @@ var init_crypto2 = __esm({
     init_crypto();
   }
 });
+function isRedirect(resp) {
+  return resp.status >= 300 && resp.status < 400 || resp.type === "opaqueredirect";
+}
+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];
+  });
+}
+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`
+    );
+  }
+}
+var MAX_RESPONSE_BYTES, MAX_REDIRECTS, EgressDenied, resolver, V4_PRIVATE, V6_PRIVATE, V4_NETS, V6_NETS, MAPPED_V4, NAT64, SIXTOFOUR;
+var init_egress = __esm({
+  "src/tools/egress.ts"() {
+    MAX_RESPONSE_BYTES = 1e6;
+    MAX_REDIRECTS = 5;
+    EgressDenied = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "EgressDenied";
+      }
+    };
+    resolver = {
+      async lookup(host) {
+        const answers = await promises.lookup(host, { all: true, verbatim: true });
+        return answers.map((a) => a.address);
+      }
+    };
+    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)
+    ];
+    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
+    ];
+    V4_NETS = compile(V4_PRIVATE);
+    V6_NETS = compile(V6_PRIVATE);
+    MAPPED_V4 = compile([["::ffff:0:0", 96]])[0];
+    NAT64 = compile([["64:ff9b::", 96]])[0];
+    SIXTOFOUR = compile([["2002::", 16]])[0];
+  }
+});
 
 // src/tools/executors/db.ts
 var db_exports = {};
@@ -8392,6 +9454,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);
 }
@@ -8520,24 +9585,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` };
       }
     }
@@ -8671,7 +9740,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_db2 = __esm({
   "src/tools/executors/db.ts"() {
     init_errors();
@@ -8680,10 +9749,22 @@ var init_db2 = __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;
   }
 });
 
@@ -8718,10 +9799,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";
@@ -8733,25 +9842,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;
@@ -8772,7 +9903,7 @@ async function executeHttp(config, args, opts = {}) {
       }
     }
   }
-  const requestInit = {
+  let requestInit = {
     method,
     url: url ?? "",
     headers
@@ -8808,27 +9939,56 @@ 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;
 }
-var TIMEOUT_MS5, SENSITIVE_RESPONSE_HEADERS;
+var TIMEOUT_MS5, SENSITIVE_RESPONSE_HEADERS, REDIRECT_STATUS, CROSS_ORIGIN_HEADERS;
 var init_http = __esm({
   "src/tools/executors/http.ts"() {
+    init_errors();
+    init_egress();
     TIMEOUT_MS5 = 3e4;
     SENSITIVE_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
       "set-cookie",
@@ -8837,10 +9997,19 @@ var init_http = __esm({
       "proxy-authenticate",
       "www-authenticate"
     ]);
+    REDIRECT_STATUS = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
+    CROSS_ORIGIN_HEADERS = /* @__PURE__ */ new Set(["authorization", "proxy-authorization", "cookie"]);
   }
 });
 
 // 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 });
+}
 function parseSseBuffer(raw) {
   const dataLines = raw.split("\n").filter((ln) => ln.startsWith("data:")).map((ln) => ln.slice(5).trimStart());
   if (!dataLines.length) return null;
@@ -8853,10 +10022,12 @@ function parseSseBuffer(raw) {
   }
   return null;
 }
-var MCPError, HttpTransport, SseTransport, WsTransport, MCPClient, MCPRegistry, PromptevMCP;
+var REDIRECT_MESSAGE, MCPError, HttpTransport, SseTransport, WsTransport, MCPClient, MCPRegistry, PromptevMCP;
 var init_mcp_client = __esm({
   "src/tools/executors/mcp-client.ts"() {
     init_version();
+    init_egress();
+    REDIRECT_MESSAGE = "MCP server redirected; register the final URL";
     MCPError = class _MCPError extends Error {
       code;
       data;
@@ -8873,10 +10044,12 @@ var init_mcp_client = __esm({
     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",
@@ -8884,6 +10057,7 @@ var init_mcp_client = __esm({
         };
       }
       async connect() {
+        await checkEgress(this.url, this.allowPrivate);
       }
       async close() {
         this.sessionId = null;
@@ -8897,10 +10071,17 @@ var init_mcp_client = __esm({
         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)}`);
@@ -8933,11 +10114,20 @@ var init_mcp_client = __esm({
       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);
@@ -8950,14 +10140,19 @@ var init_mcp_client = __esm({
         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();
@@ -9009,11 +10204,19 @@ var init_mcp_client = __esm({
           }
         }
         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();
@@ -9032,14 +10235,17 @@ var init_mcp_client = __esm({
       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);
@@ -9080,21 +10286,27 @@ var init_mcp_client = __esm({
       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() {
@@ -9146,7 +10358,15 @@ var init_mcp_client = __esm({
         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();
@@ -9229,7 +10449,7 @@ var init_mcp_client = __esm({
         }
         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();
       }
@@ -9237,11 +10457,11 @@ var init_mcp_client = __esm({
     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);
@@ -9293,8 +10513,18 @@ var init_mcp_client = __esm({
     };
     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();
@@ -9419,6 +10649,9 @@ var init_registry = __esm({
   "src/tools/registry.ts"() {
   }
 });
+function allowPrivateEgress(engine) {
+  return Boolean(engine?.config?.allowPrivateEgress);
+}
 function toolVisible(ct, principals) {
   return aclVisible(ct.acl, principals);
 }
@@ -9500,11 +10733,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),
@@ -9515,9 +10756,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`;
@@ -9528,7 +10784,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;
 }
@@ -9548,13 +10806,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,
@@ -9565,7 +10828,8 @@ async function registerTool(engine, tc) {
       configEncrypted,
       tc.requiresApproval,
       JSON.stringify(tc.approvalPolicy ?? {}),
-      tc.enabled
+      tc.enabled,
+      JSON.stringify(tc.metaData ?? {})
     ]
   );
   return id;
@@ -9582,12 +10846,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()`);
@@ -9596,7 +10889,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]);
@@ -9645,17 +10939,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 };
@@ -9676,12 +10991,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();
@@ -9689,11 +11008,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;
@@ -9710,7 +11038,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 ?? {} };
@@ -9719,7 +11047,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);
@@ -9730,7 +11058,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 ?? "");
@@ -9745,7 +11076,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`);
@@ -9766,10 +11099,19 @@ 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));
+}
+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)) {
@@ -9778,22 +11120,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
         }
       };
     }
@@ -9818,8 +11170,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
       });
@@ -9859,17 +11212,19 @@ async function executeTool(engine, callName, args, opts = {}) {
     usage: { units: 1, kind: "tool", tool_name: ct.callName, truncated }
   };
 }
-var RESULT_MAX_CHARS, RESULT_MAX_ROWS, UPDATABLE_COLUMNS, PROBE_AUTH, PROBE_UNREACHABLE, PROBE_TIMEOUT, PROBE_MISCONFIGURED;
+var RESULT_MAX_CHARS, RESULT_MAX_ROWS, UPDATABLE_COLUMNS, PROBE_AUTH, PROBE_UNREACHABLE, PROBE_TIMEOUT, PROBE_MISCONFIGURED, warnedUnscoped;
 var init_governance = __esm({
   "src/tools/governance.ts"() {
     init_errors();
     init_hooks();
     init_redaction();
+    init_sentinels();
     init_acl();
     init_approval();
     init_audit();
-    init_config();
+    init_config2();
     init_crypto2();
+    init_egress();
     init_db2();
     init_http();
     init_mcp_client();
@@ -9887,7 +11242,9 @@ var init_governance = __esm({
       "requires_approval",
       "approvalPolicy",
       "approval_policy",
-      "enabled"
+      "enabled",
+      "metaData",
+      "meta_data"
     ]);
     PROBE_AUTH = [
       "authentication failed",
@@ -9926,6 +11283,7 @@ var init_governance = __esm({
       "not supported",
       "unsupported"
     ];
+    warnedUnscoped = /* @__PURE__ */ new Set();
   }
 });
 function mulberry322(seed) {
@@ -10757,7 +12115,8 @@ var retrieval_exports = {};
 __export(retrieval_exports, {
   buildGraphRanked: () => buildGraphRanked,
   corpusIsAclUniform: () => corpusIsAclUniform,
-  shouldUseCommunitySummaries: () => shouldUseCommunitySummaries
+  shouldUseCommunitySummaries: () => shouldUseCommunitySummaries,
+  vectorSeedIds: () => vectorSeedIds
 });
 function vecLiteral2(vector) {
   return `[${vector.map((x) => Number(x)).join(",")}]`;
@@ -10783,8 +12142,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,
@@ -10849,8 +12208,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) {
@@ -10859,13 +12218,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`,
-    [vecLiteral2(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`,
+      [vecLiteral2(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 {
@@ -10874,11 +12249,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));
@@ -10900,6 +12282,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
     });
@@ -10951,7 +12334,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[])
 `;
   }
 });
@@ -11115,11 +12499,19 @@ var init_engine = __esm({
       _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) {
@@ -11305,7 +12697,9 @@ var init_engine = __esm({
             graphStore: await this.getGraphStore(),
             hooks: this.hooks,
             sourceIds: opts.sourceIds ?? null,
-            principals
+            documentIds: opts.documentIds ?? null,
+            principals,
+            backend: this.backend
           });
         }
         return runSearch(query, {
@@ -11315,6 +12709,7 @@ var init_engine = __esm({
           embedder: this.embedder,
           pool,
           sourceIds: opts.sourceIds,
+          documentIds: opts.documentIds,
           principals,
           topK: opts.topK,
           mode: opts.mode,
@@ -11420,7 +12815,7 @@ var init_engine = __esm({
           hooks: this.hooks,
           sourceIds: opts.sourceIds,
           principals: resolvePrincipals(opts.principals, "compute"),
-          docIds: opts.docIds,
+          documentIds: opts.documentIds,
           modelCfg: opts.modelCfg,
           timeout: opts.timeout
         });
@@ -11473,151 +12868,16 @@ var init_engine = __esm({
           sourceId: opts.sourceId,
           principals: resolvePrincipals(opts.principals, "executeTool"),
           actor: opts.actor,
-          source: opts.source ?? "api"
+          source: opts.source ?? "api",
+          approvalScope: opts.approvalScope
         });
       }
     };
   }
 });
 
-// src/config.ts
-init_redaction();
-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;
-    }
-  }
-  return out;
-}
-
 // src/cli.ts
+init_config();
 init_db();
 
 // src/diagnostics.ts