@promptev/context-engine 0.0.0 → 0.0.1

package/dist/index.d.cts

@@ -1,91 +1,29 @@
 import { Pool } from 'pg';
-import { C as ContextEngineConfig, L as LLMConfig, R as RerankerConfig } from './config-Bl9U789m.cjs';
-export { a as ContextEngineConfigInit, E as EmbeddingConfig, F as FusionConfig, G as GraphConfig, S as StorageConfig } from './config-Bl9U789m.cjs';
-import { H as Hooks, R as RedactionPolicy, U as UsageEvent, I as IngestReport } from './redaction-BmDSWJ7h.cjs';
-export { D as DocumentReport, a as RedactionRule, b as RedactionRuleInit, c as applyRedaction, e as emitError, d as emitToolCall, f as emitUsage, g as graphUnits, u as unitsForFile } from './redaction-BmDSWJ7h.cjs';
-import { E as Embedder, F as FetchImpl } from './embeddings-B-jZ42mk.cjs';
-export { a as EmbedKind, b as buildEmbedder } from './embeddings-B-jZ42mk.cjs';
-import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-BDkcv4qZ.cjs';
-export { c as ToolKind, d as configSchema } from './governance-BDkcv4qZ.cjs';
+import { C as ContextEngineConfig, L as LLMConfig, E as ExtractionConfig, R as RerankerConfig } from './config-CNnASw5X.cjs';
+export { a as ContextEngineConfigInit, b as EmbeddingConfig, F as FusionConfig, G as GraphConfig, S as StorageConfig } from './config-CNnASw5X.cjs';
+import { H as Hooks, R as RedactionPolicy, U as UsageEvent, P as ProgressEvent, I as IngestReport } from './redaction-BqD_DEUQ.cjs';
+export { D as DocumentReport, a as RedactionRule, b as RedactionRuleInit, c as applyRedaction, e as emitError, d as emitProgress, f as emitToolCall, g as emitUsage, h as graphUnits, u as unitsForFile } from './redaction-BqD_DEUQ.cjs';
+import { E as Embedder, S as StorageBackend, F as FetchImpl } from './storage-DU1JRno5.cjs';
+export { C as ChunkRow, a as EmbedKind, P as PostgresBackend, b as SearchScope, c as buildEmbedder } from './storage-DU1JRno5.cjs';
+import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-D8g6Wyvb.cjs';
+export { c as ToolKind, d as configSchema } from './governance-D8g6Wyvb.cjs';
 export { createMcpApp } from './mcp.cjs';
 import 'zod';
 import 'node:http';
 
