dotmd-cli 0.74.0 → 0.74.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.74.0",
+  "version": "0.74.1",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/atomic-mutation.mjs

@@ -1279,9 +1279,9 @@ export function createFileExclusive(filePath, content, options) {
 }
 
 export function moveFileAtomic(sourcePath, targetPath, render, options) {
-  const { repoRoot, finalize, rollbackFinalize, testHooks, updates = [], creations = [], deletions = [] } = options;
+  const { repoRoot, finalize, rollbackFinalize, testHooks, updates = [], creations = [], deletions = [], guards = [] } = options;
   recoverAbandonedTransactions(repoRoot, options);
-  return withPathLocks([sourcePath, targetPath, ...updates.map(item => item.path), ...creations.map(item => item.path), ...deletions.map(item => item.path)], options, () => {
+  return withPathLocks([sourcePath, targetPath, ...updates.map(item => item.path), ...creations.map(item => item.path), ...deletions.map(item => item.path), ...guards.map(item => item.path)], options, () => {
     testHooks?.afterTransactionPhase?.('lock', { sourcePath, targetPath });
     testHooks?.beforeMoveSnapshot?.({ sourcePath, targetPath });
     const source = snapshotFile(sourcePath);
@@ -1304,6 +1304,15 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
       }
       return { ...item, snapshot };
     });
+    // Read-only participants (see `mutateFileSet`). Checked before the
+    // transaction manifest exists, so a guard conflict can never leave a
+    // transaction to recover from.
+    for (const guard of guards) {
+      const snapshot = snapshotFile(guard.path);
+      if (guard.expectedContent !== undefined && snapshot.content !== guard.expectedContent) {
+        throw new MutationConflictError(`File changed while the move mutation set was being prepared: ${snapshot.path}`);
+      }
+    }
     for (const item of creations) {
       if (existsSync(item.path)) throw new MutationConflictError(`Destination already exists: ${path.resolve(item.path)}`);
     }
@@ -1627,9 +1636,30 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
   });
 }
 
-export function mutateFileSet({ updates = [], creations = [] }, options) {
-  const paths = [...updates.map(item => item.path), ...creations.map(item => item.path)];
+// `guards` are read-only participants: files the mutation's VALIDITY depends on
+// but that it never writes. They take part in locking and in the same
+// compare-and-swap as `updates`, so a mutation decided from a file it doesn't
+// modify cannot land after that file changed underneath it.
+//
+// Without this, a decision read and the write it justifies are two separate
+// steps with nothing holding the gap. A claim that adopts an already-in-session
+// plan writes only the ownership record — so a concurrent `set` releasing that
+// plan could win the status write while the claim still took ownership, leaving
+// a record that owns a plan the file says is `active`. A no-op update on the
+// plan file would close the gap too, but it would rewrite bytes and report the
+// plan as changed to anything counting touched files. A guard says what is meant.
+export function mutateFileSet({ updates = [], creations = [], guards = [] }, options) {
+  const paths = [...updates.map(item => item.path), ...creations.map(item => item.path), ...guards.map(item => item.path)];
   return withPathLocks(paths, options, () => {
+    // Guards are pure preconditions, so they are checked before anything at all
+    // is created — a guard conflict must leave the tree byte-identical, not even
+    // an empty directory behind.
+    for (const guard of guards) {
+      const snapshot = snapshotFile(guard.path);
+      if (guard.expectedContent !== undefined && snapshot.content !== guard.expectedContent) {
+        throw new MutationConflictError(`File changed while the mutation set was being prepared: ${snapshot.path}`);
+      }
+    }
     const createdDirectories = [];
     for (const item of creations) {
       const directory = path.dirname(item.path);
@@ -1654,7 +1684,7 @@ export function mutateFileSet({ updates = [], creations = [] }, options) {
     for (const item of creations) {
       if (existsSync(item.path)) throw new MutationConflictError(`Destination already exists: ${path.resolve(item.path)}`);
     }
-    options.testHooks?.afterSetPreflight?.({ updates: preparedUpdates, creations });
+    options.testHooks?.afterSetPreflight?.({ updates: preparedUpdates, creations, guards });
 
     const committedUpdates = [];
     const committedCreations = [];

package/src/lifecycle.mjs

@@ -107,6 +107,7 @@ function commitLifecycleMutation(filePath, targetPath, config, updates, historyF
         }),
       })), ...additionalUpdates],
       creations: options.creations ?? [],
+      guards: options.guards ?? [],
       gitMove: tracked,
       gitIndex,
       operation: 'lifecycle-move',
@@ -115,12 +116,13 @@ function commitLifecycleMutation(filePath, targetPath, config, updates, historyF
     });
     return { ...result, sourceContent: moveResult.source.content, updatedPaths: moveResult.updatedPaths };
   }
