pmx-canvas 0.8.0 → 0.9.0

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

@@ -13,7 +13,7 @@
  * This module must never import server.ts or index.ts.
  */
 import { z } from 'zod';
-import { tourSchema, derivedTour } from '../../../shared/tour.js';
+import { tourSchema, derivedTour, rectSchema, cameraSchema, tourStopSchema } from '../../../shared/tour.js';
 import { canvasState } from '../../canvas-state.js';
 import {
   arrangeCanvasNodes,
@@ -23,6 +23,7 @@ import {
   setClientViewportSize,
 } from '../../canvas-operations.js';
 import { validateCanvasLayout } from '../../canvas-validation.js';
+import { exitTour, goToTourStop, moveCamera, tourPosition } from '../../tour-control.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { closeNodeAppSession, isRecord } from './nodes.js';
 
@@ -241,8 +242,13 @@ const viewportSetShape = {
     .optional()
     .describe('World point {x, y} to centre in the canvas area (instead of x/y); uses scale or the current zoom'),
   recordHistory: z.unknown().optional().describe('Pass false to skip the undo-history entry'),
+  clientId: z.string().min(1).max(128).optional().describe('Originating workbench tab; echoed with camera updates'),
   clientWidth: z.unknown().optional().describe("The reporting client's window width in CSS pixels"),
   clientHeight: z.unknown().optional().describe("The reporting client's window height in CSS pixels"),
+  clientInsets: z
+    .object({ top: z.number().finite().nonnegative(), bottom: z.number().finite().nonnegative() })
+    .optional()
+    .describe('Measured floating chrome above and below the canvas, in CSS pixels'),
 };
 
 const viewportSetSchema = z.looseObject(viewportSetShape);
@@ -262,7 +268,7 @@ const viewportSetOperation = defineOperation<z.infer<typeof viewportSetSchema>,
     // The browser piggybacks its real window size here so a later agent `fit`
     // sizes to the human's actual window instead of a hardcoded 1440x900
     // (0.4.6 orb feedback #2).
-    setClientViewportSize(body.clientWidth, body.clientHeight);
+    setClientViewportSize(body.clientWidth, body.clientHeight, input.clientInsets);
     // A size-only report is not a camera command. Echoing the stored camera
     // here would cancel an in-flight browser focus with its stale fallback.
     const center = body.center;
@@ -292,7 +298,10 @@ const viewportSetOperation = defineOperation<z.infer<typeof viewportSetSchema>,
     } else {
       canvasState.setViewport(next);
     }
-    ctx.emit('canvas-viewport-update', { viewport: canvasState.viewport });
+    ctx.emit('canvas-viewport-update', {
+      viewport: canvasState.viewport,
+      ...(input.clientId ? { clientId: input.clientId } : {}),
+    });
     return { ok: true, viewport: canvasState.viewport };
   },
 });
@@ -323,12 +332,97 @@ const tourGetOperation = defineOperation({
   handler: () => ({
     tour: canvasState.getTour() ?? derivedTour(canvasState.getLayout().nodes),
     derived: !canvasState.getTour(),
+    position: tourPosition(),
   }),
 });
 
