pmx-canvas 0.8.2 → 0.9.0

package/src/server/canvas-state.ts

@@ -13,6 +13,16 @@
  */
 
 import { createHash, randomUUID } from 'node:crypto';
+import {
+  DEFAULT_WORKSPACE_SETTINGS,
+  workspaceSettingsPatchSchema,
+  workspaceSettingsSchema,
+  type WorkspaceSettings,
+} from '../shared/workspace-settings.js';
+import { KnowledgeLifecycle, lifecycleSchema, type Lifecycle } from './knowledge-lifecycle.js';
+import { relationSourceEnd } from '../shared/relations.js';
+import { OperationError } from './operations/types.js';
+import { humanPresence } from './human-presence.js';
 import { tourSchema, type Tour } from '../shared/tour.js';
 import {
   copyFileSync,
@@ -27,6 +37,8 @@ import {
 import { basename, isAbsolute, join, dirname, relative } from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
 import { normalizeCanvasNodeData } from './canvas-provenance.js';
+import { resolveWikiLinks, wikiReferences, type WikiBoard } from './wiki-links.js';
+import { wikiLinksFromData, type WikiLink } from '../shared/memory-graph.js';
 import {
   openCanvasDb,
   saveStateToDB,
@@ -41,6 +53,8 @@ import {
   checkpointCanvasDb,
   createBoardInDB,
   createBoardWithStateInDB,
+  invalidateLinksInDB,
+  invalidateIncomingLinksInDB,
   readContextBriefCursor,
   advanceContextBriefCursor,
   deleteBoardFromDB,
@@ -50,6 +64,7 @@ import {
   readMetaFromDB,
   readThemeFromDB,
   updateBoardInDB,
+  setBoardPinInDB,
   writeMetaToDB,
   saveThemeToDB,
   setActiveBoardIdInDB,
@@ -78,9 +93,8 @@ import { normalizeCanvasTheme } from './canvas-db.js';
 import {
   type CanvasPlacementRect,
   computeGroupBounds,
+  computeManualGroupLayout,
   computePackedGroupLayout,
-  GROUP_PAD,
-  GROUP_TITLEBAR_HEIGHT,
   resolveGroupCollision,
 } from './placement.js';
 import {
@@ -117,6 +131,8 @@ import {
   appendContextReadToDB,
   loadContextReadsFromDB,
   loadNodeReadStatusFromDB,
+  loadSeenLinksFromDB,
+  loadBoardLastReadFromDB,
   loadReadNodeIdsSince,
   type ContextRead,
   type ContextReadConsumerSummary,
@@ -243,6 +259,12 @@ export interface CanvasNodeState {
   lastEditedBy?: ActorAttribution;
   /** Board-monotonic revision of this node's latest semantic content. */
   contentRevision?: number;
+  /** Time of that semantic change; absent for content created before this clock was recorded. */
+  contentChangedAt?: string;
+  /** Initial authored freshness, not evidence validation. Imports and undated existing content have none. */
+  freshnessStartedAt?: string;
+  /** Board-monotonic revision of this node's latest link change, kept apart from its text. */
+  linksRevision?: number;
 }
 
 export interface NodeDeletionTombstone {
@@ -274,10 +296,41 @@ export interface CanvasEdge {
   id: string;
   from: string;
   to: string;
+  /** Target on another board. Source and mutation ownership stay on the active board. */
+  toBoardId?: string;
   type: 'relation' | 'depends-on' | 'flow' | 'references';
+  /** Open semantic relation kind, independent of the structural edge type. */
+  kind?: string;
+  reason?: string;
+  /** Source content observed when an explicit dependency was authored. Never refreshed by reads. */
+  sourceRevision?: number;
   label?: string;
   style?: 'solid' | 'dashed' | 'dotted';
   animated?: boolean;
+  /** Board revision of this link's latest add, retype or relabel (0 = never stamped). */
+  revision?: number;
+  /** Who made that change, and when: the link's author until a person changes it again. */
+  changedBy?: ActorAttribution;
+  changedAt?: string;
+  /** Who first drew the link, and when (docs/design/LinkAuthorship.dc.html). */
+  createdBy?: ActorAttribution;
+  createdAt?: string;
+}
+
+type EdgeStamp = Pick<CanvasEdge, 'revision' | 'changedBy' | 'changedAt' | 'createdBy' | 'createdAt'>;
+
+/** A link's authorship and revision fields, without the relation itself. */
+function edgeStamp(edge: CanvasEdge): EdgeStamp {
+  const { revision, changedBy, changedAt, createdBy, createdAt } = edge;
+  return Object.fromEntries(
+    Object.entries({ revision, changedBy, changedAt, createdBy, createdAt }).filter(([, value]) => value !== undefined),
+  ) as EdgeStamp;
+}
+
+/** The relation itself, without its authorship and revision fields. */
+function edgeWithoutStamp(edge: CanvasEdge): CanvasEdge {
+  const { revision: _r, changedBy: _cb, changedAt: _ca, createdBy: _crb, createdAt: _cra, ...rest } = edge;
+  return rest;
 }
 
 export interface CanvasAnnotationPoint {
@@ -389,14 +442,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
-function replaceById<T extends { id: string }>(list: T[], item: T): T[] {
-  const idx = list.findIndex((x) => x.id === item.id);
-  if (idx === -1) return [...list, item];
-  const copy = list.slice();
-  copy[idx] = item;
-  return copy;
-}
-
 function isPersistedBlobRef(value: unknown): value is PersistedBlobRef {
   return (
     isRecord(value) &&
@@ -597,6 +642,16 @@ class CanvasStateManager {
 
   private normalizeNode(node: CanvasNodeState): CanvasNodeState {
     const data = { ...node.data };
+    // Lifecycle is optional metadata, never a card taxonomy or validation clock.
+    delete data.categoryId;
+    if (data.contentOrigin !== undefined && data.contentOrigin !== 'authored' && data.contentOrigin !== 'imported') {
+      throw new OperationError('Content origin must be authored or imported.');
+    }
+    if (data.lifecycleOverride !== undefined && data.lifecycleOverride !== null) {
+      const lifecycle = lifecycleSchema.safeParse(data.lifecycleOverride);
+      if (!lifecycle.success) throw new OperationError('Invalid lifecycle override.');
+      data.lifecycleOverride = lifecycle.data;
+    }
     delete data.createdBy;
     delete data.lastEditedBy;
     delete data.contentRevision;
@@ -606,6 +661,7 @@ class CanvasStateManager {
       createdBy: node.createdBy ?? unknownActor(),
       lastEditedBy: node.lastEditedBy ?? unknownActor(),
       contentRevision: Number.isSafeInteger(node.contentRevision) ? node.contentRevision : 0,
+      linksRevision: Number.isSafeInteger(node.linksRevision) ? node.linksRevision : 0,
     };
   }
 
@@ -636,7 +692,7 @@ class CanvasStateManager {
       retentionFloor: this._revisionFloor,
       reset,
       nodes: Array.from(this.nodes.values())
-        .filter((node) => reset || (node.contentRevision ?? 0) > cursor)
+        .filter((node) => reset || Math.max(node.contentRevision ?? 0, node.linksRevision ?? 0) > cursor)
         .map((node) => structuredClone(this.nodeForRead(node))),
       deleted: reset
         ? []
@@ -724,38 +780,8 @@ class CanvasStateManager {
     const snapshot = this.getGroupSnapshot(groupId);
     if (!snapshot || snapshot.children.length === 0) return;
     if (snapshot.group.data.frameMode === 'manual') {
-      const sorted = [...snapshot.children].sort((a, b) => a.position.y - b.position.y || a.position.x - b.position.x);
-      const left = snapshot.group.position.x + GROUP_PAD;
-      const top = snapshot.group.position.y + GROUP_TITLEBAR_HEIGHT + GROUP_PAD;
-      const right = snapshot.group.position.x + snapshot.group.size.width - GROUP_PAD;
-      const gap = 24;
-      let cursorX = left;
-      let cursorY = top;
-      let rowHeight = 0;
-
-      for (const child of sorted) {
-        if (layout === 'column') {
-          this.nodes.set(child.id, { ...child, position: { x: left, y: cursorY } });
-          cursorY += child.size.height + gap;
-          continue;
-        }
-
-        if (layout === 'flow') {
-          this.nodes.set(child.id, { ...child, position: { x: cursorX, y: top } });
-          cursorX += child.size.width + gap;
-          continue;
-        }
-
-        if (cursorX > left && cursorX + child.size.width > right) {
-          cursorX = left;
-          cursorY += rowHeight + gap;
-          rowHeight = 0;
-        }
-
-        this.nodes.set(child.id, { ...child, position: { x: cursorX, y: cursorY } });
-        cursorX += child.size.width + gap;
-        rowHeight = Math.max(rowHeight, child.size.height);
-      }
+      const positions = computeManualGroupLayout(snapshot.children, snapshot.group, layout);
+      for (const child of snapshot.children) this.nodes.set(child.id, { ...child, position: positions.get(child.id)! });
       return;
     }
 
@@ -783,6 +809,16 @@ class CanvasStateManager {
   private _db: import('bun:sqlite').Database | null = null;
   private _dbPath: string | null = null;
   private _saveTimer: ReturnType<typeof setTimeout> | null = null;
+  readonly knowledge = new KnowledgeLifecycle(
+    () => this._db,
+    () => this.notifyChange('nodes'),
+    (boardId, nodeId) => {
+      const node = this.nodes.get(nodeId);
+      if (boardId !== this._activeBoardId || !node) throw new OperationError('Card not found.', 404);
+      return node.contentRevision ?? 0;
+    },
+    () => this.flushToDisk(),
+  );
 
   /** Workspace root backing persistence and workspace-relative path resolution. */
   get workspaceRoot(): string {
@@ -792,6 +828,8 @@ class CanvasStateManager {
   /** Set the workspace root to enable auto-persistence. */
   setWorkspaceRoot(workspaceRoot: string): void {
     this.close();
+    // Detached content cannot belong to the next database, even if loading it fails.
+    this.applyPersistedState(this.emptyPersistedState());
     this._workspaceRoot = workspaceRoot;
 
     // Determine DB path. PMX_CANVAS_DB_PATH wins; PMX_CANVAS_STATE_FILE is
@@ -1002,6 +1040,7 @@ class CanvasStateManager {
         const boardId = getActiveBoardIdFromDB(this._db);
         const state = boardId ? loadStateFromDB(this._db, boardId) : null;
         if (boardId && state) {
+          this.initializePersistedWikiLinks(state, boardId);
           this.applyPersistedState(state);
           this._activeBoardId = boardId;
           return true;
@@ -1009,6 +1048,8 @@ class CanvasStateManager {
         this._theme = normalizeCanvasTheme(readThemeFromDB(this._db), this._theme);
       } catch (error) {
         logCanvasStateWarning('load state from sqlite failed', error, {});
+        // Failed replacement is not an empty board: retain any live state and identity.
+        return false;
       }
     }
 
@@ -1107,10 +1148,305 @@ class CanvasStateManager {
     return board ? { ...board, nodeCount: this.nodes.size } : null;
   }
 
-  /**
-   * One board's content without opening it: the open board from memory, any
-   * other straight from SQLite. Null when there is no such board.
-   */
+  /** Synchronous, owner-controlled static creation. No board activation or runtime hydration. */
+  createStoredNode(
+    boardId: string,
+    requestId: string | undefined,
+    fingerprint: string,
+    build: (nodes: CanvasNodeState[]) => CanvasNodeState,
+  ): CanvasNodeState {
+    return this.createStoredCreation(boardId, requestId, fingerprint, (state, invalidate) => {
+      const next = this.stampStoredNode(this.normalizeNode(build(state.nodes)), state);
+      if (next.type === 'markdown') {
+        const catalog = listBoardsFromDB(this._db!).map((board) => ({
+          id: board.id,
+          name: board.name,
+          cards: (board.id === boardId
+            ? [...state.nodes, next]
+            : (loadStateFromDB(this._db!, board.id)?.nodes ?? [])
+          ).map((card) => ({ id: card.id, title: typeof card.data.title === 'string' ? card.data.title : card.id })),
+        }));
+        next.data.wikiLinks = resolveWikiLinks(String(next.data.content ?? ''), [], catalog);
+      }
+      state.nodes.push(next);
+      const links = next.type === 'markdown' ? wikiLinksFromData(next.data) : [];
+      if (links.length) {
+        invalidate(boardId, next.id);
+        const targets = new Map(
+          links.flatMap(({ target }) => (target?.cardId ? [[JSON.stringify(target), target] as const] : [])),
+        );
+        for (const target of targets.values()) invalidate(target.boardId, target.cardId!);
+      }
+      return next;
+    });
+  }
+
+  private stampStoredNode(node: CanvasNodeState, state: PersistedCanvasState): CanvasNodeState {
+    const now = new Date().toISOString();
+    const provenance = node.data.provenance as { sourceKind?: string } | undefined;
+    const imported =
+      node.data.contentOrigin === 'imported' ||
+      node.data.source !== undefined ||
+      (provenance !== undefined && provenance.sourceKind !== 'recipe');
+    return {
+      ...node,
+      createdBy: currentActor(),
+      lastEditedBy: currentActor(),
+      contentRevision: ++state.revisionState!.revision,
+      contentChangedAt: now,
+      freshnessStartedAt: imported ? undefined : now,
+    };
+  }
+
+  createStoredGroup(
+    boardId: string,
+    requestId: string | undefined,
+    fingerprint: string,
+    build: (nodes: CanvasNodeState[]) => CanvasNodeState,
+    childLayout?: 'grid' | 'column' | 'flow',
+  ): CanvasNodeState {
+    return this.createStoredCreation(boardId, requestId, fingerprint, (state) => {
+      const group = this.stampStoredNode(this.normalizeNode(build(state.nodes)), state);
+      const ids = group.data.children as string[];
+      const children = ids.map((id) => state.nodes.find((node) => node.id === id)!);
+      const affected = new Set(ids);
+      // A group can itself be a member; moving its frame moves its descendants too.
+      const move = (node: CanvasNodeState, position: { x: number; y: number }) => {
+        const dx = position.x - node.position.x,
+          dy = position.y - node.position.y;
+        const descendants = new Set<string>([node.id]);
+        for (const id of descendants) {
+          const child = state.nodes.find((item) => item.id === id)!;
+          affected.add(id);
+          if (child.type === 'group') for (const nested of child.data.children as string[]) descendants.add(nested);
+          child.position = { x: child.position.x + dx, y: child.position.y + dy };
+        }
+      };
+      if (childLayout) {
+        if (group.data.frameMode === 'manual') {
+          const positions = computeManualGroupLayout(children, group, childLayout);
+          for (const child of children) move(child, positions.get(child.id)!);
+        } else {
+          const packed = computePackedGroupLayout(children);
+          for (const child of children) move(child, packed.positions.get(child.id)!);
+          if (packed.bounds) {
+            group.position = { x: packed.bounds.x, y: packed.bounds.y };
+            group.size = { width: packed.bounds.width, height: packed.bounds.height };
+          }
+        }
+      }
+      // Detach from old parents before attaching. Refit only affected ancestors.
+      const parents = new Set<string>();
+      for (const child of children) {
+        if (typeof child.data.parentGroup === 'string') parents.add(child.data.parentGroup);
+        child.data = { ...child.data, parentGroup: group.id };
+      }
+      for (const parentId of parents) {
+        const parent = state.nodes.find((node) => node.id === parentId)!;
+        affected.add(parentId);
+        parent.data = {
+          ...parent.data,
+          children: (parent.data.children as string[]).filter((id) => !ids.includes(id)),
+        };
+      }
+      const refit = (parentId: string) => {
+        const parent = state.nodes.find((node) => node.id === parentId)!;
+        if (parent.data.frameMode === 'manual') return;
+        affected.add(parentId);
+        const bounds = computeGroupBounds(
+          state.nodes.filter((node) => (parent.data.children as string[]).includes(node.id)),
+        );
+        if (bounds) {
+          parent.position = { x: bounds.x, y: bounds.y };
+          parent.size = { width: bounds.width, height: bounds.height };
+        }
+        if (typeof parent.data.parentGroup === 'string') {
+          refit(parent.data.parentGroup);
+        }
+      };
+      for (const parentId of parents) refit(parentId);
+      for (const node of state.nodes.filter((item) => affected.has(item.id))) {
+        const held = humanPresence.lockedNodes().get(node.id);
+        if (held) throw new OperationError(`Node "${node.id}" is being edited by ${held} right now.`, 409);
+        // Group membership is semantic; geometry alone does not renew freshness.
+        if (ids.includes(node.id) || parents.has(node.id)) {
+          delete node.data.agentSummary;
+          delete node.data.summary;
+          node.contentRevision = ++state.revisionState!.revision;
+          node.lastEditedBy = currentActor();
+          node.contentChangedAt = new Date().toISOString();
+        }
+      }
+      state.nodes.push(group);
+      return group;
+    });
+  }
+
+  createStoredEdge(
+    boardId: string,
+    requestId: string | undefined,
+    fingerprint: string,
+    build: (nodes: CanvasNodeState[]) => CanvasEdge,
+  ): CanvasEdge {
+    return this.createStoredCreation(boardId, requestId, fingerprint, (state, invalidate) => {
+      const edge = build(state.nodes);
+      if (
+        (!edge.toBoardId && edge.from === edge.to) ||
+        state.edges.some(
+          (item) =>
+            item.from === edge.from &&
+            item.to === edge.to &&
+            item.toBoardId === edge.toBoardId &&
+            item.type === edge.type &&
+            item.kind === edge.kind,
+        )
+      )
+        throw new OperationError('Duplicate or self-edge.');
+      const targetBoard = edge.toBoardId ?? boardId;
+      const target =
+        targetBoard === boardId
+          ? state.nodes.find((node) => node.id === edge.to)
+          : this.readBoard(targetBoard)?.layout.nodes.find((node) => node.id === edge.to);
+      for (const id of [edge.from, edge.to]) {
+        const held = humanPresence.lockedNodes().get(id);
+        if (held) throw new OperationError(`Node "${id}" is being edited by ${held} right now.`, 409);
+      }
+      const sourceEnd = relationSourceEnd(edge);
+      const source = sourceEnd === 'to' ? target : state.nodes.find((node) => node.id === edge.from);
+      const stamped = {
+        ...edge,
+        sourceRevision: sourceEnd ? source?.contentRevision : undefined,
+        revision: ++state.revisionState!.revision,
+        createdBy: currentActor(),
+        changedBy: currentActor(),
+        createdAt: new Date().toISOString(),
+        changedAt: new Date().toISOString(),
+      };
+      state.edges.push(stamped);
+      invalidate(boardId, edge.from);
+      invalidate(targetBoard, edge.to);
+      return stamped;
+    });
+  }
+
+  /** Stored creations share one durable receipt/commit boundary, never a temporary board switch. */
+  private createStoredCreation<T extends CanvasNodeState | CanvasEdge>(
+    boardId: string,
+    requestId: string | undefined,
+    fingerprint: string,
+    build: (state: PersistedCanvasState, invalidate: (boardId: string, nodeId: string) => void) => T,
+  ): T {
+    const db = this._db;
+    if (!db) throw new OperationError('Destination/retry creation requires persistent workspace storage.');
+    const active = boardId === this._activeBoardId;
+    let committed: PersistedCanvasState | undefined;
+    let before: PersistedCanvasState | undefined;
+    const activeLinkRevisions = new Map<string, number>();
+    let activeRevision = this._contentRevision;
+    const result = db.transaction(() => {
+      const previous = requestId
+        ? db
+            .query<{ board_id: string; fingerprint: string; node: string }, [string]>(
+              'SELECT board_id, fingerprint, node FROM node_creation_requests WHERE request_id = ?',
+            )
+            .get(requestId)
+        : null;
+      if (previous) {
+        if (previous.board_id !== boardId || previous.fingerprint !== fingerprint)
+          throw new OperationError('requestId was already used with different creation input or destination.', 409);
+        // Return the original receipt even if the node has since been edited or removed.
+        return JSON.parse(previous.node) as T;
+      }
+      // Include pending edits in catalog resolution and durable relation clocks,
+      // without publishing or changing the active board before commit.
+      if (this._activeBoardId) saveStateToDB(db, this._activeBoardId, this.persistedState());
+      const state = loadStateFromDB(db, boardId);
+      if (!state) throw new OperationError(`Board "${boardId}" not found.`, 404);
+      const policies = [this.getPolicy(), state.ax?.policy];
+      if (policies.some((policy) => policy && (policy.scope || Object.keys(policy.agentScopes ?? {}).length)))
+        throw new OperationError('Destination/retry creation is refused while either board has a scope fence.', 403);
+      state.revisionState = {
+        ...state.revisionState,
+        revision: state.revisionState?.revision ?? 0,
+        floor: state.revisionState?.floor ?? 0,
+        tombstones: state.revisionState?.tombstones ?? [],
+      };
+      before = structuredClone(state);
+      const invalidations: Array<[string, string]> = [];
+      let next = build(state, (targetBoardId, nodeId) => invalidations.push([targetBoardId, nodeId]));
+      // Theme is workspace-global; never let an inactive projection overwrite it.
+      state.theme = this._theme;
+      saveStateToDB(db, boardId, state);
+      const invalidate = (targetBoardId: string, targetNodeId: string) => {
+        const revision = invalidateLinksInDB(db, targetBoardId, targetNodeId);
+        if (targetBoardId === this._activeBoardId && revision !== undefined) {
+          activeLinkRevisions.set(targetNodeId, revision);
+          activeRevision = Math.max(activeRevision, revision);
+        }
+      };
+      for (const [targetBoardId, nodeId] of invalidations) invalidate(targetBoardId, nodeId);
+      if ('data' in next) invalidateIncomingLinksInDB(db, boardId, next.id, invalidate);
+      committed = loadStateFromDB(db, boardId)!;
+      next = ([...committed.nodes, ...committed.edges].find((candidate) => candidate.id === next.id) ?? next) as T;
+      if (active) activeRevision = committed.revisionState!.revision;
+      if (requestId)
+        db.run('INSERT INTO node_creation_requests VALUES (?, ?, ?, ?)', [
+          requestId,
+          boardId,
+          fingerprint,
+          JSON.stringify(next),
+        ]);
+      return next;
+    })();
+    if (committed) {
+      if (active) {
+        const changed = committed.nodes.filter(
+          (node) => JSON.stringify(before!.nodes.find((old) => old.id === node.id)) !== JSON.stringify(node),
+        );
+        for (const node of changed) this.nodes.set(node.id, structuredClone(node));
+        if ('data' in result && result.type !== 'group') this.recordNodeCreation(result);
+        else {
+          for (const edge of committed.edges) this.edges.set(edge.id, structuredClone(edge));
+          const edge = 'data' in result ? undefined : (result as CanvasEdge);
+          const restore = (nodes: CanvasNodeState[]) =>
+            this.suppressed(() => {
+              this.removeNode(result.id);
+              for (const node of nodes) {
+                const existing = this.nodes.get(node.id);
+                if (existing) this.setSemanticNode({ ...structuredClone(node), linksRevision: existing.linksRevision });
+                else
+                  this.nodes.set(node.id, {
+                    ...structuredClone(node),
+                    contentRevision: this.nextContentRevision(),
+                    lastEditedBy: currentActor(),
+                    contentChangedAt: new Date().toISOString(),
+                  });
+              }
+              this.scheduleSave();
+              this.notifyChange('nodes');
+            });
+          this.recordMutation({
+            operationType: 'data' in result ? 'groupNodes' : 'addEdge',
+            description: `Created ${result.type} on stored board`,
+            forward: edge ? this.suppressed(() => this.addEdge(structuredClone(edge))) : restore(changed),
+            inverse:
+              'data' in result
+                ? restore(before!.nodes.filter((node) => changed.some((item) => item.id === node.id)))
+                : this.suppressed(() => this.removeEdge(result.id)),
+          });
+        }
+      }
+      for (const [id, revision] of activeLinkRevisions) {
+        const existing = this.nodes.get(id);
+        if (existing) this.nodes.set(id, { ...existing, linksRevision: revision });
+      }
+      this._contentRevision = activeRevision;
+      if (active || activeLinkRevisions.size) this.notifyChange('nodes');
+    }
+    return result;
+  }
+
+  /** Read a board without activating it. This projection is not a write payload. */
   readBoard(
     id: string,
     includeBlobs = true,
@@ -1145,6 +1481,7 @@ class CanvasStateManager {
     }
     const state = loadStateFromDB(this._db, id);
     if (!state) return null;
+    this.initializePersistedWikiLinks(state, id);
     const pins = new Set(state.contextPins);
     state.nodes = state.nodes.map((node) => ({
       ...(includeBlobs ? this.resolveNodeDataBlobs(node) : node),
@@ -1229,12 +1566,15 @@ class CanvasStateManager {
   }
 
   /** Creates a board without opening it. */
-  createBoard(name: string, category: string | null = null): CanvasBoard | null {
+  createBoard(name: string, folder: string | null = null): CanvasBoard | null {
     if (!this._db) return null;
-    return createBoardInDB(this._db, name, category);
+    return createBoardInDB(this._db, name, folder);
   }
 
-  updateBoard(id: string, patch: { name?: string; category?: string | null }): boolean {
+  updateBoard(
+    id: string,
+    patch: Pick<Parameters<typeof updateBoardInDB>[2], 'name' | 'folder' | 'mapPosition' | 'relationVocabulary'>,
+  ): boolean {
     return this._db ? updateBoardInDB(this._db, id, patch) : false;
   }
 
@@ -1246,11 +1586,37 @@ class CanvasStateManager {
     return updateBoardInDB(this._db, id, { readmeNodeId: nodeId });
   }
 
+  /**
+   * Pin a board into the agent's working set (vision move 0a). Workspace-level:
+   * survives board switches and restarts. A repeat pin keeps its first
+   * attribution, like card pins. False when the board does not exist.
+   */
+  pinBoard(id: string, reason?: string): boolean {
+    if (!this._db) return false;
+    const board = this.listBoards().find((entry) => entry.id === id);
+    if (!board) return false;
+    if (board.pin) return true;
+    const pinned = setBoardPinInDB(this._db, id, {
+      pinnedBy: currentActor(),
+      pinnedAt: new Date().toISOString(),
+      ...(reason ? { reason } : {}),
+    });
+    if (pinned) this.notifyChange('pins');
+    return pinned;
+  }
+
+  unpinBoard(id: string): boolean {
+    if (!this._db) return false;
+    const unpinned = setBoardPinInDB(this._db, id, null);
+    if (unpinned) this.notifyChange('pins');
+    return unpinned;
+  }
+
   /** Bounded inactive-board creation; never replaces the state the human has open. */
   createBoardFromBoard(input: {
     sourceBoardId: string;
     name: string;
-    category?: string | null;
+    folder?: string | null;
     nodeIds?: string[];
     includeReadme?: boolean;
     includeStructure?: boolean;
@@ -1314,6 +1680,8 @@ class CanvasStateManager {
         createdBy: actor,
         lastEditedBy: actor,
         contentRevision: index + 1,
+        // The copy starts its own revision history; no read on it has carried links yet.
+        linksRevision: 0,
       };
     });
     nodes.push({
@@ -1330,8 +1698,14 @@ class CanvasStateManager {
       contentRevision: nodes.length + 1,
     });
     const edges = source.layout.edges
-      .filter((edge) => ids.has(edge.from) && ids.has(edge.to))
-      .map((edge) => ({ ...edge, id: randomUUID(), from: ids.get(edge.from)!, to: ids.get(edge.to)! }));
+      .filter((edge) => ids.has(edge.from) && (edge.toBoardId || ids.has(edge.to)))
+      .map((source) => edgeWithoutStamp(source))
+      .map((edge) => ({
+        ...edge,
+        id: `${edge.id.startsWith('codegraph-') ? 'codegraph-' : edge.id.startsWith('boardmap-') ? 'boardmap-' : ''}${randomUUID()}`,
+        from: ids.get(edge.from)!,
+        to: edge.toBoardId ? edge.to : ids.get(edge.to)!,
+      }));
     const state: PersistedCanvasState = {
       version: 1,
       theme: source.state.theme,
@@ -1346,10 +1720,17 @@ class CanvasStateManager {
     const board = createBoardWithStateInDB(
       this._db,
       input.name,
-      input.category ?? null,
+      input.folder ?? null,
       this.externalizePersistedStateBlobs(state),
       input.includeReadme && source.board.readmeNodeId ? (ids.get(source.board.readmeNodeId) ?? null) : null,
+      (boardId, nodeId) => this.invalidateRelationTarget(boardId, nodeId),
     );
+    updateBoardInDB(this._db, board.id, {
+      previousBoardId: source.board.id,
+      relationVocabulary: source.board.relationVocabulary,
+    });
+    board.previousBoardId = source.board.id;
+    board.relationVocabulary = source.board.relationVocabulary;
     const referencedAttachmentIds = new Set<string>();
     for (const node of nodes) {
       if (typeof node.data.attachmentId === 'string') referencedAttachmentIds.add(node.data.attachmentId);
@@ -1389,7 +1770,9 @@ class CanvasStateManager {
   deleteBoard(id: string): boolean {
     if (!this._db) return false;
     if (id === this._activeBoardId && !this.switchBoard(null)) return false;
-    return deleteBoardFromDB(this._db, id);
+    // Reverse relations must include outgoing links still debounced on the open board.
+    if (this._saveTimer || this._lastPersistenceError) this.flushToDisk();
+    return deleteBoardFromDB(this._db, id, (boardId, nodeId) => this.invalidateRelationTarget(boardId, nodeId));
   }
 
   /**
@@ -1410,6 +1793,7 @@ class CanvasStateManager {
     if (id) {
       const state = loadStateFromDB(this._db, id);
       if (!state) return false;
+      this.initializePersistedWikiLinks(state, id);
       next = state;
     }
     this.applyPersistedState(next);
@@ -1476,6 +1860,22 @@ class CanvasStateManager {
     }
   }
 
+  private persistedState(): PersistedCanvasState {
+    return this.externalizePersistedStateBlobs({
+      version: 1,
+      theme: this._theme,
+      tour: this._tour,
+      viewport: this._viewport,
+      nodes: Array.from(this.nodes.values()),
+      edges: Array.from(this.edges.values()),
+      annotations: Array.from(this.annotations.values()),
+      contextPins: Array.from(this._contextPinnedNodeIds),
+      contextPinMeta: this.pinMetaRecord(),
+      ax: this.getAxState(),
+      revisionState: this.revisionState(),
+    });
+  }
+
   /** Write current state to SQLite immediately. */
   private saveToDisk(): boolean {
     if (!this._db) return false;
@@ -1487,20 +1887,7 @@ class CanvasStateManager {
       }
       const boardId = this.ensureActiveBoard();
       if (!boardId) return false;
-      const payload = this.externalizePersistedStateBlobs({
-        version: 1,
-        theme: this._theme,
-        tour: this._tour,
-        viewport: this._viewport,
-        nodes: Array.from(this.nodes.values()),
-        edges: Array.from(this.edges.values()),
-        annotations: Array.from(this.annotations.values()),
-        contextPins: Array.from(this._contextPinnedNodeIds),
-        contextPinMeta: this.pinMetaRecord(),
-        ax: this.getAxState(),
-        revisionState: this.revisionState(),
-      });
-      saveStateToDB(this._db, boardId, payload);
+      saveStateToDB(this._db, boardId, this.persistedState());
       this._lastPersistenceError = null;
       return true;
     } catch (error) {
@@ -1553,6 +1940,10 @@ class CanvasStateManager {
   }
 
   private applyPersistedState(state: PersistedCanvasState): void {
+    // Validate the complete replacement before discarding any live board state.
+    const nodes = (Array.isArray(state.nodes) ? state.nodes : [])
+      .filter((node) => node?.id)
+      .map((node) => structuredClone(this.normalizeNode(node)));
     this._boardGeneration += 1;
     this._tour = state.tour ? structuredClone(state.tour) : undefined;
     this.nodes.clear();
@@ -1572,13 +1963,7 @@ class CanvasStateManager {
     };
     this._theme = normalizeCanvasTheme(state.theme, this._theme);
 
-    if (Array.isArray(state.nodes)) {
-      for (const node of state.nodes) {
-        if (node?.id) {
-          this.nodes.set(node.id, structuredClone(this.normalizeNode(node)));
-        }
-      }
-    }
+    for (const node of nodes) this.nodes.set(node.id, node);
     if (Array.isArray(state.edges)) {
       for (const edge of state.edges) {
         if (edge?.id) this.edges.set(edge.id, structuredClone(edge));
@@ -1807,7 +2192,15 @@ class CanvasStateManager {
       tour: resolved.state.tour,
       theme: normalizeCanvasTheme(resolved.state.theme, this._theme),
       viewport: structuredClone(resolved.state.viewport),
-      nodes: Array.isArray(resolved.state.nodes) ? resolved.state.nodes.map((node) => structuredClone(node)) : [],
+      nodes: Array.isArray(resolved.state.nodes)
+        ? resolved.state.nodes.map((node) => {
+            const cloned = structuredClone(node);
+            const current = this.nodes.get(cloned.id);
+            return cloned.type === 'markdown' && cloned.data.wikiLinks === undefined
+              ? this.bindWikiLinks(this.resolveNodeDataBlobs(cloned), current)
+              : cloned;
+          })
+        : [],
       edges: Array.isArray(resolved.state.edges) ? resolved.state.edges.map((edge) => structuredClone(edge)) : [],
       annotations: Array.isArray(resolved.state.annotations)
         ? resolved.state.annotations.map((annotation) => structuredClone(annotation))
@@ -1821,7 +2214,7 @@ class CanvasStateManager {
     try {
       const revisionBeforeRestore = this._contentRevision;
       this.applyPersistedState({ ...nextState, revisionState: this.revisionState() });
-      this.restampRestoredContent(previousState.nodes, revisionBeforeRestore);
+      this.restampRestoredContent(previousState.nodes, previousState.edges, revisionBeforeRestore);
       this.scheduleSave();
       this.notifyChange('nodes');
       this.notifyChange('pins');
@@ -1831,9 +2224,10 @@ class CanvasStateManager {
         description: `Restored snapshot "${resolved.snapshot.name}"`,
         forward: this.suppressed(() => {
           const before = Array.from(this.nodes.values(), (node) => structuredClone(node));
+          const edgesBefore = this.getEdges();
           const revisionBeforeReplay = this._contentRevision;
           this.applyPersistedState({ ...nextState, revisionState: this.revisionState() });
-          this.restampRestoredContent(before, revisionBeforeReplay);
+          this.restampRestoredContent(before, edgesBefore, revisionBeforeReplay);
           this.scheduleSave();
           this.notifyChange('nodes');
           this.notifyChange('pins');
@@ -1841,9 +2235,10 @@ class CanvasStateManager {
         }),
         inverse: this.suppressed(() => {
           const before = Array.from(this.nodes.values(), (node) => structuredClone(node));
+          const edgesBefore = this.getEdges();
           const revisionBeforeReplay = this._contentRevision;
           this.applyPersistedState({ ...previousState, revisionState: this.revisionState() });
-          this.restampRestoredContent(before, revisionBeforeReplay);
+          this.restampRestoredContent(before, edgesBefore, revisionBeforeReplay);
           this.scheduleSave();
           this.notifyChange('nodes');
           this.notifyChange('pins');
@@ -1950,37 +2345,178 @@ class CanvasStateManager {
 
   // ── Node CRUD ──────────────────────────────────────────────
 
-  private restampRestoredContent(beforeNodes: CanvasNodeState[], minimumRevision: number): void {
+  private restampRestoredContent(
+    beforeNodes: CanvasNodeState[],
+    beforeEdges: CanvasEdge[],
+    minimumRevision: number,
+  ): void {
     this._contentRevision = Math.max(this._contentRevision, minimumRevision);
     const before = new Map(beforeNodes.map((node) => [node.id, node]));
     const restoredIds = new Set(this.nodes.keys());
     for (const [id, node] of this.nodes) {
       const old = before.get(id);
+      const linksRevision = old ? old.linksRevision : node.linksRevision;
       if (old && !this.nodeContentChanged(old, node)) {
-        this.nodes.set(id, { ...node, contentRevision: old.contentRevision, lastEditedBy: old.lastEditedBy });
+        this.nodes.set(id, {
+          ...node,
+          contentRevision: old.contentRevision,
+          contentChangedAt: old.contentChangedAt,
+          linksRevision,
+          lastEditedBy: old.lastEditedBy,
+        });
         continue;
       }
       const revision = this.nextContentRevision();
-      this.nodes.set(id, { ...node, lastEditedBy: currentActor(), contentRevision: revision });
+      this.nodes.set(id, {
+        ...node,
+        lastEditedBy: currentActor(),
+        contentRevision: revision,
+        contentChangedAt: new Date().toISOString(),
+        linksRevision,
+      });
+    }
+    for (const id of new Set([...before.keys(), ...restoredIds]))
+      this.touchWikiRelations(before.get(id), this.nodes.get(id));
+    for (const id of new Set([...before.keys(), ...restoredIds])) {
+      if (before.has(id) !== restoredIds.has(id)) this.invalidateIncomingRelations(id);
     }
     for (const old of beforeNodes) {
       if (!restoredIds.has(old.id)) this.recordDeletion(old.id);
     }
+    // A link the restore added, retyped, relabelled or removed is a link change on both ends.
+    // It comes back as it was saved, author included, under a new revision.
+    const relation = (edge: CanvasEdge) =>
+      JSON.stringify([edge.from, edge.toBoardId, edge.to, edge.type, edge.kind, edge.label, edge.reason]);
+    const edgesBefore = new Map(beforeEdges.map((edge) => [edge.id, edge]));
+    for (const [id, edge] of this.edges) {
+      const old = edgesBefore.get(id);
+      if (old && relation(old) === relation(edge)) {
+        this.edges.set(id, { ...edgeWithoutStamp(edge), ...edgeStamp(old) });
+        continue;
+      }
+      if (old && (old.from !== edge.from || old.to !== edge.to || old.toBoardId !== edge.toBoardId))
+        this.touchRelations(old);
+      const stamp = this.touchRelations(edge);
+      this.edges.set(
+        id,
+        edge.changedBy
+          ? { ...edge, ...(stamp.revision !== undefined ? { revision: stamp.revision } : {}) }
+          : { ...edge, ...stamp },
+      );
+    }
+    for (const old of beforeEdges) {
+      if (!this.edges.has(old.id)) this.touchRelations(old);
+    }
   }
 
   private semanticData(data: Record<string, unknown>): Record<string, unknown> {
     const copy = { ...data };
     delete copy.strictSize;
     delete copy.arrangeLocked;
+    delete copy.lifecycleOverride;
+    delete copy.fetchedAt;
+    if (copy.provenance && typeof copy.provenance === 'object') {
+      const provenance = { ...(copy.provenance as Record<string, unknown>) };
+      delete provenance.syncedAt;
+      copy.provenance = provenance;
+    }
     return copy;
   }
 
+  /** A small name/ID catalog, read only when Markdown is saved, never on a drag frame. */
+  wikiCatalog(): WikiBoard[] {
+    return this.listBoards().map((board) => ({
+      id: board.id,
+      name: board.name,
+      cards: (board.id === this._activeBoardId
+        ? [...this.nodes.values()]
+        : this._db
+          ? (loadStateFromDB(this._db, board.id)?.nodes ?? [])
+          : []
+      ).map((node) => ({ id: node.id, title: typeof node.data.title === 'string' ? node.data.title : node.id })),
+    }));
+  }
+
+  /** Backfill only uninitialized live rows, not snapshots or authoritative empty/unresolved bindings. */
+  private initializePersistedWikiLinks(state: PersistedCanvasState, boardId: string): void {
+    const legacy = state.nodes.filter((node) => node.type === 'markdown' && node.data.wikiLinks === undefined);
+    if (!legacy.length || !this._db) return;
+    // Read the persisted catalog directly: readBoard would recursively initialize other boards.
+    const catalog = listBoardsFromDB(this._db).map((board) => ({
+      id: board.id,
+      name: board.name,
+      cards: (board.id === this._activeBoardId && board.id !== boardId
+        ? [...this.nodes.values()]
+        : board.id === boardId
+          ? state.nodes
+          : (loadStateFromDB(this._db!, board.id)?.nodes ?? [])
+      ).map((node) => ({ id: node.id, title: typeof node.data.title === 'string' ? node.data.title : node.id })),
+    }));
+    this._db.transaction(() => {
+      for (const node of legacy) {
+        const resolved = this.resolveNodeDataBlobs(node);
+        const content = typeof resolved.data.content === 'string' ? resolved.data.content : '';
+        node.data = { ...node.data, wikiLinks: resolveWikiLinks(content, [], catalog) };
+        this._db!.run('UPDATE nodes SET data = ? WHERE board_id = ? AND id = ?', [
+          JSON.stringify(node.data),
+          boardId,
+          node.id,
+        ]);
+      }
+    })();
+  }
+
+  private bindWikiLinks(
+    node: CanvasNodeState,
+    existing?: CanvasNodeState,
+    savedWikiLinks?: WikiLink[],
+    savingContent = false,
+  ): CanvasNodeState {
+    if (node.type !== 'markdown') return node;
+    if (savedWikiLinks !== undefined) {
+      const data = { ...node.data };
+      data.wikiLinks = structuredClone(savedWikiLinks);
+      return { ...node, data };
+    }
+    if (
+      !savingContent &&
+      existing?.type === node.type &&
+      existing.data.content === node.data.content &&
+      existing.data.wikiLinks !== undefined
+    ) {
+      const data = { ...node.data };
+      data.wikiLinks = structuredClone(existing.data.wikiLinks);
+      return { ...node, data };
+    }
+    const content = typeof node.data.content === 'string' ? node.data.content : '';
+    const previous = existing ? wikiLinksFromData(existing.data) : [];
+    const initializedRefs =
+      existing?.data.wikiLinks !== undefined && typeof existing.data.content === 'string'
+        ? wikiReferences(existing.data.content)
+        : [];
+    const refs = wikiReferences(content).filter(
+      (ref) => !initializedRefs.includes(ref) || previous.some((link) => link.ref === ref),
+    );
+    const needsResolution = refs.some(
+      (ref) => !previous.some((link) => link.ref === ref && (!savingContent || link.target)),
+    );
+    const catalog = needsResolution ? this.wikiCatalog() : [];
+    const links = refs.map((ref) => {
+      const saved = previous.find((link) => link.ref === ref);
+      return saved && (!savingContent || saved.target) ? saved : resolveWikiLinks(`[[${ref}]]`, [], catalog)[0];
+    });
+    const data = { ...node.data };
+    data.wikiLinks = links;
+    return { ...node, data };
+  }
+
   private nodeContentChanged(a: CanvasNodeState, b: CanvasNodeState): boolean {
     return a.type !== b.type || JSON.stringify(this.semanticData(a.data)) !== JSON.stringify(this.semanticData(b.data));
   }
 
   private setSemanticNode(node: CanvasNodeState): void {
     const existing = this.nodes.get(node.id);
+    node = this.bindWikiLinks(node, existing);
     if (!existing || !this.nodeContentChanged(existing, node)) {
       this.nodes.set(node.id, node);
       return;
@@ -1994,6 +2530,7 @@ class CanvasStateManager {
       createdBy: existing.createdBy,
       lastEditedBy: currentActor(),
       contentRevision: this.nextContentRevision(),
+      contentChangedAt: new Date().toISOString(),
     });
   }
 
@@ -2011,24 +2548,56 @@ class CanvasStateManager {
     return structuredClone(this._viewport);
   }
 
-  addNode(node: CanvasNodeState): void {
+  addNode(node: CanvasNodeState, savedWikiLinks?: WikiLink[]): void {
+    node = this.normalizeNode(node);
     const actor = currentActor();
+    const now = new Date().toISOString();
+    const provenance = node.data.provenance as { sourceKind?: string } | undefined;
+    const imported =
+      node.data.contentOrigin === 'imported' ||
+      node.data.source !== undefined ||
+      (provenance !== undefined && provenance.sourceKind !== 'recipe');
     const cloned = structuredClone(
-      this.normalizeNode({
-        ...node,
-        createdBy: actor,
-        lastEditedBy: actor,
-        contentRevision: this.nextContentRevision(),
-      }),
+      this.normalizeNode(
+        this.bindWikiLinks(
+          {
+            ...node,
+            createdBy: actor,
+            lastEditedBy: actor,
+            contentRevision: this.nextContentRevision(),
+            contentChangedAt: now,
+            freshnessStartedAt: imported ? undefined : now,
+          },
+          undefined,
+          savedWikiLinks,
+        ),
+      ),
     );
     this.nodes.set(node.id, cloned);
+    this.touchWikiRelations(undefined, cloned);
+    this.invalidateIncomingRelations(node.id);
     this.scheduleSave();
     this.notifyChange('nodes');
+    this.recordNodeCreation(cloned);
+  }
+
+  private recordNodeCreation(cloned: CanvasNodeState): void {
     this.recordMutation({
       operationType: 'addNode',
-      description: `Added ${node.type} node "${(node.data.title as string) ?? node.id}"`,
-      forward: this.suppressed(() => this.addNode(structuredClone(cloned))),
-      inverse: this.suppressed(() => this.removeNode(node.id)),
+      description: `Added ${cloned.type} node "${(cloned.data.title as string) ?? cloned.id}"`,
+      forward: this.suppressed(() => {
+        this.nodes.set(cloned.id, {
+          ...structuredClone(cloned),
+          contentRevision: this.nextContentRevision(),
+          contentChangedAt: new Date().toISOString(),
+          lastEditedBy: currentActor(),
+        });
+        this.touchWikiRelations(undefined, this.nodes.get(cloned.id));
+        this.invalidateIncomingRelations(cloned.id);
+        this.scheduleSave();
+        this.notifyChange('nodes');
+      }),
+      inverse: this.suppressed(() => this.removeNode(cloned.id)),
     });
   }
 
@@ -2040,10 +2609,39 @@ class CanvasStateManager {
     this.addNode(node);
   }
 
-  updateNode(id: string, patch: Partial<CanvasNodeState>): void {
+  /** Metadata stays on the stored node: no blob hydration, wiki resolution or group reflow. */
+  setNodeLifecycle(id: string, value: Lifecycle | null): void {
+    const existing = this.nodes.get(id);
+    if (!existing) throw new OperationError('Card not found.', 404);
+    const lifecycle = value === null ? null : lifecycleSchema.parse(value);
+    const previous = structuredClone(existing.data.lifecycleOverride) as Lifecycle | null | undefined;
+    const apply = (override: Lifecycle | null | undefined) => {
+      const node = this.nodes.get(id);
+      if (!node) return;
+      const data = { ...node.data };
+      if (override === undefined) delete data.lifecycleOverride;
+      else data.lifecycleOverride = structuredClone(override);
+      this.nodes.set(id, { ...node, data });
+      this.scheduleSave();
+      this.notifyChange('nodes');
+    };
+    apply(lifecycle);
+    this.recordMutation({
+      operationType: 'updateNode',
+      description: `Changed lifecycle of "${existing.data.title ?? id}"`,
+      forward: this.suppressed(() => apply(lifecycle)),
+      inverse: this.suppressed(() => apply(previous)),
+    });
+  }
+
+  // null replays a legacy snapshot using existing records before resolving new refs.
+  updateNode(id: string, patch: Partial<CanvasNodeState>, savedWikiLinks?: WikiLink[] | null): void {
     const existing = this.nodes.get(id);
     if (!existing) return;
     if (patch.data) {
+      if (patch.data.contentOrigin !== existing.data.contentOrigin) {
+        throw new OperationError('Content origin is immutable after creation.');
+      }
       const attachmentId = existing.data.attachmentId;
       if (typeof attachmentId === 'string' && patch.data.attachmentId !== attachmentId) {
         throw new Error('Attachment identity is immutable.');
@@ -2056,10 +2654,17 @@ class CanvasStateManager {
       }
     }
     const oldSnapshot = structuredClone(existing);
+    let nextNode = this.normalizeNode(
+      this.bindWikiLinks(
+        { ...existing, ...patch, freshnessStartedAt: existing.freshnessStartedAt },
+        existing,
+        savedWikiLinks ?? undefined,
+        savedWikiLinks !== null && !!patch.data && 'content' in patch.data,
+      ),
+    );
     if (existing.type === 'group' && patch.position) {
       this.translateGroupChildren(id, patch.position.x - existing.position.x, patch.position.y - existing.position.y);
     }
-    let nextNode = this.normalizeNode({ ...existing, ...patch });
     if (this.nodeContentChanged(existing, nextNode)) {
       const data = { ...nextNode.data };
       const suppliedData = patch.data;
@@ -2071,6 +2676,7 @@ class CanvasStateManager {
         createdBy: existing.createdBy ?? unknownActor(),
         lastEditedBy: currentActor(),
         contentRevision: this.nextContentRevision(),
+        contentChangedAt: new Date().toISOString(),
       };
     } else {
       nextNode = {
@@ -2078,9 +2684,11 @@ class CanvasStateManager {
         createdBy: existing.createdBy,
         lastEditedBy: existing.lastEditedBy,
         contentRevision: existing.contentRevision,
+        contentChangedAt: existing.contentChangedAt,
       };
     }
     this.nodes.set(id, nextNode);
+    this.touchWikiRelations(existing, nextNode);
     const parentGroupId = existing.data.parentGroup as string | undefined;
     if (parentGroupId) {
       // Moving or resizing a grouped child re-fits the group frame but must NOT
@@ -2094,18 +2702,29 @@ class CanvasStateManager {
     this.recordMutation({
       operationType: 'updateNode',
       description: `Updated node "${(existing.data.title as string) ?? id}"`,
-      forward: this.suppressed(() => this.updateNode(id, structuredClone(patch))),
+      forward: this.suppressed(() =>
+        this.updateNode(
+          id,
+          structuredClone(patch),
+          nextNode.type === 'markdown' ? wikiLinksFromData(nextNode.data) : undefined,
+        ),
+      ),
       inverse: this.suppressed(() => {
         const restored = structuredClone(oldSnapshot);
         const current = this.nodes.get(id);
         if (current && this.nodeContentChanged(current, restored)) {
           restored.contentRevision = this.nextContentRevision();
+          restored.contentChangedAt = new Date().toISOString();
           restored.lastEditedBy = currentActor();
         } else if (current) {
           restored.contentRevision = current.contentRevision;
+          restored.contentChangedAt = current.contentChangedAt;
           restored.lastEditedBy = current.lastEditedBy;
         }
+        // Links are tracked apart: undoing a node change never rolls its links revision back.
+        if (current) restored.linksRevision = current.linksRevision;
         this.nodes.set(id, restored);
+        this.touchWikiRelations(current, restored);
         this.scheduleSave();
         this.notifyChange('nodes');
       }),
@@ -2150,6 +2769,10 @@ class CanvasStateManager {
       }
     }
 
+    if (existing) {
+      this.touchWikiRelations(existing, undefined);
+      this.invalidateIncomingRelations(id);
+    }
     this.nodes.delete(id);
     this.removeEdgesForNode(id);
     this._contextPinnedNodeIds.delete(id);
@@ -2200,7 +2823,10 @@ class CanvasStateManager {
             : `Removed ${cloned.type} node "${title}"`,
         forward: this.suppressed(() => this.removeNode(id)),
         inverse: this.suppressed(() => {
-          this.addNode(structuredClone(cloned));
+          this.addNode(
+            structuredClone(cloned),
+            cloned.type === 'markdown' ? wikiLinksFromData(cloned.data) : undefined,
+          );
           const restored = this.nodes.get(id);
           if (restored) this.nodes.set(id, { ...restored, createdBy: cloned.createdBy ?? unknownActor() });
           // A restored group takes its children back; the enclosing group's membership is restored verbatim.
@@ -2237,6 +2863,16 @@ class CanvasStateManager {
     return node ? structuredClone(this.nodeForRead(node)) : undefined;
   }
 
+  /** Who made and last edited each card, and its content revision — no content, no copies. */
+  nodeStamps(): Array<Pick<CanvasNodeState, 'id' | 'createdBy' | 'lastEditedBy' | 'contentRevision'>> {
+    return [...this.nodes.values()].map(({ id, createdBy, lastEditedBy, contentRevision }) => ({
+      id,
+      createdBy,
+      lastEditedBy,
+      contentRevision,
+    }));
+  }
+
   getNodeForPersistence(id: string): CanvasNodeState | undefined {
     const node = this.nodes.get(id);
     return node ? structuredClone(this.externalizeNodeDataBlobs(node)) : undefined;
@@ -2244,15 +2880,100 @@ class CanvasStateManager {
 
   // ── Edge CRUD ──────────────────────────────────────────────
 
+  /**
+   * Links are tracked apart from text (connection changes, option C of
+   * docs/design/LinksOptions.dc.html): a link change advances both endpoints'
+   * links revision, never their content revision, so cards keep their read
+   * marks while the next incremental brief resends them with their new
+   * relations. Generated auto-edges (code graph, board map) do not count.
+   * Returns the stamp for the changed link.
+   */
+  private touchRelations(
+    edge: Pick<CanvasEdge, 'id' | 'from' | 'to' | 'toBoardId'>,
+  ): Pick<CanvasEdge, 'revision' | 'changedBy' | 'changedAt'> {
+    if (edge.id.startsWith('codegraph-') || edge.id.startsWith('boardmap-')) return {};
+    const revision = this.nextContentRevision();
+    for (const id of [edge.from, ...(!edge.toBoardId || edge.toBoardId === this._activeBoardId ? [edge.to] : [])]) {
+      const node = this.nodes.get(id);
+      if (node) this.nodes.set(id, { ...node, linksRevision: revision });
+    }
+    if (edge.toBoardId && edge.toBoardId !== this._activeBoardId)
+      this.invalidateRelationTarget(edge.toBoardId, edge.to);
+    return { revision, changedBy: currentActor(), changedAt: new Date().toISOString() };
+  }
+
+  private invalidateRelationTarget(boardId: string, nodeId: string): void {
+    if (boardId === this._activeBoardId) {
+      const node = this.nodes.get(nodeId);
+      if (node) {
+        this.nodes.set(nodeId, { ...node, linksRevision: this.nextContentRevision() });
+        this.scheduleSave();
+        this.notifyChange('nodes');
+      }
+    } else if (this._db) invalidateLinksInDB(this._db, boardId, nodeId);
+  }
+
+  /** Saved wiki relationships have the same source/target clocks as native links. */
+  private touchWikiRelations(before?: CanvasNodeState, after?: CanvasNodeState): void {
+    const previous = before?.type === 'markdown' ? wikiLinksFromData(before.data) : [];
+    const next = after?.type === 'markdown' ? wikiLinksFromData(after.data) : [];
+    if (JSON.stringify(previous) === JSON.stringify(next)) return;
+    const source = after ?? before;
+    if (source && this._activeBoardId) this.invalidateRelationTarget(this._activeBoardId, source.id);
+    const targets = new Map(
+      [...previous, ...next].flatMap(({ target }) =>
+        target?.cardId ? [[JSON.stringify(target), target] as const] : [],
+      ),
+    );
+    for (const target of targets.values()) this.invalidateRelationTarget(target.boardId, target.cardId!);
+  }
+
+  private invalidateIncomingRelations(nodeId: string): void {
+    for (const source of this.nodes.values()) {
+      if (
+        source.type === 'markdown' &&
+        wikiLinksFromData(source.data).some(
+          ({ target }) => target?.boardId === this._activeBoardId && target.cardId === nodeId,
+        )
+      )
+        this.invalidateRelationTarget(this._activeBoardId!, source.id);
+    }
+    if (this._db && this._activeBoardId)
+      invalidateIncomingLinksInDB(this._db, this._activeBoardId, nodeId, (boardId, sourceId) =>
+        this.invalidateRelationTarget(boardId, sourceId),
+      );
+  }
+
   addEdge(edge: CanvasEdge): boolean {
-    if (edge.from === edge.to) return false;
+    if (!edge.toBoardId && edge.from === edge.to) return false;
     for (const existing of this.edges.values()) {
-      if (existing.from === edge.from && existing.to === edge.to && existing.type === edge.type) {
+      if (
+        existing.from === edge.from &&
+        existing.to === edge.to &&
+        existing.toBoardId === edge.toBoardId &&
+        existing.type === edge.type &&
+        existing.kind === edge.kind
+      ) {
         return false;
       }
     }
-    const cloned = structuredClone(edge);
-    this.edges.set(edge.id, edge);
+    if (!edge.changedBy) edge = { ...edge, sourceRevision: this.relationSourceRevision(edge) };
+    const stamp = this.touchRelations(edge);
+    // A link that arrives with an author is being restored (undo of a removal, a
+    // demo seed): it keeps its authorship and only takes a new revision. The API
+    // builds new links from scratch, so a new link is always the caller's.
+    this.edges.set(
+      edge.id,
+      edge.changedBy
+        ? { ...edge, ...(stamp.revision !== undefined ? { revision: stamp.revision } : {}) }
+        : {
+            ...edge,
+            ...stamp,
+            ...(stamp.changedBy ? { createdBy: stamp.changedBy, createdAt: stamp.changedAt } : {}),
+          },
+    );
+    // Redo replays the link as stored, with its author.
+    const cloned = structuredClone(this.edges.get(edge.id) as CanvasEdge);
     this.scheduleSave();
     this.notifyChange('nodes');
     this.recordMutation({
@@ -2264,25 +2985,54 @@ class CanvasStateManager {
     return true;
   }
 
-  updateEdge(id: string, patch: Partial<Pick<CanvasEdge, 'type' | 'label' | 'style' | 'animated'>>): CanvasEdge | null {
+  private relationSourceRevision(edge: CanvasEdge): number | undefined {
+    const end = relationSourceEnd(edge);
+    if (!end) return undefined;
+    const node =
+      end === 'to' && edge.toBoardId && edge.toBoardId !== this._activeBoardId
+        ? this.readBoard(edge.toBoardId, false)?.layout.nodes.find((item) => item.id === edge.to)
+        : this.nodes.get(end === 'from' ? edge.from : edge.to);
+    return node?.contentRevision;
+  }
+
+  updateEdge(
+    id: string,
+    patch: Partial<Pick<CanvasEdge, 'type' | 'kind' | 'reason' | 'label' | 'style' | 'animated'>>,
+  ): CanvasEdge | null {
     const existing = this.edges.get(id);
     if (!existing) return null;
     // Retyping onto an existing from/to/type triple would create the duplicate
     // addEdge refuses.
-    if (patch.type && patch.type !== existing.type) {
+    const candidate = { ...existing, ...patch };
+    if (candidate.type !== existing.type || candidate.kind !== existing.kind) {
       for (const other of this.edges.values()) {
-        if (other.id !== id && other.from === existing.from && other.to === existing.to && other.type === patch.type) {
+        if (
+          other.id !== id &&
+          other.from === existing.from &&
+          other.to === existing.to &&
+          other.toBoardId === existing.toBoardId &&
+          other.type === candidate.type &&
+          other.kind === candidate.kind
+        ) {
           return null;
         }
       }
     }
     const before = structuredClone(existing);
     const updated: CanvasEdge = { ...existing, ...patch };
+    if (candidate.type !== existing.type || candidate.kind !== existing.kind)
+      updated.sourceRevision = this.relationSourceRevision(updated);
     // An explicit undefined in the patch clears the field (label/style/animated
     // are optional on the wire shape — never store undefined values).
-    for (const key of ['label', 'style', 'animated'] as const) {
+    for (const key of ['kind', 'reason', 'label', 'style', 'animated'] as const) {
       if (key in patch && patch[key] === undefined) delete updated[key];
     }
+    const relationChanged =
+      updated.type !== before.type ||
+      updated.label !== before.label ||
+      updated.kind !== before.kind ||
+      updated.reason !== before.reason;
+    if (relationChanged) Object.assign(updated, this.touchRelations(updated));
     const after = structuredClone(updated);
     this.edges.set(id, updated);
     this.scheduleSave();
@@ -2291,12 +3041,12 @@ class CanvasStateManager {
       operationType: 'updateEdge',
       description: `Updated ${updated.type} edge ${updated.from} → ${updated.to}`,
       forward: this.suppressed(() => {
-        this.edges.set(id, structuredClone(after));
+        this.edges.set(id, this.replayEdge(after, relationChanged));
         this.scheduleSave();
         this.notifyChange('nodes');
       }),
       inverse: this.suppressed(() => {
-        this.edges.set(id, structuredClone(before));
+        this.edges.set(id, this.replayEdge(before, relationChanged));
         this.scheduleSave();
         this.notifyChange('nodes');
       }),
@@ -2304,11 +3054,27 @@ class CanvasStateManager {
     return structuredClone(updated);
   }
 
+  /**
+   * An edge as undo/redo puts it back. A relation change restores the link as it
+   * was, author included, under a new revision so the next brief carries it; a
+   * style-only change keeps the current stamp, so it never hides a later relabel.
+   */
+  private replayEdge(snapshot: CanvasEdge, relationChanged: boolean): CanvasEdge {
+    const edge = structuredClone(snapshot);
+    if (relationChanged) {
+      const { revision } = this.touchRelations(edge);
+      return revision === undefined ? edge : { ...edge, revision };
+    }
+    const current = this.edges.get(snapshot.id);
+    return { ...edgeWithoutStamp(edge), ...(current ? edgeStamp(current) : {}) };
+  }
+
   removeEdge(id: string): boolean {
     const existing = this.edges.get(id);
     const cloned = existing ? structuredClone(existing) : null;
     const removed = this.edges.delete(id);
     if (removed && cloned) {
+      this.touchRelations(cloned);
       this.scheduleSave();
       this.notifyChange('nodes');
       this.recordMutation({
@@ -2327,7 +3093,10 @@ class CanvasStateManager {
 
   getEdgesForNode(nodeId: string): CanvasEdge[] {
     return Array.from(this.edges.values())
-      .filter((edge) => edge.from === nodeId || edge.to === nodeId)
+      .filter(
+        (edge) =>
+          edge.from === nodeId || ((!edge.toBoardId || edge.toBoardId === this._activeBoardId) && edge.to === nodeId),
+      )
       .map((edge) => structuredClone(edge));
   }
 
@@ -2367,8 +3136,10 @@ class CanvasStateManager {
 
   private removeEdgesForNode(nodeId: string): void {
     for (const [id, edge] of this.edges) {
-      if (edge.from === nodeId || edge.to === nodeId) {
+      if (edge.from === nodeId || ((!edge.toBoardId || edge.toBoardId === this._activeBoardId) && edge.to === nodeId)) {
         this.edges.delete(id);
+        // The card on the other end lost a link.
+        this.touchRelations(edge);
       }
     }
   }
@@ -2490,7 +3261,8 @@ class CanvasStateManager {
         }),
         inverse: this.suppressed(() => {
           for (const snapshot of inverseSnapshots) {
-            this.nodes.set(snapshot.id, structuredClone(snapshot.node));
+            const linksRevision = this.nodes.get(snapshot.id)?.linksRevision ?? snapshot.node.linksRevision;
+            this.nodes.set(snapshot.id, { ...structuredClone(snapshot.node), linksRevision });
           }
           this.reflowAllGroups();
           this.scheduleSave();
@@ -2522,6 +3294,23 @@ class CanvasStateManager {
     return this._theme;
   }
 
+  getWorkspaceSettings(): WorkspaceSettings {
+    const stored = this._db ? readMetaFromDB(this._db, 'workspace_settings') : null;
+    return stored === null
+      ? { ...DEFAULT_WORKSPACE_SETTINGS }
+      : workspaceSettingsSchema.parse({ ...DEFAULT_WORKSPACE_SETTINGS, ...JSON.parse(stored) });
+  }
+
+  updateWorkspaceSettings(patch: Partial<WorkspaceSettings>): WorkspaceSettings {
+    if (!this._db) throw new OperationError('Settings need a workspace database.', 409);
+    const next = workspaceSettingsSchema.parse({
+      ...this.getWorkspaceSettings(),
+      ...workspaceSettingsPatchSchema.parse(patch),
+    });
+    writeMetaToDB(this._db, 'workspace_settings', JSON.stringify(next));
+    return next;
+  }
+
   setTheme(theme: CanvasTheme): CanvasTheme {
     const next = normalizeCanvasTheme(theme, this._theme);
     if (next === this._theme) return this._theme;
@@ -2878,7 +3667,11 @@ class CanvasStateManager {
   recordContextRead(input: ContextReadInput, boardId: string | null = this._activeBoardId): ContextRead | null {
     if (!this._db) return null;
     try {
-      const read = appendContextReadToDB(this._db, input, boardId, this.readRevisions(input, boardId));
+      // A graph read may mark an inactive target seen while its outgoing source
+      // edges are still debounced in memory. Never book seen before the source.
+      if (this._saveTimer || this._lastPersistenceError) this.flushToDisk();
+      const { readNodes, seenLinks } = this.readRevisions(input, boardId);
+      const read = appendContextReadToDB(this._db, input, boardId, readNodes, seenLinks);
       this._contextReadListener?.(boardId);
       return read;
     } catch (error) {
@@ -2887,18 +3680,41 @@ class CanvasStateManager {
     }
   }
 
-  /** The delivered ids that are nodes on the read board, each with its content revision now. */
-  private readRevisions(input: ContextReadInput, boardId: string | null): Record<string, number> {
-    if (!boardId) return {};
+  /**
+   * The delivered ids that are nodes on the read board: those read in full with
+   * their content revision now, and every one that arrived (summaries included)
+   * with its links revision now.
+   */
+  private readRevisions(
+    input: ContextReadInput,
+    boardId: string | null,
+  ): { readNodes: Record<string, number>; seenLinks: Record<string, number> } {
+    const readIds = input.readNodeIds ?? input.deliveredNodeIds;
+    const seenIds = input.seenNodeIds ?? readIds;
+    if (!boardId || (readIds.length === 0 && seenIds.length === 0)) return { readNodes: {}, seenLinks: {} };
     const nodes =
       boardId === this._activeBoardId ? [...this.nodes.values()] : (this.readBoard(boardId, false)?.state.nodes ?? []);
-    const byId = new Map(nodes.map((node) => [node.id, node.contentRevision ?? 0]));
-    const revisions: Record<string, number> = {};
-    for (const id of input.readNodeIds ?? input.deliveredNodeIds) {
-      const revision = byId.get(id);
-      if (revision !== undefined) revisions[id] = revision;
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const readNodes: Record<string, number> = {};
+    for (const id of readIds) {
+      const node = byId.get(id);
+      if (node) readNodes[id] = node.contentRevision ?? 0;
+    }
+    const seenLinks: Record<string, number> = {};
+    for (const id of seenIds) {
+      const node = byId.get(id);
+      if (!node) continue;
+      const revision = input.seenLinkRevisions ? input.seenLinkRevisions[id] : (node.linksRevision ?? 0);
+      if (revision !== undefined && Number.isSafeInteger(revision) && revision >= 0)
+        seenLinks[id] = Math.min(revision, node.linksRevision ?? 0);
     }
-    return revisions;
+    return { readNodes, seenLinks };
+  }
+
+  /** Per node on a board, the newest links revision an agent read carried. */
+  getSeenLinks(boardId: string | null = this._activeBoardId): Record<string, number> {
+    if (!this._db || !boardId) return {};
+    return loadSeenLinksFromDB(this._db, boardId);
   }
 
   /** Per node on a board, the latest agent read that delivered its content. */
@@ -2907,6 +3723,12 @@ class CanvasStateManager {
     return loadNodeReadStatusFromDB(this._db, boardId);
   }
 
+  /** The latest agent read on a board, of any kind, or null. */
+  getBoardLastRead(boardId: string | null = this._activeBoardId): { lastReadAt: string; lastReadBy: string } | null {
+    if (!this._db || !boardId) return null;
+    return loadBoardLastReadFromDB(this._db, boardId);
+  }
+
   /** Nodes on a board whose content an agent read at or after `since` (ISO). */
   getReadNodeIdsSince(boardId: string | null, since: string): string[] {
     if (!this._db || !boardId) return [];
@@ -3103,7 +3925,12 @@ class CanvasStateManager {
     const oldPins = Array.from(this._contextPinnedNodeIds);
     const oldAxState = this.getAxState();
     const oldViewport = { ...this._viewport };
-    for (const node of oldNodes) this.recordDeletion(node.id);
+    for (const edge of oldEdges) this.touchRelations(edge);
+    for (const node of oldNodes) {
+      this.touchWikiRelations(node, undefined);
+      this.invalidateIncomingRelations(node.id);
+      this.recordDeletion(node.id);
+    }
     this.nodes.clear();
     this.edges.clear();
     this.annotations.clear();
@@ -3123,7 +3950,8 @@ class CanvasStateManager {
       description: `Cleared canvas (was ${oldNodes.length} nodes, ${oldEdges.length} edges)`,
       forward: this.suppressed(() => this.clear()),
       inverse: this.suppressed(() => {
-        for (const n of oldNodes) this.addNode(structuredClone(n));
+        for (const n of oldNodes)
+          this.addNode(structuredClone(n), n.type === 'markdown' ? wikiLinksFromData(n.data) : undefined);
         for (const e of oldEdges) this.addEdge(structuredClone(e));
         for (const annotation of oldAnnotations) this.addAnnotation(structuredClone(annotation));
         this.setContextPins(oldPins);