-  if ((options.additionalUpdates?.length ?? 0) > 0 || (options.creations?.length ?? 0) > 0) {
+  if ((options.additionalUpdates?.length ?? 0) > 0 || (options.creations?.length ?? 0) > 0 || (options.guards?.length ?? 0) > 0) {
     const sourceContent = readFileSync(filePath, 'utf8');
     const result = render(sourceContent);
     mutateFileSet({
       updates: [{ path: filePath, expectedContent: sourceContent, content: result.content }, ...(options.additionalUpdates ?? [])],
       creations: options.creations ?? [],
+      guards: options.guards ?? [],
     }, { repoRoot: config.repoRoot, testHooks: options.testHooks });
     return { ...result, sourceContent, updatedPaths: [] };
   }
@@ -767,6 +769,7 @@ export function runArchive(argv, config, opts = {}) {
         createSection: Boolean(note),
         additionalUpdates: [...(opts.additionalUpdates ?? []), ...(releaseUpdate ? [releaseUpdate] : [])],
         creations: opts.creations,
+        guards: opts.guards,
         testHooks: opts.testHooks,
       });
     if (!noIndex && !opts.deferIndex) regenIndex(config);
@@ -833,6 +836,7 @@ export function runArchive(argv, config, opts = {}) {
       testHooks: opts.testHooks,
       additionalUpdates: [...(opts.additionalUpdates ?? []), ...(releaseUpdate ? [releaseUpdate] : [])],
       creations: opts.creations,
+      guards: opts.guards,
       skipInboundRefs: opts.skipInboundRefs,
       bodyTransform: closeoutTemplate ? currentBody => {
         committedCloseoutAction = planCloseoutInjection(currentBody);

package/src/pickup.mjs

@@ -258,19 +258,28 @@ export function preparePlanClaim({ filePath, sourceContent, renderedContent, own
   const content = recordContent({ identity, sessionId, state: 'owned', now,
     claimedAt: ownership && !ownership.corrupt ? ownership.claimedAt : null, operation });
   const updates = [];
+  const guards = [];
   if (renderedContent !== null && renderedContent !== sourceContent) {
     updates.push({ path: filePath, expectedContent: sourceContent, content: renderedContent });
+  } else {
+    // An `adopt` claim writes only the ownership record — the plan is already
+    // `in-session`, so there is nothing to render. The DECISION still rests on
+    // the plan's status, which was read before this mutation was prepared, so
+    // the plan file joins as a read-only guard. Without it, a concurrent
+    // `set active` could win the status write while this claim takes ownership,
+    // leaving a record that owns a plan the file calls `active`.
+    guards.push({ path: filePath, expectedContent: sourceContent });
   }
   const creations = [];
   if (ownership) updates.push({ path: recordPath, expectedContent: ownership.raw, content });
   else creations.push({ path: recordPath, content });
-  return { identity, recordPath, updates, creations, operationId };
+  return { identity, recordPath, updates, creations, guards, operationId };
 }
 
 export function commitPlanClaim(args) {
   const prepared = preparePlanClaim(args);
   mkdirSync(path.dirname(prepared.recordPath), { recursive: true });
-  mutateFileSet({ updates: prepared.updates, creations: prepared.creations }, {
+  mutateFileSet({ updates: prepared.updates, creations: prepared.creations, guards: prepared.guards }, {
     repoRoot: args.config.repoRoot,
     testHooks: args.testHooks,
   });

package/src/prompts.mjs

@@ -289,6 +289,10 @@ export async function consumePrompt(filePath, config, opts) {
     skipInboundRefs: true,
     additionalUpdates: linkedClaim?.prepared?.updates,
     creations: linkedClaim?.prepared?.creations,
+    // An adopt-shaped claim writes no plan content, so the plan file rides
+    // along as a read-only guard — the claim is only valid while the plan still
+    // says what the disposition was read from.
+    guards: linkedClaim?.prepared?.guards,
   });
   const consumedBody = archiveResult?.consumedBody ?? body;