sweet-search 2.5.13 → 2.6.0

package/core/embedding/model-server.mjs

@@ -0,0 +1,217 @@
+/**
+ * G8 — Shared model server: the resident-model SERVER process.
+ *
+ * Loads the ONNX embedding model ONCE and serves embedding requests for many
+ * per-repo daemons over a Unix domain socket, saving N−1 model copies
+ * (~10 GB across 8 repos), keeping per-repo crash isolation, and making
+ * per-repo state cheap to evict.
+ *
+ * It also cleanly resolves G3's process-global ORT-config contamination: this
+ * process can opt into the background ORT profile (force_spinning_stop +
+ * arena-off + clamped intra-op threads) WITHOUT affecting any query-serving
+ * process, because the model lives here and nowhere else. Opt in with
+ * `SWEET_SEARCH_MODEL_SERVER_BACKGROUND=1` (or pass `{ background: true }` to
+ * `startModelServer`); off by default.
+ *
+ * Wire protocol + codec live in `model-client.mjs` (single source of truth);
+ * this module imports them so framing/serialization can never drift between
+ * the two sides. Embeddings travel as RAW Float32 little-endian bytes →
+ * byte-identical to the in-process path (same model, same preprocessing).
+ *
+ * Gate: only started when `SWEET_SEARCH_SHARED_MODEL_SERVER==='1'`
+ * (the launcher checks this); the in-process embedding path is the default and
+ * is completely untouched when the flag is off.
+ */
+
+import net from 'node:net';
+import fs from 'node:fs';
+
+import {
+  encodeFrame,
+  FrameDecoder,
+  packEmbeddings,
+  modelServerSocketPath,
+  PROTOCOL_VERSION,
+} from './model-client.mjs';
+
+import {
+  callLocalModelBucketed,
+  configureLocalModelRuntime,
+} from './embedding-local-model.js';
+
+/**
+ * Compute the embeddings for one request. Routes through the SAME bucketed
+ * local-model path the in-process embedding service uses for the `local`
+ * provider, so the output Float32 vectors are byte-identical to in-process.
+ *
+ * Exported so the parity test can exercise the exact server-side code path
+ * headlessly (no socket).
+ */
+export async function computeEmbeddingsForRequest(texts, providerOptions = {}) {
+  if (!Array.isArray(texts) || texts.length === 0) return [];
+  const bucketOptions = {
+    maxLength: providerOptions.maxLength,
+    hardCap: providerOptions.hardCap,
+    resolveHardCap: providerOptions.resolveHardCap,
+    batchingSafety: providerOptions.batchingSafety,
+    // onProgress is a function → not serializable over the wire; never set.
+  };
+  return callLocalModelBucketed(texts, bucketOptions);
+}
+
+/**
+ * Handle one decoded request frame for a connected client. Writes exactly one
+ * reply frame back. Pure wire glue around `computeEmbeddingsForRequest`.
+ */
+async function handleRequestFrame(socket, header) {
+  if (!header || typeof header !== 'object') return;
+
+  if (header.type === 'ping') {
+    socket.write(encodeFrame({ type: 'pong', v: PROTOCOL_VERSION }));
+    return;
+  }
+
+  if (header.type === 'getEmbeddings') {
+    const requestId = header.requestId;
+    try {
+      const embeddings = await computeEmbeddingsForRequest(
+        header.texts || [],
+        header.providerOptions || {},
+      );
+      const { payload, dims } = packEmbeddings(embeddings);
+      socket.write(encodeFrame({ type: 'embeddings', requestId, dims, v: PROTOCOL_VERSION }, payload));
+    } catch (err) {
+      socket.write(encodeFrame({
+        type: 'error',
+        requestId,
+        message: err?.message || String(err),
+        v: PROTOCOL_VERSION,
+      }));
+    }
+    return;
+  }
+
+  // Unknown request type — reply with a structured error (client falls back).
+  socket.write(encodeFrame({
+    type: 'error',
+    requestId: header.requestId,
+    message: `unknown request type: ${header.type}`,
+    v: PROTOCOL_VERSION,
+  }));
+}
+
+/**
+ * Wire a connected socket to the request handler. Concurrent clients are
+ * supported: each connection gets its own decoder and requests are processed
+ * as their frames complete. Robust to fragmentation and to client disconnects.
+ */
+export function attachConnection(socket) {
+  socket.on('error', () => { /* client vanished — ignore, keep server up */ });
+  const decoder = new FrameDecoder((header, _payload, err) => {
+    if (err) {
+      try { socket.destroy(); } catch { /* ignore */ }
+      return;
+    }
+    // Fire-and-forget per frame; the handler writes its own reply. We never
+    // let one client's failure take down the server.
+    handleRequestFrame(socket, header).catch(() => {
+      try {
+        socket.write(encodeFrame({
+          type: 'error',
+          requestId: header?.requestId,
+          message: 'internal model-server error',
+          v: PROTOCOL_VERSION,
+        }));
+      } catch { /* socket gone */ }
+    });
+  });
+  socket.on('data', (chunk) => decoder.push(chunk));
+}
+
+/**
+ * Start the shared model server. Binds the Unix socket, applies the background
+ * ORT profile (if requested) BEFORE the first encode (the local model is a
+ * singleton built on first encode — configuring after would be a silent
+ * no-op), and serves until `close()` is called.
+ *
+ * @param {object}  [opts]
+ * @param {string}  [opts.socketPath]  override the socket path.
+ * @param {boolean} [opts.background]  opt into the bg ORT profile for THIS
+ *                                     process only (default from env gate).
+ * @returns {Promise<{ socketPath, server, close }>}
+ */
+export async function startModelServer(opts = {}) {
+  const socketPath = opts.socketPath || modelServerSocketPath();
+  const background = opts.background
+    ?? (process.env.SWEET_SEARCH_MODEL_SERVER_BACKGROUND === '1');
+
+  // Configure the resident model's runtime profile up front. This process owns
+  // the only model copy, so bg-profiling here cannot throttle any query server.
+  if (background) {
+    try {
+      configureLocalModelRuntime({ background: true });
+    } catch (err) {
+      // Best-effort: never let profile config abort server startup.
+      if (process.env.DEBUG_CATCHES) {
+        process.stderr.write(`[model-server] bg profile config failed: ${err?.message || err}\n`);
+      }
+    }
+  }
+
+  // Remove any stale socket left by a crashed predecessor.
+  try { fs.unlinkSync(socketPath); } catch { /* none / not ours — listen() will error if truly busy */ }
+
+  const server = net.createServer((socket) => attachConnection(socket));
+
+  await new Promise((resolve, reject) => {
+    const onErr = (err) => { server.off('listening', onOk); reject(err); };
+    const onOk = () => { server.off('error', onErr); resolve(); };
+    server.once('error', onErr);
+    server.once('listening', onOk);
+    // Restrict permissions on the socket file (owner-only).
+    const prevUmask = process.umask(0o077);
+    try {
+      server.listen(socketPath);
+    } finally {
+      process.umask(prevUmask);
+    }
+  });
+
+  // Belt-and-suspenders: chmod explicitly in case umask was ineffective.
+  try { fs.chmodSync(socketPath, 0o700); } catch { /* best-effort */ }
+
+  const close = () => new Promise((resolve) => {
+    try {
+      server.close(() => {
+        try { fs.unlinkSync(socketPath); } catch { /* already gone */ }
+        resolve();
+      });
+    } catch {
+      resolve();
+    }
+  });
+
+  return { socketPath, server, close };
+}
+
+// ── CLI entrypoint ────────────────────────────────────────────────────────
+// Allow `node core/embedding/model-server.mjs` to run a standalone server.
+// Guarded so importing this module (tests, launcher) never auto-binds.
+const _isMain = (() => {
+  try {
+    return import.meta.url === `file://${process.argv[1]}`;
+  } catch {
+    return false;
+  }
+})();
+
+if (_isMain) {
+  startModelServer()
+    .then(({ socketPath }) => {
+      process.stdout.write(`[model-server] listening on ${socketPath}\n`);
+    })
+    .catch((err) => {
+      process.stderr.write(`[model-server] failed to start: ${err?.message || err}\n`);
+      process.exit(1);
+    });
+}

