pmx-canvas 0.8.2 → 0.9.0

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

@@ -0,0 +1,262 @@
+import { z } from 'zod';
+import { canvasState } from '../../canvas-state.js';
+import { categorySchema, folderPropertiesSchema, lifecycleSchema } from '../../knowledge-lifecycle.js';
+import { defineOperation, OperationError, type Operation } from '../types.js';
+import { readTargetBoard } from './boards.js';
+import { lifecycleQualifications, lifecycleSnapshot } from '../../lifecycle-status.js';
+import { memoryKey } from '../../../shared/memory-graph.js';
+import { folderAncestors } from '../../../shared/boards.js';
+import { relationPresetSchema } from '../../../shared/relations.js';
+
+const jsonResult = (result: unknown) => ({
+  content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+});
+const target = { id: z.string().min(1), expectedBoardId: z.string().nullable().optional() };
+
+export const lifecycleOperations: Operation[] = [
+  defineOperation({
+    name: 'knowledge.list',
+    mutates: false,
+    input: z.object({}),
+    inputShape: {},
+    http: { method: 'GET', path: '/api/canvas/knowledge' },
+    mcp: {
+      toolName: 'canvas_knowledge_list',
+      description: 'Read workspace categories and folder properties. No inferred defaults.',
+      formatResult: jsonResult,
+    },
+    handler: () => {
+      const catalog = canvasState.knowledge.list();
+      const paths = new Set([
+        ...catalog.folders.flatMap((folder) => folderAncestors(folder.path)),
+        ...canvasState.listBoards().flatMap((board) => (board.folder ? folderAncestors(board.folder) : [])),
+      ]);
+      return {
+        ok: true,
+        ...catalog,
+        ...lifecycleSnapshot(),
+        resolvedFolders: Object.fromEntries(
+          [...paths].map((path) => [path, canvasState.knowledge.resolve(path, null, catalog)]),
+        ),
+      };
+    },
+  }),
+  defineOperation({
+    name: 'knowledge.category-set',
+    mutates: false,
+    input: z.object({ category: categorySchema }),
+    inputShape: { category: categorySchema },
+    http: { method: 'POST', path: '/api/canvas/knowledge/category' },
+    mcp: {
+      toolName: 'canvas_knowledge_category_set',
+      description: 'Create or replace one workspace category by stable id.',
+      formatResult: jsonResult,
+    },
+    handler: (input, ctx) => {
+      const category = canvasState.knowledge.setCategory(input.category);
+      ctx.emit('knowledge-changed', canvasState.knowledge.list());
+      return { ok: true, category };
+    },
+  }),
+  defineOperation({
+    name: 'knowledge.category-remove',
+    mutates: false,
+    input: z.object({ id: z.string().trim().min(1) }),
+    inputShape: { id: z.string().trim().min(1) },
+    http: { method: 'DELETE', path: '/api/canvas/knowledge/category/:id' },
+    mcp: {
+      toolName: 'canvas_knowledge_category_remove',
+      description:
+        'Delete an unused workspace category by id. Explicit folder assignments, including empty folders, refuse deletion.',
+      formatResult: jsonResult,
+    },
+    handler: (input, ctx) => {
+      const id = canvasState.knowledge.removeCategory(input.id);
+      ctx.emit('knowledge-changed', canvasState.knowledge.list());
+      return { ok: true, id };
+    },
+  }),
+  defineOperation({
+    name: 'knowledge.relation-preset-set',
+    mutates: false,
+    input: z.object({ preset: relationPresetSchema }),
+    inputShape: { preset: relationPresetSchema },
+    http: { method: 'POST', path: '/api/canvas/knowledge/relation-preset' },
+    mcp: {
+      toolName: 'canvas_knowledge_relation_preset_set',
+      description: 'Save one shared workspace relation preset. Existing boards and connections are unchanged.',
+      formatResult: jsonResult,
+    },
+    handler: (input, ctx) => {
+      const preset = canvasState.knowledge.setRelationPreset(input.preset);
+      ctx.emit('knowledge-changed', canvasState.knowledge.list());
+      return { ok: true, preset };
+    },
+  }),
+  defineOperation({
+    name: 'knowledge.relation-preset-remove',
+    mutates: false,
+    input: z.object({ id: z.string().trim().min(1) }),
+    inputShape: { id: z.string().trim().min(1) },
+    http: { method: 'DELETE', path: '/api/canvas/knowledge/relation-preset/:id' },
+    mcp: {
+      toolName: 'canvas_knowledge_relation_preset_remove',
+      description: 'Delete a shared relation preset without changing vocabularies already applied to boards.',
+      formatResult: jsonResult,
+    },
+    handler: (input, ctx) => {
+      const id = canvasState.knowledge.removeRelationPreset(input.id);
+      ctx.emit('knowledge-changed', canvasState.knowledge.list());
+      return { ok: true, id };
+    },
+  }),
+  defineOperation({
+    name: 'knowledge.folder-set',
+    mutates: false,
+    input: folderPropertiesSchema,
+    inputShape: folderPropertiesSchema.shape,
+    http: { method: 'POST', path: '/api/canvas/knowledge/folder' },
+    mcp: {
+      toolName: 'canvas_knowledge_folder_set',
+      description: 'Replace canonical folder properties. Null category inherits; null lifecycle clears the override.',
+      formatResult: jsonResult,
+    },
+    handler: (input, ctx) => {
+      try {
+        const folder = canvasState.knowledge.setFolder(input);
+        ctx.emit('knowledge-changed', canvasState.knowledge.list());
+        return { ok: true, folder };
+      } catch (error) {
+        throw new OperationError(String(error));
+      }
+    },
+  }),
+  defineOperation({
+    name: 'node.lifecycle-get',
+    mutates: false,
+    input: z.object({ id: z.string(), board: z.string().optional() }),
+    inputShape: { id: z.string(), board: z.string().optional() },
+    http: { method: 'GET', path: '/api/canvas/node/:id/lifecycle' },
+    mcp: {
+      toolName: 'canvas_node_lifecycle_get',
+      description:
+        'Read effective category/lifecycle, source folder and audited review history without opening a board.',
+      formatResult: jsonResult,
+    },
+    handler: (input) => {
+      const read = readTargetBoard(input.board);
+      const node = read.layout.nodes.find((n) => n.id === input.id);
+      if (!read.boardId || !node) throw new OperationError('Card not found.', 404);
+      const folder = canvasState.listBoards().find((b) => b.id === read.boardId)?.folder ?? null;
+      return {
+        ok: true,
+        boardId: read.boardId,
+        nodeId: input.id,
+        contentRevision: node.contentRevision ?? 0,
+        ...canvasState.knowledge.resolveCard(folder, node),
+        ...canvasState.knowledge.reviews(read.boardId, input.id),
+        qualification: lifecycleQualifications(Date.now(), [{ boardId: read.boardId, cardId: input.id }])[
+          memoryKey({ boardId: read.boardId, cardId: input.id })
+        ],
+      };
+    },
+  }),
+  defineOperation({
+    name: 'node.lifecycle-set',
+    mutates: true,
+    input: z.object({ ...target, lifecycleOverride: lifecycleSchema.nullable() }),
+    inputShape: { ...target, lifecycleOverride: lifecycleSchema.nullable() },
+    http: { method: 'POST', path: '/api/canvas/node/:id/lifecycle' },
+    mcp: {
+      toolName: 'canvas_node_lifecycle_set',
+      description:
+        'Set a full card lifecycle override, or null to inherit. Never changes category or semantic content revision.',
+      formatResult: jsonResult,
+    },
+    handler: (input) => {
+      canvasState.setNodeLifecycle(input.id, input.lifecycleOverride);
+      return { ok: true };
+    },
+  }),
+  defineOperation({
+    name: 'node.review',
+    mutates: true,
+    input: z.object({
+      ...target,
+      outcome: z.enum(['retain', 'revise', 'externalize', 'retire', 'unresolved']),
+      evidence: z.string(),
+      applied: z.boolean(),
+      expectedContentRevision: z.number().int().nonnegative().optional(),
+      expectedSources: z.record(z.string(), z.number().int().nonnegative().nullable()).optional(),
+    }),
+    inputShape: {
+      ...target,
+      outcome: z.enum(['retain', 'revise', 'externalize', 'retire', 'unresolved']),
+      evidence: z.string(),
+      applied: z.boolean(),
+      expectedSources: z
+        .record(z.string(), z.number().int().nonnegative().nullable())
+        .optional()
+        .describe('Required when validating dependencies: observations from lifecycle-get after checking the sources.'),
+      expectedContentRevision: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Required for evidence-backed validating outcomes; use the revision of the content you checked.'),
+    },
+    http: { method: 'POST', path: '/api/canvas/node/:id/review' },
+    mcp: {
+      toolName: 'canvas_node_review',
+      description:
+        'Audit an outcome. Applied retain/revise/externalize with nonempty evidence and matching expectedContentRevision renew validation. Reviewed content is persisted before evidence. Does not edit content or restore retirement.',
+      formatResult: jsonResult,
+    },
+    handler: (input, ctx) => {
+      if (!canvasState.getNode(input.id) || !canvasState.activeBoardId)
+        throw new OperationError('Card not found.', 404);
+      const observations =
+        lifecycleQualifications()[memoryKey({ boardId: canvasState.activeBoardId, cardId: input.id })]?.observations ??
+        {};
+      const validates =
+        input.applied && input.evidence.trim() && ['retain', 'revise', 'externalize'].includes(input.outcome);
+      if (validates) {
+        const expected = input.expectedSources ?? {};
+        if (
+          Object.keys(expected).length !== Object.keys(observations).length ||
+          Object.entries(observations).some(([key, revision]) => revision === null || expected[key] !== revision)
+        )
+          throw new OperationError(
+            'Sources changed or are unavailable. Check the current sources and pass expectedSources from lifecycle-get.',
+            409,
+          );
+      }
+      const record = canvasState.knowledge.record(canvasState.activeBoardId, input.id, input, observations);
+      ctx.emit('lifecycle-changed', { boardId: canvasState.activeBoardId, nodeId: input.id });
+      return { ok: true, record };
+    },
+  }),
+  defineOperation({
+    name: 'node.lifecycle-restore',
+    mutates: true,
+    input: z.object({ ...target, evidence: z.string() }),
+    inputShape: { ...target, evidence: z.string() },
+    http: { method: 'POST', path: '/api/canvas/node/:id/lifecycle/restore' },
+    mcp: {
+      toolName: 'canvas_node_lifecycle_restore',
+      description: 'Explicitly reverse retirement and audit the restoration. Never validates.',
+      formatResult: jsonResult,
+    },
+    handler: (input, ctx) => {
+      if (!canvasState.getNode(input.id) || !canvasState.activeBoardId)
+        throw new OperationError('Card not found.', 404);
+      const record = canvasState.knowledge.record(canvasState.activeBoardId, input.id, {
+        outcome: 'restore',
+        evidence: input.evidence,
+        applied: true,
+      });
+      ctx.emit('lifecycle-changed', { boardId: canvasState.activeBoardId, nodeId: input.id });
+      return { ok: true, record };
+    },
+  }),
+];

