sweet-search 2.5.1 → 2.5.3

package/core/infrastructure/code-graph-visibility.js

@@ -0,0 +1,157 @@
+import { readFileSync } from 'fs';
+import { dirname, isAbsolute, join } from 'path';
+
+export function readAdjacentManifest(dbPath) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(dirname(dbPath), 'reconcile-manifest.json'), 'utf8'));
+    return Number.isInteger(manifest?.epoch) ? manifest : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readAdjacentManifestEpoch(dbPath) {
+  return readAdjacentManifest(dbPath)?.epoch ?? null;
+}
+
+export function resolveManifestCodeGraphPath(dbPath, manifest = readAdjacentManifest(dbPath)) {
+  const descriptor = manifest?.codeGraph?.path || manifest?.codeGraph?.dbPath;
+  if (!descriptor || typeof descriptor !== 'string') return dbPath;
+  return isAbsolute(descriptor) ? descriptor : join(dirname(dbPath), descriptor);
+}
+
+function hasColumns(db, table, columns) {
+  const names = new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((row) => row.name));
+  return columns.every((column) => names.has(column));
+}
+
+export function sqlAliasPrefix(alias = '') {
+  if (!alias) return '';
+  const normalized = String(alias).endsWith('.') ? String(alias).slice(0, -1) : String(alias);
+  return normalized ? `${normalized}.` : '';
+}
+
+export function createCodeGraphVisibility(db, manifestEpoch) {
+  return {
+    manifestEpoch: Number.isInteger(manifestEpoch) ? manifestEpoch : null,
+    entities: hasColumns(db, 'entities', ['epoch_written', 'epoch_retired']),
+    relationships: hasColumns(db, 'relationships', ['epoch_written', 'epoch_retired']),
+  };
+}
+
+export function entityVisibilitySql(visibility, alias = '') {
+  const prefix = sqlAliasPrefix(alias);
+  if (!visibility?.entities) return `${prefix}stale_since IS NULL`;
+  if (Number.isInteger(visibility.manifestEpoch)) {
+    return `(${prefix}epoch_written IS NULL OR ${prefix}epoch_written <= ?)
+      AND (${prefix}epoch_retired IS NULL OR ${prefix}epoch_retired > ?)
+      AND (${prefix}stale_since IS NULL OR (${prefix}epoch_retired IS NOT NULL AND ${prefix}epoch_retired > ?))`;
+  }
+  return `${prefix}stale_since IS NULL AND ${prefix}epoch_retired IS NULL`;
+}
+
+export function entityVisibilityParams(visibility) {
+  if (!visibility?.entities || !Number.isInteger(visibility.manifestEpoch)) return [];
+  return [visibility.manifestEpoch, visibility.manifestEpoch, visibility.manifestEpoch];
+}
+
+export function relationshipVisibilitySql(visibility, alias = 'r') {
+  if (!visibility?.relationships) return '1=1';
+  const prefix = sqlAliasPrefix(alias);
+  if (Number.isInteger(visibility.manifestEpoch)) {
+    return `(${prefix}epoch_written IS NULL OR ${prefix}epoch_written <= ?)
+      AND (${prefix}epoch_retired IS NULL OR ${prefix}epoch_retired > ?)`;
+  }
+  return `${prefix}epoch_retired IS NULL`;
+}
+
+export function relationshipVisibilityParams(visibility) {
+  if (!visibility?.relationships || !Number.isInteger(visibility.manifestEpoch)) return [];
+  return [visibility.manifestEpoch, visibility.manifestEpoch];
+}
+
+export class CodeGraphReaderVisibility {
+  constructor(baseDbPath, opts = {}) {
+    this.baseDbPath = baseDbPath;
+    this.explicitManifestEpoch = Number.isInteger(opts.manifestEpoch);
+    this.manifestEpoch = this.explicitManifestEpoch ? opts.manifestEpoch : null;
+    const manifest = this.explicitManifestEpoch ? readAdjacentManifest(this.baseDbPath) : null;
+    this.dbPath = this.explicitManifestEpoch
+      ? resolveManifestCodeGraphPath(this.baseDbPath, manifest)
+      : baseDbPath;
+    this._visibility = null;
+    this._hasHcgsSummaryMetadata = null;
+    this._summaryVisibilityCache = new Map();
+    if (!this.explicitManifestEpoch) this.sync();
+  }
+
+  sync(onChange) {
+    if (this.explicitManifestEpoch) return false;
+    const manifest = readAdjacentManifest(this.baseDbPath);
+    const nextEpoch = Number.isInteger(manifest?.epoch) ? manifest.epoch : null;
+    const nextDbPath = resolveManifestCodeGraphPath(this.baseDbPath, manifest);
+    const changed = nextEpoch !== this.manifestEpoch || nextDbPath !== this.dbPath;
+    this.manifestEpoch = nextEpoch;
+    this.dbPath = nextDbPath;
+    if (changed) {
+      this.reset();
+      if (typeof onChange === 'function') onChange();
+    }
+    return changed;
+  }
+
+  reset() {
+    this._visibility = null;
+    this._hasHcgsSummaryMetadata = null;
+    this._summaryVisibilityCache = new Map();
+  }
+
+  state(db) {
+    if (!this._visibility) this._visibility = createCodeGraphVisibility(db, this.manifestEpoch);
+    return this._visibility;
+  }
+
+  entitySql(db, alias = '') { return entityVisibilitySql(this.state(db), alias); }
+  entityParams(db) { return entityVisibilityParams(this.state(db)); }
+  relationshipSql(db, alias = 'r') { return relationshipVisibilitySql(this.state(db), alias); }
+  relationshipParams(db) { return relationshipVisibilityParams(this.state(db)); }
+
+  hasSummarySidecar(db) {
+    if (
+      this._hasHcgsSummaryMetadata === null
+      || (this._hasHcgsSummaryMetadata === false && this.manifestEpoch === null)
+    ) {
+      this._hasHcgsSummaryMetadata = !!db.prepare(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='hcgs_summary_metadata'",
+      ).get();
+    }
+    return this._hasHcgsSummaryMetadata;
+  }
+
+  summaryVisible(db, entityId) {
+    if (!entityId || !this.hasSummarySidecar(db)) return true;
+    if (this.manifestEpoch === null) {
+      const row = db.prepare(`
+        SELECT epoch_retired
+        FROM hcgs_summary_metadata
+        WHERE entity_id = ?
+      `).get(String(entityId));
+      return row ? row.epoch_retired == null : false;
+    }
+    const key = `${entityId}:${this.manifestEpoch ?? 'live'}`;
+    if (this._summaryVisibilityCache.has(key)) return this._summaryVisibilityCache.get(key);
+    const row = db.prepare(`
+      SELECT epoch_written, epoch_retired
+      FROM hcgs_summary_metadata
+      WHERE entity_id = ?
+    `).get(String(entityId));
+    const visible = row
+      ? (Number.isInteger(this.manifestEpoch)
+        ? (row.epoch_written == null || row.epoch_written <= this.manifestEpoch)
+          && (row.epoch_retired == null || row.epoch_retired > this.manifestEpoch)
+        : row.epoch_retired == null)
+      : false;
+    this._summaryVisibilityCache.set(key, visible);
+    return visible;
+  }
+}

