akm-cli 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -6,6 +6,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.7.3] - 2026-05-05
+
+### Added
+
+- **`akm index --enrich` opt-in for LLM passes** — index-time enrichment work such as metadata enhancement, memory inference, and graph extraction now runs only when explicitly requested with `--enrich`. Default indexing is faster and no longer surprises operators with LLM-backed work during normal maintenance runs.
+- **Config backup snapshots before writes** — config writes now create AKM cache backups so setup/config flows have a recovery path if a config is overwritten or corrupted during development or testing.
+
+### Changed
+
+- **Setup wizard UX refresh** — `akm setup` now better reflects the real configured state: source prompts are ordered more sensibly, configured and preserved stash information is surfaced, agent defaults can be selected explicitly (including disabled), and post-setup indexing does not implicitly enable enrichment.
+- **CI workflows updated for current GitHub Actions runtimes** — CI, release, and publishing workflows now use current action majors (`checkout@v5`, `cache@v5`, `setup-node@v5`, `upload-artifact@v5`, `download-artifact@v6`) to stay off deprecated Node 20 action runtimes.
+- **Technical investigation notes updated** — the index investigation note now reflects the latest `.stash.json` migration status, current green CI runs, and the narrowed remaining compatibility surface ahead of `v0.8.0`.
+
+### Fixed
+
+- **Embedding-dimension drift on read-only DB opens** — read/telemetry paths no longer mutate the live index schema with the default embedding dimension. `akm info`, search/show parity paths, and related readers now preserve the configured embedding shape instead of downgrading vector tables.
+- **Incremental index churn across multiple source layouts** — incremental indexing is now significantly more stable for filename-less legacy metadata, wiki-root sources, repo-root git stash layouts, non-indexed companion files, and cross-source dedupe cases.
+- **Git source indexing for repo-root stashes** — git-backed sources no longer assume a `<repo>/content` subtree; repo-root stash layouts are indexed correctly and cached mirrors are treated as fresh instead of being needlessly refreshed.
+- **`show` metadata no longer depends on `.stash.json`** — command and skill summary/show metadata now comes from file-local frontmatter and renderer parsing rather than the deprecated disk fallback sidecar.
+- **`.stash.json` no longer drives incremental stale detection** — editing `.stash.json` alone no longer forces directories to rescan during incremental indexing.
+
+### Internal
+
+- **Ranking and scoring fixtures migrated toward file-local metadata** — routine benchmark and regression fixtures now prefer markdown frontmatter or inline script metadata, with `.stash.json` retained only for intentional legacy-compatibility coverage that still exercises explicit-file override behavior.
+- **Production-path ranking regression coverage** — ranking regression tests now build their fixture index through the production indexer rather than a custom `.stash.json` crawler, reducing fixture drift and improving confidence in the real indexing/search path.
+
 ### Added
 
 - **One-shot URL ingest for `akm import` and `akm wiki stash`** — both commands now accept a single HTTP/HTTPS URL in addition to file paths and stdin. `akm import <url>` fetches the exact page, converts it to markdown, and writes it into `knowledge/` using a URL-path-derived default name. `akm wiki stash <wiki> <url>` fetches the exact page, converts it to markdown, and writes it into `wikis/<wiki>/raw/`. Neither command registers a persistent website source or crawls linked pages.
@@ -13,6 +39,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 
 - **Shared website ingest boundary** — website URL validation, single-page fetch/convert, and website mirror generation now live in a dedicated shared ingest module. The website source provider is a thin adapter, and `akm add`, `akm import`, and `akm wiki stash` all reuse the same core website-ingest path.
+- **`.stash.json` docs deprecation timeline** — the docs now explicitly state that `.stash.json` is deprecated, remains only as a 0.7.x compatibility bridge, and will be removed in v0.8.0 to match the current aggressive pre-release phase-out posture.
 
 ## [0.7.0]
 

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import fs from "node:fs";
 import path from "node:path";
+import * as p from "@clack/prompts";
 import { defineCommand, runMain } from "citty";
 import { generateBashCompletions, installBashCompletions } from "./commands/completions";
 import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from "./commands/config-cli";
