pmx-canvas 0.8.2 → 0.9.1

package/src/server/operations/ops/query.ts

@@ -2,33 +2,39 @@
  * Slice 3 operations (plan-005, migration item 4): pin.set / search /
  * history.get / canvas.undo / canvas.redo / spatial.get / summary.get.
  *
- * Event notes (matching the legacy HTTP handlers exactly):
+ * Event notes:
  * - pin.set: legacy POST /api/canvas/context-pins emitted ONLY
  *   context-pins-changed (no canvas-layout-update), so mutates: false with a
  *   manual ctx.emit. The injected emitter adds the sessionId/timestamp fields
  *   the legacy handler set explicitly. (The SDK's setContextPins emits the
  *   same context-pins-changed event — its old layout-update drift was erased
  *   in v0.3.0.)
- * - canvas.undo / canvas.redo: legacy handlers emitted canvas-viewport-update
- *   then canvas-layout-update only after an entry was actually undone/redone,
- *   so mutates: false with conditional manual emits. (The SDK's undo/redo also
- *   emit ax-state-changed; that was never part of the HTTP wire and the SDK
- *   methods are untouched.)
+ * - canvas.undo / canvas.redo: successful replay emits viewport, layout and raw
+ *   pin membership, since layout updates do not replace browser pins. Empty
+ *   history emits nothing, so mutates: false with conditional manual emits.
+ *   The SDK also emits ax-state-changed.
  *
  * This module must never import server.ts or index.ts.
  */
 import { z } from 'zod';
-import { canvasState } from '../../canvas-state.js';
+import { canvasState, type CanvasNodeState } from '../../canvas-state.js';
 import { setCanvasContextPins, syncCanvasRuntimeBackends } from '../../canvas-operations.js';
 import { buildCanvasSummary } from '../../canvas-serialization.js';
 import { mutationHistory } from '../../mutation-history.js';
-import { buildSpatialContext, searchNodes } from '../../spatial-analysis.js';
+import { buildSpatialContext, searchNodes, searchRelevance } from '../../spatial-analysis.js';
+import { boardConnections, memoryGraph } from '../../memory-graph.js';
+import { relationText } from '../../../shared/relations.js';
+import { normalizeBoardFolder } from '../../../shared/boards.js';
+import { lifecycleQualifications } from '../../lifecycle-status.js';
 import {
   compileContextBrief,
+  BRIEF_SUMMARY_LENGTH,
   type ContextBriefLibraryBoard,
+  type ContextBriefPinnedBoard,
   type ContextBriefSourceEntry,
 } from '../../context-brief.js';
 import { summarizeNodeForAgentContext } from '../../../shared/agent-context.js';
+import { memoryKey, type MemoryTarget } from '../../../shared/memory-graph.js';
 import { defineOperation, OperationError, type Operation, type OperationMcpToolHost } from '../types.js';
 import { buildSummaryFromLayout, isRecord } from './nodes.js';
 import { readTargetBoard } from './boards.js';
@@ -37,6 +43,11 @@ import { readTargetBoard } from './boards.js';
 
 /** Legacy server.ts handleContextPinsUpdate capped the requested list at 20. */
 const MAX_PINS = 20;
+
+/**
+ * The brief's page size in UTF-16 characters (canvas://context?budget=N). It is
+ * not shown to the human: a brief longer than one page continues on the next read.
+ */
 export const DEFAULT_CONTEXT_BRIEF_BUDGET = 16_000;
 export const MAX_CONTEXT_BRIEF_BUDGET = 100_000;
 
@@ -108,6 +119,8 @@ const pinOperation = defineOperation<z.infer<typeof pinSchema>, Record<string, u
 const searchShape = {
   q: z.unknown().optional().describe('Search query — matches against node titles, content, and file paths'),
   scope: z.unknown().optional().describe('active (default) or library (all boards)'),
+  boardId: z.string().optional().describe('Stable board ID to search; defaults scope to library when supplied'),
+  folder: z.string().optional().describe('Folder and descendants; empty string selects unfiled boards'),
   limit: z.unknown().optional().describe('Max results to return (default: all over HTTP, 10 via the MCP tool).'),
 };
 
