pmx-canvas 0.6.5 → 0.7.0

package/src/server/canvas-state.ts

@@ -12,10 +12,19 @@
  * the one-shot boot migration into SQLite was retired.
  */
 
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { tourSchema, type Tour } from '../shared/tour.js';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
-import { isAbsolute, join, dirname, relative } from 'node:path';
+import {
+  copyFileSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  unlinkSync,
+} from 'node:fs';
+import { basename, isAbsolute, join, dirname, relative } from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
 import { normalizeCanvasNodeData } from './canvas-provenance.js';
 import {
@@ -29,13 +38,41 @@ import {
   renameSnapshotInDB,
   writeBlobToDB,
   readBlobFromDB,
-  isDbPopulated,
   checkpointCanvasDb,
+  createBoardInDB,
+  createBoardWithStateInDB,
+  readContextBriefCursor,
+  advanceContextBriefCursor,
+  deleteBoardFromDB,
+  getActiveBoardIdFromDB,
+  getBoardFromDB,
+  listBoardsFromDB,
+  readMetaFromDB,
+  readThemeFromDB,
+  updateBoardInDB,
+  writeMetaToDB,
+  saveThemeToDB,
+  setActiveBoardIdInDB,
+  type CanvasBoard,
   finalizeCanvasDbForClose,
   type PersistedCanvasState,
   type CanvasTheme,
   type AxTimelineQuery,
 } from './canvas-db.js';
+import {
+  copyBoardAttachments,
+  createImport,
+  getAttachment,
+  getImport,
+  listImports,
+  readAttachmentBytes,
+  storeAttachment,
+  updateImport,
+  type DocumentImport,
+  type DocumentImportStatus,
+  type ImportSection,
+  type Attachment,
+} from './document-import.js';
 import { normalizeCanvasTheme } from './canvas-db.js';
 import {
   type CanvasPlacementRect,
@@ -74,6 +111,14 @@ import {
   type PmxAxTimelineSummary,
 } from './ax-state.js';
 import { AxStateManager } from './ax-state-manager.js';
+import { currentActor, unknownActor, type ActorAttribution } from './attribution.js';
+import {
+  appendContextReadToDB,
+  loadContextReadsFromDB,
+  type ContextRead,
+  type ContextReadConsumerSummary,
+  type ContextReadInput,
+} from './context-reads.js';
 
 function logCanvasStateWarning(action: string, error: unknown, details?: Record<string, unknown>): void {
   console.warn(`[canvas-state] ${action}`, { error, ...(details ?? {}) });
@@ -170,6 +215,7 @@ export interface CanvasNodeState {
     | 'webpage'
     | 'json-render'
     | 'graph'
+    | 'board'
     | 'prompt'
     | 'response'
     | 'status'
@@ -188,6 +234,30 @@ export interface CanvasNodeState {
   collapsed: boolean;
   pinned: boolean;
   data: Record<string, unknown>;
+  /** Server-owned provenance. Legacy rows normalize to unknown. */
+  createdBy?: ActorAttribution;
+  lastEditedBy?: ActorAttribution;
+  /** Board-monotonic revision of this node's latest semantic content. */
+  contentRevision?: number;
+}
+
+export interface NodeDeletionTombstone {
+  nodeId: string;
+  revision: number;
+  deletedBy: ActorAttribution;
+}
+
+export interface BoardContentRevision {
+  revision: number;
+  /** Cursors below this value are expired and must perform a full reset. */
+  retentionFloor: number;
+}
+
+export interface BoardContentDelta extends BoardContentRevision {
+  since: number;
+  reset: boolean;
+  nodes: CanvasNodeState[];
+  deleted: NodeDeletionTombstone[];
 }
 
 export interface ViewportState {
@@ -241,6 +311,11 @@ export interface CanvasNodeUpdate {
 
 export type CanvasChangeType = 'pins' | 'nodes' | 'ax' | 'ax-timeline';
 
+/** Name for a board nobody named yet: when it was made, to the minute. */
+export function defaultBoardName(): string {
+  return `Board ${new Date().toISOString().slice(0, 16).replace('T', ' ')}`;
+}
+
 export interface MutationRecordInfo {
   operationType:
     | 'addNode'
@@ -339,6 +414,9 @@ class CanvasStateManager {
   private _theme: CanvasTheme = 'dark';
   private _contextPinnedNodeIds = new Set<string>();
   private _workspaceRoot = process.cwd();
+  private _contentRevision = 0;
+  private _revisionFloor = 0;
+  private _deletionTombstones: NodeDeletionTombstone[] = [];
 
   // ── AX state (canvas-bound + timeline + host partitions) ──────────
   // Extracted into a dedicated manager (plan-007 Slice A). CanvasStateManager
@@ -506,12 +584,58 @@ class CanvasStateManager {
   }
 
   private normalizeNode(node: CanvasNodeState): CanvasNodeState {
+    const data = { ...node.data };
+    delete data.createdBy;
+    delete data.lastEditedBy;
+    delete data.contentRevision;
     return {
       ...node,
-      data: normalizeCanvasNodeData(node.type, node.data),
+      data: normalizeCanvasNodeData(node.type, data),
+      createdBy: node.createdBy ?? unknownActor(),
+      lastEditedBy: node.lastEditedBy ?? unknownActor(),
+      contentRevision: Number.isSafeInteger(node.contentRevision) ? node.contentRevision : 0,
     };
   }
 
+  private nextContentRevision(): number {
+    this._contentRevision += 1;
+    return this._contentRevision;
+  }
+
+  private revisionState() {
+    return {
+      revision: this._contentRevision,
+      floor: this._revisionFloor,
+      tombstones: structuredClone(this._deletionTombstones),
+    };
+  }
+
+  /**
+   * Stable delta cursor contract: revisions strictly increase per active board;
+   * geometry-only writes do not advance them. `reset` means `since` predates
+   * retained tombstones, so callers must replace their view with `nodes`.
+   */
+  readContentDelta(since = this._contentRevision): BoardContentDelta {
+    const cursor = Math.max(0, Math.floor(since));
+    const reset = cursor < this._revisionFloor;
+    return {
+      since: cursor,
+      revision: this._contentRevision,
+      retentionFloor: this._revisionFloor,
+      reset,
+      nodes: Array.from(this.nodes.values())
+        .filter((node) => reset || (node.contentRevision ?? 0) > cursor)
+        .map((node) => structuredClone(this.nodeForRead(node))),
+      deleted: reset
+        ? []
+        : this._deletionTombstones.filter((item) => item.revision > cursor).map((item) => structuredClone(item)),
+    };
+  }
+
+  getContentRevision(): BoardContentRevision {
+    return { revision: this._contentRevision, retentionFloor: this._revisionFloor };
+  }
+
   private nodeForRead(node: CanvasNodeState): CanvasNodeState {
     const resolved = this.resolveNodeDataBlobs(node);
     return {
@@ -640,6 +764,7 @@ class CanvasStateManager {
 
   // ── Persistence ────────────────────────────────────────────
   private _db: import('bun:sqlite').Database | null = null;
+  private _dbPath: string | null = null;
   private _saveTimer: ReturnType<typeof setTimeout> | null = null;
 
   /** Workspace root backing persistence and workspace-relative path resolution. */
@@ -677,7 +802,8 @@ class CanvasStateManager {
     // 0.4.0 — the one-shot boot migration that copied them into SQLite and
     // renamed the originals to `.bak` was retired.
     try {
-      this._db = openCanvasDb(dbPath);
+      this._db = openCanvasDb(dbPath, { migratedBoardName: basename(workspaceRoot) || 'Board' });
+      this._dbPath = dbPath;
     } catch (error) {
       logCanvasStateWarning('open canvas database failed', error, { dbPath });
     }
@@ -789,7 +915,7 @@ class CanvasStateManager {
   }
 
   private externalizeNodeDataBlobs(node: CanvasNodeState): CanvasNodeState {
-    if (node.type !== 'mcp-app') return node;
+    if (node.type !== 'mcp-app' && node.type !== 'html') return node;
     let changed = false;
     const data = { ...node.data };
     for (const [key, value] of Object.entries(data)) {
@@ -803,7 +929,7 @@ class CanvasStateManager {
   }
 
   private resolveNodeDataBlobs(node: CanvasNodeState): CanvasNodeState {
-    if (node.type !== 'mcp-app') return node;
+    if (node.type !== 'mcp-app' && node.type !== 'html') return node;
     let changed = false;
     const data = { ...node.data };
     for (const [key, value] of Object.entries(data)) {
@@ -843,22 +969,27 @@ class CanvasStateManager {
       annotations: [],
       contextPins: [],
       ax: createEmptyAxState(),
+      revisionState: { revision: 0, floor: 0, tombstones: [] },
     };
   }
 
-  /** Load canvas state from SQLite. Call once on server startup. */
+  /**
+   * Load the board that was open last. Call once on server startup. With no
+   * such board the workspace starts on Home (no board open).
+   */
   loadFromDisk(options: LoadFromDiskOptions = {}): boolean {
     // Host capability lives in its own table (not snapshotted / not in PmxAxState).
     this.ax.loadHostCapabilityFromDb();
-    // Only a populated DB counts as saved state (legacy `state.json` loading was
-    // retired with the 0.4.0 boot-migration removal).
-    if (this._db && isDbPopulated(this._db)) {
+    if (this._db) {
       try {
-        const state = loadStateFromDB(this._db);
-        if (state) {
+        const boardId = getActiveBoardIdFromDB(this._db);
+        const state = boardId ? loadStateFromDB(this._db, boardId) : null;
+        if (boardId && state) {
           this.applyPersistedState(state);
+          this._activeBoardId = boardId;
           return true;
         }
+        this._theme = normalizeCanvasTheme(readThemeFromDB(this._db), this._theme);
       } catch (error) {
         logCanvasStateWarning('load state from sqlite failed', error, {});
       }
@@ -870,6 +1001,434 @@ class CanvasStateManager {
     return false;
   }
 
+  // ── Library file (backup / restore) ─────────────────────────
+
+  /** The SQLite file holding every board, or null without a workspace database. */
+  get databasePath(): string | null {
+    return this._db ? this._dbPath : null;
+  }
+
+  readWorkspaceMeta(key: string): string | null {
+    return this._db ? readMetaFromDB(this._db, key) : null;
+  }
+
+  writeWorkspaceMeta(key: string, value: string | null): void {
+    if (this._db) writeMetaToDB(this._db, key, value);
+  }
+
+  /** A consistent copy of the whole library, safe while the server runs. */
+  backupDatabaseTo(path: string): void {
+    if (!this._db) throw new Error('No workspace database to back up.');
+    this.flushToDisk();
+    this._db.run('VACUUM INTO ?', [path]);
+  }
+
+  /**
+   * Replace the library with `file`: the current file is kept beside it as
+   * `<db>.before-restore`, then the restored file opens (migrating an older
+   * layout) on the board it had open last.
+   */
+  replaceDatabase(file: string): void {
+    const dbPath = this.databasePath;
+    if (!dbPath) throw new Error('No workspace database to restore into.');
+    const root = this._workspaceRoot;
+    const recoveryPath = `${dbPath}.before-restore`;
+    const stagedPath = `${dbPath}.restore-${process.pid}-${Date.now()}`;
+    this.flushToDisk();
+    copyFileSync(file, stagedPath);
+    let closed = false;
+    let recoveryReady = false;
+    try {
+      this.close();
+      closed = true;
+      copyFileSync(dbPath, recoveryPath);
+      recoveryReady = true;
+      for (const suffix of ['-wal', '-shm']) rmSync(`${dbPath}${suffix}`, { force: true });
+      copyFileSync(stagedPath, dbPath);
+      this.setWorkspaceRoot(root);
+      if (!this._db) throw new Error('Could not open the restored database.');
+      const expectedBoard = getActiveBoardIdFromDB(this._db);
+      const loaded = this.loadFromDisk({ clearExisting: true });
+      if (expectedBoard && !loaded) throw new Error('Could not load the restored board.');
+    } catch (error) {
+      if (closed) {
+        this.close();
+        if (recoveryReady) {
+          for (const suffix of ['-wal', '-shm']) rmSync(`${dbPath}${suffix}`, { force: true });
+          copyFileSync(recoveryPath, dbPath);
+        }
+        this.setWorkspaceRoot(root);
+        this.loadFromDisk({ clearExisting: true });
+      }
+      throw error;
+    } finally {
+      rmSync(stagedPath, { force: true });
+    }
+    this.notifyChange('nodes');
+    this.notifyChange('pins');
+    this.notifyChange('ax');
+  }
+
+  // ── Boards ──────────────────────────────────────────────────
+
+  private _activeBoardId: string | null = null;
+  private _boardGeneration = 0;
+
+  /** Invalidates asynchronous work whenever the loaded board state is replaced. */
+  get boardGeneration(): number {
+    return this._boardGeneration;
+  }
+
+  /** The open board, or null on Home. */
+  get activeBoardId(): string | null {
+    return this._activeBoardId;
+  }
+
+  getActiveBoard(): CanvasBoard | null {
+    if (!this._db || !this._activeBoardId) return null;
+    const board = getBoardFromDB(this._db, this._activeBoardId);
+    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.
+   */
+  readBoard(
+    id: string,
+    includeBlobs = true,
+  ): { board: CanvasBoard; state: PersistedCanvasState; layout: CanvasLayout } | null {
+    if (!this._db) return null;
+    const board = this.listBoards().find((entry) => entry.id === id);
+    if (!board) return null;
+    if (id === this._activeBoardId) {
+      const layout = includeBlobs ? this.getLayout() : this.getLayoutForPersistence();
+      if (!includeBlobs)
+        layout.nodes = layout.nodes.map((node) => ({
+          ...node,
+          pinned: node.pinned || this._contextPinnedNodeIds.has(node.id),
+        }));
+      return {
+        board,
+        layout,
+        state: {
+          version: 1,
+          theme: this._theme,
+          tour: layout.tour,
+          ax: this.getAxState(),
+          viewport: layout.viewport,
+          nodes: layout.nodes,
+          edges: layout.edges,
+          annotations: layout.annotations,
+          contextPins: Array.from(this._contextPinnedNodeIds),
+          revisionState: this.revisionState(),
+        },
+      };
+    }
+    const state = loadStateFromDB(this._db, id);
+    if (!state) return null;
+    const pins = new Set(state.contextPins);
+    state.nodes = state.nodes.map((node) => ({
+      ...(includeBlobs ? this.resolveNodeDataBlobs(node) : node),
+      pinned: node.pinned || pins.has(node.id),
+    }));
+    return {
+      board,
+      state,
+      layout: {
+        tour: state.tour,
+        theme: state.theme ?? this._theme,
+        viewport: state.viewport,
+        nodes: state.nodes,
+        edges: state.edges,
+        annotations: state.annotations ?? [],
+      },
+    };
+  }
+
+  /** Every board in the workspace, most recently opened first. */
+  listBoards(): CanvasBoard[] {
+    if (!this._db) return [];
+    return listBoardsFromDB(this._db).map((board) =>
+      board.id === this._activeBoardId ? { ...board, nodeCount: this.nodes.size } : board,
+    );
+  }
+
+  storeAttachment(input: { boardId: string; name: string; mime: string; bytes: Uint8Array }): Attachment | null {
+    if (!this._db) return null;
+    if (input.boardId === this._activeBoardId) this.flushToDisk();
+    if (!getBoardFromDB(this._db, input.boardId)) return null;
+    return storeAttachment(this._db, input);
+  }
+  getAttachment(id: string): Attachment | null {
+    return this._db ? getAttachment(this._db, id) : null;
+  }
+  readAttachmentBytes(id: string): Uint8Array | null {
+    return this._db ? readAttachmentBytes(this._db, id) : null;
+  }
+  createDocumentImport(attachmentId: string, position: { x: number; y: number }): DocumentImport | null {
+    return this._db ? createImport(this._db, attachmentId, position) : null;
+  }
+  getDocumentImport(id: string): DocumentImport | null {
+    return this._db ? getImport(this._db, id) : null;
+  }
+  listDocumentImports(boardId?: string): DocumentImport[] {
+    return this._db ? listImports(this._db, boardId) : [];
+  }
+  updateDocumentImport(
+    id: string,
+    status: DocumentImportStatus,
+    fields?: {
+      sections?: ImportSection[];
+      warnings?: string[];
+      agentDescription?: string;
+      reason?: string;
+      committedNodeIds?: string[];
+    },
+  ): DocumentImport | null {
+    return this._db ? updateImport(this._db, id, status, fields) : null;
+  }
+  commitDocumentImport(id: string, nodeIds: string[]): DocumentImport | null {
+    if (!this._db) return null;
+    if (this._saveTimer) {
+      clearTimeout(this._saveTimer);
+      this._saveTimer = null;
+    }
+    return this._db.transaction(() => {
+      if (!this.saveToDisk()) throw new Error(this._lastPersistenceError?.message ?? 'Failed to save canvas state.');
+      return updateImport(this._db!, id, 'committed', { committedNodeIds: nodeIds });
+    })();
+  }
+
+  getContextBriefCursor(boardId: string, consumer: string): number | null {
+    return this._db ? readContextBriefCursor(this._db, boardId, consumer) : null;
+  }
+
+  advanceContextBriefCursor(boardId: string, consumer: string, revision: number): void {
+    // A durable cursor must never get ahead of the board content it describes.
+    if (boardId === this._activeBoardId) this.flushToDisk();
+    if (this._db) advanceContextBriefCursor(this._db, boardId, consumer, revision);
+  }
+
+  /** Creates a board without opening it. */
+  createBoard(name: string, category: string | null = null): CanvasBoard | null {
+    if (!this._db) return null;
+    return createBoardInDB(this._db, name, category);
+  }
+
+  updateBoard(id: string, patch: { name?: string; category?: string | null }): boolean {
+    return this._db ? updateBoardInDB(this._db, id, patch) : false;
+  }
+
+  setBoardReadme(id: string, nodeId: string | null): boolean {
+    if (!this._db) return false;
+    const read = this.readBoard(id, false);
+    if (!read) return false;
+    if (nodeId && !read.layout.nodes.some((node) => node.id === nodeId && node.type === 'markdown')) return false;
+    return updateBoardInDB(this._db, id, { readmeNodeId: nodeId });
+  }
+
+  /** Bounded inactive-board creation; never replaces the state the human has open. */
+  createBoardFromBoard(input: {
+    sourceBoardId: string;
+    name: string;
+    category?: string | null;
+    nodeIds?: string[];
+    includeReadme?: boolean;
+    includeStructure?: boolean;
+  }): CanvasBoard | null {
+    if (!this._db) return null;
+    const source = this.readBoard(input.sourceBoardId, true);
+    if (!source) return null;
+    const selected = new Set(input.nodeIds ?? []);
+    if (input.includeReadme && source.board.readmeNodeId) selected.add(source.board.readmeNodeId);
+    if (input.includeStructure) {
+      for (const node of source.layout.nodes) {
+        if (node.type === 'group') selected.add(node.id);
+      }
+    }
+    const copied = source.layout.nodes.filter(
+      (node) => selected.has(node.id) && !['prompt', 'response', 'trace', 'mcp-app'].includes(node.type),
+    );
+    const ids = new Map(copied.map((node) => [node.id, randomUUID()]));
+    const referenceKeys = new Set([
+      'nodeId',
+      'nodeIds',
+      'sourceNodeId',
+      'targetNodeId',
+      'embeddedNodeId',
+      'embeddedNodeIds',
+      'embeddedGraphId',
+    ]);
+    const remap = (value: unknown, key = ''): unknown => {
+      if (typeof value === 'string') return referenceKeys.has(key) ? (ids.get(value) ?? null) : value;
+      if (Array.isArray(value)) return value.map((item) => remap(item, key)).filter((item) => item !== null);
+      if (value && typeof value === 'object') {
+        return Object.fromEntries(
+          Object.entries(value as Record<string, unknown>).map(([key, item]) => [key, remap(item, key)]),
+        );
+      }
+      return value;
+    };
+    const actor = currentActor();
+    const nodes: CanvasNodeState[] = copied.map((node, index) => {
+      const data = remap(node.data) as Record<string, unknown>;
+      if (node.type === 'graph' || node.type === 'json-render') {
+        data.url = `/api/canvas/json-render/view?nodeId=${encodeURIComponent(ids.get(node.id)!)}`;
+      }
+      delete data.axStep;
+      delete data.axWorkStatus;
+      delete data.workItemId;
+      delete data.approvalGateId;
+      delete data.parentGroup;
+      if (typeof node.data.parentGroup === 'string' && ids.has(node.data.parentGroup)) {
+        data.parentGroup = ids.get(node.data.parentGroup);
+      }
+      if (node.type === 'group')
+        data.children = Array.isArray(node.data.children)
+          ? node.data.children.flatMap((id) => (typeof id === 'string' && ids.has(id) ? [ids.get(id)!] : []))
+          : [];
+      return {
+        ...node,
+        id: ids.get(node.id)!,
+        pinned: false,
+        data,
+        createdBy: actor,
+        lastEditedBy: actor,
+        contentRevision: index + 1,
+      };
+    });
+    nodes.push({
+      id: randomUUID(),
+      type: 'board' as const,
+      position: { x: 40, y: Math.max(40, ...nodes.map((node) => node.position.y + node.size.height + 40)) },
+      size: { width: 360, height: 160 },
+      zIndex: 1,
+      collapsed: false,
+      pinned: false,
+      data: { title: source.board.name, boardId: source.board.id },
+      createdBy: actor,
+      lastEditedBy: actor,
+      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)! }));
+    const state: PersistedCanvasState = {
+      version: 1,
+      theme: source.state.theme,
+      viewport: { x: 0, y: 0, scale: 1 },
+      nodes,
+      edges,
+      annotations: [],
+      contextPins: [],
+      ax: createEmptyAxState(),
+      revisionState: { revision: nodes.length, floor: 0, tombstones: [] },
+    };
+    const board = createBoardWithStateInDB(
+      this._db,
+      input.name,
+      input.category ?? null,
+      this.externalizePersistedStateBlobs(state),
+      input.includeReadme && source.board.readmeNodeId ? (ids.get(source.board.readmeNodeId) ?? null) : null,
+    );
+    const referencedAttachmentIds = new Set<string>();
+    for (const node of nodes) {
+      if (typeof node.data.attachmentId === 'string') referencedAttachmentIds.add(node.data.attachmentId);
+      const provenance = node.data.source;
+      if (provenance && typeof provenance === 'object') {
+        const sourceAttachmentId = (provenance as Record<string, unknown>).attachmentId;
+        if (typeof sourceAttachmentId === 'string') referencedAttachmentIds.add(sourceAttachmentId);
+      }
+      delete node.data.importId;
+    }
+    const attachmentIds = copyBoardAttachments(this._db, source.board.id, board.id, referencedAttachmentIds);
+    if (attachmentIds.size > 0) {
+      const createdImportAttachments = new Set<string>();
+      for (const row of this._db
+        .query<{ id: string; data: string }, [string]>('SELECT id,data FROM nodes WHERE board_id=?')
+        .all(board.id)) {
+        const data = JSON.parse(row.data) as Record<string, unknown>;
+        const old = typeof data.attachmentId === 'string' ? data.attachmentId : null;
+        const sourceData =
+          data.source && typeof data.source === 'object' ? (data.source as Record<string, unknown>) : null;
+        const sourceOld = typeof sourceData?.attachmentId === 'string' ? sourceData.attachmentId : null;
+        if (old && attachmentIds.has(old)) data.attachmentId = attachmentIds.get(old);
+        if (sourceOld && attachmentIds.has(sourceOld))
+          data.source = { ...sourceData, attachmentId: attachmentIds.get(sourceOld) };
+        delete data.importId;
+        this._db.run('UPDATE nodes SET data=? WHERE board_id=? AND id=?', [JSON.stringify(data), board.id, row.id]);
+        if (old && attachmentIds.has(old) && !createdImportAttachments.has(old)) {
+          createImport(this._db, attachmentIds.get(old)!, { x: 40, y: 260 });
+          createdImportAttachments.add(old);
+        }
+      }
+    }
+    return board;
+  }
+
+  /** Deletes a board and its snapshots; deleting the open board returns to Home first. */
+  deleteBoard(id: string): boolean {
+    if (!this._db) return false;
+    if (id === this._activeBoardId && !this.switchBoard(null)) return false;
+    return deleteBoardFromDB(this._db, id);
+  }
+
+  /**
+   * Save the open board, then open `id` (or Home for null). The canvas state is
+   * replaced wholesale; callers own the runtime side (undo history, app
+   * sessions, watchers, SSE) — see `openCanvasBoard` in canvas-operations.
+   */
+  switchBoard(id: string | null): boolean {
+    if (!this._db) return false;
+    if (this._saveTimer) {
+      clearTimeout(this._saveTimer);
+      this._saveTimer = null;
+    }
+    if (!this.saveToDisk()) {
+      throw new Error(this._lastPersistenceError?.message ?? 'Failed to save canvas state before switching boards.');
+    }
+    let next = this.emptyPersistedState();
+    if (id) {
+      const state = loadStateFromDB(this._db, id);
+      if (!state) return false;
+      next = state;
+    }
+    this.applyPersistedState(next);
+    this._activeBoardId = id;
+    setActiveBoardIdInDB(this._db, id);
+    this.notifyChange('nodes');
+    this.notifyChange('pins');
+    this.notifyChange('ax');
+    return true;
+  }
+
+  /**
+   * Content written while no board is open (Home) lands on a new board, which
+   * opens: nothing the human was looking at is displaced.
+   */
+  private ensureActiveBoard(): string | null {
+    if (!this._db) return null;
+    if (this._activeBoardId) return this._activeBoardId;
+    const board = createBoardInDB(this._db, defaultBoardName());
+    this._activeBoardId = board.id;
+    setActiveBoardIdInDB(this._db, board.id);
+    return board.id;
+  }
+
+  private hasBoardContent(): boolean {
+    const ax = this.getAxState();
+    return (
+      this._tour !== undefined ||
+      this.nodes.size > 0 ||
+      this.edges.size > 0 ||
+      this.annotations.size > 0 ||
+      ax.workItems.length > 0 ||
+      ax.approvalGates.length > 0 ||
+      ax.reviewAnnotations.length > 0
+    );
+  }
+
   /** Debounced save — coalesces rapid mutations into a single write. */
   private scheduleSave(): void {
     if (!this._db) return;
@@ -881,24 +1440,35 @@ class CanvasStateManager {
   }
 
   flushToDisk(): void {
+    if (!this._db) return;
     if (this._saveTimer) {
       clearTimeout(this._saveTimer);
       this._saveTimer = null;
     }
-    this.saveToDisk();
+    if (!this.saveToDisk()) {
+      throw new Error(this._lastPersistenceError?.message ?? 'Failed to save canvas state.');
+    }
     if (this._db) {
       try {
         checkpointCanvasDb(this._db);
       } catch (error) {
         logCanvasStateWarning('checkpoint database failed', error, {});
+        throw error;
       }
     }
   }
 
   /** Write current state to SQLite immediately. */
-  private saveToDisk(): void {
-    if (!this._db) return;
+  private saveToDisk(): boolean {
+    if (!this._db) return false;
     try {
+      if (!this._activeBoardId && !this.hasBoardContent()) {
+        saveThemeToDB(this._db, this._theme);
+        this._lastPersistenceError = null;
+        return true;
+      }
+      const boardId = this.ensureActiveBoard();
+      if (!boardId) return false;
       const payload = this.externalizePersistedStateBlobs({
         version: 1,
         theme: this._theme,
@@ -909,9 +1479,11 @@ class CanvasStateManager {
         annotations: Array.from(this.annotations.values()),
         contextPins: Array.from(this._contextPinnedNodeIds),
         ax: this.getAxState(),
+        revisionState: this.revisionState(),
       });
-      saveStateToDB(this._db, payload);
+      saveStateToDB(this._db, boardId, payload);
       this._lastPersistenceError = null;
+      return true;
     } catch (error) {
       // Persistence failures are otherwise warn-and-continue (the canvas keeps
       // working from memory) — record the failure so /health can report a
@@ -921,6 +1493,7 @@ class CanvasStateManager {
         at: new Date().toISOString(),
       };
       logCanvasStateWarning('save state to sqlite failed', error, {});
+      return false;
     }
   }
 
@@ -933,11 +1506,9 @@ class CanvasStateManager {
 
   /** Close the SQLite database cleanly. Call on server shutdown. */
   close(): void {
-    if (this._saveTimer) {
-      clearTimeout(this._saveTimer);
-      this._saveTimer = null;
-      this.saveToDisk();
-    }
+    // A failed debounce has no timer left, but its edits still need saving.
+    // Leave the database and memory intact if the retry fails.
+    if (this._saveTimer || this._lastPersistenceError) this.flushToDisk();
     if (this._db) {
       try {
         finalizeCanvasDbForClose(this._db);
@@ -951,6 +1522,8 @@ class CanvasStateManager {
       }
       this._db = null;
     }
+    this._activeBoardId = null;
+    this._boardGeneration += 1;
   }
 
   // ── Snapshots ───────────────────────────────────────────────
@@ -961,12 +1534,16 @@ class CanvasStateManager {
   }
 
   private applyPersistedState(state: PersistedCanvasState): void {
+    this._boardGeneration += 1;
     this._tour = state.tour ? structuredClone(state.tour) : undefined;
     this.nodes.clear();
     this.edges.clear();
     this.annotations.clear();
     this._contextPinnedNodeIds.clear();
     this.ax.resetCanvasBound();
+    this._contentRevision = state.revisionState?.revision ?? 0;
+    this._revisionFloor = state.revisionState?.floor ?? 0;
+    this._deletionTombstones = structuredClone(state.revisionState?.tombstones ?? []);
 
     this._viewport = {
       x: state.viewport?.x ?? 0,
@@ -1004,10 +1581,16 @@ class CanvasStateManager {
     snapshot: CanvasSnapshot;
     state: PersistedCanvasState;
   } | null {
+    if (!this._activeBoardId) return null;
+
     // Try SQLite first
     if (this._db) {
-      const result = loadSnapshotFromDB(this._db, idOrName);
+      const result = loadSnapshotFromDB(this._db, idOrName, this._activeBoardId);
       if (result) return result;
+      const ownedByAnotherBoard = this._db
+        .query<{ found: number }, [string, string]>('SELECT 1 AS found FROM snapshots WHERE id = ? OR name = ? LIMIT 1')
+        .get(idOrName, idOrName);
+      if (ownedByAnotherBoard) return null;
     }
 
     // Fallback to filesystem (legacy on-disk snapshots are still readable in place)
@@ -1095,8 +1678,11 @@ class CanvasStateManager {
         annotations: Array.from(this.annotations.values()),
         contextPins: Array.from(this._contextPinnedNodeIds),
         ax: this.getAxState(),
+        revisionState: this.revisionState(),
       });
-      saveSnapshotToDB(this._db, snapshot, { ...payload, tour: this._tour });
+      const boardId = this.ensureActiveBoard();
+      if (!boardId) return null;
+      saveSnapshotToDB(this._db, boardId, snapshot, { ...payload, tour: this._tour });
       snapshot.nodeCount = payload.nodes.length;
       snapshot.edgeCount = payload.edges.length;
       return snapshot;
@@ -1110,7 +1696,7 @@ class CanvasStateManager {
   listSnapshots(options: CanvasSnapshotListOptions = {}): CanvasSnapshot[] {
     if (this._db) {
       try {
-        return listSnapshotsFromDB(this._db, options);
+        return this._activeBoardId ? listSnapshotsFromDB(this._db, this._activeBoardId, options) : [];
       } catch (error) {
         logCanvasStateWarning('list snapshots from db failed', error, {});
       }
@@ -1189,6 +1775,7 @@ class CanvasStateManager {
       annotations: Array.from(this.annotations.values(), (annotation) => structuredClone(annotation)),
       contextPins: Array.from(this._contextPinnedNodeIds),
       ax: this.getAxState(),
+      revisionState: this.revisionState(),
     });
     const nextState: PersistedCanvasState = {
       version: 1,
@@ -1202,10 +1789,13 @@ class CanvasStateManager {
         : [],
       contextPins: Array.isArray(resolved.state.contextPins) ? [...resolved.state.contextPins] : [],
       ax: resolved.state.ax ? structuredClone(resolved.state.ax) : createEmptyAxState(),
+      revisionState: resolved.state.revisionState ? structuredClone(resolved.state.revisionState) : undefined,
     };
 
     try {
-      this.applyPersistedState(nextState);
+      const revisionBeforeRestore = this._contentRevision;
+      this.applyPersistedState({ ...nextState, revisionState: this.revisionState() });
+      this.restampRestoredContent(previousState.nodes, revisionBeforeRestore);
       this.scheduleSave();
       this.notifyChange('nodes');
       this.notifyChange('pins');
@@ -1214,14 +1804,20 @@ class CanvasStateManager {
         operationType: 'restoreSnapshot',
         description: `Restored snapshot "${resolved.snapshot.name}"`,
         forward: this.suppressed(() => {
-          this.applyPersistedState(nextState);
+          const before = Array.from(this.nodes.values(), (node) => structuredClone(node));
+          const revisionBeforeReplay = this._contentRevision;
+          this.applyPersistedState({ ...nextState, revisionState: this.revisionState() });
+          this.restampRestoredContent(before, revisionBeforeReplay);
           this.scheduleSave();
           this.notifyChange('nodes');
           this.notifyChange('pins');
           this.notifyChange('ax');
         }),
         inverse: this.suppressed(() => {
-          this.applyPersistedState(previousState);
+          const before = Array.from(this.nodes.values(), (node) => structuredClone(node));
+          const revisionBeforeReplay = this._contentRevision;
+          this.applyPersistedState({ ...previousState, revisionState: this.revisionState() });
+          this.restampRestoredContent(before, revisionBeforeReplay);
           this.scheduleSave();
           this.notifyChange('nodes');
           this.notifyChange('pins');
@@ -1268,9 +1864,9 @@ class CanvasStateManager {
 
   /** Delete a snapshot. */
   renameSnapshot(id: string, name: string): boolean {
-    if (!this._db) return false;
+    if (!this._db || !this._activeBoardId) return false;
     try {
-      return renameSnapshotInDB(this._db, id, name);
+      return renameSnapshotInDB(this._db, this._activeBoardId, id, name);
     } catch (error) {
       logCanvasStateWarning('rename snapshot failed', error, { id, name });
       return false;
@@ -1278,12 +1874,20 @@ class CanvasStateManager {
   }
 
   deleteSnapshot(id: string): boolean {
+    if (!this._activeBoardId) return false;
     // Try SQLite first
     if (this._db) {
       try {
-        if (deleteSnapshotFromDB(this._db, id)) return true;
+        const snapshot = this._db
+          .query<{ board_id: string }, [string]>('SELECT board_id FROM snapshots WHERE id = ?')
+          .get(id);
+        if (snapshot) {
+          if (snapshot.board_id !== this._activeBoardId) return false;
+          return deleteSnapshotFromDB(this._db, id);
+        }
       } catch (error) {
         logCanvasStateWarning('delete snapshot from db failed', error, { id });
+        return false;
       }
     }
 
@@ -1320,12 +1924,77 @@ class CanvasStateManager {
 
   // ── Node CRUD ──────────────────────────────────────────────
 
+  private restampRestoredContent(beforeNodes: CanvasNodeState[], 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);
+      if (old && !this.nodeContentChanged(old, node)) {
+        this.nodes.set(id, { ...node, contentRevision: old.contentRevision, lastEditedBy: old.lastEditedBy });
+        continue;
+      }
+      const revision = this.nextContentRevision();
+      this.nodes.set(id, { ...node, lastEditedBy: currentActor(), contentRevision: revision });
+    }
+    for (const old of beforeNodes) {
+      if (!restoredIds.has(old.id)) this.recordDeletion(old.id);
+    }
+  }
+
+  private semanticData(data: Record<string, unknown>): Record<string, unknown> {
+    const copy = { ...data };
+    delete copy.strictSize;
+    delete copy.arrangeLocked;
+    return copy;
+  }
+
+  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);
+    if (!existing || !this.nodeContentChanged(existing, node)) {
+      this.nodes.set(node.id, node);
+      return;
+    }
+    const data = { ...node.data };
+    if (data.agentSummary === existing.data.agentSummary) delete data.agentSummary;
+    if (data.summary === existing.data.summary) delete data.summary;
+    this.nodes.set(node.id, {
+      ...node,
+      data,
+      createdBy: existing.createdBy,
+      lastEditedBy: currentActor(),
+      contentRevision: this.nextContentRevision(),
+    });
+  }
+
+  private recordDeletion(nodeId: string): void {
+    const tombstone = { nodeId, revision: this.nextContentRevision(), deletedBy: currentActor() };
+    this._deletionTombstones.push(tombstone);
+    const limit = 500;
+    if (this._deletionTombstones.length > limit) {
+      const removed = this._deletionTombstones.splice(0, this._deletionTombstones.length - limit);
+      this._revisionFloor = Math.max(this._revisionFloor, removed.at(-1)?.revision ?? 0);
+    }
+  }
+
   get viewport(): ViewportState {
     return structuredClone(this._viewport);
   }
 
   addNode(node: CanvasNodeState): void {
-    const cloned = structuredClone(this.normalizeNode(node));
+    const actor = currentActor();
+    const cloned = structuredClone(
+      this.normalizeNode({
+        ...node,
+        createdBy: actor,
+        lastEditedBy: actor,
+        contentRevision: this.nextContentRevision(),
+      }),
+    );
     this.nodes.set(node.id, cloned);
     this.scheduleSave();
     this.notifyChange('nodes');
@@ -1348,11 +2017,43 @@ class CanvasStateManager {
   updateNode(id: string, patch: Partial<CanvasNodeState>): void {
     const existing = this.nodes.get(id);
     if (!existing) return;
+    if (patch.data) {
+      const attachmentId = existing.data.attachmentId;
+      if (typeof attachmentId === 'string' && patch.data.attachmentId !== attachmentId) {
+        throw new Error('Attachment identity is immutable.');
+      }
+      const source = existing.data.source;
+      const importedSource =
+        source && typeof source === 'object' && typeof (source as Record<string, unknown>).attachmentId === 'string';
+      if (importedSource && JSON.stringify(patch.data.source) !== JSON.stringify(source)) {
+        throw new Error('Import provenance is immutable.');
+      }
+    }
     const oldSnapshot = structuredClone(existing);
     if (existing.type === 'group' && patch.position) {
       this.translateGroupChildren(id, patch.position.x - existing.position.x, patch.position.y - existing.position.y);
     }
-    const nextNode = this.normalizeNode({ ...existing, ...patch });
+    let nextNode = this.normalizeNode({ ...existing, ...patch });
+    if (this.nodeContentChanged(existing, nextNode)) {
+      const data = { ...nextNode.data };
+      const suppliedData = patch.data;
+      if (!suppliedData || suppliedData.agentSummary === existing.data.agentSummary) delete data.agentSummary;
+      if (!suppliedData || suppliedData.summary === existing.data.summary) delete data.summary;
+      nextNode = {
+        ...nextNode,
+        data,
+        createdBy: existing.createdBy ?? unknownActor(),
+        lastEditedBy: currentActor(),
+        contentRevision: this.nextContentRevision(),
+      };
+    } else {
+      nextNode = {
+        ...nextNode,
+        createdBy: existing.createdBy,
+        lastEditedBy: existing.lastEditedBy,
+        contentRevision: existing.contentRevision,
+      };
+    }
     this.nodes.set(id, nextNode);
     const parentGroupId = existing.data.parentGroup as string | undefined;
     if (parentGroupId) {
@@ -1370,7 +2071,16 @@ class CanvasStateManager {
       description: `Updated node "${(existing.data.title as string) ?? id}"`,
       forward: this.suppressed(() => this.updateNode(id, structuredClone(patch))),
       inverse: this.suppressed(() => {
-        this.nodes.set(id, structuredClone(oldSnapshot));
+        const restored = structuredClone(oldSnapshot);
+        const current = this.nodes.get(id);
+        if (current && this.nodeContentChanged(current, restored)) {
+          restored.contentRevision = this.nextContentRevision();
+          restored.lastEditedBy = currentActor();
+        } else if (current) {
+          restored.contentRevision = current.contentRevision;
+          restored.lastEditedBy = current.lastEditedBy;
+        }
+        this.nodes.set(id, restored);
         this.scheduleSave();
         this.notifyChange('nodes');
       }),
@@ -1391,6 +2101,7 @@ class CanvasStateManager {
     let released: string[] = [];
 
     if (existing) {
+      this.recordDeletion(id);
       const parentGroupId = existing.data.parentGroup as string | undefined;
       const parent = parentGroupId ? this.nodes.get(parentGroupId) : undefined;
       const enclosing = parent && parent.type === 'group' ? parent : null;
@@ -1403,13 +2114,13 @@ class CanvasStateManager {
           const d = { ...child.data };
           if (enclosing) d.parentGroup = enclosing.id;
           else delete d.parentGroup;
-          this.nodes.set(cid, { ...child, data: d });
+          this.setSemanticNode({ ...child, data: d });
         }
       }
       if (enclosing && enclosingBefore) {
         // The removed node leaves the enclosing group; a dissolved group's children take its place.
         const children = enclosingBefore.children.flatMap((cid) => (cid === id ? released : [cid]));
-        this.nodes.set(enclosing.id, { ...enclosing, data: { ...enclosing.data, children } });
+        this.setSemanticNode({ ...enclosing, data: { ...enclosing.data, children } });
       }
     }
 
@@ -1463,15 +2174,17 @@ class CanvasStateManager {
         forward: this.suppressed(() => this.removeNode(id)),
         inverse: this.suppressed(() => {
           this.addNode(structuredClone(cloned));
+          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.
           for (const cid of released) {
             const child = this.nodes.get(cid);
-            if (child) this.nodes.set(cid, { ...child, data: { ...child.data, parentGroup: id } });
+            if (child) this.setSemanticNode({ ...child, data: { ...child.data, parentGroup: id } });
           }
           if (enclosingBefore) {
             const enclosing = this.nodes.get(enclosingBefore.id);
             if (enclosing) {
-              this.nodes.set(enclosing.id, {
+              this.setSemanticNode({
                 ...enclosing,
                 data: { ...enclosing.data, children: enclosingBefore.children },
               });
@@ -2132,6 +2845,21 @@ class CanvasStateManager {
     return this.ax.getAxTimelineSummary();
   }
 
+  /** Records one agent context read (diagnostics; never notifies, so a read cannot trigger reads). */
+  recordContextRead(input: ContextReadInput, boardId: string | null = this._activeBoardId): ContextRead | null {
+    if (!this._db) return null;
+    try {
+      return appendContextReadToDB(this._db, input, boardId);
+    } catch (error) {
+      logCanvasStateWarning('record context read failed', error);
+      return null;
+    }
+  }
+
+  getContextReads(limit?: number): { reads: ContextRead[]; summary: ContextReadConsumerSummary[] } {
+    return this._db ? loadContextReadsFromDB(this._db, limit) : { reads: [], summary: [] };
+  }
+
   getAxTimeline(q: AxTimelineQuery = {}): {
     events: PmxAxEvent[];
     evidence: PmxAxEvidence[];
@@ -2188,10 +2916,10 @@ class CanvasStateManager {
     }
 
     // Apply
-    this.nodes.set(groupId, { ...group, data: { ...group.data, children: merged } });
+    this.setSemanticNode({ ...group, data: { ...group.data, children: merged } });
     for (const id of validIds) {
       const child = this.nodes.get(id)!;
-      this.nodes.set(id, { ...child, data: { ...child.data, parentGroup: groupId } });
+      this.setSemanticNode({ ...child, data: { ...child.data, parentGroup: groupId } });
     }
     if (options.preservePositions === true) {
       if (options.keepGroupFrame !== true && group.data.frameMode !== 'manual') {
@@ -2214,14 +2942,14 @@ class CanvasStateManager {
       forward: this.suppressed(() => this.groupNodes(groupId, validIds, options)),
       inverse: this.suppressed(() => {
         const g = this.nodes.get(groupId);
-        if (g) this.nodes.set(groupId, { ...g, data: { ...g.data, children: oldChildren } });
+        if (g) this.setSemanticNode({ ...g, data: { ...g.data, children: oldChildren } });
         for (const [id, oldParent] of oldParents) {
           const c = this.nodes.get(id);
           if (!c) continue;
           const d = { ...c.data };
           if (oldParent) d.parentGroup = oldParent;
           else delete d.parentGroup;
-          this.nodes.set(id, { ...c, data: d });
+          this.setSemanticNode({ ...c, data: d });
         }
         this.scheduleSave();
         this.notifyChange('nodes');
@@ -2257,13 +2985,13 @@ class CanvasStateManager {
 
     const snapshot = childIds.slice();
 
-    this.nodes.set(groupId, { ...group, data: { ...group.data, children: [] } });
+    this.setSemanticNode({ ...group, data: { ...group.data, children: [] } });
     for (const id of childIds) {
       const child = this.nodes.get(id);
       if (!child) continue;
       const d = { ...child.data };
       delete d.parentGroup;
-      this.nodes.set(id, { ...child, data: d });
+      this.setSemanticNode({ ...child, data: d });
     }
 
     this.scheduleSave();
@@ -2286,6 +3014,7 @@ 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);
     this.nodes.clear();
     this.edges.clear();
     this.annotations.clear();