package/src/server/operations/ops/memory-graph.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { memoryGraph, localMemoryGraph, boardMemoryGraph } from '../../memory-graph.js';
+import { defineOperation, OperationError, type Operation } from '../types.js';
+
+const shape = {
+  projection: z
+    .enum(['full', 'boards'])
+    .default('full')
+    .describe('Full board/card graph, or board-only Map summaries with qualified cross-board and missing relations'),
+  focus: z.string().optional().describe('Board ID, board-qualified graph node key, or pins; omit for the library'),
+  depth: z
+    .union([z.number(), z.string().trim().min(1)])
+    .pipe(z.coerce.number<string | number>().int().min(0).max(4))
+    .default(2)
+    .describe('Undirected hops, including membership, 0–4 (default 2)'),
+};
+const schema = z.looseObject(shape);
+export const memoryGraphOperations: Operation[] = [
+  defineOperation({
+    name: 'memory-graph.get',
+    mutates: false,
+    input: schema,
+    inputShape: shape,
+    http: { method: 'GET', path: '/api/canvas/memory-graph' },
+    mcp: {
+      toolName: 'canvas_memory_graph',
+      description:
+        'Explore the same board/card graph Home draws. Summary-only discovery, not full content reads; writes still target the open board.',
+      extraShape: shape,
+      formatResult: (result) => ({ content: [{ type: 'text' as const, text: JSON.stringify(result) }] }),
+    },
+    handler: (input) => {
+      const graph = memoryGraph(input.focus ? 'full' : input.projection);
+      if (
+        input.focus &&
+        input.focus !== 'pins' &&
+        !graph.nodes.some((node) => node.key === input.focus || (node.kind === 'board' && node.boardId === input.focus))
+      ) {
+        throw new OperationError('Graph focus not found. Use a board ID, a qualified node key, or pins.', 404);
+      }
+      const local = localMemoryGraph(graph, input.focus ?? null, input.depth);
+      return input.projection === 'boards' ? boardMemoryGraph(local) : local;
+    },
+  }),
+];

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

