akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/storage/repositories/index-utility-repository.js

@@ -0,0 +1,356 @@
+// 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/.
+/**
+ * `index.db` utility-score + retrieval-count repository (MemRL signals).
+ *
+ * Owns the raw SQL for `utility_scores` / `utility_scores_scoped` and the
+ * retrieval-frequency counting over `usage_events`. The bounded-step EMA policy
+ * itself lives in `indexer/feedback/utility-policy`; this repo only reads/writes.
+ */
+import path from "node:path";
+import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
+import { computeNextUtility } from "../../indexer/feedback/utility-policy.js";
+import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
+/**
+ * Get the utility score for an entry, or undefined if none exists.
+ */
+export function getUtilityScore(db, entryId) {
+    const row = db
+        .prepare("SELECT entry_id, utility, show_count, search_count, select_rate, last_used_at, updated_at FROM utility_scores WHERE entry_id = ?")
+        .get(entryId);
+    if (!row)
+        return undefined;
+    return {
+        entryId: row.entry_id,
+        utility: row.utility,
+        showCount: row.show_count,
+        searchCount: row.search_count,
+        selectRate: row.select_rate,
+        lastUsedAt: row.last_used_at ?? undefined,
+        updatedAt: row.updated_at,
+    };
+}
+/**
+ * Batch-load utility scores for multiple entry IDs in a single query.
+ * Returns a `{ global, scoped }` pair, both Maps keyed by entry_id.
+ *
+ * When `scopeKey` is provided a second query runs against
+ * `utility_scores_scoped` and the result is returned as `scoped`.
+ * Both maps are always present; `scoped` is empty when `scopeKey` is absent.
+ */
+export function getUtilityScoresByIds(db, ids, scopeKey) {
+    const global = new Map();
+    const scoped = new Map();
+    if (ids.length === 0)
+        return { global, scoped };
+    // Process in chunks to stay within SQLITE_MAX_VARIABLE_NUMBER
+    for (let i = 0; i < ids.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = ids.slice(i, i + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT entry_id, utility, show_count, search_count, select_rate, last_used_at, updated_at FROM utility_scores WHERE entry_id IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows) {
+            global.set(row.entry_id, {
+                entryId: row.entry_id,
+                utility: row.utility,
+                showCount: row.show_count,
+                searchCount: row.search_count,
+                selectRate: row.select_rate,
+                lastUsedAt: row.last_used_at ?? undefined,
+                updatedAt: row.updated_at,
+            });
+        }
+        if (scopeKey) {
+            const scopedRows = db
+                .prepare(`SELECT entry_id, scope_key, utility, last_used_at FROM utility_scores_scoped WHERE scope_key = ? AND entry_id IN (${placeholders})`)
+                .all(scopeKey, ...chunk);
+            for (const row of scopedRows) {
+                scoped.set(row.entry_id, {
+                    entryId: row.entry_id,
+                    scopeKey: row.scope_key,
+                    utility: row.utility,
+                    lastUsedAt: row.last_used_at,
+                });
+            }
+        }
+    }
+    return { global, scoped };
+}
+/**
+ * Insert or update a utility score for an entry.
+ */
+export function upsertUtilityScore(db, entryId, data) {
+    // Pre-flight FK guard (mirrors `upsertEmbedding`): when an entry is
+    // deleted between when its id is aggregated from usage_events and when
+    // this INSERT runs, the FK constraint fails and rolls back the entire
+    // finalize transaction. A cheap SELECT here turns the race into a
+    // clean skip. Returns false when the entry no longer exists.
+    const exists = db.prepare("SELECT 1 FROM entries WHERE id = ?").get(entryId);
+    if (!exists)
+        return false;
+    db.prepare(`
+    INSERT INTO utility_scores (entry_id, utility, show_count, search_count, select_rate, last_used_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, datetime('now'))
+    ON CONFLICT(entry_id) DO UPDATE SET
+      utility = excluded.utility,
+      show_count = excluded.show_count,
+      search_count = excluded.search_count,
+      select_rate = excluded.select_rate,
+      last_used_at = excluded.last_used_at,
+      updated_at = datetime('now')
+  `).run(entryId, data.utility, data.showCount, data.searchCount, data.selectRate, data.lastUsedAt ?? null);
+    return true;
+}
+/**
+ * Reduce a stored ref to its bare form, dropping any `origin//` / `bundle//`
+ * prefix, matching the counting SQL's `substr` after the first `//`.
+ */
+function bareRef(ref) {
+    const boundary = ref.indexOf("//");
+    return boundary >= 0 ? ref.slice(boundary + 2) : ref;
+}
+/**
+ * The bare-form (conceptId) candidate a caller ref matches a stored
+ * `usage_events` row under. Post-Chunk-8 every stored row is conceptId-spelled
+ * (the one-time §11.4 re-key ran at the migration cutover), so only the conceptId
+ * candidate remains — the legacy `type:name` sibling is retired.
+ */
+function bareRefCandidates(ref) {
+    const bare = bareRef(ref.trim());
+    const parsed = parseRefInput(bare);
+    return [conceptIdFromTypeName(parsed.type, parsed.name)];
+}
+/**
+ * Count retrieval events for the given entry refs.
+ *
+ * Counts `search`, `show`, and `curate` usage events. Returns a
+ * Map<inputRef, count> keyed by the *input* ref strings (only those with at
+ * least one matching event appear). Used by the improve loop's
+ * proactive-maintenance selector to rank zero-feedback assets by retrieval
+ * frequency.
+ *
+ * Source-scoped callers require either an event linked to an entry in the
+ * selected stash root or a detached ref qualified with the selected source
+ * name.
+ *
+ * `curate` events are included: their per-item rows are written with
+ * entry_ref populated (see logCurateEvent), so curation is a real retrieval
+ * signal here. Summary-only rows with a NULL entry_ref contribute nothing.
+ *
+ * Machine/eval/unattributed/extension events are excluded: this count feeds
+ * salience and ranking, so only explicitly attributed `user` traffic counts.
+ */
+export function getRetrievalCounts(indexDb, stateDb, refs, options = {}) {
+    if (refs.length === 0)
+        return new Map();
+    if (options.sourceName || options.stashDir) {
+        return getSourceScopedRetrievalCounts(indexDb, stateDb, refs, options);
+    }
+    // Map each conceptId back to the input refs that produced it so DB results
+    // can be re-keyed onto the caller's strings.
+    const bareToInputs = new Map();
+    for (const ref of refs) {
+        for (const bare of bareRefCandidates(ref)) {
+            const existing = bareToInputs.get(bare);
+            if (existing)
+                existing.push(ref);
+            else
+                bareToInputs.set(bare, [ref]);
+        }
+    }
+    const bareForms = [...bareToInputs.keys()];
+    // Accumulate counts per bare form across chunks before re-keying.
+    const countsByBare = new Map();
+    // Chunk to stay within SQLITE_MAX_VARIABLE_NUMBER (same pattern as getUtilityScoresByIds).
+    for (let i = 0; i < bareForms.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = bareForms.slice(i, i + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(", ");
+        // Normalize the stored entry_ref to its bare form inside SQL by stripping
+        // everything up to and including the last `//` separator. SQLite has no
+        // rfind, but stored origins never themselves contain `//`, so a stash ref
+        // has exactly one `//` and `substr(... instr ...)` is exact; bare refs have
+        // no `//` and are excluded above.
+        // usage_events lives in state.db (Chunk-8 WI-8.3) — this global count needs
+        // no entries join, so it reads state.db directly.
+        const rows = stateDb
+            .prepare(`SELECT
+           CASE
+             WHEN instr(entry_ref, '//') > 0
+               THEN substr(entry_ref, instr(entry_ref, '//') + 2)
+             ELSE entry_ref
+           END AS bare_ref,
+           COUNT(*) AS cnt
+         FROM usage_events
+         WHERE event_type IN ('search','show','curate')
+           AND entry_ref IS NOT NULL
+           AND instr(entry_ref, '//') > 0
+           AND source = 'user'
+           AND CASE
+                 WHEN instr(entry_ref, '//') > 0
+                   THEN substr(entry_ref, instr(entry_ref, '//') + 2)
+                 ELSE entry_ref
+               END IN (${placeholders})
+         GROUP BY bare_ref`)
+            .all(...chunk);
+        for (const r of rows) {
+            countsByBare.set(r.bare_ref, (countsByBare.get(r.bare_ref) ?? 0) + r.cnt);
+        }
+    }
+    // Re-key bare-form counts onto every input ref that maps to that bare form.
+    const result = new Map();
+    for (const [bare, count] of countsByBare) {
+        for (const input of bareToInputs.get(bare) ?? []) {
+            result.set(input, count);
+        }
+    }
+    return result;
+}
+function getSourceScopedRetrievalCounts(indexDb, stateDb, refs, options) {
+    const bareToInputs = new Map();
+    for (const ref of refs) {
+        for (const bare of bareRefCandidates(ref)) {
+            const inputs = bareToInputs.get(bare);
+            if (inputs)
+                inputs.push(ref);
+            else
+                bareToInputs.set(bare, [ref]);
+        }
+    }
+    // Cross-DB (Chunk-8 WI-8.3): usage_events rows come from state.db; the
+    // per-row `stash_dir` (formerly a LEFT JOIN on entries) is resolved from
+    // index.db by entry_id. Read the usage rows first, then batch-look-up the
+    // stash_dir for their entry_ids and join in JS.
+    const entryStashDir = indexDb.prepare("SELECT stash_dir FROM entries WHERE id = ?");
+    const stashDirFor = (entryId) => {
+        if (entryId === null)
+            return null;
+        const row = entryStashDir.get(entryId);
+        return row?.stash_dir ?? null;
+    };
+    const countsByBare = new Map();
+    const bareForms = [...bareToInputs.keys()];
+    const selectedRoot = options.stashDir ? path.resolve(options.stashDir) : undefined;
+    for (let i = 0; i < bareForms.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = bareForms.slice(i, i + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(", ");
+        const rawRows = stateDb
+            .prepare(`SELECT ue.entry_ref, ue.entry_id
+           FROM usage_events ue
+          WHERE ue.event_type IN ('search','show','curate')
+            AND ue.entry_ref IS NOT NULL
+            AND instr(ue.entry_ref, '//') > 0
+            AND ue.source = 'user'
+            AND CASE
+                  WHEN instr(ue.entry_ref, '//') > 0
+                    THEN substr(ue.entry_ref, instr(ue.entry_ref, '//') + 2)
+                  ELSE ue.entry_ref
+                END IN (${placeholders})`)
+            .all(...chunk);
+        const rows = rawRows.map((r) => ({ ...r, stash_dir: stashDirFor(r.entry_id) }));
+        for (const row of rows) {
+            const bare = bareRef(row.entry_ref);
+            const linkedToSelectedRoot = row.entry_id !== null && selectedRoot !== undefined && row.stash_dir !== null
+                ? path.resolve(row.stash_dir) === selectedRoot
+                : false;
+            const detached = row.entry_id === null || selectedRoot === undefined;
+            const qualifiedForSource = detached && options.sourceName !== undefined && row.entry_ref === `${options.sourceName}//${bare}`;
+            if (!linkedToSelectedRoot && !qualifiedForSource)
+                continue;
+            countsByBare.set(bare, (countsByBare.get(bare) ?? 0) + 1);
+        }
+    }
+    const result = new Map();
+    for (const [bare, count] of countsByBare) {
+        for (const input of bareToInputs.get(bare) ?? [])
+            result.set(input, count);
+    }
+    return result;
+}
+/**
+ * Apply a MemRL reward signal to a batch of entries via exponential moving
+ * average (EMA): next = clamp(current + lr * (reward - current), 0, 1).
+ *
+ * Wrapped in a single transaction so all bumps succeed or fail together.
+ * The indexer (`akm index`) will overwrite these values at next reindex run;
+ * bumps are intentionally temporary hints between index runs, not permanent
+ * overrides.
+ *
+ * When `scopeKey` is provided, also writes a scoped bump to
+ * `utility_scores_scoped` so per-project usage signals accumulate alongside
+ * the global ones. The global table is always updated regardless.
+ */
+export function bumpUtilityScoresBatch(db, entryIds, reward, lr = 0.1, scopeKey) {
+    if (entryIds.length === 0)
+        return;
+    db.transaction(() => {
+        const { global: scoreMap } = getUtilityScoresByIds(db, entryIds);
+        const now = new Date().toISOString();
+        const nowMs = Date.now();
+        const stmt = db.prepare(`INSERT INTO utility_scores (entry_id, utility, show_count, search_count, select_rate, last_used_at, updated_at)
+       VALUES (?, ?, 0, 0, 0, ?, ?)
+       ON CONFLICT(entry_id) DO UPDATE SET
+         utility = excluded.utility,
+         updated_at = excluded.updated_at`);
+        // Prepare scoped upsert once outside the loop when scopeKey is present.
+        const scopedStmt = scopeKey
+            ? db.prepare(`INSERT INTO utility_scores_scoped (entry_id, scope_key, utility, last_used_at)
+           VALUES (?, ?, ?, ?)
+           ON CONFLICT(entry_id, scope_key) DO UPDATE SET
+             utility = excluded.utility,
+             last_used_at = excluded.last_used_at`)
+            : null;
+        for (const entryId of entryIds) {
+            const existing = scoreMap.get(entryId);
+            const current = existing?.utility ?? 0;
+            const next = Math.max(0, Math.min(1, current + lr * (reward - current)));
+            stmt.run(entryId, next, now, now);
+            if (scopedStmt && scopeKey) {
+                // Retrieve the current scoped utility so we can apply the same EMA.
+                const scopedCurrent = getScopedUtility(db, entryId, scopeKey);
+                const scopedNext = Math.max(0, Math.min(1, scopedCurrent + lr * (reward - scopedCurrent)));
+                scopedStmt.run(entryId, scopeKey, scopedNext, nowMs);
+            }
+        }
+    })();
+}
+/**
+ * Return the current utility value for a single (entry_id, scope_key) pair.
+ * Returns 0 when no row exists yet.
+ */
+function getScopedUtility(db, entryId, scopeKey) {
+    const row = db
+        .prepare("SELECT utility FROM utility_scores_scoped WHERE entry_id = ? AND scope_key = ?")
+        .get(entryId, scopeKey);
+    return row?.utility ?? 0;
+}
+/**
+ * Apply accumulated feedback counts to the utility score of an entry, persisting
+ * the result. The bounded-step EMA policy itself (MemRL, F-5 / #386,
+ * arXiv:2601.03192) lives in {@link computeNextUtility} (feedback/utility-policy);
+ * this function only reads the current utility, applies the policy, and writes
+ * the new value.
+ *
+ * A new entry starts at 0.5 (neutral midpoint) before the EMA step is applied.
+ * When there is no feedback (both counts zero) the score is left untouched — no
+ * DB write. Returns a {@link FeedbackUtilityResult} so the caller can detect a
+ * previously high-utility asset crossing below the review threshold and escalate.
+ */
+export function applyFeedbackToUtilityScore(db, entryId, positiveCount, negativeCount) {
+    const existing = getUtilityScore(db, entryId);
+    const previousUtility = existing?.utility ?? 0.5;
+    const result = computeNextUtility(previousUtility, positiveCount, negativeCount);
+    if (positiveCount === 0 && negativeCount === 0) {
+        return result;
+    }
+    const now = new Date().toISOString();
+    db.prepare(`
+    INSERT INTO utility_scores (entry_id, utility, show_count, search_count, select_rate, last_used_at, updated_at)
+    VALUES (?, ?, 0, 0, 0, ?, ?)
+    ON CONFLICT(entry_id) DO UPDATE SET
+      utility    = ?,
+      updated_at = ?
+  `).run(entryId, result.nextUtility, now, now, result.nextUtility, now);
+    return result;
+}

package/dist/storage/repositories/index-vec-repository.js

@@ -0,0 +1,250 @@
+// 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/.
+/**
+ * `index.db` vector + embedding repository.
+ *
+ * Owns the sqlite-vec extension load/availability probe, the BLOB `embeddings`
+ * table, the `entries_vec` virtual table, and the JS-cosine fallback path.
+ */
+import { createRequire } from "node:module";
+import { bestEffort } from "../../core/best-effort.js";
+import { warn } from "../../core/warn.js";
+import { cosineSimilarity } from "../../llm/embedders/types.js";
+import { getMeta, setMeta } from "./index-meta-repository.js";
+// ── sqlite-vec extension ────────────────────────────────────────────────────
+const vecStatus = new WeakMap();
+/**
+ * Attempt to load the sqlite-vec extension into `db`, recording availability.
+ * Exported so the connection lifecycle can arm it at open time.
+ */
+export function loadVecExtension(db) {
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const sqliteVec = esmRequire("sqlite-vec");
+        // `db` here is the genuine underlying driver handle returned by the storage
+        // boundary (bun:sqlite on Bun, better-sqlite3 on Node) — only structurally
+        // narrowed for callers. sqlite-vec's `load()` accepts either real handle,
+        // so no raw-handle escape hatch is required.
+        sqliteVec.load(db);
+        vecStatus.set(db, true);
+    }
+    catch {
+        vecStatus.set(db, false);
+    }
+}
+export function isVecAvailable(db) {
+    return vecStatus.get(db) ?? false;
+}
+/**
+ * Meta key persisting whether the sqlite-vec fast-path table (`entries_vec`) is
+ * fully populated and trustworthy for this index. Set to "0" by the embedding
+ * phase when one or more vec inserts FAILED (e.g. a vec0 dimension mismatch)
+ * while their BLOB rows still wrote — so semantic search reads the complete
+ * BLOB table via the JS-cosine fallback instead of a partial/mismatched vec
+ * table. Absent (legacy indexes) and "1" both mean the fast path is trusted.
+ */
+const VEC_FAST_PATH_READY_META = "vecFastPathReady";
+/** Persist whether the sqlite-vec fast path is trustworthy (see the meta doc). */
+export function setVecFastPathReady(db, ready) {
+    setMeta(db, VEC_FAST_PATH_READY_META, ready ? "1" : "0");
+}
+/**
+ * True unless the embedding phase recorded a vec insert failure. Reflects the
+ * ACTUAL insert outcomes recorded at index time — not an inference from how many
+ * BLOB rows exist — so a degraded vec table routes search to the JS fallback
+ * rather than silently returning partial fast-path results.
+ */
+export function isVecFastPathReady(db) {
+    return getMeta(db, VEC_FAST_PATH_READY_META) !== "0";
+}
+/** Remove both vector representations for an entry whose embedding input changed. */
+export function deleteEntryVectors(db, id) {
+    db.prepare("DELETE FROM embeddings WHERE id = ?").run(id);
+    if (isVecAvailable(db))
+        db.prepare("DELETE FROM entries_vec WHERE id = ?").run(id);
+}
+const VEC_DOCS_URL = "https://github.com/itlackey/akm/blob/main/docs/reference/configuration.md#sqlite-vec-extension";
+const VEC_FALLBACK_THRESHOLD = 10_000;
+// Per-database warning state: tracks which databases have already emitted the
+// vec-missing warning so we don't spam on every openDatabase() call.
+const vecInitWarnedDbs = new WeakSet();
+/**
+ * Warn if sqlite-vec is unavailable and embedding count exceeds threshold.
+ * Called from openDatabase (once at init) and from indexer (each run).
+ */
+export function warnIfVecMissing(db, { once } = { once: false }) {
+    if (isVecAvailable(db))
+        return;
+    if (once && vecInitWarnedDbs.has(db))
+        return;
+    bestEffort(() => {
+        const row = db.prepare("SELECT COUNT(*) AS cnt FROM embeddings").get();
+        const count = row?.cnt ?? 0;
+        if (count >= VEC_FALLBACK_THRESHOLD) {
+            warn("Semantic search is using JS fallback for %d entries. Install sqlite-vec for faster performance.\n  See: %s", count, VEC_DOCS_URL);
+            if (once)
+                vecInitWarnedDbs.add(db);
+        }
+    }, "embeddings table may not exist yet during init");
+}
+/**
+ * Purge stored embeddings (BLOB rows in `embeddings`, plus the `entries_vec`
+ * virtual table) and mark the index as embedding-free. The single place that
+ * invalidates embeddings — used on a dimension change, a model/provider change,
+ * and a full rebuild.
+ *
+ * No backup: embeddings are a derived cache, fully regenerable from the markdown
+ * by the next `akm index`. (Recovery model decided 2026-06-25.)
+ *
+ * `dropVecTable: true` DROPs `entries_vec` — used on a DIMENSION change, where
+ * the vec0 table must be recreated at the new width by the caller. The default
+ * clears its rows in place (same dimension, stale vectors).
+ */
+export function purgeEmbeddings(db, opts) {
+    bestEffort(() => db.exec("DELETE FROM embeddings"), "purge embeddings");
+    if (isVecAvailable(db)) {
+        bestEffort(() => db.exec(opts?.dropVecTable ? "DROP TABLE IF EXISTS entries_vec" : "DELETE FROM entries_vec"), "purge entries_vec");
+    }
+    setMeta(db, "hasEmbeddings", "0");
+}
+export function upsertEmbedding(db, entryId, embedding) {
+    // Pre-flight FK guard: when an entry is deleted between when its id is queued
+    // for embedding and when this INSERT runs (e.g. consolidation deletes during
+    // a concurrent improve cycle), the INSERT throws "FOREIGN KEY constraint failed"
+    // and rolls back the entire batch transaction in the caller, losing every
+    // embedding for that run. A cheap SELECT here turns the race into a clean skip.
+    const exists = db.prepare("SELECT 1 FROM entries WHERE id = ?").get(entryId);
+    if (!exists)
+        return { stored: false, vec: "unavailable" };
+    const buf = float32Buffer(embedding);
+    // Always write to BLOB table (works without sqlite-vec; the JS-cosine fallback
+    // reads it, so semantic search survives a vec fast-path failure).
+    db.prepare("INSERT OR REPLACE INTO embeddings (id, embedding) VALUES (?, ?)").run(entryId, buf);
+    if (!isVecAvailable(db))
+        return { stored: true, vec: "unavailable" };
+    // Fast path: mirror into the sqlite-vec table. Wrapped in a transaction so a
+    // crash between DELETE and INSERT does not leave the entry missing. A THROW
+    // here — previously swallowed silently by bestEffort — is now surfaced to the
+    // caller so the embedding phase can count it, warn, and route search to the
+    // (complete) BLOB table rather than a partial/mismatched vec table.
+    try {
+        db.transaction(() => {
+            db.prepare("DELETE FROM entries_vec WHERE id = ?").run(entryId);
+            db.prepare("INSERT INTO entries_vec (id, embedding) VALUES (?, ?)").run(entryId, buf);
+        })();
+        return { stored: true, vec: "ok" };
+    }
+    catch {
+        return { stored: true, vec: "failed" };
+    }
+}
+export function searchVec(db, queryEmbedding, k) {
+    // Fast path: sqlite-vec, but ONLY when the extension is loaded AND the
+    // embedding phase did not record a vec insert failure. A degraded fast-path
+    // table (partial or dimension-mismatched) would return wrong or missing
+    // neighbours, so we honestly fall back to the JS-cosine scan over the
+    // complete BLOB table instead.
+    if (isVecAvailable(db) && isVecFastPathReady(db)) {
+        const buf = float32Buffer(queryEmbedding);
+        try {
+            return db
+                .prepare("SELECT id, distance FROM entries_vec WHERE embedding MATCH ? AND k = ?")
+                .all(buf, k);
+        }
+        catch (err) {
+            // Log the failure so it's visible in diagnostics
+            warn("[db] searchVec (sqlite-vec path) failed:", err instanceof Error ? err.message : String(err));
+            return [];
+        }
+    }
+    // Fallback: JS-based cosine similarity over BLOB table
+    return searchBlobVec(db, queryEmbedding, k);
+}
+/**
+ * Return the k nearest neighbours of an already-indexed entry using its
+ * persisted embedding — no re-embedding, no network. Decodes the stored BLOB by
+ * byte length (dim = bytes / 4) and reuses searchVec (sqlite-vec fast path or
+ * JS-cosine fallback). Returns [] when the entry has no stored embedding or the
+ * BLOB is corrupt. The query entry itself is typically returned with distance
+ * ~0 — callers should filter it out by id.
+ */
+export function getNeighborsByEntryId(db, id, k) {
+    const row = db.prepare("SELECT embedding FROM embeddings WHERE id = ?").get(id);
+    if (!row)
+        return [];
+    const queryEmbedding = bufferToFloat32(row.embedding, Math.floor(row.embedding.byteLength / 4));
+    if (!queryEmbedding)
+        return [];
+    return searchVec(db, queryEmbedding, k);
+}
+function float32Buffer(vec) {
+    const f32 = new Float32Array(vec);
+    return Buffer.from(f32.buffer);
+}
+/**
+ * Decode a stored embedding BLOB into a Float32 array of `expectedDim`
+ * dimensions. Returns `null` (and emits a warning) when the byte length does
+ * not exactly match `expectedDim * 4`, including the legacy partial-trailing
+ * float case the previous truncating-divide silently swallowed.
+ *
+ * BUG-M2: the previous `buf.byteLength / 4` divide would truncate any
+ * trailing partial float and a misaligned `byteOffset` would throw — both
+ * surfaced as opaque generic errors caught upstream.
+ */
+function bufferToFloat32(buf, expectedDim) {
+    if (buf.byteLength !== expectedDim * 4) {
+        warn("[db] bufferToFloat32: skipping embedding row — expected %d bytes (%d dim x 4), got %d", expectedDim * 4, expectedDim, buf.byteLength);
+        return null;
+    }
+    // Copy into a fresh ArrayBuffer to sidestep any byteOffset alignment
+    // requirements imposed by Float32Array's typed-array view contract.
+    const aligned = new ArrayBuffer(buf.byteLength);
+    new Uint8Array(aligned).set(buf);
+    const f32 = new Float32Array(aligned);
+    return Array.from(f32);
+}
+function searchBlobVec(db, queryEmbedding, k) {
+    try {
+        const rows = db.prepare("SELECT id, embedding FROM embeddings").all();
+        if (rows.length === 0)
+            return [];
+        const expectedDim = queryEmbedding.length;
+        const scored = [];
+        for (const row of rows) {
+            const embedding = bufferToFloat32(row.embedding, expectedDim);
+            if (embedding === null)
+                continue;
+            const similarity = cosineSimilarity(queryEmbedding, embedding);
+            scored.push({ id: row.id, similarity });
+        }
+        scored.sort((a, b) => b.similarity - a.similarity);
+        // Convert cosine similarity to L2 distance for compatibility with sqlite-vec interface
+        // For normalized vectors: L2² = 2(1 - cos_sim)
+        return scored.slice(0, k).map(({ id, similarity }) => ({
+            id,
+            distance: Math.sqrt(2 * Math.max(0, 1 - similarity)),
+        }));
+    }
+    catch (err) {
+        // MD-5: Log the failure so it's visible in diagnostics
+        warn("[db] searchBlobVec (JS fallback) failed:", err instanceof Error ? err.message : String(err));
+        return [];
+    }
+}
+/**
+ * Return all entries that do not yet have an embedding row.
+ * Used by the embedding phase to determine which entries need vectors generated.
+ */
+export function getAllEntriesForEmbedding(db) {
+    return db
+        .prepare(`
+      SELECT e.id, e.search_text AS searchText, e.entry_key AS entryKey, e.file_path AS filePath FROM entries e
+      WHERE NOT EXISTS (SELECT 1 FROM embeddings b WHERE b.id = e.id)
+    `)
+        .all();
+}
+export function getEmbeddingCount(db) {
+    const row = db.prepare("SELECT COUNT(*) AS cnt FROM embeddings").get();
+    return row.cnt;
+}