@@ -32,7 +33,7 @@ import { appendEvent } from "./core/events";
 import { getCacheDir, getDbPath, getDefaultStashDir } from "./core/paths";
 import { setQuiet, setVerbose, warn } from "./core/warn";
 import { resolveWriteTarget, writeAssetToSource } from "./core/write-source";
-import { closeDatabase, findEntryIdByRef, openDatabase } from "./indexer/db";
+import { closeDatabase, findEntryIdByRef, openExistingDatabase } from "./indexer/db";
 import { akmIndex } from "./indexer/indexer";
 import { resolveSourceEntries } from "./indexer/search-source";
 import { insertUsageEvent } from "./indexer/usage-events";
@@ -139,22 +140,53 @@ const indexCommand = defineCommand({
     meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
     args: {
         full: { type: "boolean", description: "Force full reindex", default: false },
-        verbose: { type: "boolean", description: "Print indexing summary and phase progress to stderr", default: false },
+        enrich: { type: "boolean", description: "Enable LLM inference and enrichment passes", default: false },
+        verbose: { type: "boolean", description: "Print phase-by-phase indexing progress to stderr", default: false },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            const outputMode = getOutputMode();
             const controller = new AbortController();
             const abort = () => controller.abort(new Error("index interrupted"));
             process.once("SIGINT", abort);
             process.once("SIGTERM", abort);
-            const result = await akmIndex({
-                full: args.full,
-                onProgress: args.verbose ? ({ message }) => console.error(`[index] ${message}`) : undefined,
-                signal: controller.signal,
-            });
-            process.off("SIGINT", abort);
-            process.off("SIGTERM", abort);
-            output("index", result);
+            const spin = !args.verbose && outputMode.format === "text" ? p.spinner() : null;
+            if (spin) {
+                spin.start(`Building search index${args.full ? " (full rebuild)" : ""}...`);
+            }
+            let latestMessage = "";
+            try {
+                const result = await akmIndex({
+                    full: args.full,
+                    enrich: args.enrich,
+                    onProgress: ({ message, processed, total }) => {
+                        latestMessage = message;
+                        const progressPrefix = processed !== undefined && total !== undefined ? `[${processed}/${total}] ` : "";
+                        if (args.verbose) {
+                            console.error(`[index] ${progressPrefix}${message}`);
+                        }
+                        else if (spin) {
+                            spin.stop(`${progressPrefix}${message}`);
+                            spin.start(`${progressPrefix}${message}`);
+                        }
+                    },
+                    signal: controller.signal,
+                });
+                if (spin) {
+                    spin.stop(`Indexed ${result.totalEntries} assets.`);
+                }
+                output("index", result);
+            }
+            catch (error) {
+                if (spin) {
+                    spin.stop(latestMessage ? `Indexing failed after: ${latestMessage}` : "Indexing failed.");
+                }
+                throw error;
+            }
+            finally {
+                process.off("SIGINT", abort);
+                process.off("SIGTERM", abort);
+            }
         });
     },
 });