package/core/incremental-indexing/application/maintenance-handlers.mjs

@@ -16,12 +16,12 @@
  * Manifest semantics:
  *   - sparse_gram, LI segment: the reconcile manifest is unchanged. New
  *     artifacts replace old ones at canonical paths read fresh per query.
- *   - HNSW (float / binary): canonical paths unchanged; the reconcile
- *     manifest stays at the current epoch. Cross-process readers that
- *     cache an HNSWIndex instance in memory MUST already invalidate on
- *     manifest change — but maintenance does not bump the epoch by
- *     itself. This matches the existing reconcile tick semantics; a
- *     follow-up workstream can add versioned tier paths if needed.
+ *   - Binary HNSW: canonical paths unchanged; the reconcile manifest
+ *     stays at the current epoch. Cross-process readers that cache a
+ *     binary HNSW index in memory MUST already invalidate on manifest
+ *     change — but maintenance does not bump the epoch by itself. This
+ *     matches the existing reconcile tick semantics; a follow-up
+ *     workstream can add versioned tier paths if needed.
  *
  * The handlers degrade safely when artifacts are missing/corrupt — they
  * throw a descriptive error which the worker converts into the standard
@@ -33,7 +33,6 @@ import path from 'node:path';
 import Database from 'better-sqlite3';
 
 import { BinaryHNSWIndex } from '../../vector-store/binary-hnsw-index.js';