+// ── tour.go / tour.exit / camera.move ────────────────────────
+// Navigation only (mutates: false, PRESENCE_EXEMPT_OPS): no undo entry, no
+// writer activity, no scope-fence check. The browser animates.
+
+const tourGoShape = {
+  stop: z.number().int().nonnegative().optional().describe('Zero-based stop index to go to'),
+  step: z.enum(['next', 'previous']).optional().describe('Step relative to the current stop (clamped at the ends)'),
+  present: z
+    .boolean()
+    .optional()
+    .describe(
+      'Start presenting in viewers that are not presenting yet (default true; false only moves presenting viewers)',
+    ),
+};
+const tourGoOperation = defineOperation({
+  name: 'tour.go',
+  mutates: false,
+  input: z.object(tourGoShape),
+  inputShape: tourGoShape,
+  http: { method: 'POST', path: '/api/canvas/tour/go' },
+  mcp: {
+    toolName: 'canvas_tour_go',
+    description: 'Go to a tour stop (index, next or previous) in presenting viewers.',
+  },
+  handler: (input, ctx) => {
+    if ((input.stop === undefined) === (input.step === undefined)) {
+      throw new OperationError('Give exactly one of stop (index) or step ("next" | "previous").');
+    }
+    const result = goToTourStop(input.stop ?? (input.step as 'next' | 'previous'));
+    ctx.emit('canvas-tour-step', { ...result, present: input.present !== false });
+    return { ok: true, ...result };
+  },
+});
+
+const tourExitOperation = defineOperation({
+  name: 'tour.exit',
+  mutates: false,
+  input: z.object({}),
+  inputShape: {},
+  http: { method: 'POST', path: '/api/canvas/tour/exit' },
+  mcp: { toolName: 'canvas_tour_exit', description: 'Leave presentation in every viewer.' },
+  handler: (_input, ctx) => {
+    exitTour();
+    ctx.emit('canvas-tour-exit', {});
+    return { ok: true };
+  },
+});
+
+const cameraMoveShape = {
+  nodeId: z.string().optional().describe('Node or group id to frame'),
+  rect: rectSchema.optional().describe('World-space box { x, y, width, height } to frame'),
+  viewport: cameraSchema.optional().describe('Exact screen-space camera { x, y, scale }'),
+  duration: tourStopSchema.shape.duration.describe('Move time in seconds (default 1; 0 jumps)'),
+  easing: tourStopSchema.shape.easing.describe('linear | ease-in-out (default) | ease-out'),
+  padding: tourStopSchema.shape.padding.describe('Screen pixels around a node/rect target (default 40)'),
+  pullback: tourStopSchema.shape.pullback.describe('Mid-move log-zoom pull-back, 0–4 (default 0)'),
+};
+const cameraMoveOperation = defineOperation({
+  name: 'camera.move',
+  mutates: false,
+  input: z.object(cameraMoveShape),
+  inputShape: cameraMoveShape,
+  http: { method: 'POST', path: '/api/canvas/camera/move' },
+  mcp: {
+    toolName: 'canvas_camera_move',
+    description: 'Ease the camera to a node, a world rect or an exact viewport over a duration.',
+  },
+  handler: (input, ctx) => {
+    const { nodeId, rect, viewport, ...options } = input;
+    const targets = [
+      ...(nodeId !== undefined ? [{ nodeId }] : []),
+      ...(rect !== undefined ? [{ rect }] : []),
+      ...(viewport !== undefined ? [{ viewport }] : []),
+    ];
+    if (targets.length !== 1) throw new OperationError('Give exactly one of nodeId, rect or viewport.');
+    const result = moveCamera({ target: targets[0], ...options });
+    ctx.emit('canvas-camera-move', result);
+    return { ok: true, ...result };
+  },
+});
+
 export const viewportOperations: Operation[] = [
   tourSetOperation,
   tourGetOperation,
+  tourGoOperation,
+  tourExitOperation,
+  cameraMoveOperation,
   arrangeOperation,
   focusOperation,
   fitOperation,

package/src/server/operations/registry.ts

@@ -15,7 +15,8 @@ import { withCurrentActor } from '../attribution.js';
 import { withoutExternalMcp } from '../mcp-app-runtime.js';
 import { agentPresence, describeWrite } from '../agent-presence.js';
 import { checkScopeFence, checkScopeOwnership, describeOpTarget } from '../scope-fence.js';
-import { CONTEXT_READ_OPS, contextReadFromPayload } from '../context-reads.js';
+import { CONTEXT_READ_OPS, contextReadFromPayload, pinnedBoardReads, graphReads } from '../context-reads.js';
+import type { MemoryGraph } from '../../shared/memory-graph.js';
 import { openBoardForWrite } from '../canvas-operations.js';
 import { boardsPayload } from './ops/boards.js';
 import type { PmxAxIntent, PmxAxIntentKind } from '../../shared/ax-intent.js';
@@ -48,6 +49,10 @@ export function setOperationEventEmitter(emitter: OperationEventEmitter | null):
   operationEventEmitter = emitter;
 }
 
+export function getOperationEventEmitter(): OperationEventEmitter | null {
+  return operationEventEmitter;
+}
+
 // Batch suppression belongs to its async call chain, never concurrent human
 // operations (especially board switches while a batch waits on the network).
 const suppressedEmits = new AsyncLocalStorage<boolean>();