package/core/infrastructure/codebase-repository.js

@@ -6,16 +6,68 @@
  */
 
 import Database from 'better-sqlite3';
-import { applyReadPragmas } from './db-utils.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { applyReadPragmas, assertInClauseSize } from './db-utils.js';
+
+function readAdjacentManifest(dbPath) {
+  try {
+    const manifestPath = path.join(path.dirname(dbPath), 'reconcile-manifest.json');
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    return Number.isInteger(manifest?.epoch) ? manifest : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveManifestVectorsPath(dbPath, manifest = readAdjacentManifest(dbPath)) {
+  const descriptor = manifest?.vectors?.path || manifest?.vectors?.dbPath;
+  if (!descriptor || typeof descriptor !== 'string') return dbPath;
+  return path.isAbsolute(descriptor) ? descriptor : path.join(path.dirname(dbPath), descriptor);
+}
 
 export class CodebaseRepository {
-  constructor(dbPath) {
-    this._dbPath = dbPath;
+  constructor(dbPath, options = {}) {
+    this._baseDbPath = dbPath;
+    this._explicitManifestEpoch = Number.isInteger(options.manifestEpoch);
+    this._manifestEpoch = this._explicitManifestEpoch ? options.manifestEpoch : null;
+    const manifest = this._explicitManifestEpoch ? readAdjacentManifest(this._baseDbPath) : null;
+    this._dbPath = this._explicitManifestEpoch
+      ? resolveManifestVectorsPath(this._baseDbPath, manifest)
+      : dbPath;
     this._db = null;
+    this._hasEpochVisibility = null;
+    if (!this._explicitManifestEpoch) {
+      this._syncAdjacentManifest();
+    }
+  }
+
+  _syncAdjacentManifest() {
+    if (this._explicitManifestEpoch) return false;
+    const manifest = readAdjacentManifest(this._baseDbPath);
+    const nextEpoch = Number.isInteger(manifest?.epoch) ? manifest.epoch : null;
+    const nextDbPath = resolveManifestVectorsPath(this._baseDbPath, manifest);
+    const changed = nextEpoch !== this._manifestEpoch || nextDbPath !== this._dbPath;
+    this._manifestEpoch = nextEpoch;
+    this._dbPath = nextDbPath;
+    if (changed) {
+      this.close();
+    }
+    return changed;
+  }
+
+  refreshManifestEpoch() {
+    this._syncAdjacentManifest();
+    return this._manifestEpoch;
+  }
+
+  getManifestEpoch() {
+    return this._manifestEpoch;
   }
 
   /** Lazy read-only connection with optimized pragmas. */
   _open() {
+    this._syncAdjacentManifest();
     if (!this._db) {
       this._db = new Database(this._dbPath, { readonly: true });
       applyReadPragmas(this._db);
@@ -23,13 +75,31 @@ export class CodebaseRepository {
     return this._db;
   }
 
+  _visibility(db) {
+    if (this._hasEpochVisibility === null) {
+      const cols = db.prepare('PRAGMA table_info(vectors)').all().map((c) => c.name);
+      this._hasEpochVisibility = cols.includes('epoch_written') && cols.includes('epoch_retired');
+    }
+    if (!this._hasEpochVisibility) return { sql: '', params: [] };
+    if (this._manifestEpoch !== null) {
+      return {
+        sql: '(epoch_written IS NULL OR epoch_written <= ?) AND (epoch_retired IS NULL OR epoch_retired > ?)',
+        params: [this._manifestEpoch, this._manifestEpoch],
+      };
+    }
+    return { sql: 'epoch_retired IS NULL', params: [] };
+  }
+
   /**
    * Iterate all vectors (for O(N) scan or chunk type map building).
    * Returns rows with: id, embedding (Buffer), text, metadata (string), file_path.
    */
   * iterateVectors() {
     const db = this._open();
-    yield* db.prepare('SELECT id, embedding, text, metadata, file_path FROM vectors').iterate();
+    const visibility = this._visibility(db);
+    const where = visibility.sql ? ` WHERE ${visibility.sql}` : '';
+    yield* db.prepare(`SELECT id, embedding, text, metadata, file_path FROM vectors${where}`)
+      .iterate(...visibility.params);
   }
 
   /**
@@ -40,12 +110,15 @@ export class CodebaseRepository {
   getEmbeddingsByIds(ids) {
     const uniqueIds = [...new Set(ids)];
     if (uniqueIds.length === 0) return new Map();
+    assertInClauseSize(uniqueIds.length, 'CodebaseRepository.getEmbeddingsByIds');
 
     const db = this._open();
     const placeholders = uniqueIds.map(() => '?').join(',');
+    const visibility = this._visibility(db);
+    const visibilityClause = visibility.sql ? ` AND ${visibility.sql}` : '';
     const rows = db.prepare(
-      `SELECT id, embedding FROM vectors WHERE id IN (${placeholders})`
-    ).all(...uniqueIds);
+      `SELECT id, embedding FROM vectors WHERE id IN (${placeholders})${visibilityClause}`
+    ).all(...uniqueIds, ...visibility.params);
 
     const result = new Map();
     for (const row of rows) {
@@ -67,11 +140,14 @@ export class CodebaseRepository {
   getChunkTexts(ids) {
     if (!ids || ids.length === 0) return new Map();
     try {
+      assertInClauseSize(ids.length, 'CodebaseRepository.getChunkTexts');
       const db = this._open();
       const ph = ids.map(() => '?').join(',');
+      const visibility = this._visibility(db);
+      const visibilityClause = visibility.sql ? ` AND ${visibility.sql}` : '';
       const rows = db.prepare(
-        `SELECT id, text FROM vectors WHERE id IN (${ph})`
-      ).all(...ids);
+        `SELECT id, text FROM vectors WHERE id IN (${ph})${visibilityClause}`
+      ).all(...ids, ...visibility.params);
       return new Map(rows.map(r => [r.id, r.text]));
     } catch {
       return new Map();
@@ -91,9 +167,11 @@ export class CodebaseRepository {
     if (!filePath) return [];
     try {
       const db = this._open();
+      const visibility = this._visibility(db);
+      const visibilityClause = visibility.sql ? ` AND ${visibility.sql}` : '';
       return db.prepare(
-        'SELECT id, file_path, text, metadata FROM vectors WHERE file_path = ? ORDER BY id'
-      ).all(filePath);
+        `SELECT id, file_path, text, metadata FROM vectors WHERE file_path = ?${visibilityClause} ORDER BY id`
+      ).all(filePath, ...visibility.params);
     } catch {
       return [];
     }
@@ -105,10 +183,14 @@ export class CodebaseRepository {
    * @returns {Array<{id, embedding: Buffer, text: string, metadata: string}>}
    */
   scanAllVectors() {
+    this._syncAdjacentManifest();
     const db = new Database(this._dbPath, { readonly: true });
     applyReadPragmas(db);
     try {
-      return db.prepare('SELECT id, embedding, text, metadata FROM vectors').all();
+      const visibility = this._visibility(db);
+      const where = visibility.sql ? ` WHERE ${visibility.sql}` : '';
+      return db.prepare(`SELECT id, embedding, text, metadata FROM vectors${where}`)
+        .all(...visibility.params);
     } finally {
       db.close();
     }
@@ -128,19 +210,23 @@ export class CodebaseRepository {
     if (!clusterIds || clusterIds.length === 0) return [];
     const uniqueClusters = [...new Set(clusterIds)];
     const uniqueExclude = [...new Set(excludeIds)];
+    assertInClauseSize(uniqueClusters.length, 'CodebaseRepository.findSiblingsByClusterIds.clusters');
+    assertInClauseSize(uniqueExclude.length, 'CodebaseRepository.findSiblingsByClusterIds.exclude');
     const db = this._open();
 
     const clusterPh = uniqueClusters.map(() => '?').join(',');
     const excludePh = uniqueExclude.map(() => '?').join(',');
     const excludeClause = uniqueExclude.length > 0 ? ` AND id NOT IN (${excludePh})` : '';
+    const visibility = this._visibility(db);
+    const visibilityClause = visibility.sql ? ` AND ${visibility.sql}` : '';
 
     const sql = `
       SELECT id, file_path, text, metadata
       FROM vectors
-      WHERE json_extract(metadata, '$.clusterId') IN (${clusterPh})${excludeClause}
+      WHERE json_extract(metadata, '$.clusterId') IN (${clusterPh})${excludeClause}${visibilityClause}
     `;
 
-    return db.prepare(sql).all(...uniqueClusters, ...uniqueExclude);
+    return db.prepare(sql).all(...uniqueClusters, ...uniqueExclude, ...visibility.params);
   }
 
   close() {
@@ -148,5 +234,6 @@ export class CodebaseRepository {
       this._db.close();
       this._db = null;
     }
+    this._hasEpochVisibility = null;
   }
 }

package/core/infrastructure/config/search.js

@@ -61,7 +61,7 @@ export const FILE_PATTERNS = {
     '**/*.{rb,erb}',                       // Ruby
     '**/*.php',                             // PHP
     '**/*.{swift,m,mm}',                   // Apple
-    '**/*.{lua,zig,nim,ex,exs}',           // Other
+    '**/*.{lua,zig,nim,ex,exs,dart}',      // Other
     '**/*.{sh,bash,zsh,fish,ps1}',         // Shell
     '**/*.sql',                             // SQL
     '**/*.proto',                           // Protobuf

package/core/infrastructure/db-utils.js

@@ -4,6 +4,19 @@
 
 import Database from 'better-sqlite3';
 
+/**
+ * Maximum number of bound parameters in a single SQLite statement.
+ *
+ * SQLite's compiled-in `SQLITE_LIMIT_VARIABLE_NUMBER` is 32766 on builds
+ * since 3.32, but the historic floor is 999, and `better-sqlite3` does
+ * not expose `sqlite3_limit()` to raise it at runtime. Using 999 makes
+ * `chunkedIn()` safe against any SQLite version or fork the runtime may
+ * be vendoring, with no dependency on binding internals.
+ *
+ * Reference: https://www.sqlite.org/limits.html (LIMIT_VARIABLE_NUMBER).
+ */
+export const SAFE_IN_CLAUSE_BATCH = 999;
+
 /**
  * Apply read-path PRAGMA optimizations to a read-only database connection.
  *
@@ -43,6 +56,111 @@ export function applyReadPragmas(db, options = {}) {
   }
 }
 
+/**
+ * Throw if an array would overflow SQLite's bound-parameter limit when
+ * splatted into a single `IN (?,?,...)` clause. Use this at sites that
+ * cannot easily be migrated to {@link chunkedIn} (e.g. UPDATE/DELETE with
+ * non-trivial templates, or queries with multiple interpolated
+ * placeholder groups) as a fail-fast guard. Crash with a clear domain
+ * message instead of the opaque "too many SQL variables" from SQLite.
+ *
+ * @param {number} n - Length of the values array
+ * @param {string} [siteLabel] - Caller identifier for the error message
+ */
+export function assertInClauseSize(n, siteLabel = 'IN clause') {
+  if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) {
+    throw new TypeError(`assertInClauseSize: invalid size ${String(n)}`);
+  }
+  if (n > SAFE_IN_CLAUSE_BATCH) {
+    throw new RangeError(
+      `${siteLabel} would bind ${n} parameters; SQLite IN(?,?,...) clauses ` +
+      `must be chunked at SAFE_IN_CLAUSE_BATCH=${SAFE_IN_CLAUSE_BATCH}. ` +
+      `Migrate this call to chunkedIn() in core/infrastructure/db-utils.js.`
+    );
+  }
+}
+
+/**
+ * Execute a SELECT-style query with a dynamic `IN (?,?,...)` clause across
+ * an arbitrarily large `values` array by chunking the binds at
+ * {@link SAFE_IN_CLAUSE_BATCH}. The caller passes a SQL template that
+ * contains the literal token `__IN_PLACEHOLDERS__` exactly once; the
+ * helper replaces it with the right number of `?`s per batch and unions
+ * the per-batch rows. Empty `values` yields an empty array without
+ * preparing a statement.
+ *
+ * Rows are NOT re-sorted across batches — within a batch SQLite honours
+ * any ORDER BY in the template, but batch boundaries break global order.
+ * Callers that need globally monotonic output (e.g. ORDER BY rowid for
+ * deterministic HNSW insertion) must sort the result themselves.
+ *
+ * This is the SQLite-variable-limit fix referenced in CLAUDE.md and the
+ * indexer-ann.js handoff: the same helper is reused at every site that
+ * needs to splat a potentially-large array into an IN clause.
+ *
+ * @template T
+ * @param {import('better-sqlite3').Database} db - Open SQLite handle
+ * @param {string} sqlTemplate - Must contain `__IN_PLACEHOLDERS__` once
+ * @param {ReadonlyArray<unknown>} values - Values to bind in chunks
+ * @returns {T[]} Concatenated rows from each batch
+ */
+export function chunkedIn(db, sqlTemplate, values) {
+  if (!db || typeof db.prepare !== 'function') {
+    throw new TypeError('chunkedIn: db must be a better-sqlite3 Database');
+  }
+  if (typeof sqlTemplate !== 'string' || !sqlTemplate.includes('__IN_PLACEHOLDERS__')) {
+    throw new TypeError("chunkedIn: sqlTemplate must contain '__IN_PLACEHOLDERS__'");
+  }
+  if (!values || values.length === 0) return [];
+
+  const out = [];
+  for (let i = 0; i < values.length; i += SAFE_IN_CLAUSE_BATCH) {
+    const batch = Array.isArray(values)
+      ? values.slice(i, i + SAFE_IN_CLAUSE_BATCH)
+      : [...values].slice(i, i + SAFE_IN_CLAUSE_BATCH);
+    const placeholders = batch.map(() => '?').join(',');
+    const sql = sqlTemplate.replace('__IN_PLACEHOLDERS__', placeholders);
+    const rows = db.prepare(sql).all(...batch);
+    for (let j = 0; j < rows.length; j++) out.push(rows[j]);
+  }
+  return out;
+}
+
+/**
+ * UPDATE/DELETE counterpart to {@link chunkedIn}. Same template rules; the
+ * helper returns the total `changes` across batches and is executed inside
+ * a single transaction so partial-batch failure rolls everything back.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} sqlTemplate - Must contain `__IN_PLACEHOLDERS__` once
+ * @param {ReadonlyArray<unknown>} values
+ * @returns {{ changes: number }} Cumulative row-change count
+ */
+export function chunkedInExec(db, sqlTemplate, values) {
+  if (!db || typeof db.prepare !== 'function' || typeof db.transaction !== 'function') {
+    throw new TypeError('chunkedInExec: db must be a better-sqlite3 Database');
+  }
+  if (typeof sqlTemplate !== 'string' || !sqlTemplate.includes('__IN_PLACEHOLDERS__')) {
+    throw new TypeError("chunkedInExec: sqlTemplate must contain '__IN_PLACEHOLDERS__'");
+  }
+  if (!values || values.length === 0) return { changes: 0 };
+
+  const runBatches = db.transaction((items) => {
+    let changes = 0;
+    for (let i = 0; i < items.length; i += SAFE_IN_CLAUSE_BATCH) {
+      const batch = items.slice(i, i + SAFE_IN_CLAUSE_BATCH);
+      const placeholders = batch.map(() => '?').join(',');
+      const sql = sqlTemplate.replace('__IN_PLACEHOLDERS__', placeholders);
+      const result = db.prepare(sql).run(...batch);
+      changes += result.changes || 0;
+    }
+    return changes;
+  });
+
+  const items = Array.isArray(values) ? values : [...values];
+  return { changes: runBatches(items) };
+}
+
 /**
  * Warm the graph database page cache with lightweight queries.
  * Opens an ephemeral connection, touches FTS5/relationship/summary pages, closes.

package/core/infrastructure/dedup-hashing.js

@@ -7,12 +7,9 @@
  * fall back to a no-op that treats every chunk as its own exemplar.
  */
 
-import { createRequire } from 'module';
-import { resolveNativeAddon } from './native-resolver.js';
+import { loadNativeAddon } from './native-resolver.js';
 import { DEDUP_CONFIG } from './config/dedup.js';
 
-const require = createRequire(import.meta.url);
-
 let _addon = null;
 let _loadAttempted = false;
 let _loadError = null;
@@ -20,15 +17,15 @@ let _loadError = null;
 function loadAddon() {
   if (_loadAttempted) return _addon;
   _loadAttempted = true;
-  const addonPath = resolveNativeAddon();
-  if (!addonPath) {
-    _loadError = new Error('dedup-hashing: native addon not resolved for this platform');
-    return null;
-  }
-  try {
-    _addon = require(addonPath);
-  } catch (e) {
-    _loadError = e;
+  // CUDA-preferred with CPU fallback (see loadNativeAddon): a CUDA addon that
+  // can't load on a no-GPU box falls back to the plain CPU addon.
+  const res = loadNativeAddon({
+    validate: (m) => typeof m.dedupFingerprintBatch === 'function' && typeof m.dedupCluster === 'function',
+  });
+  if (res) {
+    _addon = res.mod;
+  } else {
+    _loadError = new Error('dedup-hashing: native addon not available for this platform');
     _addon = null;
   }
   return _addon;

package/core/infrastructure/hardware-capability.js

@@ -12,9 +12,10 @@
  *   - `sysctl` is a cheap (~5 ms) one-shot call. The result is cached so
  *     repeated consumers (init, native-inference, uninstall) all share one
  *     detection. Hardware doesn't change at runtime.
- *   - Never throws. Unknown hardware degrades to "candle-cpu fallback" —
- *     this module is only advisory; absence of a capability is never an
- *     error.
+ *   - Never throws. Unknown / no-accelerator hardware degrades to the
+ *     "ort-cpu" preference — the optimized ORT INT8 CPU path used for both
+ *     indexing and queries. It never means "load candle on CPU". This
+ *     module is only advisory; absence of a capability is never an error.
  *   - Unknown new Apple chips (e.g. an M5 shipped after this file) are
  *     admitted as cascade-eligible via the ">= 3" rule — we prefer
  *     optimistic new-hardware behavior to silently refusing to try.
@@ -214,7 +215,10 @@ function probeAddonCudaAvailability() {
  *   cudaReason                   — human string explaining eligible/not
  *   candleGpuBackend             — "metal" | "cuda" | null
  *   inferenceBackendPreference   — "coreml-cascade" | "candle-metal"
- *                                  | "candle-cuda" | "candle-cpu"
+ *                                  | "candle-cuda" | "ort-cpu"
+ *                                  ("ort-cpu" = no usable accelerator →
+ *                                   optimized ORT INT8 CPU for indexing
+ *                                   and queries; candle is never armed)
  */
 export function detectHardwareCapability() {
   if (_cached) return _cached;
@@ -281,7 +285,7 @@ export function detectHardwareCapability() {
   // Candle GPU backend availability.
   //   darwin-arm64 → metal (bundled with the darwin-arm64 native package)
   //   linux-*-gnu + NVIDIA + cuda-enabled addon → cuda
-  //   everything else → null (falls through to candle CPU)
+  //   everything else → null (falls through to ORT INT8 CPU)
   let candleGpuBackend = null;
   if (platform === 'darwin' && arch === 'arm64') {
     candleGpuBackend = 'metal';
@@ -289,10 +293,16 @@ export function detectHardwareCapability() {
     candleGpuBackend = 'cuda';
   }
 
-  // Preference order: coreml-cascade > candle-metal > candle-cuda > candle-cpu.
+  // Preference order: coreml-cascade > candle-metal > candle-cuda > ort-cpu.
   // coreml-cascade and candle-cuda never co-exist on the same host
   // (one is darwin, the other is linux), so the ordering is orthogonal
   // in practice.
+  //
+  // The no-accelerator fallback is 'ort-cpu', NOT 'candle-cpu': a host with
+  // no usable Metal / CoreML / CUDA accelerator indexes (and queries) on the
+  // optimized ORT INT8 CPU path. candle/native FP32 on CPU is slower AND
+  // lives in a different embedding space than the ORT INT8 query encoder, so
+  // it must never be the fallback. See AGENTS.md + core/indexing/model-pool.js.
   let inferenceBackendPreference;
   if (coremlCascadeEligible) {
     inferenceBackendPreference = 'coreml-cascade';
@@ -301,7 +311,7 @@ export function detectHardwareCapability() {
   } else if (candleGpuBackend === 'cuda') {
     inferenceBackendPreference = 'candle-cuda';
   } else {
-    inferenceBackendPreference = 'candle-cpu';
+    inferenceBackendPreference = 'ort-cpu';
   }
 
   _cached = Object.freeze({

package/core/infrastructure/index.js

@@ -8,7 +8,13 @@ export * from './config/index.js';
 export { default as config } from './config/index.js';
 
 // Database utilities
-export { applyReadPragmas } from './db-utils.js';
+export {
+  applyReadPragmas,
+  SAFE_IN_CLAUSE_BATCH,
+  assertInClauseSize,
+  chunkedIn,
+  chunkedInExec,
+} from './db-utils.js';
 
 // Repositories (DDD infrastructure layer)
 export { CodebaseRepository } from './codebase-repository.js';
@@ -16,7 +22,7 @@ export { CodeGraphRepository } from './code-graph-repository.js';
 
 // Model management
 export { fetchModel, fetchModelFile, resolveModelFile, computeFileHash, getModelCacheDir, isCacheValid } from './model-fetcher.js';
-export { MODEL_REGISTRY, getModelEntry, getModelsForProfile, getSkippedOptInModels, isModelEnabled } from './model-registry.js';
+export { MODEL_REGISTRY, getModelEntry, getModelsForProfile, getSkippedOptInModels, isModelEnabled, isNativeAcceleratedModel } from './model-registry.js';
 
 // Native platform resolution
 export { resolveNativeAddon, resolveNativeBinary, getPlatformInfo } from './native-resolver.js';
@@ -82,6 +88,8 @@ export {
   loadInitConfig,
   writeInitConfig,
   readPersistedLiPolicy,
+  resolveRuntimeLiModel,
+  applyPersistedLiModel,
 } from './init-config.js';
 
 // Language analysis