albex 0.3.0 → 0.6.0

package/dist/albex.js

@@ -1,5 +1,5 @@
 /*!
- * albex v0.3.0
+ * albex v0.6.0
  * Zero-config local full-text search for documents — runs entirely in the browser, no server, no upload.
  * (c) 2026 RafaCalRob
  * @license MIT
@@ -21,9 +21,9 @@
  * ```
  */
 import { asAlbexExports, asAlbexPdfExports, } from './wasm-bindings.js';
-import { AlbexInitError, AlbexUnsupportedFormatError, AlbexParseError, AlbexCapacityError, } from './errors.js';
+import { AlbexError, AlbexInitError, AlbexUnsupportedFormatError, AlbexParseError, AlbexCapacityError, } from './errors.js';
 import { savePersisted, loadPersisted, deletePersisted, listPersisted, } from './persistence.js';
-import { detectProfile, pickTier, shouldUseGpu } from './profile.js';
+import { detectProfile, shouldUseGpu } from './profile.js';
 import { getResourceManager } from './resource-manager.js';
 import { BloomGpu, packBloomsFromChunks } from './gpu/bloom-runtime.js';
 export { AlbexError, AlbexInitError, AlbexUnsupportedFormatError, AlbexParseError, AlbexCapacityError, } from './errors.js';
@@ -48,41 +48,36 @@ function warnSearchStreamDeprecated() {
         'scheduler between slices and returns a batch. The alias will be ' +
         'removed in 0.4.0.');
 }
-function tokenize(q) {
-    return q.trim().split(/\s+/).filter(t => t.length > 0);
-}
-function parseQuery(q) {
-    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).
- */
-function tokensToWasmQuery(tokens) {
-    return tokens.slice(0, 4).join(' ');
-}
 // ─────────────────────────────────────────────────────────────────────────────
-// 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, tokens, maxGap = 30) {
     const norm = (s) => s.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '');
@@ -231,32 +226,11 @@ function computePatternBloom(query) {
     }
     return bits;
 }
