albex 0.6.0 → 0.7.0

package/dist/albex.js

@@ -1,6 +1,6 @@
 /*!
- * albex v0.6.0
- * Zero-config local full-text search for documents — runs entirely in the browser, no server, no upload.
+ * albex v0.7.0
+ * Local full-text search for documents — runs entirely in the browser, no server, no upload. Zero-config: the WASM core is embedded (~19 KB gzipped), so `npm install albex` then `new AlbexEngine()` works in any bundler, esbuild/Angular included.
  * (c) 2026 RafaCalRob
  * @license MIT
  * https://github.com/RafaCalRob/Albex#readme
@@ -21,7 +21,7 @@
  * ```
  */
 import { asAlbexExports, asAlbexPdfExports, } from './wasm-bindings.js';
-import { AlbexError, AlbexInitError, AlbexUnsupportedFormatError, AlbexParseError, AlbexCapacityError, } from './errors.js';
+import { AlbexError, AlbexInitError, AlbexUnsupportedFormatError, AlbexParseError, AlbexCapacityError, assertFileSizeWithinLimit, } from './errors.js';
 import { savePersisted, loadPersisted, deletePersisted, listPersisted, } from './persistence.js';
 import { detectProfile, shouldUseGpu } from './profile.js';
 import { getResourceManager } from './resource-manager.js';
@@ -48,6 +48,39 @@ function warnSearchStreamDeprecated() {
         'scheduler between slices and returns a batch. The alias will be ' +
         'removed in 0.4.0.');
 }
