akm-cli 0.9.17-alpha.8 → 0.9.17

package/dist/setup/steps/connection.js

@@ -122,7 +122,8 @@ const LLM_PRESETS = [
     },
 ];
 /**
- * Step 3a: pick an LLM provider. Used for indexing-time metadata enhancement.
+ * Step 3a: pick an LLM provider. Used for LLM-gated background features
+ * (e.g. memory inference).
  *
  * @internal Exported for testing only.
  */
@@ -151,14 +152,14 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels, lmStudi
     }
     options.push({ value: "lmstudio", label: "LM Studio / local server", hint: lmStudioOptionHint(lmStudio) });
     options.push({ value: "custom", label: "Custom OpenAI-compatible endpoint" });
-    options.push({ value: "none", label: "Skip LLM", hint: "no metadata enhancement during indexing" });
+    options.push({ value: "none", label: "Skip LLM", hint: "LLM-gated background features stay disabled" });
     const currentLlm = readCurrentLlmEngine(current);
     if (currentLlm) {
         options.push(keepCurrentOption(currentLlm));
     }
     const initialValue = currentLlm ? "keep" : ollamaAvailable ? "ollama" : (LLM_PRESETS[0]?.value ?? "none");
     const choice = await prompt(() => p.select({
-        message: "Configure an LLM for richer metadata during indexing:",
+        message: "Configure an LLM for background features:",
         options,
         initialValue,
     }));