@@ -8,12 +8,14 @@
  *
  * This module must never import server.ts or index.ts.
  */
-import { resolve } from 'node:path';
+import { realpathSync, statSync, writeFileSync } from 'node:fs';
+import { extname, isAbsolute, relative, resolve, sep } from 'node:path';
 import { z } from 'zod';
 import { canvasState, type CanvasAnnotation, type CanvasLayout, type CanvasNodeState } from '../../canvas-state.js';
 import {
   addCanvasNode,
   createCanvasGroup,
+  storedCreationTarget,
   buildStructuredNodeUpdate,
   hasStructuredNodeUpdateFields,
   hasTraceNodeDataFields,
@@ -53,6 +55,8 @@ import {
 import { WEBPAGE_NODE_DEFAULT_SIZE, normalizeWebpageUrl } from '../../webpage-node.js';
 import { defineOperation, OperationError, type Operation, type OperationContext } from '../types.js';
 import { readTargetBoard } from './boards.js';
+import { lifecycleQualifications } from '../../lifecycle-status.js';
+import { memoryKey } from '../../../shared/memory-graph.js';
 
 // ── Node types ────────────────────────────────────────────────
 // Single definition site for the basic node-type list: drives the HTTP type
@@ -108,6 +112,11 @@ export function defaultNodeSize(type: string): { width: number; height: number }
 
 // ── Shared helpers (moved from server.ts) ─────────────────────
 
+/** Parent traversal in a relative path, using the path implementation's separator. */
+export function isParentTraversal(path: string, separator: string): boolean {
+  return path === '..' || path.startsWith(`..${separator}`);
+}
+
 export function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -282,6 +291,7 @@ export function compactLayoutPayload(layout: CanvasLayout, pinnedIds: string[]):
       id: edge.id,
       from: edge.from,
       to: edge.to,
+      ...(edge.toBoardId !== undefined ? { toBoardId: edge.toBoardId } : {}),
       type: edge.type,
       ...(edge.label ? { label: edge.label } : {}),
       ...(edge.style ? { style: edge.style } : {}),
@@ -325,7 +335,7 @@ export function createdNodePayloadFromNode(
  */
 export function createBasicCanvasNode(
   body: Record<string, unknown>,
-  options: { fileMode: 'auto' | 'path' },
+  options: { fileMode: 'auto' | 'path'; prepareOnlyNodes?: CanvasNodeState[] },
 ): { node: CanvasNodeState; needsCodeGraphRecompute: boolean; sizeAdjustment?: CanvasSizeAdjustment } {
   const type = typeof body.type === 'string' ? body.type : '';
   const extraData = isRecord(body.data) ? body.data : undefined;
@@ -417,6 +427,7 @@ export function createBasicCanvasNode(
       defaultWidth: defaults.width,
       defaultHeight: defaults.height,
       fileMode: options.fileMode,
+      prepareOnlyNodes: options.prepareOnlyNodes,
     });
     return { node, needsCodeGraphRecompute, ...(sizeAdjustment ? { sizeAdjustment } : {}) };
   } catch (error) {
@@ -445,6 +456,8 @@ export function buildNodePatch(
   }
   if (body.data && typeof body.data === 'object' && !Array.isArray(body.data)) {
     const data = body.data as Record<string, unknown>;
+    if (Object.hasOwn(data, 'lifecycleOverride'))
+      throw new OperationError('Update lifecycle overrides through node.lifecycle-set, not a content patch.');
     const source = data.source;
     const importedSource = source && typeof source === 'object' && 'attachmentId' in source;
     const attachedFileContent =
@@ -575,6 +588,30 @@ export function removeNodeCore(id: string): { needsCodeGraphRecompute: boolean }
 
 // ── node.add ──────────────────────────────────────────────────
 
+/** Explicit creation identity is opt-in, not content-based deduplication. */
+export function createDestinationNode(body: Record<string, unknown>): CanvasNodeState {
+  const { boardId, requestId, fingerprint } = storedCreationTarget(body, 'node.add');
+  const supported = ['markdown', 'status', 'context', 'ledger', 'trace', 'diff', 'mermaid', 'html'];
+  if (!supported.includes(String(body.type)) || body.primitive !== undefined || body.kind !== undefined)
+    throw new OperationError(
+      'destinationBoardId/requestId support static markdown, status, context, ledger, trace, diff, mermaid and plain html creation only.',
+    );
+  const data = isRecord(body.data) ? body.data : {};
+  if (
+    body.intentId !== undefined ||
+    ['children', 'childIds', 'childLayout', 'groupId', 'parentId', 'parentGroup'].some(
+      (key) => body[key] !== undefined || data[key] !== undefined,
+    )
+  )
+    throw new OperationError('Destination/retry creation does not support ghost intents or membership mutations.');
+  return canvasState.createStoredNode(
+    boardId,
+    requestId,
+    fingerprint,
+    (nodes) => createBasicCanvasNode(body, { fileMode: 'auto', prepareOnlyNodes: nodes }).node,
+  );
+}
+
 interface NodeAddResult {
   node: CanvasNodeState;
   extras?: Record<string, unknown>;
@@ -706,6 +743,18 @@ function createGroupNode(body: Record<string, unknown>): NodeAddResult {
 }
 
 const nodeAddShape = {
+  destinationBoardId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Create a static node on this board without opening it. expectedBoardId still guards the ACTIVE board.'),
+  requestId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Persistent logical creation identity. Reuse only for retries with identical input and destination; new identical content needs a new id. Static types only.',
+    ),
   intentId: z
     .string()
     .optional()
@@ -812,25 +861,9 @@ const nodeAddOperation = defineOperation<z.infer<typeof nodeAddSchema>, NodeAddR
   mcp: {
     toolName: 'canvas_add_node',
     description:
-      'Add a basic node to the canvas. Returns the created node with normalized title/content and rendered geometry. Supported here: markdown, status, context, ledger, trace, file, diff, mermaid, image, webpage, mcp-app, html, group. Dedicated routes: json-render -> canvas_render {action:"add-json-render"}, graph -> canvas_render {action:"add-graph"}, web-artifact -> canvas_app {action:"build-artifact"}, external apps -> canvas_app {action:"open-mcp-app"}, groups -> canvas_group {action:"create"}. Call canvas_render {action:"describe-schema"} for the full nodeTypeRouting table.',
+      'Add a basic node to the canvas. Returns the created node with normalized title/content and rendered geometry. Supported here: markdown, board (data.boardId is the target), status, context, ledger, trace, file, diff, mermaid, image, webpage, mcp-app, html, group. Dedicated routes: json-render -> canvas_render {action:"add-json-render"}, graph -> canvas_render {action:"add-graph"}, web-artifact -> canvas_app {action:"build-artifact"}, external apps -> canvas_app {action:"open-mcp-app"}, groups -> canvas_group {action:"create"}. Call canvas_render {action:"describe-schema"} for the full nodeTypeRouting table.',
     extraShape: {
-      type: z
-        .enum([
-          'markdown',
-          'status',
-          'context',
-          'ledger',
-          'trace',
-          'file',
-          'diff',
-          'mermaid',
-          'image',
-          'webpage',
-          'mcp-app',
-          'html',
-          'group',
-        ])
-        .describe('Node type (prefer canvas_group {action:"create"} for groups)'),
+      type: z.enum(NODE_TYPES).describe('Node type (prefer canvas_group {action:"create"} for groups)'),
       children: z
         .array(z.string())
         .optional()
@@ -879,6 +912,8 @@ const nodeAddOperation = defineOperation<z.infer<typeof nodeAddSchema>, NodeAddR
   },
   handler: async (input, ctx) => {
     const body: Record<string, unknown> = input;
+    if (body.destinationBoardId !== undefined || body.requestId !== undefined)
+      return { node: createDestinationNode(body) };
     const type = typeof body.type === 'string' ? body.type : '';
     // Report #50: require a resolvable type rather than silently defaulting to a
     // markdown node — an empty / type-less body created a phantom node before.
@@ -958,23 +993,32 @@ const nodeGetOperation = defineOperation<z.infer<typeof nodeGetSchema>, Serializ
     },
     buildInput: (input) => ({ id: input.id, board: input.board, includeBlobs: true }),
     formatResult: (result, input) => {
-      const node = result as CanvasNodeState;
-      const payload = wantsFullPayload(input) ? serializeCanvasNodeForAgent(node) : compactNodePayload(node);
+      const node = result as SerializedCanvasNode;
+      const payload = {
+        ...(wantsFullPayload(input) ? serializeCanvasNodeForAgent(node) : compactNodePayload(node)),
+        qualification: node.qualification,
+      };
       return { content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }] };
     },
   },
   handler: ({ id, includeBlobs, board }) => {
     const full = includeBlobs === true || includeBlobs === 'true';
+    const qualify = (node: CanvasNodeState, boardId: string | null) => ({
+      ...(full ? serializeCanvasNode(node) : serializeCanvasNodeWithBlobSummaries(node)),
+      qualification: boardId
+        ? lifecycleQualifications(Date.now(), [{ boardId, cardId: id }])[memoryKey({ boardId, cardId: id })]
+        : undefined,
+    });
     if (typeof board === 'string' && board.trim()) {
       const target = readTargetBoard(board, full);
       const node = target.layout.nodes.find((candidate) => candidate.id === id);
       if (!node) throw new OperationError(`Node "${id}" not found on board "${board}".`, 404);
-      return full ? serializeCanvasNode(node) : serializeCanvasNodeWithBlobSummaries(node);
+      return qualify(node, target.boardId);
     }
     const node = full ? canvasState.getNode(id) : canvasState.getNodeForPersistence(id);
     if (!node) throw new OperationError(`Node "${id}" not found.`, 404);
     const responseNode = withContextPinReadState(node);
-    return full ? serializeCanvasNode(responseNode) : serializeCanvasNodeWithBlobSummaries(responseNode);
+    return qualify(responseNode, canvasState.activeBoardId);
   },
 });
 
@@ -983,6 +1027,10 @@ const nodeGetOperation = defineOperation<z.infer<typeof nodeGetSchema>, Serializ
 const nodeUpdateShape = {
   id: z.string().describe('Node ID to update'),
   expectedContentRevision: z.number().int().nonnegative().optional().describe('Reject an edit based on stale content'),
+  persistFile: z
+    .boolean()
+    .optional()
+    .describe('Save file-backed Markdown to disk and card together; requires board and content revision preconditions'),
   intentId: z
     .string()
     .optional()
@@ -1175,6 +1223,35 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
       }
     }
 
