albex 0.1.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,416 @@
+# Changelog
+
+All notable changes to Albex are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and Albex follows [Semantic Versioning](https://semver.org/).
+
+## [0.6.0] — 2026-05-31
+
+Release de auditoría algorítmica + robustez. Cierra los hallazgos #1–#8 de
+la revisión externa en profundidad: sube la selectividad del pre-filtro de
+forma drástica, elimina dos clases de corrupción/pérdida silenciosa de
+datos, y de paso corrige una falta de _soundness_ del filtro Bloom bajo
+matching difuso que existía desde el principio. El binario crece ~2 KB
+(33 KB baseline · 37 KB SIMD) por el código del pre-filtro de trigramas.
+
+### Breaking changes
+
+- **ABI WASM v2 → v3** (hallazgo #7). El binario principal exporta ahora
+  `getLastIndexOverflow` y el host fija el rango ABI aceptado a `[3, 3]`
+  (antes `[1, 2]`, con un mínimo inalcanzable que la lista de exports
+  requeridos ya hacía imposible). Un `.wasm` cacheado de 0.5.x falla con
+  `AlbexAbiMismatchError` claro en `init()` en vez de petar más tarde.
+
+### Added
+
+- **Pre-filtro de trigramas q-gram** (hallazgo #1). El Bloom de 64 bits
+  (un bit por `c & 0x3F`) está saturado en chunks de prosa de 512 bytes —
+  cada chunk contiene casi todo el alfabeto, así que no poda y el Bitap
+  acababa ejecutándose sobre todo el corpus. Se añade una firma de 256
+  bits de los **trigramas** de cada chunk (`CHUNK_SIG`, BSS, no infla el
+  `.wasm`) como segundo pre-filtro mucho más selectivo. Es **sound bajo
+  matching difuso**: una ocurrencia con `e` errores conserva ≥ `N − 3e`
+  de los trigramas exactos del token (lema q-gram), y la firma no tiene
+  falsos negativos, así que nunca descarta un match real — solo poda
+  chunks que demostrablemente no pueden contenerlo. El Bitap confirma
+  cada superviviente: la corrección no cambia, solo se encoge el conjunto
+  candidato.
+- **`AlbexCapacityError` con campo `limit`** (`'chunks' | 'text' | 'docs'
+  | 'names'`). El nuevo export `getLastIndexOverflow()` señaliza qué pool
+  se llenó durante el último `begin..endDocument`.
+
+### Fixed
+
+- **Pérdida silenciosa de datos al agotar capacidad** (hallazgo #3). Los
+  pools del WASM se llenaban en silencio y `indexFile` devolvía un
+  documento a medio indexar indistinguible de uno completo (`getStats()`
+  mentía). Ahora `indexFile` lee el overflow y lanza `AlbexCapacityError`.
+  El documento que desborda se **revierte atómicamente** en el WASM
+  (`endDocument` restaura `chunk_count`/`text_used`/`name_used` al inicio
+  del doc): indexación all-or-nothing por fichero, sin chunks huérfanos
+  sin nombre.
+- **Re-entrancy en el path async** (hallazgo #2). Una única instancia WASM
+  con estado global y ops async que ceden al scheduler entre slices: dos
+  operaciones solapadas se corrompían (un `searchBegin` nuevo reseteaba el
+  cursor de una búsqueda cooperativa en vuelo). Las ops async se serializan
+  ahora con una cola interna; los mutadores/búsquedas síncronos rechazan
+  ejecutarse a media operación (`AlbexError` kind `'busy'`) en vez de
+  corromper. El worker-runtime procesa mensajes estrictamente en orden.
+- **Bloom no-sound bajo fuzzy** (corolario del #1). El filtro Bloom de
+  caracteres rechazaba un match aproximado cuando el carácter sustituido
+  no estaba en el chunk (bug latente pre-0.6.0). Ahora el Bloom solo se
+  aplica a tokens exactos (`eff_errors == 0`); los tokens difusos se
+  filtran solo con el conteo de trigramas, que sí es sound.
+- **Frase + `windowed`** (hallazgo #7). El post-filtro de frase corría
+  contra el snippet recortado, así que `{ windowed: true }` podía descartar
+  un match válido cuyo segundo término caía fuera de la ventana. Ahora la
+  comprobación de adyacencia corre contra el **texto completo** del chunk;
+  el windowing solo afecta a la visualización.
+- **GPU + OR**: el hash del pre-filtro GPU usaba siempre el patrón de la
+  rama 0, generando una máscara de candidatos errónea para las ramas i≠0 de
+  una query OR y descartando sus hits en silencio (hallazgo #6).
+- **Corte de chunk a mitad de codepoint UTF-8** (hallazgo #7): el corte duro
+  a 512 bytes podía partir una secuencia multibyte; ahora retrocede a la
+  frontera de codepoint y el snippet del borde no renderiza `�`.
+- **`replaceDocument` sin reclamar espacio** (hallazgo #7): repetidos
+  replaces dejaban tombstones en el text pool; ahora se compacta de forma
+  oportunista bajo presión.
+
+### Performance
+
+- `prepareQuery` ya no hace un `memset` de 64 KB en pila por query (hallazgo
+  #4). La query de trabajo se acota a `MAX_QUERY_BYTES` (1 KB).
+
+### Tooling
+
+- `npm run relaunch`: limpia artefactos, recompila WASM (baseline + SIMD) +
+  PDF + TS + OCR, corre los tests, empaqueta la librería (`npm pack`) y
+  levanta el demo en `http://localhost:5173/demo/`. Scripts auxiliares
+  `clean` / `clean:all` / `build:ocr`.
+- Cobertura: +16 tests (110 en total) — selectividad del trigram, soundness
+  fuzzy, supervivencia de firmas tras compact/restore, error de capacidad,
+  guard de concurrencia, frase+windowed.
+
+## [0.5.0] — 2026-05-30
+
+Release de endurecimiento — cierra las cinco clases de bugs accionables
+de la auditoría externa de código. Sin nuevas features que pidan datos
+reales para ser correctas. El binario crece ~2 KB respecto a 0.4.0 por
+la lógica de query parsing en Rust + ABI version.
+
+### Breaking changes
+
+- **`@albex/ocr` ahora requiere `engine.attachOcr()`** (audit 3.8). El
+  patrón anterior de mutar `engine.ocrImage = ...` y
+  `engine.ocrConfig = ...` directamente queda eliminado. Para
+  integradores que usaban `@albex/ocr`, **el cambio es transparente** —
+  `enableOcr(engine)` sigue siendo la misma llamada. Para quien tuviera
+  un adaptador manual: usar `engine.attachOcr({ recognize, options })`.
+- **Tiers eliminados** (audit 4.1). Mini/std/pro × baseline/SIMD (6
+  binarios) consolidados a **baseline + SIMD** (2 binarios). El
+  parámetro `tier` de `AlbexOptions` queda como noop deprecado. El alias
+  `albex_wasm_bg.wasm` se mantiene para compatibilidad con `0.4.x`.
+- `pickTier(profile)` siempre devuelve `'std'` ahora. La función queda
+  exportada para compatibilidad de código fuente, no de comportamiento.
+
+### Fixed
+
+- **Validación runtime de la ABI WASM** (audit 3.2). `asAlbexExports` y
+  `asAlbexPdfExports` ya no son `as unknown as` ceremoniales — verifican
+  que `memory` sea una `WebAssembly.Memory`, que cada export requerido
+  exista, y que `abiVersion()` esté en el rango soportado. Lanzan
+  `AlbexAbiMismatchError` con la lista de exports faltantes cuando algo
+  no encaja. Antes, un binario incompatible instanciaba en silencio y
+  petaba en el primer call site que tocaba la función ausente.
+- **`makePdfWasmImports` falla rápido** ante imports desconocidos
+  (compatibilidad con el cambio anterior de 0.3.1; ya estaba pero ahora
+  alineado con la ABI version del módulo).
+
+### Added
+
+- **Canal de diagnósticos estructurado** (audit 3.6). Los `console.warn`
+  diseminados por el path de indexación desaparecen — los reemplaza un
+  buffer interno de `AlbexDiagnostic[]` consultable con
+  `engine.takeDiagnostics()`. Cada entrada es `{kind, stage, message, file?,
+  page?}` con `kind` en `'recovered' | 'skipped' | 'fallback' | 'info'`.
+  Cubre: fallback PDF→OCR, OCR fail por imagen, GPU caída a CPU, descarga
+  PDF WASM en red restringida. Capped a 256 entradas para no explotar en
+  corpus muy corruptos. La API de "best-effort" se mantiene, pero el
+  caller ahora puede inspeccionar qué se perdió.
+- **`engine.attachOcr(adapter)`** — extension point formal. Devuelve un
+  `OcrHandle` con `dispose()`. El motor valida el contrato y rechaza
+  un segundo `attachOcr` mientras haya uno activo. La propiedad pública
+  `engine.ocrImage` se mantiene como getter de feature-detect pero no es
+  asignable — para evitar el patrón anti-encapsulación del audit.
+- **`abiVersion()` exportada por ambos módulos WASM**. Main = v2 (incluye
+  query parser nuevo); PDF = v3 (incluye image extraction). El validador
+  TS rechaza binarios fuera de rango.
+
+### Architecture — query parsing moves to WASM (audit "two truths")
+
+Pre-0.5.0 el TypeScript dueño de `parseQuery`, `tokenize`,
+`tokensToWasmQuery`, mientras Rust tokenizaba al indexar. Dos verdades
+sobre qué era un "token".
+
+- Nuevos exports WASM: `prepareQuery`, `getQueryKind`,
+  `getQueryBranchCount`, `getQueryBranchPattern`, `selectQueryBranch`.
+- Hasta **8 branches OR** soportadas, **4 tokens por branch**, **256
+  bytes por pattern compilado** — todo en static BSS, sin alocación.
+- `containsPhrase` queda en TS porque opera sobre snippets (output del
+  WASM), no sobre la query — no es divergencia de tokenizer.
+- `parseQuery`, `tokenize`, `tokensToWasmQuery` eliminados del TS.
+- Un único algoritmo de "qué es un token" entre indexación y querying.
+
+### Build & maintenance
+
+- **`prepublishOnly` rebuildea WASM + corre tests** desde 0.3.1, ya
+  garantizado en 0.5.0.
+- Build pipeline simplificada: `scripts/build-wasm.mjs` produce solo
+  dos binarios. `npm pack --dry-run` muestra 4 archivos `.wasm` en lugar
+  de 8.
+- `wasm/Cargo.toml` añade `wee_alloc` (~1 KB) para el staging Vec del
+  restore atómico de 0.4.0.
+
+### Tests
+
+- 94 vitest cases verdes (era 88 en 0.4.0). Cinco tests del tier matrix
+  eliminados (mini/std/pro ya no existen). Tests nuevos:
+  - `tests/abi-validation.test.ts` (5): valida que `AlbexAbiMismatchError`
+    se lanza ante exports faltantes, abiVersion fuera de rango, memory
+    inválida.
+  - `tests/diagnostics.test.ts` (4): valida `takeDiagnostics()` drena,
+    cap a 256, reset limpia.
+
+### Postponed con razón
+
+Cosas del audit que NO se cierran en 0.5.0 porque cerrarlas sin datos
+reales sería adivinar:
+
+- **3.5 OCR paralelización**: optimización sin profiling no es ingeniería.
+- **3.9 Adaptive runtime con métricas reales**: requiere corpus y uso
+  reales para validar decisiones.
+- **4.3 GPU equivalence test**: requiere corpus >20k chunks que aún no
+  está checked in.
+- **7 parsers lite a WASM**: ~3 semanas serias. Separable. No es bug
+  fix, es mejora arquitectural más limpia con tiempo dedicado.
+
+## [0.4.0] — 2026-05-30
+
+Cierre de dos clases enteras de bugs identificadas por la auditoría externa
+de código. Sin cambios cosméticos — el binario crece ~4 KB por la lógica
+de atomicidad y el allocator necesario para el staging buffer.
+
+### Fixed — atomic snapshot restore (audit 3.4)
+
+- **Snapshot v3 con formato por campos**. Reemplaza la copia byte a byte
+  de los structs internos `Chunk`/`DocEntry` (`from_raw_parts`) por un
+  encoding explícito little-endian. El formato deja de depender del
+  layout en memoria de Rust, del target, del padding o de cambios en
+  los tipos. Lo que va al disco es un contrato.
+- **`restoreCommit()` — protocolo de 3 fases atómico**. El antiguo
+  `restoreBegin` reseteaba el estado y escribía los counters antes de
+  recibir un solo byte del payload. Si `restoreFeed` fallaba a mitad,
+  el corpus previo quedaba destruido. v3 acumula todo el payload en un
+  staging buffer y solo aplica al estado vivo cuando `restoreCommit`
+  valida que el tamaño completo coincide con el header. Un commit
+  fallido deja el motor con el corpus previo intacto.
+- **Compatibilidad backwards**. v1 y v2 siguen cargando — para ellos
+  `restoreBegin` mantiene la semántica vieja (no-atómica) y
+  `restoreCommit` es no-op que devuelve 1. El primer `save()` tras
+  cargar un snapshot viejo lo reescribe como v3.
+- Binarios crecen ~4 KB por la lógica nueva y por `wee_alloc` (única
+  fuente de alocación en el módulo, usada por el staging Vec).
+
+### Fixed — single source of truth for content hash (audit "two truths")
+
+- **FNV-1a 64-bit ahora vive en Rust**. La implementación TypeScript que
+  duplicaba el algoritmo desaparece. Tres nuevos exports
+  (`hashBegin`/`hashFeed`/`hashFinish`) implementan el hash en streaming
+  para archivos mayores que el scratchpad. El método privado del engine
+  `_contentHash` produce exactamente el mismo string hex de 16
+  caracteres que devolvía la versión TS — ningún caller cambia.
+
+### Added — tests
+
+- `tests/load-restores-docs.test.ts`: nuevo test "a v3 restore that
+  never commits leaves the previous index intact". Verifica
+  explícitamente la atomicidad: trunca el payload de un snapshot al
+  75 %, intenta cargarlo, verifica que `load()` devuelve `false` y que
+  el corpus previo sigue indexado y consultable.
+- `tests/hash.test.ts`: reescrito para validar el hash WASM contra el
+  engine real (la versión vieja era una re-implementación TS standalone
+  comparándose consigo misma). Cubre shape, determinismo, sensibilidad
+  a un byte, FNV offset basis, streaming sobre 96 KB (> scratchpad).
+- 88 tests verdes (era 85 en 0.3.1).
+
+### Postponed
+
+- Mover el tokenizador y query parser a WASM (audit "wrapper TS hace
+  demasiado") se traslada a 0.5.0. Es mejora arquitectural, no cierre
+  de bug — y tiene suficientes trade-offs de diseño (semánticas de OR,
+  post-filter de phrase) como para no publicar una API a medio cocer.
+
+## [0.3.1] — 2026-05-30
+
+Hardening pass after an external code audit. No new features; three
+specific issues addressed.
+
+### Fixed
+
+- **Debug logs removed from the indexing hot path.** Three `console.log`
+  statements added during the OCR-worker-abort diagnostic session were
+  firing on every PDF (hybrid OCR decision) and every embedded image
+  (kind / len / magic-byte trace). They are gone; the legitimate
+  `console.warn` messages for actual failures stay.
+
+- **`makePdfWasmImports` now fails fast on unknown imports.** Previously
+  any unrecognised import was satisfied with a `console.warn` stub,
+  which let the module instantiate and defer the real failure to an
+  arbitrary call inside `extractPdf`. The loader now throws
+  `AlbexInitError` at boot with a clear "rebuild your binary" message.
+  An unknown import means the wasm-bindgen / lopdf / getrandom graph
+  drifted from what this loader was written for; better to surface that
+  immediately than to hang or crash mid-extraction.
+
+- **`prepublishOnly` now rebuilds every WASM artifact and runs the
+  entire test suite.** It was running only `tsc + banner.mjs`, which
+  meant the WASM binaries published to npm could be out of sync with
+  the current Rust source. The script is now `npm run build:all && npm
+  test`. Publishing takes longer, but the package is guaranteed to
+  contain binaries reproducible from the source it ships.
+
+## [0.3.0] — 2026-05-30
+
+### Hybrid PDF OCR (opt-in)
+
+- New `@albex/ocr` option `alwaysExtractEmbeddedImages: boolean` (default
+  `false`). When enabled, the engine OCRs the embedded images of EVERY
+  PDF on top of the normal text extraction — catching text that lives
+  only inside scanned annexes, stamps, signatures, or screenshots inside
+  otherwise-native PDFs.
+- Demo exposes the flag as a checkbox in the OCR panel; status shows
+  `ready (spa, hybrid)` when active.
+
+### PDF parse-crash → OCR fallback
+
+- When `extractPdf` traps (pdf-extract crashes on a PDF that other tools
+  read fine), the engine now re-instantiates the WASM and tries the
+  lopdf-only image-extraction path before throwing. With OCR wired, many
+  formerly "unsupported encoding" PDFs become searchable.
+- Error message updated: instead of misleading "the file may be
+  malformed", users see clear guidance pointing at OCR as the recovery
+  path.
+
+### Demo sandbox
+
+- Importmap to jsDelivr for `tesseract.js` (only loaded when the user
+  enables OCR).
+- Full OCR panel: language select, hybrid-mode checkbox, lifecycle
+  status.
+- Two fixture PDFs in `demo/fixtures/` for end-to-end testing:
+  `hybrid-test.pdf` (vector text + embedded image with text) and
+  `scanned-only-test.pdf` (100% image, no vector text).
+- Global `window.onerror` + `unhandledrejection` handlers so Tesseract
+  worker aborts surface as Log entries instead of crashing the page.
+- New `npm run serve` script wraps `npx serve -p 5173` for reproducible
+  local testing.
+
+### Breaking changes
+
+- **`searchStream` renamed to `searchCooperative`.** The original name
+  implied incremental streaming, which the method never provided — it
+  yields to the scheduler between slices and then returns a batch.
+  The new name is honest. `searchStream` is kept as a deprecated alias
+  on `AlbexEngine`, `AlbexEngineWorker` and `AlbexPool`; it logs a
+  one-time `console.warn` on first call and will be removed in 0.4.0.
+
+- **Snapshot format bumped to v2.** Existing v1 snapshots still load —
+  their documents come back with empty `contentHash` strings, same as
+  before. On the next `save()` they are rewritten as v2. No data loss;
+  no migration step required.
+
+### Added
+
+- **Scanned-PDF OCR fallback.** When `extractPdf` returns `-2` (image-
+  only PDF) AND `@albex/ocr` has been wired via `enableOcr(engine)`,
+  the engine now extracts embedded JPEG / JPEG2000 image XObjects from
+  the PDF and runs them through Tesseract.js to recover text. Covers the
+  great majority of real-world scanned PDFs. Other compression filters
+  (FlateDecode, CCITTFaxDecode, JBIG2Decode) are not yet supported; pages
+  using them register with zero chunks (same behaviour as before).
+
+- **`getPageCount`, `extractPageImages`, `getPageImage{Len,Ptr,Kind}`**
+  added to `albex_pdf.wasm` to support the scanned-PDF path. The PDF
+  binary grew from ~1.04 MB to ~1.19 MB.
+
+- **Snapshot v2 persists per-document content hashes.** `load()` now
+  repopulates the in-memory `_docs` list correctly: `getStats().documents`
+  is right after a restore, and content-hash de-duplication survives the
+  round-trip (re-indexing the same file does not create a fresh slot).
+
+- **New WASM exports**: `setDocumentContentHash`, `getDocContentHashPtr`,
+  `getDocContentHashLen`. Used by the host to round-trip the FNV-1a 64-bit
+  hash through the snapshot format.
+
+- **OCR sandbox in the demo.** `demo/index.html` now ships an "Enable
+  OCR" panel that lazy-loads Tesseract.js through an importmap and
+  exposes per-document OCR status. Drop a scanned PDF and the demo OCR's
+  it automatically.
+
+### Fixed
+
+- **`load()` repopulates `_docs` from the WASM tables.** Previously it
+  left `_docs = []` after a successful restore, which made
+  `engine.getStats().documents` return `0` even though searches against
+  the restored corpus worked. The README advertised "snapshot the index
+  and restore it" without that caveat.
+
+- **CSV parser strips the UTF-8 BOM.** Files exported as "CSV UTF-8"
+  by Excel kept the BOM glued to the first field of the first row,
+  breaking column alignment and search hits on the first header
+  ("Subject", "Asunto", etc.).
+
+- **EML parser decodes `base64` and `quoted-printable` bodies.** Real
+  emails almost always use one of these transfer encodings; before the
+  fix the body surfaced as opaque encoded blobs that searches could
+  never hit. Nested multipart (`multipart/alternative` inside
+  `multipart/mixed`) is now also unwrapped recursively.
+
+- **RTF parser decodes `\'XX` hex bytes (via Windows-1252) and `\uN ?`
+  Unicode escapes.** Spanish/French/German content stored as cp1252
+  used to lose every accent; Word's modern `\u` escapes used to eat
+  the fallback ASCII character. Also added `\emdash`, `\endash`,
+  `\bullet`, `\lquote`, `\rquote`, `\ldblquote`, `\rdblquote`, `\tab`,
+  and soft-hyphen/non-breaking-space handling.
+
+### Documentation
+
+- **README claims grounded.** Removed "every modern bundler",
+  "60 fps even on huge corpora", "5–10× speedup", "works for 99 % of
+  users", "11 formats" (without the `lite` qualifier). The matrix of
+  what is tested vs what is expected to work is now explicit. Bench
+  results are flagged as synthetic.
+
+- **Persistence caveats documented.** The `Persistence` feature bullet
+  now describes the v2 / v1 difference and what survives the round trip.
+
+### Tests
+
+- 71 → 83 vitest tests, all green. New suites:
+  - `tests/scanned-pdf.test.ts` (4 tests) — scanned-PDF OCR fallback
+    with a hand-rolled `FakePdfWasm`.
+  - `tests/load-restores-docs.test.ts` (4 tests) — verifies `load()`
+    repopulates `_docs` and that content-hash dedup survives v2.
+  - `tests/lite-parsers.test.ts` (11 tests) — adversarial fixtures for
+    CSV BOM, EML base64 / QP / nested multipart, RTF cp1252 / Unicode.
+
+## [0.2.0] — earlier
+
+Initial public release. See git history for details: the surface was
+the `AlbexEngine` class, the `albex_wasm_bg.wasm` and `albex_pdf.wasm`
+binaries, lite parsers for the 11 formats, OPFS/IndexedDB persistence,
+worker pool, tiered storage and optional WebGPU pre-filter.
+
+[0.3.0]: https://github.com/RafaCalRob/Albex/releases/tag/v0.3.0
+[0.2.0]: https://github.com/RafaCalRob/Albex/releases/tag/v0.2.0