akm-cli 0.9.0-beta.11 → 0.9.0-beta.26

package/dist/indexer/db/graph-db.js

@@ -4,7 +4,6 @@
 import fs from "node:fs";
 import { rethrowIfTestIsolationError } from "../../core/errors.js";
 import { getDbPath } from "../../core/paths.js";
-import { warn } from "../../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "./db.js";
 function withReadableGraphDb(db, fn) {
     if (db)
@@ -26,38 +25,16 @@ function uniqueSorted(values) {
 function normalizeEntity(value) {
     return value.trim().toLowerCase();
 }
-/**
- * Resolve a file_path within a stash to its entries.id. Returns null when the
- * path has no indexed entry (orphan graph row).
- */
-export function resolveEntryIdForPath(db, stashRoot, filePath) {
-    try {
-        const row = db
-            .prepare("SELECT id FROM entries WHERE stash_dir = ? AND file_path = ? LIMIT 1")
-            .get(stashRoot, filePath);
-        if (row)
-            return row.id;
-        // Fall back to file_path-only match (legacy callers may pass a stash root
-        // that doesn't exactly match entries.stash_dir, e.g. trailing-slash diffs).
-        const fallback = db.prepare("SELECT id FROM entries WHERE file_path = ? LIMIT 1").get(filePath);
-        return fallback?.id ?? null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Persist (or update) a graph snapshot for a stash root.
  *
- * Implementation: incremental upsert keyed on entries.id. Unchanged files
- * (matching body_hash) are skipped; changed files have their child rows
- * deleted (CASCADE) and re-inserted; files in DB but absent from the new
- * snapshot are deleted. The old behaviour wiped every row for the stash on
- * each write, which produced ~22k row writes per re-index even when one
- * asset changed.
- *
- * Orphan files (no entries row resolvable) are skipped and counted in a
- * single warn() so the caller sees the magnitude without log spam.
+ * #624-P1: keyed on (stash_root, file_path, body_hash) — NOT entries.id. Graph
+ * rows are self-keyed by path, so they survive an entries delete + reinsert
+ * (a reindex) when body_hash is unchanged. Unchanged files (matching body_hash)
+ * only have their file-meta refreshed; files whose body_hash changed have their
+ * old row + child rows deleted and the new content inserted; files in DB but
+ * absent from the new snapshot are deleted. There is no entry_id resolution and
+ * no orphan-skip — a graph file no longer needs a matching entries row.
  */
 export function replaceStoredGraph(db, graph) {
     const upsertMeta = db.prepare(`INSERT INTO graph_meta (
@@ -98,87 +75,98 @@ export function replaceStoredGraph(db, graph) {
         cache_misses = excluded.cache_misses,
         truncation_count = excluded.truncation_count,
         failure_count = excluded.failure_count`);
-    const selectExisting = db.prepare("SELECT entry_id, file_path, body_hash FROM graph_files WHERE stash_root = ?");
-    const deleteFile = db.prepare("DELETE FROM graph_files WHERE entry_id = ?");
-    const deleteEntities = db.prepare("DELETE FROM graph_file_entities WHERE entry_id = ?");
-    const deleteRelations = db.prepare("DELETE FROM graph_file_relations WHERE entry_id = ?");
+    const selectExisting = db.prepare("SELECT file_path, body_hash, file_order FROM graph_files WHERE stash_root = ?");
+    const deleteFile = db.prepare("DELETE FROM graph_files WHERE stash_root = ? AND file_path = ? AND body_hash = ?");
+    const deleteEntities = db.prepare("DELETE FROM graph_file_entities WHERE stash_root = ? AND file_path = ? AND body_hash = ?");
+    const deleteRelations = db.prepare("DELETE FROM graph_file_relations WHERE stash_root = ? AND file_path = ? AND body_hash = ?");
     const insertFile = db.prepare(`INSERT INTO graph_files (
-       entry_id, stash_root, file_path, file_order, file_type, body_hash, confidence, status, reason, extraction_run_id
-     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+       stash_root, file_path, file_order, file_type, body_hash, confidence, status, reason, extraction_run_id
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
     const updateFileMeta = db.prepare(`UPDATE graph_files
        SET file_order = ?, file_type = ?, confidence = ?, status = ?, reason = ?, extraction_run_id = ?
-        WHERE entry_id = ?`);
-    const insertEntity = db.prepare(`INSERT INTO graph_file_entities (entry_id, entity_order, stash_root, entity_norm, entity)
-     VALUES (?, ?, ?, ?, ?)`);
+        WHERE stash_root = ? AND file_path = ? AND body_hash = ?`);
+    const insertEntity = db.prepare(`INSERT INTO graph_file_entities (stash_root, file_path, body_hash, entity_order, entity_norm, entity)
+     VALUES (?, ?, ?, ?, ?, ?)`);
     const insertRelation = db.prepare(`INSERT INTO graph_file_relations (
-       entry_id, relation_order, from_entity_norm, from_entity, to_entity_norm, to_entity, relation_type, confidence
-     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+       stash_root, file_path, body_hash, relation_order, from_entity_norm, from_entity, to_entity_norm, to_entity, relation_type, confidence
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
     const quality = graph.quality;
     const telemetry = graph.telemetry;
     db.transaction(() => {
         upsertMeta.run(graph.stashRoot, graph.schemaVersion, graph.generatedAt, quality?.consideredFiles ?? graph.files.length, quality?.extractedFiles ?? graph.files.length, quality?.entityCount ?? graph.entities?.length ?? 0, quality?.relationCount ?? graph.relations?.length ?? 0, quality?.extractionCoverage ?? 0, quality?.density ?? 0, telemetry?.extractorId ?? null, telemetry?.extractionRunId ?? null, telemetry?.model ?? null, telemetry?.promptVersion ?? null, telemetry?.batchSize ?? null, telemetry?.cacheHits ?? 0, telemetry?.cacheMisses ?? 0, telemetry?.truncationCount ?? 0, telemetry?.failureCount ?? 0);
-        // Build a snapshot of existing rows for incremental compare.
+        // Build a snapshot of existing rows for incremental compare. The unique
+        // index idx_graph_files_path guarantees at most one row per file_path.
         const existingRows = selectExisting.all(graph.stashRoot);
         const existingByPath = new Map();
         for (const row of existingRows)
             existingByPath.set(row.file_path, row);
-        let orphanCount = 0;
-        const presentEntryIds = new Set();
+        const presentPaths = new Set();
         for (const [fileOrder, node] of graph.files.entries()) {
-            // body_hash is NOT NULL in schema v2; default to a sentinel for inputs
-            // (test fixtures, legacy imports) that don't supply one. The sentinel
-            // never equals a real hash so subsequent staleness checks always
-            // re-extract — correct behaviour for "unknown" bodies.
+            // body_hash is part of the PK; default to a sentinel for inputs (test
+            // fixtures, legacy imports) that don't supply one. The sentinel never
+            // equals a real hash so subsequent staleness checks always re-extract —
+            // correct behaviour for "unknown" bodies. Distinct files in one stash
+            // are still keyed apart by file_path, so the empty sentinel is safe.
             const bodyHash = node.bodyHash && node.bodyHash.length > 0 ? node.bodyHash : "";
-            const entryId = resolveEntryIdForPath(db, graph.stashRoot, node.path);
-            if (entryId == null) {
-                orphanCount += 1;
-                continue;
-            }
-            presentEntryIds.add(entryId);
+            presentPaths.add(node.path);
             const existing = existingByPath.get(node.path);
-            if (existing && existing.entry_id === entryId && existing.body_hash === bodyHash) {
+            if (existing && existing.body_hash === bodyHash) {
                 // Body unchanged — only fix up file_order/confidence in case they drifted.
-                updateFileMeta.run(fileOrder, node.type, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null, entryId);
+                updateFileMeta.run(fileOrder, node.type, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null, graph.stashRoot, node.path, bodyHash);
                 continue;
             }
             if (existing) {
-                // Stale row (different body_hash, or entry_id moved to a different
-                // path under the same file_path). Wipe child rows; CASCADE would do
-                // it but explicit DELETE keeps the order deterministic.
-                deleteEntities.run(existing.entry_id);
-                deleteRelations.run(existing.entry_id);
-                deleteFile.run(existing.entry_id);
+                // Stale row (different body_hash for this path). Delete the old row by
+                // its OLD body_hash; child rows cascade, but explicit DELETE keeps the
+                // order deterministic and is safe regardless of the FK pragma.
+                deleteEntities.run(graph.stashRoot, existing.file_path, existing.body_hash);
+                deleteRelations.run(graph.stashRoot, existing.file_path, existing.body_hash);
+                deleteFile.run(graph.stashRoot, existing.file_path, existing.body_hash);
             }
-            insertFile.run(entryId, graph.stashRoot, node.path, fileOrder, node.type, bodyHash, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null);
+            insertFile.run(graph.stashRoot, node.path, fileOrder, node.type, bodyHash, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null);
             for (const [entityOrder, entity] of node.entities.entries()) {
-                insertEntity.run(entryId, entityOrder, graph.stashRoot, normalizeEntity(entity), entity);
+                insertEntity.run(graph.stashRoot, node.path, bodyHash, entityOrder, normalizeEntity(entity), entity);
             }
             for (const [relationOrder, relation] of node.relations.entries()) {
-                insertRelation.run(entryId, relationOrder, normalizeEntity(relation.from), relation.from, normalizeEntity(relation.to), relation.to, relation.type ?? null, relation.confidence ?? null);
+                insertRelation.run(graph.stashRoot, node.path, bodyHash, relationOrder, normalizeEntity(relation.from), relation.from, normalizeEntity(relation.to), relation.to, relation.type ?? null, relation.confidence ?? null);
             }
         }
         // Delete files present in DB but absent from the new snapshot. Child
-        // tables CASCADE on entry_id.
+        // tables CASCADE on the composite key; explicit DELETE keeps it determinstic.
         for (const row of existingRows) {
-            if (!presentEntryIds.has(row.entry_id)) {
-                deleteEntities.run(row.entry_id);
-                deleteRelations.run(row.entry_id);
-                deleteFile.run(row.entry_id);
+            if (!presentPaths.has(row.file_path)) {
+                deleteEntities.run(graph.stashRoot, row.file_path, row.body_hash);
+                deleteRelations.run(graph.stashRoot, row.file_path, row.body_hash);
+                deleteFile.run(graph.stashRoot, row.file_path, row.body_hash);
             }
         }
-        if (orphanCount > 0) {
-            warn(`[graph] replaceStoredGraph: skipped ${orphanCount} file(s) with no resolvable entry under ${graph.stashRoot}.`);
-        }
     })();
 }
 export function deleteStoredGraph(db, stashPath) {
     db.transaction(() => {
-        // Child rows cascade via entry_id; deleting graph_files clears them.
+        // Child rows cascade via the composite (stash_root, file_path, body_hash)
+        // FK; deleting graph_files clears them. This is the explicit full-clear
+        // path for a stash (entries-delete no longer wipes graph data — see #624-P1).
         db.prepare("DELETE FROM graph_files WHERE stash_root = ?").run(stashPath);
         db.prepare("DELETE FROM graph_meta WHERE stash_root = ?").run(stashPath);
     })();
 }
+/**
+ * #624-P1 — does any graph data exist for a file_path under a stash root?
+ * Consumed by show/curate flows (P3) but defined here so the schema and its
+ * accessors land together.
+ */
+export function hasGraphData(db, stashRoot, filePath) {
+    try {
+        const row = db
+            .prepare("SELECT 1 AS present FROM graph_files WHERE stash_root = ? AND file_path = ? LIMIT 1")
+            .get(stashRoot, filePath);
+        return row !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Scoped loader — only the graph_meta row for a stash. Used by callers that
  * only need summary numbers (e.g. `akm graph summary`).
@@ -195,13 +183,12 @@ export function loadGraphFilesOnly(stashPath, db) {
         return withReadableGraphDb(db, (readDb) => {
             try {
                 const rows = readDb
-                    .prepare(`SELECT entry_id, file_path, file_type, body_hash, confidence, status, reason
+                    .prepare(`SELECT file_path, file_type, body_hash, confidence, status, reason
                 FROM graph_files
                 WHERE stash_root = ?
                 ORDER BY file_order`)
                     .all(stashPath);
                 return rows.map((row) => ({
-                    entryId: row.entry_id,
                     path: row.file_path,
                     type: row.file_type,
                     bodyHash: row.body_hash,
@@ -222,13 +209,16 @@ export function loadGraphFilesOnly(stashPath, db) {
     }
 }
 /**
- * Scoped loader — entities for a single entry_id. Used by per-asset lookups.
+ * Scoped loader — entities for a single file, keyed on the #624-P1 composite
+ * (stash_root, file_path, body_hash). Used by per-asset show/curate lookups.
  */
-export function loadGraphEntitiesByEntry(db, entryId) {
+export function loadGraphEntitiesByPath(db, stashRoot, filePath, bodyHash) {
     try {
         const rows = db
-            .prepare("SELECT entity FROM graph_file_entities WHERE entry_id = ? ORDER BY entity_order")
-            .all(entryId);
+            .prepare(`SELECT entity FROM graph_file_entities
+          WHERE stash_root = ? AND file_path = ? AND body_hash = ?
+          ORDER BY entity_order`)
+            .all(stashRoot, filePath, bodyHash);
         return rows.map((r) => r.entity);
     }
     catch {
@@ -314,27 +304,32 @@ export function loadStoredGraphSnapshot(stashPath, db) {
                 return null;
             try {
                 const fileRows = readDb
-                    .prepare(`SELECT entry_id, file_path, file_type, body_hash, confidence, status, reason, extraction_run_id
+                    .prepare(`SELECT file_path, file_type, body_hash, confidence, status, reason, extraction_run_id
               FROM graph_files
               WHERE stash_root = ?
               ORDER BY file_order`)
                     .all(stashPath);
                 const entityRows = readDb
-                    .prepare(`SELECT gfe.entry_id AS entry_id, gf.file_path AS file_path, gfe.entity AS entity
+                    .prepare(`SELECT gf.file_path AS file_path, gfe.entity AS entity
              FROM graph_file_entities gfe
-             JOIN graph_files gf ON gf.entry_id = gfe.entry_id
+             JOIN graph_files gf
+               ON gf.stash_root = gfe.stash_root
+              AND gf.file_path = gfe.file_path
+              AND gf.body_hash = gfe.body_hash
              WHERE gf.stash_root = ?
              ORDER BY gf.file_order, gfe.entity_order`)
                     .all(stashPath);
                 const relationRows = readDb
-                    .prepare(`SELECT gfr.entry_id AS entry_id,
-                    gf.file_path AS file_path,
+                    .prepare(`SELECT gf.file_path AS file_path,
                     gfr.from_entity AS from_entity,
                     gfr.to_entity AS to_entity,
                     gfr.relation_type AS relation_type,
                     gfr.confidence AS confidence
              FROM graph_file_relations gfr
-             JOIN graph_files gf ON gf.entry_id = gfr.entry_id
+             JOIN graph_files gf
+               ON gf.stash_root = gfr.stash_root
+              AND gf.file_path = gfr.file_path
+              AND gf.body_hash = gfr.body_hash
              WHERE gf.stash_root = ?
              ORDER BY gf.file_order, gfr.relation_order`)
                     .all(stashPath);

package/dist/indexer/graph/graph-boost.js

@@ -241,13 +241,18 @@ export function collectGraphRelatedHit(context, filePath) {
  * Find graph files that share entities with the given file.
  *
  * Implementation: SQL self-join on graph_file_entities, scoped by stash_root,
- * grouped by entry_id, ordered by shared-entity count desc. Touches ~50-200
+ * grouped by file_path, ordered by shared-entity count desc. Touches ~50-200
  * rows instead of loading the entire snapshot into memory. Cold-call latency
  * drops from ~30-60ms (full snapshot parse) to ~2-5ms on typical stashes.
  *
+ * #624-P1: the graph tables are keyed on (stash_root, file_path, body_hash) —
+ * NOT entries.id — so candidates are identified by file_path (the unique index
+ * idx_graph_files_path guarantees one graph_files row per path).
+ *
  * The returned `ref` field carries the canonical asset ref (`type:name`)
- * resolved from entries.entry_key when the entry is indexed. Callers should
- * fall back to formatting `path` when `ref` is undefined (orphan graph row).
+ * resolved from entries.entry_key when the file is indexed. Callers should
+ * fall back to formatting `path` when `ref` is undefined (graph row with no
+ * matching entries row).
  */
 export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
     if (!db) {
@@ -255,113 +260,118 @@ export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
         // callers pass a handle), so degrade to empty rather than reopening.
         return [];
     }
-    // Resolve target's entry_id from the stash_root + file_path. The graph rows
-    // are keyed on entry_id; without it we can't run the join.
-    let targetEntryId;
+    // Confirm the target file has a graph row; without it there is nothing to
+    // relate. (Identity is file_path within the stash — one row per path.)
     try {
         const row = db
-            .prepare("SELECT entry_id FROM graph_files WHERE stash_root = ? AND file_path = ? LIMIT 1")
+            .prepare("SELECT 1 AS present FROM graph_files WHERE stash_root = ? AND file_path = ? LIMIT 1")
             .get(stashRoot, filePath);
-        targetEntryId = row?.entry_id;
+        if (row === undefined)
+            return [];
     }
     catch {
         return [];
     }
-    if (targetEntryId == null)
-        return [];
     const effectiveLimit = Math.max(1, limit);
-    // Shared-entity count per candidate entry_id.
+    // Shared-entity count per candidate file_path. The target's entities are the
+    // rows for `filePath`; candidates are any OTHER file_path in the stash that
+    // shares a normalized entity.
     let candidateRows;
     try {
         candidateRows = db
-            .prepare(`SELECT gf.entry_id    AS entry_id,
-                gf.file_path   AS file_path,
+            .prepare(`SELECT gf.file_path   AS file_path,
                 gf.file_type   AS file_type,
                 COUNT(*)       AS shared
             FROM graph_file_entities target
             JOIN graph_file_entities e
               ON e.stash_root = target.stash_root
              AND e.entity_norm = target.entity_norm
-             AND e.entry_id  != target.entry_id
+             AND e.file_path  != target.file_path
             JOIN graph_files gf
-              ON gf.entry_id = e.entry_id
-          WHERE target.entry_id  = ?
+              ON gf.stash_root = e.stash_root
+             AND gf.file_path = e.file_path
+             AND gf.body_hash = e.body_hash
+          WHERE target.file_path  = ?
             AND target.stash_root = ?
-          GROUP BY gf.entry_id
+          GROUP BY gf.file_path
           ORDER BY shared DESC, gf.file_path ASC
           LIMIT ?`)
-            .all(targetEntryId, stashRoot, effectiveLimit);
+            .all(filePath, stashRoot, effectiveLimit);
     }
     catch {
         return [];
     }
     if (candidateRows.length === 0)
         return [];
-    const candidateIds = candidateRows.map((r) => r.entry_id);
-    const placeholders = candidateIds.map(() => "?").join(",");
+    const candidatePaths = candidateRows.map((r) => r.file_path);
+    const placeholders = candidatePaths.map(() => "?").join(",");
     // Pull the shared entity names (joined by normalized casing) for display.
     const sharedRows = db
-        .prepare(`SELECT e.entry_id AS entry_id, e.entity AS entity
+        .prepare(`SELECT e.file_path AS file_path, e.entity AS entity
          FROM graph_file_entities e
          JOIN graph_file_entities target
            ON target.stash_root = e.stash_root
            AND target.entity_norm = e.entity_norm
-         WHERE e.entry_id IN (${placeholders})
-           AND target.entry_id = ?
+         WHERE e.file_path IN (${placeholders})
+           AND e.stash_root = ?
+           AND target.file_path = ?
            AND target.stash_root = ?`)
-        .all(...candidateIds, targetEntryId, stashRoot);
-    const sharedByEntry = new Map();
+        .all(...candidatePaths, stashRoot, filePath, stashRoot);
+    const sharedByPath = new Map();
     for (const row of sharedRows) {
-        let bucket = sharedByEntry.get(row.entry_id);
+        let bucket = sharedByPath.get(row.file_path);
         if (!bucket) {
             bucket = new Set();
-            sharedByEntry.set(row.entry_id, bucket);
+            sharedByPath.set(row.file_path, bucket);
         }
         bucket.add(row.entity);
     }
     // Relation count for each candidate (relations where either endpoint
     // matches one of the shared entities).
-    const relationCountByEntry = new Map();
+    const relationCountByPath = new Map();
     const relationRows = db
-        .prepare(`SELECT entry_id, from_entity, to_entity
+        .prepare(`SELECT file_path, from_entity, to_entity
          FROM graph_file_relations
-        WHERE entry_id IN (${placeholders})`)
-        .all(...candidateIds);
+        WHERE file_path IN (${placeholders})
+          AND stash_root = ?`)
+        .all(...candidatePaths, stashRoot);
     for (const row of relationRows) {
-        const shared = sharedByEntry.get(row.entry_id);
+        const shared = sharedByPath.get(row.file_path);
         if (!shared)
             continue;
         if (shared.has(row.from_entity) || shared.has(row.to_entity)) {
-            relationCountByEntry.set(row.entry_id, (relationCountByEntry.get(row.entry_id) ?? 0) + 1);
+            relationCountByPath.set(row.file_path, (relationCountByPath.get(row.file_path) ?? 0) + 1);
         }
     }
     // Optional: ref lookup via entries.entry_key. entry_key is stored as
     // `${stash_dir}:${type}:${name}` — strip the stash-dir prefix to get the
-    // user-facing `type:name`.
-    const refByEntryId = new Map();
+    // user-facing `type:name`. Resolve by (stash_dir, file_path) now that the
+    // graph rows are no longer keyed on entries.id.
+    const refByPath = new Map();
     try {
         const entryRows = db
-            .prepare(`SELECT id, entry_key, stash_dir FROM entries WHERE id IN (${placeholders})`)
-            .all(...candidateIds);
+            .prepare(`SELECT entry_key, stash_dir, file_path FROM entries
+          WHERE file_path IN (${placeholders}) AND stash_dir = ?`)
+            .all(...candidatePaths, stashRoot);
         for (const row of entryRows) {
             const ref = stripStashPrefix(row.entry_key, row.stash_dir);
             if (ref)
-                refByEntryId.set(row.id, ref);
+                refByPath.set(row.file_path, ref);
         }
     }
     catch {
         /* ignore — refs are best-effort */
     }
     return candidateRows.map((row) => {
-        const sharedSet = sharedByEntry.get(row.entry_id) ?? new Set();
+        const sharedSet = sharedByPath.get(row.file_path) ?? new Set();
         const sharedEntities = [...sharedSet].sort((a, b) => a.localeCompare(b));
-        const ref = refByEntryId.get(row.entry_id);
+        const ref = refByPath.get(row.file_path);
         return {
             ...(ref ? { ref } : {}),
             path: row.file_path,
             type: row.file_type,
             sharedEntities,
-            relationCount: relationCountByEntry.get(row.entry_id) ?? 0,
+            relationCount: relationCountByPath.get(row.file_path) ?? 0,
         };
     });
 }

package/dist/indexer/passes/memory-inference.js

@@ -425,10 +425,17 @@ function markParentProcessed(parent) {
         warn(`memory inference: failed to re-read parent ${parent.filePath}: ${err instanceof Error ? err.message : String(err)}`);
         return;
     }
-    const updatedFm = { ...parent.data, [FM_INFERENCE_PROCESSED]: true };
     const block = parseFrontmatterBlock(raw);
-    const body = block?.content ?? raw;
-    const next = assembleAsset(updatedFm, body);
+    if (!block) {
+        // Cannot safely rewrite malformed frontmatter — skip marking so the memory
+        // is retried on the next run once the frontmatter is repaired. Writing with
+        // `body = raw` would wrap the entire file (including the bad frontmatter)
+        // in a new block, producing a duplicate-frontmatter corruption.
+        warn(`memory inference: skipping markParentProcessed for ${parent.filePath} — could not parse frontmatter block`);
+        return;
+    }
+    const updatedFm = { ...parent.data, [FM_INFERENCE_PROCESSED]: true };
+    const next = assembleAsset(updatedFm, block.content);
     try {
         fs.writeFileSync(parent.filePath, next, "utf8");
     }

package/dist/indexer/passes/staleness-detect.js

@@ -44,6 +44,7 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import stalenessDetectSystemPrompt from "../../assets/prompts/staleness-detect-system.md" with { type: "text" };
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
 import { concurrentMap } from "../../core/concurrent.js";
@@ -319,11 +320,7 @@ function pickSimilar(candidate, all) {
     return scored.slice(0, TOP_K_SIMILAR).map((s) => s.snap);
 }
 // ── LLM dispatch ────────────────────────────────────────────────────────────
-const SYSTEM_PROMPT = "You are a belief-state classifier for a memory store. Given a candidate memory and a list of more-recent similar memories from the same store, decide whether the candidate is still current or has been superseded.\n\n" +
-    "Respond on the first line with exactly YES or NO.\n" +
-    "If YES, the second line MUST be of the form `SUPERSEDED_BY: <ref>` where <ref> is the exact ref of the superseding memory from the list provided. Do NOT invent refs.\n" +
-    "If NO, do not include any additional lines.\n" +
-    "No prose, no preamble, no markdown.";
+const SYSTEM_PROMPT = stalenessDetectSystemPrompt;
 async function askValidator(connection, candidate, allMemories, signal, timeoutMs) {
     const similar = pickSimilar(candidate, allMemories);
     if (similar.length === 0) {

package/dist/indexer/search/db-search.js

@@ -65,6 +65,7 @@ export async function searchLocal(input) {
     const includeProposed = input.includeProposed === true;
     const beliefFilter = input.beliefFilter ?? "all";
     const restrictToSources = input.restrictToSources === true;
+    const includeExcludedTypes = input.includeExcludedTypes === true;
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const allSourceDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
@@ -114,7 +115,7 @@ export async function searchLocal(input) {
                 mode: "keyword",
             };
         }
-        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources);
+        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources, includeExcludedTypes);
         return {
             hits,
             tip: hits.length === 0
@@ -131,14 +132,19 @@ export async function searchLocal(input) {
     }
 }
 // ── Database search ─────────────────────────────────────────────────────────
-async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false) {
+async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false, includeExcludedTypes = false) {
     const hasSearchableTokens = query.length > 0 && sanitizeFtsQuery(query).length > 0;
+    // #627 — resolve the default type-exclusion policy. It applies ONLY on the
+    // untyped ('any') path and only when the caller did not opt back in via
+    // `includeExcludedTypes`. When the config key is ABSENT a built-in default of
+    // ['session'] is applied; an explicit empty list disables exclusion.
+    const defaultExcludes = searchType === "any" && !includeExcludedTypes ? (config.search?.defaultExcludeTypes ?? ["session"]) : [];
     // Empty queries — including ones that sanitize down to no searchable FTS
     // tokens such as "." — should enumerate matching entries instead of
     // returning an empty result set from FTS.
     if (!hasSearchableTokens) {
         const typeFilter = searchType === "any" ? undefined : searchType;
-        const allEntries = getAllEntries(db, typeFilter);
+        const allEntries = getAllEntries(db, typeFilter, defaultExcludes);
         // Deduplicate by file path — multiple entries can share the same file
         const seenFilePaths = new Set();
         const uniqueEntries = allEntries.filter((ie) => {
@@ -187,7 +193,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const typeFilter = searchType === "any" ? undefined : searchType;
     const tEmbed0 = Date.now();
     const embeddingPromise = tryVecScores(db, query, limit * 3, config);
-    const ftsResults = searchFts(db, query, limit * 3, typeFilter);
+    const ftsResults = searchFts(db, query, limit * 3, typeFilter, defaultExcludes);
     const embeddingScores = await embeddingPromise;
     const embedMs = Date.now() - tEmbed0;
     const tRank0 = Date.now();
@@ -208,6 +214,11 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         embedScoreMap,
         getEntryById: (id) => getEntryById(db, id) ?? undefined,
         typeFilter,
+        // #627 — also exclude default-hidden types from the vector-only branch so a
+        // session asset that is a top-k vector neighbor (but not an FTS match) does
+        // not leak into default ('any') results. defaultExcludes is already []
+        // unless this is the untyped path without includeExcludedTypes.
+        excludeTypes: defaultExcludes,
     });
     // ── Scoring Phase ──────────────────────────────────────────────────────
     // Apply boosts as multiplicative factors (all boosts in a single phase

package/dist/indexer/search/ranking.js

@@ -20,6 +20,7 @@ export function normalizeFtsScores(results) {
 export function combineSearchScores(options) {
     const FTS_WEIGHT = 0.7;
     const VEC_WEIGHT = 0.3;
+    const excludeTypeSet = options.excludeTypes && options.excludeTypes.length > 0 ? new Set(options.excludeTypes) : null;
     const scored = [];
     const seenIds = new Set();
     for (const [id, { score: ftsScore, result }] of options.ftsScoreMap) {
@@ -42,6 +43,9 @@ export function combineSearchScores(options) {
             continue;
         if (options.typeFilter && found.entry.type !== options.typeFilter)
             continue;
+        // #627 — drop vector-only neighbors whose type is excluded on the default path.
+        if (excludeTypeSet?.has(found.entry.type))
+            continue;
         scored.push({
             id,
             entry: found.entry,

package/dist/integrations/harnesses/claude/session-log.js

@@ -107,6 +107,16 @@ export class ClaudeCodeProvider {
     isAvailable() {
         return fs.existsSync(claudeProjectsDir());
     }
+    /**
+     * Directory holding Claude Code's per-project session JSONL files
+     * (`~/.claude/projects`, honoring `AKM_CLAUDE_PROJECTS_DIR`). Returns `[]`
+     * when the directory does not exist on this machine. See {@link
+     * SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const dir = claudeProjectsDir();
+        return fs.existsSync(dir) ? [dir] : [];
+    }
     *readEvents(input) {
         try {
             for (const jsonlPath of this.#walkJsonl(claudeProjectsDir())) {

package/dist/integrations/harnesses/opencode/session-log.js

@@ -26,6 +26,15 @@ export class OpenCodeProvider {
     isAvailable() {
         return fs.existsSync(this.#baseDir);
     }
+    /**
+     * Directory holding opencode's per-project session metadata files
+     * (`<base>/storage/session`). Returns `[]` when it does not exist on this
+     * machine. See {@link SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const sessionRoot = path.join(this.#baseDir, "storage", "session");
+        return fs.existsSync(sessionRoot) ? [sessionRoot] : [];
+    }
     *readEvents(input) {
         // Legacy behavior: stream raw log lines from the top-level dir and `log/`
         // subdirectory. Kept to keep `getExecutionLogCandidates` working without

package/dist/integrations/session-logs/index.js

@@ -28,6 +28,22 @@ const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENO
 export function getAvailableHarnesses() {
     return HARNESSES.filter((harness) => harness.isAvailable());
 }
+/**
+ * Map each available harness to its `{ harnessName, roots }` watch target,
+ * skipping harnesses that expose no roots (absent `watchRoots()` or an empty
+ * result). This is the one stable entry point the watcher uses so it never
+ * reaches into providers directly.
+ */
+export function getWatchTargets() {
+    const targets = [];
+    for (const harness of getAvailableHarnesses()) {
+        const roots = harness.watchRoots?.() ?? [];
+        if (roots.length === 0)
+            continue;
+        targets.push({ harnessName: harness.name, roots });
+    }
+    return targets;
+}
 export function normalizeSessionTopic(text) {
     const normalized = text.replace(/\s+/g, " ").trim().toLowerCase();
     if (normalized.length < 10)