akm-cli 0.9.1 → 0.9.2-alpha.1

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

@@ -6,7 +6,7 @@
  *
  * Centralizes the one canonical `entries` SELECT column list and the
  * JSON-parse-guarded row → {@link DbIndexedEntry} mapping that several queries
- * used to reimplement. Corrupt `entry_json` rows are skipped (warn once) rather
+ * used to reimplement. Corrupt `document_json` rows are skipped (warn once) rather
  * than crashing the caller.
  *
  * Relocated from `src/indexer/db/entry-mapper.ts` (WI-5a): it now imports the
@@ -23,36 +23,32 @@ import { warn } from "../../core/warn.js";
  * Durable identity columns are surfaced here so every mapped entry carries
  * current indexed provenance.
  */
-export const ENTRY_COLUMNS = "id, entry_key, dir_path, file_path, stash_dir, entry_json, search_text, item_ref, concept_id, bundle_id, adapter_id";
+export const ENTRY_COLUMNS = "id, item_ref, bundle_id, component_id, concept_id, adapter_id, type, file_path, content_hash, document_json, search_text";
 /**
- * Map one raw `entries` row to a {@link DbIndexedEntry}, parsing `entry_json`.
+ * Map one raw `entries` row to a {@link DbIndexedEntry}, parsing `document_json`.
  * Returns `null` (and warns, tagged with `context`) when the JSON is corrupt so
  * callers can skip the row instead of crashing.
  */
 export function rowToIndexedEntry(row, context) {
     let entry;
     try {
-        entry = JSON.parse(row.entry_json);
+        entry = JSON.parse(row.document_json);
     }
     catch {
-        warn(`[db] ${context}: skipping entry id=${row.id} — corrupt entry_json`);
-        return null;
-    }
-    if (!row.item_ref || !row.concept_id || !row.bundle_id || !row.adapter_id) {
-        warn(`[db] ${context}: skipping entry id=${row.id} — missing indexed provenance`);
+        warn(`[db] ${context}: skipping entry id=${row.id} — corrupt document_json`);
         return null;
     }
     return {
         id: row.id,
-        entryKey: row.entry_key,
-        dirPath: row.dir_path,
         filePath: row.file_path,
-        stashDir: row.stash_dir,
         entry,
         searchText: row.search_text,
         itemRef: row.item_ref,
         conceptId: row.concept_id,
         bundleId: row.bundle_id,
+        componentId: row.component_id,
         adapterId: row.adapter_id,
+        type: row.type,
+        ...(row.content_hash ? { contentHash: row.content_hash } : {}),
     };
 }

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

