@ifc-lite/viewer 1.17.6 → 1.19.0

package/src/lib/search/tier1-index.test.ts

@@ -0,0 +1,242 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { StringTable, EntityTableBuilder } from '@ifc-lite/data';
+import type { IfcDataStore } from '@ifc-lite/parser';
+import {
+  buildTier1Index,
+  queryTier1Indexes,
+  __internal,
+  type Tier1Index,
+} from './tier1-index.js';
+
+function buildStore(rows: Array<{
+  expressId: number;
+  type: string;
+  globalId: string;
+  name: string;
+  description?: string;
+  objectType?: string;
+}>): IfcDataStore {
+  const strings = new StringTable();
+  const builder = new EntityTableBuilder(rows.length, strings);
+  for (const r of rows) {
+    builder.add(
+      r.expressId,
+      r.type,
+      r.globalId,
+      r.name,
+      r.description ?? '',
+      r.objectType ?? '',
+      false,
+      false,
+    );
+  }
+  const entities = builder.build();
+  return {
+    fileSize: 0,
+    schemaVersion: 'IFC4',
+    entityCount: rows.length,
+    parseTime: 0,
+    source: new Uint8Array(0),
+    entityIndex: { byId: { ranges: new Uint32Array(0), index: new Map() }, byType: new Map() },
+    strings,
+    entities,
+    properties: { count: 0 },
+    quantities: { count: 0 },
+    relationships: { count: 0 },
+  } as unknown as IfcDataStore;
+}
+
+const baseRows = [
+  { expressId: 10, type: 'IFCWALL', globalId: '1abcdefghijklmnopqrstu', name: 'Wall-EXT-001' },
+  { expressId: 20, type: 'IFCWALL', globalId: '2abcdefghijklmnopqrstu', name: 'Wall-INT-002' },
+  { expressId: 30, type: 'IFCDOOR', globalId: '3abcdefghijklmnopqrstu', name: 'Door-A-201' },
+  { expressId: 40, type: 'IFCWINDOW', globalId: '4abcdefghijklmnopqrstu', name: 'WIN-North-1', description: 'fire-rated' },
+  { expressId: 50, type: 'IFCSLAB', globalId: '5abcdefghijklmnopqrstu', name: '', objectType: 'SLAB-FLOOR' },
+  { expressId: 60, type: 'IFCWALL', globalId: '', name: '' }, // all-empty, should be skipped
+];
+
+describe('tokenize', () => {
+  it('splits on whitespace and IFC punctuation', () => {
+    assert.deepStrictEqual(__internal.tokenize('Wall-EXT-001'), ['wall', 'ext', '001']);
+    assert.deepStrictEqual(__internal.tokenize('Pset_WallCommon'), ['pset', 'wallcommon']);
+    assert.deepStrictEqual(__internal.tokenize('Level.01/Zone:A'), ['level', '01', 'zone']);
+  });
+
+  it('strips one-char non-digit tokens but keeps digits', () => {
+    assert.deepStrictEqual(__internal.tokenize('a b c 2'), ['2']);
+    assert.deepStrictEqual(__internal.tokenize('X-2-Y'), ['2']);
+  });
+
+  it('returns empty on empty input', () => {
+    assert.deepStrictEqual(__internal.tokenize(''), []);
+  });
+});
+
+describe('prefixRange', () => {
+  const tokens = ['apple', 'apricot', 'banana', 'blueberry', 'cherry'];
+  it('returns the [lo, hi) range of tokens matching the prefix', () => {
+    assert.deepStrictEqual(__internal.prefixRange(tokens, 'ap'), [0, 2]);
+    assert.deepStrictEqual(__internal.prefixRange(tokens, 'b'), [2, 4]);
+    assert.deepStrictEqual(__internal.prefixRange(tokens, 'cherry'), [4, 5]);
+  });
+  it('returns an empty range when the prefix does not match', () => {
+    const [lo, hi] = __internal.prefixRange(tokens, 'z');
+    assert.strictEqual(lo, hi);
+  });
+});
+
+describe('buildTier1Index', () => {
+  it('populates entries for non-empty rows and skips the all-empty row', async () => {
+    const store = buildStore(baseRows);
+    const idx = await buildTier1Index('m', store);
+    assert.strictEqual(idx.modelId, 'm');
+    assert.strictEqual(idx.sourceEntityCount, baseRows.length);
+    // Six rows in but row 60 is all-empty → 5 entries.
+    assert.strictEqual(idx.entries.length, 5);
+    assert.ok(idx.entries.every((e) => e.expressId !== 60));
+  });
+
+  it('tokenizes names, types, descriptions, and objectTypes into the token index', async () => {
+    const store = buildStore(baseRows);
+    const idx = await buildTier1Index('m', store);
+    assert.ok(idx.tokenIndex.has('wall'), 'type token "wall" is present');
+    assert.ok(idx.tokenIndex.has('ext'), 'name token "ext" is present');
+    assert.ok(idx.tokenIndex.has('fire'), 'description token "fire" is present');
+    assert.ok(idx.tokenIndex.has('slab'), 'objectType token "slab" is present');
+    // GUIDs are intentionally NOT tokenized.
+    assert.ok(!idx.tokenIndex.has('1abcdefghijklmnopqrstu'));
+  });
+
+  it('builds a case-sensitive globalIdMap for O(1) exact GUID lookup', async () => {
+    const store = buildStore(baseRows);
+    const idx = await buildTier1Index('m', store);
+    assert.strictEqual(idx.globalIdMap.size, 5);
+    assert.ok(idx.globalIdMap.has('3abcdefghijklmnopqrstu'));
+    // Empty GUIDs don't land in the map.
+    assert.ok(!idx.globalIdMap.has(''));
+  });
+
+  it('supports AbortSignal cancellation between chunks', async () => {
+    const manyRows = Array.from({ length: 500 }, (_, i) => ({
+      expressId: 1000 + i,
+      type: 'IFCWALL',
+      globalId: `g${String(i).padStart(21, 'x')}`,
+      name: `Wall-${i}`,
+    }));
+    const store = buildStore(manyRows);
+    const controller = new AbortController();
+    controller.abort();
+    await assert.rejects(
+      () => buildTier1Index('m', store, { signal: controller.signal, chunkSize: 50 }),
+      (err: unknown) => err instanceof DOMException && err.name === 'AbortError',
+    );
+  });
+
+  it('invokes the onProgress callback after each chunk', async () => {
+    const manyRows = Array.from({ length: 250 }, (_, i) => ({
+      expressId: 1000 + i,
+      type: 'IFCWALL',
+      globalId: `g${String(i).padStart(21, 'x')}`,
+      name: `Wall-${i}`,
+    }));
+    const store = buildStore(manyRows);
+    const progressValues: Array<{ done: number; total: number }> = [];
+    await buildTier1Index('m', store, {
+      chunkSize: 50,
+      onProgress: (done, total) => progressValues.push({ done, total }),
+    });
+    assert.ok(progressValues.length >= 5, 'at least one progress call per chunk');
+    assert.strictEqual(progressValues[progressValues.length - 1].done, 250);
+    assert.strictEqual(progressValues[progressValues.length - 1].total, 250);
+  });
+});
+
+describe('queryTier1Indexes', () => {
+  const makeIndex = async (id: string, rows: typeof baseRows): Promise<Tier1Index> => {
+    return buildTier1Index(id, buildStore(rows));
+  };
+
+  it('returns nothing for empty queries', async () => {
+    const idx = await makeIndex('m', baseRows);
+    assert.deepStrictEqual(queryTier1Indexes([idx], ''), []);
+    assert.deepStrictEqual(queryTier1Indexes([idx], '   '), []);
+  });
+
+  it('exact GUID match takes the fast path with highest score', async () => {
+    const idx = await makeIndex('m', baseRows);
+    const results = queryTier1Indexes([idx], '3abcdefghijklmnopqrstu');
+    assert.ok(results.length >= 1);
+    assert.strictEqual(results[0].expressId, 30);
+    assert.strictEqual(results[0].matchField, 'globalId');
+    assert.ok(results[0].score >= 1000);
+  });
+
+  it('matches by exact token with correct scoring precedence', async () => {
+    const idx = await makeIndex('m', baseRows);
+    const results = queryTier1Indexes([idx], 'wall');
+    // Three walls: two named Wall-EXT/Wall-INT (IFCWALL) AND the all-empty
+    // IFCWALL row is skipped → two results.
+    const ids = results.map((r) => r.expressId).sort((a, b) => a - b);
+    assert.deepStrictEqual(ids, [10, 20]);
+  });
+
+  it('prefix-expands single tokens ("wal" surfaces "wall")', async () => {
+    const idx = await makeIndex('m', baseRows);
+    const results = queryTier1Indexes([idx], 'wal');
+    const ids = results.map((r) => r.expressId).sort((a, b) => a - b);
+    // Should include both walls via prefix expansion.
+    assert.ok(ids.includes(10));
+    assert.ok(ids.includes(20));
+  });
+
+  it('matches by IFC type', async () => {
+    const idx = await makeIndex('m', baseRows);
+    const results = queryTier1Indexes([idx], 'ifcdoor');
+    assert.strictEqual(results.length, 1);
+    assert.strictEqual(results[0].expressId, 30);
+    assert.strictEqual(results[0].matchField, 'type');
+  });
+
+  it('matches description / objectType substrings even with no token hit', async () => {
+    const idx = await makeIndex('m', baseRows);
+    const desc = queryTier1Indexes([idx], 'fire-rated');
+    assert.ok(desc.some((r) => r.expressId === 40 && r.matchField === 'description'));
+
+    const obj = queryTier1Indexes([idx], 'slab-floor');
+    assert.ok(obj.some((r) => r.expressId === 50 && r.matchField === 'objectType'));
+  });
+
+  it('respects the result limit and orders by descending score', async () => {
+    const many = Array.from({ length: 20 }, (_, i) => ({
+      expressId: 100 + i,
+      type: 'IFCWALL',
+      globalId: `g${String(i).padStart(21, 'x')}`,
+      name: i === 0 ? 'wall' : `wall-${i}`,
+    }));
+    const idx = await buildTier1Index('m', buildStore(many));
+    const results = queryTier1Indexes([idx], 'wall', { limit: 5 });
+    assert.strictEqual(results.length, 5);
+    // Exact-match "wall" row outranks the prefix/token-only siblings.
+    assert.strictEqual(results[0].name, 'wall');
+    for (let i = 1; i < results.length; i++) {
+      assert.ok(results[i - 1].score >= results[i].score);
+    }
+  });
+
+  it('merges results across multiple federated indexes and dedupes', async () => {
+    const a = await buildTier1Index('A', buildStore([
+      { expressId: 1, type: 'IFCWALL', globalId: 'aaaaaaaaaaaaaaaaaaaaaa', name: 'Lobby-Wall' },
+    ]));
+    const b = await buildTier1Index('B', buildStore([
+      { expressId: 2, type: 'IFCWALL', globalId: 'bbbbbbbbbbbbbbbbbbbbbb', name: 'Tower-Wall' },
+    ]));
+    const results = queryTier1Indexes([a, b], 'wall');
+    const tagged = results.map((r) => `${r.modelId}:${r.expressId}`).sort();
+    assert.deepStrictEqual(tagged, ['A:1', 'B:2']);
+  });
+});