-interface ChunkRow {
-    idx: number;
-    text: string;
-    lang?: string | null;
-    embedding?: number[] | null;
-    meta?: Record<string, unknown>;
-}
-interface SearchScope {
-    sourceIds?: string[] | null;
-    principals?: string[] | null;
-    limit?: number;
-}
-interface StorageBackend {
-    supportsFts: boolean;
-    supportsTrgm: boolean;
-    supportsAnn: boolean;
-    upsertChunks(documentId: string, sourceId: string | null, acl: string[] | null, chunks: readonly ChunkRow[]): Promise<number>;
-    deleteChunks(documentId: string): Promise<void>;
-    updateChunkEmbeddings(documentId: string, vectors: readonly number[][]): Promise<number>;
-    updateChunkAcl(documentId: string, acl: string[] | null): Promise<number>;
-    filterIds(chunkIds: readonly string[], scope: SearchScope): Promise<string[]>;
-    ftsSearch(query: string, scope: SearchScope): Promise<string[]>;
-    trgmSearch(query: string, scope: SearchScope): Promise<string[]>;
-    annSearch(vector: readonly number[], scope: SearchScope): Promise<string[]>;
-}
-declare class PostgresBackend implements StorageBackend {
-    supportsFts: boolean;
-    supportsTrgm: boolean;
-    supportsAnn: boolean;
-    private readonly pool;
-    private readonly exactThresholdOverride;
-    /** Tri-state: null = not yet checked. */
-    private iterativeScan;
-    constructor(pool: Pool, exactThreshold?: number | null);
-    private get exactThreshold();
-    /**
-     * Bind values for SCOPE + the row limit.
-     * `principals` is passed through UNCHANGED: null (trusted) and [] (anonymous)
-     * mean different things.
-     */
-    private scopeParams;
-    upsertChunks(documentId: string, sourceId: string | null, acl: string[] | null, chunks: readonly ChunkRow[]): Promise<number>;
-    deleteChunks(documentId: string): Promise<void>;
-    updateChunkEmbeddings(documentId: string, vectors: readonly number[][]): Promise<number>;
-    updateChunkAcl(documentId: string, acl: string[] | null): Promise<number>;
-    filterIds(chunkIds: readonly string[], scope: SearchScope): Promise<string[]>;
-    ftsSearch(query: string, scope: SearchScope): Promise<string[]>;
-    trgmSearch(query: string, scope: SearchScope): Promise<string[]>;
-    /**
-     * Set pg_trgm's similarity threshold for this query via the `set_limit()` /
-     * `show_limit()` FUNCTIONS — never the GUC `pg_trgm.similarity_threshold`.
-     *
-     * The GUC is registered lazily, only once pg_trgm's shared library is loaded
-     * into the backend process. On a fresh pooled connection that has not yet
-     * run any pg_trgm operation, `SHOW pg_trgm.similarity_threshold` raises
-     * "unrecognized configuration parameter" — and because that error aborts the
-     * surrounding transaction, a fallback issued on the same connection then
-     * fails with "current transaction is aborted". Every connection a pool hands
-     * out is fresh, so this is the common case, not an edge case. Calling
-     * `set_limit()` loads the library and does not depend on the GUC. This
-     * mirrors the Python backend, which was hardened against exactly this.
-     *
-     * `set_limit()` is connection-scoped and survives COMMIT and the return to
-     * the pool, so the previous value is captured here and restored by the
-     * caller.
-     */
-    private applyTrgmThreshold;
-    private restoreTrgmLimit;
-    annSearch(vector: readonly number[], scope: SearchScope): Promise<string[]>;
-    private eligibleIsSmall;
-    private tuneAnnScan;
-    private scanBudget;
-    private enableIterativeScan;
-    private supportsIterativeScan;
-}
+/**
+ * Sentinels distinguishing omitted arguments from real values, including null.
+ *
+ * UNSET: "argument omitted" vs null (e.g. updateDocument acl=null means unrestricted).
+ * TRUSTED: trusted caller, ACL filtering disabled. Truthy on purpose so
+ * `if (principals)` does not treat a trusted caller as anonymous.
+ */
+declare const UNSET: unique symbol;
+type Unset = typeof UNSET;
+declare const TRUSTED: unique symbol;
+type Trusted = typeof TRUSTED;
+type Principals = string[] | null | typeof TRUSTED | undefined;
+declare function resolvePrincipals(value: Principals, method: string): string[] | null;
 
 type Mode$1 = "hybrid" | "graph";
 interface IngestRequest {
@@ -204,7 +142,7 @@ declare function compute(instruction: string, opts: {
     hooks: Hooks;
     sourceIds?: string[] | null;
     principals?: string[] | null;
-    docIds?: string[] | null;
+    documentIds?: string[] | null;
     modelCfg?: LLMConfig | null;
     timeout?: number;
 }): Promise<Record<string, unknown>>;
@@ -317,6 +255,7 @@ interface RunSearchOpts {
     embedder: Embedder;
     pool: Pool;
     sourceIds?: string[] | null;
+    documentIds?: string[] | null;
     principals?: string[] | null;
     topK?: number;
     mode?: Mode;
@@ -392,25 +331,6 @@ declare function redactHits(hits: Hit[], policy: RedactionPolicy, opts: {
  */
 declare function runSearch(query: string, opts: RunSearchOpts): Promise<SearchResult>;
 
-/**
- * Sentinels distinguishing omitted arguments from real values, including null.
- *
- * UNSET: "argument omitted" vs null (e.g. updateDocument acl=null means unrestricted).
- * TRUSTED: trusted caller, ACL filtering disabled. Truthy on purpose so
- * `if (principals)` does not treat a trusted caller as anonymous.
- */
-declare const UNSET: unique symbol;
-type Unset = typeof UNSET;
-declare class TrustedSentinel {
-    readonly [Symbol.toStringTag] = "TRUSTED";
-    toString(): string;
-    valueOf(): boolean;
-}
-declare const TRUSTED: TrustedSentinel;
-type Trusted = typeof TRUSTED;
-type Principals = string[] | null | typeof TRUSTED | undefined;
-declare function resolvePrincipals(value: Principals, method: string): string[] | null;
-
 /**
  * `ContextEngine` — the package's public object.
  *
@@ -439,6 +359,7 @@ declare class ContextEngine implements ToolEngine {
     constructor(config: ContextEngineConfig, opts?: {
         onUsage?: ((e: UsageEvent) => void) | null;
         onError?: ((e: unknown, ctx: Record<string, unknown>) => void) | null;
+        onProgress?: ((e: ProgressEvent) => void) | null;
     });
     private ensurePool;
     /** The embedding client, built on first use. */
@@ -486,6 +407,8 @@ declare class ContextEngine implements ToolEngine {
      */
     search(query: string, opts?: {
         sourceIds?: string[] | null;
+        /** Narrows WITHIN a source; INTERSECTS with `sourceIds`. */
+        documentIds?: string[] | null;
         principals?: Principals;
         topK?: number;
         mode?: "hybrid" | "graph";
@@ -539,7 +462,7 @@ declare class ContextEngine implements ToolEngine {
     compute(instruction: string, opts?: {
         sourceIds?: string[] | null;
         principals?: Principals;
-        docIds?: string[] | null;
+        documentIds?: string[] | null;
         modelCfg?: LLMConfig | null;
         timeout?: number;
     }): Promise<Record<string, unknown>>;
@@ -566,6 +489,9 @@ declare class ContextEngine implements ToolEngine {
         principals?: Principals;
         actor?: Record<string, unknown> | null;
         source?: string;
+        /** Opaque claim scope for approvals (e.g. a run id) — separate from
+         * `sourceId`. See `governance.executeTool`. */
+        approvalScope?: string | null;
     }): Promise<Record<string, unknown>>;
 }
 
@@ -576,6 +502,23 @@ declare class ContextEngine implements ToolEngine {
  * reported via `hooks.onError` and degrade to whatever partial text was recovered.
  */
 
+/**
+ * WHY a document came back with less text than it has, when the answer is
+ * actionable. Mirrors the Python client's `Extracted.unreadable_reason` —
+ * that docstring is the canonical rationale; only the value semantics are
+ * restated here:
+ *
+ * - `needs_vision`  — pages had no usable text layer and no vision model was
+ *   configured. FIXABLE by configuring one (the OCR fallback may have tried
+ *   and read nothing; a vision model is still the actionable upgrade).
+ * - `vision_failed` — a vision model was configured and produced nothing for
+ *   those pages. An ops problem, not a configuration one.
+ *
+ * `null` means nothing was lost — a page a reader READ and found empty is
+ * blank, not unreadable. A closed set on purpose (callers branch on it), and
+ * NOT an error channel; `mediaOnly` stays set alongside it for whole files.
+ */
+type UnreadableReason = "needs_vision" | "vision_failed";
 declare class Extracted {
     text: string;
     pages: number | null;
@@ -584,6 +527,10 @@ declare class Extracted {
     providerTokens: Record<string, number>;
     llmPictures: number;
     isMarkdown: boolean;
+    /** See `UnreadableReason`. `mediaOnly` is the same idea for whole files and
+     *  stays set alongside this, so existing callers keep working. */
+    unreadableReason: UnreadableReason | null;
+    unreadablePages: number;
     constructor(init: {
         text: string;
         pages?: number | null;
@@ -592,6 +539,8 @@ declare class Extracted {
         providerTokens?: Record<string, number>;
         llmPictures?: number;
         isMarkdown?: boolean;
+        unreadableReason?: UnreadableReason | null;
+        unreadablePages?: number;
     });
 }
 /**
@@ -601,6 +550,7 @@ declare class Extracted {
 declare function extract(content: Buffer, filename: string, mime: string | null, opts: {
     visionLlm?: LLMConfig | null;
     hooks: Hooks;
+    extraction?: ExtractionConfig | null;
 }): Promise<Extracted>;
 
 declare const DEFAULT_LEG_WEIGHT = 1;
@@ -620,7 +570,8 @@ declare function rrfFuse(rankedLists: Record<string, string[]>, opts: {
  * `callLlm(cfg, { system, user, jsonMode, images, client })` is the single entry
  * point. Returns `[text, { input, output }]`.
  *
- * Images are always PNG. 30s timeout, no retries. Injectable `client` / `fetch`.
+ * Images are always PNG. 240s call timeout (every provider), no retries.
+ * Injectable `client` / `fetch`.
  * `callLlm` owns and closes the client it builds unless one is passed in.
  */
 
@@ -660,6 +611,17 @@ type LlmCallOpts = {
     user: string;
     jsonMode?: boolean;
     images?: ImageBytes[] | null;
+    maxTokens?: number | null;
+    /** Reasoning tokens are drawn from `maxTokens`, so a caller that wants
+     * transcription rather than deliberation must be able to spend the whole
+     * budget on output. Omitted = the provider's default. Applied per provider
+     * capability: gemini and anthropic take it directly (anthropic thinking is
+     * opt-in, so 0 sends nothing and a positive budget drops `temperature` —
+     * the API rejects the combination); bedrock forwards a positive budget as
+     * the anthropic-style passthrough; the openai family has no portable
+     * thinking control. */
+    thinkingBudget?: number | null;
+    temperature?: number | null;
 };
 type LLMClientOpts = {
     client?: ChatClient | null;
@@ -817,6 +779,7 @@ interface ApprovalRecord {
     toolName: string;
     toolArgsFrozen: Record<string, unknown>;
     sourceId: string | null;
+    approvalScope: string | null;
     principals: unknown;
     status: string;
     approver: string | null;
@@ -835,7 +798,7 @@ type EngineLike = {
 };
 declare function shouldRequireApproval(ct: Pick<CanonicalTool, "requiresApproval" | "approvalPolicy">, args: Record<string, unknown>): boolean;
 declare function resolveApproval(engine: EngineLike, approvalId: string, decision: "approved" | "rejected", approver: string, meta?: Record<string, unknown> | null, opts?: {
-    principals?: string[] | null;
+    principals?: string[] | null | Trusted;
 }): Promise<ApprovalRecord>;
 
 /**
@@ -848,4 +811,4 @@ declare function functionTool(fn: (...args: never[]) => unknown): CanonicalTool;
 /** Bumped by CI on every main merge; 0.0.0 = pre-first-release. */
 declare const __version__ = "0.0.0";
 
-export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, type ChunkRow, CodeExecutionError, CodeExecutionTimeout, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, LLMClient, LLMConfig, PostgresBackend, type Principals, RedactionPolicy, RerankerConfig, type SearchResult, type SearchScope, type StorageBackend, TRUSTED, type TaskRunner, type TaskStatus, ToolConfig, type Trusted, UNSET, type Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, decryptDict, encryptDict, extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, resolvePrincipals, rrfFuse, runMigrate, runSearch, shouldRequireApproval, upsertRegistry };
+export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, ExtractionConfig, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, LLMClient, LLMConfig, type Principals, ProgressEvent, RedactionPolicy, RerankerConfig, type SearchResult, StorageBackend, TRUSTED, type TaskRunner, type TaskStatus, ToolConfig, type Trusted, UNSET, type Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, decryptDict, encryptDict, extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, resolvePrincipals, rrfFuse, runMigrate, runSearch, shouldRequireApproval, upsertRegistry };

package/dist/index.d.ts

@@ -1,91 +1,29 @@
 import { Pool } from 'pg';
-import { C as ContextEngineConfig, L as LLMConfig, R as RerankerConfig } from './config-Bt9bUQqU.js';
-export { a as ContextEngineConfigInit, E as EmbeddingConfig, F as FusionConfig, G as GraphConfig, S as StorageConfig } from './config-Bt9bUQqU.js';
-import { H as Hooks, R as RedactionPolicy, U as UsageEvent, I as IngestReport } from './redaction-BmDSWJ7h.js';
-export { D as DocumentReport, a as RedactionRule, b as RedactionRuleInit, c as applyRedaction, e as emitError, d as emitToolCall, f as emitUsage, g as graphUnits, u as unitsForFile } from './redaction-BmDSWJ7h.js';
-import { E as Embedder, F as FetchImpl } from './embeddings-DaSdAZN3.js';
-export { a as EmbedKind, b as buildEmbedder } from './embeddings-DaSdAZN3.js';
-import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-XIScatRO.js';
-export { c as ToolKind, d as configSchema } from './governance-XIScatRO.js';
+import { C as ContextEngineConfig, L as LLMConfig, E as ExtractionConfig, R as RerankerConfig } from './config-CdlSkKgV.js';
+export { a as ContextEngineConfigInit, b as EmbeddingConfig, F as FusionConfig, G as GraphConfig, S as StorageConfig } from './config-CdlSkKgV.js';
+import { H as Hooks, R as RedactionPolicy, U as UsageEvent, P as ProgressEvent, I as IngestReport } from './redaction-BqD_DEUQ.js';
+export { D as DocumentReport, a as RedactionRule, b as RedactionRuleInit, c as applyRedaction, e as emitError, d as emitProgress, f as emitToolCall, g as emitUsage, h as graphUnits, u as unitsForFile } from './redaction-BqD_DEUQ.js';
+import { E as Embedder, S as StorageBackend, F as FetchImpl } from './storage-Dvt2ZxsV.js';
+export { C as ChunkRow, a as EmbedKind, P as PostgresBackend, b as SearchScope, c as buildEmbedder } from './storage-Dvt2ZxsV.js';
+import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-XFVgtEdV.js';
+export { c as ToolKind, d as configSchema } from './governance-XFVgtEdV.js';
 export { createMcpApp } from './mcp.js';
 import 'zod';
 import 'node:http';
 
-interface ChunkRow {
-    idx: number;
-    text: string;
-    lang?: string | null;
-    embedding?: number[] | null;
-    meta?: Record<string, unknown>;
-}
-interface SearchScope {
-    sourceIds?: string[] | null;
-    principals?: string[] | null;
-    limit?: number;
-}
-interface StorageBackend {
-    supportsFts: boolean;
-    supportsTrgm: boolean;
-    supportsAnn: boolean;
-    upsertChunks(documentId: string, sourceId: string | null, acl: string[] | null, chunks: readonly ChunkRow[]): Promise<number>;
-    deleteChunks(documentId: string): Promise<void>;
-    updateChunkEmbeddings(documentId: string, vectors: readonly number[][]): Promise<number>;
-    updateChunkAcl(documentId: string, acl: string[] | null): Promise<number>;
-    filterIds(chunkIds: readonly string[], scope: SearchScope): Promise<string[]>;
-    ftsSearch(query: string, scope: SearchScope): Promise<string[]>;
-    trgmSearch(query: string, scope: SearchScope): Promise<string[]>;
-    annSearch(vector: readonly number[], scope: SearchScope): Promise<string[]>;
-}
-declare class PostgresBackend implements StorageBackend {
-    supportsFts: boolean;
-    supportsTrgm: boolean;
-    supportsAnn: boolean;
-    private readonly pool;
-    private readonly exactThresholdOverride;
-    /** Tri-state: null = not yet checked. */
-    private iterativeScan;
-    constructor(pool: Pool, exactThreshold?: number | null);
-    private get exactThreshold();
-    /**
-     * Bind values for SCOPE + the row limit.
-     * `principals` is passed through UNCHANGED: null (trusted) and [] (anonymous)
-     * mean different things.
-     */
-    private scopeParams;
-    upsertChunks(documentId: string, sourceId: string | null, acl: string[] | null, chunks: readonly ChunkRow[]): Promise<number>;
-    deleteChunks(documentId: string): Promise<void>;
-    updateChunkEmbeddings(documentId: string, vectors: readonly number[][]): Promise<number>;
-    updateChunkAcl(documentId: string, acl: string[] | null): Promise<number>;
-    filterIds(chunkIds: readonly string[], scope: SearchScope): Promise<string[]>;
-    ftsSearch(query: string, scope: SearchScope): Promise<string[]>;
-    trgmSearch(query: string, scope: SearchScope): Promise<string[]>;
-    /**
-     * Set pg_trgm's similarity threshold for this query via the `set_limit()` /
-     * `show_limit()` FUNCTIONS — never the GUC `pg_trgm.similarity_threshold`.
-     *
-     * The GUC is registered lazily, only once pg_trgm's shared library is loaded
-     * into the backend process. On a fresh pooled connection that has not yet
-     * run any pg_trgm operation, `SHOW pg_trgm.similarity_threshold` raises
-     * "unrecognized configuration parameter" — and because that error aborts the
-     * surrounding transaction, a fallback issued on the same connection then
-     * fails with "current transaction is aborted". Every connection a pool hands
-     * out is fresh, so this is the common case, not an edge case. Calling
-     * `set_limit()` loads the library and does not depend on the GUC. This
-     * mirrors the Python backend, which was hardened against exactly this.
-     *
-     * `set_limit()` is connection-scoped and survives COMMIT and the return to
-     * the pool, so the previous value is captured here and restored by the
-     * caller.
-     */
-    private applyTrgmThreshold;
-    private restoreTrgmLimit;
-    annSearch(vector: readonly number[], scope: SearchScope): Promise<string[]>;
-    private eligibleIsSmall;
-    private tuneAnnScan;
-    private scanBudget;
-    private enableIterativeScan;
-    private supportsIterativeScan;
-}
+/**
+ * Sentinels distinguishing omitted arguments from real values, including null.
+ *
+ * UNSET: "argument omitted" vs null (e.g. updateDocument acl=null means unrestricted).
+ * TRUSTED: trusted caller, ACL filtering disabled. Truthy on purpose so
+ * `if (principals)` does not treat a trusted caller as anonymous.
+ */
+declare const UNSET: unique symbol;
+type Unset = typeof UNSET;
+declare const TRUSTED: unique symbol;
+type Trusted = typeof TRUSTED;
+type Principals = string[] | null | typeof TRUSTED | undefined;
+declare function resolvePrincipals(value: Principals, method: string): string[] | null;
 
 type Mode$1 = "hybrid" | "graph";
 interface IngestRequest {
@@ -204,7 +142,7 @@ declare function compute(instruction: string, opts: {
     hooks: Hooks;
     sourceIds?: string[] | null;
     principals?: string[] | null;
-    docIds?: string[] | null;
+    documentIds?: string[] | null;
     modelCfg?: LLMConfig | null;
     timeout?: number;
 }): Promise<Record<string, unknown>>;
@@ -317,6 +255,7 @@ interface RunSearchOpts {
     embedder: Embedder;
     pool: Pool;
     sourceIds?: string[] | null;
+    documentIds?: string[] | null;
     principals?: string[] | null;
     topK?: number;
     mode?: Mode;
@@ -392,25 +331,6 @@ declare function redactHits(hits: Hit[], policy: RedactionPolicy, opts: {
  */
 declare function runSearch(query: string, opts: RunSearchOpts): Promise<SearchResult>;
 
-/**
- * Sentinels distinguishing omitted arguments from real values, including null.
- *
- * UNSET: "argument omitted" vs null (e.g. updateDocument acl=null means unrestricted).
- * TRUSTED: trusted caller, ACL filtering disabled. Truthy on purpose so
- * `if (principals)` does not treat a trusted caller as anonymous.
- */
-declare const UNSET: unique symbol;
-type Unset = typeof UNSET;
-declare class TrustedSentinel {
-    readonly [Symbol.toStringTag] = "TRUSTED";
-    toString(): string;
-    valueOf(): boolean;
-}
-declare const TRUSTED: TrustedSentinel;
-type Trusted = typeof TRUSTED;
-type Principals = string[] | null | typeof TRUSTED | undefined;
-declare function resolvePrincipals(value: Principals, method: string): string[] | null;
-
 /**
  * `ContextEngine` — the package's public object.
  *
@@ -439,6 +359,7 @@ declare class ContextEngine implements ToolEngine {
     constructor(config: ContextEngineConfig, opts?: {
         onUsage?: ((e: UsageEvent) => void) | null;
         onError?: ((e: unknown, ctx: Record<string, unknown>) => void) | null;
+        onProgress?: ((e: ProgressEvent) => void) | null;
     });
     private ensurePool;
     /** The embedding client, built on first use. */
@@ -486,6 +407,8 @@ declare class ContextEngine implements ToolEngine {
      */
     search(query: string, opts?: {
         sourceIds?: string[] | null;
+        /** Narrows WITHIN a source; INTERSECTS with `sourceIds`. */
+        documentIds?: string[] | null;
         principals?: Principals;
         topK?: number;
         mode?: "hybrid" | "graph";
@@ -539,7 +462,7 @@ declare class ContextEngine implements ToolEngine {
     compute(instruction: string, opts?: {
         sourceIds?: string[] | null;
         principals?: Principals;
-        docIds?: string[] | null;
+        documentIds?: string[] | null;
         modelCfg?: LLMConfig | null;
         timeout?: number;
     }): Promise<Record<string, unknown>>;
@@ -566,6 +489,9 @@ declare class ContextEngine implements ToolEngine {
         principals?: Principals;
         actor?: Record<string, unknown> | null;
         source?: string;
+        /** Opaque claim scope for approvals (e.g. a run id) — separate from
+         * `sourceId`. See `governance.executeTool`. */
+        approvalScope?: string | null;
     }): Promise<Record<string, unknown>>;
 }
 
@@ -576,6 +502,23 @@ declare class ContextEngine implements ToolEngine {
  * reported via `hooks.onError` and degrade to whatever partial text was recovered.
  */
 
+/**
+ * WHY a document came back with less text than it has, when the answer is
+ * actionable. Mirrors the Python client's `Extracted.unreadable_reason` —
+ * that docstring is the canonical rationale; only the value semantics are
+ * restated here:
+ *
+ * - `needs_vision`  — pages had no usable text layer and no vision model was
+ *   configured. FIXABLE by configuring one (the OCR fallback may have tried
+ *   and read nothing; a vision model is still the actionable upgrade).
+ * - `vision_failed` — a vision model was configured and produced nothing for
+ *   those pages. An ops problem, not a configuration one.
+ *
+ * `null` means nothing was lost — a page a reader READ and found empty is
+ * blank, not unreadable. A closed set on purpose (callers branch on it), and
+ * NOT an error channel; `mediaOnly` stays set alongside it for whole files.
+ */
+type UnreadableReason = "needs_vision" | "vision_failed";
 declare class Extracted {
     text: string;
     pages: number | null;
@@ -584,6 +527,10 @@ declare class Extracted {
     providerTokens: Record<string, number>;
     llmPictures: number;
     isMarkdown: boolean;
+    /** See `UnreadableReason`. `mediaOnly` is the same idea for whole files and
+     *  stays set alongside this, so existing callers keep working. */
+    unreadableReason: UnreadableReason | null;
+    unreadablePages: number;
     constructor(init: {
         text: string;
         pages?: number | null;
@@ -592,6 +539,8 @@ declare class Extracted {
         providerTokens?: Record<string, number>;
         llmPictures?: number;
         isMarkdown?: boolean;
+        unreadableReason?: UnreadableReason | null;
+        unreadablePages?: number;
     });
 }
 /**
@@ -601,6 +550,7 @@ declare class Extracted {
 declare function extract(content: Buffer, filename: string, mime: string | null, opts: {
     visionLlm?: LLMConfig | null;
     hooks: Hooks;
+    extraction?: ExtractionConfig | null;
 }): Promise<Extracted>;
 
 declare const DEFAULT_LEG_WEIGHT = 1;
@@ -620,7 +570,8 @@ declare function rrfFuse(rankedLists: Record<string, string[]>, opts: {
  * `callLlm(cfg, { system, user, jsonMode, images, client })` is the single entry
  * point. Returns `[text, { input, output }]`.
  *
- * Images are always PNG. 30s timeout, no retries. Injectable `client` / `fetch`.
+ * Images are always PNG. 240s call timeout (every provider), no retries.
+ * Injectable `client` / `fetch`.
  * `callLlm` owns and closes the client it builds unless one is passed in.
  */
 
@@ -660,6 +611,17 @@ type LlmCallOpts = {
     user: string;
     jsonMode?: boolean;
     images?: ImageBytes[] | null;
+    maxTokens?: number | null;
+    /** Reasoning tokens are drawn from `maxTokens`, so a caller that wants
+     * transcription rather than deliberation must be able to spend the whole
+     * budget on output. Omitted = the provider's default. Applied per provider
+     * capability: gemini and anthropic take it directly (anthropic thinking is
+     * opt-in, so 0 sends nothing and a positive budget drops `temperature` —
+     * the API rejects the combination); bedrock forwards a positive budget as
+     * the anthropic-style passthrough; the openai family has no portable
+     * thinking control. */
+    thinkingBudget?: number | null;
+    temperature?: number | null;
 };
 type LLMClientOpts = {
     client?: ChatClient | null;
@@ -817,6 +779,7 @@ interface ApprovalRecord {
     toolName: string;
     toolArgsFrozen: Record<string, unknown>;
     sourceId: string | null;
+    approvalScope: string | null;
     principals: unknown;
     status: string;
     approver: string | null;
@@ -835,7 +798,7 @@ type EngineLike = {
 };
 declare function shouldRequireApproval(ct: Pick<CanonicalTool, "requiresApproval" | "approvalPolicy">, args: Record<string, unknown>): boolean;
 declare function resolveApproval(engine: EngineLike, approvalId: string, decision: "approved" | "rejected", approver: string, meta?: Record<string, unknown> | null, opts?: {
-    principals?: string[] | null;
+    principals?: string[] | null | Trusted;
 }): Promise<ApprovalRecord>;
 
 /**
@@ -848,4 +811,4 @@ declare function functionTool(fn: (...args: never[]) => unknown): CanonicalTool;
 /** Bumped by CI on every main merge; 0.0.0 = pre-first-release. */
 declare const __version__ = "0.0.0";
 
-export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, type ChunkRow, CodeExecutionError, CodeExecutionTimeout, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, LLMClient, LLMConfig, PostgresBackend, type Principals, RedactionPolicy, RerankerConfig, type SearchResult, type SearchScope, type StorageBackend, TRUSTED, type TaskRunner, type TaskStatus, ToolConfig, type Trusted, UNSET, type Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, decryptDict, encryptDict, extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, resolvePrincipals, rrfFuse, runMigrate, runSearch, shouldRequireApproval, upsertRegistry };
+export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, ExtractionConfig, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, LLMClient, LLMConfig, type Principals, ProgressEvent, RedactionPolicy, RerankerConfig, type SearchResult, StorageBackend, TRUSTED, type TaskRunner, type TaskStatus, ToolConfig, type Trusted, UNSET, type Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, decryptDict, encryptDict, extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, resolvePrincipals, rrfFuse, runMigrate, runSearch, shouldRequireApproval, upsertRegistry };