albex 0.3.0 → 0.6.0

package/src/errors.ts

@@ -51,10 +51,26 @@ export class AlbexParseError extends AlbexError {
   }
 }
 
-/** Thrown when the scratchpad is too small for a single chunk write. */
+/**
+ * Thrown when an indexing operation does not fit: either the scratchpad was
+ * too small for a single write, or one of the engine's pools (chunks, text,
+ * 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
+ * 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.
+ */
+export type AlbexCapacityLimit = 'chunks' | 'text' | 'docs' | 'names' | 'scratchpad';
+
 export class AlbexCapacityError extends AlbexError {
-  constructor(message: string) {
+  /** Which pool overflowed. Undefined for older call sites that didn't set it. */
+  readonly limit?: AlbexCapacityLimit;
+  constructor(message: string, limit?: AlbexCapacityLimit) {
     super('capacity', message);
     this.name = 'AlbexCapacityError';
+    if (limit) this.limit = limit;
   }
 }

package/src/profile.ts

@@ -233,19 +233,20 @@ export async function detectProfile(opts: { fresh?: boolean } = {}): Promise<Dev
 
 // ── Tier selection ───────────────────────────────────────────────────────────
 
-export type Tier = 'mini' | 'std' | 'pro';
+/**
+ * @deprecated The tier system was removed in 0.5.0 (audit 4.1: "6
+ * binaries × no proven benefit"). The type remains exported as `'std'`
+ * for backwards compatibility with code that read `engine.getStats().tier`.
+ */
+export type Tier = 'std';
 
 /**
- * Choose the optimal binary tier from a profile.
- *
- * The thresholds are conservative: a device with `deviceMemory === null`
- * (Safari) defaults to `std` to avoid both over- and under-provisioning.
+ * @deprecated Always returns `'std'` as of 0.5.0. Albex ships exactly
+ * two main binaries (baseline + SIMD); the only runtime variant is the
+ * SIMD probe, not a capacity tier. Kept callable so existing integrators
+ * don't break, but the value has no operational meaning anymore.
  */
-export function pickTier(profile: DeviceProfile): Tier {
-  const m = profile.memoryGB;
-  if (m === null) return 'std';
-  if (m <= 1) return 'mini';
-  if (m >= 8) return 'pro';
+export function pickTier(_profile: DeviceProfile): Tier {
   return 'std';
 }
 

package/src/wasm-bindings.ts

@@ -17,10 +17,21 @@
 export interface AlbexWasmExports {
   readonly memory: WebAssembly.Memory;
 
-  // Scratchpad / lifecycle
+  // ABI / lifecycle
+  abiVersion(): number;
   getBuffer(size: number): number;
   init(): void;
 
+  /** 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. */
+  hashBegin(): void;
+  /** Fold `len` bytes of scratchpad into the streaming hash. May be
+   * called repeatedly for files larger than SCRATCHPAD_SIZE. */
+  hashFeed(len: number): void;
+  /** Write the final 8 raw big-endian bytes at scratchpad[0..8] and
+   * reset the state so the next hash can start without an explicit Begin. */
+  hashFinish(): void;
+
   // Document ingestion
   setDocumentName(len: number): void;
   beginDocument(): number;
@@ -40,6 +51,13 @@ export interface AlbexWasmExports {
   setThreshold(threshold: number): void;
   setMaxResults(max: number): void;
 
+  // Query parsing (since ABI v2). Single source of truth for tokenization.
+  prepareQuery(len: number): number;
+  getQueryKind(): number;
+  getQueryBranchCount(): number;
+  getQueryBranchPattern(i: number): number;
+  selectQueryBranch(i: number): number;
+
   // Search execution
   setPattern(len: number): number;
   search(): number;
@@ -73,12 +91,27 @@ export interface AlbexWasmExports {
   getDocCount(): number;
   getTextUsed(): number;
   getTextCapacity(): number;
+  /** Bitflags of capacity limits hit during the most recent
+   * begin..endDocument cycle: 1 = chunks, 2 = text, 4 = docs, 8 = names.
+   * 0 = everything fit. Read by the host right after endDocument to raise a
+   * typed AlbexCapacityError instead of silently truncating the corpus. */
+  getLastIndexOverflow(): number;
 
-  // Snapshot / restore
+  // Snapshot / restore (v3 protocol; v1 and v2 still load)
   snapshotSize(): number;
   snapshotChunk(offset: number, maxLen: number): number;
+  /** Validate header. For v3 also reserves the staging buffer; state is
+   * NOT touched until restoreCommit succeeds. For v1/v2 (legacy) state is
+   * reset and counters are written immediately. */
   restoreBegin(): number;
+  /** Feed payload bytes. For v3 they accumulate into staging; for v1/v2
+   * they are written straight to the state arrays as before. */
   restoreFeed(len: number): number;
+  /** Atomic commit for v3 snapshots. Returns 1 if the staged payload was
+   * complete and decoded successfully; 0 otherwise — and in the 0 case
+   * the previous engine state is preserved. For v1/v2 this is a no-op
+   * that always returns 1. */
+  restoreCommit(): number;
 
   // Incremental / per-doc
   getDocId(index: number): number;
@@ -126,6 +159,10 @@ export interface AlbexWasmExports {
 export interface AlbexPdfExports {
   readonly memory: WebAssembly.Memory;
 
+  /** ABI version of the PDF module. The host loader refuses any binary
+   * whose abiVersion is outside the supported range. */
+  abiVersion(): number;
+
   /** Reserve `len` bytes inside the PDF module and return a pointer. */
   allocInput(len: number): number;
 
@@ -183,18 +220,130 @@ export interface AlbexPdfExports {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Narrowing helpers for instantiation results
+// Runtime validators
 // ─────────────────────────────────────────────────────────────────────────────
+//
+// These replace the pre-0.5.0 `as unknown as` casts. They check three
+// things at instantiation time:
+//   1. memory is a WebAssembly.Memory instance.
+//   2. abiVersion() returns a number inside the supported range.
+//   3. every required export exists and is a function.
+//
+// If any of these fails, the loader throws a typed error before the
+// engine returns from init(). This eliminates the audit 3.2 issue:
+// previously a missing export only surfaced when its call site ran.
 
-/**
- * Cast `WebAssembly.Exports` to the typed Albex main interface.
- * Runtime check is intentionally minimal — if the .wasm doesn't match,
- * the first call site that touches a missing function throws naturally.
- */
+/** 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;
+
+/** Range of ABI versions for the PDF module. */
+const PDF_ABI_MIN = 1;
+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',
+  'setDocumentName', 'beginDocument', 'feedXmlBytes', 'endDocument',
+  'beginXlsx', 'feedXlsxBytes',
+  'feedText', 'flushParagraph',
+  'setMaxErrors', 'setThreshold', 'setMaxResults',
+  'prepareQuery', 'getQueryKind', 'getQueryBranchCount',
+  'getQueryBranchPattern', 'selectQueryBranch',
+  'setPattern', 'search',
+  'searchBegin', 'searchSlice', 'getSearchCursor', 'getSearchTotal',
+  'getResultCount',
+  'getResultDocId', 'getResultLocation', 'getResultScore',
+  'getResultStart', 'getResultEnd', 'getResultChunkIdx',
+  'getResultDocName', 'getResultMatchCount',
+  'getResultMatchStartAt', 'getResultMatchEndAt',
+  'getSnippet', 'getSnippetWindow', 'getSnippetWindowOffset',
+  'getStatBloomTested', 'getStatBloomPassed', 'getStatBitapMatched',
+  'getChunkCount', 'getDocCount', 'getTextUsed', 'getTextCapacity',
+  'getLastIndexOverflow',
+  'snapshotSize', 'snapshotChunk',
+  'restoreBegin', 'restoreFeed', 'restoreCommit',
+  'getDocId', 'getDocChunkCount', 'getDocName', 'isDocDeleted',
+  'removeDocument', 'compact',
+  'setLanguage',
+  'getTier', 'getMaxChunks', 'getMaxDocs', 'getNameCapacity',
+  'getChunksPtr', 'getChunkStructSize',
+  'setCandidateMask', 'clearCandidateMask',
+  'getDocContentHashPtr', 'getDocContentHashLen', 'setDocumentContentHash',
+  'hashBegin', 'hashFeed', 'hashFinish',
+] as const;
+
+const PDF_REQUIRED = [
+  'abiVersion', 'allocInput', 'extractPdf',
+  'getPageLen', 'getPagePtr', 'getErrorLen', 'getErrorPtr',
+  'getPageCount', 'extractPageImages',
+  'getPageImageLen', 'getPageImagePtr', 'getPageImageKind',
+] as const;
+
+/** Thrown when an instantiated WASM module fails the ABI contract. */
+export class AlbexAbiMismatchError extends Error {
+  readonly module: 'main' | 'pdf';
+  readonly missing?: readonly string[];
+  readonly version?: number;
+  constructor(module: 'main' | 'pdf', message: string, opts?: { missing?: readonly string[]; version?: number }) {
+    super(message);
+    this.name = 'AlbexAbiMismatchError';
+    this.module = module;
+    if (opts?.missing) this.missing = opts.missing;
+    if (opts?.version !== undefined) this.version = opts.version;
+  }
+}
+
+function validateExports(
+  exports: WebAssembly.Exports,
+  required: readonly string[],
+  module: 'main' | 'pdf',
+  abiMin: number,
+  abiMax: number,
+): void {
+  const mem = (exports as Record<string, unknown>)['memory'];
+  if (!(mem instanceof WebAssembly.Memory)) {
+    throw new AlbexAbiMismatchError(module, `${module}: \`memory\` is missing or not a WebAssembly.Memory instance.`);
+  }
+  const missing: string[] = [];
+  for (const name of required) {
+    if (typeof (exports as Record<string, unknown>)[name] !== 'function') missing.push(name);
+  }
+  if (missing.length) {
+    throw new AlbexAbiMismatchError(
+      module,
+      `${module}: WASM binary missing required exports: ${missing.join(', ')}. ` +
+      `The .wasm was built with an incompatible source — rebuild with the current toolchain.`,
+      { missing },
+    );
+  }
+  const version = ((exports as Record<string, unknown>)['abiVersion'] as () => number)();
+  if (version < abiMin || version > abiMax) {
+    throw new AlbexAbiMismatchError(
+      module,
+      `${module}: abiVersion ${version} outside supported range [${abiMin}..${abiMax}]. ` +
+      `The host TypeScript expects a different binary — upgrade albex or rebuild the WASM.`,
+      { version },
+    );
+  }
+}
+
+/** Validate and narrow `WebAssembly.Exports` to the typed Albex main
+ * interface. Throws `AlbexAbiMismatchError` if the contract is broken. */
 export function asAlbexExports(exports: WebAssembly.Exports): AlbexWasmExports {
+  validateExports(exports, MAIN_REQUIRED, 'main', MAIN_ABI_MIN, MAIN_ABI_MAX);
   return exports as unknown as AlbexWasmExports;
 }
 
+/** Validate and narrow `WebAssembly.Exports` to the typed PDF interface. */
 export function asAlbexPdfExports(exports: WebAssembly.Exports): AlbexPdfExports {
+  validateExports(exports, PDF_REQUIRED, 'pdf', PDF_ABI_MIN, PDF_ABI_MAX);
   return exports as unknown as AlbexPdfExports;
 }

package/src/worker-runtime.ts

@@ -75,8 +75,8 @@ async function dispatch(op: WorkerOp): Promise<unknown> {
   }
 }
 
-self.onmessage = async (ev: MessageEvent<WorkerRequest>) => {
-  const { id, op } = ev.data;
+async function handle(req: WorkerRequest): Promise<void> {
+  const { id, op } = req;
   try {
     const result = await dispatch(op);
     const res: WorkerResponse = { id, ok: true, result };
@@ -93,4 +93,14 @@ self.onmessage = async (ev: MessageEvent<WorkerRequest>) => {
     };
     (self as unknown as Worker).postMessage(res);
   }
+}
+
+// Process messages strictly in arrival order. The engine guards its own
+// state, but a sync `search` arriving mid-`indexFile` await would otherwise
+// be rejected as "busy"; queueing keeps the worker's externally-observable
+// behaviour serial and matches the main-thread engine's serialization.
+let _queue: Promise<void> = Promise.resolve();
+self.onmessage = (ev: MessageEvent<WorkerRequest>) => {
+  const req = ev.data;
+  _queue = _queue.then(() => handle(req));
 };