package/src/lib/search/tier1-index.ts

@@ -0,0 +1,448 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Tier-1 search index — a per-model inverted token index built AFTER
+ * the IFC load completes (triggered by useSearchIndex once the store
+ * is present). Zero work on the load hot path; the build itself yields
+ * to the event loop every `chunkSize` rows via MessageChannel so a
+ * 4M-entity index never blocks input.
+ *
+ * Tier-1 replaces the Tier-0 linear scan transparently for any model
+ * that has finished indexing. Models still being indexed (or models
+ * that lost their index) fall back to Tier-0 without any caller
+ * awareness — see `SearchInline`.
+ *
+ * Indexed fields (all already materialised in EntityTable by the
+ * parser — no on-demand extraction is ever triggered):
+ *   - name, globalId, description, objectType, IFC type name
+ *
+ * Tokenisation splits on whitespace AND the punctuation common in IFC
+ * names (`-`, `_`, `.`, `/`, `:`) so "Wall-EXT-001" and "Pset_WallCommon"
+ * break into useful tokens.
+ */
+
+import type { IfcDataStore } from '@ifc-lite/parser';
+import type { SearchResult, MatchField } from './tier0-scan.js';
+
+export interface Tier1IndexEntry {
+  /** Row index in the original EntityTable. */
+  rowIndex: number;
+  expressId: number;
+  typeEnum: number;
+  /** IFC type name resolved once at build time (e.g. "IfcWall"). */
+  typeName: string;
+  typeNameLower: string;
+  name: string;
+  nameLower: string;
+  globalId: string;
+  description: string;
+  descriptionLower: string;
+  objectType: string;
+  objectTypeLower: string;
+}
+
+export interface Tier1Index {
+  modelId: string;
+  /** Sparse — populated rows only (same empty-row filter as Tier-0). */
+  entries: Tier1IndexEntry[];
+  /** token → indexes into `entries`; values are Uint32Arrays to avoid GC churn. */
+  tokenIndex: Map<string, Uint32Array>;
+  /** Sorted unique token list for prefix range queries (binary search). */
+  sortedTokens: string[];
+  /** GlobalId exact lookup → index into `entries`. Case-sensitive (IFC GUIDs are). */
+  globalIdMap: Map<string, number>;
+  /** Total entity count in the source store (for diagnostics, not query). */
+  sourceEntityCount: number;
+  /** Wall-clock build duration in ms. */
+  buildTimeMs: number;
+}
+
+export interface BuildTier1IndexOptions {
+  /** Rows per yield point. Default 20_000 — ~3 yields for a 147K model, ~220 for 4.4M. */
+  chunkSize?: number;
+  /** Abort the build early (e.g. model was removed or replaced). */
+  signal?: AbortSignal;
+  /** Optional progress callback — called after each chunk. Cheap observer only. */
+  onProgress?: (done: number, total: number) => void;
+}
+
+const DEFAULT_CHUNK_SIZE = 20_000;
+
+// Same scoring ladder as Tier-0 so result ordering between the two tiers
+// stays comparable while a multi-model search straddles both paths.
+const SCORE = {
+  GUID_EXACT: 1000,
+  NAME_EXACT: 500,
+  NAME_PREFIX: 100,
+  TYPE_EXACT: 80,
+  TYPE_PREFIX: 60,
+  NAME_SUBSTR: 40,
+  OBJECTTYPE_SUBSTR: 20,
+  DESCRIPTION_SUBSTR: 10,
+  TOKEN_MATCH: 70,
+} as const;
+
+const TOKEN_SPLIT = /[\s\-_./:]+/;
+
+function tokenize(value: string): string[] {
+  if (!value) return [];
+  const out: string[] = [];
+  const parts = value.toLowerCase().split(TOKEN_SPLIT);
+  for (const p of parts) {
+    // Skip empty fragments and one-char tokens that aren't digits. One-char
+    // letters produce ~O(entities) postings with essentially no selectivity,
+    // inflating the index for no query benefit.
+    if (p.length === 0) continue;
+    if (p.length === 1 && !/\d/.test(p)) continue;
+    out.push(p);
+  }
+  return out;
+}
+
+/** Yield control back to the event loop between chunks.
+ *
+ *  Mirrors the pattern used by `packages/parser/src/columnar-parser.ts`
+ *  but closes the MessageChannel ports in the fallback path — an unclosed
+ *  port keeps Node's event loop alive and hangs the test runner on
+ *  shutdown. `scheduler.yield` (when present) and `setImmediate` (Node)
+ *  don't have this problem.
+ */
+function yieldToEventLoop(): Promise<void> {
+  const maybeScheduler = (globalThis as typeof globalThis & {
+    scheduler?: { yield?: () => Promise<void> };
+  }).scheduler;
+  if (typeof maybeScheduler?.yield === 'function') {
+    return maybeScheduler.yield();
+  }
+  if (typeof setImmediate === 'function') {
+    return new Promise<void>((resolve) => {
+      setImmediate(() => resolve());
+    });
+  }
+  return new Promise<void>((resolve) => {
+    const channel = new MessageChannel();
+    channel.port1.onmessage = () => {
+      channel.port1.close();
+      channel.port2.close();
+      resolve();
+    };
+    channel.port2.postMessage(null);
+  });
+}
+
+/**
+ * Build a Tier-1 index over one model. Runs on the main thread but yields
+ * between chunks so input latency stays below ~16 ms per yield point.
+ *
+ * Must only be called AFTER `store` is fully populated (i.e. the model's
+ * `ifcDataStore` is non-null in the viewer store). Calling during the load
+ * phase is a bug — the caller should gate on the model-ready event.
+ */
+export async function buildTier1Index(
+  modelId: string,
+  store: IfcDataStore,
+  options: BuildTier1IndexOptions = {},
+): Promise<Tier1Index> {
+  const start = performance.now();
+  const chunkSize = options.chunkSize ?? DEFAULT_CHUNK_SIZE;
+  const signal = options.signal;
+  const onProgress = options.onProgress;
+
+  const table = store.entities;
+  const strings = store.strings;
+  const count = table.count;
+
+  const expressIdCol = table.expressId;
+  const typeEnumCol = table.typeEnum;
+  const nameCol = table.name;
+  const globalIdCol = table.globalId;
+  const descriptionCol = table.description;
+  const objectTypeCol = table.objectType;
+
+  const entries: Tier1IndexEntry[] = [];
+  // Build token postings as number[] arrays then freeze each to Uint32Array
+  // at the end — avoids a growing Uint32Array copy per insertion.
+  const pending = new Map<string, number[]>();
+  const globalIdMap = new Map<string, number>();
+
+  for (let start = 0; start < count; start += chunkSize) {
+    if (signal?.aborted) {
+      throw new DOMException('buildTier1Index aborted', 'AbortError');
+    }
+    const end = Math.min(start + chunkSize, count);
+    for (let i = start; i < end; i++) {
+      const nIdx = nameCol[i];
+      const gIdx = globalIdCol[i];
+      const dIdx = descriptionCol[i];
+      const oIdx = objectTypeCol[i];
+      // Same empty-row shortcut as Tier-0: rows with no searchable string
+      // slot at all are skipped entirely.
+      if (nIdx === 0 && gIdx === 0 && dIdx === 0 && oIdx === 0) continue;
+
+      const expressId = expressIdCol[i];
+      const name = nIdx !== 0 ? strings.get(nIdx) : '';
+      const globalId = gIdx !== 0 ? strings.get(gIdx) : '';
+      const description = dIdx !== 0 ? strings.get(dIdx) : '';
+      const objectType = oIdx !== 0 ? strings.get(oIdx) : '';
+      const typeName = table.getTypeName(expressId);
+
+      const entryIndex = entries.length;
+      entries.push({
+        rowIndex: i,
+        expressId,
+        typeEnum: typeEnumCol[i],
+        typeName,
+        typeNameLower: typeName.toLowerCase(),
+        name,
+        nameLower: name.toLowerCase(),
+        globalId,
+        description,
+        descriptionLower: description.toLowerCase(),
+        objectType,
+        objectTypeLower: objectType.toLowerCase(),
+      });
+
+      if (globalId) globalIdMap.set(globalId, entryIndex);
+
+      // Insert all tokens from name, type, description, objectType — NOT
+      // globalId (GUIDs are opaque 22-char strings; token-matching them
+      // just bloats the index).
+      const seen = new Set<string>();
+      const addTokens = (s: string) => {
+        for (const t of tokenize(s)) {
+          if (seen.has(t)) continue;
+          seen.add(t);
+          let list = pending.get(t);
+          if (!list) {
+            list = [];
+            pending.set(t, list);
+          }
+          list.push(entryIndex);
+        }
+      };
+      addTokens(name);
+      addTokens(typeName);
+      addTokens(description);
+      addTokens(objectType);
+    }
+
+    onProgress?.(end, count);
+    if (end < count) await yieldToEventLoop();
+  }
+
+  const tokenIndex = new Map<string, Uint32Array>();
+  for (const [token, list] of pending) {
+    tokenIndex.set(token, Uint32Array.from(list));
+  }
+  const sortedTokens = Array.from(tokenIndex.keys()).sort();
+
+  return {
+    modelId,
+    entries,
+    tokenIndex,
+    sortedTokens,
+    globalIdMap,
+    sourceEntityCount: count,
+    buildTimeMs: performance.now() - start,
+  };
+}
+
+/** Binary-search the sorted-tokens array for all tokens starting with `prefix`.
+ *  Returns the half-open range [lo, hi) in `sortedTokens`. */
+function prefixRange(sortedTokens: readonly string[], prefix: string): [number, number] {
+  if (!prefix) return [0, 0];
+  let lo = 0;
+  let hi = sortedTokens.length;
+  // Lower bound — first index with sortedTokens[i] >= prefix.
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (sortedTokens[mid] < prefix) lo = mid + 1;
+    else hi = mid;
+  }
+  const start = lo;
+  // Upper bound — first index with sortedTokens[i] NOT starting with prefix.
+  hi = sortedTokens.length;
+  let end = start;
+  // Bump the last char of `prefix` by one to find the first token past the
+  // prefix range. Works for any code point short of U+FFFF.
+  const bump = prefix.slice(0, -1) + String.fromCharCode(prefix.charCodeAt(prefix.length - 1) + 1);
+  let l = start;
+  while (l < hi) {
+    const mid = (l + hi) >>> 1;
+    if (sortedTokens[mid] < bump) l = mid + 1;
+    else hi = mid;
+  }
+  end = l;
+  return [start, end];
+}
+
+interface ScoredCandidate {
+  entryIndex: number;
+  score: number;
+  matchField: MatchField;
+}
+
+/**
+ * Query one or more Tier-1 indexes. Results from all indexes are merged,
+ * deduped, sorted by descending score, and capped at `limit`. The shape
+ * matches `runTier0Scan` so `SearchInline` can concatenate Tier-0 and
+ * Tier-1 result streams without a converter.
+ */
+export function queryTier1Indexes(
+  indexes: Iterable<Tier1Index>,
+  query: string,
+  options: { limit?: number } = {},
+): SearchResult[] {
+  const trimmed = query.trim();
+  if (trimmed.length < 1) return [];
+  const limit = options.limit ?? 50;
+  const needle = trimmed.toLowerCase();
+  const queryTokens = tokenize(trimmed);
+  const looksLikeGuid = trimmed.length === 22 && /^[A-Za-z0-9_$]{22}$/.test(trimmed);
+
+  const results: SearchResult[] = [];
+
+  for (const index of indexes) {
+    const scored = scoreOneIndex(index, trimmed, needle, queryTokens, looksLikeGuid);
+    for (const c of scored) {
+      const e = index.entries[c.entryIndex];
+      results.push({
+        modelId: index.modelId,
+        expressId: e.expressId,
+        typeName: e.typeName,
+        name: e.name,
+        globalId: e.globalId,
+        description: e.description,
+        objectType: e.objectType,
+        matchField: c.matchField,
+        score: c.score,
+      });
+    }
+  }
+
+  results.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    if (a.modelId !== b.modelId) return a.modelId < b.modelId ? -1 : 1;
+    return a.expressId - b.expressId;
+  });
+
+  const seen = new Set<string>();
+  const out: SearchResult[] = [];
+  for (const r of results) {
+    const key = `${r.modelId}:${r.expressId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(r);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+function scoreOneIndex(
+  index: Tier1Index,
+  rawQuery: string,
+  needle: string,
+  queryTokens: string[],
+  looksLikeGuid: boolean,
+): ScoredCandidate[] {
+  const scored = new Map<number, ScoredCandidate>();
+
+  const bump = (entryIndex: number, score: number, matchField: MatchField) => {
+    const prev = scored.get(entryIndex);
+    if (!prev || prev.score < score) {
+      scored.set(entryIndex, { entryIndex, score, matchField });
+    }
+  };
+
+  // GUID exact — O(1) and highest-ranked.
+  if (looksLikeGuid) {
+    const hit = index.globalIdMap.get(rawQuery);
+    if (hit !== undefined) bump(hit, SCORE.GUID_EXACT, 'globalId');
+  }
+
+  // Candidate pool from the token index. For each query token:
+  //   1. Exact token postings → TOKEN_MATCH per hit
+  //   2. Prefix-matching tokens via sortedTokens range → TOKEN_MATCH
+  // When the user typed a single token we still do a prefix expansion so
+  // "wal" surfaces results with a "wall" token before they finish typing.
+  const candidateSet = new Set<number>();
+  const queryTokenHits = new Map<number, number>(); // entryIndex → count of query tokens matched
+
+  for (const qt of queryTokens) {
+    const matchedEntries = new Set<number>();
+    const exact = index.tokenIndex.get(qt);
+    if (exact) {
+      for (let i = 0; i < exact.length; i++) matchedEntries.add(exact[i]);
+    }
+    // Prefix expansion for all query tokens (cheap when token count is small).
+    const [plo, phi] = prefixRange(index.sortedTokens, qt);
+    for (let ti = plo; ti < phi; ti++) {
+      const tok = index.sortedTokens[ti];
+      if (tok === qt) continue;
+      const list = index.tokenIndex.get(tok);
+      if (!list) continue;
+      for (let i = 0; i < list.length; i++) matchedEntries.add(list[i]);
+    }
+    for (const entryIndex of matchedEntries) {
+      candidateSet.add(entryIndex);
+      queryTokenHits.set(entryIndex, (queryTokenHits.get(entryIndex) ?? 0) + 1);
+    }
+  }
+
+  // Verify candidates against the full lowered strings first — this
+  // resolves the matchField accurately (name / type / objectType /
+  // description) when any substring-level match lands. If nothing
+  // substring-level matches, the entry still qualifies via full token
+  // coverage and falls back to a generic TOKEN_MATCH.
+  for (const entryIndex of candidateSet) {
+    const e = index.entries[entryIndex];
+    const preSize = scored.size;
+    scoreEntry(e, needle, entryIndex, bump);
+    if (scored.size === preSize) {
+      const hits = queryTokenHits.get(entryIndex) ?? 0;
+      if (queryTokens.length > 0 && hits === queryTokens.length) {
+        bump(entryIndex, SCORE.TOKEN_MATCH, 'name');
+      }
+    }
+  }
+
+  // Substring-fallback pass: for very short needles (<3 chars) OR needles
+  // that contain punctuation the tokenizer would strip, the token index
+  // has no coverage. Do a last-ditch linear sweep over the entries array.
+  // This is still bounded by `entries.length` (populated rows only) not
+  // the raw entity count, so it stays ~10× cheaper than Tier-0.
+  if (candidateSet.size === 0 && (needle.length < 3 || /[\s\-_./:]/.test(needle))) {
+    const entries = index.entries;
+    for (let i = 0; i < entries.length; i++) {
+      scoreEntry(entries[i], needle, i, bump);
+    }
+  }
+
+  return Array.from(scored.values());
+}
+
+function scoreEntry(
+  e: Tier1IndexEntry,
+  needle: string,
+  entryIndex: number,
+  bump: (entryIndex: number, score: number, matchField: MatchField) => void,
+): void {
+  if (e.nameLower) {
+    if (e.nameLower === needle) bump(entryIndex, SCORE.NAME_EXACT, 'name');
+    else if (e.nameLower.startsWith(needle)) bump(entryIndex, SCORE.NAME_PREFIX, 'name');
+    else if (e.nameLower.includes(needle)) bump(entryIndex, SCORE.NAME_SUBSTR, 'name');
+  }
+  if (e.typeNameLower === needle) bump(entryIndex, SCORE.TYPE_EXACT, 'type');
+  else if (e.typeNameLower.startsWith(needle)) bump(entryIndex, SCORE.TYPE_PREFIX, 'type');
+  if (e.objectTypeLower && e.objectTypeLower.includes(needle)) {
+    bump(entryIndex, SCORE.OBJECTTYPE_SUBSTR, 'objectType');
+  }
+  if (e.descriptionLower && e.descriptionLower.includes(needle)) {
+    bump(entryIndex, SCORE.DESCRIPTION_SUBSTR, 'description');
+  }
+}
+
+/** Exposed for tests only. */
+export const __internal = { tokenize, prefixRange };