@@ -251,7 +252,7 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels, lmStudi
     return llm;
 }
 /**
- * Step 1/2: Configure the small model connection used for metadata and bounded LLM features.
+ * Step 1/2: Configure the small model connection used for bounded LLM features.
  *
  * Detects Ollama automatically and pre-selects it. The user may also choose
  * OpenAI, LM Studio, a custom endpoint, or skip the step entirely.
@@ -260,7 +261,6 @@ export async function stepSmallModelConnection(current) {
     p.log.step("Step 1/2: Configure your small model connection");
     p.note([
         "This connection is used for background processing:",
-        "  • akm index           (metadata enhancement)",
         "  • akm improve         (lesson distillation)",
         "  • akm remember --enrich (memory compression)",
     ].join("\n"));
@@ -301,7 +301,6 @@ export async function stepSmallModelConnection(current) {
     if (providerChoice === "skip") {
         p.note([
             "Enrichment features disabled:",
-            "  • akm index           — metadata enhancement disabled",
             "  • akm improve         — lesson generation",
             "  • akm remember --enrich",
             "",

package/dist/setup/steps/platforms.js

@@ -53,10 +53,10 @@ export function printCapabilitySummary(smallModelSkipped, agentConfigured) {
     const lines = ["Setup complete. Here's what's enabled:", ""];
     lines.push("  ✓ akm search, akm curate, akm show, akm index, akm remember — always available");
     if (!smallModelSkipped) {
-        lines.push("  ✓ index metadata enhancement, akm improve, akm remember --enrich — small model configured");
+        lines.push("  ✓ akm improve, akm remember --enrich — small model configured");
     }
     else {
-        lines.push("  ✗ index metadata enhancement, akm improve, akm remember --enrich — run `akm setup` to enable");
+        lines.push("  ✗ akm improve, akm remember --enrich — run `akm setup` to enable");
     }
     if (agentConfigured) {
         lines.push("  ✓ akm proposal new, akm improve, akm task — agent configured");

package/dist/sources/providers/git-stash.js

@@ -25,11 +25,18 @@ import { getCachePaths, parseGitRepoUrl } from "./git-provider.js";
 export function isGitBackedStash(stashDir) {
     return fs.existsSync(path.join(stashDir, ".git"));
 }
-/** Return repo-relative dirty/staged paths without changing the index. */
-export function listGitChangedPaths(repoDir) {
+/**
+ * Return repo-relative dirty/staged paths without changing the index, and
+ * whether `git status` itself succeeded. A broken submodule, a detached
+ * `GIT_DIR`, or git simply not being on `PATH` all exit nonzero here — a
+ * caller that would otherwise read the empty `paths` as "nothing is dirty"
+ * must check `ok` first (see {@link listGitChangedPaths}'s callers that
+ * cannot, and the archive purge sweep, which can and does).
+ */
+export function tryListGitChangedPaths(repoDir) {
     const result = runGit(["-C", repoDir, "status", "--porcelain", "-z", "--untracked-files=all"]);
     if (result.status !== 0)
-        return [];
+        return { paths: [], ok: false };
     const records = result.stdout.split("\0");
     const paths = [];
     for (let i = 0; i < records.length; i++) {
@@ -44,7 +51,79 @@ export function listGitChangedPaths(repoDir) {
                 paths.push(previousPath);
         }
     }
-    return paths;
+    return { paths, ok: true };
+}
+/** Return repo-relative dirty/staged paths without changing the index. `[]` on any git failure — see {@link tryListGitChangedPaths} for a caller that must tell that apart from "nothing is dirty". */
+export function listGitChangedPaths(repoDir) {
+    return tryListGitChangedPaths(repoDir).paths;
+}
+/**
+ * Return repo-relative paths git tracks at HEAD/index under `pathspec` (or
+ * the whole repo when omitted), and whether `git ls-files` itself
+ * succeeded — see {@link tryListGitChangedPaths}, the same contract.
+ */
+export function tryListGitTrackedPaths(repoDir, pathspec) {
+    const args = ["-C", repoDir, "ls-files", "-z"];
+    if (pathspec)
+        args.push("--", pathspec);
+    const result = runGit(args);
+    if (result.status !== 0)
+        return { paths: [], ok: false };
+    return { paths: result.stdout.split("\0").filter((record) => record.length > 0), ok: true };
+}
+/**
+ * Return repo-relative paths under `pathspec` that `git ls-files -v` tags as
+ * NOT verifiable against the worktree: `assume-unchanged` (a lowercase tag —
+ * `ls-files -v` lowercases a file's normal tag letter when that bit is set)
+ * or `skip-worktree` (the literal `S`). `git status` silently omits an edit
+ * to either kind of file — the index is telling git not to compare it — so a
+ * caller that trusts {@link tryListGitChangedPaths} alone would read a
+ * genuinely modified file as clean.
+ */
+export function tryListGitUnverifiablePaths(repoDir, pathspec) {
+    const args = ["-C", repoDir, "ls-files", "-v", "-z"];
+    if (pathspec)
+        args.push("--", pathspec);
+    const result = runGit(args);
+    if (result.status !== 0)
+        return { paths: [], ok: false };
+    const paths = [];
+    for (const record of result.stdout.split("\0")) {
+        if (!record)
+            continue;
+        const tag = record.slice(0, 1);
+        if (tag === "S" || (tag >= "a" && tag <= "z"))
+            paths.push(record.slice(2));
+    }
+    return { paths, ok: true };
+}
+/**
+ * The three-part git cleanliness check shared by the archive purge sweep
+ * (`purgeGracedArchive` in `commands/improve/memory/memory-improve.ts`) and
+ * the `memory-cleanup-archive` health advisory (`collectArchiveUsageAdvisory`
+ * in `commands/health/archive-usage.ts`): a path is safe to treat as
+ * committed only if it is tracked ({@link tryListGitTrackedPaths}), not dirty
+ * ({@link tryListGitChangedPaths}), and not assume-unchanged/skip-worktree
+ * ({@link tryListGitUnverifiablePaths} — those hide their own edits from
+ * `git status`, so an unverifiable file is never trusted as clean either).
+ *
+ * Each of the three git calls can fail independently (a broken submodule, or
+ * git missing from `PATH`); `ok` is `false` if any one does, and `isSafe`
+ * then returns `false` for every path rather than guessing — callers that
+ * need to short-circuit before doing other work still check `ok` themselves.
+ */
+export function checkGitPathSafety(repoDir, pathspec) {
+    const dirtyQuery = tryListGitChangedPaths(repoDir);
+    const trackedQuery = tryListGitTrackedPaths(repoDir, pathspec);
+    const unverifiableQuery = tryListGitUnverifiablePaths(repoDir, pathspec);
+    const ok = dirtyQuery.ok && trackedQuery.ok && unverifiableQuery.ok;
+    const dirty = new Set(dirtyQuery.paths);
+    const tracked = new Set(trackedQuery.paths);
+    const unverifiable = new Set(unverifiableQuery.paths);
+    return {
+        ok,
+        isSafe: (repoRelativePath) => ok && tracked.has(repoRelativePath) && !dirty.has(repoRelativePath) && !unverifiable.has(repoRelativePath),
+    };
 }
 export class GitStashPushError extends Error {
     commit;

package/dist/storage/repositories/improve-ledger-repository.js

@@ -27,6 +27,17 @@ export const LEDGER_DEFAULT_REJECTION_WINDOW_DAYS = 7;
 export const LEDGER_EXPIRED_GRACE_DAYS = 1;
 /** Revisit cadence for a ref the stage looked at and had nothing to do (or is still pending). */
 export const LEDGER_REVISIT_CADENCE_DAYS = 7;
+/**
+ * The consolidate pair pass's own ledger source (alpha.9): kept apart from
+ * the promote pass's `consolidate` rows so the two candidate-selection
+ * cadences never collide on the same `(stash, ref, source)` key. Its
+ * eligibility is entirely content-driven (`content_hash` above, compared by
+ * `selectInitiators` in `src/commands/improve/consolidate/pair-pass.ts`) —
+ * {@link windowDays} below gives it no `next_eligible_at` timer at all, so a
+ * row never "expires" on its own; only a content change makes the ref
+ * eligible again.
+ */
+export const PAIR_PASS_LEDGER_SOURCE = "consolidate-pair";
 /**
  * Outcomes whose window a fresh signal on the asset (new feedback, a content
  * change) cannot lift. Every other window is a revisit cadence that a signal
@@ -38,6 +49,12 @@ export const LEDGER_HARD_OUTCOMES = new Set([
     "expired",
 ]);
 function windowDays(source, outcome) {
+    // The pair pass's own eligibility never reads next_eligible_at (it compares
+    // content_hash instead — selectInitiators in pair-pass.ts) — recording a
+    // window here would be a number nothing enforces, so every row it writes
+    // stays "eligible now" regardless of outcome.
+    if (source === PAIR_PASS_LEDGER_SOURCE)
+        return null;
     switch (outcome) {
         case "rejected":
         case "quality_rejected":
@@ -91,6 +108,7 @@ function toRow(row) {
         nextEligibleAt: row.next_eligible_at,
         proposalId: row.proposal_id,
         detail: row.detail,
+        contentHash: row.content_hash,
     };
 }
 function trimDetail(detail) {
@@ -112,16 +130,18 @@ export function recordImproveLedger(db, input) {
         nextEligibleAt: nextEligibleAt(input.source, input.outcome, input.at),
         proposalId: input.proposalId ?? null,
         detail: trimDetail(input.detail),
+        contentHash: input.contentHash ?? null,
     };
     db.prepare(`INSERT INTO improve_ledger
-       (stash_dir, ref, source, last_attempt_at, outcome, next_eligible_at, proposal_id, detail)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       (stash_dir, ref, source, last_attempt_at, outcome, next_eligible_at, proposal_id, detail, content_hash)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
      ON CONFLICT(stash_dir, ref, source) DO UPDATE SET
        last_attempt_at  = excluded.last_attempt_at,
        outcome          = excluded.outcome,
        next_eligible_at = excluded.next_eligible_at,
        proposal_id      = excluded.proposal_id,
-       detail           = excluded.detail`).run(row.stashDir, row.ref, row.source, row.lastAttemptAt, row.outcome, row.nextEligibleAt, row.proposalId, row.detail);
+       detail           = excluded.detail,
+       content_hash     = excluded.content_hash`).run(row.stashDir, row.ref, row.source, row.lastAttemptAt, row.outcome, row.nextEligibleAt, row.proposalId, row.detail, row.contentHash);
     return row;
 }
 /**
@@ -150,19 +170,40 @@ export function recordImproveLedgerDecision(db, input) {
         ...(input.detail !== undefined ? { detail: input.detail } : {}),
     });
 }
+/**
+ * Should-fix 6 (second review round): a read-only or dry-run open never
+ * migrates, so it can land on a state.db from before migration 029 added
+ * `content_hash` — reading it there threw "no such column", which
+ * `loadRetrievalScope`'s own catch then reported as "usage history
+ * unreadable", making the WHOLE scope `undefined` (every asset eligible) on
+ * every read-only/dry-run call against an as-yet-unmigrated database. A
+ * per-connection cache, since a real `Database` handle's schema does not
+ * change mid-lifetime and this is checked on every ledger read.
+ */
+const hasContentHashColumnCache = new WeakMap();
+function hasContentHashColumn(db) {
+    const cached = hasContentHashColumnCache.get(db);
+    if (cached !== undefined)
+        return cached;
+    const has = db.prepare("PRAGMA table_info(improve_ledger)").all().some((c) => c.name === "content_hash");
+    hasContentHashColumnCache.set(db, has);
+    return has;
+}
 export function getImproveLedgerRow(db, stashDir, ref, source) {
+    const withHash = hasContentHashColumn(db);
     const row = db
-        .prepare(`SELECT stash_dir, ref, source, last_attempt_at, outcome, next_eligible_at, proposal_id, detail
+        .prepare(`SELECT stash_dir, ref, source, last_attempt_at, outcome, next_eligible_at, proposal_id, detail${withHash ? ", content_hash" : ""}
        FROM improve_ledger WHERE stash_dir = ? AND ref = ? AND source = ?`)
         .get(stashDir, ref, source);
-    return row ? toRow(row) : undefined;
+    return row ? toRow(withHash ? row : { ...row, content_hash: null }) : undefined;
 }
 /** Every row for one stash, optionally narrowed to `sources`. */
 export function listImproveLedgerRows(db, stashDir, sources) {
+    const withHash = hasContentHashColumn(db);
     const sourceFilter = sources && sources.length > 0 ? ` AND source IN (${sources.map(() => "?").join(", ")})` : "";
     const rows = db
-        .prepare(`SELECT stash_dir, ref, source, last_attempt_at, outcome, next_eligible_at, proposal_id, detail
+        .prepare(`SELECT stash_dir, ref, source, last_attempt_at, outcome, next_eligible_at, proposal_id, detail${withHash ? ", content_hash" : ""}
        FROM improve_ledger WHERE stash_dir = ?${sourceFilter} ORDER BY ref ASC, source ASC`)
         .all(stashDir, ...(sources && sources.length > 0 ? sources : []));
-    return rows.map(toRow);
+    return rows.map((row) => toRow(withHash ? row : { ...row, content_hash: null }));
 }

package/dist/storage/repositories/index-connection.js

@@ -180,9 +180,12 @@ export function openReadonlyExistingDatabase(dbPath, options) {
     // never block — but in the DELETE/TRUNCATE modes the network-FS fallback and
     // AKM_SQLITE_JOURNAL_MODE can select, a concurrent writer makes every read
     // fail instantly with SQLITE_BUSY. busy_timeout is legal on a read-only
-    // connection, so apply just that one.
+    // connection, so apply just that one. `busyTimeoutMs` defaults to the
+    // shared 30s constant; a caller that must never sit behind another akm
+    // process's write lock for long (e.g. `akm info`) can pass a much shorter
+    // bound instead.
     try {
-        db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+        db.exec(`PRAGMA busy_timeout = ${options?.busyTimeoutMs ?? SQLITE_BUSY_TIMEOUT_MS}`);
         checkIndexLayout(db, resolvedPath);
         return db;
     }

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

@@ -50,8 +50,8 @@ export function upsertEntry(db, filePath, entry, provenance, contentHash) {
     // does not have to scan + JSON-decode every memory row.
     const derivedFrom = typeof entry.derivedFrom === "string" && entry.derivedFrom.trim() ? entry.derivedFrom.trim() : null;
     const hash = embedHash(entry);
-    // `content_hash` is optional on the LLM-enrichment re-upsert; a missing hash
-    // preserves the scan writer's current value.
+    // `content_hash` is optional; an upsert that omits it preserves the scan
+    // writer's current value.
     const apply = () => {
         const previous = stmts.findByItemRef.get(provenance.itemRef);
         const result = stmts.upsert.get(provenance.itemRef, provenance.bundleId, provenance.componentId, provenance.conceptId, provenance.adapterId, entry.type, filePath, contentHash ?? null, JSON.stringify(entry), derivedFrom, hash);
@@ -70,8 +70,8 @@ export function upsertEntry(db, filePath, entry, provenance, contentHash) {
     return db.transaction(apply)();
 }
 const upsertStmtsByDb = new WeakMap();
-// item_ref is the sole durable conflict target. `content_hash` COALESCEs so a
-// metadata-only enrichment pass cannot wipe a scan hash.
+// item_ref is the sole durable conflict target. `content_hash` COALESCEs so
+// an upsert that omits it (`contentHash` is optional) cannot wipe a scan hash.
 const UPSERT_SET_CLAUSE = `SET
         bundle_id = excluded.bundle_id,
         component_id = excluded.component_id,
@@ -418,9 +418,6 @@ function deleteRelatedRows(db, ids, options = {}) {
     // commits; standalone delete callers retain the immediate behavior.
     if (options.cleanupUsageEvents !== false)
         deleteUsageEventsByEntryIds(numericIds);
-    // graph_files is keyed by its own stash_root/file_path/body_hash identity,
-    // so deleting an entry row intentionally leaves extracted graph data intact,
-    // and with it the graph_meta counts the graph writer derives from those rows.
 }
 export function deleteUsageEventsByEntryIds(entryIds) {
     if (entryIds.length === 0 || !fs.existsSync(getStateDbPath()))

package/dist/storage/repositories/index-entry-schema.js

@@ -8,8 +8,10 @@
  * readers serve what is there, and the writable opener (`ensureSchema`,
  * `index-schema.ts`) brings it up to date in place — added and dropped
  * columns, retired tables dropped, a one-time full-text rebuild — without
- * touching embeddings, utility scores, graph rows, or the LLM enrichment
- * cache. A newer layout is refused, naming the upgrade.
+ * touching embeddings, utility scores, or the LLM enrichment cache (the one
+ * exception is the LLM entity graph, unconditionally dropped since its
+ * retirement in 0.9.17-alpha.9). A newer layout is refused, naming the
+ * upgrade.
  */
 // 26: declared links (#935) live in `asset_links`, one row per link, owned by
 // the entry that declares it. The writable opener derives them in place from

package/dist/storage/repositories/index-llm-cache-repository.js

@@ -4,11 +4,11 @@
 /**
  * `index.db` LLM enrichment-cache repository.
  *
- * Owns the raw SQL for `llm_enrichment_cache` — the body-hash-keyed cache that
- * lets `akm index --enrich` skip the LLM call when a file's body is unchanged.
+ * Owns the raw SQL for `llm_enrichment_cache` — the body-hash-keyed cache the
+ * graph-extraction and memory-inference passes use to skip an LLM call when
+ * a file's body is unchanged.
  */
 import { sha256Hex } from "../../runtime.js";
-import { escapeLikePattern } from "../like-pattern.js";
 import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
 /**
  * Look up a cached LLM result for the given asset_ref.
@@ -18,7 +18,7 @@ import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
  * cached). In both cases the caller should invoke the LLM and write a new
  * cache entry.
  */
-export function getLlmCacheEntry(db, assetRef, currentBodyHash, cacheVariant = "") {
+export function getLlmCacheEntry(db, assetRef, currentBodyHash, cacheVariant) {
     const row = db
         .prepare("SELECT asset_ref, cache_variant, body_hash, result_json, updated_at FROM llm_enrichment_cache WHERE asset_ref = ? AND cache_variant = ?")
         .get(assetRef, cacheVariant);
@@ -44,7 +44,7 @@ export function getLlmCacheEntry(db, assetRef, currentBodyHash, cacheVariant = "
  * compare `entry.bodyHash` against the current body hash themselves. This lets
  * the batch path issue one DB query per chunk instead of one per file.
  */
-export function getLlmCacheEntriesByRefs(db, refs, cacheVariant = "") {
+export function getLlmCacheEntriesByRefs(db, refs, cacheVariant) {
     const result = new Map();
     if (refs.length === 0)
         return result;
@@ -70,7 +70,7 @@ export function getLlmCacheEntriesByRefs(db, refs, cacheVariant = "") {
 /**
  * Insert or update a cached LLM result for the given asset_ref.
  */
-export function upsertLlmCacheEntry(db, assetRef, bodyHash, resultJson, cacheVariant = "") {
+export function upsertLlmCacheEntry(db, assetRef, bodyHash, resultJson, cacheVariant) {
     db.prepare(`INSERT INTO llm_enrichment_cache (asset_ref, cache_variant, body_hash, result_json, updated_at)
      VALUES (?, ?, ?, ?, ?)
      ON CONFLICT(asset_ref, cache_variant) DO UPDATE SET
@@ -83,33 +83,14 @@ export function upsertLlmCacheEntry(db, assetRef, bodyHash, resultJson, cacheVar
  * `entries` table. Should be called during the cleanup phase of each index
  * run to prevent the cache from growing unboundedly as assets are removed.
  *
- * Graph/memory cache refs are absolute file paths, while metadata-enrichment
- * refs use canonical `item_ref`; preserve a cache row that matches either
- * current identity.
+ * Cache refs are absolute file paths (memory inference).
  */
 export function clearStaleCacheEntries(db) {
     db.exec(`
     DELETE FROM llm_enrichment_cache
     WHERE asset_ref NOT IN (SELECT file_path FROM entries)
-      AND asset_ref NOT IN (SELECT item_ref FROM entries)
   `);
 }
-/**
- * Rewrite every `llm_enrichment_cache.asset_ref` naming `oldBundleId` (a
- * metadata-enrichment cache key, the canonical `<bundle>//conceptId` form of
- * `entries.item_ref`) to `newBundleId` (`akm bundle rename`, D6). Must run in
- * the same `index.db` write as `renameEntriesBundleId` — otherwise the next
- * `akm index`'s {@link clearStaleCacheEntries} deletes every row still keyed
- * to the old bundle, forcing a full LLM re-enrichment. A graph/memory cache
- * row (keyed by absolute file path, not `item_ref`) never matches the `//`
- * prefix and is left alone. Returns the number of rows rewritten.
- */
-export function renameLlmCacheAssetRefs(db, oldBundleId, newBundleId) {
-    const prefix = `${escapeLikePattern(oldBundleId)}//`;
-    return Number(db
-        .prepare(`UPDATE llm_enrichment_cache SET asset_ref = ? || substr(asset_ref, ?) WHERE asset_ref LIKE ? ESCAPE '\\'`)
-        .run(newBundleId, oldBundleId.length + 1, `${prefix}%`).changes);
-}
 /**
  * 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

package/dist/storage/repositories/index-schema.js

@@ -10,12 +10,15 @@
  * for columns added after a table first shipped, drops of retired derived
  * tables and columns, and one in-place rebuild of the (derived, cheap) FTS
  * table when its layout is older than this release's. It never drops
- * `entries`, `embeddings`, `utility_scores`, the extracted graph
- * (`graph_meta`, `graph_files`, `graph_file_*`), or `llm_enrichment_cache`
- * to cross a version boundary; the only from-scratch
- * rebuild is the SQLITE_CORRUPT path in `index-connection.ts`. A layout newer
- * than this release's is refused, naming the upgrade
- * ({@link newerIndexLayoutError}).
+ * `entries`, `embeddings`, `utility_scores`, or `llm_enrichment_cache` to
+ * cross a version boundary; the only from-scratch rebuild is the
+ * SQLITE_CORRUPT path in `index-connection.ts`. A layout newer than this
+ * release's is refused, naming the upgrade ({@link newerIndexLayoutError}).
+ * The one exception is the LLM entity graph (`graph_meta`, `graph_files`,
+ * `graph_file_*`), retired in 0.9.17-alpha.9: those tables are dropped
+ * unconditionally below (index.db is a regenerable cache, and declared links
+ * — `asset_links` — now back `akm show`'s `links` field, which replaced the
+ * graph's `related` list).
  */
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -30,12 +33,6 @@ import { getMeta, setMeta } from "./index-meta-repository.js";
 export const DB_VERSION = CANONICAL_INDEX_DB_VERSION;
 /** `index_meta` key set when the writable opener migrated the layout; cleared once `akm index` VACUUMs. */
 export const VACUUM_PENDING_META = "vacuumPending";
-/**
- * The value written to `graph_meta.schema_version`, a NOT NULL column in every
- * released layout. Releases up to 0.9.17-alpha.5 write 4 and nothing ever
- * compares it; the index layout version gates the graph tables' shape.
- */
-export const GRAPH_SCHEMA_VERSION = 4;
 /** The layout that added declared links (`asset_links`, #935). */
 const DECLARED_LINKS_LAYOUT = 26;
 /**
@@ -69,97 +66,15 @@ const REGISTRY_INDEX_CACHE_DDL = `
   CREATE INDEX IF NOT EXISTS idx_registry_cache_fetched
     ON registry_index_cache(fetched_at);
 `;
-/**
- * Create the graph-extraction tables (`graph_meta`/`graph_files`/`graph_file_entities`/
- * `graph_file_relations`).
- *
- * graph_files is self-keyed on (stash_root, file_path, body_hash) and is not
- * tied to entries.id (#624-P1): re-upserting an entries row never disturbs the
- * extracted graph, and a content change yields a distinct key. A UNIQUE index
- * on (stash_root, file_path) still enforces one graph_files row per path.
- */
-function ensureGraphTables(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS graph_meta (
-      stash_root          TEXT PRIMARY KEY,
-      schema_version      INTEGER NOT NULL,
-      generated_at        TEXT NOT NULL,
-      considered_files    INTEGER NOT NULL DEFAULT 0,
-      extracted_files     INTEGER NOT NULL DEFAULT 0,
-      entity_count        INTEGER NOT NULL DEFAULT 0,
-      relation_count      INTEGER NOT NULL DEFAULT 0,
-      extraction_coverage REAL NOT NULL DEFAULT 0,
-      density             REAL NOT NULL DEFAULT 0,
-      extractor_id        TEXT,
-      extraction_run_id   TEXT,
-      model               TEXT,
-      prompt_version      TEXT,
-      batch_size          INTEGER,
-      cache_hits          INTEGER NOT NULL DEFAULT 0,
-      cache_misses        INTEGER NOT NULL DEFAULT 0,
-      truncation_count    INTEGER NOT NULL DEFAULT 0,
-      failure_count       INTEGER NOT NULL DEFAULT 0
-    );
-
-    CREATE TABLE IF NOT EXISTS graph_files (
-      stash_root        TEXT NOT NULL,
-      file_path         TEXT NOT NULL,
-      file_order        INTEGER NOT NULL,
-      file_type         TEXT NOT NULL,
-      body_hash         TEXT NOT NULL,
-      confidence        REAL,
-      status            TEXT NOT NULL DEFAULT 'extracted',
-      reason            TEXT,
-      extraction_run_id TEXT,
-      PRIMARY KEY (stash_root, file_path, body_hash)
-    );
-
-    CREATE UNIQUE INDEX IF NOT EXISTS idx_graph_files_path
-      ON graph_files(stash_root, file_path);
-
-    CREATE INDEX IF NOT EXISTS idx_graph_files_stash_order
-      ON graph_files(stash_root, file_order);
-
-    CREATE TABLE IF NOT EXISTS graph_file_entities (
-      stash_root   TEXT NOT NULL,
-      file_path    TEXT NOT NULL,
-      body_hash    TEXT NOT NULL,
-      entity_order INTEGER NOT NULL,
-      entity_norm  TEXT NOT NULL,
-      entity       TEXT NOT NULL,
-      PRIMARY KEY (stash_root, file_path, body_hash, entity_order),
-      FOREIGN KEY (stash_root, file_path, body_hash)
-        REFERENCES graph_files(stash_root, file_path, body_hash) ON DELETE CASCADE
-    );
-
-    CREATE INDEX IF NOT EXISTS idx_graph_file_entities_entity_norm
-      ON graph_file_entities(stash_root, entity_norm);
-
-    CREATE TABLE IF NOT EXISTS graph_file_relations (
-      stash_root     TEXT NOT NULL,
-      file_path      TEXT NOT NULL,
-      body_hash      TEXT NOT NULL,
-      relation_order INTEGER NOT NULL,
-      from_entity_norm TEXT NOT NULL,
-      from_entity    TEXT NOT NULL,
-      to_entity_norm TEXT NOT NULL,
-      to_entity      TEXT NOT NULL,
-      relation_type  TEXT,
-      confidence     REAL,
-      PRIMARY KEY (stash_root, file_path, body_hash, relation_order),
-      FOREIGN KEY (stash_root, file_path, body_hash)
-        REFERENCES graph_files(stash_root, file_path, body_hash) ON DELETE CASCADE
-    );
-  `);
-}
 /**
  * An `entries` table missing a required column cannot be read or written by
  * this release (the last such change was v20→v21, which removed the
  * transitional `entry_key`/`dir_path`/... columns and made `item_ref` the
  * key). Recreate only the tables keyed by `entries.id` — their ids are about
- * to be re-minted, so the rows would dangle anyway. Graph rows (keyed by
- * path) and the LLM enrichment cache (keyed by ref) are kept. The next index
- * run re-walks every source.
+ * to be re-minted, so the rows would dangle anyway. The LLM enrichment cache
+ * (keyed by ref) is kept. The LLM entity-graph tables are unconditionally
+ * dropped elsewhere in this file regardless of this recreation (retired
+ * 0.9.17-alpha.9), not kept. The next index run re-walks every source.
  */
 function ensureEntriesLayout(db) {
     if (!tableExists(db, "entries"))
@@ -168,8 +83,8 @@ function ensureEntriesLayout(db) {
     if (missing.length === 0)
         return;
     warn(`Index database entries table predates the ${missing.join(", ")} column${missing.length === 1 ? "" : "s"} — ` +
-        "recreating the entries-keyed tables (entries, full-text, embeddings, utility scores); graph data and the " +
-        "LLM enrichment cache are kept. The next index run re-walks every source.");
+        "recreating the entries-keyed tables (entries, full-text, embeddings, utility scores); the " +
+        "LLM enrichment cache is kept. The next index run re-walks every source.");
     db.transaction(() => {
         for (const table of [
             "entries_fts",
@@ -246,7 +161,7 @@ function ensureFtsLayout(db) {
     const entryCount = Number(db.prepare("SELECT COUNT(*) AS n FROM entries").get().n);
     if (entryCount > 0) {
         warn(`Rebuilding the full-text index for ${entryCount} entr${entryCount === 1 ? "y" : "ies"} ` +
-            "(embeddings, utility scores, graph data and the LLM enrichment cache are kept).");
+            "(embeddings, utility scores, and the LLM enrichment cache are kept).");
     }
     db.transaction(() => {
         db.exec("DROP TABLE IF EXISTS entries_fts");
@@ -311,6 +226,25 @@ export function ensureSchema(db) {
     db.exec("DROP TABLE IF EXISTS entry_fragments_fts");
     db.exec("DROP TABLE IF EXISTS utility_scores_scoped");
     db.exec("DROP TABLE IF EXISTS graph_extraction_queue");
+    // The LLM entity graph, retired in 0.9.17-alpha.9: declared links
+    // (`asset_links`) now back `akm show`'s `links` field (which replaced the
+    // graph's `related` list) and curate's support refs (#935), and the
+    // navigation eval measured vector kNN beating the graph's `related` list
+    // by 0.157 P@5. `graph_files` stands in for the whole set — all four
+    // tables are only ever created and dropped together. Gated on it (rather
+    // than the unconditional `DROP TABLE IF EXISTS` pattern used above) so
+    // this reclaim runs once: after the first writable open drops these
+    // tables, every later open finds `graph_files` already gone and skips the
+    // no-op DROPs and the repeat VACUUM flag below. An older release's
+    // `CREATE TABLE IF NOT EXISTS` still recreates them (empty) if it ever
+    // opens this index again — a later open here would then drop them again.
+    const hadGraphTables = tableExists(db, "graph_files");
+    if (hadGraphTables) {
+        db.exec("DROP TABLE IF EXISTS graph_meta");
+        db.exec("DROP TABLE IF EXISTS graph_files");
+        db.exec("DROP TABLE IF EXISTS graph_file_entities");
+        db.exec("DROP TABLE IF EXISTS graph_file_relations");
+    }
     // One float32 BLOB per entry, searched by an exact scan
     // (index-vec-repository.ts). `model` is the provider fingerprint the vector was generated under
     // (`deriveSemanticProviderFingerprint`); the embedding pass re-embeds only
@@ -363,8 +297,8 @@ export function ensureSchema(db) {
     ensureColumn(db, "index_dir_state", "row_count", "INTEGER");
     ensureColumn(db, "index_dir_state", "index_variant", "TEXT");
     // LLM enrichment result cache, keyed by a stable asset_ref string (the
-    // absolute file path for graph/memory passes, `item_ref` for the
-    // metadata-enhance pass) plus the body hash the result was produced for.
+    // absolute file path of the memory-inference pass) plus the body hash the
+    // result was produced for.
     db.exec(`
     CREATE TABLE IF NOT EXISTS llm_enrichment_cache (
       asset_ref     TEXT NOT NULL,
@@ -378,7 +312,24 @@ export function ensureSchema(db) {
      CREATE INDEX IF NOT EXISTS idx_llm_cache_updated
        ON llm_enrichment_cache(updated_at);
   `);
-    ensureGraphTables(db);
+    // Metadata-enhance retired (RS-D, 0.9.17-alpha.9): its rows were the only
+    // ones keyed by the default empty cache_variant (memory inference writes
+    // `memory-inference-v2`), so this is safe to run unconditionally on every
+    // writable open. The table
+    // itself stays — memory inference still reads it.
+    db.exec("DELETE FROM llm_enrichment_cache WHERE cache_variant = ''");
+    // The graph-extraction cache variant is retired along with the tables
+    // above; its rows would otherwise sit unread forever. Gated the same way,
+    // on the same one-time flag, so a rerun does not re-scan the cache table
+    // for rows that are already gone.
+    if (hadGraphTables) {
+        db.exec("DELETE FROM llm_enrichment_cache WHERE cache_variant LIKE 'graph-extraction:%'");
+        // The drops and delete above freed real space (measured ~68MB on a
+        // representative index): flag it the same way a version-gated layout
+        // migration does, since this reclaim is unconditional-on-version but
+        // still one-time-per-index (guarded by hadGraphTables above).
+        setMeta(db, VACUUM_PENDING_META, "1");
+    }
     dropVecMirror(db);
     // Meta keys only the sqlite-vec mirror read.
     db.exec("DELETE FROM index_meta WHERE key IN ('embeddingDim', 'vecFastPathReady')");