@@ -0,0 +1,255 @@
+// 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/.
+/**
+ * The single canonical contract for the derived `entries` generation.
+ *
+ * `index.db` is regenerable, so callers compare one normalized PRAGMA
+ * fingerprint and discard any generation that differs. This module owns both
+ * the DDL and its expected fingerprint so schema creation, writable opens,
+ * serving preflights, and read-only evaluator tooling cannot drift into
+ * separate definitions of "current".
+ */
+export const CANONICAL_INDEX_DB_VERSION = 21;
+export const CANONICAL_ENTRY_SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS entries (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    item_ref      TEXT NOT NULL UNIQUE,
+    bundle_id     TEXT NOT NULL,
+    component_id  TEXT NOT NULL,
+    concept_id    TEXT NOT NULL,
+    adapter_id    TEXT NOT NULL,
+    type          TEXT NOT NULL,
+    file_path     TEXT NOT NULL,
+    content_hash  TEXT,
+    document_json TEXT NOT NULL,
+    search_text   TEXT NOT NULL,
+    derived_from  TEXT
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_entries_bundle ON entries(bundle_id);
+  CREATE INDEX IF NOT EXISTS idx_entries_type ON entries(type);
+  CREATE INDEX IF NOT EXISTS idx_entries_file_path ON entries(file_path);
+  CREATE INDEX IF NOT EXISTS idx_entries_derived_from ON entries(derived_from);
+`;
+const CANONICAL_ENTRY_SCHEMA_FINGERPRINT = {
+    tableSql: "CREATE TABLE entries ( id INTEGER PRIMARY KEY AUTOINCREMENT, item_ref TEXT NOT NULL UNIQUE, bundle_id TEXT NOT NULL, component_id TEXT NOT NULL, concept_id TEXT NOT NULL, adapter_id TEXT NOT NULL, type TEXT NOT NULL, file_path TEXT NOT NULL, content_hash TEXT, document_json TEXT NOT NULL, search_text TEXT NOT NULL, derived_from TEXT )",
+    sqliteSequenceTable: true,
+    sqliteSequenceValid: true,
+    columns: [
+        { cid: 0, name: "id", type: "INTEGER", notNull: 0, defaultValue: null, primaryKeyPosition: 1, hidden: 0 },
+        {
+            cid: 1,
+            name: "item_ref",
+            type: "TEXT",
+            notNull: 1,
+            defaultValue: null,
+            primaryKeyPosition: 0,
+            hidden: 0,
+        },
+        {
+            cid: 2,
+            name: "bundle_id",
+            type: "TEXT",
+            notNull: 1,
+            defaultValue: null,
+            primaryKeyPosition: 0,
+            hidden: 0,
+        },
+        {
+            cid: 3,
+            name: "component_id",
+            type: "TEXT",
+            notNull: 1,
+            defaultValue: null,
+            primaryKeyPosition: 0,
+            hidden: 0,
+        },
+        {
+            cid: 4,
+            name: "concept_id",
+            type: "TEXT",
+            notNull: 1,
+            defaultValue: null,
+            primaryKeyPosition: 0,
+            hidden: 0,
+        },
+        {
+            cid: 5,
+            name: "adapter_id",
+            type: "TEXT",
+            notNull: 1,
+            defaultValue: null,
+            primaryKeyPosition: 0,
+            hidden: 0,
+        },
+        { cid: 6, name: "type", type: "TEXT", notNull: 1, defaultValue: null, primaryKeyPosition: 0, hidden: 0 },
+        {
+            cid: 7,
+            name: "file_path",
+            type: "TEXT",
+            notNull: 1,
+            defaultValue: null,
+            primaryKeyPosition: 0,
+            hidden: 0,
+        },
+        {
+            cid: 8,
+            name: "content_hash",
+            type: "TEXT",
+            notNull: 0,
+            defaultValue: null,
+            primaryKeyPosition: 0,
+            hidden: 0,
+        },
+        {
+            cid: 9,
+            name: "document_json",
+            type: "TEXT",
+            notNull: 1,
+            defaultValue: null,
+            primaryKeyPosition: 0,
+            hidden: 0,
+        },
+        {
+            cid: 10,
+            name: "search_text",
+            type: "TEXT",
+            notNull: 1,
+            defaultValue: null,
+            primaryKeyPosition: 0,
+            hidden: 0,
+        },
+        {
+            cid: 11,
+            name: "derived_from",
+            type: "TEXT",
+            notNull: 0,
+            defaultValue: null,
+            primaryKeyPosition: 0,
+            hidden: 0,
+        },
+    ],
+    indexes: [
+        {
+            name: "idx_entries_bundle",
+            unique: 0,
+            origin: "c",
+            partial: 0,
+            columns: [
+                { sequence: 0, cid: 2, name: "bundle_id", descending: 0, collation: "BINARY", key: 1 },
+                { sequence: 1, cid: -1, name: null, descending: 0, collation: "BINARY", key: 0 },
+            ],
+        },
+        {
+            name: "idx_entries_derived_from",
+            unique: 0,
+            origin: "c",
+            partial: 0,
+            columns: [
+                { sequence: 0, cid: 11, name: "derived_from", descending: 0, collation: "BINARY", key: 1 },
+                { sequence: 1, cid: -1, name: null, descending: 0, collation: "BINARY", key: 0 },
+            ],
+        },
+        {
+            name: "idx_entries_file_path",
+            unique: 0,
+            origin: "c",
+            partial: 0,
+            columns: [
+                { sequence: 0, cid: 7, name: "file_path", descending: 0, collation: "BINARY", key: 1 },
+                { sequence: 1, cid: -1, name: null, descending: 0, collation: "BINARY", key: 0 },
+            ],
+        },
+        {
+            name: "idx_entries_type",
+            unique: 0,
+            origin: "c",
+            partial: 0,
+            columns: [
+                { sequence: 0, cid: 6, name: "type", descending: 0, collation: "BINARY", key: 1 },
+                { sequence: 1, cid: -1, name: null, descending: 0, collation: "BINARY", key: 0 },
+            ],
+        },
+        {
+            name: "sqlite_autoindex_entries_1",
+            unique: 1,
+            origin: "u",
+            partial: 0,
+            columns: [
+                { sequence: 0, cid: 1, name: "item_ref", descending: 0, collation: "BINARY", key: 1 },
+                { sequence: 1, cid: -1, name: null, descending: 0, collation: "BINARY", key: 0 },
+            ],
+        },
+    ],
+};
+function sqlString(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function normalizeSchemaSql(value) {
+    if (value == null)
+        return null;
+    return value.replace(/\s+/g, " ").trim();
+}
+export function readEntrySchemaFingerprint(db) {
+    const tableRow = db.prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'entries'").get();
+    const sqliteSequenceTable = db.prepare("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = 'sqlite_sequence'").get() !=
+        null;
+    const maxId = Number(db.prepare("SELECT COALESCE(MAX(id), 0) AS maxId FROM entries").get().maxId);
+    const sequenceRow = sqliteSequenceTable
+        ? db.prepare("SELECT seq FROM sqlite_sequence WHERE name = 'entries'").get()
+        : undefined;
+    const sqliteSequenceValid = sqliteSequenceTable &&
+        (maxId === 0 ? sequenceRow == null || Number(sequenceRow.seq) >= 0 : Number(sequenceRow?.seq) >= maxId);
+    const columns = db.prepare("PRAGMA table_xinfo(entries)").all().map((column) => ({
+        cid: Number(column.cid),
+        name: column.name,
+        type: column.type.trim().toUpperCase(),
+        notNull: Number(column.notnull),
+        defaultValue: column.dflt_value === null ? null : String(column.dflt_value),
+        primaryKeyPosition: Number(column.pk),
+        hidden: Number(column.hidden),
+    }));
+    const indexes = db.prepare("PRAGMA index_list(entries)").all()
+        .map((index) => ({
+        name: index.name,
+        unique: Number(index.unique),
+        origin: index.origin,
+        partial: Number(index.partial),
+        columns: db.prepare(`PRAGMA index_xinfo(${sqlString(index.name)})`).all()
+            .sort((left, right) => Number(left.seqno) - Number(right.seqno))
+            .map((column) => ({
+            sequence: Number(column.seqno),
+            cid: Number(column.cid),
+            name: column.name,
+            descending: Number(column.desc),
+            collation: column.coll,
+            key: Number(column.key),
+        })),
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    return {
+        tableSql: normalizeSchemaSql(tableRow?.sql),
+        sqliteSequenceTable,
+        sqliteSequenceValid,
+        columns,
+        indexes,
+    };
+}
+export function hasCanonicalEntrySchema(db) {
+    try {
+        return JSON.stringify(readEntrySchemaFingerprint(db)) === JSON.stringify(CANONICAL_ENTRY_SCHEMA_FINGERPRINT);
+    }
+    catch {
+        return false;
+    }
+}
+export function isCanonicalIndexGeneration(db) {
+    try {
+        const row = db.prepare("SELECT value FROM index_meta WHERE key = 'version'").get();
+        return row?.value === String(CANONICAL_INDEX_DB_VERSION) && hasCanonicalEntrySchema(db);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -34,7 +34,7 @@ function runFtsQuery(db, ftsQuery, limit, entryType, excludeTypes) {
     // exclusion is redundant there. An empty list skips the clause entirely
     // (never emit `NOT IN ()`, which is a SQL error / always-false).
     const excludes = excludeTypes && excludeTypes.length > 0 ? excludeTypes : [];
-    // The typed and untyped paths differ ONLY by one WHERE clause (an entry_type
+    // The typed and untyped paths differ only by one `type` WHERE clause
     // equality vs. an optional NOT IN exclusion) and their param order — the
     // SELECT/JOIN/ORDER/LIMIT is shared, so build it once. Join on integer
     // entry_id directly (no CAST; we store integer). bm25() per-column weights:
@@ -42,16 +42,16 @@ function runFtsQuery(db, ftsQuery, limit, entryType, excludeTypes) {
     let filterClause;
     let params;
     if (entryType && entryType !== "any") {
-        filterClause = "AND e.entry_type = ?";
+        filterClause = "AND e.type = ?";
         params = [ftsQuery, entryType, limit];
     }
     else {
-        filterClause = excludes.length > 0 ? `AND e.entry_type NOT IN (${excludes.map(() => "?").join(", ")})` : "";
+        filterClause = excludes.length > 0 ? `AND e.type NOT IN (${excludes.map(() => "?").join(", ")})` : "";
         // Param order: MATCH, then the NOT IN values, then LIMIT.
         params = [ftsQuery, ...excludes, limit];
     }
     const sql = `
-    SELECT e.id, e.file_path AS filePath, e.entry_json, e.search_text AS searchText,
+    SELECT e.id, e.file_path AS filePath, e.document_json AS documentJson, e.search_text AS searchText,
            e.item_ref AS itemRef, e.bundle_id AS bundleId, e.concept_id AS conceptId, e.adapter_id AS adapterId,
            bm25(entries_fts, 0, 10.0, 5.0, 3.0, 2.0, 1.0) AS bm25Score
     FROM entries_fts f
@@ -68,10 +68,10 @@ function runFtsQuery(db, ftsQuery, limit, entryType, excludeTypes) {
         for (const row of rows) {
             let entry;
             try {
-                entry = JSON.parse(row.entry_json);
+                entry = JSON.parse(row.documentJson);
             }
             catch {
-                warn(`[db] searchFts: skipping entry id=${row.id} — corrupt entry_json`);
+                warn(`[db] searchFts: skipping entry id=${row.id} — corrupt document_json`);
                 continue;
             }
             results.push({
@@ -116,7 +116,7 @@ export function rebuildFts(db, options) {
             // Then drop the matching rows from entries_fts so the INSERT below
             // doesn't double-up. The dirty list is drained at the end.
             rows = db
-                .prepare(`SELECT e.id AS id, e.entry_json AS entry_json
+                .prepare(`SELECT e.id AS id, e.document_json AS document_json
              FROM entries_fts_dirty d
              JOIN entries e ON e.id = d.entry_id`)
                 .all();
@@ -134,7 +134,7 @@ export function rebuildFts(db, options) {
         else {
             // Full path: wipe and re-read every row.
             db.exec("DELETE FROM entries_fts");
-            rows = db.prepare("SELECT id, entry_json FROM entries").all();
+            rows = db.prepare("SELECT id, document_json FROM entries").all();
         }
         const insertStmt = db.prepare("INSERT INTO entries_fts (entry_id, name, description, tags, hints, content) VALUES (?, ?, ?, ?, ?, ?)");
         let skipped = 0;
@@ -142,7 +142,7 @@ export function rebuildFts(db, options) {
             let entry;
             let fields;
             try {
-                entry = JSON.parse(row.entry_json);
+                entry = JSON.parse(row.document_json);
                 fields = buildSearchFields(entry);
             }
             catch {
@@ -152,7 +152,7 @@ export function rebuildFts(db, options) {
             insertStmt.run(row.id, fields.name, fields.description, fields.tags, fields.hints, fields.content);
         }
         if (skipped > 0) {
-            warn(`[db] rebuildFts: skipped ${skipped} entr${skipped === 1 ? "y" : "ies"} with invalid entry_json`);
+            warn(`[db] rebuildFts: skipped ${skipped} entr${skipped === 1 ? "y" : "ies"} with invalid document_json`);
         }
         // Always drain the dirty queue — both paths converge here. The
         // incremental path drains it because we just consumed every dirty row;

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

@@ -7,7 +7,6 @@
  * 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.
  */
-import { bestEffort } from "../../core/best-effort.js";
 import { sha256Hex } from "../../runtime.js";
 import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
 /**
@@ -83,20 +82,16 @@ 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.
  *
- * The join uses a LIKE match against the entries `file_path` column because
- * graph/memory cache refs are absolute file paths, while enrichment cache
- * refs are entry_key strings — we preserve any entry that still has a
- * corresponding row in either the entries table (by entry_key) or that
- * matches a live file_path.
+ * 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.
  */
 export function clearStaleCacheEntries(db) {
-    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)
-    `);
-    }, "llm_enrichment_cache may not exist in very old DBs opened without ensureSchema");
+    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)
+  `);
 }
 /**
  * Compute a stable SHA-256 hex digest of a UTF-8 string. Used as the body_hash

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

@@ -1,14 +1,6 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * `index.db` meta + per-directory index-state repository.
- *
- * Owns the raw SQL for `index_meta` (the key/value stamp table) and
- * `index_dir_state` (incremental-index bookkeeping). Lives in the storage
- * layer, not the indexer, so the storage layer owns these primitives.
- */
-import path from "node:path";
 // ── Meta helpers ────────────────────────────────────────────────────────────
 export function getMeta(db, key) {
     const row = db.prepare("SELECT value FROM index_meta WHERE key = ?").get(key);
@@ -55,6 +47,3 @@ export function upsertIndexDirState(db, state) {
 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}%`);
-}