@@ -947,7 +979,7 @@ const feedbackCommand = defineCommand({
             }
             const signal = args.positive ? "positive" : "negative";
             const metadata = args.note ? JSON.stringify({ note: args.note }) : undefined;
-            const db = openDatabase();
+            const db = openExistingDatabase();
             try {
                 const entryId = findEntryIdByRef(db, ref);
                 if (entryId === undefined) {

package/dist/commands/history.js

@@ -16,8 +16,7 @@
 import { parseAssetRef } from "../core/asset-ref";
 import { UsageError } from "../core/errors";
 import { readEvents } from "../core/events";
-import { closeDatabase, openDatabase } from "../indexer/db";
-import { ensureUsageEventsSchema } from "../indexer/usage-events";
+import { closeDatabase, openExistingDatabase } from "../indexer/db";
 // Proposal lifecycle event types emitted by the proposal substrate (#225).
 const PROPOSAL_EVENT_TYPES = new Set(["promoted", "rejected"]);
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -106,13 +105,9 @@ export async function akmHistory(options = {}) {
         normalizedRef = trimmed;
     }
     const sinceNormalized = options.since !== undefined ? normalizeSince(options.since) : undefined;
-    const db = options.db ?? openDatabase();
+    const db = options.db ?? openExistingDatabase();
     const ownsDb = options.db === undefined;
     try {
-        // The schema is normally created during `akm index`; ensure it exists so
-        // `akm history` works on a freshly-initialised stash that has never been
-        // indexed (and just returns an empty list rather than an error).
-        ensureUsageEventsSchema(db);
         const conditions = [];
         const params = [];
         if (normalizedRef !== undefined) {

package/dist/commands/info.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import { getAssetTypes } from "../core/asset-spec";
 import { loadConfig } from "../core/config";
 import { getDbPath } from "../core/paths";
-import { closeDatabase, getEntryCount, getMeta, isVecAvailable, openDatabase } from "../indexer/db";
+import { closeDatabase, getEntryCount, getMeta, isVecAvailable, openExistingDatabase } from "../indexer/db";
 import { getEffectiveSemanticStatus, readSemanticStatus } from "../indexer/semantic-status";
 import { pkgVersion } from "../version";
 /**
@@ -74,7 +74,7 @@ function readIndexStats(dbPath) {
     }
     let db;
     try {
-        db = openDatabase(resolvedPath);
+        db = openExistingDatabase(resolvedPath);
         const entryCount = getEntryCount(db);
         const lastBuiltAt = getMeta(db, "builtAt") ?? null;
         const vecAvailable = isVecAvailable(db);

package/dist/commands/installed-stashes.js

@@ -12,6 +12,7 @@ import { NotFoundError, UsageError } from "../core/errors";
 import { akmIndex } from "../indexer/indexer";
 import { removeLockEntry, upsertLockEntry } from "../integrations/lockfile";
 import { parseRegistryRef } from "../registry/resolve";
+import { parseGitRepoUrl, syncMirroredRepo } from "../sources/providers/git";
 import { syncFromRef } from "../sources/providers/sync-from-ref";
 import { ensureWebsiteMirror } from "../sources/website-ingest";
 import { listWikis, resolveWikisRoot } from "../wiki/wiki";
@@ -173,6 +174,49 @@ export async function akmUpdate(input) {
         const stashes = config.sources ?? config.stashes ?? [];
         const isUrl = target.startsWith("http://") || target.startsWith("https://");
         const resolvedPath = !isUrl ? path.resolve(target) : undefined;
+        const gitMatch = stashes.find((s) => {
+            if (s.type !== "git")
+                return false;
+            if (isUrl && s.url === target)
+                return true;
+            if (resolvedPath && s.path && path.resolve(s.path) === resolvedPath)
+                return true;
+            if (s.name === target)
+                return true;
+            if (s.url) {
+                try {
+                    const repo = parseGitRepoUrl(s.url);
+                    if (repo.canonicalUrl === target)
+                        return true;
+                }
+                catch {
+                    // Ignore malformed config here; later provider sync will surface it.
+                }
+            }
+            return false;
+        });
+        if (gitMatch) {
+            await syncMirroredRepo(gitMatch, { force: true, writable: gitMatch.writable === true });
+            const index = await akmIndex({ stashDir, full: true });
+            const updatedConfig = loadConfig();
+            return {
+                schemaVersion: 1,
+                stashDir,
+                target,
+                all,
+                processed: [],
+                config: {
+                    sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
+                    installedKitCount: updatedConfig.installed?.length ?? 0,
+                },
+                index: {
+                    mode: index.mode,
+                    totalEntries: index.totalEntries,
+                    directoriesScanned: index.directoriesScanned,
+                    directoriesSkipped: index.directoriesSkipped,
+                },
+            };
+        }
         const websiteMatch = stashes.find((s) => {
             if (s.type !== "website")
                 return false;

package/dist/commands/search.js

@@ -11,7 +11,7 @@
 import { loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
 import { appendEvent } from "../core/events";
-import { closeDatabase, openDatabase } from "../indexer/db";
+import { closeDatabase, openExistingDatabase } from "../indexer/db";
 import { searchLocal } from "../indexer/db-search";
 import { resolveSourceEntries } from "../indexer/search-source";
 // Eagerly import source providers to trigger self-registration before the
@@ -169,7 +169,7 @@ function logSearchEvent(query, response, existingDb) {
         metadata: { query, hitCount: stashHits.length, resultRefs: stashHits.map((h) => h.ref) },
     });
     try {
-        const db = existingDb ?? openDatabase();
+        const db = existingDb ?? openExistingDatabase();
         try {
             const resolved = resolveEntryIds(db, stashHits.slice(0, 50));
             for (const { entryId, ref } of resolved) {

package/dist/commands/show.js

@@ -26,10 +26,9 @@ import { loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
 import { appendEvent, readEvents } from "../core/events";
 import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
-import { closeDatabase, findEntryIdByRef, openDatabase } from "../indexer/db";
+import { closeDatabase, findEntryIdByRef, openExistingDatabase } from "../indexer/db";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../indexer/file-context";
 import { lookup } from "../indexer/indexer";
-import { loadStashFile } from "../indexer/metadata";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../indexer/search-source";
 import { insertUsageEvent } from "../indexer/usage-events";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve";
@@ -203,7 +202,7 @@ function logShowEvent(ref, existingDb) {
     const parsed = parseAssetRef(ref);
     appendEvent({ eventType: "show", ref, metadata: { type: parsed.type, name: parsed.name } });
     try {
-        const db = existingDb ?? openDatabase();
+        const db = existingDb ?? openExistingDatabase();
         try {
             insertUsageEvent(db, {
                 event_type: "show",
@@ -369,33 +368,19 @@ function buildBriefResponse(full, assetPath) {
  *
  * Strips content/template/prompt and returns only metadata fields:
  * type, name, path, description, tags, parameters, action.
- * Enriches description and tags from frontmatter or .stash.json when available.
+ * Enriches description and tags from rendered content when available.
  *
  * The resulting JSON should be under 200 tokens.
  */
 function buildSummaryResponse(full, assetPath) {
     let description = full.description;
-    let tags = full.tags;
+    const tags = full.tags;
     if (assetPath) {
         const textContent = full.content ?? full.template ?? full.prompt;
         if (textContent && !description) {
             const parsed = parseFrontmatter(textContent);
             description = toStringOrUndefined(parsed.data.description);
         }
-        const dir = path.dirname(assetPath);
-        const stashFile = loadStashFile(dir);
-        if (stashFile) {
-            const fileName = path.basename(assetPath);
-            const entry = stashFile.entries.find((e) => e.filename === fileName);
-            if (entry) {
-                if (!description && entry.description) {
-                    description = entry.description;
-                }
-                if (!tags && entry.tags) {
-                    tags = entry.tags;
-                }
-            }
-        }
     }
     const summary = {
         type: full.type,

package/dist/core/config.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { parseAgentConfig } from "../integrations/agent/config";
 import { filterNonEmptyStrings } from "./common";
 import { ConfigError } from "./errors";
-import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath } from "./paths";
+import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath, getCacheDir } from "./paths";
 import { warn } from "./warn";
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
@@ -108,9 +108,21 @@ export function saveConfig(config) {
     const configPath = getConfigPath();
     const dir = path.dirname(configPath);
     fs.mkdirSync(dir, { recursive: true });
+    backupExistingConfig(configPath);
     const sanitized = sanitizeConfigForWrite(config);
     writeConfigObject(configPath, sanitized);
 }
+function backupExistingConfig(configPath) {
+    if (!fs.existsSync(configPath))
+        return;
+    const backupDir = path.join(getCacheDir(), "config-backups");
+    fs.mkdirSync(backupDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
+    const backupPath = path.join(backupDir, `config-${timestamp}.json`);
+    fs.copyFileSync(configPath, backupPath);
+    const latestPath = path.join(backupDir, "config.latest.json");
+    fs.copyFileSync(configPath, latestPath);
+}
 /**
  * Strip apiKey fields before writing config to disk.
  * API keys should be provided via environment variables

package/dist/indexer/db-search.js

@@ -17,7 +17,7 @@ import { defaultRendererRegistry } from "../core/asset-registry";
 import { deriveCanonicalAssetNameFromStashRoot } from "../core/asset-spec";
 import { getDbPath } from "../core/paths";
 import { warn } from "../core/warn";
-import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "./db";
+import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openExistingDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "./db";
 import { getRenderer } from "./file-context";
 import { computeGraphBoost, loadGraphBoostContext } from "./graph-boost";
 import { generateMetadataFlat, isProposedQuality, loadStashFile, shouldIndexStashFile, } from "./metadata";
@@ -69,8 +69,7 @@ export async function searchLocal(input) {
     const dbPath = getDbPath();
     try {
         if (fs.existsSync(dbPath)) {
-            const embeddingDim = config.embedding?.dimension;
-            const db = openDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
+            const db = openExistingDatabase(dbPath);
             try {
                 const entryCount = getEntryCount(db);
                 const storedStashDir = getMeta(db, "stashDir");
@@ -706,44 +705,20 @@ async function indexAssets(stashDir, type, sources) {
             dirGroups.set(ctx.parentDirAbs, [ctx.absPath]);
     }
     for (const [dirPath, files] of dirGroups) {
-        let stash = loadStashFile(dirPath);
-        if (stash) {
-            const coveredFiles = new Set(stash.entries.map((entry) => entry.filename).filter((entry) => !!entry));
-            const uncoveredFiles = files.filter((file) => !coveredFiles.has(path.basename(file)));
-            if (uncoveredFiles.length > 0) {
-                const generated = await generateMetadataFlat(stashDir, uncoveredFiles);
-                if (generated.entries.length > 0) {
-                    stash = { entries: [...stash.entries, ...generated.entries] };
-                }
-            }
-        }
-        else {
-            const generated = await generateMetadataFlat(stashDir, files);
-            if (generated.entries.length === 0)
-                continue;
-            stash = generated;
-        }
-        // Build a lookup for matching filename-less entries to actual files
-        const fileBasenameMap = new Map();
-        for (const file of files) {
-            const base = path.basename(file, path.extname(file));
-            if (!fileBasenameMap.has(base))
-                fileBasenameMap.set(base, file);
-        }
+        const generated = await generateMetadataFlat(stashDir, files);
+        const legacyOverrides = loadStashFile(dirPath, { requireFilename: true });
+        const mergedEntries = legacyOverrides
+            ? generated.entries.map((entry) => mergeLegacyEntry(entry, legacyOverrides.entries))
+            : generated.entries;
+        const stash = mergedEntries.length > 0 ? { entries: mergedEntries } : legacyOverrides;
+        if (!stash || stash.entries.length === 0)
+            continue;
         for (const entry of stash.entries) {
             if (filterType && entry.type !== filterType)
                 continue;
-            let entryPath;
-            if (entry.filename) {
-                entryPath = path.join(dirPath, entry.filename);
-            }
-            else {
-                // Try matching entry name to a file by basename
-                entryPath =
-                    fileBasenameMap.get(entry.name) ??
-                        fileBasenameMap.get(entry.name.split("/").pop() ?? "") ??
-                        (files[0] || dirPath);
-            }
+            if (!entry.filename)
+                continue;
+            const entryPath = path.join(dirPath, entry.filename);
             if (!shouldIndexStashFile(stashDir, entryPath))
                 continue;
             assets.push({ entry, path: entryPath });
@@ -751,6 +726,10 @@ async function indexAssets(stashDir, type, sources) {
     }
     return assets;
 }
+function mergeLegacyEntry(entry, legacyEntries) {
+    const legacy = legacyEntries.find((candidate) => candidate.filename === entry.filename);
+    return legacy ? { ...entry, ...legacy, filename: entry.filename } : entry;
+}
 async function indexWikiRootAssets(wikiRoot, wikiName, type) {
     if (type !== "any" && type !== "wiki")
         return [];

package/dist/indexer/db.js

@@ -9,7 +9,7 @@ import { cosineSimilarity } from "../llm/embedders/types";
 import { buildSearchFields } from "./search-fields";
 import { ensureUsageEventsSchema } from "./usage-events";
 // ── Constants ───────────────────────────────────────────────────────────────
-export const DB_VERSION = 9;
+export const DB_VERSION = 10;
 export const EMBEDDING_DIM = 384;
 // ── Database lifecycle ──────────────────────────────────────────────────────
 export function openDatabase(dbPath, options) {
@@ -29,6 +29,17 @@ export function openDatabase(dbPath, options) {
     warnIfVecMissing(db, { once: true });
     return db;
 }
+export function openExistingDatabase(dbPath) {
+    const resolvedPath = dbPath ?? getDbPath();
+    const db = new Database(resolvedPath);
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA busy_timeout = 5000");
+    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.
+    loadVecExtension(db);
+    return db;
+}
 export function closeDatabase(db) {
     db.close();
 }
@@ -163,6 +174,15 @@ function ensureSchema(db, embeddingDim) {
       updated_at   TEXT NOT NULL DEFAULT (datetime('now')),
       FOREIGN KEY (entry_id) REFERENCES entries(id) ON DELETE CASCADE
     );
+  `);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS index_dir_state (
+      dir_path          TEXT PRIMARY KEY,
+      file_set_hash     TEXT NOT NULL,
+      file_mtime_max_ms REAL NOT NULL,
+      reason            TEXT NOT NULL,
+      updated_at        TEXT NOT NULL
+    );
   `);
     // FTS-dirty queue. Created here (not lazily on first upsert) so the
     // per-entry write path doesn't issue a CREATE TABLE IF NOT EXISTS on
@@ -261,6 +281,7 @@ function handleVersionUpgrade(db) {
     db.exec("DROP TABLE IF EXISTS embeddings");
     db.exec("DROP TABLE IF EXISTS entries_vec");
     db.exec("DROP TABLE IF EXISTS entries_fts");
+    db.exec("DROP TABLE IF EXISTS index_dir_state");
     db.exec("DROP INDEX IF EXISTS idx_entries_dir");
     db.exec("DROP INDEX IF EXISTS idx_entries_type");
     db.exec("DROP TABLE IF EXISTS entries");
@@ -332,6 +353,35 @@ export function getMeta(db, key) {
 export function setMeta(db, key, value) {
     db.prepare("INSERT OR REPLACE INTO index_meta (key, value) VALUES (?, ?)").run(key, value);
 }
+export function getIndexDirState(db, dirPath) {
+    const row = db
+        .prepare("SELECT dir_path, file_set_hash, file_mtime_max_ms, reason, updated_at FROM index_dir_state WHERE dir_path = ?")
+        .get(dirPath);
+    if (!row)
+        return undefined;
+    return {
+        dirPath: row.dir_path,
+        fileSetHash: row.file_set_hash,
+        fileMtimeMaxMs: row.file_mtime_max_ms,
+        reason: row.reason,
+        updatedAt: row.updated_at,
+    };
+}
+export function upsertIndexDirState(db, state) {
+    db.prepare(`INSERT INTO index_dir_state (dir_path, file_set_hash, file_mtime_max_ms, reason, updated_at)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(dir_path) DO UPDATE SET
+       file_set_hash = excluded.file_set_hash,
+       file_mtime_max_ms = excluded.file_mtime_max_ms,
+       reason = excluded.reason,
+       updated_at = excluded.updated_at`).run(state.dirPath, state.fileSetHash, state.fileMtimeMaxMs, state.reason, new Date().toISOString());
+}
+export function deleteIndexDirState(db, dirPath) {
+    db.prepare("DELETE FROM index_dir_state WHERE dir_path = ?").run(dirPath);
+}
+export function deleteIndexDirStatesByStashDir(db, stashDir) {
+    db.prepare("DELETE FROM index_dir_state WHERE dir_path = ? OR dir_path LIKE ?").run(stashDir, `${stashDir}${path.sep}%`);
+}
 // ── Entry operations ────────────────────────────────────────────────────────
 /**
  * Insert or update an entry in the `entries` table. Returns the row id.