albex 0.6.0 → 0.7.0

package/src/errors.ts

@@ -57,20 +57,65 @@ export class AlbexParseError extends AlbexError {
  * documents, names) ran out of room mid-document. Before 0.6.0 the latter was
  * silent — the corpus was truncated with no signal.
  *
- * `limit` names which pool overflowed (or `'scratchpad'`), so callers can
+ * `limit` names which pool overflowed (or `'scratchpad'`, or `'file'` when an
+ * input file exceeds `maxFileBytes` before any byte is read), so callers can
  * branch — e.g. start a fresh shard, `compact()`, or surface "library full".
  * When a capacity error is raised during `indexFile`, the engine may hold a
  * partially-indexed copy of the offending document; treat the index as full
- * and stop adding.
+ * and stop adding. A `'file'` capacity error is raised BEFORE the file is
+ * read, so the index is untouched and fully usable.
  */
-export type AlbexCapacityLimit = 'chunks' | 'text' | 'docs' | 'names' | 'scratchpad';
+export type AlbexCapacityLimit = 'chunks' | 'text' | 'docs' | 'names' | 'scratchpad' | 'file';
 
 export class AlbexCapacityError extends AlbexError {
   /** Which pool overflowed. Undefined for older call sites that didn't set it. */
   readonly limit?: AlbexCapacityLimit;
-  constructor(message: string, limit?: AlbexCapacityLimit) {
+  /**
+   * The RUNTIME numeric capacity of the pool named by `limit`, as the
+   * engine is actually configured (e.g. `4` when `capacity: { maxDocs: 4 }`
+   * overflows its document table, `128` for the std default). Units: docs
+   * for `'docs'`, chunks for `'chunks'`, bytes for `'text'`/`'names'`/
+   * `'scratchpad'`/`'file'`. Undefined when the limit is not known at the
+   * throw site.
+   */
+  readonly max?: number;
+  constructor(message: string, limit?: AlbexCapacityLimit, max?: number) {
     super('capacity', message);
     this.name = 'AlbexCapacityError';
     if (limit) this.limit = limit;
+    if (max !== undefined) this.max = max;
+  }
+}
+
+/**
+ * Default `maxFileBytes` for `indexFile`: 256 MiB. Far above anything the
+ * ~16–21 MB text pool could ever absorb, so legitimate documents are never
+ * rejected — the guard only exists to refuse pathological inputs (a 2 GB
+ * file would otherwise be fully buffered AND hashed before the first
+ * capacity check could fire).
+ */
+export const DEFAULT_MAX_FILE_BYTES = 256 * 1024 * 1024;
+
+/**
+ * Pre-read size guard for `indexFile`. Throws a typed
+ * {@link AlbexCapacityError} (`limit: 'file'`) when `file.size` exceeds the
+ * configured cap — BEFORE any byte of the file is read into memory
+ * (`File`/`Blob` expose `size` without reading). Shared by the engine, the
+ * worker wrapper and the pool coordinator so the guard fires on whichever
+ * thread would otherwise buffer the bytes.
+ */
+export function assertFileSizeWithinLimit(
+  file: { name: string; size: number },
+  maxFileBytes?: number,
+): void {
+  const cap = maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+  if (file.size > cap) {
+    throw new AlbexCapacityError(
+      `"${file.name}" is ${file.size} bytes, above the maxFileBytes limit of ` +
+      `${cap}. The file was not read or indexed. Raise \`maxFileBytes\` in ` +
+      `AlbexOptions if this is intentional.`,
+      'file',
+      cap,
+    );
   }
 }

package/src/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Albex — public entry point. Install, import, use:
+ *
+ * ```ts
+ * import { AlbexEngine } from 'albex';
+ *
+ * const engine = new AlbexEngine();   // nothing to serve, nothing to configure
+ * await engine.init();
+ * ```
+ *
+ * The ~47 KB baseline core is base64-embedded in this module (decoded once,
+ * lazily; ~19 KB gzipped over the wire). `new AlbexEngine()` instantiates
+ * those bytes directly — NO network fetch, NO `new URL('…wasm',
+ * import.meta.url)` asset resolution — so it works in **every** bundler,
+ * esbuild / Angular / Webpack included, with zero setup.
+ *
+ * Advanced options stay available and are never required:
+ *   - `wasmBaseUrl` — serve the baseline + SIMD binaries yourself (gets you
+ *     the SIMD core on capable hosts; the embedded default is baseline-only).
+ *   - `wasmUrl` — a single explicit core URL (e.g. a CDN).
+ *   - `wasmBytes` — hand the engine bytes you loaded yourself.
+ * When any of these is set, the embedded core is bypassed.
+ *
+ * The PDF module (~1.2 MB) is too large to embed; it still loads on demand
+ * from `pdfWasmUrl` (default: resolved next to the package) or `pdfWasmBytes`.
+ *
+ * Everything else (`AlbexPool`, `TieredStore`, errors, types, …) is
+ * re-exported unchanged.
+ */
+
+import { AlbexEngine as CoreAlbexEngine, type AlbexOptions } from './albex.js';
+import { ALBEX_WASM_BASE64 } from './_generated/inline-wasm.js';
+
+// Re-export the whole public surface. The local `AlbexEngine` declared below
+// takes precedence over the one this star-export would otherwise bring in.
+export * from './albex.js';
+
+function decodeBase64(b64: string): Uint8Array {
+  // `atob` exists in the DOM and in Node ≥ 18 (this package's floor), so no
+  // Buffer / environment branch is needed.
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+let _cached: Uint8Array | null = null;
+
+/**
+ * The embedded baseline core as raw bytes. Decoded from base64 on first call
+ * and cached, so multiple engines share one decode. Exposed for callers that
+ * want the bytes directly (e.g. to seed a worker with the same core).
+ */
+export function albexWasmBytes(): Uint8Array {
+  if (!_cached) _cached = decodeBase64(ALBEX_WASM_BASE64);
+  return _cached;
+}
+
+/**
+ * The Albex search engine, pre-wired with the embedded baseline core. Pass
+ * any normal {@link AlbexOptions}; an explicit `wasmBytes` / `wasmUrl` /
+ * `wasmBaseUrl` you supply takes over, so advanced (SIMD / CDN) setups keep
+ * working unchanged.
+ */
+export class AlbexEngine extends CoreAlbexEngine {
+  constructor(opts: AlbexOptions = {}) {
+    // Inject the embedded core only when the caller hasn't chosen a source.
+    // This keeps the engine a strict superset of the URL-based core: every
+    // existing option behaves exactly as before.
+    const hasSource =
+      opts.wasmBytes != null || opts.wasmUrl != null || opts.wasmBaseUrl != null;
+    // The cast bridges TS 5.7's `BufferSource` (which excludes
+    // `Uint8Array<ArrayBufferLike>` over SharedArrayBuffer variance) — a
+    // plain Uint8Array is a valid BufferSource at runtime.
+    super(
+      hasSource
+        ? opts
+        : { ...opts, wasmBytes: albexWasmBytes() as BufferSource },
+    );
+  }
+}

package/src/inline.ts

@@ -0,0 +1,9 @@
+/**
+ * `albex/inline` — compatibility alias for the default entry.
+ *
+ * The embedded core is now the DEFAULT (`import { AlbexEngine } from 'albex'`
+ * already needs no setup), so this subpath exists only so existing
+ * `from 'albex/inline'` imports keep resolving. It re-exports the default
+ * entry verbatim — there is no behavioural difference.
+ */
+export * from './index.js';

package/src/pool/coordinator.ts

@@ -30,9 +30,8 @@ import type {
   EngineStats,
   SearchStats,
 } from '../albex.js';
-import type { Tier } from '../profile.js';
 import { detectProfile, pickWorkerCount } from '../profile.js';
-import { AlbexInitError, AlbexError } from '../errors.js';
+import { AlbexInitError, AlbexError, assertFileSizeWithinLimit } from '../errors.js';
 import type {
   WorkerRequest,
   WorkerResponse,
@@ -77,7 +76,9 @@ export class AlbexPool {
   private _docsCache: IndexedDocument[] = [];
   private _rrCursor = 0;
   private _lastSearch: SearchStats | null = null;
-  private _tier: Tier | null = null;
+  /** Global result cap applied AFTER the cross-shard merge. Mirrors the
+   * last `setMaxResults` call (the WASM engine default is 50). */
+  private _maxResults = 50;
 
   constructor(opts: AlbexPoolOptions) {
     this._opts = opts;
@@ -98,23 +99,21 @@ export class AlbexPool {
       console.warn('[albex] pool mode=shared requested but cross-origin isolation is not active; falling back to replicated');
     }
 
-    const shardOpts: AlbexOptions = {
-      wasmUrl:     this._opts.wasmUrl,
-      wasmBaseUrl: this._opts.wasmBaseUrl,
-      pdfWasmUrl:  this._opts.pdfWasmUrl,
-      tier:        this._opts.tier,
-      simd:        this._opts.simd,
-    };
+    // Forward every serializable engine option to the shards; strip the
+    // pool-only fields (workerUrl/workers/mode) and anything non-clonable.
+    // Same policy as AlbexEngineWorker.init (audit 1.4).
+    const shardOpts: AlbexOptions = {};
+    for (const [k, v] of Object.entries(this._opts)) {
+      if (k === 'workerUrl' || k === 'workers' || k === 'mode') continue;
+      if (v === undefined || typeof v === 'function') continue;
+      (shardOpts as Record<string, unknown>)[k] = v;
+    }
 
     for (let i = 0; i < n; i++) {
       const shard = this._spawnShard();
       await this._send(shard, { kind: 'init', opts: shardOpts });
       this._shards.push(shard);
     }
-
-    // Tier is the same across shards — capture it from shard 0 stats.
-    const stats0 = await this._send<EngineStats>(this._shards[0]!, { kind: 'getStats' });
-    this._tier = stats0.tier;
   }
 
   // ── Shard plumbing ─────────────────────────────────────────────────────
@@ -168,6 +167,9 @@ export class AlbexPool {
 
   async indexFile(file: File): Promise<IndexedDocument> {
     if (this._shards.length === 0) throw new AlbexInitError('Pool not initialised');
+    // Size guard BEFORE reading — same limit the shard engine enforces, but
+    // checked here so an oversized file is never buffered on the main thread.
+    assertFileSizeWithinLimit(file, this._opts.maxFileBytes);
     const idx = this._rrCursor++ % this._shards.length;
     const shard = this._shards[idx]!;
     const buffer = await file.arrayBuffer();
@@ -185,30 +187,50 @@ export class AlbexPool {
    * Map-reduce search:
    *   1. broadcast the query to every shard,
    *   2. each shard runs its local Bloom→Bitap→top-K,
-   *   3. coordinator merges the K-best from each shard,
+   *   3. coordinator merges the K-best from each shard, deduplicating
+   *      identical hits (same document name, chunk id and match offset —
+   *      the case where the same file was indexed into two shards),
    *   4. global top-K returned in descending score order.
    *
    * Capped to `setMaxResults` results (default 50) AFTER merge.
+   *
+   * Per-shard search stats are requested in the same posting batch as the
+   * search itself: each worker processes its queue in arrival order, so the
+   * stats reply is guaranteed to belong to THIS query even when several
+   * `search()` calls overlap.
    */
   async search(query: string, opts: SearchOptions = {}): Promise<SearchResult[]> {
     if (this._shards.length === 0) return [];
     const t0 = performance.now();
-    const buckets = await Promise.all(
-      this._shards.map(s => this._send<SearchResult[]>(s, { kind: 'search', query, options: opts })),
+    // Post `search` and `getLastSearchStats` back-to-back (synchronously,
+    // per shard) so no other request can slot between them in the worker's
+    // FIFO queue — the stats round can't race a subsequent search.
+    const perShard = await Promise.all(
+      this._shards.map(s => {
+        const results = this._send<SearchResult[]>(s, { kind: 'search', query, options: opts });
+        const stats   = this._send<SearchStats | null>(s, { kind: 'getLastSearchStats' });
+        return Promise.all([results, stats] as const);
+      }),
     );
 
-    // Merge: simple flatten + sort (descending). Each shard already returned
-    // up to its local cap; the global cap could be different but in practice
-    // matches the per-shard cap.
-    const merged = buckets.flat();
+    // Merge: flatten + dedup + sort (descending) + global cap. Shard-local
+    // docIds collide across shards, so the dedup identity also includes the
+    // document name: it only collapses true duplicates (the same document
+    // indexed into more than one shard yields identical name/chunkId/offset).
+    const seen = new Set<string>();
+    const merged: SearchResult[] = [];
+    for (const [bucket] of perShard) {
+      for (const r of bucket) {
+        const key = `${r.documentName}:${r.chunkId}:${r.matchStart}`;
+        if (!seen.has(key)) { seen.add(key); merged.push(r); }
+      }
+    }
     merged.sort((a, b) => b.score - a.score);
+    const capped = merged.slice(0, this._maxResults);
 
     // Aggregate search stats across shards.
-    const stats = await Promise.all(
-      this._shards.map(s => this._send<SearchStats | null>(s, { kind: 'getLastSearchStats' })),
-    );
     let bloomTested = 0, bloomPassed = 0, bitapMatched = 0;
-    for (const s of stats) {
+    for (const [, s] of perShard) {
       if (!s) continue;
       bloomTested  += s.bloomTested;
       bloomPassed  += s.bloomPassed;
@@ -217,11 +239,11 @@ export class AlbexPool {
     this._lastSearch = {
       query,
       timeMs: performance.now() - t0,
-      results: merged.length,
+      results: capped.length,
       bloomTested, bloomPassed, bitapMatched,
     };
 
-    return merged;
+    return capped;
   }
 
   /**
@@ -273,11 +295,13 @@ export class AlbexPool {
     for (const s of this._shards) s.docCount = 0;
   }
 
-  /** Aggregate engine stats across all shards. */
+  /** Aggregate engine stats across all shards. Capacities are the RUNTIME
+   * per-shard capacities summed (each shard was initialised with the same
+   * `capacity` option, forwarded through the wire protocol). */
   async getStats(): Promise<EngineStats> {
     const all = await this._broadcast<EngineStats>({ kind: 'getStats' });
     let documents = 0, chunks = 0, textUsed = 0, textCapacity = 0, wasmMemoryBytes = 0;
-    let maxChunks = 0, maxDocs = 0;
+    let maxChunks = 0, maxDocs = 0, namePoolBytes = 0;
     for (const s of all) {
       documents       += s.documents;
       chunks          += s.chunks;
@@ -286,10 +310,11 @@ export class AlbexPool {
       wasmMemoryBytes += s.wasmMemoryBytes;
       maxChunks       += s.maxChunks;
       maxDocs         += s.maxDocs;
+      namePoolBytes   += s.namePoolBytes;
     }
     return {
       documents, chunks, textUsed, textCapacity, wasmMemoryBytes,
-      tier: this._tier, maxChunks, maxDocs,
+      maxChunks, maxDocs, namePoolBytes,
     };
   }
 
@@ -303,15 +328,17 @@ export class AlbexPool {
 
   async setMaxErrors(n: 0 | 1 | 2 | 3):       Promise<void> { await this._broadcast({ kind: 'setMaxErrors',  n }); }
   async setThreshold(n: number):              Promise<void> { await this._broadcast({ kind: 'setThreshold', n }); }
-  async setMaxResults(n: number):             Promise<void> { await this._broadcast({ kind: 'setMaxResults', n }); }
+  async setMaxResults(n: number):             Promise<void> {
+    // Track the effective cap (same clamp as the WASM engine) so search()
+    // can enforce it globally after the cross-shard merge.
+    this._maxResults = Math.max(1, Math.min(200, Math.floor(n)));
+    await this._broadcast({ kind: 'setMaxResults', n });
+  }
   async setLanguage(lang: 'off' | 'es'):      Promise<void> { await this._broadcast({ kind: 'setLanguage', lang }); }
 
   /** Number of shards currently running. */
   get workerCount(): number { return this._shards.length; }
 
-  /** Tier loaded by the shards (same value across all of them). */
-  get tier(): Tier | null { return this._tier; }
-
   [Symbol.dispose](): void {
     for (const s of this._shards) {
       for (const [, p] of s.pending) p.reject(new AlbexError('disposed', 'Pool disposed'));

package/src/wasm-bindings.ts

@@ -20,7 +20,23 @@ export interface AlbexWasmExports {
   // ABI / lifecycle
   abiVersion(): number;
   getBuffer(size: number): number;
+  /** Reset with the std default capacities (128 docs · 100k chunks · 16 MB
+   * text · 32 KB names) — identical behaviour to every pre-ABI-7 release. */
   init(): void;
+  /** (Re-)initialise the engine with runtime capacities (ABI 7, decision
+   * A16). Allocates the capacity-dependent pools on the WASM heap. Returns
+   * 1 on success; 0 on invalid parameters (floors/ceilings documented in
+   * wasm/src/lib.rs: ≥1 doc, docs ≤ 65 536, chunks ≥ docs and ≤ 4 M, text
+   * pool 4 KiB–1 GiB, name pool 256 B–16 MiB) or on allocation failure —
+   * never traps. Re-init with the same capacities is a plain reset; with
+   * different capacities the pools are freed and re-allocated (no leak,
+   * but the linear-memory high-water mark never shrinks). */
+  initWithCapacity(
+    maxDocs: number,
+    maxChunks: number,
+    textPoolBytes: number,
+    namePoolBytes: number,
+  ): number;
 
   /** Reset the streaming FNV-1a 64-bit hash state. Optional on the first
    * hash of a session because the static initialiser is also FNV_OFFSET. */
@@ -57,6 +73,11 @@ export interface AlbexWasmExports {
   getQueryBranchCount(): number;
   getQueryBranchPattern(i: number): number;
   selectQueryBranch(i: number): number;
+  /** Bitflags of what the most recent prepareQuery dropped or clipped
+   * (ABI 5): 1 = OR branches beyond 8 discarded, 2 = tokens dropped
+   * (> 4 per branch) or clipped (> 64 bytes), 4 = raw query cut at
+   * 1024 bytes. 0 = compiled in full. */
+  getQueryTruncationFlags(): number;
 
   // Search execution
   setPattern(len: number): number;
@@ -68,6 +89,15 @@ export interface AlbexWasmExports {
   getSearchTotal(): number;
 
   // Result accessors
+  /** Base pointer of the `#[repr(C)]` RESULTS array (ABI 6). Read
+   * `getResultCount()` records of `getResultStride()` bytes each with one
+   * DataView pass instead of ~12 frontier calls per result. Field offsets
+   * are documented (and compile-time asserted) in wasm/src/lib.rs. Copy
+   * everything out before any call that could grow WASM memory. */
+  getResultsPtr(): number;
+  /** Byte stride between consecutive RESULTS records (= sizeof(DocMatch),
+   * 60 today). Exported so the host never hardcodes the struct size. */
+  getResultStride(): number;
   getResultCount(): number;
   getResultDocId(i: number): number;
   getResultLocation(i: number): number;
@@ -121,6 +151,27 @@ export interface AlbexWasmExports {
   removeDocument(docId: number): number;
   compact(): void;
 
+  // Authoritative chunk enumeration (ABI 4). Address a document's chunks by
+  // (doc slot, ordinal). The compact()-stable key is (doc_id, ordinal).
+  /** First CHUNKS[] index for the document at slot `index` (= chunk_start).
+   * `ord = resultChunkIdx - getDocChunkBase(slot)` gives the doc-relative
+   * ordinal of a search hit. */
+  getDocChunkBase(index: number): number;
+  /** `location` (paragraph/page) of the `ord`-th chunk; u32::MAX if OOB. */
+  getChunkLocationAt(index: number, ord: number): number;
+  /** Byte length of the `ord`-th chunk's text; 0 if OOB. */
+  getChunkByteLenAt(index: number, ord: number): number;
+  /** Copy the `ord`-th chunk's UTF-8 text into the scratchpad; returns byte
+   * length (0 if OOB). Lets a host enumerate a doc's authoritative chunks
+   * right after indexing, with no query. */
+  getChunkTextAt(index: number, ord: number): number;
+  /** Batch chunk enumeration (ABI 6). Packs up to `maxChunks` records
+   * `[u32 text_len][u32 location][text bytes]` (LE, tightly packed) into
+   * the scratchpad starting at ordinal `startOrd`; returns how many were
+   * written. One frontier call per scratchpad-full instead of 2-3 per
+   * chunk. */
+  listChunksBatch(index: number, startOrd: number, maxChunks: number): number;
+
   /**
    * Per-document content hash (snapshot v2). Returns a pointer to 8 bytes
    * holding the FNV-1a 64-bit hash of the original file bytes, or 0 if the
@@ -139,8 +190,8 @@ export interface AlbexWasmExports {
   // Stemming
   setLanguage(lang: number): void;
 
-  // Tier identification
-  getTier(): number;        // 1=mini, 2=std, 3=pro
+  // Runtime capacity identification (ABI 7). Report the capacities the
+  // engine was last initialised with — `init()` = the std defaults.
   getMaxChunks(): number;
   getMaxDocs(): number;
   getNameCapacity(): number;
@@ -150,6 +201,13 @@ export interface AlbexWasmExports {
   getChunkStructSize(): number;
   setCandidateMask(byteLen: number): void;
   clearCandidateMask(): void;
+  /** Low 32 bits of the active pattern's aggregate character Bloom
+   * (ABI 6). Computed WASM-side in setPattern through the same pipeline
+   * searchBegin uses (split → optional stemming → fold), so the GPU
+   * pre-filter tests exactly the bits the CPU path would. */
+  getPatternBloomLo(): number;
+  /** High 32 bits of the active pattern's aggregate character Bloom. */
+  getPatternBloomHi(): number;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -236,12 +294,17 @@ export interface AlbexPdfExports {
 /** Range of ABI versions this host code understands for the main module.
  * Update both ends together with the Rust `abiVersion()` constant when
  * the export surface changes. */
-// 0.6.0 requires ABI 3 (trigram pre-filter + getLastIndexOverflow). The
-// required-exports list below already makes any older binary fail the
-// missing-exports check, so a tolerant lower bound was dead code — the range
-// is pinned to the one ABI this host actually speaks (audit 0.6.0, finding #7).
-const MAIN_ABI_MIN = 3;
-const MAIN_ABI_MAX = 3;
+// ABI 7 adds runtime capacity (initWithCapacity, decision A16) and removes
+// the compile-time tier system (`getTier` is gone), on top of ABI 6's batch
+// frontier reads, ABI 5's truncation signalling and ABI 4's authoritative
+// chunk enumeration. The required-exports list below already makes any
+// older binary fail the missing-exports check, so a tolerant lower bound
+// was dead code — the range is pinned to the one ABI this host actually
+// speaks (audit 0.6.0, finding #7). The .wasm ships inside this package
+// (files: wasm/pkg/*.wasm), so host TS and binary are always
+// version-matched.
+const MAIN_ABI_MIN = 7;
+const MAIN_ABI_MAX = 7;
 
 /** Range of ABI versions for the PDF module. */
 const PDF_ABI_MIN = 1;
@@ -250,16 +313,16 @@ const PDF_ABI_MAX = 3;
 /** Required function names on the main WASM. Adding a new one here forces
  * the validator to check it; removing one is a breaking ABI bump. */
 const MAIN_REQUIRED = [
-  'abiVersion', 'getBuffer', 'init',
+  'abiVersion', 'getBuffer', 'init', 'initWithCapacity',
   'setDocumentName', 'beginDocument', 'feedXmlBytes', 'endDocument',
   'beginXlsx', 'feedXlsxBytes',
   'feedText', 'flushParagraph',
   'setMaxErrors', 'setThreshold', 'setMaxResults',
   'prepareQuery', 'getQueryKind', 'getQueryBranchCount',
-  'getQueryBranchPattern', 'selectQueryBranch',
+  'getQueryBranchPattern', 'selectQueryBranch', 'getQueryTruncationFlags',
   'setPattern', 'search',
   'searchBegin', 'searchSlice', 'getSearchCursor', 'getSearchTotal',
-  'getResultCount',
+  'getResultCount', 'getResultsPtr', 'getResultStride',
   'getResultDocId', 'getResultLocation', 'getResultScore',
   'getResultStart', 'getResultEnd', 'getResultChunkIdx',
   'getResultDocName', 'getResultMatchCount',
@@ -272,10 +335,13 @@ const MAIN_REQUIRED = [
   'restoreBegin', 'restoreFeed', 'restoreCommit',
   'getDocId', 'getDocChunkCount', 'getDocName', 'isDocDeleted',
   'removeDocument', 'compact',
+  'getDocChunkBase', 'getChunkLocationAt', 'getChunkByteLenAt', 'getChunkTextAt',
+  'listChunksBatch',
   'setLanguage',
-  'getTier', 'getMaxChunks', 'getMaxDocs', 'getNameCapacity',
+  'getMaxChunks', 'getMaxDocs', 'getNameCapacity',
   'getChunksPtr', 'getChunkStructSize',
   'setCandidateMask', 'clearCandidateMask',
+  'getPatternBloomLo', 'getPatternBloomHi',
   'getDocContentHashPtr', 'getDocContentHashLen', 'setDocumentContentHash',
   'hashBegin', 'hashFeed', 'hashFinish',
 ] as const;

package/src/worker-protocol.ts

@@ -10,13 +10,19 @@
  * copying the file bytes into the worker.
  */
 
-import type { AlbexOptions, IndexedDocument, SearchOptions, SearchResult, EngineStats, SearchStats } from './albex.js';
+import type { AlbexDiagnostic, AlbexOptions, AuthoritativeChunk, IndexedDocument, SearchOptions, SearchResult, EngineStats, SearchStats } from './albex.js';
 
 export type WorkerOp =
   | { kind: 'init';            opts: AlbexOptions }
   | { kind: 'indexFile';        name: string; buffer: ArrayBuffer }
   | { kind: 'search';           query: string; options: SearchOptions }
+  | { kind: 'listChunks';       docId: number }
   | { kind: 'removeDocument';   id: string }
+  /** Replace doc `name` with new content. `fileName` is the replacement
+   * file's own name (may differ from `name`); the bytes travel as a
+   * transferred ArrayBuffer like `indexFile`. */
+  | { kind: 'replaceDocument';  name: string; fileName: string; buffer: ArrayBuffer }
+  | { kind: 'takeDiagnostics' }
   | { kind: 'compact' }
   | { kind: 'reset' }
   | { kind: 'getStats' }
@@ -39,10 +45,14 @@ export interface WorkerRequest {
 
 export type WorkerResponse =
   | { id: number; ok: true;  result: unknown }
-  | { id: number; ok: false; error: { name: string; kind?: string; message: string } };
+  /** `limit`/`max` are populated for capacity errors so the rehydrated
+   * AlbexCapacityError keeps reporting the runtime limit that overflowed. */
+  | { id: number; ok: false; error: { name: string; kind?: string; message: string; limit?: string; max?: number } };
 
 export type IndexFileResult = IndexedDocument;
 export type SearchResultArr = SearchResult[];
+export type ChunksResult    = AuthoritativeChunk[];
 export type StatsResult     = EngineStats;
 export type SearchStatsRes  = SearchStats | null;
 export type DocsResult      = readonly IndexedDocument[];
+export type DiagnosticsRes  = AlbexDiagnostic[];

package/src/worker-runtime.ts

@@ -36,8 +36,18 @@ async function dispatch(op: WorkerOp): Promise<unknown> {
     }
     case 'search':
       return ensureEngine().search(op.query, op.options);
+    case 'listChunks':
+      return ensureEngine().listChunks(op.docId);
     case 'removeDocument':
       return ensureEngine().removeDocument(op.id);
+    case 'replaceDocument': {
+      // Same File-like wrapping as indexFile; the engine's replaceDocument
+      // handles remove + re-index + auto-compact under its own lock.
+      const file = new File([op.buffer], op.fileName);
+      return ensureEngine().replaceDocument(op.name, file);
+    }
+    case 'takeDiagnostics':
+      return ensureEngine().takeDiagnostics();
     case 'compact':
       ensureEngine().compact();
       return undefined;
@@ -82,13 +92,18 @@ async function handle(req: WorkerRequest): Promise<void> {
     const res: WorkerResponse = { id, ok: true, result };
     (self as unknown as Worker).postMessage(res);
   } catch (err) {
-    const e = err as Error & { kind?: string };
+    const e = err as Error & { kind?: string; limit?: string; max?: number };
     const res: WorkerResponse = {
       id, ok: false,
       error: {
         name:    e.name ?? 'Error',
         kind:    err instanceof AlbexError ? err.kind : undefined,
         message: e.message ?? String(err),
+        // Capacity metadata (which pool + its runtime limit) — plain data,
+        // survives structuredClone, lets the main side rehydrate a full
+        // AlbexCapacityError.
+        limit:   typeof e.limit === 'string' ? e.limit : undefined,
+        max:     typeof e.max === 'number' ? e.max : undefined,
       },
     };
     (self as unknown as Worker).postMessage(res);