+    let markdownPath: string | undefined;
+    if (input.persistFile) {
+      if (
+        existing.type !== 'markdown' ||
+        typeof existing.data.path !== 'string' ||
+        !existing.data.path ||
+        typeof input.content !== 'string' ||
+        input.expectedContentRevision === undefined ||
+        typeof input.expectedBoardId !== 'string'
+      ) {
+        throw new OperationError(
+          'File persistence requires file-backed Markdown, content, expectedBoardId and expectedContentRevision.',
+        );
+      }
+      const data = isRecord(body.data) ? body.data : {};
+      if (Object.keys(data).some((key) => key !== 'rendered'))
+        throw new OperationError('File persistence accepts only data.rendered; update metadata separately.');
+      markdownPath = realpathSync(resolve(canvasState.getWorkspaceRoot(), existing.data.path));
+      const workspacePath = relative(realpathSync(canvasState.getWorkspaceRoot()), markdownPath);
+      if (
+        isParentTraversal(workspacePath, sep) ||
+        isAbsolute(workspacePath) ||
+        extname(markdownPath).toLowerCase() !== '.md' ||
+        !statSync(markdownPath).isFile()
+      ) {
+        throw new OperationError('File persistence requires a Markdown file inside the workspace.');
+      }
+      body = { ...body, content: input.content.replace(/\r\n?/g, '\n') };
+    }
     const { patch, groupChildIds } = buildNodePatch(existing, body);
     const prevPath = existing.type === 'file' && typeof existing.data.path === 'string' ? existing.data.path : null;
     if (nextFilePath && nextFileContent && patch.data) {
@@ -1186,6 +1263,12 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
       applyFileContentToNodeData(data, nextFileContent);
       patch.data = data;
     }
+    if (markdownPath && patch.data) {
+      // No await between revision validation, disk persistence and the card
+      // update: a refused/stale attempt must not write either half.
+      writeFileSync(markdownPath, String(patch.data.content), 'utf8');
+      patch.data.savedAt = new Date().toISOString();
+    }
     canvasState.updateNode(id, patch);
     if (groupChildIds !== undefined && !setGroupChildrenFromApi(id, groupChildIds)) {
       throw new OperationError(`Group "${id}" not found.`, 404);