@jarenjs/core 0.73.0 → 0.83.2

package/src/search/config.js

@@ -0,0 +1,65 @@
+//@ts-check
+/** Versioned lexical semantics. Host decoding happens before this boundary. */
+import { deepFreeze } from '../object.js';
+
+/** @typedef {{version: number, fields: string[], profile?: string, prefix?: boolean,
+ * fuzzy?: number, combineWith?: string, boost?: Record<string, number>,
+ * normalization?: string, limits?: Partial<typeof SEARCH_LIMITS>}} LexicalDefinition */
+
+/** Finite logical allocation and work credits, independent of output truncation. */
+export const SEARCH_LIMITS = Object.freeze({
+  maxDocuments: 100000, maxSourceBytes: 64 * 1024 * 1024,
+  maxIndexBytes: 256 * 1024 * 1024, maxTemporaryBytes: 512 * 1024 * 1024,
+  maxTokens: 4000000, maxPostings: 4000000, maxVocabulary: 300000,
+  maxFieldBytes: 65536, maxTokenLength: 128, maxQueryBytes: 4096,
+  maxExpansions: 16384, maxCandidates: 100000, maxResults: 1000,
+  maxWork: 100000000, maxBatchWork: 100000,
+});
+
+/** @param {LexicalDefinition} input */
+export function lexicalConfig(input) {
+  if (!input || input.version !== 1 || !Array.isArray(input.fields) || !input.fields.length
+    || input.fields.length > 64 || input.fields.some((f) => typeof f !== 'string' || !f || f.length > 256)
+    || new Set(input.fields).size !== input.fields.length) throw new TypeError('Invalid lexical definition');
+  const allowed = ['version', 'fields', 'profile', 'prefix', 'fuzzy', 'combineWith', 'boost', 'normalization', 'limits'];
+  if (Object.keys(input).some((key) => !allowed.includes(key))) throw new TypeError('Unknown lexical option');
+  const config = { version: 1, fields: [...input.fields], profile: input.profile ?? 'minisearch-7.2.0-cold',
+    prefix: input.prefix ?? true, fuzzy: input.fuzzy ?? 0.15, combineWith: input.combineWith ?? 'AND',
+    boost: { ...input.boost }, normalization: input.normalization ?? 'host-text/1',
+    limits: { ...SEARCH_LIMITS, ...input.limits } };
+  if (!['minisearch-7.2.0-cold', 'lexical-key/1'].includes(config.profile)
+    || typeof config.prefix !== 'boolean' || !Number.isFinite(config.fuzzy) || config.fuzzy < 0 || config.fuzzy > 1
+    || !['AND', 'OR'].includes(config.combineWith) || typeof config.normalization !== 'string' || !config.normalization)
+    throw new TypeError('Unsupported lexical semantics');
+  for (const [field, boost] of Object.entries(config.boost))
+    if (!config.fields.includes(field) || !Number.isFinite(boost) || boost <= 0 || boost > 1000)
+      throw new TypeError('Invalid lexical field boost');
+  for (const [key, value] of Object.entries(config.limits))
+    if (!Object.hasOwn(SEARCH_LIMITS, key) || !Number.isSafeInteger(value) || value < 1)
+      throw new TypeError(`Invalid lexical credit: ${key}`);
+  return deepFreeze(config);
+}
+
+/** Token boundaries intentionally preserve the oracle's tab and accent behavior.
+ * @param {string} value @returns {string[]} */
+export function lexicalTokens(value) { return value.split(/[\n\r\p{Z}\p{P}]+/u); }
+
+/** Banded Levenshtein in UTF-16 units, matching the named compatibility profile.
+ * @param {string} a @param {string} b @param {number} limit @param {() => void} step
+ * @param {Uint16Array} previous @param {Uint16Array} current */
+export function lexicalDistance(a, b, limit, step, previous, current) {
+  if (Math.abs(a.length - b.length) > limit) return limit + 1;
+  for (let j = 0; j <= b.length; j++) previous[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    current.fill(limit + 1, 0, b.length + 1); current[0] = i;
+    let best = limit + 1;
+    for (let j = Math.max(1, i - limit); j <= Math.min(b.length, i + limit); j++) {
+      step();
+      const value = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+      current[j] = value; best = Math.min(best, value);
+    }
+    if (best > limit) return limit + 1;
+    [previous, current] = [current, previous];
+  }
+  return previous[b.length];
+}

package/src/search/index.js