-function contentHash(bytes) {
-    // 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
  * byte order matches the snapshot format: the high 32 bits sit at offsets
@@ -450,11 +424,18 @@ function makePdfWasmImports(module, getPdfMem) {
             case '__wbindgen_externref_table_set_null':
                 return (idx) => { 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) => {
-            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 = {};
     for (const { module: modName, name } of required) {
@@ -474,27 +455,29 @@ export class AlbexEngine {
      * runtime dependency on OCR — this is a structural slot that the optional
      * companion package fills.
      */
-    ocrImage;
     /**
-     * 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;
+    get ocrImage() {
+        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. */
+    _ocrAdapter = null;
     // ── PDF WASM (lazy) ──
     _pdfWasm = null;
     _pdfMem = null;
     _docs = [];
     _lastSearch = 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). */
+    _diagnostics = [];
     _tier = null;
     _simd = false;
     _profile = null;
@@ -503,9 +486,51 @@ export class AlbexEngine {
     _gpuChunkCountUploaded = 0;
     _unsubscribeResources = null;
     _opts;
+    // ── 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).
+    _opChain = Promise.resolve();
+    _busy = false;
     constructor(opts) {
         this._opts = opts;
     }
+    /** Serialize an async engine operation behind any in-flight one. */
+    _exclusive(fn) {
+        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;
+    }
+    /** Guard a synchronous mutator/search: refuse to run mid-async-operation
+     * rather than silently corrupt the shared WASM state. */
+    _assertIdle(method) {
+        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. */
+    _autoCompactIfNeeded() {
+        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() {
         const url = await this._resolveWasmUrl();
@@ -562,28 +587,26 @@ 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;
-        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;
-        const suffix = simd ? `${tier}_simd` : tier;
+        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 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. */
     get tier() { return this._tier; }
@@ -684,6 +707,34 @@ export class AlbexEngine {
             this._wasm.feedText(c.length);
         }
     }
+    /**
+     * 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.
+     */
+    _contentHash(bytes) {
+        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;
+    }
     _feedXmlBytes(xml, fn) {
         const feeder = this._wasm[fn];
         for (let i = 0; i < xml.length; i += FEED_SIZE) {
@@ -706,7 +757,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)
@@ -831,20 +885,14 @@ export class AlbexEngine {
             this._feedText(text);
             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)
@@ -930,7 +978,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)
@@ -954,15 +1005,6 @@ export class AlbexEngine {
             const copy = new Uint8Array(len);
             copy.set(new Uint8Array(liveMem.buffer, ptr, len));
             const blob = new Blob([copy.buffer], { 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();
@@ -977,7 +1019,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)}`,
+                });
             }
         }
         return pageText;
@@ -1018,7 +1063,10 @@ export class AlbexEngine {
             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;
         }
         // Set up the doc and let _indexPdfScanned do the page-by-page walk.
@@ -1027,7 +1075,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();
     }
@@ -1487,6 +1538,9 @@ export class AlbexEngine {
      * Throws for unsupported formats or parse errors.
      */
     async indexFile(file) {
+        return this._exclusive(() => this._indexFileInner(file));
+    }
+    async _indexFileInner(file) {
         const ext = file.name.split('.').pop()?.toLowerCase() ?? '';
         const indexer = AlbexEngine._INDEXERS[ext];
         if (!indexer)
@@ -1494,7 +1548,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.
         const existing = this._docs.find(d => d.contentHash === hash);
@@ -1516,6 +1570,24 @@ export class AlbexEngine {
             w.setDocumentContentHash(hashBytes.length);
         }
         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 = (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);
         const doc = {
@@ -1538,6 +1610,10 @@ export class AlbexEngine {
      * Returns `true` if a matching document was found and tombstoned.
      */
     removeDocument(id) {
+        this._assertIdle('removeDocument');
+        return this._removeDocumentInner(id);
+    }
+    _removeDocumentInner(id) {
         const doc = this._docs.find(d => d.name === id || d.contentHash === id);
         if (!doc)
             return false;
@@ -1553,12 +1629,15 @@ export class AlbexEngine {
      * idempotency check (so re-indexing the *same* bytes after a remove works).
      */
     async replaceDocument(name, newFile) {
-        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;
+        });
     }
     /**
      * Reclaim storage from previously removed documents. Compacts CHUNKS,
@@ -1568,6 +1647,7 @@ export class AlbexEngine {
      * references (e.g. in a UI) remain valid.
      */
     compact() {
+        this._assertIdle('compact');
         this._wasm.compact();
     }
     /**
@@ -1580,15 +1660,34 @@ export class AlbexEngine {
      * markers instead of full chunk text. Defaults: 60 bytes before, 120 after.
      */
     search(query, opts = {}) {
-        const parsed = parseQuery(query);
-        if (parsed.kind === 'or') {
-            return this._searchOr(parsed.branches, query, opts);
-        }
-        const results = this._runSearch(tokensToWasmQuery(parsed.tokens), query, opts);
-        if (parsed.kind === 'phrase') {
-            return results.filter(r => containsPhrase(r.snippet, parsed.tokens));
-        }
-        return results;
+        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);
+        }
+        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);
+    }
+    /** 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. */
+    _branchTokens(i) {
+        const n = this._wasm.getQueryBranchPattern(i);
+        if (n === 0)
+            return [];
+        const pattern = this._readPad(n);
+        return pattern.split(' ').filter(t => t.length > 0);
     }
     /**
      * Cooperative search. Processes the corpus in slices, yielding to the
@@ -1605,18 +1704,29 @@ export class AlbexEngine {
      * Pass `opts.frameBudgetMs` to control the slice size (default 8 ms).
      */
     async *searchCooperative(query, opts = {}) {
-        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. */
+    async _searchCooperativeCollect(query, opts) {
         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();
             const all = [];
-            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)) {
@@ -1626,17 +1736,11 @@ export class AlbexEngine {
                 }
             }
             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);
     }
     /**
      * @deprecated Renamed to `searchCooperative` in 0.3.0. The original name
@@ -1657,21 +1761,28 @@ export class AlbexEngine {
      * JS<->WASM overhead on fast machines; on slow machines a single batch
      * may eat the entire budget, which is also fine.
      */
-    async _runSearchBudgeted(wasmQuery, displayQuery, opts, budgetMs) {
+    async _runSearchBudgeted(displayQuery, opts, budgetMs, phraseTokens, branchIdx = 0) {
         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
         // before searchBegin so the slice loop only inspects candidates.
         // 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();
             }
         }
@@ -1719,16 +1830,28 @@ export class AlbexEngine {
             bloomPassed: w.getStatBloomPassed(),
             bitapMatched: w.getStatBitapMatched(),
         };
-        return this._collectResults(count, opts);
+        return this._collectResults(count, opts, phraseTokens);
     }
-    /** Materialise results [0..count) into the public SearchResult shape. */
-    _collectResults(count, opts) {
+    /** 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 }`. */
+    _collectResults(count, opts, phraseTokens) {
         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 = [];
         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);
@@ -1775,14 +1898,18 @@ export class AlbexEngine {
         }
         return results;
     }
-    _searchOr(branches, rawQuery, opts) {
+    /** 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. */
+    _searchOr(rawQuery, opts) {
+        const w = this._wasm;
         const seen = new Set();
         const all = [];
-        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)) {
@@ -1791,14 +1918,14 @@ export class AlbexEngine {
                 }
             }
         }
-        // Re-rank the merged list by score descending.
         all.sort((a, b) => b.score - a.score);
         return all;
     }
-    _runSearch(wasmQuery, displayQuery, opts) {
+    /** 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. */
+    _runSearch(displayQuery, opts, phraseTokens) {
         const w = this._wasm;
-        const ql = this._writeStr(wasmQuery);
-        w.setPattern(ql);
         const t0 = performance.now();
         const count = w.search();
         const ms = performance.now() - t0;
@@ -1810,59 +1937,7 @@ export class AlbexEngine {
             bloomPassed: w.getStatBloomPassed(),
             bitapMatched: w.getStatBitapMatched(),
         };
-        const windowed = opts.windowed === true;
-        const before = opts.before ?? 60;
-        const after = opts.after ?? 120;
-        const results = [];
-        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 = [];
-            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;
-            let primaryStart = matchStart;
-            let primaryEnd = matchEnd;
-            let adjustedMatches = 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. */
     getStats() {
@@ -1914,9 +1989,87 @@ export class AlbexEngine {
     }
     /** Full reset — clears all indexed documents and chunks. */
     reset() {
+        this._assertIdle('reset');
+        this._resetInner();
+    }
+    _resetInner() {
         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() {
+        const out = this._diagnostics;
+        this._diagnostics = [];
+        return out;
+    }
+    /** Internal: record a diagnostic. Capped at 256 to bound memory. */
+    _diag(entry) {
+        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) {
+        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 ───────────────────────────────────────────────────────────
     /**
@@ -1927,6 +2080,9 @@ export class AlbexEngine {
      * state in roughly O(total bytes), bypassing re-parsing.
      */
     async save(name) {
+        return this._exclusive(() => this._saveInner(name));
+    }
+    async _saveInner(name) {
         const w = this._wasm;
         const total = w.snapshotSize();
         if (total === 0) {
@@ -1953,6 +2109,9 @@ export class AlbexEngine {
      * header (wrong magic, version, or struct sizes).
      */
     async load(name) {
+        return this._exclusive(() => this._loadInner(name));
+    }
+    async _loadInner(name) {
         const bytes = await loadPersisted(name);
         if (!bytes || bytes.length === 0)
             return false;
@@ -1975,6 +2134,17 @@ export class AlbexEngine {
                 return false;
             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:
@@ -2035,10 +2205,12 @@ export class AlbexEngine {
      * empty. Returns whether a load actually happened.
      */
     async loadOrInit(name) {
-        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. */
     async deleteSnapshot(name) {
@@ -2060,7 +2232,8 @@ export class AlbexEngine {
      * WASM instance and its (typically 20 MB) backing memory.
      */
     [Symbol.dispose]() {
-        this.reset();
+        // Terminal: bypass the idle guard — disposing mid-operation is allowed.
+        this._resetInner();
         this._unsubscribeResources?.();
         this._unsubscribeResources = null;
         this._gpu?.destroy();