akm-cli 0.8.7 → 0.8.14

package/dist/indexer/{db.js → db/db.js}

@@ -1,18 +1,20 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { Database } from "bun:sqlite";
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
-import { parseAssetRef } from "../core/asset-ref";
-import { getDbPath } from "../core/paths";
-import { REGISTRY_INDEX_CACHE_DDL } from "../core/state-db";
-import { warn } from "../core/warn";
-import { cosineSimilarity } from "../llm/embedders/types";
-import { backupDataDir, EMBEDDING_DIM_CHANGE_REASON } from "./db-backup";
-import { buildSearchFields } from "./search-fields";
-import { ensureUsageEventsSchema } from "./usage-events";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { bestEffort } from "../../core/best-effort.js";
+import { getDbPath } from "../../core/paths.js";
+import { REGISTRY_INDEX_CACHE_DDL } from "../../core/state-db.js";
+import { warn } from "../../core/warn.js";
+import { cosineSimilarity } from "../../llm/embedders/types.js";
+import { sha256Hex } from "../../runtime.js";
+import { openDatabase as openSqlite } from "../../storage/database.js";
+import { buildSearchFields } from "../search/search-fields.js";
+import { ensureUsageEventsSchema } from "../usage/usage-events.js";
+import { backupDataDir, EMBEDDING_DIM_CHANGE_REASON } from "./db-backup.js";
 // ── Constants ───────────────────────────────────────────────────────────────
 export const DB_VERSION = 17;
 export const EMBEDDING_DIM = 384;
@@ -24,9 +26,9 @@ export function openDatabase(dbPath, options) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    const db = new Database(resolvedPath);
+    const db = openSqlite(resolvedPath);
     db.exec("PRAGMA journal_mode = WAL");
-    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA busy_timeout = 30000");
     db.exec("PRAGMA foreign_keys = ON");
     // Try to load sqlite-vec extension
     loadVecExtension(db);