@@ -0,0 +1,360 @@
+//@ts-check
+/** Resident postings and rank statistics, published atomically by source generation. */
+import { lexicalConfig, lexicalTokens, lexicalDistance } from './config.js';
+import { utf8ByteLength as textBytes, hashContent } from '../string.js';
+import { lexicalVocabulary } from './vocabulary.js';
+export { SEARCH_LIMITS } from './config.js';
+
+/** @typedef {import('./config.js').LexicalDefinition} LexicalDefinition */
+/** @typedef {{generation?:number, sourceRevision?:string}} LexicalIdentity */
+/** @typedef {{id:string, score:number}} LexicalHit */
+
+/** Compile a versioned definition once. Each create() owns an isolated resident index.
+ * @param {LexicalDefinition} definition */
+export function compileLexical(definition) {
+  const config = lexicalConfig(definition);
+  const identity = JSON.stringify(config);
+  return Object.freeze({ config, identity, create: () => createIndex(config, identity) });
+}
+
+function createIndex(config, identity) {
+  const limits = config.limits, fields = config.fields;
+  const empty = () => ({ docs: new Map(), postings: new Map(), lengths: fields.map(() => 0),
+    sourceBytes: 0, tokens: 0, postingCount: 0, bytes: 0, dictionaryBytes: 0, forward: [], reverse: [], nextOrder: 0 });
+  let state = empty(), generation = 0, sourceRevision = '', disposed = false, ticket = 0, stagingOverhead = 0;
+  const exhausted = (reason) => { throw new RangeError(reason); };
+  const guard = (value, max, reason) => { if (value > max) exhausted(reason); };
+  const outcome = (status, reason, extra = {}) => ({ state: status, ...(reason ? { reason } : {}),
+    generation, sourceRevision, identity, ...extra });
+  const stats = () => ({ documents: state.docs.size, vocabulary: state.postings.size,
+    postings: state.postingCount, tokens: state.tokens, sourceBytes: state.sourceBytes,
+    indexBytes: state.bytes, tombstones: 0, fieldLengths: [...state.lengths], generation, sourceRevision, disposed });
+
+  function prepare(row, order) {
+    if (!row || typeof row.id !== 'string' || !row.id) throw new TypeError('Lexical IDs must be nonempty strings');
+    guard(row.id.length * 2, limits.maxFieldBytes, 'field-bytes');
+    const values = new Array(fields.length), terms = new Array(fields.length), lengths = new Array(fields.length);
+    let sourceBytes = textBytes(row.id), tokens = 0, postings = 0, bytes = 128 + row.id.length * 2, work = 1;
+    for (let fieldIndex = 0; fieldIndex < fields.length; fieldIndex++) {
+      const field = fields[fieldIndex];
+      const value = Object.hasOwn(row, field) ? row[field] ?? '' : '';
+      if (typeof value !== 'string') throw new TypeError('Lexical fields must be strings');
+      guard(value.length, limits.maxFieldBytes, 'field-bytes');
+      const size = textBytes(value); guard(size, limits.maxFieldBytes, 'field-bytes');
+      // Token arrays, sets, strings and maps are reserved before tokenization.
+      guard(bytes + value.length * 256, limits.maxTemporaryBytes - state.bytes, 'temporary-bytes');
+      guard(work + value.length, limits.maxBatchWork, 'batch-work');
+      const raw = lexicalTokens(value), counts = new Map();
+      lengths[fieldIndex] = new Set(raw).size;
+      for (const token of raw) {
+        const term = token.toLowerCase();
+        guard(term.length, limits.maxTokenLength, 'token-length');
+        if (term) { counts.set(term, (counts.get(term) ?? 0) + 1); tokens++; }
+      }
+      for (const term of counts.keys()) bytes += 160 + term.length * 2;
+      sourceBytes += size; bytes += 48 + value.length * 2; work += value.length + raw.length;
+      postings += counts.size; values[fieldIndex] = value;
+      const pairs = new Array(counts.size * 2); let offset = 0;
+      for (const [term, frequency] of counts) { pairs[offset++] = term; pairs[offset++] = frequency; }
+      terms[fieldIndex] = pairs;
+    }
+    guard(work, limits.maxBatchWork, 'batch-work');
+    return { id: row.id, values, terms, lengths, sourceBytes, tokens, postings, bytes, order, work };
+  }
+
+  function* stage(rows, remove, replace, request, myTicket) {
+    if (disposed) return outcome('error', 'disposed');
+    const wanted = request.generation ?? generation + 1;
+    const revision = request.sourceRevision ?? sourceRevision;
+    if (!Number.isSafeInteger(wanted) || wanted < 0 || typeof revision !== 'string') return outcome('error', 'invalid-identity');
+    if (wanted < generation) return outcome('invalidated', 'stale-generation');
+    if (stagingOverhead + state.bytes + (replace ? 0 : state.docs.size * 48 + state.postings.size * 48) > limits.maxTemporaryBytes)
+      return outcome('budget-exhausted', 'temporary-bytes');
+    const next = replace ? empty() : { ...state, bytes: state.bytes - state.dictionaryBytes,
+      docs: new Map(state.docs), postings: new Map(state.postings), lengths: [...state.lengths] };
+    const copied = new Set(), seen = new Set();
+    let work = 0, changes = replace ? state.docs.size : 0, temporary = stagingOverhead + state.bytes + next.docs.size * 48 + next.postings.size * 48;
+    const writable = (term) => {
+      if (!copied.has(term)) {
+        const old = next.postings.get(term);
+        const cost = old ? [...old.values()].reduce((n, entries) => n + entries.size * 48 + 64, 64) : 64;
+        guard(temporary + cost, limits.maxTemporaryBytes, 'temporary-bytes'); temporary += cost;
+        next.postings.set(term, old ? new Map([...old].map(([field, entries]) => [field, new Map(entries)])) : new Map());
+        copied.add(term);
+      }
+      return next.postings.get(term);
+    };
+    const subtract = (old, remove = true) => {
+      if (remove) next.docs.delete(old.id); next.bytes -= old.bytes; next.sourceBytes -= old.sourceBytes;
+      next.tokens -= old.tokens; next.postingCount -= old.postings;
+      for (let field = 0; field < fields.length; field++) {
+        next.lengths[field] -= old.lengths[field];
+        for (let i = 0; i < old.terms[field].length; i += 2) {
+          const term = old.terms[field][i];
+          const posting = writable(term), entries = posting.get(field);
+          entries.delete(old.id); if (!entries.size) posting.delete(field);
+          if (!posting.size) { next.postings.delete(term); copied.delete(term); }
+        }
+      }
+    };
+    try {
+      guard(temporary, limits.maxTemporaryBytes, 'temporary-bytes');
+      for (const id of remove) {
+        if (typeof id !== 'string') throw new TypeError('Invalid lexical removal ID');
+        const old = next.docs.get(id);
+        if (old) { subtract(old); changes++; work += old.work; }
+        guard(++work, limits.maxWork, 'work'); yield work;
+      }
+      for (const row of rows) {
+        guard(seen.size + 1, limits.maxDocuments, 'documents');
+        if (seen.has(row?.id)) throw new TypeError('Duplicate lexical ID');
+        seen.add(row?.id);
+        const old = next.docs.get(row?.id);
+        const doc = prepare(row, old?.order ?? next.nextOrder);
+        work += doc.work; guard(work, limits.maxWork, 'work');
+        if (old && doc.values.every((v, i) => v === old.values[i])) { yield work; continue; }
+        guard(temporary + doc.bytes * 2, limits.maxTemporaryBytes, 'temporary-bytes'); temporary += doc.bytes * 2;
+        if (old) subtract(old, false); else next.nextOrder++;
+        guard(next.docs.size + (old ? 0 : 1), limits.maxDocuments, 'documents');
+        guard(next.sourceBytes + doc.sourceBytes, limits.maxSourceBytes, 'source-bytes');
+        guard(next.tokens + doc.tokens, limits.maxTokens, 'tokens');
+        guard(next.postingCount + doc.postings, limits.maxPostings, 'postings');
+        guard(next.bytes + doc.bytes, limits.maxIndexBytes, 'index-bytes');
+        next.docs.set(doc.id, doc); next.bytes += doc.bytes; next.sourceBytes += doc.sourceBytes;
+        next.tokens += doc.tokens; next.postingCount += doc.postings;
+        for (let field = 0; field < fields.length; field++) {
+          next.lengths[field] += doc.lengths[field];
+          for (let i = 0; i < doc.terms[field].length; i += 2) {
+            const term = doc.terms[field][i], frequency = doc.terms[field][i + 1];
+            if (!next.postings.has(term)) guard(next.postings.size + 1, limits.maxVocabulary, 'vocabulary');
+            const posting = writable(term);
+            if (!posting.has(field)) posting.set(field, new Map());
+            posting.get(field).set(doc.id, frequency);
+          }
+        }
+        changes++; yield work;
+      }
+      for (const term of copied) if (!next.postings.get(term)?.size) next.postings.delete(term);
+      if (disposed || myTicket !== ticket) return outcome(disposed ? 'error' : 'invalidated', disposed ? 'disposed' : 'superseded');
+      if (replace && state.docs.size === next.docs.size) {
+        let same = true;
+        const oldIds = state.docs.keys();
+        for (const [id, doc] of next.docs) {
+          const old = state.docs.get(id);
+          if (!old || oldIds.next().value !== id || !doc.values.every((v, i) => v === old.values[i])) { same = false; break; }
+        }
+        if (same) changes = 0;
+      }
+      if (!changes && revision === sourceRevision) return outcome('complete', null, { changes: 0, work, peakBytes: temporary });
+      if (wanted === generation) return outcome('invalidated', 'conflicting-generation');
+      next.dictionaryBytes = next.postings.size * 16;
+      guard(next.bytes + next.dictionaryBytes, limits.maxIndexBytes, 'index-bytes'); next.bytes += next.dictionaryBytes;
+      guard(temporary + next.postings.size * 384, limits.maxTemporaryBytes, 'temporary-bytes');
+      temporary += next.postings.size * 384;
+      const words = new Set();
+      for (const doc of next.docs.values()) {
+        for (const terms of doc.terms) for (let i = 0; i < terms.length; i += 2) words.add(terms[i]);
+        work += doc.postings; guard(work, limits.maxWork, 'work'); yield work;
+      }
+      const vocabulary = lexicalVocabulary(words, () => { guard(++work, limits.maxWork, 'work'); });
+      let ordered = vocabulary.next();
+      while (!ordered.done) { yield work; ordered = vocabulary.next(); }
+      next.forward = ordered.value.forward; next.reverse = ordered.value.reverse;
+      if (!replace) for (const word of copied) {
+        const posting = next.postings.get(word); if (!posting) continue;
+        for (const [field, entries] of posting) {
+          let comparisons = 0;
+          const sorted = [...entries].sort((a, b) => {
+            guard(++comparisons, limits.maxBatchWork, 'batch-work'); guard(++work, limits.maxWork, 'work');
+            return next.docs.get(a[0]).order - next.docs.get(b[0]).order;
+          });
+          posting.set(field, new Map(sorted)); yield work;
+        }
+      }
+      if (disposed || myTicket !== ticket) return outcome(disposed ? 'error' : 'invalidated', disposed ? 'disposed' : 'superseded');
+      state = next; generation = wanted; sourceRevision = revision;
+      return outcome('complete', null, { changes, work, peakBytes: temporary });
+    }
+    catch (error) { return outcome(error instanceof RangeError ? 'budget-exhausted' : 'error', error.message); }
+  }
+
+  function mutate(rows, remove, replace, request = {}) {
+    const steps = stage(rows, remove, replace, request, ++ticket);
+    let result = steps.next(); while (!result.done) result = steps.next();
+    return result.value;
+  }
+
+  async function mutateAsync(rows, remove, replace, request) {
+      if (typeof request?.yield !== 'function') throw new TypeError('A cooperative yield capability is required');
+      const mine = ++ticket, steps = stage(rows, remove, replace, request, mine);
+      let previous = 0;
+      try {
+        for (;;) {
+          if (request.signal?.aborted) return outcome('error', 'cancelled');
+          if (disposed || mine !== ticket) return outcome(disposed ? 'error' : 'invalidated', disposed ? 'disposed' : 'superseded');
+          const result = steps.next(); if (result.done) return result.value;
+          if (result.value - previous >= limits.maxBatchWork / 2) {
+            previous = result.value; request.onProgress?.({ work: previous, generation: request.generation }); await request.yield();
+          }
+        }
+      }
+      finally { steps.return(undefined); }
+  }
+
+  /** @param {string} text @param {any} [options] */
+  function search(text, options = {}) {
+    const queriedState = state;
+    const used = { work: 0, expansions: 0, candidates: 0 };
+    const fail = (kind, reason) => outcome(kind, reason, { hits: [], total: null, hasMore: false, used });
+    if (disposed) return fail('error', 'disposed');
+    if (options.sourceRevision !== undefined && options.sourceRevision !== sourceRevision) return fail('invalidated', 'source-stale');
+    const limit = options.limit ?? limits.maxResults;
+    if (typeof text !== 'string' || !Number.isSafeInteger(limit) || limit < 0 || limit > limits.maxResults) return fail('error', 'invalid-query');
+    if (text.length > limits.maxQueryBytes || textBytes(text) > limits.maxQueryBytes) return fail('budget-exhausted', 'query-bytes');
+    const credits = { work: limits.maxWork, expansions: limits.maxExpansions, candidates: limits.maxCandidates, ...options.credits };
+    for (const [key, value] of Object.entries(credits))
+      if (!['work', 'expansions', 'candidates'].includes(key) || !Number.isSafeInteger(value) || value < 0
+        || value > ({ work: limits.maxWork, expansions: limits.maxExpansions, candidates: limits.maxCandidates })[key]) return fail('error', 'invalid-credits');
+    const step = () => { if (used.work >= credits.work) exhausted('work'); used.work++; };
+    const terms = lexicalTokens(text).map((t) => t.toLowerCase()).filter(Boolean);
+    const quality = new Set(terms).size;
+    let combined = null;
+    try {
+      for (const term of terms) {
+        guard(term.length, limits.maxTokenLength, 'token-length');
+        const matches = new Map();
+        const rank = (word, weight) => {
+          if (used.expansions >= credits.expansions) exhausted('expansions'); used.expansions++;
+          const posting = state.postings.get(word);
+          for (let field = 0; field < fields.length; field++) {
+            const entries = posting.get(field); if (!entries) continue;
+            const idf = Math.log(1 + (state.docs.size - entries.size + 0.5) / (entries.size + 0.5));
+            const average = state.lengths[field] / state.docs.size;
+            for (const [id, frequency] of entries) {
+              step(); const doc = state.docs.get(id);
+              const score = weight * (Object.hasOwn(config.boost, fields[field]) ? config.boost[fields[field]] : 1) * idf
+                * (0.5 + frequency * 2.2 / (frequency + 1.2 * (0.3 + 0.7 * doc.lengths[field] / average)));
+              if (!matches.has(id)) {
+                guard(matches.size + 1, credits.candidates, 'candidates');
+                guard(state.bytes + (matches.size + 1 + (combined?.size ?? 0)) * 192, limits.maxTemporaryBytes, 'temporary-bytes');
+                used.candidates = Math.max(used.candidates, matches.size + 1);
+              }
+              matches.set(id, (matches.get(id) ?? 0) + score);
+            }
+          }
+        };
+        step();
+        if (state.postings.has(term)) rank(term, 1);
+        const distance = Math.min(6, Math.round(term.length * config.fuzzy));
+        const previous = new Uint16Array(term.length + distance + 1), current = new Uint16Array(term.length + distance + 1);
+        // Exact terms precede expansions; prefix matches own their fuzzy overlap.
+        if (config.prefix) for (const word of state.reverse) {
+          step(); if (word === term) continue;
+          if (word.startsWith(term)) rank(word, 0.375 * word.length / (word.length + 0.3 * (word.length - term.length)));
+        }
+        if (distance) for (const word of state.forward) {
+          step(); if (word === term || (config.prefix && word.startsWith(term))) continue;
+          const d = lexicalDistance(term, word, distance, step, previous, current);
+          if (d <= distance) rank(word, 0.45 * word.length / (word.length + d));
+        }
+        if (combined === null) combined = matches;
+        else if (config.combineWith === 'AND') {
+          for (const [id, score] of matches) { step();
+            if (combined.has(id)) matches.set(id, score + combined.get(id)); else matches.delete(id); }
+          combined = matches;
+        }
+        else for (const [id, score] of matches) { step();
+          guard(combined.has(id) ? combined.size : combined.size + 1, credits.candidates, 'candidates');
+          combined.set(id, (combined.get(id) ?? 0) + score); }
+      }
+      const hits = [];
+      for (const [id, score] of combined ?? []) { step();
+        const hit = { id, score: score * quality };
+        if (!options.filter || options.filter(hit)) { options.onMatch?.(hit); hits.push(hit); }
+      }
+      const tie = (a, b) => config.profile === 'lexical-key/1' ? (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
+        : 0;
+      hits.sort((a, b) => { step(); return (options.compare ? options.compare(a, b) : b.score - a.score) || tie(a, b); });
+      let start = 0;
+      if (options.after != null) {
+        const after = options.after;
+        if (after.identity !== identity || after.sourceRevision !== sourceRevision || after.text !== text || after.query !== (options.query ?? ''))
+          return fail('invalidated', 'continuation-changed');
+        const position = hits.findIndex((hit) => hit.id === after.id && hit.score === after.score);
+        if (position < 0) return fail('invalidated', 'continuation-changed');
+        start = position + 1;
+      }
+      const page = hits.slice(start, start + limit), hasMore = start + page.length < hits.length;
+      const continuation = hasMore && page.length ? { ...page.at(-1), identity, sourceRevision, text, query: options.query ?? '' } : null;
+      if (disposed || state !== queriedState) return fail(disposed ? 'error' : 'invalidated', disposed ? 'disposed' : 'source-changed');
+      return outcome('complete', null, { hits: page, total: hits.length, hasMore, continuation, used });
+    }
+    catch (error) { return fail(error instanceof RangeError ? 'budget-exhausted' : 'error', error.message); }
+  }
+
+  return {
+    config, identity, stats, search,
+    /** Serialize a complete derived snapshot. The checksum detects corruption, not forgery.
+     * @returns {string} */
+    snapshot() {
+      if (disposed) throw new Error('disposed');
+      guard(state.bytes + state.sourceBytes * 12 + state.docs.size * 256, limits.maxTemporaryBytes, 'temporary-bytes');
+      const payload = JSON.stringify({ format: 'jaren-lexical/1', complete: true, identity, generation, sourceRevision,
+        documents: [...state.docs.values()].map((doc) => [doc.id, doc.values, doc.order]), nextOrder: state.nextOrder });
+      return JSON.stringify({ checksum: hashContent(payload), payload });
+    },
+    /** Validate format, configuration and authoritative source before atomic publication.
+     * Recovery always rebuilds postings through the same bounded engine.
+     * @param {string} serialized @param {LexicalIdentity & {sourceRevision:string}} request */
+    restore(serialized, request) {
+      if (disposed) return outcome('error', 'disposed');
+      const refuse = (reason) => outcome('rebuild-required', reason);
+      if (typeof serialized !== 'string') return refuse('corrupt-snapshot');
+      if (serialized.length * 16 + state.bytes > limits.maxTemporaryBytes) return refuse('snapshot-bytes');
+      let data;
+      try {
+        const envelope = JSON.parse(serialized);
+        if (typeof envelope.payload !== 'string' || hashContent(envelope.payload) !== envelope.checksum) return refuse('corrupt-snapshot');
+        data = JSON.parse(envelope.payload);
+      }
+      catch { return refuse('corrupt-snapshot'); }
+      if (data?.format !== 'jaren-lexical/1' || data.complete !== true) return refuse('snapshot-format');
+      if (data.identity !== identity) return refuse('config-mismatch');
+      if (typeof request?.sourceRevision !== 'string' || data.sourceRevision !== request.sourceRevision) return refuse('source-stale');
+      if (!Number.isSafeInteger(data.generation) || data.generation < 0 || !Array.isArray(data.documents)
+        || data.documents.length > limits.maxDocuments || !Number.isSafeInteger(data.nextOrder) || data.nextOrder < 0)
+        return refuse('corrupt-snapshot');
+      let prior = -1;
+      const rows = [];
+      for (const doc of data.documents) {
+        if (!Array.isArray(doc) || doc.length !== 3 || !Array.isArray(doc[1]) || doc[1].length !== fields.length
+          || !Number.isSafeInteger(doc[2]) || doc[2] <= prior || doc[2] >= data.nextOrder) return refuse('corrupt-snapshot');
+        prior = doc[2]; rows.push(Object.fromEntries([['id', doc[0]], ...fields.map((field, i) => [field, doc[1][i]])]));
+      }
+      let result;
+      stagingOverhead = serialized.length * 16;
+      try { result = mutate(rows, [], true, { generation: request.generation ?? Math.max(generation + 1, data.generation),
+        sourceRevision: request.sourceRevision }); }
+      finally { stagingOverhead = 0; }
+      if (result.state !== 'complete') return result.state === 'invalidated' ? result : refuse(result.reason);
+      for (const doc of data.documents) state.docs.get(doc[0]).order = doc[2];
+      state.nextOrder = data.nextOrder;
+      return result;
+    },
+    /** Atomically build from authoritative text rows. @param {Iterable<any>} rows @param {LexicalIdentity} [request] */
+    rebuild: (rows, request) => mutate(rows, [], true, request),
+    /** Replace/remove by stable ID; unchanged text is a no-op. @param {{put?:Iterable<any>, remove?:Iterable<string>}} changes @param {LexicalIdentity} [request] */
+    update: (changes, request) => mutate(changes.put ?? [], changes.remove ?? [], false, request),
+    /** Clear all postings without retaining tombstones. @param {LexicalIdentity} [request] */
+    clear: (request) => mutate([], [], true, request),
+    /** Cooperative atomic build. The host yields to its event loop and owns cancellation.
+     * @param {Iterable<any>} rows @param {LexicalIdentity & {yield:()=>Promise<void>, signal?:AbortSignal, onProgress?:(value:any)=>void}} request */
+    rebuildAsync: (rows, request) => mutateAsync(rows, [], true, request),
+    /** Cooperative atomic replacement/removal using the same staging engine.
+     * @param {{put?:Iterable<any>, remove?:Iterable<string>}} changes
+     * @param {LexicalIdentity & {yield:()=>Promise<void>, signal?:AbortSignal, onProgress?:(value:any)=>void}} request */
+    updateAsync: (changes, request) => mutateAsync(changes.put ?? [], changes.remove ?? [], false, request),
+    /** Idempotently free every resident reference and fence staged work. */
+    dispose() { disposed = true; ticket++; state = empty(); },
+  };
+}

package/src/search/vocabulary.js

@@ -0,0 +1,39 @@
+//@ts-check
+/** Compact traversal orders preserve the compatibility profile without retaining a trie. */
+
+/** Build traversal ordinals from first occurrence in authoritative document order.
+ * The temporary compressed tree is released before publication; only two arrays of
+ * term references remain. Splitting a branch appends that branch at its parent.
+ * @param {Iterable<string>} words @param {()=>void} step */
+export function* lexicalVocabulary(words, step) {
+  const root = [];
+  for (const word of words) {
+    let edges = root, offset = 0;
+    while (offset < word.length) {
+      step();
+      const position = edges.findIndex((edge) => { step(); return edge.label && edge.label[0] === word[offset]; });
+      if (position < 0) { const children = []; edges.push({ label: word.slice(offset), children }); edges = children; break; }
+      const edge = edges[position];
+      let shared = 0;
+      while (shared < edge.label.length && word[offset + shared] === edge.label[shared]) { shared++; step(); }
+      if (shared < edge.label.length) {
+        const children = [{ label: edge.label.slice(shared), children: edge.children }];
+        edges.splice(position, 1); edges.push({ label: edge.label.slice(0, shared), children }); edges = children;
+      }
+      else edges = edge.children;
+      offset += shared;
+    }
+    edges.push({ label: '', word }); yield;
+  }
+  const forward = [], reverse = [], stack = [root[Symbol.iterator]()];
+  while (stack.length) {
+    step(); const current = stack.at(-1).next();
+    if (current.done) stack.pop();
+    else if (current.value.label === '') forward.push(current.value.word);
+    else stack.push(current.value.children[Symbol.iterator]());
+    yield;
+  }
+  // A reverse depth-first traversal is the reverse of the forward leaf sequence.
+  for (let i = forward.length - 1; i >= 0; i--) { step(); reverse.push(forward[i]); yield; }
+  return { forward, reverse };
+}

package/src/virtual/index.js

@@ -0,0 +1,140 @@
+//@ts-check
+/** DOM-free virtual geometry. Work and retained state depend on the viewport and credits. */
+
+/** @param {number} value @param {string} name @param {number} [min] */
+function integer(value, name, min = 0) {
+  if (!Number.isSafeInteger(value) || value < min) throw new RangeError(`Invalid ${name}`);
+  return value;
+}
+
+/** @param {number} value */
+function positive(value) {
+  if (!Number.isFinite(value) || value <= 0) throw new RangeError('Invalid size');
+  return value;
+}
+
+/** @param {number} value */
+function nonnegative(value) { return Number.isFinite(value) ? Math.max(0, value) : 0; }
+
+/**
+ * A half-open fixed-size window, with no source access. Hidden viewports are empty.
+ * @param {{count:number, size:number, viewport:number, offset?:number, overscan?:number}} options
+ */
+export function fixedRange({ count, size, viewport, offset = 0, overscan = 0 }) {
+  integer(count, 'count'); positive(size); integer(overscan, 'overscan');
+  const extent = count * size;
+  if (!Number.isFinite(extent) || extent > Number.MAX_SAFE_INTEGER) throw new RangeError('Invalid extent');
+  viewport = nonnegative(viewport);
+  offset = Math.min(nonnegative(offset), Math.max(0, extent - viewport));
+  if (!count || !viewport) return { start: 0, end: 0, offset, extent };
+  return { start: Math.max(0, Math.floor(offset / size) - overscan),
+    end: Math.min(count, Math.ceil((offset + viewport) / size) + overscan), offset, extent };
+}
+
+/**
+ * Sparse measured axis. Only credited measurements are retained; evicted sizes become estimates.
+ * Prefix summaries rebuild on measurement, never by enumerating logical items.
+ * @param {{count:number, estimateSize:number, maxMeasurements?:number, maxBytes?:number}} options
+ */
+export function createVirtualAxis({ count, estimateSize, maxMeasurements = 256, maxBytes = 32768 }) {
+  integer(count, 'count'); positive(estimateSize);
+  integer(maxMeasurements, 'maxMeasurements'); integer(maxBytes, 'maxBytes');
+  const entries = new Map();
+  let sorted = [], prefix = [], bytes = 0, disposed = false;
+  function rebuild() {
+    sorted = [...entries.values()].sort((a, b) => a.index - b.index);
+    let sum = 0;
+    prefix = sorted.map((item) => (sum += item.size - estimateSize));
+  }
+  function position(index) {
+    let low = 0, high = sorted.length;
+    while (low < high) { const mid = Math.floor((low + high) / 2);
+      if (sorted[mid].index < index) low = mid + 1; else high = mid; }
+    return index * estimateSize + (low ? prefix[low - 1] : 0);
+  }
+  function size(index) {
+    let low = 0, high = sorted.length;
+    while (low < high) { const mid = Math.floor((low + high) / 2);
+      if (sorted[mid].index < index) low = mid + 1; else high = mid; }
+    return sorted[low]?.index === index ? sorted[low].size : estimateSize;
+  }
+  function indexAt(offset) {
+    let low = 0, high = count;
+    while (low < high) { const mid = Math.floor((low + high) / 2);
+      if (position(mid + 1) <= offset) low = mid + 1; else high = mid; }
+    return Math.min(low, Math.max(0, count - 1));
+  }
+  function remove(key) { bytes -= entries.get(key).bytes; entries.delete(key); }
+  return {
+    position, size, indexAt,
+    extent() { return position(count); },
+    range({ offset = 0, viewport = 0, overscan = 0 } = {}) {
+      if (!sorted.length) return fixedRange({ count: disposed ? 0 : count, size: estimateSize, offset, viewport, overscan });
+      integer(overscan, 'overscan'); viewport = nonnegative(viewport);
+      const extent = position(count);
+      offset = Math.min(nonnegative(offset), Math.max(0, extent - viewport));
+      if (disposed || !count || !viewport) return { start: 0, end: 0, offset, extent };
+      const first = indexAt(offset);
+      let end = indexAt(offset + viewport);
+      if (position(end) < offset + viewport) end++;
+      return { start: Math.max(0, first - overscan), end: Math.min(count, end + overscan), offset, extent };
+    },
+    measure(index, key, value) {
+      if (disposed) return { state: 'error', reason: 'disposed' };
+      integer(index, 'index'); positive(value);
+      if (index >= count || typeof key !== 'string') return { state: 'error', reason: 'invalid-measurement' };
+      if (key.length > maxBytes) return { state: 'budget-exhausted', reason: 'measurement-credits' };
+      const cost = new TextEncoder().encode(key).byteLength + 24;
+      if (!maxMeasurements || cost > maxBytes) return { state: 'budget-exhausted', reason: 'measurement-credits' };
+      if (entries.has(key)) remove(key);
+      for (const [other, entry] of entries) if (entry.index === index) remove(other);
+      while (entries.size >= maxMeasurements || bytes + cost > maxBytes) remove(entries.keys().next().value);
+      entries.set(key, { index, size: value, bytes: cost }); bytes += cost; rebuild();
+      return { state: 'ready' };
+    },
+    anchor(offset, keyAt, query = '') {
+      if (!count) return null;
+      const index = indexAt(nonnegative(offset));
+      return { key: String(keyAt(index)), index, offset: nonnegative(offset) - position(index), query };
+    },
+    restore(anchor, indexOf, query = '') {
+      if (!anchor || anchor.query !== query || !count) return { state: 'ready', offset: 0, fallback: true };
+      const found = indexOf?.(anchor.key);
+      const valid = Number.isSafeInteger(found) && found >= 0 && found < count;
+      const index = valid ? found : Math.min(count - 1, Math.max(0, anchor.index));
+      return { state: 'ready', offset: position(index) + Math.min(nonnegative(anchor.offset), size(index)), fallback: !valid };
+    },
+    update(next) {
+      if (disposed) return;
+      if (next.count !== undefined) count = integer(next.count, 'count');
+      if (next.estimateSize !== undefined && next.estimateSize !== estimateSize) {
+        estimateSize = positive(next.estimateSize); entries.clear(); bytes = 0;
+      }
+      const occupied = new Set();
+      for (const [key, entry] of entries) {
+        const index = next.indexOf ? next.indexOf(key) : entry.index;
+        if (!Number.isSafeInteger(index) || index < 0 || index >= count || occupied.has(index)) remove(key);
+        else { entry.index = index; occupied.add(index); }
+      }
+      rebuild();
+    },
+    clear() { entries.clear(); sorted = []; prefix = []; bytes = 0; },
+    stats() { return { measurements: entries.size, bytes, summaries: sorted.length }; },
+    dispose() { disposed = true; entries.clear(); sorted = []; prefix = []; bytes = 0; },
+  };
+}
+
+/** Add finite pinned indices to a window; pins count against the same mounted budget.
+ * @param {{start:number,end:number}} range @param {number[]} pins @param {number} count @param {number} budget */
+export function virtualIndices(range, pins, count, budget) {
+  integer(budget, 'pinBudget');
+  const extra = [...new Set(pins)].filter((i) => Number.isSafeInteger(i) && i >= 0 && i < count && (i < range.start || i >= range.end));
+  if (extra.length > budget) return { state: 'budget-exhausted', reason: 'pin-credits', indices: [] };
+  return { state: 'ready', indices: [...Array.from({ length: range.end - range.start }, (_, i) => range.start + i), ...extra].sort((a, b) => a - b) };
+}
+
+/** Normalize a browser RTL scroll offset at the DOM boundary. Modern engines use negative offsets.
+ * @param {number} value @param {number} maximum @param {'ltr'|'negative'|'reverse'|'default'} [mode] */
+export function logicalScrollOffset(value, maximum, mode = 'ltr') {
+  return Math.min(Math.max(0, maximum), Math.max(0, mode === 'negative' ? -value : mode === 'reverse' ? maximum - value : value));
+}