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

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

@@ -0,0 +1,863 @@
+// 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` entries repository — CRUD, lookup, re-key, delete-cascade, and the
+ * usage-event relink + workflow-document + tag-set reads that key on `entries`.
+ *
+ * Owns ALL raw SQL against the `entries` table. The shared row/option shapes
+ * come from the leaf types + mapper modules.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
+import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
+import { bestEffort } from "../../core/best-effort.js";
+import { getStateDbPath, withStateDb } from "../../core/state-db.js";
+import { warn } from "../../core/warn.js";
+import { buildSearchText } from "../../indexer/search/search-fields.js";
+import { ENTRY_COLUMNS, rowToIndexedEntry } from "./index-entry-mapper.js";
+import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
+import { deleteEntryVectors, isVecAvailable } from "./index-vec-repository.js";
+// ── Entry operations ────────────────────────────────────────────────────────
+/**
+ * Insert or update an entry in the `entries` table. Returns the row id.
+ *
+ * **Important:** This does not update the FTS index. Callers must call
+ * `rebuildFts()` after all upserts are complete for full-text search to
+ * reflect the changes.
+ */
+export function upsertEntry(db, entryKey, dirPath, filePath, stashDir, entry, searchText, provenance, contentHash) {
+    // Hot path during indexing — cache prepared statements per database
+    // connection so we don't pay the SQL parse/compile cost on every call.
+    const stmts = getUpsertStmts(db);
+    const previous = (provenance?.itemRef
+        ? stmts.findByItemRef.get(provenance.itemRef)
+        : undefined) ?? stmts.findByEntryKey.get(entryKey);
+    // Phase 5A / Advantage D5: surface derived memory parent ref into the
+    // dedicated `derived_from` column so retrieval-time lookup (parent→child)
+    // does not have to scan + JSON-decode every memory row.
+    const derivedFrom = typeof entry.derivedFrom === "string" && entry.derivedFrom.trim() ? entry.derivedFrom.trim() : null;
+    // Chunk-5 Step 2 (spec §14.4): populate the additive identity/provenance
+    // columns alongside the legacy ones. `type` mirrors `entry_type` (the open
+    // token) unconditionally; `item_ref`/bundle/component/concept/adapter come
+    // from the write-boundary derivation when available (NULL otherwise, healed
+    // by the next full index). `content_hash` (F4a M-core-2) is `doc.hash` from
+    // the diff-persist writer; a NULL passed here PRESERVES any existing hash (the
+    // ON CONFLICT COALESCE below) so the LLM-enrichment re-upsert cannot wipe it.
+    const apply = () => {
+        const result = stmts.upsert.get(entryKey, dirPath, filePath, stashDir, JSON.stringify(entry), searchText, entry.type, derivedFrom, provenance?.itemRef ?? null, provenance?.bundleId ?? null, provenance?.componentId ?? null, provenance?.conceptId ?? null, provenance?.adapterId ?? null, entry.type, contentHash ?? null);
+        if (!result)
+            throw new Error("upsertEntry: entry_key not found after upsert");
+        if (previous?.id === result.id && previous.search_text !== searchText)
+            deleteEntryVectors(db, result.id);
+        // Mark this entry as FTS-dirty so `rebuildFts({ incremental: true })`
+        // only revisits entries that actually changed. INSERT OR IGNORE is
+        // idempotent across multiple upserts of the same row.
+        stmts.markDirty.run(result.id);
+        return result.id;
+    };
+    return previous && previous.search_text !== searchText ? db.transaction(apply)() : apply();
+}
+const upsertStmtsByDb = new WeakMap();
+// The ON CONFLICT DO UPDATE column assignments — factored out so the two
+// conflict targets below stay byte-identical. `item_ref` is durable identity;
+// update `entry_key` when adapter ownership changes its
+// spelling so directory pruning retains the upserted row.
+// `content_hash` COALESCEs so a NULL passed by the LLM-enhance re-upsert cannot
+// wipe a previously-persisted hash.
+const UPSERT_SET_CLAUSE = `SET
+        entry_key = excluded.entry_key,
+        dir_path = excluded.dir_path,
+        file_path = excluded.file_path,
+        stash_dir = excluded.stash_dir,
+        entry_json = excluded.entry_json,
+        search_text = excluded.search_text,
+        entry_type = excluded.entry_type,
+        derived_from = excluded.derived_from,
+        item_ref = excluded.item_ref,
+        bundle_id = excluded.bundle_id,
+        component_id = excluded.component_id,
+        concept_id = excluded.concept_id,
+        adapter_id = excluded.adapter_id,
+        type = excluded.type,
+        content_hash = COALESCE(excluded.content_hash, content_hash)`;
+function getUpsertStmts(db) {
+    const existing = upsertStmtsByDb.get(db);
+    if (existing)
+        return existing;
+    // Durable identity is the primary conflict target. `entry_key` remains the
+    // internal conflict key for low-level entries without provenance.
+    const conflictClause = `ON CONFLICT(item_ref) DO UPDATE ${UPSERT_SET_CLAUSE}
+      ON CONFLICT(entry_key) DO UPDATE ${UPSERT_SET_CLAUSE}`;
+    const stmts = {
+        // RETURNING id handles ON CONFLICT DO UPDATE correctly — no second
+        // SELECT round-trip needed (last_insert_rowid() is unreliable for
+        // ON CONFLICT). Use `.get()` so a single row comes back.
+        upsert: db.prepare(`
+      INSERT INTO entries (
+        entry_key, dir_path, file_path, stash_dir, entry_json, search_text, entry_type, derived_from,
+        item_ref, bundle_id, component_id, concept_id, adapter_id, type, content_hash
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ${conflictClause}
+      RETURNING id
+    `),
+        markDirty: db.prepare("INSERT OR IGNORE INTO entries_fts_dirty (entry_id) VALUES (?)"),
+        findByItemRef: db.prepare("SELECT id, search_text FROM entries WHERE item_ref = ? ORDER BY id ASC LIMIT 1"),
+        findByEntryKey: db.prepare("SELECT id, search_text FROM entries WHERE entry_key = ? LIMIT 1"),
+    };
+    upsertStmtsByDb.set(db, stmts);
+    return stmts;
+}
+/**
+ * Phase 5A / Advantage D5: look up the derived-memory child row whose
+ * `derived_from` column matches `parentRef` (the 0.9.0 conceptId, e.g.
+ * `"memories/claude-prefs"` — Group-C item 2 flip).
+ *
+ * Returns the most-recently-updated derived child when multiple exist (one
+ * parent should yield exactly one `.derived` child in practice, but the
+ * ordering keeps results deterministic). Returns `null` when no derived
+ * child has been indexed for this parent.
+ */
+export function getDerivedForParent(db, parentRef, stashDir) {
+    if (!parentRef)
+        return null;
+    const sourceScope = stashDir ? "AND stash_dir = ?" : "";
+    const row = db
+        .prepare(`SELECT ${ENTRY_COLUMNS}
+         FROM entries
+         WHERE derived_from = ?
+         ${sourceScope}
+         ORDER BY id DESC
+         LIMIT 1`)
+        .get(parentRef, ...(stashDir ? [stashDir] : []));
+    if (!row)
+        return null;
+    return rowToIndexedEntry(row, "getDerivedForParent");
+}
+/**
+ * 03-R3: for the given derived-twin row ids, fetch each twin's BASE memory
+ * `beliefState`, keyed by twin id.
+ *
+ * Used by the derived-twin belief inheritance in search ranking: a `.derived`
+ * twin has no belief state of its own, so it inherits its base memory's
+ * demoting state (contradicted/superseded/…) at search time. A twin's
+ * `entry_key` is exactly its base's `entry_key` plus the `.derived` suffix
+ * (same stash + type prefix, `<name>` vs `<name>.derived`), so the base is
+ * found by stripping that suffix — no ref/prefix reconstruction. Returns a map
+ * of twin id → base beliefState for bases that carry a non-empty state.
+ * Best-effort: any query error (e.g. legacy DB) yields no inheritance rather
+ * than failing the search.
+ */
+export function getBaseBeliefStatesForDerivedTwins(db, twinIds) {
+    const out = new Map();
+    if (twinIds.length === 0)
+        return out;
+    // Chunk at SQLITE_CHUNK_SIZE like the sibling bulk-by-id helpers, so a large
+    // `--limit` candidate set never trips SQLITE_MAX_VARIABLE_NUMBER (which would
+    // otherwise fall into the best-effort catch and silently disable the feature).
+    for (let i = 0; i < twinIds.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = twinIds.slice(i, i + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
+        bestEffort(() => {
+            const rows = db
+                .prepare(`SELECT twin.id AS twin_id, json_extract(base.entry_json, '$.beliefState') AS belief
+           FROM entries twin
+           JOIN entries base
+             ON base.entry_type = 'memory'
+             AND base.item_ref = substr(twin.item_ref, 1, length(twin.item_ref) - length('.derived'))
+           WHERE twin.id IN (${placeholders})
+             AND twin.item_ref LIKE '%.derived'
+             AND json_extract(base.entry_json, '$.beliefState') IS NOT NULL`)
+                .all(...chunk);
+            for (const r of rows) {
+                if (typeof r.belief === "string" && r.belief.trim().length > 0)
+                    out.set(r.twin_id, r.belief.trim());
+            }
+        }, "belief-state inheritance is best-effort");
+    }
+    return out;
+}
+/**
+ * SPEC-7 (`akm mv`): re-key an entries row IN PLACE after an on-disk rename.
+ *
+ * The row id is preserved on purpose — `utility_scores`,
+ * `utility_scores_scoped`, and `embeddings` are keyed by `entry_id`, so an
+ * UPDATE (rather than a delete + insert under the new `entry_key`) is what
+ * keeps the asset's accumulated usage-ranking history attached across a
+ * rename. (`asset_salience` / `asset_outcome` live in state.db keyed by
+ * `asset_ref` TEXT and are re-keyed separately by `akm mv` — see
+ * mv-cli.ts `rekeyStateDbForMove`.) `entry_json.name` (and `filename`, when
+ * present) is patched and `search_text` rebuilt so search reflects the new
+ * name; the row is marked FTS-dirty for the caller's
+ * `rebuildFts({incremental: true})`.
+ *
+ * Bundle-qualified `usage_events.entry_ref` rows for the old conceptId are
+ * rewritten to the new item ref. Without this, events keep the old
+ * ref, `relinkUsageEvents` finds no matching entry after the next full
+ * rebuild, and the utility history the re-key exists to preserve silently
+ * resets. DETACHED orphan events already sitting at the new ref (entry_id
+ * NULL — a deleted stranger's history) are deleted first, so the moved asset
+ * never adopts them (live asset's history wins, matching the stale-row
+ * eviction below).
+ *
+ * A stale row already occupying `newEntryKey` (the caller has verified no
+ * FILE exists at the target, so such a row can only be a leftover for a
+ * deleted file) is evicted first — through {@link deleteRelatedRows}, so its
+ * child rows (embeddings, entries_vec, utility scores, usage events) go with
+ * it. A bare `DELETE FROM entries` would trip the non-CASCADE `embeddings`
+ * FK under `PRAGMA foreign_keys = ON` and roll back the whole re-key.
+ * The moved row keeps its id.
+ *
+ * Returns the surviving row id, or `null` when no row matches `oldEntryKey`
+ * (nothing indexed under the old name — the caller falls open and the next
+ * full `akm index` picks the file up as a fresh entry).
+ */
+export function rekeyEntryInPlace(db, opts) {
+    const oldItemRef = `${opts.sourceName}//${opts.oldRef}`;
+    const row = db
+        .prepare("SELECT id, stash_dir, entry_json, search_text, entry_type FROM entries WHERE item_ref = ?")
+        .get(oldItemRef);
+    if (!row)
+        return null;
+    if (path.resolve(row.stash_dir) !== path.resolve(opts.sourceRoot)) {
+        throw new Error(`Refusing to re-key entry ${opts.oldEntryKey}: source root does not match.`);
+    }
+    // Patch the JSON payload. On corrupt entry_json still re-key key + paths so
+    // the utility history survives; the next full index heals the JSON.
+    let entryJson = row.entry_json;
+    let searchText = row.search_text;
+    try {
+        const entry = JSON.parse(row.entry_json);
+        entry.name = opts.newName;
+        if (typeof entry.filename === "string")
+            entry.filename = path.basename(opts.newFilePath);
+        if (opts.newDerivedFrom !== undefined)
+            entry.derivedFrom = opts.newDerivedFrom;
+        entryJson = JSON.stringify(entry);
+        searchText = buildSearchText(entry);
+    }
+    catch {
+        /* corrupt entry_json — key/path-only re-key */
+    }
+    const expectedNewRef = conceptIdFromTypeName(row.entry_type, opts.newName);
+    if (opts.newRef !== expectedNewRef) {
+        throw new Error(`Refusing to re-key entry ${opts.oldEntryKey}: target ref does not match the entry type and name.`);
+    }
+    const newItemRef = `${opts.sourceName}//${opts.newRef}`;
+    db.transaction(() => {
+        const stale = db.prepare("SELECT id FROM entries WHERE entry_key = ?").get(opts.newEntryKey);
+        if (stale && stale.id !== row.id) {
+            // Full child-row cleanup (embeddings, entries_vec, utility scores,
+            // usage events, FTS + dirty marks) BEFORE the entries delete: the
+            // `embeddings` FK is non-CASCADE and `foreign_keys = ON`, so a bare
+            // entries delete would throw and roll back the entire re-key; and
+            // without it the FK-less child rows would orphan permanently.
+            deleteRelatedRows(db, [{ id: stale.id }]);
+            db.prepare("DELETE FROM entries WHERE id = ?").run(stale.id);
+        }
+        db.prepare("UPDATE entries SET entry_key = ?, dir_path = ?, file_path = ?, entry_json = ?, search_text = ?, item_ref = ?, concept_id = ? WHERE id = ?").run(opts.newEntryKey, path.dirname(opts.newFilePath), opts.newFilePath, entryJson, searchText, newItemRef, opts.newRef, row.id);
+        if (opts.newDerivedFrom !== undefined) {
+            db.prepare("UPDATE entries SET derived_from = ? WHERE id = ?").run(opts.newDerivedFrom, row.id);
+        }
+        db.prepare("INSERT OR IGNORE INTO entries_fts_dirty (entry_id) VALUES (?)").run(row.id);
+    })();
+    // Re-point usage history at the new ref. Chunk-8 WI-8.3: usage_events lives in
+    // state.db now, so this is a SEPARATE cross-DB transaction (best-effort — the
+    // rename itself already committed above; on failure the next full index's
+    // relinkUsageEvents re-attaches by ref). See the docstring for the spellings
+    // and the live-asset-wins collision policy.
+    rewriteUsageEventRefForMove(opts);
+    return row.id;
+}
+/**
+ * Rewrite `usage_events.entry_ref` from `opts.oldRef` to `opts.newRef` in
+ * state.db. DETACHED orphan events (entry_id NULL) already sitting AT the new
+ * ref are evicted first so the moved asset never adopts a deleted stranger's
+ * history (live-asset-wins). Best-effort + guarded on state.db's existence.
+ */
+function rewriteUsageEventRefForMove(opts) {
+    if (!fs.existsSync(getStateDbPath()))
+        return;
+    // `usage_events.entry_ref` is the fully-qualified item_ref
+    // (`<bundle>//<conceptId>`).
+    const rename = (stateDb, oldR, newR) => {
+        stateDb.prepare("DELETE FROM usage_events WHERE entry_id IS NULL AND entry_ref = ?").run(newR);
+        stateDb.prepare("UPDATE usage_events SET entry_ref = ? WHERE entry_ref = ?").run(newR, oldR);
+    };
+    try {
+        withStateDb((stateDb) => {
+            stateDb.transaction(() => {
+                rename(stateDb, `${opts.sourceName}//${opts.oldRef}`, `${opts.sourceName}//${opts.newRef}`);
+            })();
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to rewrite usage events for move: ${message}`, { cause: error });
+    }
+}
+/**
+ * Phase 2A / Rec 5: bulk-load positive feedback event counts for the given
+ * entry ids. Used by the utility-decay forgetting curve to stabilize
+ * (extend the half-life of) memories that have repeatedly proven useful.
+ *
+ * Returns a `Map<entryId, count>` containing only entries with at least one
+ * positive feedback event — missing ids implicitly map to `0`. Chunks at
+ * `SQLITE_CHUNK_SIZE` (500) to respect `SQLITE_MAX_VARIABLE_NUMBER`.
+ *
+ * Cheap when called with zero ids, and silently empty when state.db (or its
+ * `usage_events` table) is absent.
+ *
+ * Chunk-8 WI-8.3: usage_events lives in state.db — this reads it there (no
+ * entries join needed; the ids are supplied by the caller). Gated by the caller
+ * (`shouldQueryPositiveFeedbackCounts`) so the state.db open is not on the
+ * default search hot path.
+ */
+export function getPositiveFeedbackCountsByIds(ids) {
+    const result = new Map();
+    if (ids.length === 0 || !fs.existsSync(getStateDbPath()))
+        return result;
+    bestEffort(() => {
+        withStateDb((stateDb) => {
+            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 = stateDb
+                    .prepare(`SELECT entry_id, COUNT(*) AS cnt
+               FROM usage_events
+               WHERE event_type = 'feedback'
+                 AND signal = 'positive'
+                 AND entry_id IN (${placeholders})
+               GROUP BY entry_id`)
+                    .all(...chunk);
+                for (const row of rows) {
+                    if (row.entry_id !== null && row.cnt > 0) {
+                        result.set(row.entry_id, row.cnt);
+                    }
+                }
+            }
+        });
+    }, "positive feedback counts are best-effort");
+    return result;
+}
+function deleteEntriesWhere(db, column, value) {
+    db.transaction(() => {
+        const ids = db.prepare(`SELECT id FROM entries WHERE ${column} = ?`).all(value);
+        deleteRelatedRows(db, ids);
+        db.prepare(`DELETE FROM entries WHERE ${column} = ?`).run(value);
+    })();
+}
+export function deleteEntriesByDir(db, dirPath) {
+    deleteEntriesWhere(db, "dir_path", dirPath);
+}
+export function deleteEntriesByDirAndStash(db, dirPath, stashDir, options = {}) {
+    return db.transaction(() => {
+        const ids = db
+            .prepare("SELECT id FROM entries WHERE dir_path = ? AND stash_dir = ?")
+            .all(dirPath, stashDir);
+        deleteRelatedRows(db, ids, options);
+        db.prepare("DELETE FROM entries WHERE dir_path = ? AND stash_dir = ?").run(dirPath, stashDir);
+        return ids.map((row) => row.id);
+    })();
+}
+/**
+ * Delete every entry (and its child rows) under a source's stash root.
+ *
+ * Chunk-5 flip F1: this keys on `stash_dir` — the physical source-root path,
+ * which is orthogonal to the ref grammar and identifies rows regardless of
+ * whether their `item_ref` is populated or NULL. No item_ref predicate is
+ * needed (or correct) here; both grammars' rows are removed by location.
+ */
+export function deleteEntriesByStashDir(db, stashDir) {
+    deleteEntriesWhere(db, "stash_dir", stashDir);
+}
+/**
+ * Diff-persist orphan delete (Chunk-5 flip F4a M-core-2): remove every entry
+ * (and its child rows, via {@link deleteRelatedRows}) under `dirPath` whose
+ * `entry_key` is NOT in `keepKeys` — the rows for files that vanished from a
+ * rescanned directory.
+ *
+ * Replaces the old per-dir `deleteEntriesByDir` + full re-insert: the caller
+ * upserts the current file set FIRST (ON CONFLICT preserving `entries.id`, so
+ * embeddings / utility / usage stay attached to unchanged rows), then calls this
+ * to prune only the DEPARTED rows. The net row-state of `dir_path` is identical
+ * to delete-then-reinsert; the win is that unchanged rows keep their id.
+ *
+ * Keyed on `entry_key` because it mirrors the directory upsert key precisely.
+ * Both directory- and source-scoped so overlapping source roots cannot prune
+ * one another's rows.
+ */
+export function deleteEntriesByDirExceptKeys(db, dirPath, stashDir, keepKeys, options = {}) {
+    return db.transaction(() => {
+        const rows = db
+            .prepare("SELECT id, entry_key FROM entries WHERE dir_path = ? AND stash_dir = ?")
+            .all(dirPath, stashDir);
+        const doomed = rows.filter((r) => !keepKeys.has(r.entry_key));
+        if (doomed.length === 0)
+            return [];
+        deleteRelatedRows(db, doomed, options);
+        for (let i = 0; i < doomed.length; i += SQLITE_CHUNK_SIZE) {
+            const chunk = doomed.slice(i, i + SQLITE_CHUNK_SIZE);
+            const placeholders = chunk.map(() => "?").join(",");
+            db.prepare(`DELETE FROM entries WHERE id IN (${placeholders})`).run(...chunk.map((r) => r.id));
+        }
+        return doomed.map((row) => row.id);
+    })();
+}
+function deleteRelatedRows(db, ids, options = {}) {
+    if (ids.length === 0)
+        return;
+    const numericIds = ids.map((r) => r.id);
+    const vecAvail = isVecAvailable(db);
+    // Drop matching FTS rows + dirty markers immediately so an incremental
+    // rebuild after a deletion doesn't try to re-index entries that no longer
+    // exist (and so a full scan after deletion sees a consistent FTS).
+    for (let i = 0; i < numericIds.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = numericIds.slice(i, i + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
+        bestEffort(() => db.prepare(`DELETE FROM entries_fts WHERE entry_id IN (${placeholders})`).run(...chunk), "fts table may not exist on a brand-new db");
+        bestEffort(() => db.prepare(`DELETE FROM entries_fts_dirty WHERE entry_id IN (${placeholders})`).run(...chunk), "fts dirty table is created lazily by upsertEntry");
+    }
+    // Process in chunks to stay within SQLITE_MAX_VARIABLE_NUMBER
+    for (let i = 0; i < numericIds.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = numericIds.slice(i, i + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
+        bestEffort(() => db.prepare(`DELETE FROM embeddings WHERE id IN (${placeholders})`).run(...chunk), "delete embeddings for entries");
+        if (vecAvail) {
+            bestEffort(() => db.prepare(`DELETE FROM entries_vec WHERE id IN (${placeholders})`).run(...chunk), "delete entries_vec for entries");
+        }
+        // Clean up utility scores before deleting entries
+        bestEffort(() => db.prepare(`DELETE FROM utility_scores WHERE entry_id IN (${placeholders})`).run(...chunk), "delete utility_scores for entries");
+        bestEffort(() => db.prepare(`DELETE FROM utility_scores_scoped WHERE entry_id IN (${placeholders})`).run(...chunk), "delete utility_scores_scoped for entries");
+    }
+    // usage_events lives in state.db, outside this transaction. Index persistence
+    // disables this cleanup and runs it only after its index.db transaction
+    // commits; standalone delete callers retain the immediate behavior.
+    if (options.cleanupUsageEvents !== false)
+        deleteUsageEventsByEntryIds(numericIds);
+    // #624-P1: graph_files is NO LONGER keyed on entries.id, so deleting an
+    // entries row must NOT wipe the extracted graph (that is the whole point —
+    // the graph survives a reindex when body_hash is unchanged). We therefore do
+    // NOT delete graph_files here. We DO, however, recompute graph_meta counts
+    // for the stash roots touched by the deleted entries so the summary numbers
+    // stay consistent with the live child rows (the counts are derived, and the
+    // entries delete may have changed which files are considered/indexed).
+    //
+    // Resolve the affected stash roots from the entries rows BEFORE deletion.
+    const affectedStashRoots = new Set();
+    for (let i = 0; i < numericIds.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = numericIds.slice(i, i + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
+        bestEffort(() => {
+            const rows = db
+                .prepare(`SELECT DISTINCT stash_dir FROM entries WHERE id IN (${placeholders})`)
+                .all(...chunk);
+            for (const row of rows) {
+                if (row.stash_dir)
+                    affectedStashRoots.add(row.stash_dir);
+            }
+        }, "resolve stash roots for graph_meta recompute");
+    }
+    for (const stashRoot of affectedStashRoots) {
+        bestEffort(() => db
+            .prepare(`UPDATE graph_meta
+             SET extracted_files = (SELECT COUNT(*) FROM graph_files WHERE stash_root = ?),
+                 entity_count    = (SELECT COUNT(*) FROM graph_file_entities WHERE stash_root = ?),
+                 relation_count  = (SELECT COUNT(*) FROM graph_file_relations WHERE stash_root = ?)
+             WHERE stash_root = ?`)
+            .run(stashRoot, stashRoot, stashRoot, stashRoot), "sync graph_meta counts after entries delete");
+    }
+}
+export function deleteUsageEventsByEntryIds(entryIds) {
+    if (entryIds.length === 0 || !fs.existsSync(getStateDbPath()))
+        return;
+    bestEffort(() => {
+        withStateDb((stateDb) => {
+            for (let i = 0; i < entryIds.length; i += SQLITE_CHUNK_SIZE) {
+                const chunk = entryIds.slice(i, i + SQLITE_CHUNK_SIZE);
+                const placeholders = chunk.map(() => "?").join(",");
+                stateDb.prepare(`DELETE FROM usage_events WHERE entry_id IN (${placeholders})`).run(...chunk);
+            }
+        });
+    }, "delete usage_events (state.db) for entries");
+}
+/**
+ * Delete entries by their primary key IDs, along with all related rows
+ * (embeddings, entries_vec, entries_fts, utility_scores, usage_events).
+ *
+ * Used by the `--clean` post-pass to remove stale entries whose source files
+ * no longer exist on disk.
+ */
+export function deleteEntriesByIds(db, ids) {
+    if (ids.length === 0)
+        return;
+    db.transaction(() => {
+        const idObjs = ids.map((id) => ({ id }));
+        deleteRelatedRows(db, idObjs);
+        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(",");
+            db.prepare(`DELETE FROM entries WHERE id IN (${placeholders})`).run(...chunk);
+        }
+    })();
+}
+// ── All entries ─────────────────────────────────────────────────────────────
+function parseEntryRows(rows, context) {
+    const entries = [];
+    for (const row of rows) {
+        const mapped = rowToIndexedEntry(row, context);
+        if (mapped)
+            entries.push(mapped);
+    }
+    return entries;
+}
+export function getAllEntries(db, entryType, excludeTypes) {
+    let sql;
+    let params;
+    // #627 — exclude-type clause applies only on the untyped ('any') path. Empty
+    // list skips the clause (never `NOT IN ()`).
+    const excludes = excludeTypes && excludeTypes.length > 0 ? excludeTypes : [];
+    if (entryType && entryType !== "any") {
+        sql = `SELECT ${ENTRY_COLUMNS} FROM entries WHERE entry_type = ?`;
+        params = [entryType];
+    }
+    else if (excludes.length > 0) {
+        sql = `SELECT ${ENTRY_COLUMNS} FROM entries WHERE entry_type NOT IN (${excludes.map(() => "?").join(", ")})`;
+        params = [...excludes];
+    }
+    else {
+        sql = `SELECT ${ENTRY_COLUMNS} FROM entries`;
+        params = [];
+    }
+    const rows = db.prepare(sql).all(...params);
+    return parseEntryRows(rows, "getAllEntries");
+}
+/**
+ * Resolve a single `entries.id` from a new-grammar `[bundle//]conceptId` ref,
+ * keying on the canonical stored `item_ref` (ref-grammar decision D-R1/D-R4).
+ * The optional `stashDir` scopes the
+ * match to one source root.
+ */
+export function findEntryIdByRef(db, ref, stashDir) {
+    return findEntryIdByBundleRef(db, ref, stashDir);
+}
+/** `name` plus its `.md`-toggled sibling — the markdown ext-keep/strip ambiguity. */
+function withMdVariants(name) {
+    return name.endsWith(".md") ? [name, name.slice(0, -3)] : [name, `${name}.md`];
+}
+/**
+ * Current (`[bundle//]conceptId`) id lookup: match `item_ref` exactly when
+ * bundle-qualified or by `//conceptId` suffix when short.
+ */
+function findEntryIdByBundleRef(db, ref, stashDir) {
+    const parsed = parseBundleRef(ref);
+    const conceptVariants = withMdVariants(parsed.conceptId);
+    // item_ref is the canonical stored spelling post-flip.
+    for (const conceptId of conceptVariants) {
+        const id = matchIdByItemRef(db, parsed.bundle, conceptId, stashDir);
+        if (id !== undefined)
+            return id;
+    }
+    return undefined;
+}
+/**
+ * Match a row `id` by `item_ref`: exact `bundle//conceptId` when `bundle` is
+ * known, else the `//conceptId` SUFFIX (short ref — any bundle). The suffix
+ * uses `substr(...) = ...` (never LIKE) so `_`/`%` in a conceptId are literal,
+ * and includes the `//` boundary so a segment split never false-matches.
+ *
+ * ── Deterministic winner (`ORDER BY id ASC`) ──
+ *
+ * A SHORT ref can match one concept id across MULTIPLE bundles (e.g. the same
+ * `knowledge/guide` in the primary stash and an installed source). The bare
+ * `LIMIT 1` this replaced picked whichever row SQLite happened to visit first —
+ * a nondeterministic winner when two bundles share a conceptId. We now impose a
+ * total order (`ORDER BY id ASC`) so the winner is STABLE across runs.
+ *
+ * `id ASC` is also the SENSIBLE choice, not just a stable tiebreak: a full index
+ * walks its sources in installation-precedence order (`resolveSourceEntries`,
+ * primary stash first — the same order `resolveSourcesForOrigin` calls "local"),
+ * so the highest-precedence source's rows carry the LOWEST ids. Ascending id
+ * therefore prefers the primary/highest-precedence bundle — mirroring what a
+ * precedence-ordered scan would pick — while staying a pure config-free leaf
+ * (true installation-priority resolution against an injected bundle list is
+ * `resolveRef`'s job; this DB helper takes no config handle). The exact-bundle
+ * arm is single-row under the UNIQUE `item_ref` index.
+ */
+function matchIdByItemRef(db, bundle, conceptId, stashDir) {
+    const scope = stashDir ? "AND stash_dir = ?" : "";
+    if (bundle !== undefined) {
+        const itemRef = `${bundle}//${conceptId}`;
+        const row = db
+            .prepare(`SELECT id FROM entries WHERE item_ref = ? ${scope} ORDER BY id ASC LIMIT 1`)
+            .get(itemRef, ...(stashDir ? [stashDir] : []));
+        return row?.id;
+    }
+    const suffix = `//${conceptId}`;
+    const row = db
+        .prepare(`SELECT id FROM entries
+       WHERE item_ref IS NOT NULL
+         AND substr(item_ref, length(item_ref) - length(?) + 1) = ?
+         ${scope}
+       ORDER BY id ASC
+       LIMIT 1`)
+        .get(suffix, suffix, ...(stashDir ? [stashDir] : []));
+    return row?.id;
+}
+export function getEntryCount(db) {
+    const row = db.prepare("SELECT COUNT(*) AS cnt FROM entries").get();
+    return row.cnt;
+}
+/**
+ * Per-asset-type entry counts (keyed by `entry_type`, e.g. "skill",
+ * "knowledge", "memory"). Used by `akm info` to break down the aggregate
+ * `indexStats.entryCount` (R-057). Rows with a null/empty `entry_type` are
+ * omitted rather than surfaced under a synthetic key.
+ */
+export function getEntryCountByType(db) {
+    const rows = db
+        .prepare("SELECT entry_type AS type, COUNT(*) AS cnt FROM entries WHERE entry_type IS NOT NULL GROUP BY entry_type")
+        .all();
+    const out = {};
+    for (const row of rows) {
+        out[row.type] = row.cnt;
+    }
+    return out;
+}
+export function getEmbeddableEntryCount(db) {
+    return getEntryCount(db);
+}
+export function getEntryById(db, id) {
+    const row = db
+        .prepare("SELECT file_path, stash_dir, entry_json, item_ref, bundle_id, concept_id FROM entries WHERE id = ?")
+        .get(id);
+    if (!row)
+        return undefined;
+    // Guard against corrupt JSON
+    let entry;
+    try {
+        entry = JSON.parse(row.entry_json);
+    }
+    catch {
+        warn(`[db] getEntryById: skipping entry id=${id} — corrupt entry_json`);
+        return undefined;
+    }
+    return {
+        filePath: row.file_path,
+        stashDir: row.stash_dir,
+        entry,
+        itemRef: row.item_ref,
+        bundleId: row.bundle_id,
+        conceptId: row.concept_id,
+    };
+}
+export function getEntriesByDir(db, dirPath) {
+    const rows = db.prepare(`SELECT ${ENTRY_COLUMNS} FROM entries WHERE dir_path = ?`).all(dirPath);
+    return parseEntryRows(rows, "getEntriesByDir");
+}
+/** Return every directory previously indexed for one physical source root. */
+export function getIndexedDirPathsByStashDir(db, stashDir) {
+    const rows = db.prepare("SELECT DISTINCT dir_path FROM entries WHERE stash_dir = ?").all(stashDir);
+    return rows.map((row) => row.dir_path);
+}
+/** Return every persisted source owner for one physical directory. */
+export function getIndexedStashDirsByDir(db, dirPath) {
+    const rows = db.prepare("SELECT DISTINCT stash_dir FROM entries WHERE dir_path = ?").all(dirPath);
+    return rows.map((row) => row.stash_dir);
+}
+/**
+ * Resolve a single `entries.id` by exact `file_path` (the canonical on-disk
+ * path), or `undefined` if no row matches.
+ *
+ * Lifted verbatim (WS5) from the inline `SELECT id FROM entries WHERE
+ * file_path = ? LIMIT 1` in commands/search.ts so all `entries` SQL lives in
+ * this module. The result is a plain number materialised before return —
+ * nothing lazy crosses a connection boundary.
+ */
+export function getEntryIdByFilePath(db, filePath) {
+    const row = db.prepare("SELECT id FROM entries WHERE file_path = ? LIMIT 1").get(filePath);
+    return row?.id;
+}
+/**
+ * Set of every non-empty `entries.file_path` currently indexed (across all
+ * stashes/sources). Used by staleness detection to spot files that exist on
+ * disk but were never indexed — a clock-independent signal for newly-added
+ * assets that an mtime-vs-builtAt comparison can miss when the two clocks
+ * (filesystem vs wall-clock) are skewed within the same millisecond.
+ */
+export function getIndexedFilePaths(db) {
+    const rows = db
+        .prepare("SELECT DISTINCT file_path FROM entries WHERE file_path IS NOT NULL AND file_path <> ''")
+        .all();
+    return new Set(rows.map((r) => r.file_path));
+}
+/**
+ * Resolve a single `entries.file_path` by primary key, or `undefined` if no
+ * row matches.
+ *
+ * Lifted verbatim (WS5) from the inline `SELECT file_path FROM entries WHERE
+ * id = ?` in commands/feedback-cli.ts. Unlike {@link getEntryById}, this does
+ * NOT parse `entry_json`, so a row with corrupt JSON still yields its path —
+ * preserving feedback-cli's pre-extraction behaviour byte-for-byte.
+ */
+export function getEntryFilePathById(db, id) {
+    const row = db.prepare("SELECT file_path FROM entries WHERE id = ?").get(id);
+    return row?.file_path;
+}
+/**
+ * Fetch every `(file_path, entry_json)` row whose entry belongs to a given
+ * stash root — matched either by exact `stash_dir` OR by `file_path` prefix.
+ *
+ * Lifted verbatim (WS5) from the inline query in commands/graph.ts'
+ * `buildRefByPath`. The full result set is materialised with `.all()` before
+ * return so callers can iterate it after the connection closes (WS5
+ * connection-lifetime rule). JSON parsing stays with the caller, unchanged.
+ */
+export function getEntryRefRowsForStashRoot(db, stashRoot) {
+    return db
+        .prepare("SELECT file_path, entry_json FROM entries WHERE stash_dir = ? OR file_path LIKE ?")
+        .all(stashRoot, `${stashRoot}%`);
+}
+// ── Indexer-phase helpers (moved from indexer.ts) ────────────────────────────
+/**
+ * Upsert a workflow document record for an indexed entry.
+ * Persists the parsed workflow AST as JSON alongside a FNV-1a hash of the
+ * source content for future incremental fast-paths.
+ */
+export function upsertWorkflowDocument(db, entryId, doc, content) {
+    const sourceHash = computeSourceHash(content);
+    db.prepare(`INSERT INTO workflow_documents (entry_id, schema_version, document_json, source_path, source_hash, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(entry_id) DO UPDATE SET
+       schema_version = excluded.schema_version,
+       document_json = excluded.document_json,
+       source_path = excluded.source_path,
+       source_hash = excluded.source_hash,
+       updated_at = excluded.updated_at`).run(entryId, doc.schemaVersion, JSON.stringify(doc), doc.source.path, sourceHash, new Date().toISOString());
+}
+/**
+ * Compute a cheap FNV-1a hash of a buffer for source-identity tracking.
+ * Not security-sensitive; used as an incremental fast-path skip key.
+ */
+export function computeSourceHash(content) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < content.length; i++) {
+        hash ^= content[i];
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16);
+}
+/**
+ * Return distinct zero-result search queries from the `usage_events` table
+ * within the given lookback window.
+ *
+ * Reads from `usage_events` (event_type = 'search') where the metadata JSON
+ * blob contains `resultCount = 0`. The `search_events` table never existed;
+ * all errors are caught and an empty array is returned so callers never need
+ * to guard against DB schema differences.
+ */
+export function getZeroResultSearches(db, sinceDays = 30) {
+    const since = new Date(Date.now() - sinceDays * 24 * 60 * 60 * 1000).toISOString();
+    try {
+        const rows = db
+            .prepare(`SELECT DISTINCT json_extract(metadata, '$.query') AS query
+         FROM usage_events
+         WHERE event_type = 'search'
+           AND created_at >= ?
+           AND json_extract(metadata, '$.resultCount') = 0
+         ORDER BY created_at DESC LIMIT 20`)
+            .all(since);
+        return rows.map((r) => r.query).filter((q) => q !== null);
+    }
+    catch {
+        return []; // table may not exist in older DBs
+    }
+}
+/**
+ * Look up an entry `id` by a new-grammar `[bundle//]conceptId` ref, resolving
+ * against the canonical stored `item_ref`. Returns `{ id }` or `null`.
+ */
+export function getEntryByRef(db, ref) {
+    const id = findEntryIdByRef(db, ref);
+    return id === undefined ? null : { id };
+}
+/**
+ * The fully-qualified `item_ref` (`<bundle>//<conceptId>`, the durable stored
+ * spelling — spec §11.1 D-R3) for an entry `id`, or `null` when the row is gone
+ * or its `item_ref` is still NULL (a write-back straggler, healed on the next
+ * full index). The usage-event / salience / feedback writers derive the durable
+ * key from this so a stored key is always the resolved entry's canonical ref,
+ * never raw input (D-R3: durable keys are never derived from input).
+ */
+export function getItemRefById(db, id) {
+    const row = db.prepare("SELECT item_ref FROM entries WHERE id = ?").get(id);
+    return row?.item_ref ?? null;
+}
+/**
+ * Resolve a `usage_events.entry_ref` to its live `entries.id`. `entry_ref` is
+ * the fully-qualified `bundle//conceptId` `item_ref` spelling, so this keys
+ * directly on the globally-unique `item_ref`. Bare durable refs are invalid and
+ * remain detached.
+ */
+function resolveUsageEventEntryId(db, ref) {
+    if (parseBundleRef(ref).bundle === undefined)
+        return undefined;
+    return findEntryIdByRef(db, ref);
+}
+/**
+ * Re-link detached usage_events to their current entry_ids via entry_ref.
+ *
+ * After a full rebuild, entry IDs change. This restores each event's link
+ * using the stable `entry_ref` column so usage history survives a reindex.
+ *
+ * Cross-DB (Chunk-8 WI-8.3): `usage_events` lives in `stateDb` while `entries`
+ * lives in `indexDb`. The stale-id null-out (formerly a single-DB
+ * `NOT IN (SELECT id FROM entries)`) is done in two bounded passes — the set of
+ * distinct linked entry_ids in usage_events is small — and the re-resolution
+ * reads `entries` from `indexDb`.
+ */
+export function relinkUsageEvents(indexDb, stateDb, _options = {}) {
+    bestEffort(() => {
+        // Step 1: null out stale entry_ids (entry was deleted, re-keyed, etc).
+        // Leaving them in place would let `recomputeUtilityScores` aggregate by an
+        // entry_id that no longer exists in `entries`, then trip the FK constraint
+        // on the utility_scores INSERT and roll back the entire finalize
+        // transaction. Nulled rows can be re-resolved by step 2 below; events whose
+        // entry is permanently gone simply stay null and age out via retention.
+        const linkedIds = stateDb.prepare("SELECT DISTINCT entry_id AS id FROM usage_events WHERE entry_id IS NOT NULL").all().map((r) => r.id);
+        const entryExists = indexDb.prepare("SELECT 1 FROM entries WHERE id = ?");
+        const staleIds = linkedIds.filter((id) => entryExists.get(id) == null);
+        if (staleIds.length > 0) {
+            const nullOut = stateDb.prepare("UPDATE usage_events SET entry_id = NULL WHERE entry_id = ?");
+            const nullTx = stateDb.transaction(() => {
+                for (const id of staleIds)
+                    nullOut.run(id);
+            });
+            nullTx();
+        }
+        // Step 2: re-resolve each fully-qualified ref. Bare rows are not current
+        // durable identities and remain detached.
+        const refs = stateDb
+            .prepare("SELECT DISTINCT entry_ref AS ref FROM usage_events WHERE entry_id IS NULL AND entry_ref IS NOT NULL")
+            .all();
+        const update = stateDb.prepare("UPDATE usage_events SET entry_id = ? WHERE entry_ref = ? AND entry_id IS NULL");
+        const relinkTx = stateDb.transaction(() => {
+            for (const { ref } of refs) {
+                let id;
+                try {
+                    id = resolveUsageEventEntryId(indexDb, ref);
+                }
+                catch (err) {
+                    if (err instanceof Error && err.name === "UsageError")
+                        continue;
+                    throw err;
+                }
+                if (id !== undefined)
+                    update.run(id, ref);
+            }
+        });
+        relinkTx();
+    }, "usage_events table may not exist yet during entry_id re-resolution");
+}