-import { HNSWIndex } from '../../vector-store/hnsw-index.js';
 import { LateInteractionIndex } from '../../ranking/late-interaction-index.js';
 import { compactDeltaSegments, listDeltaSegments } from '../infrastructure/sparse-gram-delta.mjs';
 import { mergeLiSegments, LI_MERGE_GRACE_MS } from '../infrastructure/li-segment-merge.mjs';
@@ -160,9 +159,8 @@ export async function binaryHnswHandler(job, { stateDir, onProgress = null }) {
   await existing.load(indexPath);
   progress('maintenance:binary-hnsw:loaded');
 
-  // Liveness authority is codebase.db, NOT the binary stale bitmap. This makes
-  // binary reclamation self-healing and consistent with floatHnswHandler
-  // (which already rebuilds from `vectors WHERE epoch_retired IS NULL`): a
+  // Liveness authority is codebase.db (`vectors WHERE epoch_retired IS NULL`),
+  // NOT the binary stale bitmap. This makes binary reclamation self-healing: a
   // vector retired in codebase.db is dropped here even if its binary stale bit
   // was never set. Falls back to the stale bitmap only when codebase.db is
   // unavailable.
@@ -195,8 +193,18 @@ export async function binaryHnswHandler(job, { stateDir, onProgress = null }) {
     maxElements: existing.maxElements,
   });
   fresh.resetForBuild();
+  // When deterministic levels are enabled, the compacted graph must be
+  // reproducible: insert surviving ids in a FIXED sorted order so the
+  // rebuild is independent of the scan/encounter order above. Combined with
+  // levelForId() (gated by the same flag inside `add()`), this makes the
+  // compaction path agree byte-for-byte with batched/per-file builds.
+  // DEFAULT-ON (disable with SWEET_SEARCH_HNSW_DETERMINISTIC_LEVELS=0) →
+  // set the flag to '0' to preserve today's encounter-order insertion exactly.
+  const insertOrder = process.env.SWEET_SEARCH_HNSW_DETERMINISTIC_LEVELS !== '0'
+    ? [...live].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    : live;
   let added = 0;
