albex 0.3.0 → 0.6.0

package/src/albex.ts

@@ -21,10 +21,12 @@ import {
   asAlbexPdfExports,
 } from './wasm-bindings.js';
 import {
+  AlbexError,
   AlbexInitError,
   AlbexUnsupportedFormatError,
   AlbexParseError,
   AlbexCapacityError,
+  type AlbexCapacityLimit,
 } from './errors.js';
 import {
   savePersisted,
@@ -32,7 +34,7 @@ import {
   deletePersisted,
   listPersisted,
 } from './persistence.js';
-import { detectProfile, pickTier, shouldUseGpu, type Tier, type DeviceProfile } from './profile.js';
+import { detectProfile, shouldUseGpu, type Tier, type DeviceProfile } from './profile.js';
 import { getResourceManager, type ResourceState } from './resource-manager.js';
 import { BloomGpu, packBloomsFromChunks } from './gpu/bloom-runtime.js';
 
@@ -96,6 +98,8 @@ export interface AlbexOptions {
    * Override the tier auto-detection. Pass `'auto'` (default), or an
    * explicit tier when you know the constraints of your target environment.
    */
+  /** @deprecated Removed in 0.5.0. Albex no longer has capacity tiers;
+   * pass `'auto'` or omit. Other values are accepted and ignored. */
   tier?: 'auto' | 'mini' | 'std' | 'pro';
   /**
    * SIMD selection. When `'auto'` (default), Albex probes for v128 support
@@ -201,57 +205,57 @@ export interface SearchStats {
   bitapMatched: number;
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Query parsing
-// ─────────────────────────────────────────────────────────────────────────────
-
-type SimpleQuery = { kind: 'simple'; tokens: string[] };
-type PhraseQuery = { kind: 'phrase'; tokens: string[]; raw: string };
-type OrQuery    = { kind: 'or';     branches: string[][] };
-type ParsedQuery = SimpleQuery | PhraseQuery | OrQuery;
-
-function tokenize(q: string): string[] {
-  return q.trim().split(/\s+/).filter(t => t.length > 0);
-}
-
-function parseQuery(q: string): ParsedQuery {
-  const trimmed = q.trim();
-
-  // OR: "term1 | term2" or "phrase one | phrase two"
-  if (trimmed.includes('|')) {
-    const branches = trimmed.split('|')
-      .map(p => tokenize(p.replace(/"/g, '')))
-      .filter(b => b.length > 0);
-    return { kind: 'or', branches };
-  }
-
-  // Phrase: "exact phrase here"
-  const phraseMatch = /^"(.+)"$/.exec(trimmed);
-  if (phraseMatch) {
-    const inner = phraseMatch[1] ?? '';
-    const tokens = tokenize(inner);
-    return { kind: 'phrase', tokens, raw: inner };
-  }
-
-  return { kind: 'simple', tokens: tokenize(trimmed) };
-}
-
 /**
- * Reconstruct a WASM-compatible query string from parsed tokens.
- * The WASM engine accepts up to 4 space-separated tokens (AND semantics).
+ * One structured warning recorded by the engine during indexFile or
+ * load. Replaces the pre-0.5.0 pattern of scattered `console.warn`
+ * calls. Inspect via `engine.takeDiagnostics()` after the operation.
  */
-function tokensToWasmQuery(tokens: string[]): string {
-  return tokens.slice(0, 4).join(' ');
+export interface AlbexDiagnostic {
+  /** Coarse kind. `'recovered'` means the engine handled the issue and
+   * kept going; `'skipped'` means content was dropped; `'fallback'` means
+   * an alternate code path was used (e.g. lopdf after pdf-extract trap). */
+  kind: 'recovered' | 'skipped' | 'fallback' | 'info';
+  /** Where in the pipeline this happened. Free-form short tag. */
+  stage: 'pdf' | 'ocr' | 'gpu' | 'persistence' | 'network';
+  /** Human-readable message safe to surface in a UI. */
+  message: string;
+  /** Optional file the issue belongs to. */
+  file?: string;
+  /** Optional page number (1-based for PDFs). */
+  page?: number;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Phrase post-filter
+// Query parsing (WASM-side as of 0.5.0)
 // ─────────────────────────────────────────────────────────────────────────────
+//
+// Pre-0.5.0 this file owned parseQuery + tokenize. That created two
+// truths about what a "token" was: one in TS for the query, one in Rust
+// for the indexed text. The audit flagged this as the biggest divergence
+// in the wrapper.
+//
+// 0.5.0 moves parseQuery/tokenize/tokensToWasmQuery to Rust. The TS
+// dispatcher reduces to:
+//
+//   1. Write the raw UTF-8 query bytes to the scratchpad.
+//   2. Call prepareQuery(len). Get back the kind (simple/phrase/or).
+//   3. For OR: iterate getQueryBranchCount() branches, calling
+//      selectQueryBranch(i) + search() for each, then merge in TS.
+//      For simple/phrase: selectQueryBranch(0) + search().
+//   4. For phrase: post-filter the snippets with containsPhrase().
+//
+// containsPhrase stays in TS because it operates on snippet text already
+// produced by the WASM, not on the query. It is not a tokenizer.
 
 /**
- * Returns true if `snippet` contains the phrase formed by `tokens` in order,
- * with at most `maxGap` characters between consecutive tokens.
- * Comparison is case- and accent-insensitive.
+ * Phrase post-filter. Returns true if `snippet` contains the phrase
+ * formed by `tokens` in order, with at most `maxGap` characters between
+ * consecutive tokens. Comparison is case- and accent-insensitive.
+ *
+ * The tokens come from the WASM-compiled pattern of a phrase branch,
+ * not from a TS re-tokenization of the query, so there is no
+ * tokenization divergence: WASM said "these are the tokens", we just
+ * check adjacency in the snippet.
  */
 function containsPhrase(snippet: string, tokens: string[], maxGap = 30): boolean {
   const norm = (s: string): string =>
@@ -392,32 +396,11 @@ function computePatternBloom(query: string): bigint {
   return bits;
 }
 
-function contentHash(bytes: Uint8Array): string {
-  // 64-bit arithmetic via two 32-bit halves (no BigInt to keep it fast in
-  // engines without optimised BigInt support).
-  let hi = 0xcbf29ce4 | 0;
-  let lo = 0x84222325 | 0;
-  // FNV prime: 0x100000001b3 = (0x100 << 32) | 0x000001b3
-  for (let i = 0; i < bytes.length; i++) {
-    lo ^= bytes[i]!;
-    // multiply by FNV prime
-    // (hi:lo) *= 0x100000001b3
-    // low * prime
-    const lo_lo = (lo & 0xffff) * 0x1b3;
-    const lo_hi = (lo >>> 16) * 0x1b3;
-    let new_lo  = (lo_lo + ((lo_hi & 0xffff) << 16)) | 0;
-    let carry   = (lo_hi >>> 16) + ((lo_lo + ((lo_hi & 0xffff) << 16)) > 0xffffffff ? 1 : 0);
-    // hi*prime + carry
-    const hi_lo = (hi & 0xffff) * 0x1b3;
-    const hi_hi = (hi >>> 16) * 0x1b3;
-    const new_hi = ((hi_lo + ((hi_hi & 0xffff) << 16)) | 0) + carry + lo; // + lo because high 33rd bit
-    lo = new_lo;
-    hi = new_hi | 0;
-  }
-  const hexHi = (hi >>> 0).toString(16).padStart(8, '0');
-  const hexLo = (lo >>> 0).toString(16).padStart(8, '0');
-  return hexHi + hexLo;
-}
+// Note: `contentHash` is implemented as a method on AlbexEngine below
+// (it needs access to the WASM scratchpad). The standalone TS reference
+// implementation that used to live here was removed in 0.4.0 — the
+// canonical hash now lives in wasm/src/lib.rs::hashBytes so there is
+// exactly one definition of "the content hash of these bytes".
 
 /**
  * 16-hex-char content hash → 8 raw bytes for setDocumentContentHash. The
@@ -612,11 +595,20 @@ function makePdfWasmImports(
       case '__wbindgen_externref_table_set_null':
         return (idx: number) => { heap[idx] = undefined; };
     }
-    // Unknown import — return a stub that warns when called. Loading still
-    // succeeds; only an actually-invoked unknown import will surface.
-    return (...args: unknown[]) => {
-      console.warn(`[albex] unhandled PDF WASM import ${modName}.${name}`, args);
-    };
+    // Unknown import — fail fast. An import we don't recognise means the
+    // wasm-bindgen / lopdf / getrandom dependency graph has drifted from
+    // the prefixes this loader is written to satisfy. Accepting the
+    // module would defer the failure to an arbitrary execution path,
+    // typically deep inside extractPdf(), where the user gets either a
+    // hang or a misleading "PDF parse error". Refusing instantiation
+    // surfaces the version skew at boot, where the maintainer can act
+    // on it.
+    throw new AlbexInitError(
+      `Unknown PDF WASM import "${modName}.${name}". ` +
+      `The albex_pdf.wasm binary was probably built with a newer Rust ` +
+      `toolchain or dependency graph than this loader was written for. ` +
+      `Rebuild with 'npm run build:pdf-wasm' or open an issue.`,
+    );
   };
 
   const imports: Record<string, Record<string, unknown>> = {};
@@ -647,6 +639,39 @@ export interface OcrAttachedOptions {
   hint?: string;
 }
 
+/**
+ * Contract the engine accepts from an OCR plugin. `@albex/ocr` is the
+ * canonical implementation, but any module that satisfies this interface
+ * can be attached via `engine.attachOcr(adapter)`.
+ */
+export interface OcrAdapter {
+  /** Invoked by the engine to OCR a single image. Receives whatever the
+   * caller passes (Blob, ArrayBuffer, etc.); the adapter is responsible
+   * for accepting that input. Must return text + confidence. */
+  recognize(image: unknown, opts?: OcrAttachedOptions): Promise<OcrAttachedResult>;
+
+  /** Engine-side switches the adapter wants honoured. The only one
+   * defined today is `alwaysExtractEmbeddedImages`, which turns on the
+   * hybrid PDF OCR pass. New flags can be added without breaking the
+   * adapter interface. */
+  options?: {
+    /** When true, every PDF (native or scanned) is walked for embedded
+     * images and each qualifying image is sent to `recognize`. Off by
+     * default to keep performance predictable on native PDFs. */
+    alwaysExtractEmbeddedImages?: boolean;
+  };
+}
+
+/** Returned by `attachOcr`. Holds the lifecycle handles for the plugin.
+ * Calling `dispose()` removes the adapter from the engine; subsequent
+ * `engine.ocrImage` access returns `undefined` again. */
+export interface OcrHandle {
+  /** Detach the plugin and tear down any resources it holds. After this,
+   * the engine reverts to "no OCR" — scanned PDFs go back to registering
+   * with zero chunks. */
+  dispose(): Promise<void>;
+}
+
 export class AlbexEngine {
   // ── main WASM ──
   private _wasm!: AlbexWasmExports;
@@ -658,23 +683,20 @@ export class AlbexEngine {
    * runtime dependency on OCR — this is a structural slot that the optional
    * companion package fills.
    */
-  ocrImage?: (image: unknown, opts?: OcrAttachedOptions) => Promise<OcrAttachedResult>;
-
   /**
-   * Optional OCR-side configuration set by `@albex/ocr::enableOcr`. Read
-   * by the engine to decide whether to invoke OCR on top of the text it
-   * already extracted from a PDF (hybrid PDFs: native text + images that
-   * also contain text, like stamps, scanned annexes, or diagrams with
-   * labels).
-   *
-   * When `alwaysExtractEmbeddedImages` is true, every page of every PDF
-   * passes through `extractPageImages` after the normal text extraction;
-   * any image that meets the size filter (200×200 in Rust) is fed to
-   * `ocrImage`. Performance cost: 1–3 s per qualifying image.
-   *
-   * Off by default — set this opt-in via the OCR module's options.
+   * Public OCR entry point. Forwards to the attached OCR adapter installed
+   * via `attachOcr()`. Reading this property is a feature-detect for
+   * integrators: `if (engine.ocrImage) { ... OCR available ... }`. Writing
+   * to it directly is no longer supported in 0.5.0+ — use `attachOcr`.
    */
-  ocrConfig?: { alwaysExtractEmbeddedImages?: boolean };
+  get ocrImage(): ((image: unknown, opts?: OcrAttachedOptions) => Promise<OcrAttachedResult>) | undefined {
+    return this._ocrAdapter?.recognize;
+  }
+
+  /** Private adapter slot. Holds the OCR plugin contract installed by
+   * `attachOcr()`. The engine reads `recognize` and `options` here; the
+   * caller never gets a reference to this object directly. */
+  private _ocrAdapter: OcrAdapter | null = null;
 
   // ── PDF WASM (lazy) ──
   private _pdfWasm: AlbexPdfExports | null = null;
@@ -682,6 +704,11 @@ export class AlbexEngine {
 
   private _docs: IndexedDocument[] = [];
   private _lastSearch: SearchStats | null = null;
+  /** Structured diagnostics collected during the most recent operation.
+   * Drained by `takeDiagnostics()`. Capped at 256 entries to avoid
+   * unbounded memory growth in pathological cases (very corrupted
+   * corpora producing thousands of recovery warnings). */
+  private _diagnostics: AlbexDiagnostic[] = [];
   private _tier: Tier | null = null;
   private _simd: boolean = false;
   private _profile: DeviceProfile | null = null;
@@ -691,10 +718,55 @@ export class AlbexEngine {
   private _unsubscribeResources: (() => void) | null = null;
   private readonly _opts: AlbexOptions;
 
+  // ── Concurrency guard ──────────────────────────────────────────────────────
+  // One WASM instance, global mutable state, async ops that yield to the
+  // scheduler between slices. Two overlapping operations corrupt each other
+  // (e.g. a fresh searchBegin resets the cursor of an in-flight cooperative
+  // search). Async ops serialize through `_opChain`; sync mutators/searches
+  // assert the engine is idle (audit 0.6.0, finding #2).
+  private _opChain: Promise<unknown> = Promise.resolve();
+  private _busy = false;
+
   constructor(opts: AlbexOptions) {
     this._opts = opts;
   }
 
+  /** Serialize an async engine operation behind any in-flight one. */
+  private _exclusive<T>(fn: () => Promise<T>): Promise<T> {
+    const run = this._opChain.then(async () => {
+      this._busy = true;
+      try { return await fn(); }
+      finally { this._busy = false; }
+    });
+    // Swallow result/error on the chain so one failure can't wedge the queue.
+    this._opChain = run.then(() => undefined, () => undefined);
+    return run as Promise<T>;
+  }
+
+  /** Guard a synchronous mutator/search: refuse to run mid-async-operation
+   * rather than silently corrupt the shared WASM state. */
+  private _assertIdle(method: string): void {
+    if (this._busy) {
+      throw new AlbexError(
+        'busy',
+        `${method}() was called while an async engine operation is still ` +
+        `running. Await the previous indexFile/save/load/replaceDocument/` +
+        `searchCooperative call, or use searchCooperative instead of search().`,
+      );
+    }
+  }
+
+  /** Compact opportunistically when tombstones pile up under text pressure,
+   * so repeated removeDocument/replaceDocument don't exhaust the pool. */
+  private _autoCompactIfNeeded(): void {
+    const w = this._wasm;
+    const cap = w.getTextCapacity();
+    const hasTombstones = w.getDocCount() > this._docs.length;
+    if (hasTombstones && cap > 0 && w.getTextUsed() / cap > 0.85) {
+      w.compact();
+    }
+  }
+
   /** Load and initialise the main WASM module. Must be called before any other method. */
   async init(): Promise<void> {
     const url = await this._resolveWasmUrl();
@@ -754,29 +826,28 @@ export class AlbexEngine {
     // as an asset reference. They copy the .wasm to the output directory and
     // rewrite the URL automatically. Consumers who use one of those bundlers
     // get a working `new AlbexEngine()` with no manual setup.
-    if (!o.wasmBaseUrl) {
-      // We can't tier-select with one URL, so fall back to std baseline.
-      // The integrator who wants tier optimisation must opt in via wasmBaseUrl.
-      this._tier = 'std';
-      this._simd = false;
-      return new URL('../wasm/pkg/albex_wasm_bg.wasm', import.meta.url).href;
-    }
-
-    let tier: Tier;
-    if (o.tier && o.tier !== 'auto') tier = o.tier;
-    else                             tier = pickTier(profile);
-    this._tier = tier;
-
+    // 0.5.0+: two main binaries only — baseline and SIMD. The tier
+    // system is gone (audit 4.1). Selection collapses to a single
+    // boolean: SIMD on or off, decided either by the explicit `simd`
+    // option or by a runtime probe.
     const simd = o.simd === 'on'
       ? true
       : o.simd === 'off'
         ? false
         : !!profile?.wasm.simd;
     this._simd = simd;
+    this._tier = 'std';
+
+    if (!o.wasmBaseUrl) {
+      // Zero-config: bundler resolves the .wasm next to dist/. We only
+      // ship the baseline alias (albex_wasm_bg.wasm) inside the npm
+      // package; integrators who want SIMD must serve both binaries
+      // themselves via `wasmBaseUrl`.
+      return new URL('../wasm/pkg/albex_wasm_bg.wasm', import.meta.url).href;
+    }
 
-    const suffix = simd ? `${tier}_simd` : tier;
     const base = o.wasmBaseUrl.replace(/\/+$/, '');
-    return `${base}/albex_wasm_${suffix}.wasm`;
+    return simd ? `${base}/albex_wasm_simd.wasm` : `${base}/albex_wasm.wasm`;
   }
 
   /** The tier that was actually loaded. `null` until `init()` resolves. */
@@ -887,6 +958,35 @@ export class AlbexEngine {
     }
   }
 
+  /**
+   * Compute the FNV-1a 64-bit content hash of `bytes` via the WASM
+   * streaming API. Returns a 16-character hex string identical in shape
+   * to what the TS implementation in 0.3.x returned, so all callers
+   * stay unchanged. Single source of truth — same hash whether we use
+   * it for indexFile dedup, for snapshot v2 persistence, or anywhere
+   * else. Large inputs are chunked at FEED_SIZE just like _feedText.
+   */
+  private _contentHash(bytes: Uint8Array): string {
+    const w = this._wasm;
+    w.hashBegin();
+    for (let i = 0; i < bytes.length; i += FEED_SIZE) {
+      const c = bytes.subarray(i, i + FEED_SIZE);
+      this._writePad(c);
+      w.hashFeed(c.length);
+    }
+    w.hashFinish();
+    // Read 8 result bytes back from scratchpad[0..8].
+    const ptr = w.getBuffer(8);
+    const out = this._u8(ptr, 8);
+    // Big-endian to hex. Same layout as the old hexHi + hexLo output:
+    // high u32 first (4 bytes), low u32 second (4 bytes).
+    let s = '';
+    for (let i = 0; i < 8; i++) {
+      s += out[i]!.toString(16).padStart(2, '0');
+    }
+    return s;
+  }
+
   private _feedXmlBytes(xml: Uint8Array, fn: 'feedXmlBytes' | 'feedXlsxBytes'): void {
     const feeder = this._wasm[fn];
     for (let i = 0; i < xml.length; i += FEED_SIZE) {
@@ -910,7 +1010,10 @@ export class AlbexEngine {
     // called when the user actually drops a PDF — but we issue a console
     // hint so embedders can surface a "this will download ~1 MB" prompt.
     if (this._resources?.constrainedNetwork) {
-      console.info('[albex] downloading PDF WASM (~1 MB) on a constrained network connection');
+      this._diag({
+        kind: 'info', stage: 'network',
+        message: 'Downloading PDF WASM (~1 MB) on a constrained network connection',
+      });
     }
     const res = await fetch(pdfUrl);
     if (!res.ok) throw new AlbexInitError(`Failed to fetch PDF WASM: ${res.status}`);
@@ -1046,21 +1149,14 @@ export class AlbexEngine {
       this._wasm.flushParagraph();
     }
 
-    // Hybrid OCR pass: when the OCR module is wired with
-    // `alwaysExtractEmbeddedImages: true`, also walk every page for
-    // embedded images and OCR them on top of the vector text.
-    //
-    // We always log the decision so users debugging "why isn't OCR
-    // firing on my hybrid PDF" can see which precondition failed.
-    const hybridOn = !!this.ocrConfig?.alwaysExtractEmbeddedImages;
-    const hasOcr   = !!this.ocrImage;
-    const binSupportsImages = typeof pw.extractPageImages === 'function'
-                            && typeof pw.getPageCount === 'function';
-    console.log(`[albex] hybrid OCR decision: ocrImage=${hasOcr} ocrConfig.alwaysExtractEmbeddedImages=${hybridOn} binarySupportsImages=${binSupportsImages}`);
-
-    if (hasOcr && hybridOn && binSupportsImages) {
+    // Hybrid OCR pass: when the OCR adapter is wired with
+    // `options.alwaysExtractEmbeddedImages: true`, also walk every page
+    // for embedded images and OCR them on top of the vector text.
+    if (this._ocrAdapter
+        && this._ocrAdapter.options?.alwaysExtractEmbeddedImages
+        && typeof pw.extractPageImages === 'function'
+        && typeof pw.getPageCount === 'function') {
       const totalPages = pw.getPageCount();
-      console.log(`[albex] hybrid OCR pass starting over ${totalPages} page(s)`);
       for (let p = 0; p < totalPages; p++) {
         const ocrText = await this._ocrPageEmbeddedImages(pw, p);
         if (ocrText === null) break; // WASM trapped, stop hybrid pass.
@@ -1148,7 +1244,10 @@ export class AlbexEngine {
       // so `_ensurePdfWasm` re-instantiates on the next call.
       this._pdfWasm = null;
       this._pdfMem  = null;
-      console.warn(`[albex] PDF image extractor trapped on page ${page + 1}: ${e instanceof Error ? e.message : String(e)}. Stopping OCR.`);
+      this._diag({
+        kind: 'skipped', stage: 'pdf', page: page + 1,
+        message: `PDF image extractor trapped: ${e instanceof Error ? e.message : String(e)}. Remaining pages skipped.`,
+      });
       return null;
     }
     if (imageCount <= 0) return '';
@@ -1174,16 +1273,6 @@ export class AlbexEngine {
       copy.set(new Uint8Array(liveMem.buffer, ptr, len));
       const blob = new Blob([copy.buffer as ArrayBuffer], { type: mime });
 
-      // Defensive diagnostics: when an OCR call goes wrong (Tesseract
-      // worker abort, malformed JPEG, etc.) the first thing we want to
-      // see is whether we even handed it valid image bytes. A real JPEG
-      // starts with FF D8 FF (E0 for JFIF, E1 for EXIF). A JPEG2000
-      // starts with 00 00 00 0C 6A 50 20 20.
-      const magic = Array.from(copy.subarray(0, 4))
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join(' ');
-      console.log(`[albex] OCR page ${page + 1} image ${i + 1}/${imageCount}: kind=${kind} (${mime}) len=${len} bytes magic=${magic}`);
-
       try {
         const { text } = await ocr(blob);
         const trimmed = text?.trim();
@@ -1197,7 +1286,10 @@ export class AlbexEngine {
         // "Aborted(-1)") are also caught here; if they bypass the
         // promise rejection and surface as `uncaught` instead, the
         // demo's window.onerror handler will keep the app alive.
-        console.warn(`[albex] OCR failed on page ${page + 1} image ${i + 1}: ${e instanceof Error ? e.message : String(e)}`);
+        this._diag({
+          kind: 'skipped', stage: 'ocr', page: page + 1,
+          message: `OCR failed on image ${i + 1}: ${e instanceof Error ? e.message : String(e)}`,
+        });
       }
     }
 
@@ -1242,7 +1334,10 @@ export class AlbexEngine {
       inPtr = pw.allocInput(bytes.length);
       new Uint8Array(pw.memory.buffer, inPtr, bytes.length).set(bytes);
     } catch (e) {
-      console.warn(`[albex] PDF re-load after extractor crash failed: ${e instanceof Error ? e.message : String(e)}`);
+      this._diag({
+        kind: 'skipped', stage: 'pdf',
+        message: `PDF re-load after extractor crash failed: ${e instanceof Error ? e.message : String(e)}`,
+      });
       return null;
     }
 
@@ -1252,7 +1347,10 @@ export class AlbexEngine {
     // first page, no paragraphs are emitted and we end up with 0 chunks.
     this._wasm.setDocumentName(this._writeStr(file.name));
     this._wasm.beginDocument();
-    console.info(`[albex] pdf-extract failed (${originalError}); attempting OCR-only fallback via lopdf for ${file.name}`);
+    this._diag({
+      kind: 'fallback', stage: 'pdf', file: file.name,
+      message: `pdf-extract failed (${originalError}); attempting OCR-only fallback via lopdf`,
+    });
     await this._indexPdfScanned(pw);
     return this._wasm.endDocument();
   }
@@ -1657,6 +1755,10 @@ export class AlbexEngine {
    * Throws for unsupported formats or parse errors.
    */
   async indexFile(file: File): Promise<IndexedDocument> {
+    return this._exclusive(() => this._indexFileInner(file));
+  }
+
+  private async _indexFileInner(file: File): Promise<IndexedDocument> {
     const ext = file.name.split('.').pop()?.toLowerCase() ?? '';
     const indexer = AlbexEngine._INDEXERS[ext];
     if (!indexer) throw new AlbexUnsupportedFormatError(ext);
@@ -1664,7 +1766,7 @@ export class AlbexEngine {
     // Hash the source bytes for idempotency. We always read the bytes once
     // here so the indexer can reuse them — avoids a double File.arrayBuffer().
     const bytes = new Uint8Array(await file.arrayBuffer());
-    const hash  = contentHash(bytes);
+    const hash  = this._contentHash(bytes);
 
     // Idempotency: if a non-deleted doc already has this hash, return it
     // unchanged. Cheap O(N) scan since MAX_DOCS = 128.
@@ -1689,6 +1791,30 @@ export class AlbexEngine {
     }
 
     const chunks  = await indexer(this, file, bytes);
+
+    // Capacity check (0.6.0). The WASM pools fill silently and break out of
+    // their ingest loops; getLastIndexOverflow reports which one filled.
+    // Surface a typed error instead of returning a half-indexed document the
+    // caller cannot tell apart from a complete one (audit finding #3).
+    const overflow = w.getLastIndexOverflow();
+    if (overflow !== 0) {
+      const which: AlbexCapacityLimit =
+        (overflow & 1) ? 'chunks' : (overflow & 2) ? 'text'
+        : (overflow & 4) ? 'docs' : 'names';
+      const pools = [
+        overflow & 1 ? 'chunk pool' : '',
+        overflow & 2 ? 'text pool' : '',
+        overflow & 4 ? 'document table' : '',
+        overflow & 8 ? 'name pool' : '',
+      ].filter(Boolean).join(', ');
+      throw new AlbexCapacityError(
+        `Index capacity exceeded while indexing "${file.name}" (${pools} full). ` +
+        `The document was rolled back (not indexed); treat the index as full ` +
+        `(compact(), shard across an AlbexPool, or reset()).`,
+        which,
+      );
+    }
+
     // The new doc occupies slot `docCountBefore`.
     const docId   = w.getDocId(docCountBefore);
 
@@ -1713,6 +1839,11 @@ export class AlbexEngine {
    * Returns `true` if a matching document was found and tombstoned.
    */
   removeDocument(id: string): boolean {
+    this._assertIdle('removeDocument');
+    return this._removeDocumentInner(id);
+  }
+
+  private _removeDocumentInner(id: string): boolean {
     const doc = this._docs.find(d => d.name === id || d.contentHash === id);
     if (!doc) return false;
     const ok = this._wasm.removeDocument(doc.docId) === 1;
@@ -1728,12 +1859,15 @@ export class AlbexEngine {
    * idempotency check (so re-indexing the *same* bytes after a remove works).
    */
   async replaceDocument(name: string, newFile: File): Promise<IndexedDocument> {
-    this.removeDocument(name);
-    // Force a unique-hash path by indexing directly; if the new file happens
-    // to hash identically to a still-tracked document, the dedupe in
-    // indexFile will return that one. The remove above prevents the
-    // common case.
-    return this.indexFile(newFile);
+    return this._exclusive(async () => {
+      this._removeDocumentInner(name);
+      // Index directly via the inner path (we already hold the lock).
+      const doc = await this._indexFileInner(newFile);
+      // Repeated replaces leave tombstones in the text pool; reclaim under
+      // pressure so the pool isn't silently exhausted (audit finding #7).
+      this._autoCompactIfNeeded();
+      return doc;
+    });
   }
 
   /**
@@ -1744,6 +1878,7 @@ export class AlbexEngine {
    * references (e.g. in a UI) remain valid.
    */
   compact(): void {
+    this._assertIdle('compact');
     this._wasm.compact();
   }
 
@@ -1757,19 +1892,35 @@ export class AlbexEngine {
    * markers instead of full chunk text. Defaults: 60 bytes before, 120 after.
    */
   search(query: string, opts: SearchOptions = {}): SearchResult[] {
-    const parsed = parseQuery(query);
-
-    if (parsed.kind === 'or') {
-      return this._searchOr(parsed.branches, query, opts);
+    this._assertIdle('search');
+    const w = this._wasm;
+    const ql = this._writeStr(query);
+    const kind = w.prepareQuery(ql);
+    if (kind < 0) return [];
+
+    if (kind === 2) {
+      // OR: iterate branches and merge in TS. WASM stores compiled
+      // branches internally so we never re-tokenize on the host.
+      return this._searchOr(query, opts);
     }
 
-    const results = this._runSearch(tokensToWasmQuery(parsed.tokens), query, opts);
-
-    if (parsed.kind === 'phrase') {
-      return results.filter(r => containsPhrase(r.snippet, parsed.tokens));
-    }
+    w.selectQueryBranch(0);
+    // Phrase queries (kind 1) post-filter on adjacency. Pass the tokens down
+    // so the check runs against the FULL chunk text, not a cropped windowed
+    // snippet — otherwise `{ windowed: true }` could drop a valid phrase hit
+    // whose second term fell outside the window (audit finding #7).
+    const phraseTokens = kind === 1 ? this._branchTokens(0) : undefined;
+    return this._runSearch(query, opts, phraseTokens);
+  }
 
-    return results;
+  /** Read the WASM-compiled tokens of branch `i` for phrase post-filter.
+   * The bytes returned are exactly what the WASM tokenizer produced —
+   * no TS re-tokenization. */
+  private _branchTokens(i: number): string[] {
+    const n = this._wasm.getQueryBranchPattern(i);
+    if (n === 0) return [];
+    const pattern = this._readPad(n);
+    return pattern.split(' ').filter(t => t.length > 0);
   }
 
   /**
@@ -1787,34 +1938,42 @@ export class AlbexEngine {
    * Pass `opts.frameBudgetMs` to control the slice size (default 8 ms).
    */
   async *searchCooperative(query: string, opts: SearchOptions = {}): AsyncIterable<SearchResult> {
-    const parsed = parseQuery(query);
+    // Collect under the exclusivity lock so no other engine op interleaves at
+    // a slice boundary; the per-slice scheduler yields still happen inside.
+    const results = await this._exclusive(() => this._searchCooperativeCollect(query, opts));
+    for (const r of results) yield r;
+  }
+
+  /** Materialise a cooperative search to a sorted result array. Runs inside
+   * the exclusivity lock. Frame-budget yielding lives in _runSearchBudgeted. */
+  private async _searchCooperativeCollect(query: string, opts: SearchOptions): Promise<SearchResult[]> {
     const budget = opts.frameBudgetMs ?? 8;
     const w = this._wasm;
 
-    // OR queries: run each branch as its own resumable search, dedup, sort.
-    if (parsed.kind === 'or') {
+    const ql = this._writeStr(query);
+    const kind = w.prepareQuery(ql);
+    if (kind < 0) return [];
+
+    if (kind === 2) {
+      // OR branches — run each as its own resumable search and merge.
       const seen = new Set<string>();
       const all: SearchResult[] = [];
-      for (const tokens of parsed.branches) {
-        const q = tokensToWasmQuery(tokens);
-        if (!q) continue;
-        const r = await this._runSearchBudgeted(q, query, opts, budget);
+      const n = w.getQueryBranchCount();
+      for (let i = 0; i < n; i++) {
+        w.selectQueryBranch(i);
+        const r = await this._runSearchBudgeted(query, opts, budget, undefined, i);
         for (const x of r) {
           const key = `${x.documentName}:${x.location}:${x.matchStart}`;
           if (!seen.has(key)) { seen.add(key); all.push(x); }
         }
       }
       all.sort((a, b) => b.score - a.score);
-      for (const r of all) yield r;
-      return;
+      return all;
     }
 
-    const results = await this._runSearchBudgeted(tokensToWasmQuery(parsed.tokens), query, opts, budget);
-    const filtered = parsed.kind === 'phrase'
-      ? results.filter(r => containsPhrase(r.snippet, parsed.tokens))
-      : results;
-    for (const r of filtered) yield r;
-    void w;
+    w.selectQueryBranch(0);
+    const phraseTokens = kind === 1 ? this._branchTokens(0) : undefined;
+    return this._runSearchBudgeted(query, opts, budget, phraseTokens, 0);
   }
 
   /**
@@ -1838,14 +1997,19 @@ export class AlbexEngine {
    * may eat the entire budget, which is also fine.
    */
   private async _runSearchBudgeted(
-    wasmQuery: string,
     displayQuery: string,
     opts: SearchOptions,
     budgetMs: number,
+    phraseTokens?: string[],
+    branchIdx = 0,
   ): Promise<SearchResult[]> {
     const w = this._wasm;
-    const ql = this._writeStr(wasmQuery);
-    w.setPattern(ql);
+    // Pattern is already set by the caller via selectQueryBranch(branchIdx).
+    // Snapshot THAT branch's compiled pattern for the GPU pre-filter hash —
+    // not branch 0, which would build the wrong candidate mask for OR
+    // branches and silently drop their hits (audit finding #6).
+    const activePatternLen = w.getQueryBranchPattern(branchIdx);
+    const activePattern = activePatternLen > 0 ? this._readPad(activePatternLen) : '';
 
     // GPU pre-filter (CD1). If enabled AND the corpus is large enough,
     // the GPU computes the candidate bitset and we install it into WASM
@@ -1853,10 +2017,13 @@ export class AlbexEngine {
     // Failure here is silent: we fall back to CPU-only Bloom transparently.
     if (this._shouldEngageGpu()) {
       try {
-        await this._gpuPreFilter(wasmQuery);
+        await this._gpuPreFilter(activePattern);
       } catch (e) {
         // Don't let a GPU hiccup kill the search — drop to CPU path.
-        console.warn('[albex] GPU pre-filter failed; falling back to CPU:', e);
+        this._diag({
+          kind: 'fallback', stage: 'gpu',
+          message: `GPU pre-filter failed; falling back to CPU: ${e instanceof Error ? e.message : String(e)}`,
+        });
         w.clearCandidateMask();
       }
     }
@@ -1912,18 +2079,30 @@ export class AlbexEngine {
       bitapMatched: w.getStatBitapMatched(),
     };
 
-    return this._collectResults(count, opts);
+    return this._collectResults(count, opts, phraseTokens);
   }
 
-  /** Materialise results [0..count) into the public SearchResult shape. */
-  private _collectResults(count: number, opts: SearchOptions): SearchResult[] {
+  /** Materialise results [0..count) into the public SearchResult shape.
+   * When `phraseTokens` is given, each result is kept only if those tokens
+   * appear adjacently in the FULL chunk text — independent of any display
+   * windowing — so phrase queries stay correct under `{ windowed: true }`. */
+  private _collectResults(count: number, opts: SearchOptions, phraseTokens?: string[]): SearchResult[] {
     const w = this._wasm;
     const windowed = opts.windowed === true;
     const before   = opts.before ?? 60;
     const after    = opts.after  ?? 120;
+    const phraseFilter = phraseTokens && phraseTokens.length > 0 ? phraseTokens : null;
 
     const results: SearchResult[] = [];
     for (let i = 0; i < count; i++) {
+      // Phrase adjacency check against the full chunk text (getSnippet), not
+      // the possibly-cropped display window.
+      if (phraseFilter) {
+        const fl = w.getSnippet(i);
+        const full = fl > 0 ? this._readPad(fl) : '';
+        if (!containsPhrase(full, phraseFilter)) continue;
+      }
+
       const score      = w.getResultScore(i);
       const location   = w.getResultLocation(i);
       const matchStart = w.getResultStart(i);
@@ -1973,29 +2152,32 @@ export class AlbexEngine {
     return results;
   }
 
-  private _searchOr(branches: string[][], rawQuery: string, opts: SearchOptions): SearchResult[] {
+  /** Run all OR branches and merge dedup-by-(doc, location, match). The
+   * branches are already compiled inside the WASM (by prepareQuery); we
+   * iterate them with selectQueryBranch. The "rawQuery" param is kept
+   * only for the lastSearch.query field. */
+  private _searchOr(rawQuery: string, opts: SearchOptions): SearchResult[] {
+    const w = this._wasm;
     const seen = new Set<string>();
     const all: SearchResult[] = [];
-
-    for (const tokens of branches) {
-      const q = tokensToWasmQuery(tokens);
-      if (!q) continue;
-      const results = this._runSearch(q, rawQuery, opts);
+    const n = w.getQueryBranchCount();
+    for (let i = 0; i < n; i++) {
+      w.selectQueryBranch(i);
+      const results = this._runSearch(rawQuery, opts);
       for (const r of results) {
         const key = `${r.documentName}:${r.location}:${r.matchStart}`;
         if (!seen.has(key)) { seen.add(key); all.push(r); }
       }
     }
-
-    // Re-rank the merged list by score descending.
     all.sort((a, b) => b.score - a.score);
     return all;
   }
 
-  private _runSearch(wasmQuery: string, displayQuery: string, opts: SearchOptions): SearchResult[] {
+  /** Execute a single search using whichever query branch is currently
+   * active (set via selectQueryBranch). Returns the materialised
+   * SearchResult[]. Caller is responsible for activating a branch first. */
+  private _runSearch(displayQuery: string, opts: SearchOptions, phraseTokens?: string[]): SearchResult[] {
     const w  = this._wasm;
-    const ql = this._writeStr(wasmQuery);
-    w.setPattern(ql);
 
     const t0    = performance.now();
     const count = w.search();
@@ -2010,63 +2192,7 @@ export class AlbexEngine {
       bitapMatched: w.getStatBitapMatched(),
     };
 
-    const windowed = opts.windowed === true;
-    const before   = opts.before ?? 60;
-    const after    = opts.after  ?? 120;
-
-    const results: SearchResult[] = [];
-    for (let i = 0; i < count; i++) {
-      const score      = w.getResultScore(i);
-      const location   = w.getResultLocation(i);
-      const matchStart = w.getResultStart(i);
-      const matchEnd   = w.getResultEnd(i);
-      const nl         = w.getResultDocName(i);
-      const name       = nl > 0 ? this._readPad(nl) : '?';
-
-      const matchCount = w.getResultMatchCount(i);
-      const matches: MatchSpan[] = [];
-      for (let k = 0; k < matchCount; k++) {
-        matches.push({ start: w.getResultMatchStartAt(i, k), end: w.getResultMatchEndAt(i, k) });
-      }
-      if (matches.length === 0) {
-        matches.push({ start: matchStart, end: matchEnd });
-      }
-
-      let snippet: string;
-      let primaryStart = matchStart;
-      let primaryEnd   = matchEnd;
-      let adjustedMatches: MatchSpan[] = matches;
-
-      if (windowed) {
-        const sl = w.getSnippetWindow(i, before, after);
-        snippet = sl > 0 ? this._readPad(sl) : '';
-        const offset = w.getSnippetWindowOffset();
-        // Spans came back chunk-relative; shift them into window-relative.
-        // Account for leading "... " prefix when present.
-        const leadingPrefix = offset > 0 ? 4 : 0;
-        const shift = leadingPrefix - offset;
-        adjustedMatches = matches.map(m => ({
-          start: Math.max(0, m.start + shift),
-          end:   Math.max(0, m.end   + shift),
-        }));
-        primaryStart = adjustedMatches[0]?.start ?? 0;
-        primaryEnd   = adjustedMatches[0]?.end   ?? 0;
-      } else {
-        const sl = w.getSnippet(i);
-        snippet = sl > 0 ? this._readPad(sl) : '';
-      }
-
-      results.push({
-        documentName: name,
-        location,
-        score,
-        snippet,
-        matchStart: primaryStart,
-        matchEnd:   primaryEnd,
-        matches:    adjustedMatches,
-      });
-    }
-    return results;
+    return this._collectResults(count, opts, phraseTokens);
   }
 
   /** Returns current engine statistics. */
@@ -2127,9 +2253,93 @@ export class AlbexEngine {
 
   /** Full reset — clears all indexed documents and chunks. */
   reset(): void {
+    this._assertIdle('reset');
+    this._resetInner();
+  }
+
+  private _resetInner(): void {
     this._wasm.init();
     this._docs = [];
     this._lastSearch = null;
+    this._diagnostics = [];
+  }
+
+  /**
+   * Drain and return the diagnostics collected since the last call (or
+   * since the engine was created). Use this to surface recoverable
+   * issues to the caller after `indexFile`, `load`, or any other
+   * operation that may run into a "best-effort" path.
+   *
+   * Example diagnostics:
+   *   - `{kind:'fallback', stage:'pdf', message:'pdf-extract crashed,
+   *      attempting OCR-only fallback', file:'invoice.pdf'}`
+   *   - `{kind:'skipped', stage:'ocr', message:'Tesseract abort on page
+   *      3 image 1; remaining images on this page skipped', file:'...',
+   *      page:3}`
+   *   - `{kind:'fallback', stage:'gpu', message:'GPU pre-filter failed,
+   *      using CPU'}`
+   *
+   * The buffer is cleared on each call; callers should consume the
+   * returned array immediately (e.g. log to their telemetry, surface
+   * a UI banner). After `reset()` the buffer is also cleared.
+   */
+  takeDiagnostics(): AlbexDiagnostic[] {
+    const out = this._diagnostics;
+    this._diagnostics = [];
+    return out;
+  }
+
+  /** Internal: record a diagnostic. Capped at 256 to bound memory. */
+  private _diag(entry: AlbexDiagnostic): void {
+    if (this._diagnostics.length >= 256) return;
+    this._diagnostics.push(entry);
+  }
+
+  /**
+   * Install an OCR adapter. Returns a handle whose `dispose()` removes the
+   * adapter from the engine.
+   *
+   * The contract: the adapter must provide `recognize(image, opts)` that
+   * returns `Promise<OcrAttachedResult>`. The engine validates the
+   * contract at attach time and refuses adapters that don't expose a
+   * recognise function. Only one adapter can be attached at a time; a
+   * second call to `attachOcr` while one is active throws — the caller
+   * must dispose the previous one first.
+   *
+   * @example
+   * ```ts
+   * import { enableOcr } from '@albex/ocr';
+   * const handle = enableOcr(engine);   // internally calls attachOcr
+   * // ... later ...
+   * await handle.dispose();
+   * ```
+   *
+   * Direct use without the companion package:
+   * ```ts
+   * const handle = engine.attachOcr({
+   *   recognize: async (blob) => myCustomOcr(blob),
+   *   options: { alwaysExtractEmbeddedImages: false },
+   * });
+   * ```
+   */
+  attachOcr(adapter: OcrAdapter): OcrHandle {
+    if (this._ocrAdapter) {
+      throw new AlbexInitError(
+        'OCR adapter already attached. Call dispose() on the previous handle before attaching a new one.',
+      );
+    }
+    if (typeof adapter?.recognize !== 'function') {
+      throw new AlbexInitError(
+        'attachOcr requires an adapter with a recognize(image, opts) function.',
+      );
+    }
+    this._ocrAdapter = adapter;
+    return {
+      dispose: async () => {
+        // Idempotent: a double dispose is a no-op rather than a throw.
+        if (this._ocrAdapter === adapter) this._ocrAdapter = null;
+      },
+    };
   }
 
   // ── Persistence ───────────────────────────────────────────────────────────
@@ -2142,6 +2352,10 @@ export class AlbexEngine {
    * state in roughly O(total bytes), bypassing re-parsing.
    */
   async save(name: string): Promise<void> {
+    return this._exclusive(() => this._saveInner(name));
+  }
+
+  private async _saveInner(name: string): Promise<void> {
     const w     = this._wasm;
     const total = w.snapshotSize();
     if (total === 0) {
@@ -2168,6 +2382,10 @@ export class AlbexEngine {
    * header (wrong magic, version, or struct sizes).
    */
   async load(name: string): Promise<boolean> {
+    return this._exclusive(() => this._loadInner(name));
+  }
+
+  private async _loadInner(name: string): Promise<boolean> {
     const bytes = await loadPersisted(name);
     if (!bytes || bytes.length === 0) return false;
 
@@ -2188,6 +2406,17 @@ export class AlbexEngine {
       off += n;
     }
 
+    // Commit. For v3 this is the atomic apply step (state is untouched
+    // until now); a failure here leaves the previous index intact so the
+    // caller can keep using the engine. For v1/v2 snapshots `restoreCommit`
+    // is a no-op that returns 1 (those formats applied in-place during
+    // restoreFeed and have no rollback to offer). Older binaries that
+    // predate v3 do not export `restoreCommit` — in that case we treat
+    // the load as already committed by feature-detect.
+    if (typeof w.restoreCommit === 'function') {
+      if (w.restoreCommit() !== 1) return false;
+    }
+
     // Rebuild _docs metadata from the restored WASM tables.
     //
     // What's available after a restore:
@@ -2250,9 +2479,11 @@ export class AlbexEngine {
    * empty. Returns whether a load actually happened.
    */
   async loadOrInit(name: string): Promise<boolean> {
-    const loaded = await this.load(name);
-    if (!loaded) this.reset();
-    return loaded;
+    return this._exclusive(async () => {
+      const loaded = await this._loadInner(name);
+      if (!loaded) this._resetInner();
+      return loaded;
+    });
   }
 
   /** Delete a previously persisted snapshot. */
@@ -2277,7 +2508,8 @@ export class AlbexEngine {
    * WASM instance and its (typically 20 MB) backing memory.
    */
   [Symbol.dispose](): void {
-    this.reset();
+    // Terminal: bypass the idle guard — disposing mid-operation is allowed.
+    this._resetInner();
     this._unsubscribeResources?.();
     this._unsubscribeResources = null;
     this._gpu?.destroy();