@@ -130,13 +143,17 @@ const searchOperation = defineOperation<z.infer<typeof searchSchema>, Record<str
       query: z.string().describe('Search query — matches against node titles, content, and file paths'),
       limit: z.number().optional().describe('Max results to return (default: 10)'),
       scope: z.enum(['active', 'library']).optional().describe('Search the active board or the full board library'),
+      boardId: searchShape.boardId,
+      folder: searchShape.folder,
     },
     // Map the MCP-facing `query` arg onto the wire's `q`. The handler caps by
     // `limit` on every transport; the MCP tool additionally defaults it to 10.
     buildInput: (input) => ({
       q: typeof input.query === 'string' ? input.query : '',
       ...(typeof input.limit === 'number' ? { limit: input.limit } : {}),
-      ...(input.scope === 'library' ? { scope: 'library' } : {}),
+      ...(input.scope === 'library' || input.scope === 'active' ? { scope: input.scope } : {}),
+      ...(typeof input.boardId === 'string' ? { boardId: input.boardId } : {}),
+      ...(typeof input.folder === 'string' ? { folder: input.folder } : {}),
     }),
     formatResult: (result, input) => {
       const body = isRecord(result) ? result : {};
@@ -160,58 +177,106 @@ const searchOperation = defineOperation<z.infer<typeof searchSchema>, Record<str
       };
     },
   },
-  handler: (input) => {
-    const q = typeof input.q === 'string' ? input.q : '';
-    if (!q.trim()) {
-      return { results: [], query: q };
-    }
-    const rawLimit = input.limit;
-    const limit =
-      typeof rawLimit === 'number'
-        ? rawLimit
-        : typeof rawLimit === 'string' && rawLimit.trim() !== ''
-          ? Number(rawLimit)
-          : Number.NaN;
-    const library = input.scope === 'library';
-    const results = library
-      ? canvasState.listBoards().flatMap((board) => {
-          const read = canvasState.readBoard(board.id, true);
-          if (!read) return [];
-          const cards = searchNodes(read.layout.nodes, q).map((result) => ({
-            ...result,
-            boardId: board.id,
-            boardTitle: board.name,
-            cardId: result.id,
-          }));
-          const metadata = `${board.name} ${board.category ?? ''}`.toLocaleLowerCase();
-          const readme = read.layout.nodes.find((node) => node.id === board.readmeNodeId);
-          const readmeText = typeof readme?.data.content === 'string' ? readme.data.content : '';
-          if (`${metadata} ${readmeText.toLocaleLowerCase()}`.includes(q.toLocaleLowerCase())) {
-            cards.unshift({
-              id: board.id,
-              type: 'board',
-              title: board.name,
-              snippet: readmeText.slice(0, 160) || board.category || board.name,
-              score: metadata.includes(q.toLocaleLowerCase()) ? 4 : 2,
-              boardId: board.id,
-              boardTitle: board.name,
-              cardId: readme?.id ?? board.id,
-            });
-          }
-          return cards;
-        })
-      : searchNodes(canvasState.getLayout().nodes, q).map((result) => ({
+  handler: (input) =>
+    searchCanvasNodes(typeof input.q === 'string' ? input.q : '', {
+      scope: input.scope === 'active' || input.scope === 'library' ? input.scope : undefined,
+      boardId: input.boardId,
+      folder: input.folder,
+      limit: typeof input.limit === 'number' || typeof input.limit === 'string' ? input.limit : undefined,
+    }),
+});
+
+/** Search without opening boards; HTTP, MCP and SDK share discovery and ranking. */
+export function searchCanvasNodes(
+  q: string,
+  options: { scope?: 'active' | 'library'; boardId?: string; folder?: string; limit?: number | string } = {},
+) {
+  if (!q.trim()) {
+    return { results: [], query: q };
+  }
+  const rawLimit = options.limit;
+  const limit =
+    typeof rawLimit === 'number'
+      ? rawLimit
+      : typeof rawLimit === 'string' && rawLimit.trim() !== ''
+        ? Number(rawLimit)
+        : Number.NaN;
+  const hasFilter = options.boardId !== undefined || options.folder !== undefined;
+  const library = options.scope === 'library' || (options.scope === undefined && hasFilter);
+  const folder = options.folder === undefined ? undefined : normalizeBoardFolder(options.folder);
+  const selectedBoards = canvasState
+    .listBoards()
+    .filter(
+      (board) =>
+        (options.boardId === undefined || board.id === options.boardId) &&
+        (folder === undefined ||
+          board.folder === folder ||
+          (folder !== null && board.folder?.startsWith(`${folder}/`))),
+    );
+  const results = library
+    ? selectedBoards.flatMap((board) => {
+        const read = canvasState.readBoard(board.id, true);
+        if (!read) return [];
+        const cards = searchNodes(read.layout.nodes, q).map((result) => ({
           ...result,
-          boardId: canvasState.activeBoardId,
+          boardId: board.id,
+          boardTitle: board.name,
           cardId: result.id,
         }));
-    results.sort((a, b) => b.score - a.score);
-    return {
-      results: Number.isFinite(limit) && limit > 0 ? results.slice(0, Math.floor(limit)) : results,
-      query: q,
-    };
-  },
-});
+        const readme = read.layout.nodes.find((node) => node.id === board.readmeNodeId);
+        const readmeText = typeof readme?.data.content === 'string' ? readme.data.content : '';
+        const score = searchRelevance(
+          board.name,
+          [
+            [board.folder ?? '', 2],
+            [readmeText, 1],
+          ],
+          q,
+        );
+        if (score > 0) {
+          cards.unshift({
+            id: board.id,
+            type: 'board',
+            title: board.name,
+            snippet: readmeText.slice(0, 160) || board.folder || board.name,
+            score,
+            boardId: board.id,
+            boardTitle: board.name,
+            cardId: readme?.id ?? board.id,
+          });
+        }
+        return cards;
+      })
+    : searchNodes(
+        !hasFilter || selectedBoards.some((board) => board.id === canvasState.activeBoardId)
+          ? canvasState.getLayout().nodes
+          : [],
+        q,
+      ).map((result) => ({
+        ...result,
+        boardId: canvasState.activeBoardId,
+        cardId: result.id,
+      }));
+  results.sort((a, b) => {
+    const aKey = `${a.boardId ?? ''}/${a.id}`;
+    const bKey = `${b.boardId ?? ''}/${b.id}`;
+    return b.score - a.score || (aKey < bKey ? -1 : aKey > bKey ? 1 : 0);
+  });
+  const delivered = Number.isFinite(limit) && limit > 0 ? results.slice(0, Math.floor(limit)) : results;
+  const qualifications = lifecycleQualifications(
+    Date.now(),
+    delivered.flatMap((result) => (result.boardId ? [{ boardId: result.boardId, cardId: result.cardId }] : [])),
+  );
+  return {
+    results: delivered.map((result) => ({
+      ...result,
+      ...(result.boardId
+        ? { qualification: qualifications[memoryKey({ boardId: result.boardId, cardId: result.cardId })] }
+        : {}),
+    })),
+    query: q,
+  };
+}
 
 // ── context.get ───────────────────────────────────────────────
 
@@ -246,28 +311,83 @@ const contextOperation = defineOperation<z.infer<typeof contextSchema>, Record<s
 
     // Capture the active target and revision synchronously. Library boards are
     // read from SQLite and are never opened or made writable by this operation.
+    let qualifications = lifecycleQualifications();
+    const included = (boardId: string, node: CanvasNodeState) =>
+      !qualifications[memoryKey({ boardId, cardId: node.id })]?.retired;
     const layout = canvasState.getLayout();
+    layout.nodes = layout.nodes.filter((node) => included(active.id, node));
+    // One read per board per brief: linked/same-folder tiers, README summaries and
+    // pinned boards all share it (the link scan below reads without blobs).
+    const fullReads = new Map<string, ReturnType<typeof canvasState.readBoard>>();
+    const readFull = (boardId: string) => {
+      if (!fullReads.has(boardId)) {
+        const read = canvasState.readBoard(boardId, true);
+        if (read) read.layout.nodes = read.layout.nodes.filter((node) => included(boardId, node));
+        fullReads.set(boardId, read);
+      }
+      return fullReads.get(boardId) ?? null;
+    };
     const revision = canvasState.getContentRevision();
     const pinnedNodeIds = [...canvasState.contextPinnedNodeIds];
     const linkedIds = new Map<string, string[]>();
-    for (const node of layout.nodes) {
-      if (node.type !== 'board' || typeof node.data.boardId !== 'string') continue;
-      const ids = linkedIds.get(node.data.boardId) ?? [];
-      ids.push(node.id);
-      linkedIds.set(node.data.boardId, ids);
+    const graph = memoryGraph();
+    const graphNodes = new Map(graph.nodes.map((node) => [node.key, node]));
+    const qualifiedTitle = (target: MemoryTarget): string | undefined => {
+      const card = graphNodes.get(memoryKey(target));
+      const board = graphNodes.get(memoryKey({ boardId: target.boardId }));
+      return card && board ? (target.cardId ? `${board.title} / ${card.title}` : board.title) : undefined;
+    };
+    const connections = boardConnections(graph).filter((edge) => !edge.missing);
+    const memoryRelations: Record<string, string[]> = {};
+    for (const edge of graph.edges) {
+      if (edge.kind === 'member') continue;
+      // Local and outgoing card edges are compiled below with their revision marks.
+      // Only incoming cross-board card edges need the library graph here.
+      if (edge.kind === 'card' && (edge.source.boardId === edge.target.boardId || edge.target.boardId !== active.id))
+        continue;
+      for (const [source, target, direction] of [
+        [edge.source, edge.target, '→'],
+        [edge.target, edge.source, '←'],
+      ] as const) {
+        if (source.boardId !== active.id || !source.cardId) continue;
+        const other = graphNodes.get(direction === '→' ? edge.to : edge.from);
+        const kind = edge.kind === 'card' ? relationText({ ...edge, kind: edge.relationKind }) : edge.kind;
+        memoryRelations[source.cardId] ??= [];
+        memoryRelations[source.cardId].push(
+          `${direction} ${kind}: ${qualifiedTitle(target) ?? other?.title ?? 'Missing target'} (${target.boardId}${target.cardId ? ` / ${target.cardId}` : ''})`,
+        );
+      }
+    }
+    for (const link of graph.unresolvedLinks) {
+      if (link.source.boardId === active.id && link.source.cardId) {
+        memoryRelations[link.source.cardId] ??= [];
+        memoryRelations[link.source.cardId].push(`Unresolved wiki: [[${link.ref}]]`);
+      }
+    }
+    for (const edge of connections) {
+      const other =
+        edge.source.boardId === active.id
+          ? edge.target.boardId
+          : edge.target.boardId === active.id
+            ? edge.source.boardId
+            : null;
+      if (!other) continue;
+      const ids = linkedIds.get(other) ?? [];
+      if (edge.source.boardId === active.id && edge.source.cardId) ids.push(edge.source.cardId);
+      linkedIds.set(other, ids);
     }
     const libraryBoards: ContextBriefLibraryBoard[] = [];
     for (const board of canvasState.listBoards()) {
       if (board.id === active.id) continue;
-      if (!linkedIds.has(board.id) && (!active.category || active.category !== board.category)) continue;
-      const read = canvasState.readBoard(board.id, true);
+      if (!linkedIds.has(board.id) && (!active.folder || active.folder !== board.folder)) continue;
+      const read = readFull(board.id);
       if (!read) continue;
       const readme = read.layout.nodes.find((node) => node.id === board.readmeNodeId);
       const pins = new Set(read.state.contextPins);
       libraryBoards.push({
         boardId: board.id,
         name: board.name,
-        category: board.category,
+        folder: board.folder,
         ...(readme
           ? {
               readme: {
@@ -286,6 +406,65 @@ const contextOperation = defineOperation<z.infer<typeof contextSchema>, Record<s
         linkIds: linkedIds.get(board.id) ?? [],
       });
     }
+    // The brief is a map (vision move 0a and the maintainer's 2026-10-07 rule):
+    // titles, short summaries and relations; the agent pulls what it wants in full.
+    const title = (node: { id: string; data: Record<string, unknown> }) =>
+      typeof node.data.title === 'string' && node.data.title ? node.data.title : node.id;
+    const short = (node: CanvasNodeState) =>
+      summarizeNodeForAgentContext(node, {
+        defaultTextLength: BRIEF_SUMMARY_LENGTH,
+        webpageTextLength: BRIEF_SUMMARY_LENGTH,
+      });
+    // Connections come from the shared graph; README summaries are read
+    // only for the open board and pinned boards, so a large library stays cheap.
+    const library = canvasState.listBoards();
+    const names = new Map(library.map((board) => [board.id, board.name]));
+    const linksFrom = new Map<string, string[]>();
+    for (const board of library) {
+      linksFrom.set(
+        board.id,
+        connections.filter((edge) => edge.source.boardId === board.id).map((edge) => edge.target.boardId),
+      );
+    }
+    const readmeSummary = (boardId: string): string | null => {
+      const board = library.find((entry) => entry.id === boardId);
+      if (!board?.readmeNodeId) return null;
+      const nodes = boardId === active.id ? layout.nodes : (readFull(boardId)?.layout.nodes ?? []);
+      const readme = nodes.find((node) => node.id === board.readmeNodeId && node.type === 'markdown');
+      return readme ? summarizeNodeForAgentContext(readme, { defaultTextLength: 1_000 }) : null;
+    };
+    const relationsOf = (boardId: string) => ({
+      folder: library.find((board) => board.id === boardId)?.folder ?? null,
+      readmeSummary: readmeSummary(boardId),
+      readmeNodeId: library.find((board) => board.id === boardId)?.readmeNodeId ?? undefined,
+      links: [...new Set((linksFrom.get(boardId) ?? []).flatMap((id) => names.get(id) ?? []))],
+      backlinks: [
+        ...new Set(
+          [...linksFrom].filter(([, targets]) => targets.includes(boardId)).flatMap(([id]) => names.get(id) ?? []),
+        ),
+      ],
+    });
+    const overview = relationsOf(active.id);
+    const pinReasons: Record<string, string> = {};
+    for (const [nodeId, meta] of Object.entries(canvasState.getContextPinMeta())) {
+      if (meta.reason) pinReasons[nodeId] = meta.reason;
+    }
+    const pinnedBoards: ContextBriefPinnedBoard[] = [];
+    for (const board of library) {
+      if (!board.pin || board.id === active.id) continue;
+      const read = readFull(board.id);
+      if (!read) continue;
+      const pins = new Set(read.state.contextPins);
+      pinnedBoards.push({
+        boardId: board.id,
+        name: board.name,
+        ...relationsOf(board.id),
+        cards: read.layout.nodes
+          .filter((node) => pins.has(node.id))
+          .sort((a, b) => a.id.localeCompare(b.id))
+          .map((node) => ({ nodeId: node.id, title: title(node), summary: short(node) })),
+      });
+    }
     const entries: ContextBriefSourceEntry[] = layout.nodes
       .filter((node) => node.createdBy?.actor === 'human')
       .map((node) => ({
@@ -293,7 +472,7 @@ const contextOperation = defineOperation<z.infer<typeof contextSchema>, Record<s
         nodeId: node.id,
         reason: 'human' as const,
         title: typeof node.data.title === 'string' ? node.data.title : node.id,
-        text: summarizeNodeForAgentContext(node, { defaultTextLength: budget, webpageTextLength: budget }),
+        text: short(node),
       }));
     entries.push(
       ...canvasState
@@ -336,15 +515,41 @@ const contextOperation = defineOperation<z.infer<typeof contextSchema>, Record<s
         text: item.message,
       })),
     );
+    qualifications = lifecycleQualifications(
+      Date.now(),
+      [...fullReads.keys()].map((boardId) => ({ boardId })),
+    );
     const result = compileContextBrief({
-      activeBoard: { boardId: active.id, name: active.name, category: active.category },
+      qualifications,
+      activeBoard: { boardId: active.id, name: active.name, folder: active.folder },
       nodes: layout.nodes,
       pinnedNodeIds,
       contentRevision: revision.revision,
       retentionFloor: revision.retentionFloor,
       tombstones: canvasState.readContentDelta(sinceValue ?? 0).deleted,
       since: explicitSince ? (Number.isSafeInteger(sinceValue) ? sinceValue : Number.NaN) : sinceValue,
+      overview,
+      memoryRelations,
+      edges: layout.edges.map((edge) => ({
+        from: edge.from,
+        to: edge.to,
+        toBoardId: edge.toBoardId,
+        remoteTitle: edge.toBoardId
+          ? (qualifiedTitle({ boardId: edge.toBoardId, cardId: edge.to }) ??
+            `Missing target (${edge.toBoardId} / ${edge.to})`)
+          : undefined,
+        type: edge.type,
+        kind: edge.kind,
+        reason: edge.reason,
+        label: edge.label ?? null,
+        revision: edge.revision,
+        changedBy: edge.changedBy,
+        createdAt: edge.createdAt,
+        changedAt: edge.changedAt,
+      })),
+      pinReasons,
       libraryBoards,
+      pinnedBoards,
       entries,
       budget,
     });
@@ -425,6 +630,10 @@ const undoOperation = defineOperation<z.infer<typeof undoRedoSchema>, Record<str
     await syncCanvasRuntimeBackends();
     ctx.emit('canvas-viewport-update', { viewport: canvasState.viewport });
     ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    ctx.emit('context-pins-changed', {
+      count: canvasState.contextPinnedNodeIds.size,
+      nodeIds: Array.from(canvasState.contextPinnedNodeIds),
+    });
     return { ok: true, description: `Undid: ${entry.description}` };
   },
 });
@@ -449,6 +658,10 @@ const redoOperation = defineOperation<z.infer<typeof undoRedoSchema>, Record<str
     await syncCanvasRuntimeBackends();
     ctx.emit('canvas-viewport-update', { viewport: canvasState.viewport });
     ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    ctx.emit('context-pins-changed', {
+      count: canvasState.contextPinnedNodeIds.size,
+      nodeIds: Array.from(canvasState.contextPinnedNodeIds),
+    });
     return { ok: true, description: `Redid: ${entry.description}` };
   },
 });

package/src/server/operations/ops/snapshots.ts

@@ -1,7 +1,7 @@
 /**
  * Slice 3 operations (plan-005, migration item 5): snapshot.list /
  * snapshot.save / snapshot.gc / snapshot.diff (+ query-param variant) /
- * snapshot.restore / snapshot.delete.
+ * snapshot.restore / snapshot.restore-node / snapshot.delete.
  *
  * Wire notes:
  * - snapshot.list serves the bare-array body (tests/e2e clearSnapshots reads
@@ -24,6 +24,7 @@
  */
 import { z } from 'zod';
 import { canvasState } from '../../canvas-state.js';
+import { wikiLinksFromData } from '../../../shared/memory-graph.js';
 import {
   deleteCanvasSnapshot,
   gcCanvasSnapshots,
@@ -333,6 +334,76 @@ const snapshotRestoreOperation = defineOperation<z.infer<typeof snapshotRestoreS
   },
 });
 
+// ── snapshot.restore-node ─────────────────────────────────────
+
+const snapshotRestoreNodeShape = {
+  id: z.string().optional().catch(undefined).describe('Snapshot ID or name holding the earlier version'),
+  nodeId: z.string().optional().catch(undefined).describe('The card to put back as it was in that snapshot'),
+  preserveHumanEdits: z.boolean().optional().describe('Skip a card whose latest editor is human (receipt Undo)'),
+};
+
+const snapshotRestoreNodeSchema = z.looseObject(snapshotRestoreNodeShape);
+
+/**
+ * One card back to its content in a snapshot — the receipt's Undo on an edit
+ * (docs/design/AgentContext.dc.html), without restoring the rest of the board.
+ * A normal, undoable node edit: position, links and pins stay as they are.
+ */
+const snapshotRestoreNodeOperation = defineOperation<
+  z.infer<typeof snapshotRestoreNodeSchema>,
+  Record<string, unknown>
+>({
+  name: 'snapshot.restore-node',
+  mutates: true,
+  input: snapshotRestoreNodeSchema,
+  inputShape: snapshotRestoreNodeShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/snapshots/:id/restore-node',
+  },
+  handler: ({ id, nodeId, preserveHumanEdits }) => {
+    const snapshot = canvasState.getSnapshotData(id ?? '');
+    if (!snapshot) throw new OperationError('Snapshot not found', 404);
+    const current = canvasState.getNode(nodeId ?? '');
+    const earlier = snapshot.nodes.find((node) => node.id === nodeId);
+    if (!current || !earlier)
+      throw new OperationError(`Node "${nodeId}" is not in both the board and the snapshot.`, 404);
+    // A file card mirrors its file on disk; old text would only be overwritten by the watcher.
+    if (current.type === 'file') throw new OperationError('A file card follows its file; restore the file instead.');
+    if (earlier.type !== current.type) {
+      throw new OperationError(
+        `Node "${current.id}" was a ${earlier.type} card in that snapshot; it is a ${current.type} now.`,
+        409,
+      );
+    }
+    // Check current ownership at the write boundary, not a browser's last poll.
+    if (preserveHumanEdits && current.lastEditedBy?.actor === 'human') {
+      return { ok: true, id: current.id, restored: false, skipped: 'human-edit' };
+    }
+    // Content only: where the card sits in groups is today's, not the snapshot's.
+    const data = { ...earlier.data };
+    for (const key of ['parentGroup', 'children'] as const) {
+      if (current.data[key] === undefined) delete data[key];
+      else data[key] = current.data[key];
+    }
+    canvasState.updateNode(
+      current.id,
+      { data },
+      earlier.type === 'markdown'
+        ? earlier.data.wikiLinks === undefined
+          ? null
+          : wikiLinksFromData(earlier.data)
+        : undefined,
+    );
+    return {
+      ok: true,
+      id: current.id,
+      restored: true,
+      contentRevision: canvasState.getNode(current.id)?.contentRevision ?? null,
+    };
+  },
+});
+
 // ── snapshot.delete ───────────────────────────────────────────
 
 const snapshotDeleteShape = {
@@ -375,6 +446,7 @@ export const snapshotOperations: Operation[] = [
   snapshotGcOperation,
   snapshotDiffQueryOperation,
   snapshotDiffOperation,
+  snapshotRestoreNodeOperation,
   snapshotRestoreOperation,
   snapshotDeleteOperation,
 ];

package/src/server/operations/ops/validate.ts

@@ -32,7 +32,11 @@ const validateGetOperation = defineOperation<z.infer<typeof validateGetSchema>,
       content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
     }),
   },
-  handler: () => validateCanvasLayout(canvasState.getLayout()),
+  handler: () =>
+    validateCanvasLayout(
+      canvasState.getLayout(),
+      (boardId, cardId) => !!canvasState.readBoard(boardId, false)?.layout.nodes.some((node) => node.id === cardId),
+    ),
 });
 
 export const validateOperations: Operation[] = [validateGetOperation];