pmx-canvas 0.8.0 → 0.9.0

package/src/server/canvas-db.ts

@@ -8,7 +8,9 @@
 import { Database } from 'bun:sqlite';
 import type { ActorAttribution } from './attribution.js';
 import { CONTEXT_READS_SCHEMA_SQL } from './context-reads.js';
-import { MIGRATED_SNAPSHOT_CATEGORY, normalizeBoardCategory } from '../shared/boards.js';
+import { MIGRATED_SNAPSHOT_FOLDER, normalizeBoardFolder } from '../shared/boards.js';
+import { wikiLinksFromData } from '../shared/memory-graph.js';
+import { relationVocabularySchema, type RelationDefinition } from '../shared/relations.js';
 import { tourSchema, type Tour } from '../shared/tour.js';
 import { existsSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
@@ -54,6 +56,16 @@ export function normalizeCanvasTheme(value: unknown, fallback: CanvasTheme = 'ha
 }
 
 const SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS node_creation_requests (
+    request_id TEXT PRIMARY KEY, board_id TEXT NOT NULL, fingerprint TEXT NOT NULL, node TEXT NOT NULL
+  );
+  CREATE TABLE IF NOT EXISTS knowledge_categories (id TEXT PRIMARY KEY, value TEXT NOT NULL);
+  CREATE TABLE IF NOT EXISTS folder_properties (path TEXT PRIMARY KEY, value TEXT NOT NULL);
+  CREATE TABLE IF NOT EXISTS review_records (
+    sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+    board_id TEXT NOT NULL, node_id TEXT NOT NULL, value TEXT NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS review_records_target ON review_records (board_id, node_id, sequence);
   CREATE TABLE IF NOT EXISTS meta (
     key TEXT PRIMARY KEY,
     value TEXT NOT NULL
@@ -75,7 +87,7 @@ const SCHEMA_SQL = `
     viewport_y REAL NOT NULL DEFAULT 0,
     viewport_scale REAL NOT NULL DEFAULT 1,
     tour TEXT NOT NULL DEFAULT 'null',
-    category TEXT,
+    folder TEXT,
     readme_node_id TEXT
   );
 
@@ -120,6 +132,13 @@ const SCHEMA_SQL = `
     PRIMARY KEY (board_id, id)
   );
 
+  -- Board pins (vision move 0a): the workspace's working set across boards. Not part of
+  -- any board's state, so snapshots and restores never touch them.
+  CREATE TABLE IF NOT EXISTS board_pins (
+    board_id TEXT PRIMARY KEY,
+    meta TEXT NOT NULL
+  );
+
   CREATE TABLE IF NOT EXISTS context_pins (
     board_id TEXT NOT NULL,
     node_id TEXT NOT NULL,
@@ -291,6 +310,14 @@ const SCHEMA_SQL = `
   );
 `;
 
+type EdgeAttribution = Pick<CanvasEdge, 'changedBy' | 'changedAt' | 'createdBy' | 'createdAt' | 'sourceRevision'>;
+
+/** A link's authorship (LinkAuthorship.dc.html) as one JSON column, like a node's attribution. */
+function edgeAttribution(edge: CanvasEdge): string {
+  const { changedBy, changedAt, createdBy, createdAt, sourceRevision } = edge;
+  return JSON.stringify({ changedBy, changedAt, createdBy, createdAt, sourceRevision });
+}
+
 /** Idempotently add a column to an existing table (no prior-migrations system in this repo). */
 function ensureColumn(db: Database, table: string, column: string, ddl: string): void {
   interface ColumnInfoRow {
@@ -404,7 +431,29 @@ export function openCanvasDb(dbPath: string, options: OpenCanvasDbOptions = {}):
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
   const db = new Database(dbPath);
-  db.exec('PRAGMA journal_mode=WAL');
+  // Journal negotiation can return SQLITE_BUSY without invoking SQLite's busy
+  // handler (including WAL cleanup by a closing connection). Retry only this
+  // startup step within the same five-second budget, not arbitrary writes.
+  const journalDeadline = performance.now() + 5000;
+  while (true) {
+    try {
+      db.exec(`PRAGMA busy_timeout=${Math.max(1, Math.ceil(journalDeadline - performance.now()))}`);
+      db.exec('PRAGMA journal_mode=WAL');
+      break;
+    } catch (error) {
+      if (
+        !(error instanceof Error) ||
+        !('code' in error) ||
+        error.code !== 'SQLITE_BUSY' ||
+        performance.now() >= journalDeadline
+      ) {
+        db.close();
+        throw error;
+      }
+      Bun.sleepSync(10);
+    }
+  }
+  db.exec('PRAGMA busy_timeout=5000');
   // FULL, not NORMAL: under WAL, NORMAL lets a host/OS-level crash lose the most
   // recent commits (a clean process exit loses nothing either way). The reporter of
   // issue #22 declined FULL specifically because a save rewrote the whole board, so
@@ -412,7 +461,6 @@ export function openCanvasDb(dbPath: string, options: OpenCanvasDbOptions = {}):
   // typical save is a row or two — so that objection is gone and the durability is
   // worth the fsync.
   db.exec('PRAGMA synchronous=FULL');
-  db.exec('PRAGMA busy_timeout=5000');
   if (needsBoardsMigration(db)) migrateToBoards(db, dbPath, options.migratedBoardName ?? 'Board');
   db.exec(SCHEMA_SQL);
   db.exec(CONTEXT_READS_SCHEMA_SQL);
@@ -423,14 +471,47 @@ export function openCanvasDb(dbPath: string, options: OpenCanvasDbOptions = {}):
   ensureColumn(db, 'ax_steering', 'target', 'target TEXT');
   ensureColumn(db, 'context_reads', 'board_id', 'board_id TEXT');
   ensureColumn(db, 'context_reads', 'read_nodes', "read_nodes TEXT NOT NULL DEFAULT '{}'");
+  ensureColumn(db, 'context_reads', 'seen_links', "seen_links TEXT NOT NULL DEFAULT '{}'");
   ensureColumn(db, 'context_pins', 'meta', 'meta TEXT');
   ensureColumn(db, 'snapshot_pins', 'meta', 'meta TEXT');
-  ensureColumn(db, 'boards', 'category', 'category TEXT');
+  const boardColumns = db
+    .query<{ name: string }, []>('PRAGMA table_info(boards)')
+    .all()
+    .map((column) => column.name);
+  if (!boardColumns.includes('folder') || boardColumns.includes('category')) {
+    // Recheck under the writer lock; already-current databases need no write transaction.
+    db.transaction(() => {
+      if (
+        db
+          .query<{ name: string }, []>('PRAGMA table_info(boards)')
+          .all()
+          .some((column) => column.name === 'category')
+      ) {
+        db.exec('ALTER TABLE boards RENAME COLUMN category TO folder');
+      }
+      ensureColumn(db, 'boards', 'folder', 'folder TEXT');
+    }).immediate();
+  }
   ensureColumn(db, 'boards', 'readme_node_id', 'readme_node_id TEXT');
+  ensureColumn(db, 'boards', 'map_position', 'map_position TEXT');
+  ensureColumn(db, 'boards', 'previous_board_id', 'previous_board_id TEXT');
+  ensureColumn(db, 'edges', 'to_board_id', 'to_board_id TEXT');
+  ensureColumn(db, 'snapshot_edges', 'to_board_id', 'to_board_id TEXT');
+  for (const table of ['edges', 'snapshot_edges']) {
+    ensureColumn(db, table, 'kind', 'kind TEXT');
+    ensureColumn(db, table, 'reason', 'reason TEXT');
+  }
+  ensureColumn(db, 'boards', 'relation_vocabulary', 'relation_vocabulary TEXT');
   ensureColumn(db, 'nodes', 'attribution', "attribution TEXT NOT NULL DEFAULT '{}' ");
   ensureColumn(db, 'nodes', 'content_revision', 'content_revision INTEGER NOT NULL DEFAULT 0');
   ensureColumn(db, 'snapshot_nodes', 'attribution', "attribution TEXT NOT NULL DEFAULT '{}' ");
   ensureColumn(db, 'snapshot_nodes', 'content_revision', 'content_revision INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'nodes', 'links_revision', 'links_revision INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'snapshot_nodes', 'links_revision', 'links_revision INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'edges', 'revision', 'revision INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'edges', 'attribution', "attribution TEXT NOT NULL DEFAULT '{}'");
+  ensureColumn(db, 'snapshot_edges', 'revision', 'revision INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'snapshot_edges', 'attribution', "attribution TEXT NOT NULL DEFAULT '{}'");
   ensureColumn(db, 'document_imports', 'committed_node_ids', 'committed_node_ids TEXT');
 
   // Set schema version if not present
@@ -551,11 +632,11 @@ function snapshotsToBoards(db: Database): void {
     );
     const boardId = createBoardId();
     db.run(
-      'INSERT INTO boards (id, name, category, created_at, viewport_x, viewport_y, viewport_scale, tour) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+      'INSERT INTO boards (id, name, folder, created_at, viewport_x, viewport_y, viewport_scale, tour) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
       [
         boardId,
         snapshot.name,
-        MIGRATED_SNAPSHOT_CATEGORY,
+        MIGRATED_SNAPSHOT_FOLDER,
         snapshot.created_at,
         Number(meta.get('viewport_x') ?? 0),
         Number(meta.get('viewport_y') ?? 0),
@@ -713,19 +794,21 @@ export function saveStateToDB(db: Database, boardId: string, state: PersistedCan
 
     // Save nodes
     const upsertNode = db.prepare(
-      `INSERT INTO nodes (board_id, id, type, pos_x, pos_y, width, height, z_index, collapsed, pinned, data, attribution, content_revision)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `INSERT INTO nodes (board_id, id, type, pos_x, pos_y, width, height, z_index, collapsed, pinned, data, attribution, content_revision, links_revision)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(board_id, id) DO UPDATE SET
          type = excluded.type, pos_x = excluded.pos_x, pos_y = excluded.pos_y,
          width = excluded.width, height = excluded.height, z_index = excluded.z_index,
          collapsed = excluded.collapsed, pinned = excluded.pinned, data = excluded.data,
-         attribution = excluded.attribution, content_revision = excluded.content_revision
+         attribution = excluded.attribution, content_revision = excluded.content_revision,
+         links_revision = excluded.links_revision
        WHERE type IS NOT excluded.type OR pos_x IS NOT excluded.pos_x
           OR pos_y IS NOT excluded.pos_y OR width IS NOT excluded.width
           OR height IS NOT excluded.height OR z_index IS NOT excluded.z_index
           OR collapsed IS NOT excluded.collapsed OR pinned IS NOT excluded.pinned
           OR data IS NOT excluded.data OR attribution IS NOT excluded.attribution
-          OR content_revision IS NOT excluded.content_revision`,
+          OR content_revision IS NOT excluded.content_revision
+          OR links_revision IS NOT excluded.links_revision`,
     );
     for (const node of state.nodes) {
       upsertNode.run(
@@ -740,22 +823,32 @@ export function saveStateToDB(db: Database, boardId: string, state: PersistedCan
         node.collapsed ? 1 : 0,
         node.pinned ? 1 : 0,
         JSON.stringify(node.data),
-        JSON.stringify({ createdBy: node.createdBy, lastEditedBy: node.lastEditedBy }),
+        JSON.stringify({
+          createdBy: node.createdBy,
+          lastEditedBy: node.lastEditedBy,
+          contentChangedAt: node.contentChangedAt,
+          freshnessStartedAt: node.freshnessStartedAt,
+        }),
         node.contentRevision ?? 0,
+        node.linksRevision ?? 0,
       );
     }
     deleteMissingRows(db, 'nodes', 'id', boardId, new Set(state.nodes.map((node) => node.id)));
 
     // Save edges
     const upsertEdge = db.prepare(
-      `INSERT INTO edges (board_id, id, from_node, to_node, type, label, style, animated)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `INSERT INTO edges (board_id, id, from_node, to_node, type, label, style, animated, revision, attribution, to_board_id, kind, reason)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(board_id, id) DO UPDATE SET
          from_node = excluded.from_node, to_node = excluded.to_node, type = excluded.type,
-         label = excluded.label, style = excluded.style, animated = excluded.animated
+         label = excluded.label, style = excluded.style, animated = excluded.animated,
+         revision = excluded.revision, attribution = excluded.attribution, to_board_id = excluded.to_board_id,
+         kind = excluded.kind, reason = excluded.reason
        WHERE from_node IS NOT excluded.from_node OR to_node IS NOT excluded.to_node
           OR type IS NOT excluded.type OR label IS NOT excluded.label
-          OR style IS NOT excluded.style OR animated IS NOT excluded.animated`,
+          OR style IS NOT excluded.style OR animated IS NOT excluded.animated
+          OR revision IS NOT excluded.revision OR attribution IS NOT excluded.attribution
+          OR to_board_id IS NOT excluded.to_board_id OR kind IS NOT excluded.kind OR reason IS NOT excluded.reason`,
     );
     for (const edge of state.edges) {
       upsertEdge.run(
@@ -767,6 +860,11 @@ export function saveStateToDB(db: Database, boardId: string, state: PersistedCan
         edge.label ?? null,
         edge.style ?? null,
         edge.animated ? 1 : 0,
+        edge.revision ?? 0,
+        edgeAttribution(edge),
+        edge.toBoardId ?? null,
+        edge.kind ?? null,
+        edge.reason ?? null,
       );
     }
     deleteMissingRows(db, 'edges', 'id', boardId, new Set(state.edges.map((edge) => edge.id)));
@@ -863,11 +961,12 @@ export function loadStateFromDB(db: Database, boardId?: string): PersistedCanvas
     data: string;
     attribution: string;
     content_revision: number;
+    links_revision: number;
   }
   const nodeRows = db.query<NodeRow, [string]>('SELECT * FROM nodes WHERE board_id = ?').all(id);
   const nodes: CanvasNodeState[] = nodeRows.map((row) => {
     const attribution = JSON.parse(row.attribution || '{}') as Partial<
-      Pick<CanvasNodeState, 'createdBy' | 'lastEditedBy'>
+      Pick<CanvasNodeState, 'createdBy' | 'lastEditedBy' | 'contentChangedAt' | 'freshnessStartedAt'>
     >;
     return {
       id: row.id,
@@ -880,7 +979,10 @@ export function loadStateFromDB(db: Database, boardId?: string): PersistedCanvas
       data: JSON.parse(row.data) as Record<string, unknown>,
       createdBy: attribution.createdBy,
       lastEditedBy: attribution.lastEditedBy,
+      contentChangedAt: attribution.contentChangedAt,
+      freshnessStartedAt: attribution.freshnessStartedAt,
       contentRevision: row.content_revision,
+      linksRevision: row.links_revision,
     };
   });
 
@@ -889,20 +991,30 @@ export function loadStateFromDB(db: Database, boardId?: string): PersistedCanvas
     id: string;
     from_node: string;
     to_node: string;
+    to_board_id: string | null;
     type: string;
+    kind: string | null;
+    reason: string | null;
     label: string | null;
     style: string | null;
     animated: number;
+    revision: number;
+    attribution: string;
   }
   const edgeRows = db.query<EdgeRow, [string]>('SELECT * FROM edges WHERE board_id = ?').all(id);
   const edges: CanvasEdge[] = edgeRows.map((row) => ({
     id: row.id,
     from: row.from_node,
     to: row.to_node,
+    ...(row.to_board_id ? { toBoardId: row.to_board_id } : {}),
     type: row.type as CanvasEdge['type'],
+    ...(row.kind ? { kind: row.kind } : {}),
+    ...(row.reason ? { reason: row.reason } : {}),
     ...(row.label ? { label: row.label } : {}),
     ...(row.style ? { style: row.style as CanvasEdge['style'] } : {}),
     ...(row.animated ? { animated: true } : {}),
+    ...(row.revision ? { revision: row.revision } : {}),
+    ...(JSON.parse(row.attribution || '{}') as EdgeAttribution),
   }));
 
   // Load annotations
@@ -966,38 +1078,53 @@ export function loadStateFromDB(db: Database, boardId?: string): PersistedCanvas
 export interface CanvasBoard {
   id: string;
   name: string;
-  /** A human-chosen shelf on Home ("Planning", "Research"); null is uncategorized. */
-  category: string | null;
+  /** A human-chosen folder on Home ("Planning", "Research"); null is unfiled. */
+  folder: string | null;
   createdAt: string;
   lastOpenedAt: string | null;
   nodeCount: number;
   /** Markdown node used as this board's introduction. */
   readmeNodeId: string | null;
+  /** Human-dragged position in Home Map; null uses the generated folder layout. */
+  mapPosition?: { x: number; y: number } | null;
+  /** The source of a recurring/template board, separate from ordinary portals. */
+  previousBoardId?: string | null;
+  relationVocabulary?: RelationDefinition[];
+  /** Pinned into the agent's working set (vision move 0a); null when not pinned. */
+  pin: ContextPinMeta | null;
 }
 
 interface BoardListRow {
   id: string;
   name: string;
-  category: string | null;
+  folder: string | null;
   created_at: string;
   last_opened_at: string | null;
   node_count: number;
   readme_node_id: string | null;
+  map_position: string | null;
+  previous_board_id: string | null;
+  relation_vocabulary: string | null;
+  pin_meta: string | null;
 }
 
-const BOARD_LIST_SQL = `SELECT b.id, b.name, b.category, b.created_at, b.last_opened_at, b.readme_node_id,
-    (SELECT COUNT(*) FROM nodes n WHERE n.board_id = b.id) AS node_count
-  FROM boards b`;
+const BOARD_LIST_SQL = `SELECT b.id, b.name, b.folder, b.created_at, b.last_opened_at, b.readme_node_id, b.map_position, b.previous_board_id, b.relation_vocabulary,
+    (SELECT COUNT(*) FROM nodes n WHERE n.board_id = b.id) AS node_count, p.meta AS pin_meta
+  FROM boards b LEFT JOIN board_pins p ON p.board_id = b.id`;
 
 function rowToBoard(row: BoardListRow): CanvasBoard {
   return {
     id: row.id,
     name: row.name,
-    category: row.category,
+    folder: row.folder,
     createdAt: row.created_at,
     lastOpenedAt: row.last_opened_at,
     nodeCount: row.node_count,
     readmeNodeId: row.readme_node_id,
+    mapPosition: row.map_position ? (JSON.parse(row.map_position) as { x: number; y: number }) : null,
+    previousBoardId: row.previous_board_id,
+    relationVocabulary: row.relation_vocabulary ? JSON.parse(row.relation_vocabulary) : [],
+    pin: row.pin_meta ? (JSON.parse(row.pin_meta) as ContextPinMeta) : null,
   };
 }
 
@@ -1014,27 +1141,53 @@ export function getBoardFromDB(db: Database, id: string): CanvasBoard | null {
   return row ? rowToBoard(row) : null;
 }
 
-export function createBoardInDB(db: Database, name: string, category: string | null = null): CanvasBoard {
-  category = normalizeBoardCategory(category);
+export function createBoardInDB(db: Database, name: string, folder: string | null = null): CanvasBoard {
+  folder = normalizeBoardFolder(folder);
   const id = createBoardId();
   const createdAt = new Date(Date.now()).toISOString();
-  db.run('INSERT INTO boards (id, name, category, created_at) VALUES (?, ?, ?, ?)', [id, name, category, createdAt]);
-  return { id, name, category, createdAt, lastOpenedAt: null, nodeCount: 0, readmeNodeId: null };
+  db.run('INSERT INTO boards (id, name, folder, created_at) VALUES (?, ?, ?, ?)', [id, name, folder, createdAt]);
+  return { id, name, folder, createdAt, lastOpenedAt: null, nodeCount: 0, readmeNodeId: null, pin: null };
+}
+
+/** Pin a board into the working set, or unpin it with null. False when the board does not exist. */
+export function setBoardPinInDB(db: Database, id: string, meta: ContextPinMeta | null): boolean {
+  if (!db.query<{ id: string }, [string]>('SELECT id FROM boards WHERE id = ?').get(id)) return false;
+  if (meta) db.run('INSERT OR REPLACE INTO board_pins (board_id, meta) VALUES (?, ?)', [id, JSON.stringify(meta)]);
+  else db.run('DELETE FROM board_pins WHERE board_id = ?', [id]);
+  return true;
 }
 
-/** Rename and/or re-shelve a board; `category: null` removes it from its category. */
+/** Rename and/or re-shelve a board; `folder: null` unfiles it. */
 export function updateBoardInDB(
   db: Database,
   id: string,
-  patch: { name?: string; category?: string | null; readmeNodeId?: string | null },
+  patch: {
+    name?: string;
+    folder?: string | null;
+    readmeNodeId?: string | null;
+    mapPosition?: { x: number; y: number } | null;
+    previousBoardId?: string | null;
+    relationVocabulary?: RelationDefinition[];
+  },
 ): boolean {
-  const category = patch.category === undefined ? undefined : normalizeBoardCategory(patch.category);
+  const folder = patch.folder === undefined ? undefined : normalizeBoardFolder(patch.folder);
+  const vocabulary =
+    patch.relationVocabulary === undefined ? undefined : relationVocabularySchema.parse(patch.relationVocabulary);
   if (!db.query<{ id: string }, [string]>('SELECT id FROM boards WHERE id = ?').get(id)) return false;
+  if (vocabulary !== undefined)
+    db.run('UPDATE boards SET relation_vocabulary = ? WHERE id = ?', [JSON.stringify(vocabulary), id]);
   if (patch.name !== undefined) db.run('UPDATE boards SET name = ? WHERE id = ?', [patch.name, id]);
-  if (category !== undefined) db.run('UPDATE boards SET category = ? WHERE id = ?', [category, id]);
+  if (folder !== undefined) db.run('UPDATE boards SET folder = ? WHERE id = ?', [folder, id]);
   if (patch.readmeNodeId !== undefined) {
     db.run('UPDATE boards SET readme_node_id = ? WHERE id = ?', [patch.readmeNodeId, id]);
   }
+  if (patch.mapPosition !== undefined)
+    db.run('UPDATE boards SET map_position = ? WHERE id = ?', [
+      patch.mapPosition ? JSON.stringify(patch.mapPosition) : null,
+      id,
+    ]);
+  if (patch.previousBoardId !== undefined)
+    db.run('UPDATE boards SET previous_board_id = ? WHERE id = ?', [patch.previousBoardId, id]);
   return true;
 }
 
@@ -1042,22 +1195,133 @@ export function updateBoardInDB(
 export function createBoardWithStateInDB(
   db: Database,
   name: string,
-  category: string | null,
+  folder: string | null,
   state: PersistedCanvasState,
   readmeNodeId: string | null,
+  invalidateTarget?: (boardId: string, nodeId: string) => void,
 ): CanvasBoard {
   return db.transaction(() => {
-    const board = createBoardInDB(db, name, category);
+    const board = createBoardInDB(db, name, folder);
     saveStateToDB(db, board.id, state);
+    for (const edge of state.edges) {
+      if (edge.toBoardId && !edge.id.startsWith('codegraph-') && !edge.id.startsWith('boardmap-'))
+        (invalidateTarget ?? ((boardId, nodeId) => invalidateLinksInDB(db, boardId, nodeId)))(edge.toBoardId, edge.to);
+    }
+    for (const node of state.nodes) {
+      for (const { target } of node.type === 'markdown' ? wikiLinksFromData(node.data) : []) {
+        if (target?.cardId && target.boardId !== board.id)
+          (invalidateTarget ?? ((boardId, nodeId) => invalidateLinksInDB(db, boardId, nodeId)))(
+            target.boardId,
+            target.cardId,
+          );
+      }
+    }
     updateBoardInDB(db, board.id, { readmeNodeId });
     return { ...board, nodeCount: state.nodes.length, readmeNodeId };
   })();
 }
 
+/** Derived incoming-link metadata only: the target owns its clock and its body. */
+export function invalidateLinksInDB(db: Database, boardId: string, nodeId: string): number | undefined {
+  return db.transaction(() => {
+    const node = db
+      .query<{ links_revision: number; content_revision: number }, [string, string]>(
+        'SELECT links_revision, content_revision FROM nodes WHERE board_id = ? AND id = ?',
+      )
+      .get(boardId, nodeId);
+    if (!node || !getBoardFromDB(db, boardId)) return;
+    const raw = db
+      .query<{ value: string }, [string, string]>('SELECT value FROM ax_state WHERE board_id = ? AND key = ?')
+      .get(boardId, 'revision')?.value;
+    const state: PersistedRevisionState = raw ? JSON.parse(raw) : { revision: 0, floor: 0, tombstones: [] };
+    state.revision = Math.max(state.revision, node.links_revision, node.content_revision) + 1;
+    db.run('UPDATE nodes SET links_revision = ? WHERE board_id = ? AND id = ?', [state.revision, boardId, nodeId]);
+    db.run(
+      'INSERT INTO ax_state (board_id, key, value) VALUES (?, ?, ?) ON CONFLICT(board_id, key) DO UPDATE SET value = excluded.value',
+      [boardId, 'revision', JSON.stringify(state)],
+    );
+    return state.revision;
+  })();
+}
+
+/** A target's appearance/disappearance changes its incoming saved relations on source cards. */
+export function invalidateIncomingLinksInDB(
+  db: Database,
+  boardId: string,
+  nodeId: string | null,
+  invalidate: (boardId: string, nodeId: string) => void,
+): void {
+  const sources = new Set<string>();
+  for (const edge of db
+    .query<{ id: string; board_id: string; from_node: string }, [string, string, string | null, string | null]>(
+      'SELECT id, board_id, from_node FROM edges WHERE to_board_id = ? AND board_id <> ? AND (? IS NULL OR to_node = ?)',
+    )
+    .all(boardId, boardId, nodeId, nodeId)) {
+    if (edge.id.startsWith('codegraph-') || edge.id.startsWith('boardmap-')) continue;
+    const key = JSON.stringify([edge.board_id, edge.from_node]);
+    if (sources.has(key)) continue;
+    sources.add(key);
+    invalidate(edge.board_id, edge.from_node);
+  }
+  for (const source of db
+    .query<{ board_id: string; id: string }, [string, string, string | null, string | null]>(
+      `SELECT DISTINCT n.board_id, n.id FROM nodes n, json_each(n.data, '$.wikiLinks') link
+       WHERE n.type = 'markdown' AND n.board_id <> ?
+       AND json_extract(link.value, '$.target.boardId') = ?
+       AND (? IS NULL OR json_extract(link.value, '$.target.cardId') = ?)`,
+    )
+    .all(boardId, boardId, nodeId, nodeId)) {
+    const key = JSON.stringify([source.board_id, source.id]);
+    if (sources.has(key)) continue;
+    sources.add(key);
+    invalidate(source.board_id, source.id);
+  }
+}
+
 /** Deletes a board with its rows and its snapshots. */
-export function deleteBoardFromDB(db: Database, id: string): boolean {
+export function deleteBoardFromDB(
+  db: Database,
+  id: string,
+  invalidateTarget?: (boardId: string, nodeId: string) => void,
+): boolean {
   const transaction = db.transaction(() => {
-    for (const table of ['nodes', 'edges', 'annotations', 'context_pins', 'ax_state']) {
+    invalidateIncomingLinksInDB(
+      db,
+      id,
+      null,
+      invalidateTarget ?? ((boardId, nodeId) => invalidateLinksInDB(db, boardId, nodeId)),
+    );
+    for (const edge of db
+      .query<{ id: string; to_board_id: string; to_node: string }, [string]>(
+        'SELECT id, to_board_id, to_node FROM edges WHERE board_id = ? AND to_board_id IS NOT NULL',
+      )
+      .all(id)) {
+      if (edge.to_board_id !== id && !edge.id.startsWith('codegraph-') && !edge.id.startsWith('boardmap-'))
+        (invalidateTarget ?? ((boardId, nodeId) => invalidateLinksInDB(db, boardId, nodeId)))(
+          edge.to_board_id,
+          edge.to_node,
+        );
+    }
+    for (const node of db
+      .query<{ data: string }, [string]>("SELECT data FROM nodes WHERE board_id = ? AND type = 'markdown'")
+      .all(id)) {
+      for (const { target } of wikiLinksFromData(JSON.parse(node.data))) {
+        if (target?.cardId && target.boardId !== id)
+          (invalidateTarget ?? ((boardId, nodeId) => invalidateLinksInDB(db, boardId, nodeId)))(
+            target.boardId,
+            target.cardId,
+          );
+      }
+    }
+    for (const table of [
+      'nodes',
+      'edges',
+      'annotations',
+      'context_pins',
+      'ax_state',
+      'board_pins',
+      'node_creation_requests',
+    ]) {
       db.run(`DELETE FROM ${table} WHERE board_id = ?`, [id]);
     }
     const snapshotIds = db
@@ -1162,8 +1426,8 @@ export function saveSnapshotToDB(
 
     // Insert snapshot nodes
     const insertNode = db.prepare(
-      `INSERT INTO snapshot_nodes (snapshot_id, id, type, pos_x, pos_y, width, height, z_index, collapsed, pinned, data, attribution, content_revision)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      `INSERT INTO snapshot_nodes (snapshot_id, id, type, pos_x, pos_y, width, height, z_index, collapsed, pinned, data, attribution, content_revision, links_revision)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     );
     for (const node of state.nodes) {
       insertNode.run(
@@ -1178,15 +1442,21 @@ export function saveSnapshotToDB(
         node.collapsed ? 1 : 0,
         node.pinned ? 1 : 0,
         JSON.stringify(node.data),
-        JSON.stringify({ createdBy: node.createdBy, lastEditedBy: node.lastEditedBy }),
+        JSON.stringify({
+          createdBy: node.createdBy,
+          lastEditedBy: node.lastEditedBy,
+          contentChangedAt: node.contentChangedAt,
+          freshnessStartedAt: node.freshnessStartedAt,
+        }),
         node.contentRevision ?? 0,
+        node.linksRevision ?? 0,
       );
     }
 
     // Insert snapshot edges
     const insertEdge = db.prepare(
-      `INSERT INTO snapshot_edges (snapshot_id, id, from_node, to_node, type, label, style, animated)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      `INSERT INTO snapshot_edges (snapshot_id, id, from_node, to_node, type, label, style, animated, revision, attribution, to_board_id, kind, reason)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     );
     for (const edge of state.edges) {
       insertEdge.run(
@@ -1198,6 +1468,11 @@ export function saveSnapshotToDB(
         edge.label ?? null,
         edge.style ?? null,
         edge.animated ? 1 : 0,
+        edge.revision ?? 0,
+        edgeAttribution(edge),
+        edge.toBoardId ?? null,
+        edge.kind ?? null,
+        edge.reason ?? null,
       );
     }
 
@@ -1303,13 +1578,14 @@ export function loadSnapshotFromDB(
     data: string;
     attribution: string;
     content_revision: number;
+    links_revision: number;
   }
   const nodeRows = db
     .query<NodeRow, [string]>('SELECT * FROM snapshot_nodes WHERE snapshot_id = ?')
     .all(snapshotRow.id);
   const nodes: CanvasNodeState[] = nodeRows.map((row) => {
     const attribution = JSON.parse(row.attribution || '{}') as Partial<
-      Pick<CanvasNodeState, 'createdBy' | 'lastEditedBy'>
+      Pick<CanvasNodeState, 'createdBy' | 'lastEditedBy' | 'contentChangedAt' | 'freshnessStartedAt'>
     >;
     return {
       id: row.id,
@@ -1322,7 +1598,10 @@ export function loadSnapshotFromDB(
       data: JSON.parse(row.data) as Record<string, unknown>,
       createdBy: attribution.createdBy,
       lastEditedBy: attribution.lastEditedBy,
+      contentChangedAt: attribution.contentChangedAt,
+      freshnessStartedAt: attribution.freshnessStartedAt,
       contentRevision: row.content_revision,
+      linksRevision: row.links_revision,
     };
   });
 
@@ -1331,10 +1610,15 @@ export function loadSnapshotFromDB(
     id: string;
     from_node: string;
     to_node: string;
+    to_board_id: string | null;
     type: string;
+    kind: string | null;
+    reason: string | null;
     label: string | null;
     style: string | null;
     animated: number;
+    revision: number;
+    attribution: string;
   }
   const edgeRows = db
     .query<EdgeRow, [string]>('SELECT * FROM snapshot_edges WHERE snapshot_id = ?')
@@ -1343,10 +1627,15 @@ export function loadSnapshotFromDB(
     id: row.id,
     from: row.from_node,
     to: row.to_node,
+    ...(row.to_board_id ? { toBoardId: row.to_board_id } : {}),
     type: row.type as CanvasEdge['type'],
+    ...(row.kind ? { kind: row.kind } : {}),
+    ...(row.reason ? { reason: row.reason } : {}),
     ...(row.label ? { label: row.label } : {}),
     ...(row.style ? { style: row.style as CanvasEdge['style'] } : {}),
     ...(row.animated ? { animated: true } : {}),
+    ...(row.revision ? { revision: row.revision } : {}),
+    ...(JSON.parse(row.attribution || '{}') as EdgeAttribution),
   }));
 
   // Load snapshot annotations