@hanna84/mcp-writing 3.14.1 → 3.15.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.15.1](https://github.com/hannasdev/mcp-writing/compare/v3.15.0...v3.15.1)
+
+- chore(security): add eslint security checks [`#211`](https://github.com/hannasdev/mcp-writing/pull/211)
+
+#### [v3.15.0](https://github.com/hannasdev/mcp-writing/compare/v3.14.1...v3.15.0)
+
+> 20 May 2026
+
+- feat(sync): harden structural authority [`#210`](https://github.com/hannasdev/mcp-writing/pull/210)
+- Release 3.15.0 [`8146269`](https://github.com/hannasdev/mcp-writing/commit/81462696b50a33b82bfb37ece8f41b39570b1874)
+
 #### [v3.14.1](https://github.com/hannasdev/mcp-writing/compare/v3.14.0...v3.14.1)
 
+> 19 May 2026
+
 - ci: optimize validation workflow [`#208`](https://github.com/hannasdev/mcp-writing/pull/208)
+- Release 3.14.1 [`995bb83`](https://github.com/hannasdev/mcp-writing/commit/995bb83941d589061d63ecdae764cf81b1503b41)
 
 #### [v3.14.0](https://github.com/hannasdev/mcp-writing/compare/v3.13.1...v3.14.0)
 

package/README.md

@@ -28,7 +28,8 @@ 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.
-- **Active development:** OpenClaw integration, the client-agnostic setup contract, and chapter-structure follow-up work after the first-class chapter/epigraph rollout.
+- **Recently completed:** Structural Authority Hardening tightened remaining structure-authority paths so scene placement and ordering go through explicit structure workflows, ordinary sync reports drift instead of adopting it, and trusted structure exports can be diagnosed and restored explicitly.
+- **Active development:** none selected.
 - **Deferred backlog:** embeddings search.
 - **Ideas and open questions:** tracked separately so future exploration does not distort the active roadmap.
 
@@ -149,7 +150,7 @@ Outcome: subplot structure stays visible and auditable, which reduces dropped th
 Goal: keep indexes accurate without manually re-tagging everything.
 
 1. After rewriting scenes, call `enrich_scene` to re-derive lightweight metadata from current prose.
-2. Use `update_scene_metadata` for intentional editorial fields (for example, beat, POV, timeline position, and tags).
+2. Use `update_scene_metadata` for intentional editorial fields (for example, beat, POV, status, and tags); use `list_chapters` plus `assign_scene_to_chapter` or `move_scene` for chapter placement and ordering. Numeric chapter filters are compatibility aliases for read scopes, not mutation targets.
 3. Use `search_metadata` and `find_scenes` to verify scenes are discoverable under the expected filters.
 
 Outcome: your AI assistant can reliably find the right scenes without drifting from the manuscript.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.14.1",
+  "version": "3.15.1",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "homepage": "https://hannasdev.github.io/mcp-writing/",
   "type": "module",
@@ -110,6 +110,7 @@
     "@eslint/js": "^10.0.1",
     "auto-changelog": "^2.5.1",
     "eslint": "^10.3.0",
+    "eslint-plugin-security": "^4.0.0",
     "globals": "^17.6.0",
     "release-it": "^20.0.1"
   },

package/src/structure/chapter-indexing.js

@@ -202,7 +202,15 @@ export function resolveIndexedChapterForFile(db, {
   relativePath,
   meta = {},
   chapterStructure,
+  managedStructure = false,
 }) {
+  const existingScene = meta.scene_id
+    ? db.prepare(`
+      SELECT chapter_id, chapter, chapter_title
+      FROM scenes
+      WHERE scene_id = ? AND project_id = ?
+    `).get(meta.scene_id, projectId)
+    : null;
   let chapterId = meta.chapter_id ?? chapterStructure.chapter?.chapter_id ?? null;
   let chapterSortIndex = chapterStructure.chapter?.sort_index ?? meta.chapter ?? null;
   let chapterTitle = chapterStructure.chapter?.title ?? meta.chapter_title ?? (chapterSortIndex != null ? `Chapter ${chapterSortIndex}` : null);
@@ -213,6 +221,56 @@ export function resolveIndexedChapterForFile(db, {
   const explicitSceneChapterId = !chapterStructure.isEpigraph ? meta.chapter_id ?? null : null;
   let explicitSceneCanonicalChapter = null;
 
+  if (managedStructure && !chapterStructure.isEpigraph) {
+    let managedWarning = null;
+    if (existingScene?.chapter_id) {
+      const canonicalChapter = db.prepare(`
+        SELECT chapter_id, sort_index, title
+        FROM chapters
+        WHERE chapter_id = ? AND project_id = ?
+      `).get(existingScene.chapter_id, projectId);
+      if (canonicalChapter) {
+        chapterId = canonicalChapter.chapter_id;
+        chapterSortIndex = canonicalChapter.sort_index ?? null;
+        chapterTitle = canonicalChapter.title ?? null;
+        const observedChapterId = meta.chapter_id ?? chapterStructure.chapter?.chapter_id ?? null;
+        const observedSortIndex = chapterStructure.chapter?.sort_index ?? meta.chapter ?? null;
+        const observedTitle = chapterStructure.chapter?.title ?? meta.chapter_title ?? null;
+        if (
+          (observedChapterId && observedChapterId !== chapterId)
+          || (observedSortIndex != null && observedSortIndex !== chapterSortIndex)
+          || (observedTitle && observedTitle !== chapterTitle)
+        ) {
+          managedWarning = `Managed structure sync ignored file-derived chapter linkage for scene '${meta.scene_id}': ${relativePath}`;
+        }
+      } else {
+        chapterId = null;
+        chapterSortIndex = null;
+        chapterTitle = null;
+        managedWarning = `Scene references unknown chapter_id '${existingScene.chapter_id}': ${relativePath}`;
+      }
+    } else {
+      const observedChapterId = meta.chapter_id ?? chapterStructure.chapter?.chapter_id ?? null;
+      const observedSortIndex = chapterStructure.chapter?.sort_index ?? meta.chapter ?? null;
+      const observedTitle = chapterStructure.chapter?.title ?? meta.chapter_title ?? null;
+      if (observedChapterId || observedSortIndex != null || observedTitle) {
+        managedWarning = `Managed structure sync ignored file-derived chapter linkage for scene '${meta.scene_id}': ${relativePath}`;
+      }
+      chapterId = null;
+      chapterSortIndex = null;
+      chapterTitle = null;
+    }
+
+    return {
+      chapterId,
+      chapterSortIndex,
+      chapterTitle,
+      chapterSourcePath,
+      chapterWarning: managedWarning,
+      upsertChapter: null,
+    };
+  }
+
   if (explicitSceneChapterId && !chapterStructure.chapter) {
     explicitSceneCanonicalChapter = db.prepare(`
       SELECT chapter_id, sort_index, title

package/src/structure/epigraph-indexing.js

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+
 export function indexCanonicalEpigraph(db, {
   projectId,
   chapterId,
@@ -10,8 +12,116 @@ export function indexCanonicalEpigraph(db, {
   chapterWarning = null,
   buildProseChecksum,
   buildDefaultEpigraphId,
+  managedStructure = false,
   updatedAt = new Date().toISOString(),
 }) {
+  const defaultEpigraphId = chapterId
+    ? buildDefaultEpigraphId({ projectId, chapterId })
+    : null;
+  const requestedEpigraphId = meta.epigraph_id ?? defaultEpigraphId;
+  const epigraphChecksum = buildProseChecksum(prose);
+
+  if (managedStructure) {
+    const existingEpigraphByPath = db.prepare(`
+      SELECT epigraph_id, chapter_id, file_path, prose_checksum
+      FROM epigraphs
+      WHERE project_id = ? AND file_path = ?
+      LIMIT 1
+    `).get(projectId, file);
+    const existingEpigraphById = requestedEpigraphId
+      ? db.prepare(`
+        SELECT e.epigraph_id, e.chapter_id, e.file_path, e.prose_checksum, c.sort_index AS chapter_sort_index
+        FROM epigraphs e
+        LEFT JOIN chapters c
+          ON c.project_id = e.project_id
+         AND c.chapter_id = e.chapter_id
+        WHERE e.project_id = ? AND e.epigraph_id = ?
+        LIMIT 1
+      `).get(projectId, requestedEpigraphId)
+      : null;
+    const existingEpigraphByCompatibleId = existingEpigraphById
+      && (
+        chapterSortIndex == null
+        || existingEpigraphById.chapter_sort_index == null
+        || existingEpigraphById.chapter_sort_index === chapterSortIndex
+      )
+      ? existingEpigraphById
+      : null;
+    const existingEpigraphByChapter = chapterId
+      ? db.prepare(`
+        SELECT epigraph_id, chapter_id, file_path, prose_checksum
+        FROM epigraphs
+        WHERE project_id = ? AND chapter_id = ?
+        ORDER BY epigraph_id
+        LIMIT 2
+      `).all(projectId, chapterId)
+      : [];
+    const existingEpigraphByChapterSort = chapterSortIndex != null
+      ? db.prepare(`
+        SELECT e.epigraph_id, e.chapter_id, e.file_path, e.prose_checksum
+        FROM epigraphs e
+        JOIN chapters c
+          ON c.project_id = e.project_id
+         AND c.chapter_id = e.chapter_id
+        WHERE e.project_id = ? AND c.sort_index = ?
+        ORDER BY e.epigraph_id
+        LIMIT 2
+      `).all(projectId, chapterSortIndex)
+      : [];
+    const movedCandidate = (candidate) => candidate && (!candidate.file_path || !fs.existsSync(candidate.file_path))
+      ? candidate
+      : null;
+    const existingEpigraph = existingEpigraphByPath
+      ?? movedCandidate(existingEpigraphByCompatibleId)
+      ?? (existingEpigraphByChapter.length === 1 ? movedCandidate(existingEpigraphByChapter[0]) : null)
+      ?? (existingEpigraphByChapterSort.length === 1 ? movedCandidate(existingEpigraphByChapterSort[0]) : null);
+
+    if (!existingEpigraph) {
+      return {
+        isStale: 0,
+        skippedAsEpigraph: true,
+        warning: `Managed structure sync ignored file-derived epigraph linkage: ${relativePath}`,
+      };
+    }
+
+    const epigraphIsStale = existingEpigraph.prose_checksum !== null && existingEpigraph.prose_checksum !== epigraphChecksum ? 1 : 0;
+    db.prepare(`
+      UPDATE epigraphs
+      SET body = ?,
+          file_path = ?,
+          prose_checksum = ?,
+          metadata_stale = CASE
+            WHEN ? != prose_checksum THEN 1
+            ELSE metadata_stale
+          END,
+          updated_at = ?
+      WHERE epigraph_id = ? AND project_id = ?
+    `).run(
+      prose,
+      file,
+      epigraphChecksum,
+      epigraphChecksum,
+      updatedAt,
+      existingEpigraph.epigraph_id,
+      projectId
+    );
+
+    return {
+      isStale: epigraphIsStale,
+      skippedAsEpigraph: true,
+      epigraphIndexed: true,
+      chapterId: existingEpigraph.chapter_id,
+      epigraphId: existingEpigraph.epigraph_id,
+      warning: existingEpigraphByPath
+        ? (requestedEpigraphId && requestedEpigraphId !== existingEpigraph.epigraph_id
+          ? `Managed structure sync ignored file-derived epigraph_id '${requestedEpigraphId}': ${relativePath}`
+          : chapterId && chapterId !== existingEpigraph.chapter_id
+            ? `Managed structure sync ignored file-derived epigraph linkage: ${relativePath}`
+            : null)
+        : `Managed structure sync preserved canonical epigraph '${existingEpigraph.epigraph_id}' while refreshing moved file path: ${relativePath}`,
+    };
+  }
+
   const canonicalChapter = chapterId
     ? db.prepare(`SELECT chapter_id FROM chapters WHERE chapter_id = ? AND project_id = ?`).get(chapterId, projectId)
     : null;
@@ -26,9 +136,6 @@ export function indexCanonicalEpigraph(db, {
     return { isStale: 0, skippedAsEpigraph: true, warning: reason };
   }
 
-  const defaultEpigraphId = buildDefaultEpigraphId({ projectId, chapterId });
-  const requestedEpigraphId = meta.epigraph_id ?? defaultEpigraphId;
-  const epigraphChecksum = buildProseChecksum(prose);
   const epigraphById = db.prepare(`
     SELECT epigraph_id, chapter_id, prose_checksum
     FROM epigraphs

package/src/structure/structure-diagnostics.js

@@ -2,6 +2,12 @@ import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
 import yaml from "js-yaml";
+import {
+  buildStructureExport,
+  computeStructureChecksum,
+  defaultStructureExportFileName,
+  STRUCTURE_EXPORT_SCHEMA_VERSION,
+} from "./structure-export.js";
 import {
   inferChapterStructureFromPath,
   normalizeSceneMetaForPath,
@@ -91,6 +97,16 @@ function readIndexedEpigraphRows(db, projectId) {
   `).all(...scope.params);
 }
 
+function readProjectRows(db, projectId) {
+  const scope = projectClause(projectId);
+  return db.prepare(`
+    SELECT project_id
+    FROM projects
+    WHERE 1 = 1${scope.sql}
+    ORDER BY project_id
+  `).all(...scope.params);
+}
+
 function diagnoseUnknownChapterLinks(db, diagnostics, projectId) {
   const sceneScope = projectClause(projectId, "s");
   const scenes = db.prepare(`
@@ -280,7 +296,20 @@ function diagnoseObservedFiles(syncDir, diagnostics, { scenes, epigraphs }) {
   }
 
   for (const epigraph of epigraphs) {
-    if (!epigraph.file_path || !fs.existsSync(epigraph.file_path)) continue;
+    if (!epigraph.file_path || !fs.existsSync(epigraph.file_path)) {
+      addDiagnostic(
+        diagnostics,
+        "indexed_epigraph_file_missing",
+        `Epigraph "${epigraph.epigraph_id}" has an indexed file path that no longer exists.`,
+        {
+          project_id: epigraph.project_id,
+          epigraph_id: epigraph.epigraph_id,
+          file_path: epigraph.file_path,
+        },
+        { nextStep: "Run sync to refresh moved epigraph file paths, then inspect remaining drift." }
+      );
+      continue;
+    }
     if (!isPathInsideSyncDir(syncDir, epigraph.file_path)) {
       addDiagnostic(
         diagnostics,
@@ -334,8 +363,332 @@ function diagnoseObservedFiles(syncDir, diagnostics, { scenes, epigraphs }) {
   }
 }
 
+function resolveStructureExportPath(syncDir, exportDir, projectId) {
+  const resolvedSyncDir = path.resolve(syncDir);
+  const resolvedExportDir = exportDir
+    ? (path.isAbsolute(exportDir) ? path.resolve(exportDir) : path.resolve(resolvedSyncDir, exportDir))
+    : path.resolve(resolvedSyncDir, "structure-exports");
+  const relativeDir = path.relative(resolvedSyncDir, resolvedExportDir);
+  if (relativeDir.startsWith("..") || path.isAbsolute(relativeDir)) {
+    throw new Error(`Structure export directory must be inside sync_dir: ${exportDir}`);
+  }
+  return path.join(resolvedExportDir, defaultStructureExportFileName(projectId));
+}
+
+function readStructureExportFile(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    return {
+      error: error instanceof Error ? error : new Error("Could not read structure export."),
+    };
+  }
+}
+
+function diagnoseStructureExportFileKind(diagnostics, {
+  projectId,
+  exportPath,
+}) {
+  let exportStat;
+  try {
+    exportStat = fs.lstatSync(exportPath);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    addDiagnostic(
+      diagnostics,
+      "structure_export_missing",
+      `Project "${projectId}" does not have a generated structure export.`,
+      {
+        project_id: projectId,
+        export_path: exportPath,
+      },
+      {
+        severity: "info",
+        nextStep: "Run export_structure_snapshot before relying on export-based recovery.",
+      }
+    );
+    return "missing";
+  }
+
+  if (exportStat.isSymbolicLink()) {
+    addDiagnostic(
+      diagnostics,
+      "structure_export_symlink",
+      `Structure export for project "${projectId}" is a symlink, which is not trusted diagnostics input.`,
+      {
+        project_id: projectId,
+        export_path: exportPath,
+      },
+      {
+        nextStep: "Use a regular generated structure export file under WRITING_SYNC_DIR.",
+      }
+    );
+    return "symlink";
+  }
+
+  if (!exportStat.isFile()) {
+    addDiagnostic(
+      diagnostics,
+      "structure_export_not_regular",
+      `Structure export for project "${projectId}" is not a regular file.`,
+      {
+        project_id: projectId,
+        export_path: exportPath,
+      },
+      {
+        nextStep: "Regenerate the export with export_structure_snapshot before using it for recovery.",
+      }
+    );
+    return "not_regular";
+  }
+
+  return "regular";
+}
+
+function diagnoseStructureExports(db, diagnostics, {
+  syncDir,
+  exportDir,
+  projectId,
+}) {
+  if (!syncDir) return [];
+
+  const exportChecks = [];
+  const projects = readProjectRows(db, projectId);
+  for (const project of projects) {
+    const expectedProjectId = project.project_id;
+    let exportPath;
+    try {
+      exportPath = resolveStructureExportPath(syncDir, exportDir, expectedProjectId);
+    } catch {
+      addDiagnostic(
+        diagnostics,
+        "structure_export_invalid_location",
+        `Structure export location for project "${expectedProjectId}" is outside the active sync root.`,
+        {
+          project_id: expectedProjectId,
+          export_dir: exportDir,
+          sync_dir: syncDir,
+        },
+        {
+          nextStep: "Use an export directory inside WRITING_SYNC_DIR before trusting generated structure exports.",
+        }
+      );
+      exportChecks.push({
+        project_id: expectedProjectId,
+        export_path: null,
+        trusted: false,
+        status: "invalid_location",
+      });
+      continue;
+    }
+
+    const exportFileKind = diagnoseStructureExportFileKind(diagnostics, {
+      projectId: expectedProjectId,
+      exportPath,
+    });
+    if (exportFileKind !== "regular") {
+      exportChecks.push({
+        project_id: expectedProjectId,
+        export_path: exportPath,
+        trusted: false,
+        status: exportFileKind,
+      });
+      continue;
+    }
+
+    const parsed = readStructureExportFile(exportPath);
+    if (parsed.error) {
+      addDiagnostic(
+        diagnostics,
+        "structure_export_unreadable",
+        `Structure export for project "${expectedProjectId}" could not be read as JSON.`,
+        {
+          project_id: expectedProjectId,
+          export_path: exportPath,
+          error: parsed.error.message,
+        },
+        {
+          nextStep: "Regenerate the export with export_structure_snapshot before using it for recovery.",
+        }
+      );
+      exportChecks.push({
+        project_id: expectedProjectId,
+        export_path: exportPath,
+        trusted: false,
+        status: "unreadable",
+      });
+      continue;
+    }
+
+    const exportedProjectId = parsed.project?.project_id ?? parsed.export?.project_id ?? null;
+    if (exportedProjectId !== expectedProjectId) {
+      addDiagnostic(
+        diagnostics,
+        "structure_export_project_mismatch",
+        `Structure export for project "${expectedProjectId}" belongs to project "${exportedProjectId ?? "unknown"}".`,
+        {
+          project_id: expectedProjectId,
+          export_path: exportPath,
+          exported_project_id: exportedProjectId,
+        },
+        {
+          nextStep: "Regenerate the export for this project before using it for recovery.",
+        }
+      );
+      exportChecks.push({
+        project_id: expectedProjectId,
+        export_path: exportPath,
+        trusted: false,
+        status: "wrong_project",
+      });
+      continue;
+    }
+
+    const exportedSchemaVersion = parsed.export?.schema_version ?? null;
+    if (exportedSchemaVersion !== STRUCTURE_EXPORT_SCHEMA_VERSION) {
+      addDiagnostic(
+        diagnostics,
+        "structure_export_incompatible_schema",
+        `Structure export for project "${expectedProjectId}" has schema version "${exportedSchemaVersion ?? "unknown"}"; expected "${STRUCTURE_EXPORT_SCHEMA_VERSION}".`,
+        {
+          project_id: expectedProjectId,
+          export_path: exportPath,
+          exported_schema_version: exportedSchemaVersion,
+          expected_schema_version: STRUCTURE_EXPORT_SCHEMA_VERSION,
+        },
+        {
+          nextStep: "Regenerate the export with the current server before using it for recovery.",
+        }
+      );
+      exportChecks.push({
+        project_id: expectedProjectId,
+        export_path: exportPath,
+        trusted: false,
+        status: "incompatible_schema",
+      });
+      continue;
+    }
+
+    let built;
+    try {
+      built = buildStructureExport(db, {
+        projectId: expectedProjectId,
+        syncDir,
+      });
+    } catch (error) {
+      addDiagnostic(
+        diagnostics,
+        "structure_export_current_snapshot_failed",
+        `Could not build current structure snapshot for project "${expectedProjectId}".`,
+        {
+          project_id: expectedProjectId,
+          export_path: exportPath,
+          error_code: "CURRENT_SNAPSHOT_FAILED",
+          error_message: error instanceof Error ? error.message : String(error),
+        },
+        {
+          nextStep: "Repair the canonical project record before trusting structure exports.",
+        }
+      );
+      exportChecks.push({
+        project_id: expectedProjectId,
+        export_path: exportPath,
+        trusted: false,
+        status: "current_snapshot_failed",
+      });
+      continue;
+    }
+    if (!built.ok) {
+      addDiagnostic(
+        diagnostics,
+        "structure_export_current_snapshot_failed",
+        `Could not build current structure snapshot for project "${expectedProjectId}".`,
+        {
+          project_id: expectedProjectId,
+          export_path: exportPath,
+          error_code: built.error.code,
+          error_message: built.error.message,
+        },
+        {
+          nextStep: "Repair the canonical project record before trusting structure exports.",
+        }
+      );
+      exportChecks.push({
+        project_id: expectedProjectId,
+        export_path: exportPath,
+        trusted: false,
+        status: "current_snapshot_failed",
+      });
+      continue;
+    }
+
+    const exportedChecksum = parsed.export?.structure_checksum ?? null;
+    const computedExportChecksum = computeStructureChecksum(parsed);
+    if (!exportedChecksum || exportedChecksum !== computedExportChecksum) {
+      addDiagnostic(
+        diagnostics,
+        "structure_export_checksum_mismatch",
+        `Structure export for project "${expectedProjectId}" does not match its embedded checksum.`,
+        {
+          project_id: expectedProjectId,
+          export_path: exportPath,
+          exported_checksum: exportedChecksum,
+          computed_checksum: computedExportChecksum,
+        },
+        {
+          nextStep: "Regenerate the export with export_structure_snapshot before using it for recovery.",
+        }
+      );
+      exportChecks.push({
+        project_id: expectedProjectId,
+        export_path: exportPath,
+        trusted: false,
+        status: "checksum_mismatch",
+      });
+      continue;
+    }
+
+    const currentChecksum = built.snapshot.export.structure_checksum;
+    if (exportedChecksum !== currentChecksum) {
+      addDiagnostic(
+        diagnostics,
+        "structure_export_stale",
+        `Structure export for project "${expectedProjectId}" is stale relative to current SQLite canonical state.`,
+        {
+          project_id: expectedProjectId,
+          export_path: exportPath,
+          exported_checksum: exportedChecksum,
+          current_checksum: currentChecksum,
+        },
+        {
+          nextStep: "Regenerate the export with export_structure_snapshot, then review the Git diff.",
+        }
+      );
+      exportChecks.push({
+        project_id: expectedProjectId,
+        export_path: exportPath,
+        trusted: false,
+        status: "stale",
+      });
+      continue;
+    }
+
+    exportChecks.push({
+      project_id: expectedProjectId,
+      export_path: exportPath,
+      trusted: true,
+      status: "current",
+      schema_version: exportedSchemaVersion,
+      structure_checksum: currentChecksum,
+    });
+  }
+
+  return exportChecks;
+}
+
 export function runStructureDiagnostics(db, {
   syncDir,
+  structureExportDir = null,
   projectId = null,
 } = {}) {
   const diagnostics = [];
@@ -349,6 +702,12 @@ export function runStructureDiagnostics(db, {
     diagnoseObservedFiles(syncDir, diagnostics, { scenes, epigraphs });
   }
 
+  const structureExports = diagnoseStructureExports(db, diagnostics, {
+    syncDir,
+    exportDir: structureExportDir,
+    projectId,
+  });
+
   diagnostics.sort((a, b) => {
     const projectCompare = String(a.details.project_id ?? "").localeCompare(String(b.details.project_id ?? ""));
     if (projectCompare) return projectCompare;
@@ -363,6 +722,7 @@ export function runStructureDiagnostics(db, {
       project_id: projectId,
       scenes: scenes.length,
       epigraphs: epigraphs.length,
+      structure_exports: structureExports,
     },
     summary: {
       total: diagnostics.length,

package/src/structure/structure-export.js

@@ -45,6 +45,22 @@ function sha256(value) {
   return crypto.createHash("sha256").update(value).digest("hex");
 }
 
+export function computeStructureChecksum(snapshot) {
+  const {
+    export: exportMetadata = {},
+    ...rest
+  } = snapshot ?? {};
+  const {
+    structure_checksum: _structureChecksum,
+    ...checksumExportMetadata
+  } = exportMetadata;
+
+  return sha256(stableStringify({
+    export: checksumExportMetadata,
+    ...rest,
+  }, 0));
+}
+
 export function defaultStructureExportFileName(projectId) {
   const slug = String(projectId ?? "project")
     .toLowerCase()
@@ -173,7 +189,7 @@ export function buildStructureExport(db, { projectId, syncDir }) {
     epigraphs,
   };
 
-  const structureChecksum = sha256(stableStringify(baseSnapshot, 0));
+  const structureChecksum = computeStructureChecksum(baseSnapshot);
   return {
     ok: true,
     snapshot: {