pmx-canvas 0.3.4 → 0.4.0

package/src/server/canvas-state.ts

@@ -7,20 +7,13 @@
  *
  * Persistence: canvas state auto-saves to `.pmx-canvas/canvas.db` (SQLite WAL mode)
  * in the workspace root on every mutation (debounced). Auto-loads on `loadFromDisk()`.
- * Legacy `.pmx-canvas/state.json` is auto-migrated on first boot.
+ * Legacy pre-0.2 formats (`.pmx-canvas/state.json`, `.pmx-canvas.json`,
+ * `.pmx-canvas-snapshots/`, loose blob files) are no longer imported as of 0.4.0 —
+ * the one-shot boot migration into SQLite was retired.
  */
 
 import { createHash } from 'node:crypto';
-import {
-  existsSync,
-  readFileSync,
-  writeFileSync,
-  mkdirSync,
-  readdirSync,
-  renameSync,
-  rmSync,
-  unlinkSync,
-} from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
 import { isAbsolute, join, dirname, relative } from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
 import { normalizeCanvasNodeData } from './canvas-provenance.js';
@@ -34,7 +27,6 @@ import {
   deleteSnapshotFromDB,
   writeBlobToDB,
   readBlobFromDB,
-  hasBlobInDB,
   isDbPopulated,
   checkpointCanvasDb,
   finalizeCanvasDbForClose,
@@ -97,12 +89,9 @@ function normalizeSnapshotTimestamp(value: string | undefined): string | undefin
 }
 
 export const PMX_CANVAS_DIR = '.pmx-canvas';
-const STATE_FILENAME = 'state.json';
 const DB_FILENAME = 'canvas.db';
 const SNAPSHOTS_SUBDIR = 'snapshots';
 const BLOBS_SUBDIR = 'blobs';
