@hanna84/mcp-writing 3.20.0 → 3.21.1

package/CHANGELOG.md

@@ -4,9 +4,23 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v3.21.1](https://github.com/hannasdev/mcp-writing/compare/v3.21.0...v3.21.1)
+
+- fix(sync): preserve managed canonical structure [`#222`](https://github.com/hannasdev/mcp-writing/pull/222)
+
+#### [v3.21.0](https://github.com/hannasdev/mcp-writing/compare/v3.20.0...v3.21.0)
+
+> 26 May 2026
+
+- feat(backup): apply project restores transactionally [`#221`](https://github.com/hannasdev/mcp-writing/pull/221)
+- Release 3.21.0 [`4097165`](https://github.com/hannasdev/mcp-writing/commit/40971653b4332af83c15a9337fa1089b61aa0973)
+
 #### [v3.20.0](https://github.com/hannasdev/mcp-writing/compare/v3.19.0...v3.20.0)
 
+> 24 May 2026
+
 - feat(backup): add project restore dry-run planning [`#220`](https://github.com/hannasdev/mcp-writing/pull/220)
+- Release 3.20.0 [`0237cae`](https://github.com/hannasdev/mcp-writing/commit/0237cae3743e46cd19433e3e47cf5582d37dfe7c)
 
 #### [v3.19.0](https://github.com/hannasdev/mcp-writing/compare/v3.18.1...v3.19.0)
 

package/README.md

@@ -28,9 +28,9 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 
 **Current status:**
 - **Core platform complete:** Metadata-first analysis, sidecar-backed metadata maintenance, AI-assisted prose editing with confirmation + git history, review bundles, and Scrivener Direct extraction are all implemented.
-- **Recently completed:** Docker, CI, and Deployment Workflow made Docker a supported way to build, run, smoke-test, and deploy Writing MCP.
-- **Previous milestone:** Filesystem Boundary Hardening centralized local file mutation through application-aware helpers and lint guardrails.
-- **Active development:** Database Backup and Recovery now has project backup export, freshness diagnostics, advisory operation history, and automatic backup refresh after sanctioned project-scoped canonical mutations; the next slice focuses on dry-run restore planning.
+- **Recently completed:** Database Backup and Recovery added project backup export, freshness diagnostics, advisory operation history, automatic backup refresh after sanctioned project-scoped canonical mutations, dry-run restore planning, transactional restore application, and backup/restore operations guidance.
+- **Previous milestone:** Docker, CI, and Deployment Workflow made Docker a supported way to build, run, smoke-test, and deploy Writing MCP.
+- **Active development:** Post-initiative stabilization and backlog selection.
 - **Deferred backlog:** OpenClaw integration, client-agnostic setup, divisions, and embeddings search.
 - **Ideas and open questions:** tracked separately so future exploration does not distort the active roadmap.
 
@@ -47,6 +47,7 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 | [docs/guides/setup.md](docs/guides/setup.md) | Prerequisites, first-time setup, Scrivener import, native sync format |
 | [mcp-writing-vscode](https://github.com/hannasdev/mcp-writing-vscode) | VS Code extension for client-native setup flows |
 | [docs/guides/docker.md](docs/guides/docker.md) | Docker Compose, deployment operations, MCP gateway notes |
+| [docs/guides/backup-recovery.md](docs/guides/backup-recovery.md) | Project backup artifacts, diagnostics, and explicit restore workflow |
 | [docs/foundations/managed-structure-contract.md](docs/foundations/managed-structure-contract.md) | Design boundaries for structural mutation, generated views, import, and maintenance workflows |
 | [docs/agents/tools.md](docs/agents/tools.md) | Full tool reference — auto-generated from source |
 | [docs/agents/README.md](docs/agents/README.md) | Index of agent-focused guidance, examples, and boot files |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.20.0",
+  "version": "3.21.1",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "homepage": "https://hannasdev.github.io/mcp-writing/",
   "type": "module",

package/src/structure/project-backup-restore.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import matter from "gray-matter";
 import {
   buildProjectBackup,
   computeProjectBackupBundleChecksum,
@@ -65,6 +66,30 @@ const PROJECT_SCOPE_FIELDS = new Map([
   ["reference_links", ["source_project_id"]],
 ]);
 
+const SNAPSHOT_DOMAIN_COLUMNS = new Map([
+  ["project", ["project_id", "universe_id", "name"]],
+  ["universe", ["universe_id", "name"]],
+  ["external_references", ["character_ids", "place_ids", "reference_doc_ids"]],
+  ["operation_history", ["supported", "authority", "advisory", "artifact"]],
+  ["chapters", ["chapter_id", "project_id", "title", "sort_index", "logline", "source_path", "source_checksum", "metadata_stale", "updated_at"]],
+  ["scenes", ["scene_id", "project_id", "chapter_id", "scene_role", "title", "part", "chapter", "chapter_title", "pov", "logline", "scene_change", "causality", "stakes", "scene_functions", "save_the_cat_beat", "timeline_position", "story_time", "word_count", "file_path", "prose_checksum", "metadata_stale", "updated_at"]],
+  ["epigraphs", ["epigraph_id", "project_id", "chapter_id", "file_path", "prose_checksum", "metadata_stale", "updated_at"]],
+  ["epigraph_characters", ["epigraph_id", "project_id", "character_id"]],
+  ["epigraph_tags", ["epigraph_id", "project_id", "tag"]],
+  ["scene_characters", ["scene_id", "project_id", "character_id"]],
+  ["scene_places", ["scene_id", "project_id", "place_id"]],
+  ["scene_tags", ["scene_id", "project_id", "tag"]],
+  ["scene_threads", ["scene_id", "project_id", "thread_id", "beat"]],
+  ["characters", ["character_id", "project_id", "universe_id", "name", "role", "arc_summary", "first_appearance", "file_path"]],
+  ["character_traits", ["character_id", "trait"]],
+  ["character_relationships", ["from_character", "to_character", "relationship_type", "strength", "scene_id", "note"]],
+  ["places", ["place_id", "project_id", "universe_id", "name", "file_path"]],
+  ["threads", ["thread_id", "project_id", "name", "status"]],
+  ["reference_docs", ["doc_id", "project_id", "universe_id", "type", "title", "summary", "file_path"]],
+  ["reference_doc_tags", ["doc_id", "tag"]],
+  ["reference_links", ["source_kind", "source_project_id", "source_id", "target_doc_id", "relation", "origin"]],
+]);
+
 function stableStringify(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
@@ -81,6 +106,10 @@ function jsonType(value) {
   return typeof value;
 }
 
+function sortedUnique(values) {
+  return [...new Set(values.filter(value => value !== null && value !== undefined && value !== ""))].sort();
+}
+
 function fileReferenceBoundaryFailure(error, fallbackResolvedPath) {
   const errorDetails = isRecord(error?.details) ? error.details : {};
   const message = error instanceof Error ? error.message : String(error);
@@ -127,7 +156,7 @@ function identityFieldError(row, field, nullableFields, emptyStringFields) {
       actual_type: jsonType(value),
     };
   }
-  if (value === "" && !nullableFields.has(field) && !emptyStringFields.has(field)) {
+  if (value === "" && !emptyStringFields.has(field)) {
     return { reason: "empty_identity" };
   }
   return null;
@@ -256,6 +285,75 @@ function compareRows(currentRows = [], backupRows = [], keyFields) {
   return changes;
 }
 
+function rowIsCrossScope(domain, row, projectId) {
+  if (!row) return false;
+  if (domain === "universes") return true;
+  if (["characters", "places", "reference_docs"].includes(domain)) {
+    return row.project_id == null || row.project_id === "";
+  }
+  if (domain === "character_traits") {
+    return false;
+  }
+  if (domain === "reference_links") {
+    return row.source_project_id == null || row.source_project_id === "";
+  }
+  if (domain === "reference_doc_tags") {
+    return false;
+  }
+  if (domain === "character_relationships") {
+    return row.scene_id == null || row.scene_id === "";
+  }
+  return Object.hasOwn(row, "project_id") && row.project_id !== projectId;
+}
+
+function mergeScopedIds(map, rows, idField, projectId) {
+  for (const row of rows ?? []) {
+    const id = row?.[idField];
+    if (!id) continue;
+    const crossScope = row.project_id == null || row.project_id === "" || row.project_id !== projectId;
+    map.set(id, (map.get(id) ?? false) || crossScope);
+  }
+}
+
+function buildRestoreScopeContext(currentSnapshot, backupSnapshot, projectId) {
+  const projectSceneIds = new Set();
+  for (const snapshot of [currentSnapshot, backupSnapshot]) {
+    for (const row of snapshot.scenes ?? []) {
+      if (row.project_id === projectId) projectSceneIds.add(row.scene_id);
+    }
+  }
+
+  const characterIds = new Map();
+  mergeScopedIds(characterIds, currentSnapshot.characters, "character_id", projectId);
+  mergeScopedIds(characterIds, backupSnapshot.characters, "character_id", projectId);
+
+  const referenceDocIds = new Map();
+  mergeScopedIds(referenceDocIds, currentSnapshot.reference_docs, "doc_id", projectId);
+  mergeScopedIds(referenceDocIds, backupSnapshot.reference_docs, "doc_id", projectId);
+
+  return { characterIds, projectSceneIds, referenceDocIds };
+}
+
+function rowIsContextCrossScope(domain, row, projectId, scopeContext) {
+  if (domain === "character_traits") {
+    return scopeContext.characterIds.get(row?.character_id) === true;
+  }
+  if (domain === "reference_doc_tags") {
+    return scopeContext.referenceDocIds.get(row?.doc_id) === true;
+  }
+  if (domain === "character_relationships") {
+    if (!row || row.scene_id == null || row.scene_id === "") return true;
+    return !scopeContext.projectSceneIds.has(row.scene_id);
+  }
+  return rowIsCrossScope(domain, row, projectId);
+}
+
+function markChangeScope(change, projectId, scopeContext) {
+  const row = change.backup ?? change.current ?? null;
+  const crossScope = rowIsContextCrossScope(change.domain, row, projectId, scopeContext);
+  return crossScope ? { ...change, cross_scope: true } : change;
+}
+
 function compareSingleton(domain, current, backup, keyFields) {
   return compareRows(
     current ? [current] : [],
@@ -323,7 +421,7 @@ function collectCurrentSnapshot(db, {
   if (built.ok) return { ok: true, snapshot: built.snapshot, checksum: built.manifest.checksums.canonical_snapshot_sha256 };
   if (built.error?.code === "NOT_FOUND") {
     const snapshot = buildEmptyCurrentSnapshot(db, backupSnapshot);
-    return { ok: true, snapshot, checksum: null };
+    return { ok: true, snapshot, checksum: computeProjectBackupSnapshotChecksum(snapshot) };
   }
   return built;
 }
@@ -527,6 +625,21 @@ function validateBundleShape({ manifest, snapshot, backupDir, projectId }) {
         },
         { nextStep: "Regenerate the backup with export_project_backup before using it for recovery." }
       ));
+    } else if (value !== null) {
+      const allowedColumns = SNAPSHOT_DOMAIN_COLUMNS.get(domain) ?? [];
+      const unexpectedColumns = Object.keys(value).filter(column => !allowedColumns.includes(column));
+      if (unexpectedColumns.length) {
+        diagnostics.push(createDiagnostic(
+          "project_restore_invalid_snapshot",
+          `Backup canonical snapshot field "${domain}" contains unsupported columns.`,
+          {
+            backup_dir: backupDir,
+            domain,
+            unsupported_columns: unexpectedColumns,
+          },
+          { nextStep: "Regenerate the backup with export_project_backup before using it for recovery." }
+        ));
+      }
     }
   }
 
@@ -570,6 +683,22 @@ function validateBundleShape({ manifest, snapshot, backupDir, projectId }) {
           return;
         }
 
+        const allowedColumns = SNAPSHOT_DOMAIN_COLUMNS.get(domain) ?? [];
+        const unexpectedColumns = Object.keys(row).filter(column => !allowedColumns.includes(column));
+        if (unexpectedColumns.length) {
+          diagnostics.push(createDiagnostic(
+            "project_restore_invalid_snapshot",
+            `Backup canonical snapshot row ${index} in domain "${domain}" contains unsupported columns.`,
+            {
+              backup_dir: backupDir,
+              domain,
+              index,
+              unsupported_columns: unexpectedColumns,
+            },
+            { nextStep: "Regenerate the backup with export_project_backup before using it for recovery." }
+          ));
+        }
+
         let hasValidIdentity = true;
         for (const field of keyFields) {
           const identityError = identityFieldError(row, field, nullableFields, emptyStringFields);
@@ -648,7 +777,21 @@ function validateBundleShape({ manifest, snapshot, backupDir, projectId }) {
             continue;
           }
           const value = row[field];
-          if (value !== null && value !== undefined && value !== "" && value !== projectId) {
+          const emptyStringFields = EMPTY_STRING_IDENTITY_FIELDS.get(domain) ?? new Set();
+          if (value === "" && !emptyStringFields.has(field)) {
+            diagnostics.push(createDiagnostic(
+              "project_restore_invalid_snapshot",
+              `Backup canonical snapshot row ${index} in domain "${domain}" has empty project scope field "${field}".`,
+              {
+                backup_dir: backupDir,
+                domain,
+                index,
+                field,
+                reason: "empty_project_scope",
+              },
+              { nextStep: "Regenerate the backup with export_project_backup before using it for recovery." }
+            ));
+          } else if (value !== null && value !== undefined && value !== "" && value !== projectId) {
             diagnostics.push(createDiagnostic(
               "project_restore_wrong_project",
               `Backup canonical snapshot row ${index} in domain "${domain}" has ${field} "${value}", not "${projectId}".`,
@@ -700,7 +843,7 @@ function validateCurrentSnapshotForPlanning(snapshot, { backupDir }) {
   return diagnostics;
 }
 
-function buildRestorePlan(currentSnapshot, backupSnapshot) {
+function buildRestorePlan(currentSnapshot, backupSnapshot, { projectId }) {
   const changes = [
     ...compareSingleton("projects", currentSnapshot.project, backupSnapshot.project, ["project_id"]),
     ...compareSingleton("universes", currentSnapshot.universe, backupSnapshot.universe, ["universe_id"]),
@@ -712,25 +855,210 @@ function buildRestorePlan(currentSnapshot, backupSnapshot) {
     }
   }
 
+  const scopeContext = buildRestoreScopeContext(currentSnapshot, backupSnapshot, projectId);
+  const scopedChanges = changes.map(change => markChangeScope(change, projectId, scopeContext));
+
   const byDomain = {};
-  for (const change of changes) {
+  for (const change of scopedChanges) {
     byDomain[change.domain] ??= { create: 0, update: 0, delete: 0, unchanged: 0, refused: 0, conflict: 0 };
     byDomain[change.domain][change.action] = (byDomain[change.domain][change.action] ?? 0) + 1;
   }
 
   return {
-    totals: countActions(changes),
+    totals: countActions(scopedChanges),
     by_domain: byDomain,
-    destructive_change_count: changes.filter(change => change.action === "delete").length,
-    changes,
+    destructive_change_count: scopedChanges.filter(change => change.action === "delete").length,
+    cross_scope_change_count: scopedChanges.filter(change => change.cross_scope && change.action !== "unchanged").length,
+    changes: scopedChanges,
   };
 }
 
+function placeholders(values) {
+  return values.map(() => "?").join(",") || "NULL";
+}
+
+function allSnapshotIds(snapshot, domain, field) {
+  return sortedUnique((snapshot[domain] ?? []).map(row => row[field]));
+}
+
+function deleteCharacterRelationship(db, row) {
+  db.prepare(`
+    DELETE FROM character_relationships
+    WHERE from_character = ?
+      AND to_character = ?
+      AND relationship_type = ?
+      AND (strength IS ? OR strength = ?)
+      AND (scene_id IS ? OR scene_id = ?)
+      AND (note IS ? OR note = ?)
+  `).run(
+    row.from_character,
+    row.to_character,
+    row.relationship_type,
+    row.strength ?? null,
+    row.strength ?? null,
+    row.scene_id ?? null,
+    row.scene_id ?? null,
+    row.note ?? null,
+    row.note ?? null
+  );
+}
+
+function upsertRow(db, table, row, conflictColumns) {
+  const columns = Object.keys(row);
+  if (!conflictColumns.length) {
+    db.prepare(`
+      INSERT INTO ${table} (${columns.join(", ")})
+      VALUES (${columns.map(() => "?").join(", ")})
+    `).run(...columns.map(column => row[column]));
+    return;
+  }
+  const updateColumns = columns.filter(column => !conflictColumns.includes(column));
+  const conflictSql = conflictColumns.join(", ");
+  const updateSql = updateColumns.length
+    ? `DO UPDATE SET ${updateColumns.map(column => `${column} = excluded.${column}`).join(", ")}`
+    : "DO NOTHING";
+  db.prepare(`
+    INSERT INTO ${table} (${columns.join(", ")})
+    VALUES (${columns.map(() => "?").join(", ")})
+    ON CONFLICT (${conflictSql}) ${updateSql}
+  `).run(...columns.map(column => row[column]));
+}
+
+function insertRows(db, table, rows, conflictColumns) {
+  for (const row of rows) {
+    upsertRow(db, table, row, conflictColumns);
+  }
+}
+
+function restoreEpigraphRows(db, snapshot, { syncDir }) {
+  for (const row of snapshot.epigraphs) {
+    const filePath = path.isAbsolute(row.file_path)
+      ? path.resolve(row.file_path)
+      : path.resolve(syncDir, row.file_path);
+    const body = matter(fs.readFileSync(filePath, "utf8")).content;
+    upsertRow(db, "epigraphs", {
+      ...row,
+      body,
+      file_path: row.file_path,
+    }, ["epigraph_id", "project_id"]);
+  }
+}
+
+function clearDerivedRestoreRows(db, { projectId, currentSnapshot, backupSnapshot }) {
+  db.prepare(`DELETE FROM scenes_fts WHERE project_id = ?`).run(projectId);
+
+  const referenceDocIds = sortedUnique([
+    ...allSnapshotIds(currentSnapshot, "reference_docs", "doc_id"),
+    ...allSnapshotIds(backupSnapshot, "reference_docs", "doc_id"),
+  ]);
+  if (referenceDocIds.length) {
+    db.prepare(`
+      DELETE FROM reference_docs_fts
+      WHERE doc_id IN (${placeholders(referenceDocIds)})
+    `).run(...referenceDocIds);
+  }
+}
+
+function applyProjectRestore(db, {
+  projectId,
+  syncDir,
+  currentSnapshot,
+  backupSnapshot,
+}) {
+  const currentCharacterIds = allSnapshotIds(currentSnapshot, "characters", "character_id");
+  const currentPlaceIds = allSnapshotIds(currentSnapshot, "places", "place_id");
+  const currentReferenceDocIds = allSnapshotIds(currentSnapshot, "reference_docs", "doc_id");
+
+  clearDerivedRestoreRows(db, { projectId, currentSnapshot, backupSnapshot });
+
+  for (const domain of [
+    "epigraph_characters",
+    "epigraph_tags",
+    "scene_characters",
+    "scene_places",
+    "scene_tags",
+    "scene_threads",
+  ]) {
+    db.prepare(`DELETE FROM ${domain} WHERE project_id = ?`).run(projectId);
+  }
+
+  db.prepare(`DELETE FROM chapters WHERE project_id = ?`).run(projectId);
+  db.prepare(`DELETE FROM epigraphs WHERE project_id = ?`).run(projectId);
+  db.prepare(`DELETE FROM scenes WHERE project_id = ?`).run(projectId);
+  db.prepare(`DELETE FROM threads WHERE project_id = ?`).run(projectId);
+
+  if (currentCharacterIds.length) {
+    db.prepare(`DELETE FROM character_traits WHERE character_id IN (${placeholders(currentCharacterIds)})`).run(...currentCharacterIds);
+  }
+  for (const row of currentSnapshot.character_relationships ?? []) {
+    deleteCharacterRelationship(db, row);
+  }
+  if (currentCharacterIds.length) {
+    db.prepare(`DELETE FROM characters WHERE character_id IN (${placeholders(currentCharacterIds)})`).run(...currentCharacterIds);
+  }
+
+  if (currentPlaceIds.length) {
+    db.prepare(`DELETE FROM places WHERE place_id IN (${placeholders(currentPlaceIds)})`).run(...currentPlaceIds);
+  }
+
+  if (currentReferenceDocIds.length) {
+    db.prepare(`DELETE FROM reference_doc_tags WHERE doc_id IN (${placeholders(currentReferenceDocIds)})`).run(...currentReferenceDocIds);
+    db.prepare(`DELETE FROM reference_docs WHERE doc_id IN (${placeholders(currentReferenceDocIds)})`).run(...currentReferenceDocIds);
+  }
+  for (const row of currentSnapshot.reference_links ?? []) {
+    db.prepare(`
+      DELETE FROM reference_links
+      WHERE source_kind = ?
+        AND source_project_id = ?
+        AND source_id = ?
+        AND target_doc_id = ?
+        AND relation = ?
+    `).run(row.source_kind, row.source_project_id, row.source_id, row.target_doc_id, row.relation);
+  }
+
+  if (currentSnapshot.universe && !backupSnapshot.universe) {
+    db.prepare(`DELETE FROM universes WHERE universe_id = ?`).run(currentSnapshot.universe.universe_id);
+  }
+
+  if (backupSnapshot.universe) {
+    upsertRow(db, "universes", backupSnapshot.universe, ["universe_id"]);
+  }
+  if (backupSnapshot.project) {
+    upsertRow(db, "projects", backupSnapshot.project, ["project_id"]);
+  }
+
+  insertRows(db, "chapters", backupSnapshot.chapters, ["chapter_id", "project_id"]);
+  insertRows(db, "scenes", backupSnapshot.scenes, ["scene_id", "project_id"]);
+  restoreEpigraphRows(db, backupSnapshot, { syncDir });
+  insertRows(db, "characters", backupSnapshot.characters, ["character_id"]);
+  insertRows(db, "character_traits", backupSnapshot.character_traits, ["character_id", "trait"]);
+  insertRows(db, "character_relationships", backupSnapshot.character_relationships, []);
+  insertRows(db, "places", backupSnapshot.places, ["place_id"]);
+  insertRows(db, "threads", backupSnapshot.threads, ["thread_id"]);
+  insertRows(db, "reference_docs", backupSnapshot.reference_docs, ["doc_id"]);
+  insertRows(db, "reference_doc_tags", backupSnapshot.reference_doc_tags, ["doc_id", "tag"]);
+  insertRows(db, "reference_links", backupSnapshot.reference_links, ["source_kind", "source_project_id", "source_id", "target_doc_id", "relation"]);
+
+  for (const domain of [
+    ["epigraph_characters", ["epigraph_id", "project_id", "character_id"]],
+    ["epigraph_tags", ["epigraph_id", "project_id", "tag"]],
+    ["scene_characters", ["scene_id", "project_id", "character_id"]],
+    ["scene_places", ["scene_id", "project_id", "place_id"]],
+    ["scene_tags", ["scene_id", "project_id", "tag"]],
+    ["scene_threads", ["scene_id", "project_id", "thread_id"]],
+  ]) {
+    insertRows(db, domain[0], backupSnapshot[domain[0]], domain[1]);
+  }
+}
+
 export function restoreProjectFromBackup(db, {
   syncDir,
   projectId,
   backupPath = null,
   dryRun = true,
+  confirmDestructive = false,
+  confirmCrossScope = false,
+  expectedCurrentSnapshotChecksum = null,
   applicationVersion = "0.0.0",
 } = {}) {
   const resolvedBackupDir = resolveBackupDir(backupPath ?? path.join(syncDir, "project-backups", projectId));
@@ -740,15 +1068,6 @@ export function restoreProjectFromBackup(db, {
   const snapshotRead = readJsonFile(snapshotPath, "canonical snapshot");
   const diagnostics = [manifestRead.diagnostic, snapshotRead.diagnostic].filter(Boolean);
 
-  if (dryRun === false) {
-    diagnostics.push(createDiagnostic(
-      "project_restore_apply_not_implemented",
-      "Project backup restore apply is not implemented in this milestone.",
-      { project_id: projectId },
-      { severity: "error", nextStep: "Run with dry_run=true to inspect the restore plan. Apply support is planned for M7." }
-    ));
-  }
-
   const manifest = manifestRead.ok ? manifestRead.value : null;
   const snapshot = snapshotRead.ok ? snapshotRead.value : null;
   if (manifestRead.ok && snapshotRead.ok) {
@@ -830,10 +1149,125 @@ export function restoreProjectFromBackup(db, {
     };
   }
 
-  const plan = buildRestorePlan(current.snapshot, snapshot);
+  const plan = buildRestorePlan(current.snapshot, snapshot, { projectId });
+  const applyDiagnostics = [];
+  if (dryRun === false) {
+    if (typeof expectedCurrentSnapshotChecksum !== "string" || expectedCurrentSnapshotChecksum === "") {
+      applyDiagnostics.push(createDiagnostic(
+        "project_restore_current_snapshot_confirmation_required",
+        "Project backup restore requires the current_snapshot_checksum from the reviewed dry-run plan.",
+        {
+          project_id: projectId,
+          current_snapshot_checksum: current.checksum,
+        },
+        {
+          severity: "error",
+          nextStep: "Run a dry-run restore, review the plan, then retry with expected_current_snapshot_checksum set to that dry-run current_snapshot_checksum.",
+        }
+      ));
+    } else if (expectedCurrentSnapshotChecksum !== current.checksum) {
+      applyDiagnostics.push(createDiagnostic(
+        "project_restore_current_snapshot_changed",
+        "Current SQLite canonical state changed after the reviewed dry-run plan.",
+        {
+          project_id: projectId,
+          expected_current_snapshot_checksum: expectedCurrentSnapshotChecksum,
+          current_snapshot_checksum: current.checksum,
+        },
+        {
+          severity: "error",
+          nextStep: "Run a new dry-run restore, review the updated plan, then retry with the new current_snapshot_checksum.",
+        }
+      ));
+    }
+  }
+  if (dryRun === false && plan.destructive_change_count > 0 && confirmDestructive !== true) {
+    applyDiagnostics.push(createDiagnostic(
+      "project_restore_destructive_confirmation_required",
+      "Project backup restore would delete canonical SQLite records and requires explicit confirmation.",
+      {
+        project_id: projectId,
+        destructive_change_count: plan.destructive_change_count,
+      },
+      {
+        severity: "error",
+        nextStep: "Review the dry-run delete candidates, then retry with confirm_destructive=true if those deletes are intended.",
+      }
+    ));
+  }
+  if (dryRun === false && plan.cross_scope_change_count > 0 && confirmCrossScope !== true) {
+    applyDiagnostics.push(createDiagnostic(
+      "project_restore_cross_scope_confirmation_required",
+      "Project backup restore would create, update, or delete universe-scoped records and requires explicit confirmation.",
+      {
+        project_id: projectId,
+        cross_scope_change_count: plan.cross_scope_change_count,
+      },
+      {
+        severity: "error",
+        nextStep: "Review the dry-run cross_scope changes, then retry with confirm_cross_scope=true if those changes are intended.",
+      }
+    ));
+  }
+
+  if (applyDiagnostics.length) {
+    applyDiagnostics.sort((a, b) => {
+      const typeCompare = a.type.localeCompare(b.type);
+      if (typeCompare) return typeCompare;
+      return a.message.localeCompare(b.message);
+    });
+    return {
+      ok: false,
+      action: "restore_refused",
+      dry_run: Boolean(dryRun),
+      project_id: projectId,
+      backup_dir: resolvedBackupDir,
+      diagnostics: applyDiagnostics,
+      plan,
+      next_step: "Resolve confirmation requirements before applying this trusted backup.",
+    };
+  }
+
+  if (dryRun === false) {
+    try {
+      db.exec("BEGIN");
+      applyProjectRestore(db, {
+        projectId,
+        syncDir,
+        currentSnapshot: current.snapshot,
+        backupSnapshot: snapshot,
+      });
+      db.exec("COMMIT");
+    } catch (error) {
+      try {
+        db.exec("ROLLBACK");
+      } catch (rollbackError) {
+        void rollbackError;
+      }
+      return {
+        ok: false,
+        action: "restore_refused",
+        dry_run: false,
+        project_id: projectId,
+        backup_dir: resolvedBackupDir,
+        diagnostics: [createDiagnostic(
+          "project_restore_write_failed",
+          "Failed to apply project backup restore transaction.",
+          {
+            project_id: projectId,
+            error: error instanceof Error ? error.message : String(error),
+          },
+          { severity: "error", nextStep: "Review the database error and retry after resolving conflicts." }
+        )],
+        plan,
+        next_step: "Resolve restore write diagnostics before retrying.",
+      };
+    }
+  }
+
   return {
     ok: true,
-    action: "planned",
+    action: dryRun ? "planned" : "restored",
     dry_run: Boolean(dryRun),
     project_id: projectId,
     backup_dir: resolvedBackupDir,
@@ -846,9 +1280,20 @@ export function restoreProjectFromBackup(db, {
     current_snapshot_checksum: current.checksum,
     backup_snapshot_checksum: manifest.checksums.canonical_snapshot_sha256,
     plan,
+    applied: dryRun ? null : {
+      restored: true,
+      destructive_confirmed: Boolean(confirmDestructive),
+      cross_scope_confirmed: Boolean(confirmCrossScope),
+      derived_indexes: {
+        scenes_fts: "cleared_for_restored_project",
+        reference_docs_fts: "cleared_for_restored_reference_docs",
+      },
+    },
     diagnostics: [],
-    next_step: plan.destructive_change_count > 0
-      ? "Review destructive delete candidates carefully. Apply support will require explicit confirmation in a later milestone."
-      : "Review the dry-run plan. Apply support is intentionally not available until the transactional restore milestone.",
+    next_step: dryRun
+      ? (plan.destructive_change_count > 0 || plan.cross_scope_change_count > 0
+          ? "Review destructive delete and cross_scope candidates carefully before applying with explicit confirmation."
+          : "Review the dry-run plan, then rerun with dry_run=false to apply the restore transactionally.")
+      : "Run sync, diagnose_project_backups, and export_project_backup to rebuild derived indexes and refresh generated backup transparency.",
   };
 }

package/src/sync/sync.js

@@ -957,15 +957,24 @@ function canPruneScenes(syncDir) {
   return hasBroadRootChild;
 }
 
-function pruneMissingScenes(db, seenSceneKeys, syncDir) {
+function pruneMissingScenes(db, seenSceneKeys, syncDir, { managedProjectIds = new Set() } = {}) {
   const projectScope = inferSceneProjectScopeFromSyncDir(syncDir);
   const rows = projectScope
-    ? db.prepare(`SELECT scene_id, project_id FROM scenes WHERE project_id = ?`).all(projectScope)
-    : db.prepare(`SELECT scene_id, project_id FROM scenes`).all();
+    ? db.prepare(`SELECT scene_id, project_id, file_path FROM scenes WHERE project_id = ?`).all(projectScope)
+    : db.prepare(`SELECT scene_id, project_id, file_path FROM scenes`).all();
 
+  const result = { deleted: 0, preservedManagedScenes: [] };
   for (const row of rows) {
     const key = `${row.scene_id}::${row.project_id}`;
     if (seenSceneKeys.has(key)) continue;
+    if (managedProjectIds.has(row.project_id)) {
+      result.preservedManagedScenes.push({
+        scene_id: row.scene_id,
+        project_id: row.project_id,
+        file_path: row.file_path,
+      });
+      continue;
+    }
 
     db.prepare(`DELETE FROM scenes_fts WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
     db.prepare(`
@@ -977,7 +986,9 @@ function pruneMissingScenes(db, seenSceneKeys, syncDir) {
     db.prepare(`DELETE FROM scene_places WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
     db.prepare(`DELETE FROM scene_tags WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
     db.prepare(`DELETE FROM scene_threads WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
+    result.deleted++;
   }
+  return result;
 }
 
 function pruneMissingChapters(db, seenChapterKeys, syncDir) {
@@ -1013,19 +1024,99 @@ function pruneMissingEpigraphs(db, seenEpigraphKeys, syncDir) {
   }
 }
 
+function formatSyncRelativePath(syncDir, filePath) {
+  if (!filePath) return null;
+  if (!path.isAbsolute(filePath)) return filePath.split(/[\\/]+/).join("/");
+  const resolvedSyncDir = path.resolve(syncDir);
+  const resolvedFilePath = path.resolve(filePath);
+  const relativePath = path.relative(resolvedSyncDir, resolvedFilePath);
+  if (relativePath && !relativePath.startsWith("..") && !path.isAbsolute(relativePath)) {
+    return relativePath.split(path.sep).join("/");
+  }
+  return resolvedFilePath;
+}
+
+function storedSyncPathCandidates(syncDir, filePath) {
+  if (!filePath) return [];
+  if (path.isAbsolute(filePath)) return [path.resolve(filePath)];
+
+  const candidates = new Set([path.resolve(syncDir, filePath)]);
+  const normalizedParts = filePath.split(/[\\/]+/).filter(Boolean);
+  const anchor = normalizedParts[0];
+  if (["projects", "universes", "scenes"].includes(anchor)) {
+    const syncParts = path.resolve(syncDir).split(path.sep);
+    for (let index = syncParts.length - 1; index >= 0; index--) {
+      if (syncParts[index] !== anchor) continue;
+      const rootParts = syncParts.slice(0, index);
+      const root = rootParts.length ? rootParts.join(path.sep) : path.sep;
+      candidates.add(path.resolve(root, filePath));
+    }
+  }
+
+  return [...candidates];
+}
+
+function collectMissingManagedRepresentationWarnings(db, syncDir, {
+  observedChapterKeys,
+  observedEpigraphKeys,
+}) {
+  const projectScope = inferSceneProjectScopeFromSyncDir(syncDir);
+  const chapterRows = projectScope
+    ? db.prepare(`SELECT chapter_id, project_id, source_path FROM chapters WHERE project_id = ?`).all(projectScope)
+    : db.prepare(`SELECT chapter_id, project_id, source_path FROM chapters`).all();
+  const epigraphRows = projectScope
+    ? db.prepare(`SELECT epigraph_id, project_id, file_path FROM epigraphs WHERE project_id = ?`).all(projectScope)
+    : db.prepare(`SELECT epigraph_id, project_id, file_path FROM epigraphs`).all();
+  const warnings = [];
+
+  for (const row of chapterRows) {
+    const key = `${row.chapter_id}::${row.project_id}`;
+    if (observedChapterKeys.has(key)) continue;
+    const sourcePaths = storedSyncPathCandidates(syncDir, row.source_path);
+    if (!sourcePaths.length || sourcePaths.some(candidate => fs.existsSync(candidate))) continue;
+    warnings.push(`Managed sync preserved canonical chapter missing from filesystem: ${row.project_id}/${row.chapter_id} (${formatSyncRelativePath(syncDir, row.source_path)})`);
+  }
+
+  for (const row of epigraphRows) {
+    const key = `${row.epigraph_id}::${row.project_id}`;
+    if (observedEpigraphKeys.has(key)) continue;
+    const filePaths = storedSyncPathCandidates(syncDir, row.file_path);
+    if (!filePaths.length || filePaths.some(candidate => fs.existsSync(candidate))) continue;
+    warnings.push(`Managed sync preserved canonical epigraph missing from filesystem: ${row.project_id}/${row.epigraph_id} (${formatSyncRelativePath(syncDir, row.file_path)})`);
+  }
+
+  return warnings;
+}
+
+function formatStoredPathSuffix(syncDir, filePath) {
+  const displayPath = formatSyncRelativePath(syncDir, filePath);
+  return displayPath ? ` (${displayPath})` : "";
+}
+
+function formatPreservedManagedSceneWarning(syncDir, scene) {
+  const pathSuffix = formatStoredPathSuffix(syncDir, scene.file_path);
+  const sceneLabel = `${scene.project_id}/${scene.scene_id}`;
+  const filePaths = storedSyncPathCandidates(syncDir, scene.file_path);
+  if (filePaths.some(candidate => fs.existsSync(candidate))) {
+    return `Managed sync preserved canonical scene not observed during sync scan: ${sceneLabel}${pathSuffix}`;
+  }
+  return `Managed sync preserved canonical scene missing from filesystem: ${sceneLabel}${pathSuffix}`;
+}
+
 export function pruneSyncDerivedIndexes(db, syncDir, {
   seenSceneKeys,
   seenEpigraphKeys,
   seenChapterKeys,
   sceneIndexFailures,
+  managedProjectIds = new Set(),
 }) {
   if (!canPruneScenes(syncDir)) return { pruned: false, reason: "scope_not_prunable" };
   if (sceneIndexFailures !== 0) return { pruned: false, reason: "scene_index_failures" };
 
-  pruneMissingScenes(db, seenSceneKeys, syncDir);
+  const scenePrune = pruneMissingScenes(db, seenSceneKeys, syncDir, { managedProjectIds });
   pruneMissingEpigraphs(db, seenEpigraphKeys, syncDir);
   pruneMissingChapters(db, seenChapterKeys, syncDir);
-  return { pruned: true, reason: null };
+  return { pruned: true, reason: null, scenePrune };
 }
 
 export function regenerateReferenceAndWorldIndexes(db, syncDir, files, {
@@ -1449,6 +1540,10 @@ const WARNING_TYPE_LABELS = {
   chapter_structure: "Chapter structure",
   orphaned_sidecar: "Orphaned sidecar",
   moved_scene: "Moved scene",
+  missing_canonical_scene: "Missing canonical scene",
+  unobserved_canonical_scene: "Unobserved canonical scene",
+  missing_canonical_chapter: "Missing canonical chapter",
+  missing_canonical_epigraph: "Missing canonical epigraph",
   nested_mirror: "Ignored nested mirror path",
 };
 
@@ -1459,6 +1554,10 @@ const WARNING_PATTERNS = [
   { type: "chapter_structure",      re: /^(Chapter structure warning|Epigraph requires explicit chapter linkage|Epigraph references unknown chapter_id|Scene references unknown chapter_id|Ambiguous chapter linkage|Epigraph identity conflict|Managed structure sync ignored|Managed structure sync preserved canonical epigraph)/ },
   { type: "moved_scene",            re: /^Moved scene detected:/      },
   { type: "orphaned_sidecar",       re: /^Orphaned sidecar/          },
+  { type: "missing_canonical_scene", re: /^Managed sync preserved canonical scene missing from filesystem:/ },
+  { type: "unobserved_canonical_scene", re: /^Managed sync preserved canonical scene not observed during sync scan:/ },
+  { type: "missing_canonical_chapter", re: /^Managed sync preserved canonical chapter missing from filesystem:/ },
+  { type: "missing_canonical_epigraph", re: /^Managed sync preserved canonical epigraph missing from filesystem:/ },
   { type: "nested_mirror",          re: /^Ignored nested mirror path:/ },
 ];
 
@@ -1511,6 +1610,8 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
   const indexedSceneIds = new Set(); // scene_id only — for orphaned sidecar move detection
   const seenChapterKeys = new Set(managedChapterKeys);
   const seenEpigraphKeys = new Set(managedEpigraphKeys);
+  const observedChapterKeys = new Set();
+  const observedEpigraphKeys = new Set();
   let sceneIndexFailures = 0;
   const warnings = [];
   const chapterFoldersByProject = new Map();
@@ -1588,7 +1689,9 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
         warnings.push(result.warning);
       }
       if (result.chapterId) {
-        seenChapterKeys.add(`${result.chapterId}::${project_id}`);
+        const chapterKey = `${result.chapterId}::${project_id}`;
+        seenChapterKeys.add(chapterKey);
+        observedChapterKeys.add(chapterKey);
       }
       if (chapterStructure.chapter && result.chapterId) {
         const chapterMapKey = `${project_id}::${chapterStructure.chapter.sort_index}`;
@@ -1607,7 +1710,9 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
       if (result.skippedAsEpigraph) {
         if (result.epigraphIndexed && result.epigraphId) {
           const epigraphId = result.epigraphId;
-          seenEpigraphKeys.add(`${epigraphId}::${project_id}`);
+          const epigraphKey = `${epigraphId}::${project_id}`;
+          seenEpigraphKeys.add(epigraphKey);
+          observedEpigraphKeys.add(epigraphKey);
         }
         if (result.epigraphIndexed) {
           epigraphsIndexed++;
@@ -1626,12 +1731,22 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
     }
   }
 
-  pruneSyncDerivedIndexes(db, syncDir, {
+  const pruneResult = pruneSyncDerivedIndexes(db, syncDir, {
     seenSceneKeys,
     seenEpigraphKeys,
     seenChapterKeys,
     sceneIndexFailures,
+    managedProjectIds,
   });
+  for (const scene of pruneResult.scenePrune?.preservedManagedScenes ?? []) {
+    warnings.push(formatPreservedManagedSceneWarning(syncDir, scene));
+  }
+  for (const warning of collectMissingManagedRepresentationWarnings(db, syncDir, {
+    observedChapterKeys,
+    observedEpigraphKeys,
+  })) {
+    warnings.push(warning);
+  }
 
   // --- Orphaned sidecar detection ---
   for (const diagnostic of observeOrphanedSidecars(syncDir, { indexedSceneIds })) {

package/src/tools/sync.js

@@ -338,13 +338,16 @@ export function registerSyncTools(s, {
 
   s.tool(
     "restore_project_from_backup",
-    "Dry-run an explicit project restore from a trusted generated project backup bundle. Validates manifest, schema, checksums, project identity, and file references, then returns a deterministic create/update/delete/unchanged plan without mutating SQLite or generated files.",
+    "Explicitly restore a project from a trusted generated project backup bundle. Defaults to dry-run planning; dry_run=false applies canonical SQLite changes transactionally after the reviewed current snapshot checksum and required destructive or cross-scope confirmations are provided.",
     {
       project_id: z.string().describe("Project ID to restore (e.g. 'test-novel' or 'universe-1/book-1-the-lamb')."),
       backup_path: z.string().optional().describe("Path under WRITING_SYNC_DIR to a project backup directory, manifest.json, or canonical.snapshot.json. Defaults to project-backups/<project_id>."),
-      dry_run: z.boolean().optional().describe("If true (default), validate and summarize the restore plan without writing SQLite state. dry_run=false is reserved for a later transactional restore milestone."),
+      dry_run: z.boolean().optional().describe("If true (default), validate and summarize the restore plan without writing SQLite state."),
+      confirm_destructive: z.boolean().optional().describe("Required with dry_run=false when the restore plan includes delete candidates."),
+      confirm_cross_scope: z.boolean().optional().describe("Required with dry_run=false when the restore plan changes universe-scoped records."),
+      expected_current_snapshot_checksum: z.string().optional().describe("Required with dry_run=false; pass the current_snapshot_checksum returned by the reviewed dry-run plan to guard against state changes before apply."),
     },
-    async ({ project_id, backup_path, dry_run = true } = {}) => {
+    async ({ project_id, backup_path, dry_run = true, confirm_destructive = false, confirm_cross_scope = false, expected_current_snapshot_checksum = null } = {}) => {
       if (!SYNC_DIR_WRITABLE && dry_run === false) {
         return errorResponse("READ_ONLY", "Cannot restore project from backup: server is in read-only mode for canonical structure mutations.");
       }
@@ -368,6 +371,9 @@ export function registerSyncTools(s, {
           projectId: project_id,
           backupPath: requestedBackupPath,
           dryRun: dry_run,
+          confirmDestructive: confirm_destructive,
+          confirmCrossScope: confirm_cross_scope,
+          expectedCurrentSnapshotChecksum: expected_current_snapshot_checksum,
           applicationVersion: MCP_SERVER_VERSION,
         }));
       } catch (error) {

package/src/workflows/workflow-catalogue.js

@@ -95,6 +95,19 @@ export const WORKFLOW_CATALOGUE = [
       { tool: "export_project_backup", note: "Generate or repair the broader deterministic project backup bundle for Git review and future recovery input; editing it does not mutate canonical state." },
     ],
   },
+  {
+    id: "backup_recovery",
+    label: "Verify or restore project backups",
+    use_when: "Use when the user asks about backup freshness, generated project-backups files, database loss, recovery readiness, or restoring SQLite-canonical project state.",
+    steps: [
+      { tool: "diagnose_project_backups", note: "Start here to verify whether the bundle is missing, stale, tampered, incompatible, partial, or current. This never mutates SQLite or generated files." },
+      { tool: "export_project_backup", note: "Generate or refresh the deterministic project backup bundle when diagnostics report missing or stale backup artifacts." },
+      { tool: "restore_project_from_backup", note: "Use dry_run=true first to validate the trusted bundle and inspect create/update/delete/unchanged and cross_scope changes before applying anything." },
+      { tool: "restore_project_from_backup", note: "Apply only after the dry-run plan is reviewed. Pass dry_run=false with expected_current_snapshot_checksum from that dry run, confirm_destructive=true for deletes, and confirm_cross_scope=true for universe-scoped changes." },
+      { tool: "sync", note: "Run after a successful restore to regenerate derived indexes and confirm ordinary read workflows see the restored state." },
+      { tool: "diagnose_project_backups", note: "Re-check backup health after restore, then run export_project_backup if generated transparency needs refreshing." },
+    ],
+  },
   {
     id: "review_preparation",
     label: "Prepare material for human review",