-  for (const v of live) {
+  for (const v of insertOrder) {
     await fresh.add(v.id, v.binary, v.metadata, v.int8);
     added += 1;
     if (added % 500 === 0) progress('maintenance:binary-hnsw:add');
@@ -214,92 +222,6 @@ export async function binaryHnswHandler(job, { stateDir, onProgress = null }) {
   };
 }
 
-/* ------------------------------------------------------------------ *
- * float_hnsw                                                          *
- * ------------------------------------------------------------------ */
-
-/**
- * Float HNSW clean replacement.
- *
- * Source of truth for "which vectors are live" is `codebase.db`. The
- * existing HNSW meta.json's idMap is also pruned, but we re-read the DB
- * to pick up `embedding` blobs the in-memory HNSWIndex doesn't expose.
- *
- * Caller invariant: the codebase.db schema columns (`id`, `embedding`,
- * `metadata`, `epoch_retired`) are stable — verified in the production
- * reconciler `applyVectorDelta` path.
- */
-export async function floatHnswHandler(job, { stateDir, onProgress = null }) {
-  const progress = progressFn(onProgress);
-  const indexPath = path.join(stateDir, 'codebase-hnsw.idx');
-  const metaPath = path.join(stateDir, 'codebase-hnsw.meta.json');
-  const dbPath = path.join(stateDir, 'codebase.db');
-  if (!fs.existsSync(metaPath)) return { skipped: 'no-index' };
-  if (!fs.existsSync(dbPath)) return { skipped: 'no-vector-db' };
-
-  // Load existing index to discover dimension / parameters (cheap).
-  const existing = new HNSWIndex({ indexPath });
-  try { await existing.load(indexPath); } catch { return { skipped: 'load-failed' }; }
-  progress('maintenance:float-hnsw:loaded');
-  const dimension = existing.dimension;
-  const stalePath = existing.stalePath;
-
-  const stalePresent = fs.existsSync(stalePath);
-  const liveIdsBefore = new Set(existing.idMap.keys());
-
-  // Walk live vectors from codebase.db.
-  const db = new Database(dbPath, { readonly: true });
-  let liveRows;
-  try {
-    liveRows = db.prepare(
-      'SELECT id, embedding, metadata FROM vectors WHERE epoch_retired IS NULL'
-    ).all();
-  } finally {
-    db.close();
-  }
-
-  // If everything aligns AND no stale bitmap → nothing to do.
-  if (!stalePresent && liveIdsBefore.size === liveRows.length) {
-    return { skipped: 'no-stale-vectors', dropped: 0 };
-  }
-
-  // Rebuild the index in memory and let `HNSWIndex.save()` publish via
-  // its tmp+rename protocol — that protocol keeps any cross-process
-  // `usearch.view()` mmap valid against the unlinked old inode.
-  const fresh = new HNSWIndex({
-    indexPath,
-    stalePath,
-    dimension,
-    maxElements: existing.maxElements,
-    M: existing.M,
-    efConstruction: existing.efConstruction,
-    efSearch: existing.efSearch,
-    metric: existing.metric,
-  });
-  await fresh.init();
-  for (let i = 0; i < liveRows.length; i += 1) {
-    const row = liveRows[i];
-    const embedding = float32FromBuffer(row.embedding);
-    let meta;
-    try { meta = JSON.parse(row.metadata || '{}'); } catch { meta = {}; }
-    const truncated = embedding.length > dimension ? embedding.slice(0, dimension) : embedding;
-    await fresh.add(row.id, truncated, meta);
-    if (i > 0 && i % 500 === 0) progress('maintenance:float-hnsw:add');
-  }
-  await fresh.save(indexPath);
-  progress('maintenance:float-hnsw:saved');
-  // Stale bitmap is meaningless after rebuild — keys are fresh.
-  safeUnlink(stalePath);
-
-  return {
-    tier: 'float_hnsw',
-    kept: liveRows.length,
-    dropped: Math.max(0, liveIdsBefore.size - liveRows.length),
-    staleBitmapCleared: true,
-    atomicPublish: true,
-  };
-}
-
 /* ------------------------------------------------------------------ *
  * li_segment                                                          *
  * ------------------------------------------------------------------ */
@@ -510,7 +432,6 @@ export function reclamationHandlers(stateDir) {
   return {
     sparse_gram: (job, ctx = {}) => sparseGramHandler(job, { stateDir, onProgress: ctx.onProgress }),
     binary_hnsw: (job, ctx = {}) => binaryHnswHandler(job, { stateDir, onProgress: ctx.onProgress }),
-    float_hnsw: (job, ctx = {}) => floatHnswHandler(job, { stateDir, onProgress: ctx.onProgress }),
     li_segment: (job, ctx = {}) => liSegmentHandler(job, { stateDir, onProgress: ctx.onProgress }),
     li_segments: (job, ctx = {}) => liSegmentsHandler(job, { stateDir, onProgress: ctx.onProgress }),
     vector_gc: (job, ctx = {}) => vectorGcHandler(job, { stateDir, onProgress: ctx.onProgress }),

package/core/incremental-indexing/application/maintenance-worker.mjs

@@ -34,9 +34,20 @@ import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import Database from 'better-sqlite3';
-import { fts5Merge } from '../infrastructure/sqlite-fts5.mjs';
+import { fts5Merge, fts5Optimize, fts5SegmentCount, fts5WatermarkBudgetPages } from '../infrastructure/sqlite-fts5.mjs';
 import { reclamationHandlers } from './maintenance-handlers.mjs';
 
+// SWEET_SEARCH_RECONCILE_FTS5_BUDGET is DEFAULT-ON (disable with =0): the
+// budget-derived merge scales page count down as the drain budget runs out so a
+// near-exhausted window makes a small step instead of one big overrun. Verified
+// recall-neutral + soak == baseline. Set to '0' for the legacy fixed 500-page
+// merge. SWEET_SEARCH_RECONCILE_FTS5_OPTIMIZE stays DEFAULT-OFF (heavy idle
+// compaction — strict opt-in).
+const fts5BudgetEnabled = () => process.env.SWEET_SEARCH_RECONCILE_FTS5_BUDGET !== '0';
+const fts5OptimizeEnabled = () => process.env.SWEET_SEARCH_RECONCILE_FTS5_OPTIMIZE === '1';
+// Minimum segment count below which an optimize is not worth its full rewrite.
+const FTS5_OPTIMIZE_MIN_SEGMENTS = Number.parseInt(process.env.SWEET_SEARCH_RECONCILE_FTS5_OPTIMIZE_MIN_SEGMENTS || '8', 10);
+
 const FORBIDDEN_GPU_FLAGS = [
   'SWEET_SEARCH_GPU',          // sweet-search canonical knob
   'INDEX_GPU_BACKEND',         // pre-existing flag in core/indexing
@@ -89,7 +100,7 @@ export function installGpuLoadGuard() {
  * JSON job descriptor:
  *
  *   {
- *     "tier":   "float_hnsw" | "binary_hnsw" | "li_segment" | "sparse_gram" | "fts5",
+ *     "tier":   "binary_hnsw" | "li_segment" | "sparse_gram" | "fts5",
  *     "reason": "tombstone_watermark" | "dead_doc_ratio" | "stale_doc_ratio" | "delta_size_ratio" | "fts5_segment_count" | "crash_recovery",
  *     "epoch":  <int>,
  *     "createdAt": <ISO-8601>,
@@ -226,29 +237,52 @@ export function appendDeadLetter(stateDir, job, err) {
 export function defaultMaintenanceHandlers(stateDir) {
   return {
     ...reclamationHandlers(stateDir),
-    fts5: async (job) => {
+    fts5: async (job, ctx = {}) => {
       const payload = job?.payload || {};
       const dbPath = payload.dbPath || payload.databasePath || path.join(stateDir, payload.dbFile || 'code-graph.db');
       const tableNames = payload.tableName || payload.table
         ? [payload.tableName || payload.table]
         : ['entities_fts', 'entities_trigram'];
-      const pages = Number.isFinite(payload.pages) && payload.pages > 0 ? payload.pages : 500;
+      // E.5: derive the merge page count from the budget remaining in the drain
+      // window. Off (default) → the original aggressive 500-page merge. On →
+      // scale pages down (floor 16) as the budget runs out so a near-exhausted
+      // drain still makes a small step rather than overrunning on one big merge.
+      // An explicit `payload.pages` always wins (operator override).
+      const explicitPages = Number.isFinite(payload.pages) && payload.pages > 0 ? payload.pages : null;
+      const pages = explicitPages != null
+        ? explicitPages
+        : (fts5BudgetEnabled()
+            ? fts5WatermarkBudgetPages({ remainingMs: ctx.remainingBudgetMs })
+            : 500);
+      // E.5 idle-gated optimize: when the daemon enqueues an fts5 job with
+      // `payload.optimize:true` (signaling true-idle / consecutive empty ticks)
+      // AND the optimize flag is on, run the full `('optimize')` rewrite + an
+      // immediate wal_checkpoint(TRUNCATE) — but ONLY on tables above a size
+      // threshold (a tiny table doesn't need it). Off by default; the merge path
+      // is the steady-state behavior.
+      const wantOptimize = fts5OptimizeEnabled() && payload.optimize === true;
       if (!fs.existsSync(dbPath)) throw new Error(`fts5 maintenance database not found: ${dbPath}`);
       const db = new Database(dbPath);
       try {
         const merged = [];
+        const optimized = [];
         for (const tableName of tableNames) {
           const exists = db.prepare(
             "SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?",
           ).get(tableName);
           if (!exists) continue;
-          fts5Merge(db, tableName, pages);
-          merged.push(tableName);
+          if (wantOptimize && fts5SegmentCount(db, tableName) >= FTS5_OPTIMIZE_MIN_SEGMENTS) {
+            fts5Optimize(db, tableName);
+            optimized.push(tableName);
+          } else {
+            fts5Merge(db, tableName, pages);
+            merged.push(tableName);
+          }
         }
-        if (merged.length === 0) {
+        if (merged.length === 0 && optimized.length === 0) {
           throw new Error(`fts5 maintenance found no FTS5 tables in ${dbPath}`);
         }
-        return { dbPath, tableNames: merged, pages };
+        return { dbPath, tableNames: [...merged, ...optimized], pages, optimized };
       } finally {
         db.close();
       }
@@ -317,7 +351,10 @@ export async function processMaintenanceQueue(stateDir, options = {}) {
     attempted += 1;
     try {
       onProgress(`maintenance:${job.tier || 'unknown'}:start`);
-      await handler(job, { stateDir, onProgress });
+      // E.5: surface the wall-clock budget remaining so budget-aware handlers
+      // (fts5 merge) can scale their work to the spare window.
+      const remainingBudgetMs = budgetMs === Infinity ? Infinity : Math.max(0, budgetMs - (clock() - startMs));
+      await handler(job, { stateDir, onProgress, remainingBudgetMs });
       onProgress(`maintenance:${job.tier || 'unknown'}:done`);
       summary.succeeded += 1;
     } catch (err) {

package/core/incremental-indexing/application/operator-cli.mjs

@@ -27,9 +27,7 @@ const MERKLE_STATE = 'merkle-state.json';
 const PAUSE_FILE = 'reconcile-pause.json';
 
 const REBUILD_TIERS = new Map([
-  ['hnsw', 'float_hnsw'],
-  ['float_hnsw', 'float_hnsw'],
-  ['float-hnsw', 'float_hnsw'],
+  ['hnsw', 'binary_hnsw'],
   ['binary_hnsw', 'binary_hnsw'],
   ['binary-hnsw', 'binary_hnsw'],
   ['li', 'li_segment'],
@@ -399,12 +397,23 @@ function addDirtyHint(ctx, inputPath) {
 
 async function preserveJsonStdout(json, fn) {
   if (!json) return fn();
-  const originalLog = console.log;
+  // Route EVERY stdout-bound console level (log/info/debug) to stderr while the
+  // command runs, so stray diagnostics never corrupt the --json payload on
+  // stdout. console.log alone is not enough: the autotune emits its
+  // "[reconciler] interval …ms → …ms" line via the default `console` logger's
+  // `.info` (now that autotune is default-on), which writes to stdout and would
+  // otherwise prepend a non-JSON line to `reconcile tick --json`. warn/error
+  // already go to stderr, so they're left alone.
+  const original = { log: console.log, info: console.info, debug: console.debug };
   console.log = (...args) => console.error(...args);
+  console.info = (...args) => console.error(...args);
+  console.debug = (...args) => console.error(...args);
   try {
     return await fn();
   } finally {
-    console.log = originalLog;
+    console.log = original.log;
+    console.info = original.info;
+    console.debug = original.debug;
   }
 }
 

package/core/incremental-indexing/application/production-reconciler-helpers.mjs

@@ -105,3 +105,43 @@ export async function maintainFloatStore(binaryHnswPath, { upserts, removeIds, b
   store.applyDelta({ upserts, removeIds });
   await store.save(floatStorePath);
 }
+
+/**
+ * Tick-finalize variant of `maintainFloatStore` for the batched path (lever
+ * E.1). Instead of loading + saving the float store once per file, the
+ * reconciler loads the store once at tick start, accumulates all of the tick's
+ * float upserts/removes, and calls this once at tick finalize to apply them and
+ * save.
+ *
+ * `binaryVectorsBefore` is the live binary-HNSW vector count captured at TICK
+ * START (before any of this tick's appends), preserving the same
+ * "abnormal-state skip" semantics as the per-file path: if the float store is
+ * absent but the binary HNSW already held vectors, a store built from the delta
+ * alone would mis-score every baseline doc, so we skip until a full rebuild
+ * restores it.
+ *
+ * Returns `{ saved: boolean }` — `saved=false` means the delta was empty or the
+ * store was skipped (no fsync happened), which the persist-before-advance gate
+ * treats as "no float artifact changed this tick".
+ *
+ * @param {object} args
+ * @param {string} args.binaryHnswPath
+ * @param {FloatVectorStore} [args.store]        resident store (loaded once at tick start)
+ * @param {Array<{id:string, vector:Float32Array}>} args.upserts
+ * @param {string[]} args.removeIds
+ * @param {number} args.binaryVectorsBefore
+ * @param {number} args.dimension
+ * @returns {Promise<{saved: boolean}>}
+ */
+export async function flushFloatStore({ binaryHnswPath, store = null, upserts = [], removeIds = [], binaryVectorsBefore = 0, dimension }) {
+  if (upserts.length === 0 && removeIds.length === 0) return { saved: false };
+  const floatStorePath = getFloatStorePath(binaryHnswPath);
+  if (!existsSync(floatStorePath) && binaryVectorsBefore > 0 && !(store && store.loaded && store.count > 0)) {
+    return { saved: false };
+  }
+  const fvs = store || new FloatVectorStore();
+  if (!fvs.loaded) await fvs.loadOrInit(floatStorePath, dimension);
+  fvs.applyDelta({ upserts, removeIds });
+  await fvs.save(floatStorePath);
+  return { saved: true };
+}