akm-cli 0.9.17-alpha.7 → 0.9.17-alpha.9

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

@@ -10,30 +10,31 @@
  * 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";
 import { ConfigError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { sha256Hex } from "../../runtime.js";
 import { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, entriesFtsDdl, isContentlessFtsDdl, missingEntryColumns, readTableSql, supportsContentlessDelete, tableExists, } from "./index-entry-schema.js";
 import { rebuildFts } from "./index-fts-repository.js";
+import { rebuildAllEntryLinks } from "./index-links-repository.js";
 import { getMeta, setMeta } from "./index-meta-repository.js";
 // ── Constants ───────────────────────────────────────────────────────────────
 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;
 /**
  * The refusal for an index a newer akm wrote. Readers and the writable opener
  * both raise it: a newer layout may lack tables or columns this release reads
@@ -65,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"))
@@ -164,12 +83,13 @@ 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",
             "entry_fragments",
+            "asset_links",
             "embeddings",
             "utility_scores_scoped",
             "utility_scores",
@@ -241,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");
@@ -249,6 +169,25 @@ function ensureFtsLayout(db) {
         rebuildFts(db);
     })();
 }
+/**
+ * Layout 26 stores declared links (#935). Every relation an older layout
+ * indexed already sits in `document_json`, so the links are derived from there
+ * in place, with no file read. The exception is a workflow's step targets and
+ * a task's target, which no earlier layout stored: the directories holding
+ * workflows and tasks lose their incremental cursor, so the next `akm index`
+ * re-reads those and nothing else. One transaction.
+ */
+function migrateToDeclaredLinks(db) {
+    db.transaction(() => {
+        rebuildAllEntryLinks(db);
+        const rows = db
+            .prepare("SELECT DISTINCT file_path FROM entries WHERE type IN ('workflow', 'task')")
+            .all();
+        const forget = db.prepare("DELETE FROM index_dir_state WHERE dir_path = ?");
+        for (const dir of new Set(rows.map((row) => path.dirname(row.file_path))))
+            forget.run(dir);
+    })();
+}
 function tableHasColumn(db, table, column) {
     const columns = db.prepare(`PRAGMA table_info(${table})`).all();
     return columns.some((existing) => existing.name === column);
@@ -287,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
@@ -339,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,
@@ -354,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')");
@@ -368,6 +343,9 @@ export function ensureSchema(db) {
     if (!hadFragmentSource && tableExists(db, "entries")) {
         db.exec("DELETE FROM index_dir_state");
     }
+    if (storedVersion > 0 && storedVersion < DECLARED_LINKS_LAYOUT && tableExists(db, "entries")) {
+        migrateToDeclaredLinks(db);
+    }
     // Migrating an existing layout drops tables and columns; the next `akm index`
     // VACUUMs the pages they leave free (`vacuumIndexDb`, indexer.ts), since a
     // writable open may run inside a caller's transaction, where VACUUM cannot.

package/dist/storage/repositories/proposals-repository.js

@@ -168,6 +168,50 @@ function validatePresentMetadata(meta) {
     if (Object.hasOwn(meta, "eligibilitySource") && typeof meta.eligibilitySource !== "string") {
         invalidPresentField("eligibilitySource");
     }
+    if (Object.hasOwn(meta, "promotionSource") && typeof meta.promotionSource !== "string") {
+        invalidPresentField("promotionSource");
+    }
+    if (Object.hasOwn(meta, "promotionSourceHash") && typeof meta.promotionSourceHash !== "string") {
+        invalidPresentField("promotionSourceHash");
+    }
+    if (Object.hasOwn(meta, "retirement")) {
+        const retirement = meta.retirement;
+        if (typeof retirement !== "object" ||
+            retirement === null ||
+            typeof retirement.retiredRef !== "string" ||
+            typeof retirement.successorRef !== "string" ||
+            typeof retirement.cosine !== "number" ||
+            !Number.isFinite(retirement.cosine) ||
+            (retirement.judgeLabel !== "duplicate" &&
+                retirement.judgeLabel !== "subsumed" &&
+                retirement.judgeLabel !== "supersedes") ||
+            typeof retirement.judgeReason !== "string" ||
+            typeof retirement.retiredContentHash !== "string" ||
+            typeof retirement.successorContentHash !== "string" ||
+            (retirement.reason !== "duplicate" && retirement.reason !== "subsumed" && retirement.reason !== "superseded")) {
+            invalidPresentField("retirement");
+        }
+    }
+    if (Object.hasOwn(meta, "retiredArchive")) {
+        const archive = meta.retiredArchive;
+        if (typeof archive !== "object" ||
+            archive === null ||
+            !Array.isArray(archive.dirs) ||
+            archive.dirs.length === 0 ||
+            archive.dirs.some((dir) => typeof dir !== "string" || dir.length === 0)) {
+            invalidPresentField("retiredArchive");
+        }
+    }
+    if (Object.hasOwn(meta, "retireAcceptIntent")) {
+        const intent = meta.retireAcceptIntent;
+        if (typeof intent !== "object" ||
+            intent === null ||
+            typeof intent.assetPath !== "string" ||
+            intent.assetPath.length === 0 ||
+            typeof intent.backupContent !== "string") {
+            invalidPresentField("retireAcceptIntent");
+        }
+    }
 }
 /**
  * Convert a raw `ProposalRow` to the public `Proposal` shape.
@@ -233,6 +277,13 @@ export function proposalRowToProposal(row) {
         ...(typeof meta.eligibilitySource === "string"
             ? { eligibilitySource: meta.eligibilitySource }
             : {}),
+        ...(typeof meta.promotionSource === "string" ? { promotionSource: meta.promotionSource } : {}),
+        ...(typeof meta.promotionSourceHash === "string" ? { promotionSourceHash: meta.promotionSourceHash } : {}),
+        ...(meta.retirement !== undefined ? { retirement: meta.retirement } : {}),
+        ...(meta.retiredArchive !== undefined ? { retiredArchive: meta.retiredArchive } : {}),
+        ...(meta.retireAcceptIntent !== undefined
+            ? { retireAcceptIntent: meta.retireAcceptIntent }
+            : {}),
     };
 }
 /**
@@ -291,6 +342,16 @@ export function proposalToRowValues(proposal, stashDir) {
         metaObj.acceptedTarget = proposal.acceptedTarget;
     if (proposal.eligibilitySource !== undefined)
         metaObj.eligibilitySource = proposal.eligibilitySource;
+    if (proposal.promotionSource !== undefined)
+        metaObj.promotionSource = proposal.promotionSource;
+    if (proposal.promotionSourceHash !== undefined)
+        metaObj.promotionSourceHash = proposal.promotionSourceHash;
+    if (proposal.retirement !== undefined)
+        metaObj.retirement = proposal.retirement;
+    if (proposal.retiredArchive !== undefined)
+        metaObj.retiredArchive = proposal.retiredArchive;
+    if (proposal.retireAcceptIntent !== undefined)
+        metaObj.retireAcceptIntent = proposal.retireAcceptIntent;
     validatePresentMetadata(metaObj);
     return {
         id: proposal.id,

package/dist/storage/repositories/salience-repository.js

@@ -58,23 +58,6 @@ export function getAssetSalience(db, ref) {
     // Bun SQLite returns null (not undefined) when no row found.
     return row == null ? undefined : row;
 }
-/**
- * Load ALL rank scores from the asset_salience table (full-stash query).
- *
- * Used by the forgetting-safety report (plan §WS-1 step 7) to compute stash-wide
- * rank positions rather than pool-relative positions. Returns an empty Map when the
- * table is empty (first WS-1 run = no pre-existing rows).
- *
- * Order is unspecified; callers must sort before assigning 1-indexed positions.
- */
-export function getAllRankScores(db) {
-    const rows = db.prepare("SELECT asset_ref, rank_score FROM asset_salience").all();
-    const result = new Map();
-    for (const row of rows) {
-        result.set(row.asset_ref, row.rank_score);
-    }
-    return result;
-}
 // ── Plasticity helpers ────────────────────────────────────────────────────────
 /**
  * Increment `consecutive_no_ops` for an asset. Called after a no-op reflect/distill.
@@ -84,8 +67,7 @@ export function getAllRankScores(db) {
  * Invariant: recordNoOp must never originate rank_score semantics. If the asset has
  * no salience row yet (persistence's best-effort try/catch may have swallowed an
  * error), we do nothing — a no-op counter is meaningless without a rank_score row,
- * and a synthetic INSERT would fabricate a rank_score=0 entry that could produce
- * false catastrophic-forgetting signals in buildRankChangeReport.
+ * and a synthetic INSERT would fabricate a rank_score=0 entry with nothing behind it.
  */
 export function recordNoOp(db, ref) {
     db.prepare(`UPDATE asset_salience SET consecutive_no_ops = consecutive_no_ops + 1, updated_at = ? WHERE asset_ref = ?`).run(Date.now(), ref);