@@ -52,7 +54,7 @@ export function openDatabase(dbPath, options) {
  */
 function resolveConfiguredEmbeddingDim() {
     try {
-        const { loadConfig } = require("../core/config");
+        const { loadConfig } = require("../../core/config/config");
         const dim = loadConfig().embedding?.dimension;
         if (typeof dim === "number" && Number.isInteger(dim) && dim > 0 && dim <= 4096) {
             return dim;
@@ -65,9 +67,9 @@ function resolveConfiguredEmbeddingDim() {
 }
 export function openExistingDatabase(dbPath) {
     const resolvedPath = dbPath ?? getDbPath();
-    const db = new Database(resolvedPath);
+    const db = openSqlite(resolvedPath);
     db.exec("PRAGMA journal_mode = WAL");
-    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA busy_timeout = 30000");
     db.exec("PRAGMA foreign_keys = ON");
     // Existing-DB callers must not mutate schema or embedding metadata on open,
     // but some paths still need write access to usage_events and other tables.
@@ -83,6 +85,10 @@ 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);
     }
@@ -107,7 +113,7 @@ export function warnIfVecMissing(db, { once } = { once: false }) {
         return;
     if (once && vecInitWarnedDbs.has(db))
         return;
-    try {
+    bestEffort(() => {
         const row = db.prepare("SELECT COUNT(*) AS cnt FROM embeddings").get();
         const count = row?.cnt ?? 0;
         if (count >= VEC_FALLBACK_THRESHOLD) {
@@ -115,10 +121,7 @@ export function warnIfVecMissing(db, { once } = { once: false }) {
             if (once)
                 vecInitWarnedDbs.add(db);
         }
-    }
-    catch {
-        /* embeddings table may not exist yet during init */
-    }
+    }, "embeddings table may not exist yet during init");
 }
 function ensureSchema(db, embeddingDim, options) {
     // Create meta table first so we can check version
@@ -402,20 +405,10 @@ function ensureSchema(db, embeddingDim, options) {
                 // uses earlier in this function, just gated on embedding-dim mismatch
                 // and tagged so operators can tell the two backup kinds apart.
                 backupBeforeEmbeddingDimChange(options?.dataDir, storedDim, String(embeddingDim));
-                try {
-                    db.exec("DROP TABLE IF EXISTS entries_vec");
-                }
-                catch {
-                    /* ignore */
-                }
+                bestEffort(() => db.exec("DROP TABLE IF EXISTS entries_vec"), "drop entries_vec on dim change");
                 // Delete stale BLOB embeddings so they don't produce silently wrong
                 // similarity scores against the new-dimension vec table.
-                try {
-                    db.exec("DELETE FROM embeddings");
-                }
-                catch {
-                    /* ignore */
-                }
+                bestEffort(() => db.exec("DELETE FROM embeddings"), "delete stale embeddings on dim change");
                 setMeta(db, "hasEmbeddings", "0");
             }
         }
@@ -444,12 +437,7 @@ function ensureSchema(db, embeddingDim, options) {
             const storedDim = getMeta(db, "embeddingDim");
             if (storedDim && storedDim !== String(embeddingDim)) {
                 backupBeforeEmbeddingDimChange(options?.dataDir, storedDim, String(embeddingDim));
-                try {
-                    db.exec("DELETE FROM embeddings");
-                }
-                catch {
-                    /* ignore */
-                }
+                bestEffort(() => db.exec("DELETE FROM embeddings"), "delete embeddings on explicit dim change");
                 setMeta(db, "hasEmbeddings", "0");
             }
             setMeta(db, "embeddingDim", String(embeddingDim));
@@ -484,12 +472,9 @@ function handleVersionUpgrade(db) {
     if (storedVersion === undefined || storedVersion === "" || storedVersion === String(DB_VERSION))
         return [];
     let usageBackup = [];
-    try {
+    bestEffort(() => {
         usageBackup = db.prepare("SELECT * FROM usage_events").all();
-    }
-    catch {
-        /* table may not exist in older versions */
-    }
+    }, "usage_events table may not exist in older versions");
     db.exec("DROP TABLE IF EXISTS utility_scores");
     db.exec("DROP TABLE IF EXISTS utility_scores_scoped");
     db.exec("DROP INDEX IF EXISTS idx_utility_scores_scoped_entry_id");
@@ -720,7 +705,7 @@ function getUpsertStmts(db) {
  * data loss. Idempotent: a `PRAGMA table_info` lookup gates the ALTER.
  */
 function ensureDerivedFromColumn(db) {
-    try {
+    bestEffort(() => {
         const cols = db.prepare("PRAGMA table_info(entries)").all();
         const hasColumn = cols.some((c) => c.name === "derived_from");
         if (!hasColumn) {
@@ -728,10 +713,7 @@ function ensureDerivedFromColumn(db) {
         }
         // Index creation is idempotent on its own; safe to call unconditionally.
         db.exec("CREATE INDEX IF NOT EXISTS idx_entries_derived_from ON entries(derived_from)");
-    }
-    catch {
-        /* table may not exist on a brand-new DB before CREATE — caller is responsible */
-    }
+    }, "entries table may not exist on a brand-new DB before CREATE — caller is responsible");
 }
 /**
  * Phase 5A / Advantage D5: look up the derived-memory child row whose
@@ -798,7 +780,7 @@ export function getPositiveFeedbackCountsByIds(db, ids) {
     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(",");
-        try {
+        bestEffort(() => {
             const rows = db
                 .prepare(`SELECT entry_id, COUNT(*) AS cnt
              FROM usage_events
@@ -812,10 +794,7 @@ export function getPositiveFeedbackCountsByIds(db, ids) {
                     result.set(row.entry_id, row.cnt);
                 }
             }
-        }
-        catch {
-            /* usage_events table may be missing on legacy DBs — treat as zero counts */
-        }
+        }, "usage_events table may be missing on legacy DBs — treat as zero counts");
     }
     return result;
 }
@@ -843,57 +822,22 @@ function deleteRelatedRows(db, ids) {
     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(",");
-        try {
-            db.prepare(`DELETE FROM entries_fts WHERE entry_id IN (${placeholders})`).run(...chunk);
-        }
-        catch {
-            /* fts table may not exist on a brand-new db */
-        }
-        try {
-            db.prepare(`DELETE FROM entries_fts_dirty WHERE entry_id IN (${placeholders})`).run(...chunk);
-        }
-        catch {
-            /* dirty table is created lazily by upsertEntry */
-        }
+        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(",");
-        try {
-            db.prepare(`DELETE FROM embeddings WHERE id IN (${placeholders})`).run(...chunk);
-        }
-        catch {
-            /* ignore */
-        }
+        bestEffort(() => db.prepare(`DELETE FROM embeddings WHERE id IN (${placeholders})`).run(...chunk), "delete embeddings for entries");
         if (vecAvail) {
-            try {
-                db.prepare(`DELETE FROM entries_vec WHERE id IN (${placeholders})`).run(...chunk);
-            }
-            catch {
-                /* ignore */
-            }
+            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
-        try {
-            db.prepare(`DELETE FROM utility_scores WHERE entry_id IN (${placeholders})`).run(...chunk);
-        }
-        catch {
-            /* ignore */
-        }
-        try {
-            db.prepare(`DELETE FROM utility_scores_scoped WHERE entry_id IN (${placeholders})`).run(...chunk);
-        }
-        catch {
-            /* ignore */
-        }
+        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");
         // Clean up usage events before deleting entries
-        try {
-            db.prepare(`DELETE FROM usage_events WHERE entry_id IN (${placeholders})`).run(...chunk);
-        }
-        catch {
-            /* ignore */
-        }
+        bestEffort(() => db.prepare(`DELETE FROM usage_events WHERE entry_id IN (${placeholders})`).run(...chunk), "delete usage_events for entries");
     }
 }
 /**
@@ -1005,15 +949,12 @@ export function upsertEmbedding(db, entryId, embedding) {
     // Wrapped in a transaction so a crash between DELETE and INSERT does not
     // leave the entry missing from the vec table.
     if (isVecAvailable(db)) {
-        try {
+        bestEffort(() => {
             db.transaction(() => {
                 db.prepare("DELETE FROM entries_vec WHERE id = ?").run(entryId);
                 db.prepare("INSERT INTO entries_vec (id, embedding) VALUES (?, ?)").run(entryId, buf);
             })();
-        }
-        catch {
-            /* ignore — vec table unavailable or constraint failure */
-        }
+        }, "vec table unavailable or constraint failure");
     }
     return true;
 }