-const LEGACY_STATE_FILENAME = '.pmx-canvas.json';
-const LEGACY_SNAPSHOTS_DIR = '.pmx-canvas-snapshots';
 const SAVE_DEBOUNCE_MS = 500;
 const BLOB_JSON_THRESHOLD_BYTES = Number(process.env.PMX_CANVAS_BLOB_THRESHOLD_BYTES ?? '2048');
 const BLOB_DATA_FIELDS = new Set([
@@ -393,10 +382,23 @@ class CanvasStateManager {
   }
 
   // ── Mutation recorder (for undo/redo history) ─────────────
+  //
+  // Single slot BY DESIGN, last-write-wins (plan-009 L5): the only logical
+  // consumer is the `mutationHistory` singleton, wired by `startCanvasServer()`
+  // (server.ts) on every fresh start. A listener LIST here would record every
+  // mutation twice into the history ring (breaking undo) if a second wire ever
+  // appeared, so keep it a single slot and wire recorders in one place only.
   private _mutationRecorder: ((info: MutationRecordInfo) => void) | null = null;
+  // The ONE recording-suppression counter (depth-counted so nested suppressed
+  // scopes compose). Two related mechanisms are deliberately NOT merged into
+  // it: `mutationHistory._replaying` guards direct `record()` calls during
+  // undo/redo replay, and the operation registry's `suppressEmitDepth`
+  // suppresses SSE emits during meta-ops (canvas.batch) — whose sub-ops must
+  // still record history, just as undo/redo still emits SSE while recording is
+  // suppressed here. The three counters are active at different times.
   private _suppressRecordingDepth = 0;
 
-  /** Register a mutation recorder. Used by mutation-history to capture undo/redo closures. */
+  /** Register THE mutation recorder (single slot, last-write-wins — see note above). */
   onMutation(cb: (info: MutationRecordInfo) => void): void {
     this._mutationRecorder = cb;
   }
@@ -617,7 +619,6 @@ class CanvasStateManager {
   }
 
   // ── Persistence ────────────────────────────────────────────
-  private _stateFilePath: string | null = null;
   private _db: import('bun:sqlite').Database | null = null;
   private _saveTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -630,9 +631,9 @@ class CanvasStateManager {
   setWorkspaceRoot(workspaceRoot: string): void {
     this.close();
     this._workspaceRoot = workspaceRoot;
-    this.migrateLegacyLayout(workspaceRoot);
 
-    // Determine DB path
+    // Determine DB path. PMX_CANVAS_DB_PATH wins; PMX_CANVAS_STATE_FILE is
+    // honored only as a legacy alias when it points at a `.db` file.
     const dbOverride = (process.env.PMX_CANVAS_DB_PATH ?? '').trim();
     const stateFileOverride = (process.env.PMX_CANVAS_STATE_FILE ?? '').trim();
     let dbPath: string;
@@ -643,16 +644,20 @@ class CanvasStateManager {
     } else {
       dbPath = join(workspaceRoot, PMX_CANVAS_DIR, DB_FILENAME);
     }
+    if (stateFileOverride && !stateFileOverride.endsWith('.db')) {
+      logCanvasStateWarning(
+        'PMX_CANVAS_STATE_FILE ignored',
+        'legacy JSON state files are no longer supported as of 0.4.0 — use PMX_CANVAS_DB_PATH',
+        { stateFileOverride },
+      );
+    }
 
-    // Keep legacy _stateFilePath for JSON migration detection
-    this._stateFilePath =
-      stateFileOverride && !stateFileOverride.endsWith('.db')
-        ? stateFileOverride
-        : join(workspaceRoot, PMX_CANVAS_DIR, STATE_FILENAME);
-
+    // Legacy pre-0.2 formats (`.pmx-canvas/state.json`, `.pmx-canvas.json`,
+    // `.pmx-canvas-snapshots/`, loose blob files) are no longer imported as of
+    // 0.4.0 — the one-shot boot migration that copied them into SQLite and
+    // renamed the originals to `.bak` was retired.
     try {
       this._db = openCanvasDb(dbPath);
-      this.migrateJsonToSqlite();
     } catch (error) {
       logCanvasStateWarning('open canvas database failed', error, { dbPath });
     }
@@ -745,7 +750,7 @@ class CanvasStateManager {
       }
     }
 
-    // Fallback to filesystem (for legacy blobs not yet migrated)
+    // Fallback to filesystem (legacy on-disk blobs are still readable in place)
     const filePath = this.resolveBlobPath(ref);
     if (!filePath) return ref;
     try {
@@ -804,112 +809,6 @@ class CanvasStateManager {
     };
   }
 
-  /**
-   * One-time migration: rename files from the pre-consolidation layout
-   * (`.pmx-canvas.json` + `.pmx-canvas-snapshots/`) into `.pmx-canvas/`.
-   * No-op when the new layout already exists.
-   */
-  private migrateLegacyLayout(workspaceRoot: string): void {
-    const newDir = join(workspaceRoot, PMX_CANVAS_DIR);
-    const legacyState = join(workspaceRoot, LEGACY_STATE_FILENAME);
-    const newState = join(newDir, STATE_FILENAME);
-    const legacySnapshots = join(workspaceRoot, LEGACY_SNAPSHOTS_DIR);
-    const newSnapshots = join(newDir, SNAPSHOTS_SUBDIR);
-
-    try {
-      if (existsSync(legacyState) && !existsSync(newState)) {
-        mkdirSync(newDir, { recursive: true });
-        renameSync(legacyState, newState);
-      }
-      if (existsSync(legacySnapshots) && !existsSync(newSnapshots)) {
-        mkdirSync(newDir, { recursive: true });
-        renameSync(legacySnapshots, newSnapshots);
-      }
-    } catch (error) {
-      logCanvasStateWarning('legacy layout migration failed', error, {
-        workspaceRoot,
-      });
-    }
-  }
-
-  /**
-   * One-time migration: import state.json + snapshot JSON files + blob files
-   * into the SQLite database. Renames originals to `.bak`.
-   */
-  private migrateJsonToSqlite(): void {
-    if (!this._db || !this._stateFilePath) return;
-    const db = this._db;
-
-    if (isDbPopulated(this._db)) return; // DB already initialized
-
-    if (existsSync(this._stateFilePath)) {
-      try {
-        const raw = readFileSync(this._stateFilePath, 'utf-8');
-        const parsed = JSON.parse(raw) as PersistedCanvasState;
-        if (parsed && parsed.version === 1) {
-          saveStateToDB(db, parsed);
-          renameSync(this._stateFilePath, `${this._stateFilePath}.bak`);
-        }
-      } catch (error) {
-        logCanvasStateWarning('migrate state.json to sqlite failed', error, {
-          path: this._stateFilePath,
-        });
-      }
-    }
-
-    // Migrate snapshot JSON files
-    const snapshotsDir = this.snapshotsDir;
-    if (snapshotsDir && existsSync(snapshotsDir)) {
-      try {
-        const files = readdirSync(snapshotsDir).filter((f) => f.endsWith('.json'));
-        for (const file of files) {
-          try {
-            const filePath = join(snapshotsDir, file);
-            const raw = readFileSync(filePath, 'utf-8');
-            const parsed = JSON.parse(raw) as PersistedCanvasState & { snapshot?: CanvasSnapshot };
-            if (parsed.snapshot && parsed.version === 1) {
-              saveSnapshotToDB(db, parsed.snapshot, parsed);
-              renameSync(filePath, `${filePath}.bak`);
-            }
-          } catch (error) {
-            logCanvasStateWarning('migrate snapshot file to sqlite failed', error, { file });
-          }
-        }
-      } catch (error) {
-        logCanvasStateWarning('migrate snapshots dir failed', error, { snapshotsDir });
-      }
-    }
-
-    // Migrate blob files
-    const blobsDir = this.blobsDir;
-    if (blobsDir && existsSync(blobsDir)) {
-      try {
-        const prefixes = readdirSync(blobsDir).filter((d) => d.length === 2);
-        for (const prefix of prefixes) {
-          const prefixDir = join(blobsDir, prefix);
-          const blobFiles = readdirSync(prefixDir).filter((f) => f.endsWith('.json.gz'));
-          for (const blobFile of blobFiles) {
-            try {
-              const blobPath = join(prefixDir, blobFile);
-              const sha256 = blobFile.replace('.json.gz', '');
-              if (!hasBlobInDB(db, sha256)) {
-                const compressed = readFileSync(blobPath);
-                const json = gunzipSync(compressed).toString('utf-8');
-                writeBlobToDB(db, sha256, json);
-              }
-              const backupPath = `${blobPath}.bak`;
-              if (!existsSync(backupPath)) renameSync(blobPath, backupPath);
-            } catch (error) {
-              logCanvasStateWarning('migrate blob file to sqlite failed', error, { blobFile });
-            }
-          }
-        }
-      } catch (error) {
-        logCanvasStateWarning('migrate blobs dir failed', error, { blobsDir });
-      }
-    }
-  }
-
   getWorkspaceRoot(): string {
     return this._workspaceRoot;
   }
@@ -927,11 +826,12 @@ class CanvasStateManager {
     };
   }
 
-  /** Load canvas state from SQLite (or legacy JSON fallback). Call once on server startup. */
+  /** Load canvas state from SQLite. Call once on server startup. */
   loadFromDisk(options: LoadFromDiskOptions = {}): boolean {
     // Host capability lives in its own table (not snapshotted / not in PmxAxState).
     this.ax.loadHostCapabilityFromDb();
-    // Try SQLite first (only if DB has been populated)
+    // Only a populated DB counts as saved state (legacy `state.json` loading was
+    // retired with the 0.4.0 boot-migration removal).
     if (this._db && isDbPopulated(this._db)) {
       try {
         const state = loadStateFromDB(this._db);
@@ -944,21 +844,6 @@ class CanvasStateManager {
       }
     }
 
-    // Fallback to JSON (for edge cases where migration hasn't happened)
-    if (this._stateFilePath && existsSync(this._stateFilePath)) {
-      try {
-        const raw = readFileSync(this._stateFilePath, 'utf-8');
-        const parsed = JSON.parse(raw) as PersistedCanvasState;
-        if (!parsed || parsed.version !== 1) return false;
-        this.applyPersistedState(parsed);
-        return true;
-      } catch (error) {
-        logCanvasStateWarning('load state from json fallback failed', error, {
-          path: this._stateFilePath,
-        });
-      }
-    }
-
     if (options.clearExisting) {
       this.applyPersistedState(this.emptyPersistedState());
     }
@@ -1015,11 +900,26 @@ class CanvasStateManager {
         ax: this.getAxState(),
       });
       saveStateToDB(this._db, payload);
+      this._lastPersistenceError = null;
     } catch (error) {
+      // Persistence failures are otherwise warn-and-continue (the canvas keeps
+      // working from memory) — record the failure so /health can report a
+      // degraded persistence state instead of silently losing durability (M4).
+      this._lastPersistenceError = {
+        message: error instanceof Error ? error.message : String(error),
+        at: new Date().toISOString(),
+      };
       logCanvasStateWarning('save state to sqlite failed', error, {});
     }
   }
 
+  private _lastPersistenceError: { message: string; at: string } | null = null;
+
+  /** Health view of state persistence: ok until a save fails, ok again after the next success. */
+  get persistenceHealth(): { ok: boolean; lastError: { message: string; at: string } | null } {
+    return { ok: this._lastPersistenceError === null, lastError: this._lastPersistenceError };
+  }
+
   /** Close the SQLite database cleanly. Call on server shutdown. */
   close(): void {
     if (this._saveTimer) {
@@ -1098,7 +998,7 @@ class CanvasStateManager {
       if (result) return result;
     }
 
-    // Fallback to filesystem (for legacy snapshots not yet migrated)
+    // Fallback to filesystem (legacy on-disk snapshots are still readable in place)
     const dir = this.snapshotsDir;
     if (!dir || !existsSync(dir)) return null;
 

package/src/server/index.ts

@@ -176,15 +176,9 @@ export class PmxCanvas extends EventEmitter {
     this._server = base;
     this._port = getCanvasServerPort() ?? this._port;
 
-    // Wire up mutation history recorder
-    canvasState.onMutation((info) => {
-      mutationHistory.record({
-        description: info.description,
-        operationType: info.operationType,
-        forward: info.forward,
-        inverse: info.inverse,
-      });
-    });
+    // The mutation-history recorder is wired by startCanvasServer above —
+    // onMutation is a single slot, so wiring it again here would only
+    // re-install an identical forwarder (plan-009 L5).
 
     // Wire up prompt handler to emit events
     setPrimaryWorkbenchCanvasPromptHandler(async (request) => {

package/src/server/operations/composites.ts

@@ -16,27 +16,12 @@
  * operation (plan-005 slices 1–7 + plan-008 Wave 1) that is now reachable ONLY
  * through its composite (or `canvas_batch`).
  *
- * Deferred to v0.4: the `canvas_snapshot` composite (still a name collision —
- * see below). Its 6 legacy snapshot standalones (`canvas_snapshot`,
- * `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`,
- * `canvas_gc_snapshots`, `canvas_diff`) stay registered in v0.3.0 but are marked
- * deprecated (description-prefixed) per docs/api-stability.md's
- * deprecate-one-minor-before-removal rule. (`canvas_webview` shipped in plan-008
- * Wave 3 via runner injection; `canvas_app` shipped in Wave 4 — open-mcp-app /
- * diagram / build-artifact. Wave 5 folded the last three legacy tools
- * deprecate-only — NO per-action input-injection mechanism was needed:
- * `canvas_add_html_node` / `canvas_add_html_primitive` → `canvas_node` action
- * "add" (type:"html" [+ primitive]); `canvas_refresh_webpage_node` → `canvas_node`
- * action "update" (refresh:true). `canvas_screenshot` stays standalone — it
- * returns a binary image payload the composite/registry JSON wire shape does not
- * model.)
- *
- * Not shipped here: the `canvas_snapshot` composite (plan-006 #7). Its target
- * name is ALREADY a legacy standalone tool (the save-snapshot tool, op
- * `snapshot.save`), so it cannot be added additively without a name clash, and
- * repurposing `canvas_snapshot` to be action-discriminated now would break
- * existing callers. It lands in v0.4, in the same change that removes the 6
- * kept-but-deprecated legacy snapshot tools and frees the name.
+ * v0.4.0 completed the fold: the `canvas_snapshot` composite shipped (its name
+ * was held by the legacy save-snapshot standalone through v0.3.x, which — with
+ * the other 5 snapshot standalones — was deprecated in 0.3.0 and removed here
+ * per docs/api-stability.md's deprecate-one-minor-before-removal rule).
+ * `canvas_screenshot` stays standalone — it returns a binary image payload the
+ * composite/registry JSON wire shape does not model.
  *
  * This module must never import server.ts or index.ts.
  */
@@ -138,6 +123,24 @@ const GATE_OPS: Array<{ op: string; kind: string; action: string }> = GATE_KINDS
 );
 
 export const compositeToolDefinitions: CompositeToolDefinition[] = [
+  {
+    // v0.4.0: the long-deferred snapshot composite (plan-006 #7). The name was
+    // held by the legacy save-snapshot standalone through v0.3.x; listing the
+    // composite here suppresses all 6 legacy snapshot standalones via
+    // compositeFoldedOpNames and frees the name in the same change.
+    toolName: 'canvas_snapshot',
+    description:
+      'Canvas snapshots: save the current state, list saved snapshots, restore one, delete one, garbage-collect old ones, or diff the live canvas against one. Action "save" stores a named snapshot; "list" returns saved snapshots (newest first); "restore" replaces the live canvas with a snapshot; "delete" removes one; "gc" keeps the newest N and deletes the rest (dryRun to preview); "diff" shows added/removed/modified nodes and edges versus a snapshot (by name or id).',
+    actionSummary: 'save | list | restore | delete | gc | diff',
+    actions: {
+      save: 'snapshot.save',
+      list: 'snapshot.list',
+      restore: 'snapshot.restore',
+      delete: 'snapshot.delete',
+      gc: 'snapshot.gc',
+      diff: 'snapshot.diff',
+    },
+  },
   {
     toolName: 'canvas_node',
     description:

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

@@ -70,7 +70,7 @@ const snapshotListOperation = defineOperation<z.infer<typeof snapshotListSchema>
   mcp: {
     toolName: 'canvas_list_snapshots',
     description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). List saved canvas snapshots with IDs, names, timestamps, and node/edge counts. Defaults to the 20 newest snapshots; pass all=true to return every snapshot.',
+      'List saved canvas snapshots with IDs, names, timestamps, and node/edge counts. Defaults to the 20 newest snapshots; pass all=true to return every snapshot.',
     extraShape: {
       limit: z.number().optional().describe('Maximum snapshots to return (default: 20)'),
       query: z.string().optional().describe('Optional case-insensitive ID/name filter'),
@@ -117,7 +117,7 @@ const snapshotSaveOperation = defineOperation<z.infer<typeof snapshotSaveSchema>
   mcp: {
     toolName: 'canvas_snapshot',
     description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Save the current canvas state as a named snapshot. Snapshots persist to disk and can be restored later.',
+      'Save the current canvas state as a named snapshot. Snapshots persist to disk and can be restored later.',
     extraShape: {
       name: z.string().describe('Name for this snapshot (e.g., "before refactor", "investigation v2")'),
     },
@@ -155,7 +155,7 @@ const snapshotGcOperation = defineOperation<z.infer<typeof snapshotGcSchema>, Re
   mcp: {
     toolName: 'canvas_gc_snapshots',
     description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Delete old saved canvas snapshots, keeping the newest N snapshots. Use dryRun=true to preview deletions.',
+      'Delete old saved canvas snapshots, keeping the newest N snapshots. Use dryRun=true to preview deletions.',
     extraShape: {
       keep: z.number().optional().describe('Number of newest snapshots to keep (default: 20)'),
       dryRun: z.boolean().optional().describe('Preview deletions without removing snapshot files'),
@@ -206,7 +206,7 @@ const snapshotDiffOperation = defineOperation<z.infer<typeof snapshotDiffSchema>
   mcp: {
     toolName: 'canvas_diff',
     description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Compare the current canvas state against a saved snapshot. Shows added/removed/modified nodes and edges. Pass either a snapshot name or ID.',
+      'Compare the current canvas state against a saved snapshot. Shows added/removed/modified nodes and edges. Pass either a snapshot name or ID.',
     extraShape: {
       snapshot: z.string().describe('Snapshot name or ID to compare against'),
     },
@@ -291,7 +291,7 @@ const snapshotRestoreOperation = defineOperation<z.infer<typeof snapshotRestoreS
   mcp: {
     toolName: 'canvas_restore',
     description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Restore the canvas to a previously saved snapshot. Use canvas_snapshot to save first. Pass either the snapshot ID or name to restore.',
+      'Restore the canvas to a previously saved snapshot. Use canvas_snapshot to save first. Pass either the snapshot ID or name to restore.',
     extraShape: {
       id: z.string().describe('Snapshot ID or name to restore (from canvas_snapshot or snapshot list)'),
     },
@@ -346,8 +346,7 @@ const snapshotDeleteOperation = defineOperation<z.infer<typeof snapshotDeleteSch
   },
   mcp: {
     toolName: 'canvas_delete_snapshot',
-    description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Delete a saved snapshot by ID.',
+    description: 'Delete a saved snapshot by ID.',
     extraShape: {
       id: z.string().describe('Snapshot ID to delete'),
     },

package/src/server/operations/registry.ts

@@ -39,7 +39,10 @@ export function setOperationEventEmitter(emitter: OperationEventEmitter | null):
   operationEventEmitter = emitter;
 }
 
-// Depth-counted emit suppression (mirrors canvasState._suppressRecordingDepth).
+// Depth-counted EMIT suppression (same pattern as, but deliberately distinct
+// state from, canvasState's recording suppression: batch suppresses SSE emits
+// while sub-ops still record history; undo/redo suppresses recording while
+// still emitting SSE — merging the two counters would break one or the other).
 // While > 0, emitOperationEvent is a no-op so a meta-op (canvas.batch) can run
 // many sub-ops without producing per-entry SSE frames, then emit ONE final
 // layout frame itself. Both the `mutates` auto-emit and `ctx.emit` route through