seekstone 0.10.0 → 0.11.0

package/dist/index.js

@@ -74,7 +74,7 @@ Docs: https://github.com/shaqmughal/seekstone`;
 }
 
 // src/tools/append_note.ts
-import { readFile, writeFile } from "fs/promises";
+import { readFile } from "fs/promises";
 import { join } from "path";
 
 // ../core/src/frontmatter.ts
@@ -143,6 +143,34 @@ function parseFrontmatter(text) {
 // src/tools/append_note.ts
 import { z } from "zod";
 
+// src/atomic-write.ts
+import { rename, writeFile } from "fs/promises";
+async function atomicWrite(absPath, content) {
+  const tmpPath = `${absPath}.seekstone-tmp`;
+  await writeFile(tmpPath, content, "utf8");
+  await rename(tmpPath, absPath);
+}
+
+// src/content-hash.ts
+import { createHash } from "crypto";
+function contentHash(raw) {
+  return createHash("sha256").update(raw).digest("hex");
+}
+function assertHashMatch(raw, prevHash, path2) {
+  const actual = contentHash(raw);
+  if (actual !== prevHash) {
+    throw new Error(
+      JSON.stringify({
+        error: "hash_conflict",
+        path: path2,
+        expected: prevHash,
+        actual,
+        hint: "Note changed on disk since it was read. Re-read it and retry with the new contentHash."
+      })
+    );
+  }
+}
+
 // src/policy.ts
 import picomatch from "picomatch";
 function parseWritePolicy(env) {
@@ -177,6 +205,9 @@ var AppendNoteInput = z.object({
   path: z.string().describe("Vault-relative path to the note."),
   content: z.string().min(1).describe(
     "Text to append to the note body. Will be separated from existing content by a blank line."
+  ),
+  prevHash: z.string().optional().describe(
+    "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
   )
 });
 async function appendNote(ctx2, input) {
@@ -186,6 +217,7 @@ async function appendNote(ctx2, input) {
   }
   assertWritable(ctx2.policy, input.path);
   const original = await readFile(absPath, "utf8");
+  if (input.prevHash !== void 0) assertHashMatch(original, input.prevHash, input.path);
   const fm = parseFrontmatter(original);
   const body = fm.body.endsWith("\n") ? fm.body : `${fm.body}
 `;
@@ -193,17 +225,21 @@ async function appendNote(ctx2, input) {
   const newBody = `${body}${separator}${input.content}`;
   const header = original.slice(0, fm.bodyStart);
   const newContent = `${header}${newBody}`;
-  await writeFile(absPath, newContent, "utf8");
+  await atomicWrite(absPath, newContent);
   const cached = ctx2.notes.get(input.path);
   if (cached) {
     cached.body = newBody;
     cached.raw = newContent;
   }
-  return { path: input.path, bytesWritten: Buffer.byteLength(newContent, "utf8") };
+  return {
+    path: input.path,
+    bytesWritten: Buffer.byteLength(newContent, "utf8"),
+    contentHash: contentHash(newContent)
+  };
 }
 
 // src/tools/create_note.ts
-import { access, mkdir, writeFile as writeFile2 } from "fs/promises";
+import { access, mkdir, readFile as readFile2 } from "fs/promises";
 import { dirname, join as join2 } from "path";
 import { stringify as stringifyYaml } from "yaml";
 import { z as z2 } from "zod";
@@ -282,9 +318,17 @@ var CreateNoteInput = z2.object({
   ),
   content: z2.string().default("").describe("Body content for the note."),
   frontmatter: z2.record(z2.string(), z2.unknown()).optional().describe("Frontmatter key-value pairs to write as a YAML block at the top of the note."),
-  overwrite: z2.boolean().default(false).describe("Overwrite an existing note. Defaults to false \u2014 throws if the note already exists.")
+  overwrite: z2.boolean().default(false).describe(
+    "Overwrite an existing note. Defaults to false \u2014 throws if the note already exists."
+  ),
+  prevHash: z2.string().optional().describe(
+    "Optional compare-and-swap guard for overwrite: true \u2014 the contentHash of the note being replaced. Fails with hash_conflict if it changed since it was read."
+  )
+}).refine((v) => v.prevHash === void 0 || v.overwrite === true, {
+  message: "prevHash only makes sense with overwrite: true (a fresh create has no prior version)."
 });
-async function createNote(ctx2, input) {
+async function createNote(ctx2, rawInput) {
+  const input = CreateNoteInput.parse(rawInput);
   const absPath = join2(ctx2.vaultRoot, input.path);
   if (!absPath.startsWith(ctx2.vaultRoot)) {
     throw new Error(`Path outside vault: ${input.path}`);
@@ -297,6 +341,22 @@ async function createNote(ctx2, input) {
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
     }
+  } else if (input.prevHash !== void 0) {
+    let existing;
+    try {
+      existing = await readFile2(absPath, "utf8");
+    } catch {
+      throw new Error(
+        JSON.stringify({
+          error: "hash_conflict",
+          path: input.path,
+          expected: input.prevHash,
+          actual: null,
+          hint: "The note no longer exists on disk. Re-check before overwriting."
+        })
+      );
+    }
+    assertHashMatch(existing, input.prevHash, input.path);
   }
   let raw = "";
   if (input.frontmatter && Object.keys(input.frontmatter).length > 0) {
@@ -306,30 +366,112 @@ ${stringifyYaml(input.frontmatter)}---
   }
   raw += input.content ?? "";
   await mkdir(dirname(absPath), { recursive: true });
-  await writeFile2(absPath, raw, "utf8");
+  await atomicWrite(absPath, raw);
   upsertDoc(ctx2, buildDoc(input.path, raw));
-  return { path: input.path, bytesWritten: Buffer.byteLength(raw, "utf8") };
+  return {
+    path: input.path,
+    bytesWritten: Buffer.byteLength(raw, "utf8"),
+    contentHash: contentHash(raw)
+  };
 }
 
 // src/tools/delete_note.ts
-import { rm } from "fs/promises";
-import { join as join3 } from "path";
+import { access as access2, mkdir as mkdir2, rename as rename2, rm } from "fs/promises";
+import { basename as basename2, extname as extname2, join as join3 } from "path";
 import { z as z3 } from "zod";
+
+// src/index/resolve.ts
+function resolveLink(target, notes2) {
+  if (notes2.has(target)) return target;
+  const withMd = `${target}.md`;
+  if (notes2.has(withMd)) return withMd;
+  const targetLower = target.toLowerCase();
+  const targetBase = (target.split("/").pop() ?? target).toLowerCase();
+  for (const path2 of notes2.keys()) {
+    const pathNoExt = path2.replace(/\.md$/i, "");
+    if (pathNoExt.toLowerCase() === targetLower) return path2;
+    const pathBase = (pathNoExt.split("/").pop() ?? pathNoExt).toLowerCase();
+    if (pathBase === targetBase) return path2;
+  }
+  return void 0;
+}
+
+// src/index/backlinks.ts
+function removeNoteBacklinks(ctx2, relPath) {
+  const oldDoc = ctx2.notes.get(relPath);
+  if (oldDoc === void 0) return;
+  for (const link of extractLinksWithLines(oldDoc.raw)) {
+    const resolved = resolveLink(link.target, ctx2.notes);
+    if (resolved === void 0) continue;
+    const arr = ctx2.backlinks.get(resolved);
+    if (arr === void 0) continue;
+    const filtered = arr.filter((r) => r.path !== relPath);
+    ctx2.backlinks.set(resolved, filtered);
+  }
+}
+function addNoteBacklinks(ctx2, relPath, raw) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const link of extractLinksWithLines(raw)) {
+    const resolved = resolveLink(link.target, ctx2.notes);
+    if (resolved === void 0) continue;
+    const dedupeKey = `${relPath}\0${resolved}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    let arr = ctx2.backlinks.get(resolved);
+    if (arr === void 0) {
+      arr = [];
+      ctx2.backlinks.set(resolved, arr);
+    }
+    const ref = { path: relPath, line: link.line, linkType: link.linkType };
+    arr.push(ref);
+    arr.sort((a, b) => a.path.localeCompare(b.path));
+  }
+}
+
+// src/tools/delete_note.ts
 var DeleteNoteInput = z3.object({
-  path: z3.string().describe("Vault-relative path of the note to delete.")
+  path: z3.string().describe("Vault-relative path of the note to delete."),
+  permanent: z3.boolean().default(false).describe(
+    "Permanently remove the note instead of moving it to the vault .trash/ folder. Defaults to false \u2014 deletes are recoverable."
+  )
 });
-async function deleteNote(ctx2, input) {
+async function freeTrashPath(vaultRoot2, noteBase) {
+  const ext = extname2(noteBase);
+  const stem = noteBase.slice(0, noteBase.length - ext.length);
+  let candidate = `.trash/${noteBase}`;
+  for (; ; ) {
+    try {
+      await access2(join3(vaultRoot2, candidate));
+    } catch {
+      return candidate;
+    }
+    candidate = `.trash/${stem}.${Date.now()}${ext}`;
+  }
+}
+async function deleteNote(ctx2, rawInput) {
+  const input = DeleteNoteInput.parse(rawInput);
   const absPath = join3(ctx2.vaultRoot, input.path);
   if (!absPath.startsWith(ctx2.vaultRoot)) {
     throw new Error(`Path outside vault: ${input.path}`);
   }
   assertWritable(ctx2.policy, input.path);
-  await rm(absPath);
+  let trashedTo;
+  if (input.permanent) {
+    await rm(absPath);
+  } else {
+    await access2(absPath);
+    await mkdir2(join3(ctx2.vaultRoot, ".trash"), { recursive: true });
+    trashedTo = await freeTrashPath(ctx2.vaultRoot, basename2(input.path));
+    await rename2(absPath, join3(ctx2.vaultRoot, trashedTo));
+  }
+  removeNoteBacklinks(ctx2, input.path);
   if (ctx2.notes.has(input.path)) {
     ctx2.index.discard(input.path);
     ctx2.notes.delete(input.path);
   }
-  return { path: input.path };
+  const result = { path: input.path, permanent: input.permanent };
+  if (trashedTo !== void 0) result.trashedTo = trashedTo;
+  return result;
 }
 
 // src/tools/get_backlinks.ts
@@ -372,24 +514,6 @@ function getBacklinks(ctx2, input) {
 // src/tools/get_links.ts
 import { join as join5 } from "path";
 import { z as z5 } from "zod";
-
-// src/index/resolve.ts
-function resolveLink(target, notes2) {
-  if (notes2.has(target)) return target;
-  const withMd = `${target}.md`;
-  if (notes2.has(withMd)) return withMd;
-  const targetLower = target.toLowerCase();
-  const targetBase = (target.split("/").pop() ?? target).toLowerCase();
-  for (const path2 of notes2.keys()) {
-    const pathNoExt = path2.replace(/\.md$/i, "");
-    if (pathNoExt.toLowerCase() === targetLower) return path2;
-    const pathBase = (pathNoExt.split("/").pop() ?? pathNoExt).toLowerCase();
-    if (pathBase === targetBase) return path2;
-  }
-  return void 0;
-}
-
-// src/tools/get_links.ts
 var GetLinksInput = z5.object({
   path: z5.string().describe("Vault-relative path to the note.")
 });
@@ -481,42 +605,10 @@ function listTags(ctx2, input) {
 }
 
 // src/tools/move_note.ts
-import { access as access2, mkdir as mkdir2, rename, writeFile as writeFile3 } from "fs/promises";
+import { access as access3, mkdir as mkdir3, rename as rename3 } from "fs/promises";
 import { dirname as dirname2, join as join6 } from "path";
 import { z as z8 } from "zod";
 
-// src/index/backlinks.ts
-function removeNoteBacklinks(ctx2, relPath) {
-  const oldDoc = ctx2.notes.get(relPath);
-  if (oldDoc === void 0) return;
-  for (const link of extractLinksWithLines(oldDoc.raw)) {
-    const resolved = resolveLink(link.target, ctx2.notes);
-    if (resolved === void 0) continue;
-    const arr = ctx2.backlinks.get(resolved);
-    if (arr === void 0) continue;
-    const filtered = arr.filter((r) => r.path !== relPath);
-    ctx2.backlinks.set(resolved, filtered);
-  }
-}
-function addNoteBacklinks(ctx2, relPath, raw) {
-  const seen = /* @__PURE__ */ new Set();
-  for (const link of extractLinksWithLines(raw)) {
-    const resolved = resolveLink(link.target, ctx2.notes);
-    if (resolved === void 0) continue;
-    const dedupeKey = `${relPath}\0${resolved}`;
-    if (seen.has(dedupeKey)) continue;
-    seen.add(dedupeKey);
-    let arr = ctx2.backlinks.get(resolved);
-    if (arr === void 0) {
-      arr = [];
-      ctx2.backlinks.set(resolved, arr);
-    }
-    const ref = { path: relPath, line: link.line, linkType: link.linkType };
-    arr.push(ref);
-    arr.sort((a, b) => a.path.localeCompare(b.path));
-  }
-}
-
 // src/tools/rewrite_links.ts
 import { posix } from "path";
 var WIKI_RE = /(!?)\[\[([^\]|#\n]{1,512})(#[^\]|\n]{1,512})?(\|[^\]\n]{1,512})?\]\]/g;
@@ -625,13 +717,13 @@ async function moveNote(ctx2, rawInput) {
   assertWritable(ctx2.policy, input.from);
   assertWritable(ctx2.policy, input.to);
   try {
-    await access2(absFrom);
+    await access3(absFrom);
   } catch {
     throw new Error(`Note not found: ${input.from}`);
   }
   if (!input.overwrite) {
     try {
-      await access2(absTo);
+      await access3(absTo);
       throw new Error(
         `Destination already exists: ${input.to}. Pass overwrite: true to replace it.`
       );
@@ -649,8 +741,8 @@ async function moveNote(ctx2, rawInput) {
     }
     candidates.delete(input.from);
   }
-  await mkdir2(dirname2(absTo), { recursive: true });
-  await rename(absFrom, absTo);
+  await mkdir3(dirname2(absTo), { recursive: true });
+  await rename3(absFrom, absTo);
   const raw = ctx2.notes.get(input.from)?.raw ?? "";
   removeNoteBacklinks(ctx2, input.from);
   if (ctx2.notes.has(input.from)) {
@@ -679,7 +771,7 @@ async function moveNote(ctx2, rawInput) {
     );
     removeNoteBacklinks(ctx2, path2);
     if (count > 0) {
-      await writeFile3(join6(ctx2.vaultRoot, path2), content, "utf8");
+      await atomicWrite(join6(ctx2.vaultRoot, path2), content);
       upsertDoc(ctx2, buildDoc(path2, content));
       notesRewritten++;
       linksRewritten += count;
@@ -695,7 +787,7 @@ async function moveNote(ctx2, rawInput) {
 }
 
 // src/tools/outline_note.ts
-import { readFile as readFile2 } from "fs/promises";
+import { readFile as readFile3 } from "fs/promises";
 import { join as join7 } from "path";
 
 // ../core/src/outline.ts
@@ -757,7 +849,7 @@ async function outlineNote(ctx2, input) {
   if (!absPath.startsWith(ctx2.vaultRoot)) {
     throw new Error(`Path outside vault: ${input.path}`);
   }
-  const raw = await readFile2(absPath, "utf8");
+  const raw = await readFile3(absPath, "utf8");
   return buildOutline(raw, {
     includeBlocks: input.includeBlocks,
     includeSizes: input.includeSizes
@@ -765,7 +857,7 @@ async function outlineNote(ctx2, input) {
 }
 
 // src/tools/patch_frontmatter.ts
-import { readFile as readFile3, writeFile as writeFile4 } from "fs/promises";
+import { readFile as readFile4 } from "fs/promises";
 import { join as join8 } from "path";
 import { parseDocument } from "yaml";
 import { z as z10 } from "zod";
@@ -773,6 +865,9 @@ var PatchFrontmatterInput = z10.object({
   path: z10.string().describe("Vault-relative path to the note."),
   patch: z10.record(z10.string(), z10.unknown()).describe(
     "Key-value pairs to set in the frontmatter. Existing keys not in the patch are unchanged. Pass null as a value to remove a key."
+  ),
+  prevHash: z10.string().optional().describe(
+    "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
   )
 });
 async function patchFrontmatter(ctx2, input) {
@@ -781,7 +876,8 @@ async function patchFrontmatter(ctx2, input) {
     throw new Error(`Path outside vault: ${input.path}`);
   }
   assertWritable(ctx2.policy, input.path);
-  const original = await readFile3(absPath, "utf8");
+  const original = await readFile4(absPath, "utf8");
+  if (input.prevHash !== void 0) assertHashMatch(original, input.prevHash, input.path);
   const fm = parseFrontmatter(original);
   const keysChanged = [];
   const keysAdded = [];
@@ -823,18 +919,24 @@ ${original}`;
     const tail = opensWithCRLF ? "---\r\n" : "---\n";
     newContent = `${head}${doc.toString()}${tail}${fm.body}`;
   }
-  await writeFile4(absPath, newContent, "utf8");
+  await atomicWrite(absPath, newContent);
   const cached = ctx2.notes.get(input.path);
   if (cached) {
     const updated = parseFrontmatter(newContent);
     cached.raw = newContent;
     cached.fmKeys = updated.keys.join(" ");
   }
-  return { path: input.path, keysChanged, keysAdded, keysRemoved };
+  return {
+    path: input.path,
+    keysChanged,
+    keysAdded,
+    keysRemoved,
+    contentHash: contentHash(newContent)
+  };
 }
 
 // src/tools/patch_note.ts
-import { readFile as readFile4, rename as rename2, writeFile as writeFile5 } from "fs/promises";
+import { readFile as readFile5 } from "fs/promises";
 import { join as join9 } from "path";
 import { z as z11 } from "zod";
 var PatchNoteInput = z11.object({
@@ -849,6 +951,9 @@ var PatchNoteInput = z11.object({
   content: z11.string().min(1).describe("Content to insert or replace with."),
   createIfMissing: z11.boolean().default(false).describe(
     "If the heading target is not found, append a new heading (level 2) + content. Only valid for heading targets."
+  ),
+  prevHash: z11.string().optional().describe(
+    "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
   )
 });
 function lineEnd(raw, offset) {
@@ -860,18 +965,14 @@ function lineStart(raw, offset) {
   const prev = raw.lastIndexOf("\n", offset - 1);
   return prev === -1 ? 0 : prev + 1;
 }
-async function atomicWrite(absPath, content) {
-  const tmpPath = `${absPath}.seekstone-patch-tmp`;
-  await writeFile5(tmpPath, content, "utf8");
-  await rename2(tmpPath, absPath);
-}
 async function patchNote(ctx2, input) {
   const absPath = join9(ctx2.vaultRoot, input.path);
   if (!absPath.startsWith(ctx2.vaultRoot)) {
     throw new Error(`Path outside vault: ${input.path}`);
   }
   assertWritable(ctx2.policy, input.path);
-  const raw = await readFile4(absPath, "utf8");
+  const raw = await readFile5(absPath, "utf8");
+  if (input.prevHash !== void 0) assertHashMatch(raw, input.prevHash, input.path);
   const fm = parseFrontmatter(raw);
   const originalFmRegion = raw.slice(0, fm.bodyStart);
   const outline = buildOutline(raw, { includeBlocks: true });
@@ -899,7 +1000,8 @@ ${input.content}${contentNl}`;
             line: newContent2.slice(0, headingOffset).split("\n").length,
             byteOffset: headingOffset
           },
-          frontmatterUnchanged: true
+          frontmatterUnchanged: true,
+          contentHash: contentHash(newContent2)
         };
       }
       throw new Error(
@@ -964,11 +1066,12 @@ ${input.content}${contentNl}`;
     path: input.path,
     bytesWritten: Buffer.byteLength(newContent, "utf8"),
     targetResolvedAt: resolvedAt,
-    frontmatterUnchanged: true
+    frontmatterUnchanged: true,
+    contentHash: contentHash(newContent)
   };
 }
 async function verifyFrontmatter(absPath, originalFmRegion) {
-  const written = await readFile4(absPath, "utf8");
+  const written = await readFile5(absPath, "utf8");
   if (written.slice(0, originalFmRegion.length) !== originalFmRegion) {
     throw new Error("Write-safety violation: frontmatter region changed unexpectedly");
   }
@@ -983,7 +1086,7 @@ function updateCache(ctx2, path2, newContent, bodyStart) {
 }
 
 // src/tools/periodic_note.ts
-import { access as access3, mkdir as mkdir3, readFile as readFile5, writeFile as writeFile6 } from "fs/promises";
+import { access as access4, mkdir as mkdir4, readFile as readFile6 } from "fs/promises";
 import { dirname as dirname3, join as join10 } from "path";
 import { z as z12 } from "zod";
 var PERIOD = z12.enum(["daily", "weekly", "monthly", "quarterly", "yearly"]);
@@ -996,7 +1099,7 @@ var DEFAULTS = {
 };
 async function readJson(absPath) {
   try {
-    return JSON.parse(await readFile5(absPath, "utf8"));
+    return JSON.parse(await readFile6(absPath, "utf8"));
   } catch {
     return null;
   }
@@ -1069,7 +1172,7 @@ async function getPeriodicNote(ctx2, rawInput) {
   if (!abs.startsWith(ctx2.vaultRoot)) throw new Error(`Path outside vault: ${path2}`);
   let existed = false;
   try {
-    await access3(abs);
+    await access4(abs);
     existed = true;
   } catch {
   }
@@ -1084,21 +1187,24 @@ async function getPeriodicNote(ctx2, rawInput) {
     );
     if (templateAbs.startsWith(ctx2.vaultRoot)) {
       try {
-        body = await readFile5(templateAbs, "utf8");
+        body = await readFile6(templateAbs, "utf8");
       } catch {
       }
     }
   }
-  await mkdir3(dirname3(abs), { recursive: true });
-  await writeFile6(abs, body, "utf8");
+  await mkdir4(dirname3(abs), { recursive: true });
+  await atomicWrite(abs, body);
   upsertDoc(ctx2, buildDoc(path2, body));
-  return { path: path2, existed: false, created: true };
+  return { path: path2, existed: false, created: true, contentHash: contentHash(body) };
 }
 var AppendPeriodicNoteInput = z12.object({
   period: PERIOD.default("daily").describe("Period type. Default: daily."),
   date: z12.string().optional().describe("ISO date string (YYYY-MM-DD). Defaults to today."),
   content: z12.string().min(1).describe("Text to append to the note body. Separated from existing content by a blank line."),
-  createIfMissing: z12.boolean().default(true).describe("Create the note if it does not exist before appending. Default true.")
+  createIfMissing: z12.boolean().default(true).describe("Create the note if it does not exist before appending. Default true."),
+  prevHash: z12.string().optional().describe(
+    "Optional compare-and-swap guard: the contentHash from a prior read of the resolved periodic note. Fails with hash_conflict if it changed since."
+  )
 });
 async function appendPeriodicNote(ctx2, rawInput) {
   const input = AppendPeriodicNoteInput.parse(rawInput);
@@ -1110,14 +1216,30 @@ async function appendPeriodicNote(ctx2, rawInput) {
   assertWritable(ctx2.policy, path2);
   let original = "";
   try {
-    original = await readFile5(abs, "utf8");
+    original = await readFile6(abs, "utf8");
+    if (input.prevHash !== void 0) assertHashMatch(original, input.prevHash, path2);
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
+    if (input.prevHash !== void 0) {
+      throw new Error(
+        JSON.stringify({
+          error: "hash_conflict",
+          path: path2,
+          expected: input.prevHash,
+          actual: null,
+          hint: "The periodic note no longer exists on disk. Re-read before retrying."
+        })
+      );
+    }
     if (!input.createIfMissing) throw new Error(`Periodic note not found: ${path2}`);
-    await mkdir3(dirname3(abs), { recursive: true });
-    await writeFile6(abs, input.content, "utf8");
+    await mkdir4(dirname3(abs), { recursive: true });
+    await atomicWrite(abs, input.content);
     upsertDoc(ctx2, buildDoc(path2, input.content));
-    return { path: path2, bytesWritten: Buffer.byteLength(input.content, "utf8") };
+    return {
+      path: path2,
+      bytesWritten: Buffer.byteLength(input.content, "utf8"),
+      contentHash: contentHash(input.content)
+    };
   }
   const fm = parseFrontmatter(original);
   const body = fm.body.endsWith("\n") ? fm.body : `${fm.body}
@@ -1126,13 +1248,17 @@ async function appendPeriodicNote(ctx2, rawInput) {
   const newBody = `${body}${separator}${input.content}`;
   const header = original.slice(0, fm.bodyStart);
   const newRaw = `${header}${newBody}`;
-  await writeFile6(abs, newRaw, "utf8");
+  await atomicWrite(abs, newRaw);
   const cached = ctx2.notes.get(path2);
   if (cached) {
     cached.body = newBody;
     cached.raw = newRaw;
   }
-  return { path: path2, bytesWritten: Buffer.byteLength(newRaw, "utf8") };
+  return {
+    path: path2,
+    bytesWritten: Buffer.byteLength(newRaw, "utf8"),
+    contentHash: contentHash(newRaw)
+  };
 }
 
 // src/tools/query_notes.ts
@@ -1341,7 +1467,7 @@ function queryNotes(ctx2, input) {
 }
 
 // src/tools/read_note.ts
-import { readFile as readFile6 } from "fs/promises";
+import { readFile as readFile7 } from "fs/promises";
 import { join as join11 } from "path";
 import { z as z15 } from "zod";
 var ReadNoteInput = z15.object({
@@ -1363,10 +1489,17 @@ async function readNote(ctx2, input) {
   if (!absPath.startsWith(ctx2.vaultRoot)) {
     throw new Error(`Path outside vault: ${input.path}`);
   }
-  const raw = await readFile6(absPath, "utf8");
+  const raw = await readFile7(absPath, "utf8");
   const noteBytes = Buffer.byteLength(raw, "utf8");
+  const hash = contentHash(raw);
   if (input.section === void 0 && input.block === void 0 && input.lines === void 0) {
-    return { path: input.path, content: raw, bytesReturned: noteBytes, noteBytes };
+    return {
+      path: input.path,
+      content: raw,
+      bytesReturned: noteBytes,
+      noteBytes,
+      contentHash: hash
+    };
   }
   const fm = parseFrontmatter(raw);
   const outline = buildOutline(raw, { includeBlocks: true });
@@ -1438,12 +1571,13 @@ async function readNote(ctx2, input) {
     content,
     bytesReturned: Buffer.byteLength(content, "utf8"),
     noteBytes,
+    contentHash: hash,
     span: { charStart, charEnd }
   };
 }
 
 // src/tools/replace_in_note.ts
-import { readFile as readFile7, rename as rename3, writeFile as writeFile7 } from "fs/promises";
+import { readFile as readFile8 } from "fs/promises";
 import { join as join12 } from "path";
 import { z as z16 } from "zod";
 var ReplaceInNoteInput = z16.object({
@@ -1454,7 +1588,10 @@ var ReplaceInNoteInput = z16.object({
   caseSensitive: z16.boolean().default(false).describe("Case-sensitive matching."),
   wholeWord: z16.boolean().default(false).describe("Match whole words only (\\b word-boundary)."),
   limit: z16.number().int().min(1).optional().describe("Maximum number of replacements. Omit to replace all."),
-  dryRun: z16.boolean().default(false).describe("If true, report matches without writing anything.")
+  dryRun: z16.boolean().default(false).describe("If true, report matches without writing anything."),
+  prevHash: z16.string().optional().describe(
+    "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
+  )
 });
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -1465,11 +1602,6 @@ function buildRegex(find, opts) {
   const flags = `g${opts.caseSensitive ? "" : "i"}`;
   return new RegExp(pattern, flags);
 }
-async function atomicWrite2(absPath, content) {
-  const tmpPath = `${absPath}.seekstone-replace-tmp`;
-  await writeFile7(tmpPath, content, "utf8");
-  await rename3(tmpPath, absPath);
-}
 async function replaceInNote(ctx2, input) {
   const absPath = join12(ctx2.vaultRoot, input.path);
   if (!absPath.startsWith(ctx2.vaultRoot)) {
@@ -1486,7 +1618,8 @@ async function replaceInNote(ctx2, input) {
   } catch (err) {
     throw new Error(`Invalid regex: ${err instanceof Error ? err.message : String(err)}`);
   }
-  const raw = await readFile7(absPath, "utf8");
+  const raw = await readFile8(absPath, "utf8");
+  if (input.prevHash !== void 0) assertHashMatch(raw, input.prevHash, input.path);
   const fm = parseFrontmatter(raw);
   const originalFmRegion = raw.slice(0, fm.bodyStart);
   const body = raw.slice(fm.bodyStart);
@@ -1516,8 +1649,8 @@ async function replaceInNote(ctx2, input) {
   }
   newBody += body.slice(lastIndex);
   const newContent = `${originalFmRegion}${newBody}`;
-  await atomicWrite2(absPath, newContent);
-  const written = await readFile7(absPath, "utf8");
+  await atomicWrite(absPath, newContent);
+  const written = await readFile8(absPath, "utf8");
   if (written.slice(0, originalFmRegion.length) !== originalFmRegion) {
     throw new Error("Write-safety violation: frontmatter region changed unexpectedly");
   }
@@ -1532,7 +1665,8 @@ async function replaceInNote(ctx2, input) {
     replacements: toReplace.length,
     matches: matches2,
     bytesWritten: Buffer.byteLength(newContent, "utf8"),
-    frontmatterUnchanged: true
+    frontmatterUnchanged: true,
+    contentHash: contentHash(newContent)
   };
 }
 
@@ -1565,7 +1699,9 @@ var META_KEYS = [
   "minSizeBytes",
   "maxSizeBytes",
   "period",
-  "date"
+  "date",
+  "permanent",
+  "prevHash"
 ];
 function safeMeta(args) {
   if (typeof args !== "object" || args === null) return {};
@@ -1653,13 +1789,19 @@ async function run(ctx2, name, args) {
       const input = CreateNoteInput.parse(args);
       const result = await createNote(ctx2, input);
       return {
-        content: [{ type: "text", text: `Created ${result.path} (${result.bytesWritten} bytes).` }]
+        content: [
+          {
+            type: "text",
+            text: `Created ${result.path} (${result.bytesWritten} bytes). contentHash: ${result.contentHash}`
+          }
+        ]
       };
     }
     case "delete_note": {
       const input = DeleteNoteInput.parse(args);
-      await deleteNote(ctx2, input);
-      return { content: [{ type: "text", text: `Deleted ${input.path}.` }] };
+      const result = await deleteNote(ctx2, input);
+      const text = result.trashedTo ? `Moved ${result.path} to ${result.trashedTo} (recoverable \u2014 restore by moving it back).` : `Permanently deleted ${result.path}.`;
+      return { content: [{ type: "text", text }] };
     }
     case "move_note": {
       const input = MoveNoteInput.parse(args);
@@ -1675,7 +1817,10 @@ async function run(ctx2, name, args) {
       const result = await appendNote(ctx2, input);
       return {
         content: [
-          { type: "text", text: `Appended ${result.bytesWritten} bytes to ${result.path}.` }
+          {
+            type: "text",
+            text: `Appended ${result.bytesWritten} bytes to ${result.path}. contentHash: ${result.contentHash}`
+          }
         ]
       };
     }
@@ -1721,7 +1866,7 @@ async function run(ctx2, name, args) {
         content: [
           {
             type: "text",
-            text: `Appended ${result.bytesWritten} bytes to ${result.path}.`
+            text: `Appended ${result.bytesWritten} bytes to ${result.path}. contentHash: ${result.contentHash}`
           }
         ]
       };
@@ -1732,12 +1877,12 @@ async function run(ctx2, name, args) {
 }
 
 // src/index/build.ts
-import { readFile as readFile8 } from "fs/promises";
-import { basename as basename2, extname as extname3 } from "path";
+import { readFile as readFile9 } from "fs/promises";
+import { basename as basename3, extname as extname4 } from "path";
 
 // ../core/src/walk.ts
 import { stat } from "fs/promises";
-import { extname as extname2, join as join13, relative, sep } from "path";
+import { extname as extname3, join as join13, relative, sep } from "path";
 import fg from "fast-glob";
 var IMAGE_EXTS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp", ".heic"]);
 var VIDEO_EXTS = /* @__PURE__ */ new Set([".mp4", ".mov", ".webm", ".mkv", ".avi"]);
@@ -1752,7 +1897,7 @@ var IGNORE_GLOBS = [
 function classify(relPath) {
   if (relPath.endsWith(".excalidraw.md")) return "note";
   if (relPath.endsWith(".excalidraw")) return "excalidraw";
-  const ext = extname2(relPath).toLowerCase();
+  const ext = extname3(relPath).toLowerCase();
   if (ext === ".md") return "note";
   if (ext === ".canvas") return "canvas";
   if (ext === ".pdf") return "pdf";
@@ -1784,7 +1929,7 @@ async function walkVault(vaultRoot2) {
       absPath,
       relPath,
       topDir,
-      ext: extname2(relPath).toLowerCase(),
+      ext: extname3(relPath).toLowerCase(),
       kind: classify(relPath),
       sizeBytes: stats.size,
       mtimeMs: stats.mtimeMs
@@ -1814,12 +1959,12 @@ async function buildIndex(vaultRoot2) {
   await Promise.all(
     noteEntries.map(async (entry) => {
       try {
-        const raw = await readFile8(entry.absPath, "utf8");
+        const raw = await readFile9(entry.absPath, "utf8");
         const fm = parseFrontmatter(raw);
         const inlineTags = extractInlineTags(fm.body);
         const fmTags = frontmatterTags(fm.data);
         const allTags = [.../* @__PURE__ */ new Set([...inlineTags, ...fmTags])];
-        const title = typeof fm.data?.title === "string" && fm.data.title ? fm.data.title : basename2(entry.relPath, extname3(entry.relPath));
+        const title = typeof fm.data?.title === "string" && fm.data.title ? fm.data.title : basename3(entry.relPath, extname4(entry.relPath));
         const doc = {
           id: entry.relPath,
           title,
@@ -1867,7 +2012,7 @@ function buildBacklinks(notes2) {
 
 // src/init.ts
 import { execFileSync } from "child_process";
-import { access as access4, copyFile, mkdir as mkdir4, readdir, readFile as readFile9, stat as stat2, writeFile as writeFile8 } from "fs/promises";
+import { access as access5, copyFile, mkdir as mkdir5, readdir, readFile as readFile10, stat as stat2, writeFile as writeFile2 } from "fs/promises";
 import path, { dirname as dirname4, join as join14 } from "path";
 function parseInitArgs(argv) {
   const opts = { write: false, client: "desktop" };
@@ -1973,7 +2118,7 @@ async function validateVault(vaultPath) {
     return { ok: false, error: `Path does not exist: ${vaultPath}` };
   }
   try {
-    await access4(join14(vaultPath, ".obsidian"));
+    await access5(join14(vaultPath, ".obsidian"));
   } catch {
     return {
       ok: false,
@@ -2011,7 +2156,7 @@ async function runInit(opts, deps) {
       ]
     };
   }
-  const rf = deps.readFile ?? readFile9;
+  const rf = deps.readFile ?? readFile10;
   let vaultPath = opts.vault ?? deps.env.SEEKSTONE_VAULT;
   if (!vaultPath) {
     const registryPath = obsidianRegistryPath(deps.platform, {
@@ -2142,12 +2287,12 @@ async function runInit(opts, deps) {
   }
   const merged = opts.client === "vscode" ? mergeSeekstoneConfigVsCode(existing, vaultPath) : mergeSeekstoneConfig(existing, vaultPath);
   let backupPath;
-  await mkdir4(dirname4(configPath), { recursive: true });
+  await mkdir5(dirname4(configPath), { recursive: true });
   if (existingRaw !== null) {
     backupPath = `${configPath}.backup-${deps.timestamp}`;
     await copyFile(configPath, backupPath);
   }
-  await writeFile8(configPath, `${JSON.stringify(merged, null, 2)}
+  await writeFile2(configPath, `${JSON.stringify(merged, null, 2)}
 `, "utf8");
   out.push(
     `\u2713 Patched ${configPath}`,
@@ -2218,7 +2363,7 @@ function createLogger(opts = {}) {
       );
     }
   }
-  function writeFile9(record) {
+  function writeFile3(record) {
     if (!fileOk || filePath === void 0) return;
     const line = `${JSON.stringify(record)}
 `;
@@ -2240,7 +2385,7 @@ function createLogger(opts = {}) {
     const f = fields ?? {};
     stderr(`${lvl.toUpperCase().padEnd(5)} ${ts} ${msg}${fmtFields(f)}
 `);
-    writeFile9({ t: ts, level: lvl, msg, ...f });
+    writeFile3({ t: ts, level: lvl, msg, ...f });
   }
   return {
     level,
@@ -2346,7 +2491,7 @@ var ALL_TOOLS = [
   },
   {
     name: "read_note",
-    description: "Read a note or a span of it \u2014 by heading section, block reference, or line range. Returns structured JSON with the content, bytes returned, and total note size so payload savings are measurable. Use search or outline_note first to find the right path and section names.",
+    description: "Read a note or a span of it \u2014 by heading section, block reference, or line range. Returns structured JSON with the content, bytes returned, total note size, and a contentHash to pass as prevHash to edit tools for compare-and-swap. Use search or outline_note first to find the right path and section names.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2420,7 +2565,7 @@ var ALL_TOOLS = [
   },
   {
     name: "create_note",
-    description: "Create a new note at a vault-relative path. Optionally sets frontmatter and body content. Parent directories are created automatically. Fails if the note already exists unless overwrite is true.",
+    description: "Create a new note at a vault-relative path. Optionally sets frontmatter and body content. Parent directories are created automatically. Fails if the note already exists unless overwrite is true (prevHash may guard the overwrite).",
     inputSchema: {
       type: "object",
       properties: {
@@ -2437,6 +2582,10 @@ var ALL_TOOLS = [
         overwrite: {
           type: "boolean",
           description: "Overwrite an existing note. Defaults to false."
+        },
+        prevHash: {
+          type: "string",
+          description: "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
         }
       },
       required: ["path"]
@@ -2444,11 +2593,15 @@ var ALL_TOOLS = [
   },
   {
     name: "delete_note",
-    description: "Permanently delete a note from the vault. This cannot be undone.",
+    description: "Delete a note. By default it is moved to the vault .trash/ folder (recoverable by moving it back); pass permanent: true to remove it outright.",
     inputSchema: {
       type: "object",
       properties: {
-        path: { type: "string", description: "Vault-relative path of the note to delete." }
+        path: { type: "string", description: "Vault-relative path of the note to delete." },
+        permanent: {
+          type: "boolean",
+          description: "Permanently remove instead of moving to .trash/. Defaults to false."
+        }
       },
       required: ["path"]
     }
@@ -2480,7 +2633,11 @@ var ALL_TOOLS = [
       type: "object",
       properties: {
         path: { type: "string", description: "Vault-relative path to the note." },
-        content: { type: "string", description: "Text to append." }
+        content: { type: "string", description: "Text to append." },
+        prevHash: {
+          type: "string",
+          description: "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
+        }
       },
       required: ["path", "content"]
     }
@@ -2496,6 +2653,10 @@ var ALL_TOOLS = [
           type: "object",
           description: "Key-value pairs to set. Null value removes the key.",
           additionalProperties: true
+        },
+        prevHash: {
+          type: "string",
+          description: "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
         }
       },
       required: ["path", "patch"]
@@ -2540,6 +2701,10 @@ var ALL_TOOLS = [
         createIfMissing: {
           type: "boolean",
           description: "If the heading target is not found, append a new heading (level 2) + content. Only valid for heading targets. Default false."
+        },
+        prevHash: {
+          type: "string",
+          description: "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
         }
       },
       required: ["path", "target", "operation", "content"]
@@ -2606,6 +2771,10 @@ var ALL_TOOLS = [
         dryRun: {
           type: "boolean",
           description: "If true, report matches without writing. Default false."
+        },
+        prevHash: {
+          type: "string",
+          description: "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
         }
       },
       required: ["path", "find", "replace"]
@@ -2656,6 +2825,10 @@ var ALL_TOOLS = [
         createIfMissing: {
           type: "boolean",
           description: "Create the note if it does not exist before appending. Default true."
+        },
+        prevHash: {
+          type: "string",
+          description: "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
         }
       },
       required: ["content"]
@@ -2669,7 +2842,7 @@ function visibleTools(policy2) {
 
 // src/watcher.ts
 import { realpathSync } from "fs";
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import { join as join15, relative as relative2, sep as sep2 } from "path";
 import chokidar from "chokidar";
 function startWatcher(ctx2, log2, opts) {
@@ -2682,7 +2855,7 @@ function startWatcher(ctx2, log2, opts) {
   const toRel = (abs) => relative2(vaultRoot2, abs).split(sep2).join("/");
   async function upsert(relPath, op) {
     try {
-      const raw = await readFile10(join15(vaultRoot2, relPath), "utf8");
+      const raw = await readFile11(join15(vaultRoot2, relPath), "utf8");
       removeNoteBacklinks(ctx2, relPath);
       upsertDoc(ctx2, buildDoc(relPath, raw));
       addNoteBacklinks(ctx2, relPath, raw);
@@ -2734,7 +2907,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.10.0" : "0.0.0-dev";
+var VERSION = true ? "0.11.0" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}