@@ -1279,6 +1220,10 @@ export function getEntryCount(db) {
     const row = db.prepare("SELECT COUNT(*) AS cnt FROM entries").get();
     return row.cnt;
 }
+export function getEmbeddableEntryCount(db) {
+    const row = db.prepare("SELECT COUNT(*) AS cnt FROM entries").get();
+    return row.cnt;
+}
 export function getEmbeddingCount(db) {
     const row = db.prepare("SELECT COUNT(*) AS cnt FROM embeddings").get();
     return row.cnt;
@@ -1304,6 +1249,46 @@ export function getEntriesByDir(db, dirPath) {
         .all(dirPath);
     return parseEntryRows(rows, "getEntriesByDir");
 }
+/**
+ * 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;
+}
+/**
+ * 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}%`);
+}
 /**
  * Get the utility score for an entry, or undefined if none exists.
  */
@@ -1475,28 +1460,21 @@ export function upsertLlmCacheEntry(db, assetRef, bodyHash, resultJson, cacheVar
  * matches a live file_path.
  */
 export function clearStaleCacheEntries(db) {
-    try {
+    bestEffort(() => {
         db.exec(`
       DELETE FROM llm_enrichment_cache
       WHERE asset_ref NOT IN (SELECT file_path FROM entries)
         AND asset_ref NOT IN (SELECT entry_key FROM entries)
     `);
-    }
-    catch {
-        /* ignore — table may not exist in very old DBs opened without ensureSchema */
-    }
+    }, "llm_enrichment_cache may not exist in very old DBs opened without ensureSchema");
 }
 /**
- * Compute a stable SHA-256 hex digest of a UTF-8 string using Bun's native
- * hashing. Used as the body_hash key in `llm_enrichment_cache`.
- *
- * Bun.CryptoHasher is synchronous and allocation-free compared to Web Crypto,
- * making it suitable for use inside tight per-asset loops.
+ * Compute a stable SHA-256 hex digest of a UTF-8 string. Used as the body_hash
+ * key in `llm_enrichment_cache`. Routed through the runtime boundary so the
+ * SQLite layer stays free of direct runtime-specific references.
  */
 export function computeBodyHash(body) {
-    const hasher = new Bun.CryptoHasher("sha256");
-    hasher.update(body);
-    return hasher.digest("hex");
+    return sha256Hex(body);
 }
 /**
  * Count search and show events for the given entry refs.
@@ -1588,7 +1566,6 @@ export function getAllEntriesForEmbedding(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)
-        AND e.entry_type != 'vault'
     `)
         .all();
 }
@@ -1751,7 +1728,7 @@ export function applyFeedbackToUtilityScore(db, entryId, positiveCount, negative
  * history survives a full reindex.
  */
 export function relinkUsageEvents(db) {
-    try {
+    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
@@ -1776,10 +1753,7 @@ export function relinkUsageEvents(db) {
       )
       WHERE entry_id IS NULL AND entry_ref IS NOT NULL
     `);
-    }
-    catch {
-        /* ignore if table doesn't exist yet */
-    }
+    }, "usage_events table may not exist yet during entry_id re-resolution");
 }
 // ── registry_index_cache helpers ─────────────────────────────────────────────
 /**
@@ -1825,3 +1799,39 @@ export function getRegistryIndexCache(db, registryUrl, maxAgeMs = 3_600_000 /* 1
         return undefined;
     return { indexJson: row.index_json, etag: row.etag, lastModified: row.last_modified };
 }
+/**
+ * Walk indexed entries and collect a deduplicated set of tags. When
+ * `entryType` is provided, only entries of that type contribute tags.
+ *
+ * Pure read; never mutates the DB. Used by `akm lessons coverage` (Phase 7A)
+ * to compute the diff between all-asset tags and lesson tags. Tags are
+ * normalised by trimming and lower-casing, and blank tags are dropped.
+ *
+ * SQL owner: this module owns ALL raw SQL against the `entries` table (WS5),
+ * so the `lessons coverage` read lives here rather than leaking into cli.ts.
+ * The result set is fully materialised (`.all()` then iterate) before return.
+ */
+export function collectTagSetFromEntries(db, entryType) {
+    const tags = new Set();
+    const stmt = entryType
+        ? db.prepare("SELECT entry_json FROM entries WHERE entry_type = ?")
+        : db.prepare("SELECT entry_json FROM entries");
+    const rows = (entryType ? stmt.all(entryType) : stmt.all());
+    for (const row of rows) {
+        let parsed;
+        try {
+            parsed = JSON.parse(row.entry_json);
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(parsed.tags))
+            continue;
+        for (const tag of parsed.tags) {
+            if (typeof tag === "string" && tag.trim().length > 0) {
+                tags.add(tag.trim().toLowerCase());
+            }
+        }
+    }
+    return tags;
+}

package/dist/indexer/{graph-db.js → db/graph-db.js}

@@ -2,10 +2,10 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
-import { rethrowIfTestIsolationError } from "../core/errors";
-import { getDbPath } from "../core/paths";
-import { warn } from "../core/warn";
-import { closeDatabase, openExistingDatabase } from "./db";
+import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { getDbPath } from "../../core/paths.js";
+import { warn } from "../../core/warn.js";
+import { closeDatabase, openExistingDatabase } from "./db.js";
 function withReadableGraphDb(db, fn) {
     if (db)
         return fn(db);
@@ -287,6 +287,11 @@ export function loadStoredGraphMeta(stashPath, db) {
                         cacheMisses: row.cache_misses,
                         truncationCount: row.truncation_count,
                         failureCount: row.failure_count,
+                        // `retry_attempts` is not persisted to the graph-meta table (it is
+                        // surfaced from the run's emitted telemetry into `akm health`, not
+                        // from the reuse cache). Default to 0 so the loaded shape satisfies
+                        // GraphExtractionTelemetry.
+                        retryAttempts: 0,
                     },
                 };
             }

package/dist/indexer/{llm-cache.js → db/llm-cache.js}

@@ -1,7 +1,15 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } from "./db";
+/**
+ * Generic LLM-result cache wrapper shared across indexer passes.
+ *
+ * Each pass that calls an LLM and wants to skip re-processing unchanged
+ * content can delegate the cache check/write to `withLlmCache` instead of
+ * duplicating the hash-compute → lookup → write pattern inline.
+ */
+import { bestEffort } from "../../core/best-effort.js";
+import { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } from "./db.js";
 /**
  * Generic LLM cache wrapper. Returns cached result if body unchanged,
  * otherwise calls llmFn(), caches the result, and returns it.
@@ -25,7 +33,7 @@ import { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } from "./db";
 export async function withLlmCache(db, cacheKey, body, reEnrich, llmFn, validate, precomputedHash, cacheVariant = "", hooks) {
     const bodyHash = precomputedHash ?? computeBodyHash(body);
     if (!reEnrich) {
-        try {
+        const cacheHit = bestEffort(() => {
             const cached = getLlmCacheEntry(db, cacheKey, bodyHash, cacheVariant);
             if (cached) {
                 const result = validate(JSON.parse(cached.resultJson));
@@ -34,19 +42,14 @@ export async function withLlmCache(db, cacheKey, body, reEnrich, llmFn, validate
                     return result;
                 }
             }
-        }
-        catch {
-            // Cache corrupt — fall through
-        }
+            return undefined;
+        }, "llm cache read corrupt — fall through to recompute");
+        if (cacheHit !== undefined)
+            return cacheHit;
     }
     const result = await llmFn();
     if (result !== undefined) {
-        try {
-            upsertLlmCacheEntry(db, cacheKey, bodyHash, JSON.stringify(result), cacheVariant);
-        }
-        catch {
-            // Cache write failure is non-fatal
-        }
+        bestEffort(() => upsertLlmCacheEntry(db, cacheKey, bodyHash, JSON.stringify(result), cacheVariant), "llm cache write failure is non-fatal");
     }
     return result;
 }

package/dist/indexer/ensure-index.js

@@ -13,10 +13,10 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { ASSET_SPECS, TYPE_DIRS } from "../core/asset-spec";
-import { getDbPath } from "../core/paths";
-import { warn } from "../core/warn";
-import { closeDatabase, getEntryCount, getMeta, openExistingDatabase } from "./db";
+import { ASSET_SPECS, TYPE_DIRS } from "../core/asset/asset-spec.js";
+import { getDbPath } from "../core/paths.js";
+import { warn } from "../core/warn.js";
+import { closeDatabase, getEntryCount, getMeta, openExistingDatabase } from "./db/db.js";
 function getIndexableFiles(root, spec) {
     if (!fs.existsSync(root))
         return [];

package/dist/indexer/{graph-boost.js → graph/graph-boost.js}

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { loadStoredGraphMeta, loadStoredGraphSnapshot } from "./graph-db";
+import { loadStoredGraphMeta, loadStoredGraphSnapshot } from "../db/graph-db.js";
 function normalizeGraphName(value) {
     return value.trim().toLowerCase();
 }

package/dist/indexer/{graph-extraction.js → graph/graph-extraction.js}

@@ -1,20 +1,54 @@
 // 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/.
+/**
+ * Graph-extraction pass for `akm index` (#207).
+ *
+ * Walks the primary stash for `memory:` and `knowledge:` assets, asks the
+ * configured LLM to extract entities and relations from each one, and
+ * persists the result to stash-local SQLite graph tables keyed by stash root.
+ * The artifact is consumed by the search
+ * pipeline (see `src/indexer/graph-boost.ts`) as a single boost component
+ * inside the existing FTS5+boosts loop — there is NO second SearchHit
+ * scorer and no parallel ranking track.
+ *
+ * Disabling — three preconditions must ALL hold for the pass to run:
+ *   1. An LLM profile must be configured (no provider = no extraction). When
+ *      absent, `resolveIndexPassLLM("graph", config)` returns `undefined`
+ *      and the pass short-circuits.
+ *   2. `profiles.improve.default.processes.graphExtraction.enabled !== false`
+ *      — the feature-gate layer (historically v1 spec §14, since superseded by
+ *      the 0.8.0 profile shape). Set to `false` to block the pass at the
+ *      feature-gate layer (no network call may ever issue).
+ *   3. `index.graph.llm !== false` — the per-pass opt-out layer (#208).
+ *      Set to `false` to skip just this pass while leaving other passes
+ *      that share the same LLM profile enabled.
+ *   Toggling any one off does NOT delete the existing persisted graph — the
+ *   user keeps the boost component they already have, it just stops
+ *   refreshing.
+ *
+ * Locked v1 contract:
+ *   - LLM access is exclusively via `resolveIndexPassLLM("graph", config)`.
+ *   - The graph rows are an indexer artifact, NOT a user-visible
+ *     asset. It does not have an asset ref, does not appear in search
+ *     hits, and is not addressable via `akm show`. Direct `fs.writeFile`
+ *     is therefore the correct primitive — `writeAssetToSource` is
+ *     reserved for asset writes (CLAUDE.md / spec §10 step 5).
+ */
 import fs from "node:fs";
 import path from "node:path";
-import { TYPE_DIRS } from "../core/asset-spec";
-import { concurrentMap } from "../core/concurrent";
-import { getIndexPassConfig, resolveBatchSize } from "../core/config";
-import { parseFrontmatter } from "../core/frontmatter";
-import { warn, warnVerbose } from "../core/warn";
-import { isProcessEnabled } from "../llm/feature-gate";
-import * as graphExtract from "../llm/graph-extract";
-import { resolveIndexPassLLM } from "../llm/index-passes";
-import { computeBodyHash, GRAPH_SCHEMA_VERSION, getLlmCacheEntriesByRefs, getLlmCacheEntry, upsertLlmCacheEntry, } from "./db";
-import { loadStoredGraphSnapshot, replaceStoredGraph } from "./graph-db";
-import { deduplicateGraph } from "./graph-dedup";
-import { walkMarkdownFiles } from "./walker";
+import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { concurrentMap } from "../../core/concurrent.js";
+import { getIndexPassConfig, resolveBatchSize } from "../../core/config/config.js";
+import { warn, warnVerbose } from "../../core/warn.js";
+import { isProcessEnabled } from "../../llm/feature-gate.js";
+import * as graphExtract from "../../llm/graph-extract.js";
+import { resolveIndexPassLLM } from "../../llm/index-passes.js";
+import { computeBodyHash, GRAPH_SCHEMA_VERSION, getLlmCacheEntriesByRefs, getLlmCacheEntry, upsertLlmCacheEntry, } from "../db/db.js";
+import { loadStoredGraphSnapshot, replaceStoredGraph } from "../db/graph-db.js";
+import { walkMarkdownFiles } from "../walk/walker.js";
+import { deduplicateGraph } from "./graph-dedup.js";
 /** Schema version for the persisted artifact — bumps trigger a full rebuild. */
 export const GRAPH_FILE_SCHEMA_VERSION = GRAPH_SCHEMA_VERSION;
 const EMPTY_QUALITY = {
@@ -37,6 +71,7 @@ const EMPTY_RESULT = {
         cacheMisses: 0,
         truncationCount: 0,
         failureCount: 0,
+        retryAttempts: 0,
     },
     warnings: [],
 };
@@ -231,7 +266,8 @@ function reuseGraphNode(previousNodes, candidate, bodyHash) {
  * `extractGraphFromBodies`. Default batch size is 1 (one call per asset —
  * preserves existing behaviour, fully opt-in).
  */
-export async function runGraphExtractionPass(config, sources, signal, db, reEnrich, onProgress, options = {}) {
+export async function runGraphExtractionPass(ctx) {
+    const { config, sources, signal, db, reEnrich, onProgress, options = {} } = ctx;
     // Gate 1 — feature gate via isProcessEnabled, which reads the 0.8.0 path
     // (profiles.improve.default.processes.graphExtraction.enabled). Defaults to
     // enabled when the key is absent.
@@ -306,11 +342,15 @@ export async function runGraphExtractionPass(config, sources, signal, db, reEnri
         cacheMisses: 0,
         truncationCount: 0,
         failureCount: 0,
+        htmlErrorCount: 0,
+        retryAttempts: 0,
     };
     const canReusePreviousGraph = previousGraph.telemetry?.extractorId === extractorId;
     const runtimeTelemetry = {
         truncationCount: 0,
         failureCount: 0,
+        htmlErrorCount: 0,
+        retryAttempts: 0,
         filteredGenericEntities: 0,
         filteredInvalidRelations: 0,
         filteredLowConfidenceRelations: 0,
@@ -555,6 +595,8 @@ export async function runGraphExtractionPass(config, sources, signal, db, reEnri
     const deduped = deduplicateGraph(mergedNodes.map((node) => ({ entities: node.entities, relations: node.relations })), assetRefs);
     telemetry.truncationCount = runtimeTelemetry.truncationCount ?? 0;
     telemetry.failureCount = runtimeTelemetry.failureCount ?? 0;
+    telemetry.htmlErrorCount = runtimeTelemetry.htmlErrorCount ?? 0;
+    telemetry.retryAttempts = runtimeTelemetry.retryAttempts ?? 0;
     const qualityConsidered = mergedNodes.length;
     const qualityExtracted = mergedNodes.filter((node) => node.status === "extracted" && node.entities.length > 0).length;
     const quality = computeGraphQualityTelemetry(qualityConsidered, qualityExtracted, deduped.entities.length, deduped.relations.length);