akm-cli 0.9.16 → 0.9.17-alpha.10

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

@@ -4,82 +4,103 @@
 /**
  * `index.db` FTS5 search + materialization repository.
  *
- * Owns the `entries_fts` full-text query path, per-entry projections, and the
- * explicit full recovery rebuild.
+ * Owns the `entries_fts` full-text query path, per-entry projections (the FTS
+ * row and the `entry_fragments` safe Markdown `akm show` resolves fragment
+ * selectors from), and the explicit full recovery rebuild.
+ *
+ * `entries_fts` is contentless (`content=''`, see index-entry-schema.ts): the
+ * text lives once in `entries`, and an FTS row is addressed only by its rowid
+ * (`entries.id`). The `COALESCE(f.entry_id, f.rowid)` join below also reads
+ * the content-bearing table older releases wrote (where the UNINDEXED column
+ * is populated), so a read-only open of a not-yet-migrated index still
+ * answers correctly.
  */
 import { splitMarkdownFragments } from "../../core/asset/markdown-fragments.js";
-import { stableFtsScore } from "../../core/lexical-score.js";
 import { warn } from "../../core/warn.js";
-import { buildLexicalQueryPlan } from "../../indexer/search/fts-query.js";
+import { ftsOrMatch, ftsQueryTokens } from "../../indexer/search/fts-query.js";
 import { buildSearchFields } from "../../indexer/search/search-fields.js";
 import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
-const INSERT_FTS_SQL = "INSERT INTO entries_fts (entry_id, name, description, tags, hints, content) VALUES (?, ?, ?, ?, ?, ?)";
-const INSERT_FRAGMENT_SQL = "INSERT INTO entry_fragments_fts (entry_id, fragment_id, fragment_ordinal, content) VALUES (?, ?, ?, ?)";
+// `entries_fts.rowid = entries.id`, so a per-entry delete is a rowid lookup.
+const INSERT_FTS_SQL = "INSERT INTO entries_fts (rowid, entry_id, name, description, tags, hints, content) VALUES (?, ?, ?, ?, ?, ?, ?)";
 const ftsMutationStatementsByDb = new WeakMap();
 function getFtsMutationStatements(db) {
     const existing = ftsMutationStatementsByDb.get(db);
     if (existing)
         return existing;
     const statements = {
-        deleteOne: db.prepare("DELETE FROM entries_fts WHERE entry_id = ?"),
+        deleteOne: db.prepare("DELETE FROM entries_fts WHERE rowid = ?"),
         insert: db.prepare(INSERT_FTS_SQL),
-        deleteFragments: db.prepare("DELETE FROM entry_fragments_fts WHERE entry_id = ?"),
         upsertFragmentSource: db.prepare("INSERT INTO entry_fragments (entry_id, safe_markdown) VALUES (?, ?) ON CONFLICT(entry_id) DO UPDATE SET safe_markdown = excluded.safe_markdown"),
         deleteFragmentSource: db.prepare("DELETE FROM entry_fragments WHERE entry_id = ?"),
-        insertFragment: db.prepare(INSERT_FRAGMENT_SQL),
     };
     ftsMutationStatementsByDb.set(db, statements);
     return statements;
 }
-/** Replace one entry's derived FTS projection inside the caller's transaction. */
+/**
+ * Replace one entry's derived FTS row, and its fragment source when the scan
+ * read Markdown, inside the caller's transaction.
+ */
 export function replaceFtsEntry(db, entryId, entry, fragmentContent) {
     const fields = buildSearchFields(entry);
     const statements = getFtsMutationStatements(db);
     statements.deleteOne.run(entryId);
-    statements.insert.run(entryId, fields.name, fields.description, fields.tags, fields.hints, fields.content);
+    statements.insert.run(entryId, entryId, fields.name, fields.description, fields.tags, fields.hints, fields.content);
     if (fragmentContent === undefined) {
         // Metadata-only re-upserts and re-keys deserialize the public document
         // without the internal substrate. Leave the persisted source untouched.
         // A scan that did read Markdown always supplies a value below.
         return;
     }
-    statements.deleteFragments.run(entryId);
-    statements.deleteFragmentSource.run(entryId);
-    if (!fragmentContent)
-        return;
-    statements.upsertFragmentSource.run(entryId, fragmentContent);
-    for (const fragment of splitMarkdownFragments(fragmentContent)) {
-        statements.insertFragment.run(entryId, fragment.fragmentId, fragment.ordinal, fragment.text.toLowerCase());
-    }
+    if (fragmentContent)
+        statements.upsertFragmentSource.run(entryId, fragmentContent);
+    else
+        statements.deleteFragmentSource.run(entryId);
 }