@@ -190,6 +195,7 @@ function autoGhostInput(name: string, rawInput: unknown, kind: string): Record<s
       return typeof body.id === 'string' ? { ...base, nodeId: body.id } : null;
     case 'connect': {
       if (typeof body.from !== 'string' || typeof body.to !== 'string') return null;
+      if (body.toBoardId && body.toBoardId !== canvasState.activeBoardId) return null;
       const edgeType = typeof body.type === 'string' && AUTO_GHOST_EDGE_TYPES.has(body.type) ? body.type : 'flow';
       return { ...base, nodeType: undefined, edge: { from: body.from, to: body.to, type: edgeType } };
     }
@@ -252,7 +258,10 @@ function heldByHuman(name: string, rawInput: unknown): { nodeId: string; name: s
   const locked = humanPresence.lockedNodes();
   if (locked.size === 0) return null;
   const input = asRecord(rawInput);
-  const ids = [input.id, input.nodeId, input.groupId, input.from, input.to].filter(isString);
+  const foreignTarget = name === 'edge.add' && input.toBoardId && input.toBoardId !== canvasState.activeBoardId;
+  const ids = [input.id, input.nodeId, input.groupId, input.from, ...(foreignTarget ? [] : [input.to])].filter(
+    isString,
+  );
   if (name === 'canvas.apply-updates' || name === 'node.update') {
     // Fence and lock targets must agree, including translated children and
     // the automatic parent frames re-fitted by a child write.
@@ -312,6 +321,7 @@ function touchedNodeId(rawInput: unknown, result: unknown): string | null {
  * and re-touching after a `session-end` would resurrect the writer).
  */
 const PRESENCE_EXEMPT_OPS = new Set([
+  'settings.set',
   'ax.presence.set',
   'ax.presence.get',
   'ax.activity.ingest',
@@ -330,6 +340,9 @@ const PRESENCE_EXEMPT_OPS = new Set([
   'viewport.set',
   'view.fit',
   'node.focus',
+  'tour.go',
+  'tour.exit',
+  'camera.move',
   'ax.focus.set',
 ]);
 
@@ -391,8 +404,10 @@ export async function executeOperation(
       ...(typeof inputAgentId === 'string' && inputAgentId.trim() ? { agentId: inputAgentId.trim() } : {}),
     },
     async () => {
-      const recordRead = CONTEXT_READ_OPS.has(name) && !meta.fromWorkbench && !meta.proxiedRead;
       const input = asRecord(rawInput);
+      const deliversContext =
+        name !== 'node.get' || (input.contextDelivery !== false && input.contextDelivery !== 'false');
+      const recordRead = CONTEXT_READ_OPS.has(name) && deliversContext && !meta.fromWorkbench && !meta.proxiedRead;
       const requestedBoard =
         recordRead && 'board' in getOperation(name).inputShape && isString(input.board) && input.board.trim()
           ? input.board.trim()
@@ -410,28 +425,32 @@ export async function executeOperation(
         ? withoutExternalMcp(run)
         : run());
       if (recordRead) {
-        canvasState.recordContextRead(
-          contextReadFromPayload(
-            {
-              channel: 'operation',
-              resource: name,
-              source: meta.source ?? 'api',
-              consumer: isString(input.consumer) && input.consumer.trim() ? input.consumer.trim() : null,
-              agentId: isString(input.agentId) && input.agentId.trim() ? input.agentId.trim() : null,
-              pinnedNodeIds: readPins,
-            },
-            result,
-          ),
-          readBoardId,
-        );
+        const base = {
+          channel: 'operation' as const,
+          resource: name,
+          source: meta.source ?? 'api',
+          consumer: isString(input.consumer) && input.consumer.trim() ? input.consumer.trim() : null,
+          agentId: isString(input.agentId) && input.agentId.trim() ? input.agentId.trim() : null,
+        };
+        if (name === 'memory-graph.get') {
+          for (const read of graphReads(base, result as MemoryGraph)) canvasState.recordContextRead(read, read.boardId);
+        } else {
+          canvasState.recordContextRead(
+            contextReadFromPayload({ ...base, pinnedNodeIds: readPins }, result),
+            readBoardId,
+          );
+        }
+        if (name === 'context.get') {
+          for (const read of pinnedBoardReads(base, result)) canvasState.recordContextRead(read, read.boardId);
+        }
       }
       return result;
     },
   );
 }
 
-/** Board deletion and import review actions require the human in the workbench. */
-const HUMAN_ONLY_OPS = new Set(['board.delete', 'import.request', 'import.cancel', 'import.commit']);
+/** Workspace preferences, board deletion and import review require the human workbench. */
+const HUMAN_ONLY_OPS = new Set(['settings.set', 'board.delete', 'import.request', 'import.cancel', 'import.commit']);
 const TRUSTED_HUMAN_ONLY_OPS = new Set(['board.delete', 'import.request', 'import.cancel', 'import.commit']);
 
 /**
@@ -461,6 +480,9 @@ function needsOpenBoard(op: Operation): boolean {
 
 async function executeOperationInner(name: string, rawInput: unknown, meta: ExecuteOperationMeta): Promise<unknown> {
   const op = getOperation(name);
+  const storedCreation =
+    ['node.add', 'group.create', 'edge.add'].includes(name) &&
+    (asRecord(rawInput).destinationBoardId !== undefined || asRecord(rawInput).requestId !== undefined);
   if (HUMAN_ONLY_OPS.has(name) && !meta.fromWorkbench) {
     throw new OperationError('This action requires the human in the workbench.', 403);
   }
@@ -481,7 +503,7 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
   if (name === 'node.add' && typeof capturedBoard === 'string' && capturedBoard !== canvasState.activeBoardId) {
     throw new OperationError('The board changed while the file was loading.', 409);
   }
-  if (!canvasState.activeBoardId && needsOpenBoard(op)) {
+  if (!canvasState.activeBoardId && needsOpenBoard(op) && !storedCreation) {
     openBoardForWrite();
     if (canvasState.activeBoardId) emitOperationEvent('boards-changed', boardsPayload());
   }
@@ -493,11 +515,19 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
     // carries one, else its transport/source label.
     const rawAgentId = asRecord(rawInput).agentId;
     const writerKey = typeof rawAgentId === 'string' && rawAgentId.trim() ? rawAgentId.trim() : (meta.source ?? 'api');
-    const refusal = op.mutates
-      ? checkScopeFence(op, rawInput, writerKey)
-      : name === 'ax.policy.set'
-        ? checkScopeOwnership(rawInput, writerKey)
-        : null;
+    const refusal =
+      op.mutates ||
+      name === 'knowledge.category-set' ||
+      name === 'knowledge.category-remove' ||
+      name === 'knowledge.relation-preset-set' ||
+      name === 'knowledge.relation-preset-remove' ||
+      name === 'knowledge.folder-set' ||
+      (name === 'board.update' &&
+        ['folder', 'relationVocabulary'].some((key) => Object.hasOwn(asRecord(rawInput), key)))
+        ? checkScopeFence(op, rawInput, writerKey)
+        : name === 'ax.policy.set'
+          ? checkScopeOwnership(rawInput, writerKey)
+          : null;
     if (refusal) throw new OperationError(`Outside the agent scope: ${refusal}`, 403);
     // User wins (item 6): a node a human is holding right now is not the
     // agent's to change — refuse with 409 so the agent requeues the edit.
@@ -511,6 +541,16 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
       }
     }
   }
+  if (storedCreation) {
+    const revision = canvasState.getContentRevision().revision;
+    const result = await op.execute(rawInput, operationContext);
+    const destination = asRecord(rawInput).destinationBoardId ?? canvasState.activeBoardId;
+    if (destination === canvasState.activeBoardId || revision !== canvasState.getContentRevision().revision)
+      emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    emitOperationEvent('boards-changed', boardsPayload());
+    if (destination === canvasState.activeBoardId) notePresence(name, rawInput, meta, op, result);
+    return result;
+  }
   const linkedId = linkedIntentId(rawInput);
   // A ghost that expired QUIETLY (no veto) does not block its mutation — the
   // write proceeds unlinked (and takes the auto-ghost path below). Vetoed and
@@ -578,8 +618,19 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
     }
   }
 
+  const beforeBoard = canvasState.activeBoardId;
+  const beforeRevision =
+    name === 'board.create-from' || name === 'board.delete' ? canvasState.getContentRevision().revision : null;
   const result = await op.execute(rawInput, operationContext);
-  if (op.mutates) emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  // Library writes can invalidate relations on the open board without being
+  // layout mutations themselves. Publish those clocks once, after the write.
+  if (
+    op.mutates ||
+    (beforeRevision !== null &&
+      beforeBoard === canvasState.activeBoardId &&
+      beforeRevision !== canvasState.getContentRevision().revision)
+  )
+    emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   notePresence(name, rawInput, meta, op, result);
   return result;
 }

package/src/server/placement.ts

@@ -14,6 +14,35 @@ const GROUP_LAYOUT_MIN_ROW_WIDTH = 1200;
 const GROUP_LAYOUT_MAX_ROW_WIDTH = 1800;
 const GROUP_TO_GROUP_GAP = 48;
 
+/** Pack members inside an explicitly sized frame without changing that frame. */
+export function computeManualGroupLayout<T extends CanvasPlacementRect & { id: string }>(
+  children: T[],
+  frame: CanvasPlacementRect,
+  layout: 'grid' | 'column' | 'flow',
+): Map<string, { x: number; y: number }> {
+  const positions = new Map<string, { x: number; y: number }>();
+  const left = frame.position.x + GROUP_PAD;
+  const top = frame.position.y + GROUP_TITLEBAR_HEIGHT + GROUP_PAD;
+  const right = frame.position.x + frame.size.width - GROUP_PAD;
+  let x = left,
+    y = top,
+    rowHeight = 0;
+  for (const child of [...children].sort((a, b) => a.position.y - b.position.y || a.position.x - b.position.x)) {
+    if (layout === 'grid' && x > left && x + child.size.width > right) {
+      x = left;
+      y += rowHeight + 24;
+      rowHeight = 0;
+    }
+    positions.set(child.id, { x: layout === 'column' ? left : x, y: layout === 'flow' ? top : y });
+    if (layout === 'column') y += child.size.height + 24;
+    else {
+      x += child.size.width + 24;
+      rowHeight = Math.max(rowHeight, child.size.height);
+    }
+  }
+  return positions;
+}
+
 /**
  * Compute bounding box for a group that should contain the given child rects.
  * Returns position and size with padding, or null if no valid children.

package/src/server/scope-fence.ts

@@ -24,8 +24,11 @@
  * authentication boundary.
  */
 import { type FenceRect, fenceRectFromNodes } from '../shared/scope-fence.js';
+import { normalizeBoardFolder } from '../shared/boards.js';
 import { canvasState } from './canvas-state.js';
 import { resolvePatchGeometry, validCanvasNodeUpdates } from './canvas-geometry.js';
+import { normalizeAxPolicy, type PmxAxPolicy } from './ax-state.js';
+import { categorySchema, folderPropertiesSchema } from './knowledge-lifecycle.js';
 import type { Operation } from './operations/types.js';
 
 /** Bounding box of the fenced nodes plus padding; null when none of them exist. */
@@ -55,8 +58,12 @@ function inside(rect: FenceRect, x: number, y: number): boolean {
 }
 
 /** Returns a human-readable refusal, or null when the target is inside the fence. */
-export function checkFenceTarget(target: FenceTarget, opName: string, writerKey?: string): string | null {
-  const policy = canvasState.getPolicy();
+export function checkFenceTarget(
+  target: FenceTarget,
+  opName: string,
+  writerKey?: string,
+  policy: PmxAxPolicy = canvasState.getPolicy(),
+): string | null {
   // Per-agent territory (fleet orchestration) overrides the global fence for
   // that writer; writers without a territory fall under the global fence.
   const territory = writerKey ? policy.agentScopes[writerKey] : undefined;
@@ -154,13 +161,24 @@ function createTarget(input: Record<string, unknown>, extraNodeIds: string[] = [
 }
 
 /** Ops that rewrite the whole board — never allowed under a fence. */
-const BOARD_WIDE_OPS = new Set(['arrange', 'canvas.clear', 'snapshot.restore', 'render.workboard', 'tour.set']);
+const BOARD_WIDE_OPS = new Set([
+  'arrange',
+  'canvas.clear',
+  'snapshot.restore',
+  'render.workboard',
+  'tour.set',
+  'board.update',
+]);
 
 /** Describe what a registry op would write, in fence terms. */
 export function describeOpTarget(op: Operation, rawInput: unknown): FenceTarget {
   const input = asRecord(rawInput);
   if (BOARD_WIDE_OPS.has(op.name)) return { boardWide: true };
   switch (op.name) {
+    case 'node.lifecycle-set':
+    case 'node.review':
+    case 'node.lifecycle-restore':
+      return { nodeIds: [str(input.id)] };
     case 'canvas.apply-updates':
       return applyUpdatesTarget(input);
     case 'node.update': {
@@ -177,6 +195,8 @@ export function describeOpTarget(op: Operation, rawInput: unknown): FenceTarget
     }
     case 'node.remove':
       return { nodeIds: [str(input.id)] };
+    case 'snapshot.restore-node':
+      return { nodeIds: [str(input.nodeId)] };
     case 'node.add':
       return createTarget(input, input.type === 'group' ? groupChildren(input) : []);
     case 'jsonrender.add':
@@ -188,11 +208,16 @@ export function describeOpTarget(op: Operation, rawInput: unknown): FenceTarget
     case 'edge.add':
       // Search-resolved endpoints (`fromSearch`/`toSearch`) cannot be checked
       // before resolution and so read as '' — refused, not bypassed.
-      return { nodeIds: [str(input.from), str(input.to)] };
+      return {
+        nodeIds:
+          input.toBoardId && input.toBoardId !== canvasState.activeBoardId
+            ? [str(input.from)]
+            : [str(input.from), str(input.to)],
+      };
     case 'edge.remove': {
       const id = str(input.id) || str(input.edge_id);
       const edge = canvasState.getEdges().find((entry) => entry.id === id);
-      return edge ? { nodeIds: [edge.from, edge.to] } : {}; // missing edge: the op 404s on its own
+      return edge ? { nodeIds: edge.toBoardId ? [edge.from] : [edge.from, edge.to] } : {}; // missing edge: the op 404s on its own
     }
     case 'group.create':
       return { nodeIds: stringList(input.childIds ?? input.children) };
@@ -228,7 +253,54 @@ export function describeOpTarget(op: Operation, rawInput: unknown): FenceTarget
 
 /** Registry entry point: refusal text or null. Only call for mutating, agent-originated ops. */
 export function checkScopeFence(op: Operation, rawInput: unknown, writerKey?: string): string | null {
-  return checkFenceTarget(describeOpTarget(op, rawInput), op.name, writerKey);
+  const target = describeOpTarget(op, rawInput);
+  const activeRefusal = checkFenceTarget(target, op.name, writerKey);
+  if (activeRefusal) return activeRefusal;
+  // Re-filing changes every card's lifecycle inheritance, even on a closed
+  // board. Its stored policy applies without opening it or dropping the active fence.
+  const input = asRecord(rawInput);
+  if (op.name === 'board.update' && typeof input.id === 'string' && input.id !== canvasState.activeBoardId) {
+    const board = canvasState.readBoard(input.id, false);
+    return checkFenceTarget(target, op.name, writerKey, normalizeAxPolicy(board?.state.ax?.policy));
+  }
+  if (op.name === 'knowledge.category-set' || op.name === 'knowledge.folder-set') {
+    const before = canvasState.knowledge.list();
+    const after = { ...before };
+    if (op.name === 'knowledge.category-set') {
+      const parsed = categorySchema.safeParse(input.category);
+      if (!parsed.success) return null; // The operation reports invalid input without writing.
+      const category = parsed.data;
+      after.categories = [...before.categories.filter((entry) => entry.id !== category.id), category];
+    } else {
+      const parsed = folderPropertiesSchema.safeParse(rawInput);
+      if (!parsed.success) return null;
+      const folder = parsed.data;
+      let path: string | null;
+      try {
+        path = normalizeBoardFolder(folder.path);
+      } catch {
+        return null; // Folder validation belongs to the operation handler.
+      }
+      if (!path) return null;
+      after.folders = [...before.folders.filter((entry) => entry.path !== path), { ...folder, path }];
+    }
+    for (const board of canvasState.listBoards()) {
+      if (
+        JSON.stringify(canvasState.knowledge.resolve(board.folder, null, before)) ===
+        JSON.stringify(canvasState.knowledge.resolve(board.folder, null, after))
+      )
+        continue;
+      const stored = canvasState.readBoard(board.id, false);
+      const refusal = checkFenceTarget(
+        { boardWide: true },
+        op.name,
+        writerKey,
+        normalizeAxPolicy(stored?.state.ax?.policy),
+      );
+      if (refusal) return refusal;
+    }
+  }
+  return null;
 }
 
 /**