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

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

@@ -21,6 +21,7 @@ import { buildSearchText } from "../../indexer/search/search-fields.js";
 import { sha256Hex } from "../../runtime.js";
 import { ENTRY_COLUMNS, rowToIndexedEntry } from "./index-entry-mapper.js";
 import { deleteFtsEntries, replaceFtsEntry } from "./index-fts-repository.js";
+import { deleteEntryLinks, replaceEntryLinks } from "./index-links-repository.js";
 import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
 import { deleteEntryVectors } from "./index-vec-repository.js";
 // ── Entry operations ────────────────────────────────────────────────────────
@@ -36,9 +37,9 @@ function embedHash(entry) {
  * Insert or update one canonical entry and all synchronously derived search
  * state. Returns the stable row id.
  *
- * The entries row, FTS projection, and stale-vector invalidation commit as one
- * SQLite transaction. Callers therefore cannot publish an entry and forget a
- * second FTS maintenance step.
+ * The entries row, FTS projection, declared links, and stale-vector
+ * invalidation commit as one SQLite transaction. Callers therefore cannot
+ * publish an entry and forget a second FTS or links maintenance step.
  */
 export function upsertEntry(db, filePath, entry, provenance, contentHash) {
     // Hot path during indexing — cache prepared statements per database
@@ -59,6 +60,7 @@ export function upsertEntry(db, filePath, entry, provenance, contentHash) {
         if (previous?.id === result.id && previous.embed_hash !== hash)
             deleteEntryVectors(db, result.id);
         replaceFtsEntry(db, result.id, entry, hasMarkdownFragmentContent(entry) ? (getMarkdownFragmentContent(entry) ?? null) : undefined);
+        replaceEntryLinks(db, result.id, entry, provenance);
         return result.id;
     };
     // Always enter the driver's transaction wrapper. Both supported SQLite
@@ -258,8 +260,10 @@ export function rekeyEntryInPlace(db, opts) {
         }
         if (row.embed_hash !== hash)
             deleteEntryVectors(db, row.id);
-        if (document)
+        if (document) {
             replaceFtsEntry(db, row.id, document, hasMarkdownFragmentContent(document) ? (getMarkdownFragmentContent(document) ?? null) : undefined);
+            replaceEntryLinks(db, row.id, document, { bundleId: opts.sourceName, conceptId: opts.newRef });
+        }
         else
             deleteFtsEntries(db, [row.id]);
     })();
@@ -396,9 +400,11 @@ function deleteRelatedRows(db, ids, options = {}) {
     if (ids.length === 0)
         return;
     const numericIds = ids.map((r) => r.id);
-    // FTS is part of the canonical mutation boundary, not a caller-maintained
-    // dirty queue. Delete it before the parent row inside this transaction.
+    // FTS and declared links are part of the canonical mutation boundary, not a
+    // caller-maintained dirty queue. Delete them before the parent row inside
+    // this transaction.
     deleteFtsEntries(db, numericIds);
+    deleteEntryLinks(db, numericIds);
     // Process in chunks to stay within SQLITE_MAX_VARIABLE_NUMBER
     for (let i = 0; i < numericIds.length; i += SQLITE_CHUNK_SIZE) {
         const chunk = numericIds.slice(i, i + SQLITE_CHUNK_SIZE);

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

@@ -11,6 +11,10 @@
  * touching embeddings, utility scores, graph rows, or the LLM enrichment
  * cache. A newer layout is refused, naming the upgrade.
  */
+// 26: declared links (#935) live in `asset_links`, one row per link, owned by
+// the entry that declares it. The writable opener derives them in place from
+// each entry's stored `document_json` (`migrateToDeclaredLinks`,
+// index-schema.ts); releases before 26 did not store them.
 // 25: vectors live only in `embeddings`; the sqlite-vec mirror `entries_vec`
 // is dropped (`dropVecMirror`, index-schema.ts), and so is the fragment FTS
 // table `entry_fragments_fts`, which search no longer reads. `entries` keeps
@@ -21,7 +25,7 @@
 // 23 and earlier stored a second copy of every indexed field in FTS5's own
 // content shadow tables. `ensureFtsLayout` (index-schema.ts) rebuilds the FTS
 // tables from the stored entries when it finds the older layout.
-export const CANONICAL_INDEX_DB_VERSION = 25;
+export const CANONICAL_INDEX_DB_VERSION = 26;
 export const CANONICAL_ENTRY_SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS entries (
     id            INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -47,6 +51,19 @@ export const CANONICAL_ENTRY_SCHEMA_SQL = `
     entry_id INTEGER PRIMARY KEY REFERENCES entries(id) ON DELETE CASCADE,
     safe_markdown TEXT NOT NULL
   );
+
+  -- Declared links (#935). dst_bundle NULL: the declaring entry's own bundle.
+  CREATE TABLE IF NOT EXISTS asset_links (
+    entry_id    INTEGER NOT NULL REFERENCES entries(id) ON DELETE CASCADE,
+    ord         INTEGER NOT NULL,
+    kind        TEXT NOT NULL,
+    raw         TEXT NOT NULL,
+    dst_bundle  TEXT,
+    dst_concept TEXT NOT NULL,
+    PRIMARY KEY (entry_id, ord)
+  ) WITHOUT ROWID;
+
+  CREATE INDEX IF NOT EXISTS idx_asset_links_dst ON asset_links(dst_concept);
 `;
 // The FTS table is contentless: FTS5 keeps only the inverted index, and a row
 // is addressed by its rowid (`entries_fts.rowid = entries.id`, see

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-schema.js

@@ -18,11 +18,13 @@
  * ({@link newerIndexLayoutError}).
  */
 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;
@@ -34,6 +36,8 @@ export const VACUUM_PENDING_META = "vacuumPending";
  * 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
@@ -170,6 +174,7 @@ function ensureEntriesLayout(db) {
         for (const table of [
             "entries_fts",
             "entry_fragments",
+            "asset_links",
             "embeddings",
             "utility_scores_scoped",
             "utility_scores",
@@ -249,6 +254,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);
@@ -368,6 +392,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.