@hanna84/mcp-writing 3.21.2 → 3.22.0

package/src/tools/reference-link-persistence.js

@@ -1,4 +1,4 @@
-import { readMeta, writeMeta, normalizeReferenceLinkList } from "../sync/sync.js";
+import { readSourceMeta, writeMeta, normalizeReferenceLinkList } from "../sync/sync.js";
 
 let savepointCounter = 0;
 
@@ -13,7 +13,7 @@ export function upsertSerializedReferenceLinks(existing, targetDocId, relation,
 }
 
 export function persistSceneReferenceLink({ scenePath, syncDir, targetDocId, relation }) {
-  const { meta } = readMeta(scenePath, syncDir, { writable: true });
+  const { sourceMeta: meta } = readSourceMeta(scenePath, syncDir, { writable: true });
   const existingExplicit = [
     ...(Array.isArray(meta.reference_links) ? meta.reference_links : meta.reference_links ? [meta.reference_links] : []),
     ...(Array.isArray(meta.explicit_reference_links) ? meta.explicit_reference_links : meta.explicit_reference_links ? [meta.explicit_reference_links] : []),
@@ -59,6 +59,11 @@ export function upsertExplicitReferenceLinkRow(
     insertStmt.run(sourceKind, sourceProjectId, sourceId, targetDocId, relation);
   };
 
+  if (db.inTransaction) {
+    runUpsertBody();
+    return;
+  }
+
   if (typeof db.transaction === "function") {
     db.transaction(runUpsertBody)();
     return;

package/src/tools/search.js

@@ -2,7 +2,10 @@ import { z } from "zod";
 import fs from "node:fs";
 import matter from "gray-matter";
 import { readMeta } from "../sync/sync.js";
-import { persistSceneReferenceLink, upsertExplicitReferenceLinkRow } from "./reference-link-persistence.js";
+import {
+  persistSceneReferenceLink,
+  upsertExplicitReferenceLinkRow,
+} from "./reference-link-persistence.js";
 import { resolveValidatedChapterFilter } from "../core/chapter-resolution.js";
 import {
   createToolActor,
@@ -606,7 +609,7 @@ export function registerSearchTools(s, {
   // ---- get_place_sheet -----------------------------------------------------
   s.tool(
     "get_place_sheet",
-    "Get full place details: associated_characters, tags, the canonical sheet content, and any adjacent support notes when the place uses a folder-based layout. Use this when the current scene or question makes the place itself materially relevant. Response shape note: returns a structured envelope (`results`, `total_count`) with one result row.",
+    "Get full place details, including canonical sheet content plus retained sidecar associated_characters and tags as compatibility/review notes. Use connect_character_place_evidence for current scene-backed character/place authority. Response shape note: returns a structured envelope (`results`, `total_count`) with one result row.",
     {
       place_id: z.string().describe("The place_id to look up (e.g. 'place-harbor-district'). Use list_places to find valid IDs."),
     },
@@ -1073,7 +1076,7 @@ export function registerSearchTools(s, {
   // ---- suggest_scene_references --------------------------------------------
   s.tool(
     "suggest_scene_references",
-    "Suggest reference documents for a scene by aggregating links from the scene's characters and places. Returns weighted candidates ranked by how many entities in the scene link to each reference. Excludes any explicit scene → reference links already present. In apply mode, can persist selected suggestions as explicit scene links in one call.",
+    "Suggest reference documents for a scene by aggregating links from the scene's characters and places. Returns weighted candidates ranked by how many entities in the scene link to each reference. Excludes any explicit scene reference links already present. In apply mode, selected links commit to SQLite first, project backups refresh, and scene sidecar/frontmatter output is refreshed only as generated compatibility.",
     {
       scene_id: z.string().describe("Scene ID (e.g. 'sc-011-sebastian')."),
       project_id: z.string().optional().describe("Optional project scope to disambiguate an ambiguous scene_id across projects."),
@@ -1235,40 +1238,13 @@ export function registerSearchTools(s, {
 
 
       if (mode === "apply") {
-        if (!resolvedScene.file_path) {
-          return errorResponse("STALE_PATH", `Scene '${scene_id}' has no indexed file path. Run sync() to refresh.`, {
-            scene_id,
-            project_id: resolvedProjectId,
-          });
-        }
-
-          const toApply = selectApplyCandidates(enriched, selected_doc_ids, max_apply);
-
+        const toApply = selectApplyCandidates(enriched, selected_doc_ids, max_apply);
         const appliedLinks = [];
         const failedLinks = [];
 
-        for (const candidate of toApply) {
-          try {
-            persistSceneReferenceLink({
-              scenePath: resolvedScene.file_path,
-              syncDir: SYNC_DIR,
-              targetDocId: candidate.doc_id,
-              relation: candidate.relation,
-            });
-          } catch (err) {
-            failedLinks.push({
-              target_doc_id: candidate.doc_id,
-              relation: candidate.relation,
-              stage: "metadata",
-              code: err?.code ?? "IO_ERROR",
-              message: err?.code === "ENOENT"
-                ? `Scene file for '${scene_id}' not found at indexed path — run sync() to refresh.`
-                : `Failed to persist scene reference link metadata: ${err.message}`,
-            });
-            continue;
-          }
-
-          try {
+        try {
+          db.exec("BEGIN");
+          for (const candidate of toApply) {
             upsertExplicitReferenceLinkRow(db, {
               sourceKind: "scene",
               sourceProjectId: resolvedProjectId,
@@ -1276,7 +1252,15 @@ export function registerSearchTools(s, {
               targetDocId: candidate.doc_id,
               relation: candidate.relation,
             });
-          } catch (err) {
+          }
+          db.exec("COMMIT");
+        } catch (err) {
+          try {
+            db.exec("ROLLBACK");
+          } catch (rollbackErr) {
+            void rollbackErr;
+          }
+          for (const candidate of toApply) {
             failedLinks.push({
               target_doc_id: candidate.doc_id,
               relation: candidate.relation,
@@ -1284,17 +1268,20 @@ export function registerSearchTools(s, {
               code: err?.code ?? "IO_ERROR",
               message: `Failed to persist scene reference link index row: ${err.message}`,
             });
-            continue;
           }
+        }
 
-          appliedLinks.push({
-            source_kind: "scene",
-            source_project_id: resolvedProjectId,
-            source_id: scene_id,
-            target_doc_id: candidate.doc_id,
-            relation: candidate.relation,
-            origin: "explicit",
-          });
+        if (failedLinks.length === 0) {
+          for (const candidate of toApply) {
+            appliedLinks.push({
+              source_kind: "scene",
+              source_project_id: resolvedProjectId,
+              source_id: scene_id,
+              target_doc_id: candidate.doc_id,
+              relation: candidate.relation,
+              origin: "explicit",
+            });
+          }
         }
 
         const backupResult = appliedLinks.length
@@ -1323,6 +1310,47 @@ export function registerSearchTools(s, {
               backup_warnings: [],
             };
 
+        const compatibilityDiagnostics = [];
+        if (appliedLinks.length) {
+          if (!resolvedScene.file_path) {
+            compatibilityDiagnostics.push({
+              code: "STALE_PATH",
+              severity: "warning",
+              message: `Canonical scene reference link was committed, but scene '${scene_id}' has no indexed file path for generated compatibility output.`,
+              next_step: "Treat SQLite and project backup artifacts as current. Run sync, inspect the indexed scene path, then retry suggest_scene_references in apply mode if compatibility output is still needed.",
+              details: {
+                scene_id,
+                project_id: resolvedProjectId,
+                indexed_path: null,
+              },
+            });
+          } else {
+            for (const link of appliedLinks) {
+              try {
+                persistSceneReferenceLink({
+                  scenePath: resolvedScene.file_path,
+                  syncDir: SYNC_DIR,
+                  targetDocId: link.target_doc_id,
+                  relation: link.relation,
+                });
+              } catch (err) {
+                compatibilityDiagnostics.push({
+                  code: err?.code ?? "COMPATIBILITY_OUTPUT_FAILED",
+                  severity: "warning",
+                  message: `Canonical scene reference link was committed, but generated compatibility metadata for scene '${scene_id}' could not be refreshed: ${err.message}`,
+                  next_step: "Treat SQLite and project backup artifacts as current. Run sync, inspect the indexed scene path, then retry suggest_scene_references in apply mode if compatibility output is still needed.",
+                  details: {
+                    scene_id,
+                    project_id: resolvedProjectId,
+                    target_doc_id: link.target_doc_id,
+                    indexed_path: resolvedScene.file_path,
+                  },
+                });
+              }
+            }
+          }
+        }
+
         return {
           content: [{
             type: "text",
@@ -1336,6 +1364,18 @@ export function registerSearchTools(s, {
               applied_links: appliedLinks,
               failed_count: failedLinks.length,
               failed_links: failedLinks,
+              mutation_order: [
+                "validated_request",
+                "sqlite_commit",
+                "project_backup_refresh",
+                "compatibility_output_refresh",
+              ],
+              compatibility_output: {
+                generated_transparency: true,
+                mutation_surface: false,
+                refreshed: compatibilityDiagnostics.length === 0,
+              },
+              compatibility_diagnostics: compatibilityDiagnostics,
               operation_history: backupResult.operation_history,
               backup_refresh: backupResult.backup_refresh,
               backup_warnings: backupResult.backup_warnings,

package/src/tools/sync.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { syncAll, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath, isManagedStructureProject } from "../sync/sync.js";
+import { syncAll, writeMeta, readSourceMeta, indexSceneFile, normalizeSceneMetaForPath, isManagedStructureProject } from "../sync/sync.js";
 import { importScrivenerSync, validateProjectId } from "../sync/importer.js";
 import { runStructureDiagnostics } from "../structure/structure-diagnostics.js";
 import {
@@ -676,7 +676,7 @@ export function registerSyncTools(s, {
 
   s.tool(
     "enrich_scene_characters_batch",
-    "Start an asynchronous batch job that infers scene character mentions and updates scene metadata links. Version 1 uses canonical character names only (no aliases). Defaults to dry_run=true.",
+    "Start an asynchronous prose-derived relationship repair job that infers scene character mentions and updates scene character links. Defaults to dry_run=true; apply mode retains scene sidecar characters as compatibility output, then syncs SQLite scene_characters and refreshes project backups for changed scenes.",
     {
       project_id: z.string().describe("Project ID (e.g. 'the-lamb' or 'universe-1/book-1-the-lamb')."),
       scene_ids: z.array(z.string()).optional().describe("Optional allowlist of scene IDs to process before other filters are applied."),
@@ -684,7 +684,7 @@ export function registerSyncTools(s, {
       chapter: z.number().int().optional().describe("Optional read-scope compatibility alias resolved through canonical chapter identity. Not a structural mutation target."),
       chapter_id: z.string().optional().describe("Optional canonical chapter identifier."),
       only_stale: z.boolean().optional().describe("If true, only process scenes currently marked metadata_stale."),
-      dry_run: z.boolean().optional().describe("If true (default), returns preview results without writing sidecars."),
+      dry_run: z.boolean().optional().describe("If true (default), returns preview results without writing compatibility metadata."),
       replace_mode: z.enum(["merge", "replace"]).optional().describe("merge (default): add inferred IDs; replace: overwrite characters with inferred IDs."),
       max_scenes: z.number().int().positive().optional().describe("Hard guardrail for resolved scene count (default: 200)."),
       include_match_details: z.boolean().optional().describe("If true, include extra match diagnostics per scene."),
@@ -805,6 +805,18 @@ export function registerSyncTools(s, {
             });
             completedJob.result = {
               ...completedJob.result,
+              mutation_order: [
+                "prose_inference",
+                "compatibility_output_refresh",
+                "sqlite_sync_index",
+                "project_backup_refresh",
+              ],
+              compatibility_output: {
+                role: "prose_derived_repair_output",
+                generated_transparency: true,
+                mutation_surface: false,
+                refreshed: true,
+              },
               ...backupMutationFields(backupResult),
             };
           }
@@ -951,20 +963,21 @@ export function registerSyncTools(s, {
       try {
         const raw = fs.readFileSync(scene.file_path, "utf8");
         const { content: prose } = matter(raw);
-        const { meta } = readMeta(scene.file_path, SYNC_DIR, { writable: true });
+        const { sourceMeta: meta } = readSourceMeta(scene.file_path, SYNC_DIR, { writable: true });
 
         const inferredLogline = deriveLoglineFromProse(prose);
         const inferredCharacters = inferCharacterIdsFromProse(db, prose, scene.project_id);
 
-        const updatedMeta = normalizeSceneMetaForPath(SYNC_DIR, scene.file_path, {
+        const sourceUpdatedMeta = {
           ...meta,
           ...(inferredLogline ? { logline: inferredLogline } : {}),
           ...((inferredCharacters.length > 0 || (meta.characters?.length ?? 0) > 0)
             ? { characters: inferredCharacters.length > 0 ? inferredCharacters : meta.characters }
             : {}),
-        }).meta;
+        };
+        const updatedMeta = normalizeSceneMetaForPath(SYNC_DIR, scene.file_path, sourceUpdatedMeta).meta;
 
-        writeMeta(scene.file_path, updatedMeta, { syncDir: SYNC_DIR });
+        writeMeta(scene.file_path, sourceUpdatedMeta, { syncDir: SYNC_DIR });
         indexSceneFile(db, SYNC_DIR, scene.file_path, updatedMeta, prose, {
           managedStructure: isManagedStructureProject(db, scene.project_id),
         });

package/src/workflows/workflow-catalogue.js

@@ -63,6 +63,23 @@ export const WORKFLOW_CATALOGUE = [
       { tool: "get_arc", note: "Use when the thread question is really a character-progression question and character context is the better structural entry point." },
     ],
   },
+  {
+    id: "relationship_alignment",
+    label: "Track and repair story relationships",
+    use_when: "Use when the user wants to track an arc, link evidence, review stale relationships, repair metadata parity, or prepare generated recovery material for relationship metadata.",
+    steps: [
+      { tool: "find_scenes", note: "Identify scene_id and project_id from story context before recording relationships." },
+      { tool: "track_thread_arc", note: "Use when a scene should carry a storyline, subplot, setup, escalation, reveal, reversal, payoff, or other thread beat." },
+      { tool: "connect_character_place_evidence", note: "Use when a scene proves a character/place association; SQLite scene relationship indexes commit first and sidecar characters/places remain generated compatibility output." },
+      { tool: "record_character_relationship_beat", note: "Use when a scene proves a relationship beat between two characters without exposing the character_relationships table." },
+      { tool: "link_reference_evidence", note: "Use when scene, character, place, or reference evidence should point to a reference document; SQLite commits first and compatibility output is generated transparency." },
+      { tool: "audit_relationship_metadata", note: "Use before repair work to review stale relationship indexes and sidecar-only compatibility notes without mutating canonical state." },
+      { tool: "suggest_scene_references", note: "Use preview first to review candidate scene-reference links from character/place evidence; use apply only after the relationship outcome is intended." },
+      { tool: "enrich_scene_characters_batch", note: "Use dry_run first when prose-derived character relationship parity needs repair across multiple scenes; apply mode syncs SQLite after compatibility output and refreshes backups for changed scenes." },
+      { tool: "diagnose_project_backups", note: "Relationship mutation tools refresh project backups after canonical commits; run this if backup_warnings were returned or recovery readiness matters." },
+      { tool: "export_project_backup", note: "Prepare a deterministic recovery snapshot from SQLite canonical state; editing generated backup files does not mutate relationships." },
+    ],
+  },
   {
     id: "parity_recovery",
     label: "Recover metadata parity",
@@ -70,9 +87,11 @@ export const WORKFLOW_CATALOGUE = [
     steps: [
       { tool: "sync", note: "Refresh the index and use the result as the main signal that material has changed or parity may need attention." },
       { tool: "diagnose_structure", note: "Use when sync warning summaries suggest chapter, epigraph, folder-derived, or generated-export drift that should be understood before repair." },
+      { tool: "audit_relationship_metadata", note: "Use when parity questions involve stale relationship indexes, character/place sidecar notes, sidecar threads, or relationship recovery readiness." },
       { tool: "enrich_scene", note: "Use for lightweight opportunistic recovery when the current task is already touching a specific low-parity scene." },
       { tool: "enrich_scene_characters_batch", note: "Use when recovery scope is broad enough to justify focused catch-up work; prefer dry_run first." },
-      { tool: "suggest_scene_references", note: "Use when low parity is specifically about missing scene-to-reference relationships." },
+      { tool: "suggest_scene_references", note: "Use when low parity is specifically about missing scene-to-reference relationships; apply mode commits SQLite first and refreshes compatibility output as generated transparency." },
+      { tool: "link_reference_evidence", note: "Use when the repair is a known evidence relationship rather than a suggestion-review workflow." },
     ],
   },
   {