-/** Delete derived FTS projections for canonical entries that are being removed. */
+/** Delete the FTS rows and fragment sources of canonical entries that are being removed. */
 export function deleteFtsEntries(db, entryIds) {
     for (let i = 0; i < entryIds.length; i += SQLITE_CHUNK_SIZE) {
         const chunk = entryIds.slice(i, i + SQLITE_CHUNK_SIZE);
         const placeholders = chunk.map(() => "?").join(",");
-        db.prepare(`DELETE FROM entries_fts WHERE entry_id IN (${placeholders})`).run(...chunk);
-        db.prepare(`DELETE FROM entry_fragments_fts WHERE entry_id IN (${placeholders})`).run(...chunk);
+        db.prepare(`DELETE FROM entries_fts WHERE rowid IN (${placeholders})`).run(...chunk);
         db.prepare(`DELETE FROM entry_fragments WHERE entry_id IN (${placeholders})`).run(...chunk);
     }
 }
-export function searchFts(db, query, limit, entryType, excludeTypes) {
-    const plan = buildLexicalQueryPlan(query);
-    if (!plan.exact)
+/**
+ * BM25 per-column weights for `entries_fts(entry_id, name, description, tags,
+ * hints, content)`. `entry_id` is UNINDEXED and carries no weight.
+ */
+const BM25_COLUMN_WEIGHTS = "0, 1.0, 1.0, 1.0, 1.0, 1.0";
+/**
+ * The top `limit` entries matching ANY of the query's tokens
+ * (`ftsQueryTokens`), best whole-document BM25 first; equal scores are
+ * ordered by `item_ref` so the ranking is deterministic. Fragments play no
+ * part: whole-document BM25 beat the fragment population by 0.059 nDCG@10 on
+ * the retrieval suite.
+ *
+ * `entryType` narrows to one type; otherwise `excludeTypes` (#627, the
+ * default-hidden types such as `session`) are left out.
+ */
+export function searchFts(db, query, limit, entryType, excludeTypes = []) {
+    const tokens = ftsQueryTokens(query);
+    if (limit <= 0 || tokens.length === 0)
         return [];
-    // Try the exact AND query first
-    const exactResults = runFtsQuery(db, plan.exact, "exact", limit, entryType, excludeTypes);
-    if (exactResults.length > 0)
-        return exactResults;
-    if (plan.exactPrefix) {
-        const prefixResults = runFtsQuery(db, plan.exactPrefix, "prefix", limit, entryType, excludeTypes);
-        if (prefixResults.length > 0)
-            return prefixResults;
-    }
-    // One measured relaxation only after both conjunctive forms miss. This is
-    // still the same FTS table, BM25 weights, candidate collection, and
-    // downstream ranker — merely an OR candidate query for sentence-shaped
-    // input whose filler terms prevented a strict hit.
-    return plan.relaxed ? runFtsQuery(db, plan.relaxed, "relaxed", limit, entryType, excludeTypes) : [];
+    const typed = entryType !== undefined && entryType !== "any";
+    const filter = typed
+        ? "AND e.type = ?"
+        : excludeTypes.length > 0
+            ? `AND e.type NOT IN (${excludeTypes.map(() => "?").join(", ")})`
+            : "";
+    const params = [ftsOrMatch(tokens), ...(typed ? [entryType] : excludeTypes), limit];
+    // Contentless FTS rows address their entry by rowid; the COALESCE also reads
+    // the content-bearing layout older releases wrote.
+    return db
+        .prepare(`SELECT e.id AS id, e.item_ref AS itemRef
+         FROM entries_fts f
+         JOIN entries e ON e.id = COALESCE(f.entry_id, f.rowid)
+        WHERE entries_fts MATCH ? ${filter}
+        ORDER BY bm25(entries_fts, ${BM25_COLUMN_WEIGHTS}), e.item_ref
+        LIMIT ?`)
+        .all(...params);
 }
 /**
  * Resolve an opaque fragment selector from the indexed safe projection, not
@@ -87,40 +108,14 @@ export function searchFts(db, query, limit, entryType, excludeTypes) {
  * file edit; the next index refresh atomically publishes the new revision.
  */
 export function getIndexedMarkdownFragment(db, itemRef, fragmentId) {
-    return getIndexedMarkdownFragments(db, [{ itemRef, fragmentId }])[0];
-}
-/**
- * Batch the selected-hit projection read. Search commonly enriches several
- * fragment hits at once; reading all indexed-safe parents in chunks avoids an
- * N-query loop, while grouping selectors by parent ensures each safe revision
- * is split at most once.
- */
-export function getIndexedMarkdownFragments(db, selections) {
-    if (selections.length === 0)
-        return [];
-    const itemRefs = [...new Set(selections.map((selection) => selection.itemRef))];
-    const sourceByRef = new Map();
-    for (let offset = 0; offset < itemRefs.length; offset += SQLITE_CHUNK_SIZE) {
-        const chunk = itemRefs.slice(offset, offset + SQLITE_CHUNK_SIZE);
-        const placeholders = chunk.map(() => "?").join(",");
-        const rows = db
-            .prepare(`SELECT e.item_ref, s.safe_markdown FROM entry_fragments s JOIN entries e ON e.id = s.entry_id WHERE e.item_ref IN (${placeholders})`)
-            .all(...chunk);
-        for (const row of rows)
-            sourceByRef.set(row.item_ref, row.safe_markdown);
-    }
-    const fragmentsByRef = new Map();
-    for (const [itemRef, safeMarkdown] of sourceByRef) {
-        fragmentsByRef.set(itemRef, splitMarkdownFragments(safeMarkdown));
-    }
-    return selections.map((selection) => {
-        const safeMarkdown = sourceByRef.get(selection.itemRef);
-        const fragments = fragmentsByRef.get(selection.itemRef);
-        if (safeMarkdown === undefined || !fragments)
-            return undefined;
-        const fragment = fragments.find((candidate) => candidate.fragmentId === selection.fragmentId || candidate.headingSlug === selection.fragmentId);
-        return fragment ? materializeIndexedMarkdownFragment(fragment, fragments, safeMarkdown.length) : undefined;
-    });
+    const row = db
+        .prepare("SELECT s.safe_markdown FROM entry_fragments s JOIN entries e ON e.id = s.entry_id WHERE e.item_ref = ?")
+        .get(itemRef);
+    if (row === undefined)
+        return undefined;
+    const fragments = splitMarkdownFragments(row.safe_markdown);
+    const fragment = fragments.find((candidate) => candidate.fragmentId === fragmentId || candidate.headingSlug === fragmentId);
+    return fragment ? materializeIndexedMarkdownFragment(fragment, fragments, row.safe_markdown.length) : undefined;
 }
 function materializeIndexedMarkdownFragment(fragment, fragments, parentChars) {
     return {
@@ -136,170 +131,8 @@ function materializeIndexedMarkdownFragment(fragment, fragments, parentChars) {
         fragments,
     };
 }
-function runFtsQuery(db, ftsQuery, lexicalMatch, limit, entryType, excludeTypes) {
-    // Preserve the repository's ordinary limit contract for direct callers.
-    // The boundary-expansion rule applies only to a positive candidate pool.
-    if (limit <= 0)
-        return [];
-    // #627 — exclude-type clause. Only applies on the untyped ('any') path; an
-    // explicit include filter (entryType) already narrows to a single type, so
-    // 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 : [];
-    const candidateBoundaryOffset = Math.max(0, limit - 1);
-    // The typed and untyped paths differ only by one `type` WHERE clause
-    // equality vs. an optional NOT IN exclusion) and their parameter order.
-    // Join on integer entry_id directly (no CAST; we store integer). bm25()
-    // per-column weights:
-    // entry_id(0), name(10), description(5), tags(3), hints(2), content(1).
-    let filterClause;
-    let params;
-    if (entryType && entryType !== "any") {
-        filterClause = "AND e.type = ?";
-        params = [ftsQuery, entryType, candidateBoundaryOffset];
-    }
-    else {
-        filterClause = excludes.length > 0 ? `AND e.type NOT IN (${excludes.map(() => "?").join(", ")})` : "";
-        // Param order: MATCH, then the NOT IN values, then the zero-based
-        // candidate-boundary offset.
-        params = [ftsQuery, ...excludes, candidateBoundaryOffset];
-    }
-    const sql = `
-    -- Do not make a SQL-only relevance decision inside a tied BM25 boundary:
-    -- the TypeScript ranker adds exact-name, type, and other contributors
-    -- afterwards.  Materialize BM25 once, locate the Nth score, and admit
-    -- every row tied with it.  This deliberately makes the result set
-    -- data-bound for a pathological all-tied query; that is the only way to
-    -- avoid silently dropping a legitimate later ranking winner.
-    WITH scored AS MATERIALIZED (
-      -- Keep this materialized set deliberately narrow. document_json can be
-      -- large, and only rows admitted through the BM25 boundary need it.
-      SELECT e.id, bm25(entries_fts, 0, 10.0, 5.0, 3.0, 2.0, 1.0) AS bm25Score
-    FROM entries_fts f
-    JOIN entries e ON e.id = f.entry_id
-    WHERE entries_fts MATCH ?
-      ${filterClause}
-    ), boundary AS (
-      SELECT bm25Score
-      FROM scored
-      ORDER BY bm25Score
-      LIMIT 1 OFFSET ?
-    )
-    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,
-           scored.bm25Score
-    FROM scored
-    JOIN entries e ON e.id = scored.id
-    WHERE NOT EXISTS (SELECT 1 FROM boundary)
-       OR scored.bm25Score <= (SELECT bm25Score FROM boundary)
-    ORDER BY scored.bm25Score, e.id ASC
-  `;
-    const rows = db.prepare(sql).all(...params);
-    const results = materializeRows(rows, lexicalMatch);
-    // Fragments are a separate, intentionally calibrated evidence population:
-    // parent FTS remains the sole implementation of metadata/body conjunction.
-    // A selector is emitted only for one fragment that independently satisfies
-    // this query. Raw BM25 values are never claimed comparable across tables;
-    // each is passed through #933's stable mapping before merge.
-    const fragmentResults = hasFragmentFts(db)
-        ? runFragmentQuery(db, ftsQuery, lexicalMatch, limit, entryType, excludes)
-        : [];
-    return mergeParentAndFragmentResults(results, fragmentResults);
-}
-function hasFragmentFts(db) {
-    return Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'entry_fragments_fts'").get());
-}
-function materializeRows(rows, lexicalMatch) {
-    const results = [];
-    for (const row of rows) {
-        let entry;
-        try {
-            entry = JSON.parse(row.documentJson);
-        }
-        catch {
-            warn(`[db] searchFts: skipping entry id=${row.id} — corrupt document_json`);
-            continue;
-        }
-        results.push({
-            id: row.id,
-            filePath: row.filePath,
-            entry,
-            searchText: row.searchText,
-            bm25Score: row.bm25Score,
-            itemRef: row.itemRef,
-            bundleId: row.bundleId,
-            conceptId: row.conceptId,
-            adapterId: row.adapterId,
-            lexicalMatch,
-        });
-    }
-    return results;
-}
-function runFragmentQuery(db, ftsQuery, lexicalMatch, limit, entryType, excludes) {
-    const filter = entryType && entryType !== "any"
-        ? "AND e.type = ?"
-        : excludes.length
-            ? `AND e.type NOT IN (${excludes.map(() => "?").join(",")})`
-            : "";
-    const filterParams = entryType && entryType !== "any" ? [entryType] : excludes;
-    const candidateBoundaryOffset = Math.max(0, limit - 1);
-    // Select the winning child per parent inside SQLite before finding the
-    // candidate boundary. A document with many matching fragments therefore
-    // occupies one parent slot, while a boundary tie retains every parent for
-    // the TypeScript ranker to decide with its non-BM25 contributors. This has
-    // one FTS query and no OFFSET walk; the returned boundary is intentionally
-    // data-bound for a pathological all-tied query, just like parent FTS.
-    const sql = `
-    WITH matches AS MATERIALIZED (
-      -- Keep repeated child rows as narrow as parent FTS's scored CTE. The
-      -- document projection can be large; hydrate it only after the one-child
-      -- per-parent collapse and BM25 boundary filtering below.
-      SELECT e.id, f.fragment_id AS fragmentId, f.fragment_ordinal AS fragmentOrdinal,
-             bm25(entry_fragments_fts) AS bm25Score
-      FROM entry_fragments_fts f JOIN entries e ON e.id = f.entry_id
-      WHERE entry_fragments_fts MATCH ? ${filter}
-    ), ranked AS MATERIALIZED (
-      SELECT *, ROW_NUMBER() OVER (PARTITION BY id ORDER BY bm25Score ASC, fragmentOrdinal ASC, fragmentId ASC) AS parentRank
-      FROM matches
-    ), parents AS MATERIALIZED (
-      SELECT * FROM ranked WHERE parentRank = 1
-    ), boundary AS (
-      SELECT bm25Score FROM parents ORDER BY bm25Score ASC LIMIT 1 OFFSET ?
-    )
-    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,
-           parents.fragmentId, parents.bm25Score
-    FROM parents JOIN entries e ON e.id = parents.id
-    WHERE NOT EXISTS (SELECT 1 FROM boundary)
-       OR parents.bm25Score <= (SELECT bm25Score FROM boundary)
-    ORDER BY parents.bm25Score ASC, parents.id ASC`;
-    const rows = db.prepare(sql).all(ftsQuery, ...filterParams, candidateBoundaryOffset);
-    const results = [];
-    for (const row of rows) {
-        const [result] = materializeRows([row], lexicalMatch);
-        if (result) {
-            results.push({
-                ...result,
-                fragmentId: row.fragmentId,
-                lexicalScore: stableFtsScore(result.bm25Score, "fragment"),
-            });
-        }
-    }
-    return results;
-}
-function mergeParentAndFragmentResults(parents, fragments) {
-    const winners = new Map();
-    for (const parent of parents)
-        winners.set(parent.id, { ...parent, lexicalScore: stableFtsScore(parent.bm25Score) });
-    for (const fragment of fragments) {
-        const existing = winners.get(fragment.id);
-        if (!existing || (fragment.lexicalScore ?? 0) > (existing.lexicalScore ?? 0))
-            winners.set(fragment.id, fragment);
-    }
-    return [...winners.values()].sort((left, right) => (right.lexicalScore ?? 0) - (left.lexicalScore ?? 0) || left.id - right.id);
-}
 /**
- * Explicitly rebuild the complete FTS5 projection from canonical entries.
+ * Explicitly rebuild `entries_fts` from canonical entries.
  * Ordinary entry mutations do not call this: `upsertEntry` and the delete
  * operations publish their FTS state in the same transaction as `entries`.
  * This remains a recovery/schema-verification primitive for regenerable
@@ -311,29 +144,26 @@ function mergeParentAndFragmentResults(parents, fragments) {
 export function rebuildFts(db) {
     db.transaction(() => {
         db.exec("DELETE FROM entries_fts");
-        db.exec("DELETE FROM entry_fragments_fts");
-        const rows = db
-            .prepare("SELECT e.id, e.document_json, f.safe_markdown FROM entries e LEFT JOIN entry_fragments f ON f.entry_id = e.id")
-            .all();
+        // Keyset pages, so a large index is never held in memory at once.
+        const page = db.prepare("SELECT id, document_json FROM entries WHERE id > ? ORDER BY id LIMIT 500");
         const insertStmt = db.prepare(INSERT_FTS_SQL);
-        const fragmentStmt = db.prepare(INSERT_FRAGMENT_SQL);
         let skipped = 0;
-        for (const row of rows) {
-            let entry;
-            let fields;
-            try {
-                entry = JSON.parse(row.document_json);
-                fields = buildSearchFields(entry);
-            }
-            catch {
-                skipped++;
-                continue;
-            }
-            insertStmt.run(row.id, fields.name, fields.description, fields.tags, fields.hints, fields.content);
-            if (row.safe_markdown) {
-                for (const fragment of splitMarkdownFragments(row.safe_markdown)) {
-                    fragmentStmt.run(row.id, fragment.fragmentId, fragment.ordinal, fragment.text.toLowerCase());
+        let afterId = -1;
+        for (;;) {
+            const rows = page.all(afterId);
+            if (rows.length === 0)
+                break;
+            afterId = rows[rows.length - 1].id;
+            for (const row of rows) {
+                let fields;
+                try {
+                    fields = buildSearchFields(JSON.parse(row.document_json));
+                }
+                catch {
+                    skipped++;
+                    continue;
                 }
+                insertStmt.run(row.id, row.id, fields.name, fields.description, fields.tags, fields.hints, fields.content);
             }
         }
         if (skipped > 0) {

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

@@ -0,0 +1,143 @@
+// 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` declared-links repository (#935): owns every SQL statement
+ * against `asset_links`.
+ *
+ * A row belongs to the entry that declares the link and is written, replaced
+ * and deleted with that entry (`upsertEntry`, `deleteRelatedRows`). A target
+ * is stored as `dst_bundle` (NULL for a short ref, meaning the declaring
+ * entry's own bundle) plus `dst_concept`; whether it exists is a join on
+ * `entries.item_ref` at read time, so a target indexed later resolves with
+ * no rewrite of its citer and a bundle rename carries short refs along.
+ *
+ * A memory target whose own file is gone resolves to its `.derived` child, the
+ * reachability rule lint applies (#882): consolidation keeps the distilled
+ * child after the parent is pruned.
+ */
+import { declaredLinks } from "../../indexer/links/declared-links.js";
+import { tableExists } from "./index-entry-schema.js";
+import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
+const statementsByDb = new WeakMap();
+function statements(db) {
+    const existing = statementsByDb.get(db);
+    if (existing)
+        return existing;
+    const created = {
+        deleteForEntry: db.prepare("DELETE FROM asset_links WHERE entry_id = ?"),
+        insert: db.prepare("INSERT INTO asset_links (entry_id, ord, kind, raw, dst_bundle, dst_concept) VALUES (?, ?, ?, ?, ?, ?)"),
+    };
+    statementsByDb.set(db, created);
+    return created;
+}
+/** Replace one entry's declared links with the ones its document names, inside the caller's transaction. */
+export function replaceEntryLinks(db, entryId, document, owner) {
+    const { deleteForEntry, insert } = statements(db);
+    deleteForEntry.run(entryId);
+    declaredLinks(document, owner).forEach((link, ord) => {
+        insert.run(entryId, ord, link.kind, link.raw, link.bundle ?? null, link.conceptId);
+    });
+}
+/** Delete the declared links of entries that are being removed. */
+export function deleteEntryLinks(db, entryIds) {
+    for (let i = 0; i < entryIds.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = entryIds.slice(i, i + SQLITE_CHUNK_SIZE);
+        db.prepare(`DELETE FROM asset_links WHERE entry_id IN (${chunk.map(() => "?").join(",")})`).run(...chunk);
+    }
+}
+/**
+ * Derive every entry's links from its stored `document_json`, replacing
+ * whatever the table held — the in-place migration to layout 26, which needs
+ * no file read. An entry whose JSON does not parse keeps no links until it is
+ * next indexed.
+ */
+export function rebuildAllEntryLinks(db) {
+    db.exec("DELETE FROM asset_links");
+    const page = db.prepare("SELECT id, bundle_id, concept_id, document_json FROM entries WHERE id > ? ORDER BY id LIMIT 500");
+    let afterId = -1;
+    for (;;) {
+        const rows = page.all(afterId);
+        if (rows.length === 0)
+            break;
+        afterId = rows[rows.length - 1].id;
+        for (const row of rows) {
+            let document;
+            try {
+                document = JSON.parse(row.document_json);
+            }
+            catch {
+                continue;
+            }
+            replaceEntryLinks(db, row.id, document, { bundleId: row.bundle_id, conceptId: row.concept_id });
+        }
+    }
+}
+/**
+ * The id of the entry a link row resolves to, or NULL: the exact target, else
+ * (for a memory) its `.derived` child, never the declaring entry itself.
+ * Expects `l` (the link) and `o` (its owner) in scope.
+ */
+const TARGET_ID_SQL = `COALESCE(
+    (SELECT id FROM entries WHERE item_ref = COALESCE(l.dst_bundle, o.bundle_id) || '//' || l.dst_concept),
+    (SELECT id FROM entries
+      WHERE item_ref = COALESCE(l.dst_bundle, o.bundle_id) || '//' || l.dst_concept || '.derived'
+        AND substr(l.dst_concept, 1, 9) = 'memories/' AND id <> o.id))`;
+/**
+ * The declared links of the entry `itemRef`, both ways: `outgoing` in stored
+ * order (unresolved targets carry only `raw`), `incoming` from every other
+ * entry that names it, ordered by kind then source. An index that predates
+ * the table (an older layout served as-is) has none.
+ */
+export function readEntryLinks(db, itemRef) {
+    if (!tableExists(db, "asset_links"))
+        return { outgoing: [], incoming: [] };
+    const owner = db.prepare("SELECT id, bundle_id, concept_id FROM entries WHERE item_ref = ?").get(itemRef);
+    if (!owner)
+        return { outgoing: [], incoming: [] };
+    const outgoing = db
+        .prepare(`SELECT l.kind AS kind, l.raw AS raw, t.bundle_id AS bundleId, t.concept_id AS conceptId, t.type AS type
+         FROM asset_links l
+         JOIN entries o ON o.id = l.entry_id
+         LEFT JOIN entries t ON t.id = ${TARGET_ID_SQL}
+        WHERE l.entry_id = ?
+        ORDER BY l.ord`)
+        .all(owner.id);
+    // A `.derived` memory also receives the links that name its parent when the
+    // parent is not indexed (the resolution rule above).
+    const parentConcept = owner.concept_id.startsWith("memories/") && owner.concept_id.endsWith(".derived")
+        ? owner.concept_id.slice(0, -".derived".length)
+        : owner.concept_id;
+    const incoming = db
+        .prepare(`SELECT l.kind AS kind, o.bundle_id AS bundleId, o.concept_id AS conceptId, o.type AS type
+         FROM asset_links l
+         JOIN entries o ON o.id = l.entry_id
+        WHERE l.dst_concept IN (?, ?) AND COALESCE(l.dst_bundle, o.bundle_id) = ? AND o.id <> ?
+          AND ${TARGET_ID_SQL} = ?
+        ORDER BY l.kind, o.item_ref`)
+        .all(owner.concept_id, parentConcept, owner.bundle_id, owner.id, owner.id);
+    return {
+        outgoing: outgoing.map((row) => row.conceptId === null
+            ? { kind: row.kind, raw: row.raw }
+            : {
+                kind: row.kind,
+                bundleId: row.bundleId ?? undefined,
+                conceptId: row.conceptId,
+                type: row.type ?? undefined,
+            }),
+        incoming,
+    };
+}
+/** Stored links per kind with how many name a target that is not indexed; empty when the index has none. */
+export function countLinksByKind(db) {
+    if (!tableExists(db, "asset_links"))
+        return {};
+    const rows = db
+        .prepare(`SELECT l.kind AS kind, COUNT(*) AS total, SUM(${TARGET_ID_SQL} IS NULL) AS unresolved
+         FROM asset_links l
+         JOIN entries o ON o.id = l.entry_id
+        GROUP BY l.kind
+        ORDER BY l.kind`)
+        .all();
+    return Object.fromEntries(rows.map((row) => [row.kind, { total: row.total, unresolved: row.unresolved }]));
+}

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

@@ -4,8 +4,9 @@
 /**
  * `index.db` LLM enrichment-cache repository.
  *
- * Owns the raw SQL for `llm_enrichment_cache` — the body-hash-keyed cache that
- * lets `akm index --enrich` skip the LLM call when a file's body is unchanged.
+ * Owns the raw SQL for `llm_enrichment_cache` — the body-hash-keyed cache the
+ * graph-extraction and memory-inference passes use to skip an LLM call when
+ * a file's body is unchanged.
  */
 import { sha256Hex } from "../../runtime.js";
 import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
@@ -17,7 +18,7 @@ import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
  * cached). In both cases the caller should invoke the LLM and write a new
  * cache entry.
  */
-export function getLlmCacheEntry(db, assetRef, currentBodyHash, cacheVariant = "") {
+export function getLlmCacheEntry(db, assetRef, currentBodyHash, cacheVariant) {
     const row = db
         .prepare("SELECT asset_ref, cache_variant, body_hash, result_json, updated_at FROM llm_enrichment_cache WHERE asset_ref = ? AND cache_variant = ?")
         .get(assetRef, cacheVariant);
@@ -43,7 +44,7 @@ export function getLlmCacheEntry(db, assetRef, currentBodyHash, cacheVariant = "
  * compare `entry.bodyHash` against the current body hash themselves. This lets
  * the batch path issue one DB query per chunk instead of one per file.
  */
-export function getLlmCacheEntriesByRefs(db, refs, cacheVariant = "") {
+export function getLlmCacheEntriesByRefs(db, refs, cacheVariant) {
     const result = new Map();
     if (refs.length === 0)
         return result;
@@ -69,7 +70,7 @@ export function getLlmCacheEntriesByRefs(db, refs, cacheVariant = "") {
 /**
  * Insert or update a cached LLM result for the given asset_ref.
  */
-export function upsertLlmCacheEntry(db, assetRef, bodyHash, resultJson, cacheVariant = "") {
+export function upsertLlmCacheEntry(db, assetRef, bodyHash, resultJson, cacheVariant) {
     db.prepare(`INSERT INTO llm_enrichment_cache (asset_ref, cache_variant, body_hash, result_json, updated_at)
      VALUES (?, ?, ?, ?, ?)
      ON CONFLICT(asset_ref, cache_variant) DO UPDATE SET
@@ -82,15 +83,12 @@ export function upsertLlmCacheEntry(db, assetRef, bodyHash, resultJson, cacheVar
  * `entries` table. Should be called during the cleanup phase of each index
  * run to prevent the cache from growing unboundedly as assets are removed.
  *
- * Graph/memory cache refs are absolute file paths, while metadata-enrichment
- * refs use canonical `item_ref`; preserve a cache row that matches either
- * current identity.
+ * Cache refs are absolute file paths (memory inference).
  */
 export function clearStaleCacheEntries(db) {
     db.exec(`
     DELETE FROM llm_enrichment_cache
     WHERE asset_ref NOT IN (SELECT file_path FROM entries)
-      AND asset_ref NOT IN (SELECT item_ref FROM entries)
   `);
 }
 /**

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

@@ -23,7 +23,7 @@ export function deleteMeta(db, key) {
 // ── Per-directory index state ───────────────────────────────────────────────
 export function getIndexDirState(db, dirPath) {
     const row = db
-        .prepare("SELECT dir_path, file_set_hash, file_mtime_max_ms, reason, updated_at, row_count FROM index_dir_state WHERE dir_path = ?")
+        .prepare("SELECT dir_path, file_set_hash, file_mtime_max_ms, reason, updated_at, row_count, index_variant FROM index_dir_state WHERE dir_path = ?")
         .get(dirPath);
     if (!row)
         return undefined;
@@ -34,17 +34,19 @@ export function getIndexDirState(db, dirPath) {
         reason: row.reason,
         updatedAt: row.updated_at,
         rowCount: row.row_count ?? undefined,
+        indexVariant: row.index_variant ?? undefined,
     };
 }
 export function upsertIndexDirState(db, state) {
-    db.prepare(`INSERT INTO index_dir_state (dir_path, file_set_hash, file_mtime_max_ms, reason, updated_at, row_count)
-     VALUES (?, ?, ?, ?, ?, ?)
+    db.prepare(`INSERT INTO index_dir_state (dir_path, file_set_hash, file_mtime_max_ms, reason, updated_at, row_count, index_variant)
+     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,
-       row_count = excluded.row_count`).run(state.dirPath, state.fileSetHash, state.fileMtimeMaxMs, state.reason, new Date().toISOString(), state.rowCount ?? null);
+       row_count = excluded.row_count,
+       index_variant = excluded.index_variant`).run(state.dirPath, state.fileSetHash, state.fileMtimeMaxMs, state.reason, new Date().toISOString(), state.rowCount ?? null, state.indexVariant ?? null);
 }
 export function deleteIndexDirState(db, dirPath) {
     db.prepare("DELETE FROM index_dir_state WHERE dir_path = ?").run(dirPath);