+/** The std preset = the historical compile-time defaults. */
+const CAPACITY_STD = {
+    maxDocs: 128,
+    maxChunks: 100_000,
+    textPoolBytes: 16 * 1024 * 1024,
+    namePoolBytes: 32 * 1024,
+};
+/** The large preset = the old compile-time "pro" tier. */
+const CAPACITY_LARGE = {
+    maxDocs: 1024,
+    maxChunks: 800_000,
+    textPoolBytes: 128 * 1024 * 1024,
+    namePoolBytes: 256 * 1024,
+};
+/**
+ * Resolve a user-facing capacity option into full numbers. Partial custom
+ * configs are completed from the std defaults scaled to keep std's ratios:
+ * `maxChunks` follows `maxDocs` (×782), `textPoolBytes` follows `maxChunks`
+ * (×168 B), `namePoolBytes` follows `maxDocs` (×256 B) — each with a floor
+ * so tiny configs stay usable. `maxChunks` is clamped to at least `maxDocs`
+ * (every document needs at least one chunk).
+ */
+function resolveCapacity(capacity) {
+    if (capacity === undefined || capacity === 'std')
+        return { ...CAPACITY_STD };
+    if (capacity === 'large')
+        return { ...CAPACITY_LARGE };
+    const maxDocs = Math.floor(capacity.maxDocs ?? CAPACITY_STD.maxDocs);
+    const maxChunks = Math.max(Math.floor(capacity.maxChunks ?? Math.max(maxDocs * 782, 1024)), maxDocs);
+    const textPoolBytes = Math.floor(capacity.textPoolBytes ?? Math.max(maxChunks * 168, 64 * 1024));
+    const namePoolBytes = Math.floor(capacity.namePoolBytes ?? Math.max(maxDocs * 256, 4 * 1024));
+    return { maxDocs, maxChunks, textPoolBytes, namePoolBytes };
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Query parsing (WASM-side as of 0.5.0)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -196,35 +229,51 @@ const FEED_SIZE = 32_768; // 32 KB — fits in 64 KB scratchpad
  * The result is stable across runs and engines, so it can be persisted in
  * snapshots without versioning concerns.
  */
+// NOTE: the TS `computePatternBloom` that used to live here (the THIRD copy
+// of the accent fold, after the Rust index side and the Rust query side) was
+// removed in 0.8.0. The GPU pre-filter now reads the pattern Bloom straight
+// from WASM via `getPatternBloomLo/Hi` (ABI 6) — `setPattern` computes it
+// through the exact pipeline `searchBegin` uses, including Spanish stemming,
+// which the TS copy never applied (audit 2.4).
 /**
- * Compute the same 64-bit Bloom value the Rust side computes for a query.
+ * Convert a UTF-8 byte offset into `bytes` to the equivalent UTF-16
+ * code-unit index of the decoded string. Walks lead bytes only — O(offset)
+ * with no allocation — counting 1 unit per BMP code point and 2 per 4-byte
+ * (astral, e.g. emoji) sequence. Stray continuation bytes (malformed input)
+ * count 1 unit each, matching TextDecoder's per-byte U+FFFD replacement.
  *
- * Must stay in sync with `BloomFilter::from_text` and `fold_utf8_char` in
- * `core/src/bloom.rs`. The hashing is `c & 0x3F` over each accent-folded
- * lowercase ASCII byte; non-letters are skipped. The aggregate of all token
- * blooms is what the GPU pre-filter checks against.
+ * Offsets that land mid-sequence are attributed to the code point they fall
+ * inside (the engine only emits code-point-aligned offsets, so this is a
+ * defensive clamp, not an expected path).
  */
-function computePatternBloom(query) {
-    // Quick-and-faithful fold: lowercase, NFKD, strip combining marks. This
-    // matches the Rust Latin-1/Latin-A fold for the characters we care about
-    // (the rest fall through as non-letters which contribute nothing).
-    const norm = query.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '');
-    let bits = 0n;
-    for (let i = 0; i < norm.length; i++) {
-        const code = norm.charCodeAt(i);
-        if ((code >= 0x61 && code <= 0x7a) || (code >= 0x30 && code <= 0x39)) {
-            bits |= 1n << BigInt(code & 0x3f);
-        }
-        else if (code === 0x20) {
-            // skip token separator
-        }
-        else if (code < 0x80) {
-            // other ASCII punctuation — they bias the filter; mirror Rust which
-            // also includes them via the 6-bit mask.
-            bits |= 1n << BigInt(code & 0x3f);
-        }
-    }
-    return bits;
+function utf16IndexAtByte(bytes, byteOffset) {
+    const end = Math.min(byteOffset, bytes.length);
+    let units = 0;
+    let i = 0;
+    while (i < end) {
+        const b = bytes[i];
+        if (b < 0x80) {
+            i += 1;
+            units += 1;
+        } // ASCII
+        else if (b < 0xc0) {
+            i += 1;
+            units += 1;
+        } // stray continuation → U+FFFD
+        else if (b < 0xe0) {
+            i += 2;
+            units += 1;
+        } // 2-byte (é, ñ, …)
+        else if (b < 0xf0) {
+            i += 3;
+            units += 1;
+        } // 3-byte (…, €, CJK)
+        else {
+            i += 4;
+            units += 2;
+        } // 4-byte → surrogate pair
+    }
+    return units;
 }
 // Note: `contentHash` is implemented as a method on AlbexEngine below
 // (it needs access to the WASM scratchpad). The standalone TS reference
@@ -473,17 +522,29 @@ export class AlbexEngine {
     _pdfMem = null;
     _docs = [];
     _lastSearch = null;
+    /** Raw truncation bitflags from the most recent prepareQuery (ABI 5):
+     * 1 = branches dropped, 2 = tokens dropped/clipped, 4 = query bytes cut.
+     * Captured right after prepareQuery so every _lastSearch built for that
+     * query (including per-branch OR runs) reports the same flags. */
+    _lastTruncFlags = 0;
     /** 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;
+    /** Resolved runtime capacity (set in init(); reused by reset()). */
+    _capacity = { ...CAPACITY_STD };
     _simd = false;
     _profile = null;
     _resources = null;
     _gpu = null;
-    _gpuChunkCountUploaded = 0;
+    /** True when the GPU-resident Bloom array no longer mirrors the WASM
+     * chunk array. Set by EVERY index mutation (indexFile, removeDocument,
+     * compact, reset, load) and cleared after a successful upload. A plain
+     * chunk-count comparison is NOT enough: compact() can reorder blooms
+     * while keeping the count identical, which would silently filter the
+     * wrong chunks (audit 1.5). */
+    _gpuUploadDirty = true;
     _unsubscribeResources = null;
     _opts;
     // ── Concurrency guard ──────────────────────────────────────────────────────
@@ -494,7 +555,7 @@ export class AlbexEngine {
     // assert the engine is idle (audit 0.6.0, finding #2).
     _opChain = Promise.resolve();
     _busy = false;
-    constructor(opts) {
+    constructor(opts = {}) {
         this._opts = opts;
     }
     /** Serialize an async engine operation behind any in-flight one. */
@@ -529,18 +590,32 @@ export class AlbexEngine {
         const hasTombstones = w.getDocCount() > this._docs.length;
         if (hasTombstones && cap > 0 && w.getTextUsed() / cap > 0.85) {
             w.compact();
+            this._gpuUploadDirty = true;
         }
     }
-    /** Load and initialise the main WASM module. Must be called before any other method. */
+    /**
+     * Load and initialise the main WASM module. Must be called before any
+     * other method.
+     *
+     * Resolves `opts.capacity` ('std' default · 'large' · explicit object)
+     * and sizes the WASM pools accordingly via `initWithCapacity` (ABI 7).
+     * Memory cost ≈ `maxChunks × 64 B + textPoolBytes + namePoolBytes` —
+     * ~22 MB for 'std', ~180 MB for 'large'. Throws `AlbexInitError` if the
+     * requested capacity is out of range or the allocation fails.
+     */
     async init() {
-        const url = await this._resolveWasmUrl();
-        const res = await fetch(url);
-        if (!res.ok)
-            throw new AlbexInitError(`Failed to fetch WASM: ${res.status} (${url})`);
-        const { instance } = await WebAssembly.instantiateStreaming(res, {});
+        const instance = await this._instantiateMainWasm();
         this._wasm = asAlbexExports(instance.exports);
         this._mem = this._wasm.memory;
-        this._wasm.init();
+        this._capacity = resolveCapacity(this._opts.capacity);
+        const c = this._capacity;
+        if (this._wasm.initWithCapacity(c.maxDocs, c.maxChunks, c.textPoolBytes, c.namePoolBytes) !== 1) {
+            throw new AlbexInitError(`initWithCapacity(${c.maxDocs} docs, ${c.maxChunks} chunks, ` +
+                `${c.textPoolBytes} text bytes, ${c.namePoolBytes} name bytes) failed — ` +
+                `parameters out of range (docs 1-65536, chunks ≥ docs and ≤ 4194304, ` +
+                `text 4 KiB-1 GiB, names 256 B-16 MiB) or the WASM memory allocation ` +
+                `was refused by the host.`);
+        }
         // Subscribe to environmental signals. Cheap and benign in node tests
         // (the manager tolerates missing globals).
         const rm = getResourceManager();
@@ -555,23 +630,87 @@ export class AlbexEngine {
         }
     }
     /**
-     * Decide which `.wasm` binary to fetch. Order of precedence:
-     *   1. `opts.wasmUrl` if provided — used verbatim.
-     *   2. `opts.tier` if explicit — joined with `wasmBaseUrl`.
-     *   3. `opts.wasmBaseUrl` + tier picked from the device profile.
+     * Instantiate the main core WASM. Two sources, in order of precedence:
+     *   1. `opts.wasmBytes` — caller-provided bytes; NO network access. The
+     *      `albex/inline` entry uses this with the embedded baseline core, and
+     *      integrators on bundlers that don't rewrite `new URL(…, import.meta.
+     *      url)` (esbuild / Angular / some Webpack) can import the `.wasm` as an
+     *      asset and pass the bytes here.
+     *   2. a URL from `_resolveWasmUrl` (`wasmUrl` / `wasmBaseUrl` / the
+     *      bundler-friendly default).
      *
-     * Order of precedence:
+     * The URL path prefers `instantiateStreaming` and falls back to
+     * `instantiate(arrayBuffer)` when the host serves the `.wasm` with the
+     * wrong MIME type — a common esbuild / static-server pitfall that
+     * otherwise rejects with an opaque "Incorrect response MIME type". A 404
+     * or a network error is rethrown as an `AlbexInitError` whose message
+     * points at the concrete fixes (inline entry / `wasmBytes` / `wasmUrl`).
+     */
+    async _instantiateMainWasm() {
+        const bytes = this._opts.wasmBytes;
+        if (bytes) {
+            // No fetch, no SIMD probe: the caller chose the binary. `simdEnabled`
+            // reflects only an explicit `simd: 'on'` assertion about those bytes.
+            this._profile = await detectProfile();
+            this._simd = this._opts.simd === 'on';
+            const { instance } = await WebAssembly.instantiate(bytes, {});
+            return instance;
+        }
+        const url = await this._resolveWasmUrl();
+        let res;
+        try {
+            res = await fetch(url);
+        }
+        catch (cause) {
+            throw new AlbexInitError(this._wasmLoadHelp(url, String(cause)));
+        }
+        if (!res.ok) {
+            throw new AlbexInitError(this._wasmLoadHelp(url, `HTTP ${res.status}`));
+        }
+        try {
+            const { instance } = await WebAssembly.instantiateStreaming(res, {});
+            return instance;
+        }
+        catch (streamErr) {
+            // Streaming rejects when the response Content-Type isn't
+            // `application/wasm`. The bytes are usually fine — re-fetch (the first
+            // body was consumed by the streaming attempt) and compile from a buffer.
+            try {
+                const buf = await (await fetch(url)).arrayBuffer();
+                const { instance } = await WebAssembly.instantiate(buf, {});
+                return instance;
+            }
+            catch {
+                throw new AlbexInitError(this._wasmLoadHelp(url, `instantiate failed (${String(streamErr)})`));
+            }
+        }
+    }
+    /** Build the actionable "couldn't load the core" message shared by every
+     * main-WASM load failure. The default `albex` entry embeds the core, so a
+     * fetch only runs when the caller explicitly set `wasmUrl`/`wasmBaseUrl` —
+     * the message leads with the one-line exit (drop the option). */
+    _wasmLoadHelp(url, reason) {
+        return (`Albex couldn't fetch its core WASM (${reason}) from ${url}. ` +
+            `You're on the network path because \`wasmUrl\` or \`wasmBaseUrl\` is ` +
+            `set. Easiest fix: remove that option — the default ` +
+            `\`import { AlbexEngine } from 'albex'\` embeds the core and serves ` +
+            `nothing. Keep the option only for a CDN or the SIMD build, and make ` +
+            `sure it points at a reachable \`albex_wasm*.wasm\` (check the path, ` +
+            `the dev server, and CORS).`);
+    }
+    /**
+     * Decide which `.wasm` binary to fetch. Order of precedence:
      *   1. `opts.wasmUrl` literal               → use verbatim
-     *   2. `opts.wasmBaseUrl` + tier suffix     → fetched from that directory
+     *   2. `opts.wasmBaseUrl` + simd suffix     → fetched from that directory
      *   3. zero-config default                  → `albex_wasm_bg.wasm` packaged
      *                                             next to this file, resolved
      *                                             via `import.meta.url`
      *
-     * The zero-config default loads the std-baseline binary. Tier auto-detection
-     * is only active when `wasmBaseUrl` is given, because picking a tier in
-     * runtime would defeat any bundler's static asset rewriting. Users who want
-     * tier optimisation must serve the six variants themselves and pass the
-     * directory through `wasmBaseUrl`.
+     * There are exactly two main binaries (baseline + SIMD); capacity is a
+     * RUNTIME parameter since ABI 7, so it never affects which file is
+     * fetched. SIMD auto-detection is only active when `wasmBaseUrl` is
+     * given, because picking a URL at runtime would defeat any bundler's
+     * static asset rewriting.
      */
     async _resolveWasmUrl() {
         const o = this._opts;
@@ -587,17 +726,16 @@ 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.
-        // 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.
+        // 0.5.0+: two main binaries only — baseline and SIMD (the tier system
+        // is gone; capacity became a runtime parameter in ABI 7). 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
@@ -608,8 +746,6 @@ export class AlbexEngine {
         const base = o.wasmBaseUrl.replace(/\/+$/, '');
         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; }
     /** True if the SIMD-accelerated binary was loaded. */
     get simdEnabled() { return this._simd; }
     /** True if a WebGPU device is acquired and the next search will use it. */
@@ -645,8 +781,14 @@ export class AlbexEngine {
      * No-op if the GPU device hasn't been acquired yet — first call attempts
      * `init()` lazily; if that fails, the candidate path is permanently
      * disabled for this engine instance.
+     *
+     * IMPORTANT: this method CLOBBERS the scratchpad (the candidate bitset
+     * is pushed through it via `setCandidateMask`). Any pattern previously
+     * staged by `selectQueryBranch` is destroyed — the caller MUST re-select
+     * the active branch before calling `searchBegin`, which snapshots the
+     * pattern from the scratchpad (audit 1.2).
      */
-    async _gpuPreFilter(wasmQuery) {
+    async _gpuPreFilter() {
         const gpu = this._gpu;
         if (!gpu)
             return;
@@ -660,20 +802,26 @@ export class AlbexEngine {
         const chunkCount = this._wasm.getChunkCount();
         if (chunkCount === 0)
             return;
-        // Upload blooms if the corpus changed. We re-upload everything on any
-        // delta; incremental delta-upload is a future optimisation.
-        if (chunkCount !== this._gpuChunkCountUploaded) {
+        // Upload blooms if the corpus changed since the last upload. The
+        // signal is a dirty flag set by every index mutation — not a chunk
+        // count comparison, because compact() can reorder blooms while
+        // keeping the count identical (audit 1.5). We re-upload everything
+        // on any delta; incremental delta-upload is a future optimisation.
+        if (this._gpuUploadDirty) {
             const ptr = this._wasm.getChunksPtr();
             const stride = this._wasm.getChunkStructSize();
             const bytes = new Uint8Array(this._mem.buffer, ptr, chunkCount * stride);
             const blooms = packBloomsFromChunks(bytes, chunkCount);
             gpu.uploadChunkBlooms(blooms, chunkCount);
-            this._gpuChunkCountUploaded = chunkCount;
-        }
-        // Build the pattern Bloom on the JS side: same hash as Rust
-        // (`c & 0x3F` after accent-folding), aggregated across all tokens.
-        const patternBloom = computePatternBloom(wasmQuery);
-        const passes = await gpu.scan(Number(patternBloom & 0xffffffffn), Number((patternBloom >> 32n) & 0xffffffffn));
+            this._gpuUploadDirty = false;
+        }
+        // Pattern Bloom comes straight from WASM (ABI 6): `selectQueryBranch`
+        // → `setPattern` computed it through the same pipeline `searchBegin`
+        // uses — split, optional Spanish stemming, accent fold, `c & 0x3F`.
+        // The retired TS copy of the fold never stemmed, so with `setLanguage
+        // ('es')` it could set bits for suffixes the CPU pattern no longer
+        // had → over-restrictive mask → silent false negatives (audit 2.4).
+        const passes = await gpu.scan(this._wasm.getPatternBloomLo(), this._wasm.getPatternBloomHi());
         // Push the bitset back into WASM via the scratchpad.
         const passBytes = new Uint8Array(passes.buffer, passes.byteOffset, passes.byteLength);
         this._writePad(passBytes);
@@ -699,6 +847,16 @@ export class AlbexEngine {
         const ptr = this._wasm.getBuffer(0);
         return _dec.decode(this._u8(ptr, n));
     }
+    /** Copy `n` scratchpad bytes out of WASM memory. The copy is private to
+     * JS, so it survives later WASM calls (and memory growth) — used when the
+     * caller needs both the raw bytes (UTF-16 span mapping) and the decoded
+     * string of the same payload. */
+    _readPadBytes(n) {
+        const ptr = this._wasm.getBuffer(0);
+        const out = new Uint8Array(n);
+        out.set(this._u8(ptr, n));
+        return out;
+    }
     _feedText(text) {
         const b = _enc.encode(text);
         for (let i = 0; i < b.length; i += FEED_SIZE) {
@@ -747,9 +905,26 @@ export class AlbexEngine {
     async _ensurePdfWasm() {
         if (this._pdfWasm)
             return;
+        // Compile first (regardless of source) so we can inspect the module's
+        // required imports and resolve mangled wasm-bindgen names by prefix
+        // rather than by hash.
+        const module = this._opts.pdfWasmBytes
+            ? await WebAssembly.compile(this._opts.pdfWasmBytes)
+            : await this._fetchPdfModule();
+        const imports = makePdfWasmImports(module, () => this._pdfMem);
+        const instance = await WebAssembly.instantiate(module, imports);
+        this._pdfWasm = asAlbexPdfExports(instance.exports);
+        this._pdfMem = this._pdfWasm.memory;
+    }
+    /** Fetch + compile the PDF module from a URL. Split out of
+     * `_ensurePdfWasm` so the `pdfWasmBytes` (no-network) path stays trivial.
+     * Falls back to a buffered compile when the host serves the binary with
+     * the wrong MIME type (same pitfall as the core loader). */
+    async _fetchPdfModule() {
         // Zero-config default: resolve relative to this module so bundlers copy
         // the .wasm to the output automatically. Override with `opts.pdfWasmUrl`
-        // when serving from a separate CDN.
+        // when serving from a separate CDN, or pass `pdfWasmBytes` to skip the
+        // network entirely (e.g. esbuild/Angular).
         const pdfUrl = this._opts.pdfWasmUrl
             ?? new URL('../wasm/pkg/albex_pdf.wasm', import.meta.url).href;
         // Network politeness: on constrained connections (slow-2g/2g/saveData)
@@ -762,16 +937,25 @@ export class AlbexEngine {
                 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}`);
-        // Compile first so we can inspect the module's required imports and
-        // resolve mangled wasm-bindgen names by prefix rather than by hash.
-        const module = await WebAssembly.compileStreaming(res);
-        const imports = makePdfWasmImports(module, () => this._pdfMem);
-        const instance = await WebAssembly.instantiate(module, imports);
-        this._pdfWasm = asAlbexPdfExports(instance.exports);
-        this._pdfMem = this._pdfWasm.memory;
+        let res;
+        try {
+            res = await fetch(pdfUrl);
+        }
+        catch (cause) {
+            throw new AlbexInitError(`Failed to fetch PDF WASM from ${pdfUrl} (${String(cause)}). ` +
+                `Pass \`pdfWasmBytes\` (bundler asset import) or set \`pdfWasmUrl\`.`);
+        }
+        if (!res.ok) {
+            throw new AlbexInitError(`Failed to fetch PDF WASM: ${res.status} (${pdfUrl}). ` +
+                `Pass \`pdfWasmBytes\` (bundler asset import) or set \`pdfWasmUrl\`.`);
+        }
+        try {
+            return await WebAssembly.compileStreaming(res);
+        }
+        catch {
+            const buf = await (await fetch(pdfUrl)).arrayBuffer();
+            return WebAssembly.compile(buf);
+        }
     }
     // ── Indexers ──────────────────────────────────────────────────────────────
     async _indexDocx(file, bytes) {
@@ -1534,7 +1718,9 @@ export class AlbexEngine {
     };
     // ── Public API ────────────────────────────────────────────────────────────
     /**
-     * Index a file. Supported formats: DOCX, XLSX, PDF, TXT, XML.
+     * Index a file. Supported formats (11, with varying depth): DOCX, XLSX, PDF,
+     * HTML, MD, JSON, CSV, EML, RTF, TXT, XML. Several are deliberately "lite"
+     * (CSV is RFC-4180-lite, EML is MIME-lite, RTF is regex-stripped).
      * Throws for unsupported formats or parse errors.
      */
     async indexFile(file) {
@@ -1545,12 +1731,16 @@ export class AlbexEngine {
         const indexer = AlbexEngine._INDEXERS[ext];
         if (!indexer)
             throw new AlbexUnsupportedFormatError(ext);
+        // Size guard BEFORE reading: `file.size` is available without buffering,
+        // so a pathological input (a 2 GB .txt) is refused with a typed error
+        // instead of being fully loaded and hashed first (audit 3.5).
+        assertFileSizeWithinLimit(file, this._opts.maxFileBytes);
         // 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 = this._contentHash(bytes);
         // Idempotency: if a non-deleted doc already has this hash, return it
-        // unchanged. Cheap O(N) scan since MAX_DOCS = 128.
+        // unchanged. O(doc_count) scan — cheap at any supported capacity.
         const existing = this._docs.find(d => d.contentHash === hash);
         if (existing)
             return existing;
@@ -1578,15 +1768,22 @@ export class AlbexEngine {
         if (overflow !== 0) {
             const which = (overflow & 1) ? 'chunks' : (overflow & 2) ? 'text'
                 : (overflow & 4) ? 'docs' : 'names';
+            // The RUNTIME limit of the pool that overflowed, as configured via
+            // `capacity` (std defaults · 'large' · custom object).
+            const max = which === 'chunks' ? w.getMaxChunks()
+                : which === 'text' ? w.getTextCapacity()
+                    : which === 'docs' ? w.getMaxDocs()
+                        : w.getNameCapacity();
             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);
+            throw new AlbexCapacityError(`Index capacity exceeded while indexing "${file.name}" (${pools} full, ` +
+                `${which} limit = ${max}). The document was rolled back (not indexed); ` +
+                `treat the index as full (compact(), shard across an AlbexPool, ` +
+                `reset(), or re-create the engine with a bigger \`capacity\`).`, which, max);
         }
         // The new doc occupies slot `docCountBefore`.
         const docId = w.getDocId(docCountBefore);
@@ -1600,6 +1797,7 @@ export class AlbexEngine {
             contentHash: hash,
         };
         this._docs.push(doc);
+        this._gpuUploadDirty = true;
         return doc;
     }
     /**
@@ -1620,6 +1818,7 @@ export class AlbexEngine {
         const ok = this._wasm.removeDocument(doc.docId) === 1;
         if (ok) {
             this._docs = this._docs.filter(d => d !== doc);
+            this._gpuUploadDirty = true;
         }
         return ok;
     }
@@ -1649,6 +1848,76 @@ export class AlbexEngine {
     compact() {
         this._assertIdle('compact');
         this._wasm.compact();
+        // compact() reorders the chunk array (and therefore the per-chunk
+        // blooms) even when the chunk count stays the same — the GPU copy is
+        // stale no matter what (audit 1.5).
+        this._gpuUploadDirty = true;
+    }
+    /**
+     * Enumerate the authoritative chunks Albex indexed for a document, in order.
+     * Lets a host mirror Albex's exact chunking — e.g. embed the same units for a
+     * parallel semantic index keyed on the same {@link AuthoritativeChunk.id}
+     * (`"<docId>::<ord>"`, identical to {@link SearchResult.chunkId}). `docId` is
+     * `IndexedDocument.docId` from {@link indexFile}; returns `[]` if no live
+     * document has that id.
+     *
+     * The returned `id`/`ord`/`sub` are stable across {@link compact} and
+     * snapshot save/load. Never key persistent structures on a search result's
+     * absolute `chunkIdx`, which {@link compact} renumbers.
+     */
+    listChunks(docId) {
+        this._assertIdle('listChunks');
+        const w = this._wasm;
+        const slot = this._docSlotOf(docId);
+        if (slot < 0)
+            return [];
+        const count = w.getDocChunkCount(slot);
+        const out = [];
+        let prevLocation = -1;
+        let sub = 0;
+        // Batched enumeration (ABI 6): one `listChunksBatch` frontier call per
+        // scratchpad-full of chunks instead of 2-3 calls per chunk (audit 2.6 —
+        // an embeddings pipeline over 100k chunks used to make ~300k calls).
+        // Each batch packs records as [u32 text_len][u32 location][text bytes],
+        // tightly, in ordinal order; layout documented in wasm/src/lib.rs.
+        let ord = 0;
+        while (ord < count) {
+            const n = w.listChunksBatch(slot, ord, count - ord);
+            if (n === 0)
+                break; // defensive — should not happen for a live slot
+            const ptr = w.getBuffer(0);
+            // The view is only valid until the next frontier call; everything is
+            // decoded out of it inside this loop body before the next batch.
+            const view = new DataView(this._mem.buffer);
+            let off = ptr;
+            for (let k = 0; k < n; k++) {
+                const byteLen = view.getUint32(off, true);
+                const location = view.getUint32(off + 4, true);
+                const text = byteLen > 0
+                    ? _dec.decode(new Uint8Array(this._mem.buffer, off + 8, byteLen))
+                    : '';
+                if (location === prevLocation)
+                    sub++;
+                else {
+                    sub = 0;
+                    prevLocation = location;
+                }
+                out.push({ docId, location, ord, sub, text, byteLen, id: `${docId}::${ord}` });
+                ord++;
+                off += 8 + byteLen;
+            }
+        }
+        return out;
+    }
+    /** Doc-table slot (0..getDocCount) whose stable id is `docId`, or -1. */
+    _docSlotOf(docId) {
+        const w = this._wasm;
+        const n = w.getDocCount();
+        for (let i = 0; i < n; i++) {
+            if (w.getDocId(i) === docId)
+                return i;
+        }
+        return -1;
     }
     /**
      * Search the index. Supports:
@@ -1658,12 +1927,18 @@ export class AlbexEngine {
      *
      * Pass `{ windowed: true }` to receive cropped snippets with ASCII ellipsis
      * markers instead of full chunk text. Defaults: 60 bytes before, 120 after.
+     *
+     * Note: this synchronous path never uses the GPU pre-filter — the WebGPU
+     * scan is asynchronous by nature. Only `searchCooperative` (the budgeted
+     * path) engages the GPU; `search()` always runs the CPU Bloom pre-filter,
+     * regardless of the `gpu` option.
      */
     search(query, opts = {}) {
         this._assertIdle('search');
         const w = this._wasm;
         const ql = this._writeStr(query);
         const kind = w.prepareQuery(ql);
+        this._lastTruncFlags = w.getQueryTruncationFlags();
         if (kind < 0)
             return [];
         if (kind === 2) {
@@ -1717,6 +1992,7 @@ export class AlbexEngine {
         const w = this._wasm;
         const ql = this._writeStr(query);
         const kind = w.prepareQuery(ql);
+        this._lastTruncFlags = w.getQueryTruncationFlags();
         if (kind < 0)
             return [];
         if (kind === 2) {
@@ -1728,7 +2004,12 @@ export class AlbexEngine {
                 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}`;
+                    // chunkId ("<docId>::<ord>") distinguishes two sub-chunks of the
+                    // same location — a (doc, location, matchStart) key would collide
+                    // when both sub-chunks hit at the same relative offset and drop a
+                    // legitimate result (audit 3.4). matchStart keeps distinct hits
+                    // within one chunk across branches.
+                    const key = `${x.chunkId}:${x.matchStart}`;
                     if (!seen.has(key)) {
                         seen.add(key);
                         all.push(x);
@@ -1763,19 +2044,17 @@ export class AlbexEngine {
      */
     async _runSearchBudgeted(displayQuery, opts, budgetMs, phraseTokens, branchIdx = 0) {
         const w = this._wasm;
-        // 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) : '';
+        // Pattern is already set by the caller via selectQueryBranch(branchIdx),
+        // which also computed THAT branch's pattern Bloom inside WASM — so the
+        // GPU pre-filter below builds the right candidate mask per OR branch
+        // (audit finding #6) without re-reading the pattern across the frontier.
         // 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(activePattern);
+                await this._gpuPreFilter();
             }
             catch (e) {
                 // Don't let a GPU hiccup kill the search — drop to CPU path.
@@ -1785,12 +2064,20 @@ export class AlbexEngine {
                 });
                 w.clearCandidateMask();
             }
+            // The GPU pre-filter pushes the candidate bitset through the
+            // scratchpad, overwriting the pattern staged by selectQueryBranch.
+            // searchBegin() snapshots the pattern FROM the scratchpad, so it
+            // would compile garbage tokens out of the mask bytes (audit 1.2 —
+            // every GPU-assisted search silently returned wrong results).
+            // Re-select the active branch to restore the pattern.
+            w.selectQueryBranch(branchIdx);
         }
         const t0 = performance.now();
         if (w.searchBegin() === 0) {
             this._lastSearch = {
                 query: displayQuery, timeMs: 0, results: 0,
                 bloomTested: 0, bloomPassed: 0, bitapMatched: 0,
+                ...this._truncStats(),
             };
             return [];
         }
@@ -1829,21 +2116,96 @@ export class AlbexEngine {
             bloomTested: w.getStatBloomTested(),
             bloomPassed: w.getStatBloomPassed(),
             bitapMatched: w.getStatBitapMatched(),
+            ...this._truncStats(),
         };
         return this._collectResults(count, opts, phraseTokens);
     }
+    /** Truncation booleans for SearchStats, decoded from the flags the WASM
+     * reported for the most recent prepareQuery (audit 1.6 — the engine used
+     * to drop OR branches past 8 and tokens past 4 in silence). */
+    _truncStats() {
+        const f = this._lastTruncFlags;
+        return {
+            truncatedBranches: (f & 1) !== 0,
+            truncatedTokens: (f & 2) !== 0,
+            truncatedQuery: (f & 4) !== 0,
+        };
+    }
     /** 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 }`. */
+     * windowing — so phrase queries stay correct under `{ windowed: true }`.
+     *
+     * Frontier discipline (audit 2.1): all numeric fields of every result are
+     * read in ONE DataView pass over the `#[repr(C)]` RESULTS array
+     * (`getResultsPtr`/`getResultStride`, ABI 6) — the old path made 12-15
+     * frontier calls per result. Strings still need calls, minimised to one
+     * snippet read per result plus one doc-name read per DISTINCT document
+     * (the old `getResultDocName` was additionally O(doc_count) inside WASM
+     * for every single result). */
     _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;
+        // Map each live doc_id to its CHUNKS[] base (to turn a result's absolute
+        // chunk index into a compact()-stable doc-relative ordinal) and to its
+        // doc-table slot (for O(1) name resolution via getDocName).
+        const chunkBaseByDocId = new Map();
+        const slotByDocId = new Map();
+        {
+            const docCount = w.getDocCount();
+            for (let d = 0; d < docCount; d++) {
+                const id = w.getDocId(d);
+                chunkBaseByDocId.set(id, w.getDocChunkBase(d));
+                slotByDocId.set(id, d);
+            }
+        }
+        const raw = new Array(count);
+        {
+            const ptr = w.getResultsPtr();
+            const stride = w.getResultStride();
+            const view = new DataView(this._mem.buffer, ptr, count * stride);
+            for (let i = 0; i < count; i++) {
+                const base = i * stride;
+                const matchCount = view.getUint32(base + 56, true);
+                const matches = [];
+                for (let k = 0; k < matchCount && k < 4; k++) {
+                    matches.push({
+                        start: view.getUint32(base + 24 + k * 8, true),
+                        end: view.getUint32(base + 28 + k * 8, true),
+                    });
+                }
+                const matchStart = view.getUint32(base + 16, true);
+                const matchEnd = view.getUint32(base + 20, true);
+                if (matches.length === 0)
+                    matches.push({ start: matchStart, end: matchEnd });
+                raw[i] = {
+                    docId: view.getUint32(base, true),
+                    chunkIdx: view.getUint32(base + 4, true),
+                    location: view.getUint32(base + 8, true),
+                    score: view.getUint16(base + 12, true),
+                    matchStart, matchEnd, matches,
+                };
+            }
+        }
+        // Resolve each distinct doc name ONCE per search (one getDocName call
+        // per document that actually appears in the results).
+        const nameByDocId = new Map();
+        const docName = (docId) => {
+            let name = nameByDocId.get(docId);
+            if (name === undefined) {
+                const slot = slotByDocId.get(docId);
+                const nl = slot !== undefined ? w.getDocName(slot) : 0;
+                name = nl > 0 ? this._readPad(nl) : '?';
+                nameByDocId.set(docId, name);
+            }
+            return name;
+        };
         const results = [];
         for (let i = 0; i < count; i++) {
+            const r = raw[i];
             // Phrase adjacency check against the full chunk text (getSnippet), not
             // the possibly-cropped display window.
             if (phraseFilter) {
@@ -1852,30 +2214,18 @@ export class AlbexEngine {
                 if (!containsPhrase(full, phraseFilter))
                     continue;
             }
-            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;
+            const chunkOrd = r.chunkIdx - (chunkBaseByDocId.get(r.docId) ?? 0);
+            let snippetBytes;
+            let primaryStart = r.matchStart;
+            let primaryEnd = r.matchEnd;
+            let adjustedMatches = r.matches;
             if (windowed) {
                 const sl = w.getSnippetWindow(i, before, after);
-                snippet = sl > 0 ? this._readPad(sl) : '';
+                snippetBytes = sl > 0 ? this._readPadBytes(sl) : new Uint8Array(0);
                 const offset = w.getSnippetWindowOffset();
                 const leadingPrefix = offset > 0 ? 4 : 0;
                 const shift = leadingPrefix - offset;
-                adjustedMatches = matches.map(m => ({
+                adjustedMatches = r.matches.map(m => ({
                     start: Math.max(0, m.start + shift),
                     end: Math.max(0, m.end + shift),
                 }));
@@ -1884,21 +2234,31 @@ export class AlbexEngine {
             }
             else {
                 const sl = w.getSnippet(i);
-                snippet = sl > 0 ? this._readPad(sl) : '';
+                snippetBytes = sl > 0 ? this._readPadBytes(sl) : new Uint8Array(0);
             }
+            const snippet = snippetBytes.length > 0 ? _dec.decode(snippetBytes) : '';
+            // UTF-16 view of the primary span, ready for `snippet.slice()` —
+            // byte offsets and JS string indices diverge on the first accent
+            // (audit 3.1, the consumer footgun in the main Spanish use case).
+            const snippetStart = utf16IndexAtByte(snippetBytes, primaryStart);
+            const snippetEnd = utf16IndexAtByte(snippetBytes, primaryEnd);
             results.push({
-                documentName: name,
-                location,
-                score,
+                documentName: docName(r.docId),
+                docId: r.docId,
+                location: r.location,
+                chunkId: `${r.docId}::${chunkOrd}`,
+                score: r.score,
                 snippet,
                 matchStart: primaryStart,
                 matchEnd: primaryEnd,
                 matches: adjustedMatches,
+                snippetStart,
+                snippetEnd,
             });
         }
         return results;
     }
-    /** Run all OR branches and merge dedup-by-(doc, location, match). The
+    /** Run all OR branches and merge dedup-by-(chunkId, matchStart). 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. */
@@ -1911,7 +2271,10 @@ export class AlbexEngine {
             w.selectQueryBranch(i);
             const results = this._runSearch(rawQuery, opts);
             for (const r of results) {
-                const key = `${r.documentName}:${r.location}:${r.matchStart}`;
+                // Keyed on chunkId, not (doc, location, matchStart): two sub-chunks
+                // of the same location can hit at the same relative offset, and the
+                // old key silently dropped one of them (audit 3.4).
+                const key = `${r.chunkId}:${r.matchStart}`;
                 if (!seen.has(key)) {
                     seen.add(key);
                     all.push(r);
@@ -1936,10 +2299,12 @@ export class AlbexEngine {
             bloomTested: w.getStatBloomTested(),
             bloomPassed: w.getStatBloomPassed(),
             bitapMatched: w.getStatBitapMatched(),
+            ...this._truncStats(),
         };
         return this._collectResults(count, opts, phraseTokens);
     }
-    /** Returns current engine statistics. */
+    /** Returns current engine statistics (capacities are the RUNTIME values
+     * the engine was initialised with via the `capacity` option). */
     getStats() {
         return {
             documents: this._docs.length,
@@ -1947,9 +2312,9 @@ export class AlbexEngine {
             textUsed: this._wasm.getTextUsed(),
             textCapacity: this._wasm.getTextCapacity(),
             wasmMemoryBytes: this._mem.buffer.byteLength,
-            tier: this._tier,
             maxChunks: this._wasm.getMaxChunks(),
             maxDocs: this._wasm.getMaxDocs(),
+            namePoolBytes: this._wasm.getNameCapacity(),
         };
     }
     /** Returns stats from the most recent search, or null. */
@@ -1993,10 +2358,15 @@ export class AlbexEngine {
         this._resetInner();
     }
     _resetInner() {
-        this._wasm.init();
+        // Re-init with the engine's CONFIGURED capacity, not the std defaults
+        // (`wasm.init()` would silently shrink a 'large'/custom engine). Same
+        // capacities → the WASM side does a plain counter reset, no realloc.
+        const c = this._capacity;
+        this._wasm.initWithCapacity(c.maxDocs, c.maxChunks, c.textPoolBytes, c.namePoolBytes);
         this._docs = [];
         this._lastSearch = null;
         this._diagnostics = [];
+        this._gpuUploadDirty = true;
     }
     /**
      * Drain and return the diagnostics collected since the last call (or
@@ -2145,6 +2515,8 @@ export class AlbexEngine {
             if (w.restoreCommit() !== 1)
                 return false;
         }
+        // The restored chunk array replaces whatever the GPU last saw.
+        this._gpuUploadDirty = true;
         // Rebuild _docs metadata from the restored WASM tables.
         //
         // What's available after a restore: