pmx-canvas 0.8.2 → 0.9.0

package/src/server/canvas-operations.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { basename, resolve } from 'node:path';
 import { agentPresence } from './agent-presence.js';
 import { recomputeCodeGraph } from './code-graph.js';
@@ -22,12 +23,14 @@ import {
 } from './mcp-app-runtime.js';
 import { mutationHistory } from './mutation-history.js';
 import { intentRegistry } from './intent-registry.js';
+import { OperationError } from './operations/types.js';
 import { clampCreateNodeSize } from './canvas-validation.js';
 import { validCanvasNodeUpdates } from './canvas-geometry.js';
 import { computeGroupBounds, findOpenCanvasPosition } from './placement.js';
 import { searchNodes } from './spatial-analysis.js';
 import { getCanvasNodeTitle } from './canvas-serialization.js';
 import { computeAutoArrange } from '../shared/auto-arrange.js';
+import { relationKindSchema, relationReasonSchema } from '../shared/relations.js';
 import {
   applyJsonRenderStreamPatches,
   buildGraphSpec,
@@ -93,6 +96,7 @@ export interface CanvasStructuredNodeUpdateInput extends Omit<CanvasGraphNodeUpd
 }
 
 interface CanvasAddNodeInput {
+  prepareOnlyNodes?: CanvasNodeState[];
   type: CanvasNodeState['type'];
   title?: string;
   content?: string;
@@ -150,6 +154,10 @@ export function describeCreateSize(
 // surface's sizeWarnings.
 
 interface CanvasCreateGroupInput {
+  destinationBoardId?: string;
+  requestId?: string;
+  expectedBoardId?: string | null;
+  intentId?: string;
   title?: string;
   childIds?: string[];
   x?: number;
@@ -163,6 +171,7 @@ interface CanvasCreateGroupInput {
 interface CanvasNodeLookupInput {
   id?: string;
   search?: string;
+  board?: string;
 }
 
 const MAX_CONTEXT_PINS = 20;
@@ -424,6 +433,7 @@ export function buildGraphNodeUpdate(
   const source = isGraphPayloadLike(input.spec)
     ? input.spec
     : Object.fromEntries(Object.entries(input).filter(([key, value]) => key !== 'spec' && value !== undefined));
+  const specVersion = (typeof node.data.specVersion === 'number' ? node.data.specVersion : 0) + 1;
 
   if (input.spec !== undefined && !isGraphPayloadLike(input.spec)) {
     const spec = normalizeAndValidateJsonRenderSpec(input.spec);
@@ -436,6 +446,7 @@ export function buildGraphNodeUpdate(
         ...createJsonRenderNodeData(node.id, title, spec, {
           viewerType: 'graph',
           graphConfig: currentConfig,
+          specVersion,
         }),
       },
     };
@@ -453,6 +464,7 @@ export function buildGraphNodeUpdate(
       ...createJsonRenderNodeData(node.id, title, spec, {
         viewerType: 'graph',
         graphConfig,
+        specVersion,
       }),
     },
   };
@@ -791,7 +803,7 @@ function buildImageNodeData(input: CanvasAddNodeInput): Record<string, unknown>
   }
 
   if (!isDataUri && !isUrl && src) {
-    const resolved = resolve(src);
+    const resolved = resolve(canvasState.getWorkspaceRoot(), src);
     const fileName = basename(resolved) || src;
     const { mimeType } = validateLocalImageFile(resolved);
     return {
@@ -949,7 +961,7 @@ export function addCanvasNode(input: CanvasAddNodeInput): {
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
-      : findOpenCanvasPosition(canvasState.getLayout().nodes, width, height);
+      : findOpenCanvasPosition(input.prepareOnlyNodes ?? canvasState.getLayout().nodes, width, height);
   const id = `node-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
   const data = buildNodeData(input);
   const node: CanvasNodeState = {
@@ -963,6 +975,7 @@ export function addCanvasNode(input: CanvasAddNodeInput): {
     data,
   };
 
+  if (input.prepareOnlyNodes) return { id, node, needsCodeGraphRecompute: false };
   canvasState.addNode(node);
   const storedNode = canvasState.getNode(id) ?? node;
 
@@ -992,8 +1005,12 @@ export function resolveCanvasNode(nodeRef: CanvasNodeLookupInput):
       ok: false;
       error: string;
     } {
+  const remote = nodeRef.board ? canvasState.readBoard(nodeRef.board, true) : null;
+  if (nodeRef.board && !remote) return { ok: false, error: `Board "${nodeRef.board}" not found.` };
+  const getNode = (id: string) =>
+    remote ? remote.layout.nodes.find((node) => node.id === id) : canvasState.getNode(id);
   if (typeof nodeRef.id === 'string' && nodeRef.id.trim().length > 0) {
-    const node = canvasState.getNode(nodeRef.id.trim());
+    const node = getNode(nodeRef.id.trim());
     if (!node) {
       return { ok: false, error: `Node "${nodeRef.id}" not found.` };
     }
@@ -1002,7 +1019,7 @@ export function resolveCanvasNode(nodeRef: CanvasNodeLookupInput):
 
   if (typeof nodeRef.search === 'string' && nodeRef.search.trim().length > 0) {
     const query = nodeRef.search.trim();
-    const layout = canvasState.getLayout();
+    const layout = remote?.layout ?? canvasState.getLayout();
     const exactTitleMatches = layout.nodes.filter((node) => {
       const title = getCanvasNodeTitle(node);
       return title !== null && title.toLowerCase() === query.toLowerCase();
@@ -1030,7 +1047,7 @@ export function resolveCanvasNode(nodeRef: CanvasNodeLookupInput):
           .join(', ')}`,
       };
     }
-    const node = canvasState.getNode(matches[0]!.id);
+    const node = getNode(matches[0]!.id);
     if (!node) {
       return { ok: false, error: `Resolved node "${matches[0]!.id}" disappeared.` };
     }
@@ -1406,7 +1423,8 @@ export function setCanvasContextPins(
     canvasState.setContextPins(normalizePins([...current, ...normalizedNodeIds]), options);
   } else {
     const current = Array.from(canvasState.contextPinnedNodeIds);
-    canvasState.setContextPins(current.filter((id) => !normalizedNodeIds.includes(id)));
+    // Limit live pins, not a merged receipt's list of IDs to remove.
+    canvasState.setContextPins(current.filter((id) => !nodeIds.includes(id)));
   }
 
   return {
@@ -1522,50 +1540,76 @@ export function gcCanvasSnapshots(
 }
 
 export function addCanvasEdge(input: {
+  destinationBoardId?: string;
+  requestId?: string;
+  expectedBoardId?: string | null;
+  intentId?: string;
   from?: string;
   to?: string;
+  toBoardId?: string;
   fromSearch?: string;
   toSearch?: string;
   type: CanvasEdge['type'];
+  kind?: string;
+  reason?: string;
   label?: string;
   style?: CanvasEdge['style'];
   animated?: boolean;
 }): CanvasEdge {
-  const fromResult = resolveCanvasNode({
-    ...(typeof input.from === 'string' ? { id: input.from } : {}),
-    ...(typeof input.fromSearch === 'string' ? { search: input.fromSearch } : {}),
-  });
-  if (!fromResult.ok) {
-    throw new Error(fromResult.error);
-  }
-  const toResult = resolveCanvasNode({
-    ...(typeof input.to === 'string' ? { id: input.to } : {}),
-    ...(typeof input.toSearch === 'string' ? { search: input.toSearch } : {}),
-  });
-  if (!toResult.ok) {
-    throw new Error(toResult.error);
-  }
+  const stored =
+    input.destinationBoardId !== undefined || input.requestId !== undefined
+      ? storedCreationTarget(input, 'edge.add')
+      : undefined;
+  const build = (): CanvasEdge => {
+    const kind = input.kind === undefined ? undefined : relationKindSchema.parse(input.kind);
+    const reason = input.reason === undefined ? undefined : relationReasonSchema.parse(input.reason);
+    const fromResult = resolveCanvasNode({
+      ...(typeof input.from === 'string' ? { id: input.from } : {}),
+      ...(typeof input.fromSearch === 'string' ? { search: input.fromSearch } : {}),
+      ...(stored ? { board: stored.boardId } : {}),
+    });
+    if (!fromResult.ok) {
+      throw new Error(fromResult.error);
+    }
+    const toResult = resolveCanvasNode({
+      ...(typeof input.to === 'string' ? { id: input.to } : {}),
+      ...(typeof input.toSearch === 'string' ? { search: input.toSearch } : {}),
+      ...(input.toBoardId || stored ? { board: input.toBoardId ?? stored!.boardId } : {}),
+    });
+    if (!toResult.ok) {
+      throw new Error(toResult.error);
+    }
 
-  const id = `edge-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
-  const edge: CanvasEdge = {
-    id,
-    from: fromResult.node.id,
-    to: toResult.node.id,
-    type: input.type,
-    ...(input.label ? { label: input.label } : {}),
-    ...(input.style ? { style: input.style } : {}),
-    ...(input.animated !== undefined ? { animated: input.animated } : {}),
+    const id = `edge-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+    const edge: CanvasEdge = {
+      id,
+      from: fromResult.node.id,
+      to: toResult.node.id,
+      ...(input.toBoardId && input.toBoardId !== (stored?.boardId ?? canvasState.activeBoardId)
+        ? { toBoardId: input.toBoardId }
+        : {}),
+      type: input.type,
+      ...(kind ? { kind } : {}),
+      ...(reason ? { reason } : {}),
+      ...(input.label ? { label: input.label } : {}),
+      ...(input.style ? { style: input.style } : {}),
+      ...(input.animated !== undefined ? { animated: input.animated } : {}),
+    };
+    return edge;
   };
+  if (stored) return canvasState.createStoredEdge(stored.boardId, stored.requestId, stored.fingerprint, build);
+  const edge = build();
   const added = canvasState.addEdge(edge);
   if (!added) {
     throw new Error('Duplicate or self-edge.');
   }
-  return edge;
+  // The stored link, stamped with its author and revision — the browser replaces its copy with this.
+  return canvasState.getEdges().find((stored) => stored.id === edge.id) ?? edge;
 }
 
 export function updateCanvasEdge(
   id: string,
-  patch: Partial<Pick<CanvasEdge, 'type' | 'label' | 'style' | 'animated'>>,
+  patch: Partial<Pick<CanvasEdge, 'type' | 'kind' | 'reason' | 'label' | 'style' | 'animated'>>,
 ): CanvasEdge {
   if (!canvasState.getEdges().some((edge) => edge.id === id)) {
     throw new Error(`Edge "${id}" not found.`);
@@ -1586,52 +1630,73 @@ export function createCanvasGroup(input: CanvasCreateGroupInput): {
   node: CanvasNodeState;
   sizeAdjustment?: CanvasSizeAdjustment;
 } {
-  let x = input.x;
-  let y = input.y;
-  let width = input.width ?? 600;
-  let height = input.height ?? 400;
+  const stored =
+    input.destinationBoardId !== undefined || input.requestId !== undefined
+      ? storedCreationTarget(
+          { ...input, title: input.title ?? 'Group', childIds: input.childIds ?? [] },
+          'group.create',
+        )
+      : undefined;
   const explicitFrame =
     input.x !== undefined || input.y !== undefined || input.width !== undefined || input.height !== undefined;
-
-  const childIds = input.childIds ?? [];
-  if (childIds.length > 0 && x === undefined && y === undefined) {
-    const childRects = childIds
-      .map((cid) => canvasState.getNode(cid))
-      .filter((node): node is CanvasNodeState => node !== undefined);
-    const bounds = computeGroupBounds(childRects);
-    if (bounds) {
-      x = bounds.x;
-      y = bounds.y;
-      width = bounds.width;
-      height = bounds.height;
+  const childIds = [...new Set(input.childIds ?? [])];
+  const build = (nodes: CanvasNodeState[]): CanvasNodeState => {
+    const missing = childIds.filter((id) => !nodes.some((node) => node.id === id));
+    if (stored && missing.length)
+      throw new OperationError(`Cannot create group: missing child node IDs: ${missing.join(', ')}.`);
+    // Selecting both a frame and its descendant would create conflicting memberships.
+    for (const id of stored ? childIds : []) {
+      let parent = nodes.find((node) => node.id === id)?.data.parentGroup;
+      while (typeof parent === 'string') {
+        if (childIds.includes(parent)) throw new OperationError('Cannot group both an ancestor and its descendant.');
+        parent = nodes.find((node) => node.id === parent)?.data.parentGroup;
+      }
+    }
+    let x = input.x;
+    let y = input.y;
+    let width = input.width ?? 600;
+    let height = input.height ?? 400;
+    if (childIds.length > 0 && x === undefined && y === undefined) {
+      const childRects = childIds
+        .map((cid) => nodes.find((node) => node.id === cid))
+        .filter((node): node is CanvasNodeState => node !== undefined);
+      const bounds = computeGroupBounds(childRects);
+      if (bounds) {
+        x = bounds.x;
+        y = bounds.y;
+        width = bounds.width;
+        height = bounds.height;
+      }
     }
-  }
 
-  const position =
-    x !== undefined && y !== undefined
-      ? { x, y }
-      : findOpenCanvasPosition(canvasState.getLayout().nodes, width, height);
+    const position = x !== undefined && y !== undefined ? { x, y } : findOpenCanvasPosition(nodes, width, height);
 
-  const id = `group-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
-  const data: Record<string, unknown> = {
-    title: input.title ?? 'Group',
-    children: [],
-    frameMode: explicitFrame ? 'manual' : 'fit',
-    ...(input.color ? { color: input.color } : {}),
-  };
+    const id = `group-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+    const data: Record<string, unknown> = {
+      title: input.title ?? 'Group',
+      children: [],
+      frameMode: explicitFrame ? 'manual' : 'fit',
+      ...(input.color ? { color: input.color } : {}),
+    };
 
-  canvasState.addNode({
-    id,
-    type: 'group',
-    position,
-    size: { width, height },
-    zIndex: 0,
-    collapsed: false,
-    pinned: false,
-    data,
-  });
+    return {
+      id,
+      type: 'group',
+      position,
+      size: { width, height },
+      zIndex: 0,
+      collapsed: false,
+      pinned: false,
+      data: { ...data, children: stored ? childIds : [] },
+    };
+  };
+  const created = stored
+    ? canvasState.createStoredGroup(stored.boardId, stored.requestId, stored.fingerprint, build, input.childLayout)
+    : build(canvasState.getLayout().nodes);
+  const id = created.id;
+  if (!stored) canvasState.addNode(created);
 
-  if (childIds.length > 0) {
+  if (!stored && childIds.length > 0) {
     canvasState.groupNodes(id, childIds, {
       preservePositions: input.childLayout === undefined,
       ...(input.childLayout ? { layout: input.childLayout } : {}),
@@ -1639,7 +1704,7 @@ export function createCanvasGroup(input: CanvasCreateGroupInput): {
     });
   }
 
-  const node = canvasState.getNode(id);
+  const node = stored ? created : canvasState.getNode(id);
   if (!node) {
     throw new Error(`Group "${id}" was not created.`);
   }
@@ -1660,6 +1725,41 @@ export function createCanvasGroup(input: CanvasCreateGroupInput): {
   };
 }
 
+/** One logical creation identity across node, frame and link operations. */
+export function storedCreationTarget(input: object, operation: string) {
+  const body = input as Record<string, unknown>;
+  for (const key of ['destinationBoardId', 'requestId']) {
+    if (body[key] !== undefined && (typeof body[key] !== 'string' || !body[key].trim()))
+      throw new OperationError(`${key} must be a non-empty string.`);
+  }
+  if (body.expectedBoardId !== undefined && body.expectedBoardId !== canvasState.activeBoardId)
+    throw new OperationError('The active board changed. Refresh before retrying this action.', 409);
+  if (body.intentId !== undefined)
+    throw new OperationError('Destination/retry creation does not support ghost intents.');
+  const boardId = typeof body.destinationBoardId === 'string' ? body.destinationBoardId : canvasState.activeBoardId;
+  if (!boardId) throw new OperationError('Open a board or provide destinationBoardId.');
+  const ignored = new Set(['requestId', 'destinationBoardId', 'expectedBoardId', 'full', 'verbose', 'agentId']);
+  const canonical = (value: unknown): unknown =>
+    Array.isArray(value)
+      ? value.map(canonical)
+      : isRecord(value)
+        ? Object.fromEntries(
+            Object.keys(value)
+              .sort()
+              .filter((key) => value[key] !== undefined)
+              .map((key) => [key, canonical(value[key])]),
+          )
+        : value;
+  const fingerprint = createHash('sha256')
+    .update(JSON.stringify(canonical(Object.fromEntries(Object.entries(body).filter(([key]) => !ignored.has(key))))))
+    .digest('hex');
+  return {
+    boardId,
+    requestId: typeof body.requestId === 'string' ? body.requestId : undefined,
+    fingerprint: operation === 'node.add' ? fingerprint : `${operation}:${fingerprint}`,
+  };
+}
+
 export function groupCanvasNodes(
   groupId: string,
   childIds: string[],
@@ -1893,16 +1993,21 @@ export function createCanvasGraphNode(input: GraphNodeInput): {
  * fit call still win. In-memory only (a live client fact, never persisted);
  * with several clients connected, the most recent reporter wins.
  */
-let lastClientViewportSize: { width: number; height: number } | null = null;
-
-export function setClientViewportSize(width: unknown, height: unknown): void {
+let lastClientViewportSize: {
+  width: number;
+  height: number;
+  boardId: string | null;
+  insets?: { top: number; bottom: number };
+} | null = null;
+
+export function setClientViewportSize(width: unknown, height: unknown, insets?: { top: number; bottom: number }): void {
   if (typeof width !== 'number' || typeof height !== 'number') return;
   if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return;
-  lastClientViewportSize = { width, height };
+  lastClientViewportSize = { width, height, boardId: canvasState.activeBoardId, insets };
 }
 
 export function getClientViewportSize(): { width: number; height: number } | null {
-  return lastClientViewportSize ? { ...lastClientViewportSize } : null;
+  return lastClientViewportSize ? { width: lastClientViewportSize.width, height: lastClientViewportSize.height } : null;
 }
 
 export function fitCanvasView(options: CanvasFitViewOptions = {}): CanvasFitViewResult {
@@ -1911,7 +2016,8 @@ export function fitCanvasView(options: CanvasFitViewOptions = {}): CanvasFitView
   const padding = positiveNumber(options.padding, 24); // screen px now, not world units
   const maxScale = positiveNumber(options.maxScale, 1);
   const nodeIdFilter = options.nodeIds && options.nodeIds.length > 0 ? new Set(options.nodeIds) : null;
-  const targetNodes = canvasState.getLayout().nodes.filter((node) => !nodeIdFilter || nodeIdFilter.has(node.id));
+  const layout = canvasState.getLayout();
+  const targetNodes = layout.nodes.filter((node) => !nodeIdFilter || nodeIdFilter.has(node.id));
 
   if (targetNodes.length === 0) {
     const viewport = canvasState.viewport;
@@ -1933,12 +2039,18 @@ export function fitCanvasView(options: CanvasFitViewOptions = {}): CanvasFitView
   // Screen-space fit (architecture rule 9): `padding` and the chrome reserve
   // are SCREEN pixels — world-space padding shrank with the fit zoom and
   // parked nodes under the command bar and minimap (0.5.0 Amp report,
-  // finding A). The server cannot measure the client's chrome, so it reserves
-  // nominal bottom space: the minimap is always there; the command bar only
-  // while a session is attached.
-  const bottomReserve = agentPresence.snapshot().sessionActive ? 128 : 96;
+  // finding A). The workbench reports its measured chrome with its size;
+  // without a matching board and viewport size, retain nominal chrome reserves.
+  const insets =
+    lastClientViewportSize?.boardId === canvasState.activeBoardId &&
+    lastClientViewportSize.width === width &&
+    lastClientViewportSize.height === height
+      ? lastClientViewportSize.insets
+      : undefined;
+  const bottomReserve = insets?.bottom ?? (agentPresence.snapshot().sessionActive ? 128 : 96);
+  const topReserve = Math.max(padding, insets?.top ?? (layout.edges.length ? 90 : 48));
   const usableWidth = Math.max(80, width - padding * 2);
-  const usableHeight = Math.max(80, height - padding - bottomReserve);
+  const usableHeight = Math.max(80, height - topReserve - bottomReserve);
   const worldWidth = Math.max(1, bounds.width);
   const worldHeight = Math.max(1, bounds.height);
   const scale = Math.min(maxScale, usableWidth / worldWidth, usableHeight / worldHeight);
@@ -1946,7 +2058,7 @@ export function fitCanvasView(options: CanvasFitViewOptions = {}): CanvasFitView
   const centerY = minY + bounds.height / 2;
   const viewport = {
     x: padding + usableWidth / 2 - centerX * scale,
-    y: padding + usableHeight / 2 - centerY * scale,
+    y: topReserve + usableHeight / 2 - centerY * scale,
     scale,
   };
 

package/src/server/canvas-provenance.ts

@@ -1,5 +1,7 @@
 import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
 import { normalizeHtmlNodeSemanticData } from './html-node-summary.js';
+import { OperationError } from './operations/types.js';
 
 export type CanvasNodeType =
   | 'markdown'
@@ -26,7 +28,8 @@ export type CanvasNodeProvenanceSourceKind =
   | 'webpage-url'
   | 'mcp-tool'
   | 'artifact-file'
-  | 'image-url';
+  | 'image-url'
+  | 'recipe';
 
 export type CanvasNodeRefreshStrategy =
   | 'file-watch'
@@ -34,7 +37,21 @@ export type CanvasNodeRefreshStrategy =
   | 'image-reload'
   | 'webpage-refresh'
   | 'mcp-app-rehydrate'
-  | 'artifact-reopen';
+  | 'artifact-reopen'
+  | 'agent-request';
+
+const observedSourceSchema = z.object({
+  boardId: z.string().min(1),
+  cardId: z.string().min(1),
+  contentRevision: z.number().int().nonnegative().optional(),
+  observedAt: z.iso.datetime().optional(),
+  availability: z.enum(['live', 'cached', 'unavailable']).optional(),
+});
+const recipeSchema = z.object({
+  tool: z.string().max(200),
+  input: z.unknown().optional(),
+  prompt: z.string().max(20000),
+});
 
 export interface CanvasNodeProvenance {
   sourceKind: CanvasNodeProvenanceSourceKind;
@@ -42,6 +59,8 @@ export interface CanvasNodeProvenance {
   refreshStrategy: CanvasNodeRefreshStrategy;
   snapshotContent: boolean;
   syncedAt?: string;
+  sources?: Array<z.infer<typeof observedSourceSchema>>;
+  recipe?: z.infer<typeof recipeSchema>;
   details?: Record<string, unknown>;
 }
 
@@ -65,28 +84,40 @@ function buildMcpToolUri(serverName: string, toolName: string): string {
   return `mcp-tool://${encodeURIComponent(serverName)}/${encodeURIComponent(toolName)}`;
 }
 
-function normalizeExistingProvenance(value: unknown): CanvasNodeProvenance | null {
-  if (!isRecord(value)) return null;
-
-  const sourceKind = pickString(value.sourceKind);
-  const sourceUri = pickString(value.sourceUri);
-  const refreshStrategy = pickString(value.refreshStrategy);
-  if (!sourceKind || !sourceUri || !refreshStrategy) return null;
-
-  const normalized: CanvasNodeProvenance = {
-    sourceKind: sourceKind as CanvasNodeProvenanceSourceKind,
-    sourceUri,
-    refreshStrategy: refreshStrategy as CanvasNodeRefreshStrategy,
-    snapshotContent: value.snapshotContent !== false,
-  };
+const provenanceSchema = z.object({
+  sourceKind: z.enum(['workspace-file', 'webpage-url', 'mcp-tool', 'artifact-file', 'image-url', 'recipe']),
+  sourceUri: z.string().trim().min(1),
+  refreshStrategy: z.enum([
+    'file-watch',
+    'file-read-write',
+    'image-reload',
+    'webpage-refresh',
+    'mcp-app-rehydrate',
+    'artifact-reopen',
+    'agent-request',
+  ]),
+  snapshotContent: z.boolean().default(true),
+  syncedAt: z.string().trim().min(1).optional(),
+  sources: z
+    .array(observedSourceSchema)
+    .max(100)
+    .refine(
+      (sources) =>
+        new Set(sources.map((source) => JSON.stringify([source.boardId, source.cardId]))).size === sources.length,
+      'Source targets must be unique',
+    )
+    .optional(),
+  recipe: recipeSchema.optional(),
+  details: z.record(z.string(), z.unknown()).optional(),
+});
 
-  const syncedAt = pickString(value.syncedAt);
-  if (syncedAt) normalized.syncedAt = syncedAt;
-  if (isRecord(value.details) && Object.keys(value.details).length > 0) {
-    normalized.details = { ...value.details };
+function normalizeExistingProvenance(value: unknown): CanvasNodeProvenance | null {
+  if (value === undefined) return null;
+  const result = z.object({ provenance: provenanceSchema }).safeParse({ provenance: value });
+  if (!result.success) {
+    throw new OperationError(`Invalid node data: ${z.prettifyError(result.error)}`);
   }
-
-  return normalized;
+  return result.data.provenance;
 }
 
 function mergeProvenance(

package/src/server/canvas-serialization.ts

@@ -4,8 +4,10 @@ import type { CanvasAnnotation, CanvasLayout, CanvasNodeState, ViewportState } f
 import { normalizeCanvasNodeData, type CanvasNodeProvenance } from './canvas-provenance.js';
 import { getCanvasNodeKind as getSharedCanvasNodeKind } from '../shared/canvas-node-kind.js';
 import { canOpenNodeAsSurface } from '../shared/surface.js';
+import type { LifecycleQualification } from '../shared/lifecycle-status.js';
 
 export interface SerializedCanvasNode extends CanvasNodeState {
+  qualification?: LifecycleQualification;
   kind: string;
   title: string | null;
   content: string | null;