@staix/vault-mem 0.0.0-stage → 0.1.1

package/src/write-validation.ts

@@ -0,0 +1,285 @@
+import { isDeepStrictEqual } from "node:util";
+import { sourceReferences, sourceWorkspaceRoot, missingSourceWarnings } from "./source.ts";
+import { basename, resolve } from "node:path";
+import type { VaultSpec, VmemConfig } from "./config.ts";
+import { parseFrontmatter } from "./frontmatter.ts";
+import { extractLinks, normalizeTarget, proseLines, resolveLinks, type Link, type LinkNote, type ResolvedLink } from "./links.ts";
+import { canonicalPath, isDenied } from "./platform.ts";
+import type { PlannedChange, ValidationContext, WriteIssue } from "./write-types.ts";
+
+const TYPES = new Set(["insight", "decision", "observation", "person", "project", "method", "moc", "reference"]);
+const DOMAINS = new Set(["research", "projects", "teaching", "operations", "people", "ai-practice"]);
+const CONFIDENCE = new Set(["proven", "likely", "experimental"]);
+const STATUS = new Set(["active", "superseded", "archived"]);
+const CATEGORY = new Set(["gap", "prompt", "workflow"]);
+const KEYS = new Set([
+  "description", "type", "domain", "topics", "source", "confidence", "status",
+  "methodology", "evidence_strength", "project", "alternatives", "superseded_by", "supersedes", "stakeholders",
+  "course", "semester", "student_level", "institution", "policy_area", "role", "affiliation", "last_contact",
+  "tool", "category", "resolution_status", "aliases", "tags", "cssclasses", "title", "created", "updated", "received", "entities",
+  "promoted_from", "promoted_at", "promoted_to", "source_ref",
+  // Adopted in the V2 cutover (#22): decision dates/owners and person contact fields.
+  "decided_at", "decided_by", "email", "phone",
+]);
+/** Adopted keys valid only on one note type (contact fields additionally only in personal vaults, by PII policy). */
+export const TYPED_KEYS: Readonly<Record<string, string>> = { decided_at: "decision", decided_by: "decision", email: "person", phone: "person" };
+export const SCHEMA_KEYS: ReadonlySet<string> = KEYS;
+const WIKI_FIELDS = ["topics", "project", "superseded_by", "supersedes", "source_ref"];
+// Exact regex set from @staix/agent-mem v0.11.0 src/memory/screen.ts; parity-tested against its root export.
+const SECRETS = [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, /\bAKIA[0-9A-Z]{16}\b/, /\bgh[pousr]_[A-Za-z0-9]{30,}/, /\bgithub_pat_[A-Za-z0-9_]{40,}/, /\bsk-[A-Za-z0-9_-]{20,}/,
+  /\bxox[abprs]-[A-Za-z0-9-]{10,}/, /\bAIza[0-9A-Za-z_-]{35}\b/, /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, /\b(?:password|passwd|secret|api[_-]?key|token)\s*[:=]\s*\S{8,}/i];
+export const SECRET_PATTERNS: readonly RegExp[] = SECRETS;
+const EMAIL = /[A-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Z0-9](?:[A-Z0-9.-]*[A-Z0-9])?\.[A-Z]{2,}/i;
+export const EMAIL_PATTERN = EMAIL;
+const MAX_BYTES = 256 * 1024;
+
+function issue(code: string, message: string, severity: WriteIssue["severity"] = "error", path?: string): WriteIssue {
+  return { code, severity, message, ...(path ? { path } : {}) };
+}
+function hasPhone(text: string): boolean {
+  // A complete ISO calendar timestamp is metadata, not a phone-number candidate.
+  const withoutTimestamps = text.replace(/\b[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])[ T](?:[01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9](?:\.[0-9]{1,3})?)?(?:Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])?\b/g, "\n");
+  // The newline replacement is outside the candidate class, so neighbours of a timestamp never merge.
+  const digits = (value: string) => value.replace(/\D/g, "").length;
+  for (const match of withoutTimestamps.matchAll(/(?<![\p{L}\p{N}])\+?\d(?:[\d ().-]{6,}\d)(?![\p{L}\p{N}])/gu)) {
+    const count = digits(match[0]);
+    if (count >= 9 && count <= 15) return true;
+    if (count <= 15) continue;
+    // Oversized run, e.g. two phones separated by spaces: evaluate every contiguous run of
+    // whitespace-separated groups alone so each embedded phone is screened (fails closed).
+    const groups = match[0].split(/\s+/).filter(Boolean);
+    for (let start = 0; start < groups.length; start++) {
+      let total = 0;
+      for (let end = start; end < groups.length && total <= 15; end++) {
+        total += digits(groups[end]!);
+        if (total >= 9 && total <= 15) return true;
+      }
+    }
+  }
+  return false;
+}
+/** Screen the whole prospective text, including frontmatter, without returning matched values. */
+export function screenContent(text: string, vault: VaultSpec, config: VmemConfig): WriteIssue[] {
+  const issues: WriteIssue[] = [];
+  if (SECRETS.some(pattern => pattern.test(text))) issues.push(issue("V06", "secret-looking content is refused"));
+  const pii = vault.pii ?? (vault.kind === "org" ? "deny" : "allow");
+  if (pii === "deny") {
+    const normalized = text.normalize("NFKC");
+    if (EMAIL.test(normalized) || hasPhone(normalized)) issues.push(issue("V07", "PII is refused by the vault policy"));
+    for (const pattern of config.piiPatterns ?? []) {
+      try {
+        if (new RegExp(pattern).test(text)) { issues.push(issue("V07", "configured PII pattern matched")); break; }
+      } catch { issues.push(issue("V07", "invalid PII screening configuration")); break; }
+    }
+  }
+  return issues;
+}
+
+/** Quoted escapes must not hide semantic metadata from the same content policy. */
+function screenMetadata(data:Record<string,unknown>,context:ValidationContext,path:string):WriteIssue[]{
+  const found=new Map<string,WriteIssue>(),active=new WeakSet<object>();let nodes=0,bytes=0;
+  const inspect=(text:string)=>{
+    bytes+=Buffer.byteLength(text);if(bytes>MAX_BYTES*4)throw new Error("budget");
+    for(const item of screenContent(text,context.vault,context.config))found.set(item.code,{...item,path});
+  };
+  const visit=(value:unknown,key:string|undefined,depth:number):void=>{
+    if(++nodes>10000||depth>32)throw new Error("budget");
+    if(value===null||typeof value!=="object"){
+      const text=String(value);inspect(text);if(key!==undefined)inspect(key+": "+text);return;
+    }
+    if(active.has(value))throw new Error("cycle");active.add(value);
+    try{if(Array.isArray(value))for(const item of value)visit(item,key,depth+1);
+      else for(const [name,item] of Object.entries(value)){inspect(name);visit(item,name,depth+1);}}
+    finally{active.delete(value);}
+  };
+  try{visit(data,undefined,0);}catch{return [...found.values(),issue("V09","frontmatter semantic screening exceeds safe traversal bounds","error",path)];}
+  return [...found.values()];
+}
+
+interface ParsedNote extends LinkNote { data: Record<string, unknown>; h1: string; text: string }
+function strings(value: unknown): string[] {
+  return typeof value === "string" ? [value] : Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+function fold(value: string): string { return value.normalize("NFKC").toLowerCase().replace(/[-_\s]+/g, " ").trim(); }
+/** Notes whose path and text match `reuse` keep that parsed object, so link analysis is shared too. */
+function parseNotes(notes: Map<string, string>, reuse?: Map<string, ParsedNote>): Map<string, ParsedNote> {
+  const parsed = new Map<string, ParsedNote>();
+  for (const [path, text] of notes) {
+    const previous = reuse?.get(path);
+    if (previous?.text === text) { parsed.set(path, previous); continue; }
+    try {
+      const { data, body } = parseFrontmatter(text);
+      const h1 = proseLines(body).map(line => /^ {0,3}#(?:[ \t]+(.*)|[ \t]*)$/.exec(line)).find(match => match)?.[1]?.replace(/[ \t]+#+[ \t]*$/, "").trim() ?? "";
+      parsed.set(path, { path, title: typeof data.title === "string" ? data.title : h1 || basename(path, ".md"), aliases: strings(data.aliases), body, data, h1, text });
+    } catch { /* An invalid changed note is reported separately; unrelated legacy YAML is not exposed. */ }
+  }
+  return parsed;
+}
+function noteKey(value: string): string {
+  return normalizeTarget(value.replace(/^\.\//, "").replace(/^notes\//i, "").replace(/\.md$/i, ""));
+}
+function names(notes: Map<string, ParsedNote>): Map<string, Set<ParsedNote>> {
+  const result = new Map<string, Set<ParsedNote>>();
+  // Path-only, matching Obsidian, lint L01 and resolveLinks.
+  for (const note of notes.values()) {
+    const key = noteKey(note.path), candidates = result.get(key) ?? new Set<ParsedNote>();
+    candidates.add(note); result.set(key, candidates);
+  }
+  return result;
+}
+function target(value: unknown, index: Map<string, Set<ParsedNote>>): ParsedNote | undefined {
+  if (typeof value !== "string") return undefined;
+  const wiki = /^\[\[([^\]|#]+)\]\]$/.exec(value.trim());
+  if (!wiki || !wiki[1]!.trim()) return undefined;
+  const candidates = index.get(noteKey(wiki[1]!.trim()));
+  return candidates?.size === 1 ? candidates.values().next().value : undefined;
+}
+const metadataLinks = new WeakMap<ParsedNote, Link[]>();
+function references(notes: Map<string, ParsedNote>): ResolvedLink[] {
+  const metadata = new Map([...notes].map(([path, note]) => {
+    let links = metadataLinks.get(note);
+    if (!links) metadataLinks.set(note, links = WIKI_FIELDS.flatMap(key => strings(note.data[key]).flatMap(value => extractLinks(value))));
+    return [path, links];
+  }));
+  return resolveLinks([...notes.values()], metadata);
+}
+function linkSignature(link: ResolvedLink, source: string = link.source): string {
+  return JSON.stringify([source, noteKey(link.target), link.heading ? normalizeTarget(link.heading) : null,
+    link.block ? normalizeTarget(link.block) : null, link.embed, link.reason]);
+}
+function changedBrokenLinks(oldNotes: Map<string, ParsedNote>, newNotes: Map<string, ParsedNote>, context: ValidationContext): WriteIssue[] {
+  const oldCounts = new Map<string, number>();
+  const move = context.operation.op === "move" ? context.operation : undefined;
+  const from = move ? `notes/${move.from.replace(/^notes\//, "").replace(/\.md$/, "")}.md` : "";
+  const to = move ? `notes/${move.to.replace(/^notes\//, "").replace(/\.md$/, "")}.md` : "";
+  const oldNames = move ? names(oldNotes) : undefined;
+  for (const link of references(oldNotes)) if (link.reason) {
+    const candidates = oldNames?.get(noteKey(link.target));
+    const renamedTarget = candidates?.size === 1 && [...candidates][0]!.path === from;
+    const signature = linkSignature(renamedTarget ? { ...link, target: to } : link, link.source === from ? to : link.source);
+    oldCounts.set(signature, (oldCounts.get(signature) ?? 0) + 1);
+  }
+  const issues: WriteIssue[] = [];
+  for (const link of references(newNotes)) if (link.reason) {
+    const signature = linkSignature(link), count = oldCounts.get(signature) ?? 0;
+    if (count) oldCounts.set(signature, count - 1);
+    issues.push(issue("V03", count ? "pre-existing unresolved link retained" : "new unresolved link is refused", count ? "warning" : "error", link.source));
+  }
+  return issues;
+}
+interface SchemaIssue extends WriteIssue { fields: string[] }
+function schema(note: ParsedNote): SchemaIssue[] {
+  const issues: SchemaIssue[] = [], { data, path } = note;
+  const add=(field:string,message:string,dependencies=[field])=>issues.push({...issue("V01",message,"error",path),fields:dependencies});
+  for(const key of Object.keys(data))if(!KEYS.has(key)||(TYPED_KEYS[key]!==undefined&&data.type!==TYPED_KEYS[key]))add(key,"unknown frontmatter key",[key,"type"]);
+  const description = data.description;
+  if (typeof description !== "string" || !description.trim() || [...description].length > 200) add("description","description must contain 1..200 Unicode characters");
+  else if ([note.title, note.h1, basename(path, ".md")].some(value => value && fold(description) === fold(value))) add("description","description must supplement the title");
+  if (typeof data.type !== "string" || !TYPES.has(data.type)) add("type","invalid or missing note type");
+  if (data.type !== "moc" || data.domain !== undefined) {
+    if (typeof data.domain !== "string" || !DOMAINS.has(data.domain)) add("domain","invalid or missing domain");
+  }
+  for (const [key, allowed] of [["confidence", CONFIDENCE], ["status", STATUS], ["category", CATEGORY]] as const) {
+    if (data[key] !== undefined && (typeof data[key] !== "string" || !allowed.has(data[key]))) add(key,`invalid ${key} enum`);
+  }
+  if(data.source!==undefined)try{sourceReferences(data.source);}catch{add("source","source must contain workspace-relative paths, mem ids or URLs");}
+  return issues;
+}
+function schemaIssues(note:ParsedNote,old:ParsedNote|undefined,context:ValidationContext):WriteIssue[]{
+  const op=context.operation;
+  const explicit=op.op==="frontmatter"&&noteKey(op.path)===noteKey(note.path)?new Set(Object.keys(op.set)):new Set<string>();
+  const value=(n:ParsedNote,key:string)=>n.data[key];
+  const previous=old?schema(old):[];
+  return schema(note).map(({fields,...finding})=>{
+    const retained=op.op!=="create"&&old&&!fields.some(key=>explicit.has(key))&&fields.every(key=>isDeepStrictEqual(value(note,key),value(old,key)))&&previous.some(before=>before.message===finding.message&&isDeepStrictEqual(before.fields,fields));
+    return {...finding,severity:retained?"warning":"error"};
+  });
+}
+function validPath(path: string, report: boolean): boolean {
+  if (Buffer.byteLength(path) > 200 || path.includes("\\") || path.split("/").some(part => !part || part === "." || part === "..")) return false;
+  return report ? /^(?:reports|ops)\//.test(path) && path.split("/").slice(1).every(part => /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(part)) : /^notes\/[a-z0-9][a-z0-9-]*\.md$/.test(path);
+}
+function topicIssues(note: ParsedNote, index: Map<string, Set<ParsedNote>>, severity: WriteIssue["severity"]): WriteIssue[] {
+  if (note.data.type === "moc" && note.data.topics === undefined) return [];
+  if (!Array.isArray(note.data.topics) || note.data.topics.length === 0 || note.data.topics.some(value => !target(value, index) || target(value, index)!.data.type !== "moc")) {
+    return [issue("V02", "topics must be nonempty wiki links to existing MOC notes", severity, note.path)];
+  }
+  return [];
+}
+function topicPlacement(note: ParsedNote): WriteIssue[] {
+  if (note.data.type === "moc" && note.data.topics === undefined) return [];
+  const lines = proseLines(note.body), h2s = lines.flatMap((line, index) => /^ {0,3}##[ \t]+/.test(line) ? [index] : []);
+  const topics = h2s.filter(index => /^ {0,3}##[ \t]+Topics(?:[ \t]+#+)?[ \t]*$/i.test(lines[index]!));
+  let valid = topics.length === 1 && h2s[h2s.length - 1] === topics[0];
+  const actual: string[] = [];
+  if (valid) for (const line of lines.slice(topics[0]! + 1)) {
+    if (!line.trim()) continue;
+    const wiki = /^[ \t]*(?:[-*+][ \t]+)?(\[\[[^\]|#]+\]\])[ \t]*$/.exec(line);
+    if (!wiki) { valid = false; break; }
+    actual.push(noteKey(wiki[1]!.slice(2, -2)));
+  }
+  const expected = Array.isArray(note.data.topics) ? note.data.topics.map(value => typeof value === "string" ? noteKey(value.slice(2, -2)) : "") : [];
+  const sortedExpected = [...expected].sort();
+  if (actual.length !== expected.length || [...actual].sort().some((value, index) => value !== sortedExpected[index])) valid = false;
+  return valid ? [] : [issue("V05", "Topics must be the final H2 and list exactly the frontmatter topics", "warning", note.path)];
+}
+
+/** Validate a complete mutation plan against the final overlaid snapshot, without filesystem writes. */
+export function validateWrite(changes: PlannedChange[], context: ValidationContext): WriteIssue[] {
+  const issues: WriteIssue[] = [], final = new Map(context.notes), touched = new Set(changes.map(change => change.path));
+  const report = context.operation.op === "report";
+  for (const change of changes) {
+    // Sanitize may rewrite an existing legacy-named note in place (L13 names stay until moved).
+    if (!validPath(change.path, report) && !(context.operation.op === "sanitize" && context.notes.has(change.path))) issues.push(issue("V04", "invalid mutation path"));
+    if (change.after === null) final.delete(change.path);
+    else if (change.path.startsWith("notes/")) final.set(change.path, change.after);
+    if (change.after === null) continue;
+    if (Buffer.byteLength(change.after) > MAX_BYTES) issues.push(issue("V09", "prospective file exceeds 256 KiB", "error", change.path));
+    issues.push(...screenContent(change.after, context.vault, context.config).map(value => ({ ...value, path: change.path })));
+    try{issues.push(...screenMetadata(parseFrontmatter(change.after).data,context,change.path));}catch{ /* Invalid note YAML is reported separately; reports remain schema-exempt. */ }
+  }
+  const sourceRoot=sourceWorkspaceRoot(context.vault);
+  const oldNotes = parseNotes(context.notes), newNotes = parseNotes(final, oldNotes), oldNames = names(oldNotes), newNames = names(newNotes);
+  const candidates=[...changes];
+  if(context.operation.op==="frontmatter"){
+    const key=noteKey(context.operation.path),existing=[...newNotes.values()].find(note=>noteKey(note.path)===key);
+    if(existing&&!candidates.some(change=>change.path===existing.path))candidates.push({path:existing.path,before:existing.text,after:existing.text});
+  }
+  for (const change of candidates) {
+    if (change.after === null || report) continue;
+    const note = newNotes.get(change.path);
+    if (!note) { issues.push(issue("V01", "invalid frontmatter", "error", change.path)); continue; }
+    const prior=context.operation.op==="move"&&noteKey(context.operation.to)===noteKey(note.path)?oldNotes.get(`notes/${noteKey(context.operation.from)}.md`):oldNotes.get(note.path);
+    issues.push(...schemaIssues(note,prior,context), ...topicPlacement(note));
+    const source = note.data.source;
+    let sourceDenied=strings(source).some(entry=>isDenied(entry.replaceAll("\\","/"),context.config.denyPaths));
+    if(source!==undefined&&!sourceDenied)try{
+      const references=sourceReferences(source);
+      if(sourceRoot&&references.some(ref=>ref.kind==="path"&&isDenied(canonicalPath(resolve(sourceRoot,ref.value)),context.config.denyPaths)))sourceDenied=true;
+      if(!sourceDenied)issues.push(...missingSourceWarnings(source,sourceRoot).map(message=>issue("V11",message,"warning",change.path)));
+    }catch{ /* Typed source errors are emitted as field-sensitive V01 above. */ }
+    if(sourceDenied)issues.push(issue("V06","source is denied by the path policy","error",change.path));
+    if (change.before === null && context.operation.op === "create") {
+      const stem = noteKey(change.path);
+      if (context.notes.has(change.path) || [...newNotes.values()].some(other => other.path !== note.path && (noteKey(other.path) === stem || (note.h1 && other.h1 && fold(note.h1) === fold(other.h1))))) {
+        issues.push(issue("V08", "a note with the same stem or normalized H1 already exists", "error", change.path));
+      }
+    }
+  }
+  if (!report) {
+    for (const note of newNotes.values()) {
+      const old = oldNotes.get(note.path);
+      const topicsPreviouslyValid = old && topicIssues(old, oldNames, "error").length === 0;
+      issues.push(...topicIssues(note, newNames, touched.has(note.path) || topicsPreviouslyValid ? "error" : "warning"));
+      if (note.data.status === "superseded" && !target(note.data.superseded_by, newNames)) {
+        const wasValid = old?.data.status === "superseded" && target(old.data.superseded_by, oldNames);
+        issues.push(issue("V10", "superseded notes require an existing superseded_by wiki target", touched.has(note.path) || wasValid ? "error" : "warning", note.path));
+      }
+      for (const field of ["supersedes", "superseded_by"] as const) if (note.data[field] !== undefined && (!strings(note.data[field]).length || !strings(note.data[field]).every(value => target(value, newNames)))) {
+        issues.push(issue("V10", "supersession references must resolve to existing notes", touched.has(note.path) ? "error" : "warning", note.path));
+      }
+    }
+    issues.push(...changedBrokenLinks(oldNotes, newNotes, context));
+  }
+  return issues;
+}

package/src/writer.ts

@@ -0,0 +1,259 @@
+import { appendLog } from "./vault-log.ts";
+import type { LogEvent } from "./log-types.ts";
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { hostname } from "node:os";
+import { Database } from "bun:sqlite";
+import { loadRegistry, syncDirectory } from "./registry.ts";
+import { VaultIndex, MAX_NOTE_BYTES } from "./vault-index.ts";
+import { parseFrontmatter } from "./frontmatter.ts";
+import { canonicalPath, isDenied } from "./platform.ts";
+import { notePath, planOperation, refuse, WriteRefusal } from "./write-operations.ts";
+import { validateWrite } from "./write-validation.ts";
+import type { ChangeReceipt, PlannedChange, WriteIssue, WriteReceipt, WriteRequest } from "./write-types.ts";
+export const MUTATION_LOCK = "mutation.lock";
+export const MAX_WRITE_BYTES = 256 * 1024;
+export function sha256(text: string): string { return createHash("sha256").update(text).digest("hex"); }
+function canonical(value: unknown): string {
+  if (value === undefined) return "null";
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.entries(value).filter(([, item]) => item !== undefined).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+/** Reject linked parent components as well as linked final files. No directories are created here. */
+function safePath(root: string, path: string): string {
+  const parts = path.split("/");
+  if (parts.some(part => !part || part === "." || part === "..") || path.startsWith("/") || path.includes("\\")) refuse("V04", "unsafe relative path");
+  let current = root;
+  for (let i = 0; i < parts.length; i++) {
+    current = join(current, parts[i]!);
+    try {
+      const stat = lstatSync(current);
+      if (stat.isSymbolicLink() || (i < parts.length - 1 ? !stat.isDirectory() : !stat.isFile())) refuse("V04", "path must use plain directories and files", path);
+    } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  }
+  return current;
+}
+/** Nanosecond file identity used to detect a write racing a single read. */
+function stamp(stat: { dev: bigint; ino: bigint; size: bigint; mtimeNs: bigint; ctimeNs: bigint }): string {
+  return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+}
+function readPlain(root: string, path: string): string | null {
+  const file = safePath(root, path);
+  let fd: number;
+  try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
+  try {
+    const before = fstatSync(fd, { bigint: true });
+    if (!before.isFile() || before.size > BigInt(MAX_NOTE_BYTES)) refuse("V09", "file exceeds read bound or is not regular", path);
+    const bytes = Buffer.alloc(Math.min(Number(before.size) + 1, MAX_NOTE_BYTES + 1));
+    let size = 0;
+    while (size < bytes.length) {
+      const count = readSync(fd, bytes, size, bytes.length - size, null); size += count;
+      if (!count) break;
+    }
+    const after = fstatSync(fd, { bigint: true });
+    if (size > MAX_NOTE_BYTES || stamp(before) !== stamp(after)) refuse("V09", "file changed during read", path);
+    const buffer = bytes.subarray(0, size), text = buffer.toString("utf8");
+    if (!Buffer.from(text).equals(buffer)) refuse("V01", "note must be valid UTF-8", path);
+    return text;
+  } finally { closeSync(fd); }
+}
+/** Flat `notes/*.md` snapshot used by every mutation (other directories such as templates/ and self/ are never read). */
+export function snapshot(root: string, denyPaths: string[] = []): Map<string, string> {
+  const dir = join(root, "notes");
+  if (realpathSync(dir) !== dir || !lstatSync(dir).isDirectory()) refuse("V04", "notes directory changed");
+  const notes = new Map<string, string>();
+  for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    if (notes.size >= 10000) refuse("V09", "vault exceeds 10000-note mutation bound");
+    const path = `notes/${entry.name}`;
+    if (isDenied(join(root, path), denyPaths)) refuse("V06", "mutation snapshot contains a denied note path");
+    const source = readPlain(root, path);
+    if (source === null) refuse("V09", "note disappeared during snapshot", path);
+    notes.set(path, source);
+  }
+  return notes;
+}
+function receipts(changes: PlannedChange[]): ChangeReceipt[] {
+  return changes.map(change => ({ path: change.path, beforeSha: change.before === null ? null : sha256(change.before), sha256: change.after === null ? null : sha256(change.after), bytes: Buffer.byteLength(change.after ?? "") }));
+}
+function checkExpected(request: WriteRequest, notes: Map<string, string>): void {
+  const expected = { ...request.expectedShas };
+  if ("expectedSha" in request.operation && request.operation.expectedSha !== undefined && "path" in request.operation) expected[notePath(request.operation.path)] = request.operation.expectedSha;
+  for (const [path, hash] of Object.entries(expected)) {
+    // Reports verify an existing snapshot, including legacy names diagnosed by L13.
+    // Exact membership is safe here: snapshot() contains only existing flat regular notes.
+    // All note mutation targets still go through the stricter notePath naming policy.
+    const canonical = (request.operation.op === "report" || request.operation.op === "sanitize") && notes.has(path) ? path : notePath(path), source = notes.get(canonical);
+    if (typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash) || source === undefined || sha256(source) !== hash) refuse("V09", "expected SHA mismatch", canonical);
+  }
+}
+function duplicateWarnings(request: WriteRequest, notes: Map<string, string>, changes: PlannedChange[]): WriteIssue[] {
+  if (request.operation.op !== "create" || !notes.size || !changes[0]?.after) return [];
+  const doc = parseFrontmatter(changes[0].after);
+  const title = typeof doc.data.title === "string" ? doc.data.title : /^#\s+(.+)$/m.exec(doc.body)?.[1] ?? "";
+  const terms = [...new Set(title.normalize("NFKC").toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [])].slice(0, 12);
+  if (!terms.length) return [];
+  // Disposable FTS preserves dry-run's no-disk-write contract, including on a fresh home.
+  const db = new Database(":memory:");
+  try {
+    db.run("CREATE VIRTUAL TABLE candidates USING fts5(path UNINDEXED,title,description,body,tokenize='unicode61')");
+    const insert = db.query("INSERT INTO candidates VALUES (?,?,?,?)");
+    for (const [path, source] of notes) {
+      let value: ReturnType<typeof parseFrontmatter>;
+      try { value = parseFrontmatter(source); } catch { continue; } // Unrelated legacy YAML is not a duplicate candidate.
+      insert.run(path, typeof value.data.title === "string" ? value.data.title : path, typeof value.data.description === "string" ? value.data.description : "", value.body);
+    }
+    const hits = db.query<{ path: string; score: number }, [string]>("SELECT path,bm25(candidates,0,5,2,1) AS score FROM candidates WHERE candidates MATCH ? ORDER BY score,path LIMIT 3").all(terms.map(term => `"${term}"`).join(" AND "));
+    return hits.filter(hit => hit.score <= -0.000001).map(hit => ({ code: "V08", severity: "warning", path: hit.path, message: "possible duplicate: FTS title terms match an existing note" }));
+  } finally { db.close(); }
+}
+/** Single mutation entry point. Preview/dry-run perform no writes, including locks and caches. */
+export function applyWrite(home: string, request: WriteRequest, options: { env?: NodeJS.ProcessEnv } = {}): WriteReceipt {
+  let lockFd: number | undefined, lockFile: string | undefined, lockIdentity: { ino: number; dev: number } | undefined;
+  let index: VaultIndex | undefined;
+  const temps = new Set<string>(), createdDirs: string[] = [], committed: PlannedChange[] = [];
+  let changes: PlannedChange[] = [], issues: WriteIssue[] = [], fingerprint: string | undefined, root = "", applied = false, indexUpdated = false;
+  let result: WriteReceipt | undefined;
+  const recordError = (code: string, message: string, path?: string) => issues.push({ code, severity: "error", message, ...(path ? { path } : {}) });
+  try {
+    if (!request || typeof request !== "object" || !request.operation || typeof request.operation !== "object" || typeof request.vault !== "string") refuse("V01", "invalid write request");
+    if (Object.keys(request).some(key => !["vault", "operation", "channel", "dryRun", "confirm", "fingerprint", "expectedShas", "log"].includes(key)) || [request.dryRun, request.confirm].some(value => value !== undefined && typeof value !== "boolean")) refuse("V01", "unknown request option or invalid boolean");
+    if (request.expectedShas !== undefined && (!request.expectedShas || typeof request.expectedShas !== "object" || Array.isArray(request.expectedShas))) refuse("V09", "expectedShas must be a mapping");
+    if (request.channel !== undefined && !["cli", "mcp"].includes(request.channel)) refuse("POLICY", "unknown write channel");
+    const config = loadRegistry(home), vault = config.vaults.find(value => value.id === request.vault);
+    if (!vault) refuse("V04", "unknown vault id");
+    if (request.operation.op !== "check" && (vault.write === "none" || (request.channel === "mcp" && vault.write !== "mcp"))) refuse("POLICY", "vault write policy refuses this channel");
+    root = realpathSync(vault.path);
+    if (root !== vault.path || isDenied(root, config.denyPaths)) refuse("V06", "vault path denied or changed");
+    if (config.vaults.some(value => canonicalPath(home) === value.path || canonicalPath(home).startsWith(`${value.path}/`))) refuse("V04", "VMEM_HOME must be outside registered vaults");
+    const twoStep = ["move", "delete", "tidy"].includes(request.operation.op);
+    const preview = request.operation.op === "check" || request.dryRun === true || (twoStep && request.confirm !== true);
+    if (!preview) {
+      lockFile = join(root, MUTATION_LOCK);
+      try { lockFd = openSync(lockFile, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+      catch { lockFile = undefined; refuse("LOCKED", "vault mutation lock unavailable; existing lock is preserved"); }
+      const stat = fstatSync(lockFd); lockIdentity = { ino: Number(stat.ino), dev: Number(stat.dev) };
+      writeFileSync(lockFd, JSON.stringify({ pid: process.pid, host: hostname(), token: randomUUID(), created: new Date().toISOString() }) + "\n");
+      fsyncSync(lockFd);
+    }
+    const notes = snapshot(root, config.denyPaths);
+    checkExpected(request, notes);
+    let reportBefore: string | null | undefined;
+    if (request.operation.op === "report") {
+      // Planning validates the report's exact relative path before it can be read.
+      planOperation(request.operation, notes, null);
+      if (isDenied(join(root, request.operation.path), config.denyPaths)) refuse("V06", "report output path is denied");
+      reportBefore = readPlain(root, request.operation.path);
+    }
+    changes = planOperation(request.operation, notes, reportBefore);
+    for (const change of changes) if (isDenied(join(root, change.path), config.denyPaths)) refuse("V06", "planned mutation path is denied", change.path);
+    issues = validateWrite(changes, { vault, config, notes, operation: request.operation });
+    if (!issues.some(issue => issue.severity === "error")) issues.push(...duplicateWarnings(request, notes, changes));
+    const input = { vault: request.vault, channel: request.channel ?? "cli", operation: request.operation, expectedShas: request.expectedShas ?? {}, log: request.log ?? null };
+    const identity = lstatSync(root);
+    fingerprint = sha256(canonical({ input, vault, policy: { denyPaths: config.denyPaths ?? [], piiPatterns: config.piiPatterns ?? [] }, root, identity: [identity.dev, identity.ino], files: [...notes].map(([path, text]) => [path, sha256(text)]), changes: receipts(changes) }));
+    if (twoStep && request.confirm === true && (typeof request.fingerprint !== "string" || request.fingerprint !== fingerprint)) refuse("V09", "stale or missing preview fingerprint");
+    if (issues.some(issue => issue.severity === "error")) return result = { ok: false, applied: false, issues, changes: receipts(changes), fingerprint, indexUpdated: false };
+    if (preview) return result = { ok: true, applied: false, preview: true, ...(request.operation.op === "link" && !changes.length ? {unchanged:true} : {}), issues, changes: receipts(changes), fingerprint, indexUpdated: false };
+    if (!changes.length) return result = { ok: true, applied: false, ...(request.operation.op === "link" ? {unchanged:true} : {}), issues, changes: [], fingerprint, indexUpdated: false };
+    index = new VaultIndex(home, vault, config.vaults.map(value => value.path));
+    const backups = new Map<string, string>(), staged = new Map<string, string>();
+    const ensureDir = (dir: string) => {
+      if (dir === root) return;
+      try { if (!lstatSync(dir).isDirectory() || lstatSync(dir).isSymbolicLink()) refuse("V04", "unsafe output directory"); }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+        ensureDir(dirname(dir)); mkdirSync(dir, { mode: 0o700 }); createdDirs.push(dir);
+      }
+    };
+    const stage = (file: string, text: string) => {
+      const temp = join(dirname(file), `.vmem-${randomUUID()}.tmp`);
+      const fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+      temps.add(temp);
+      try { writeFileSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
+      return temp;
+    };
+    for (const change of changes) {
+      const file = safePath(root, change.path); ensureDir(dirname(file));
+      if (change.before !== null) backups.set(change.path, stage(file, change.before));
+      if (change.after !== null) staged.set(change.path, stage(file, change.after));
+    }
+    try {
+      // Detect non-cooperating writers before any rename; cooperating callers use our lock.
+      const currentRoot = lstatSync(root);
+      if (currentRoot.dev !== identity.dev || currentRoot.ino !== identity.ino) refuse("V09", "vault identity changed while staging");
+      // Full content recheck: shared mmap writes can change bytes without moving any stat field.
+      const current = snapshot(root, config.denyPaths);
+      if (current.size !== notes.size || [...current].some(([path, text]) => notes.get(path) !== text)) refuse("V09", "vault changed while staging");
+      for (const change of changes) {
+        const file = safePath(root, change.path);
+        if (readPlain(root, change.path) !== change.before) refuse("V09", "file changed while staging", change.path);
+        if (change.after === null) unlinkSync(file);
+        else { const temp = staged.get(change.path)!; renameSync(temp, file); temps.delete(temp); }
+        committed.push(change);
+      }
+      for (const dir of new Set(changes.map(change => dirname(join(root, change.path))))) syncDirectory(dir);
+      const refreshed = index.scan(false, { skipInvalidFrontmatter: true });
+      for (const path of refreshed.skipped ?? []) issues.push({ code: "V01", severity: "warning", path: `notes/${path}`, message: "legacy invalid frontmatter omitted from derived index; note unchanged" });
+      indexUpdated = true; applied = true;
+    } catch (error) {
+      for (const change of [...committed].reverse()) {
+        try {
+          const file = safePath(root, change.path);
+          if (readPlain(root, change.path) !== change.after) throw new Error("external write detected before rollback");
+          if (change.before === null) unlinkSync(file);
+          else { const backup = backups.get(change.path)!; renameSync(backup, file); temps.delete(backup); }
+        } catch {
+          applied = true;
+          const backup = backups.get(change.path);
+          if (backup) temps.delete(backup); // Recovery copy must survive failed rollback or external drift.
+          recordError("ROLLBACK", "rollback refused or failed; external edits preserved and original backup retained when available", backup ? backup.slice(root.length + 1) : change.path);
+        }
+      }
+      for (const dir of new Set(committed.map(change => dirname(join(root, change.path))))) {
+        try { syncDirectory(dir); } catch { recordError("ROLLBACK", "rollback directory flush failed"); }
+      }
+      try { index.scan(false, { skipInvalidFrontmatter: true }); } catch { recordError("INDEX", "derived index refresh failed; rebuild after resolving filesystem error"); }
+      throw error;
+    }
+    result = { ok: true, applied, issues, changes: receipts(changes), fingerprint, indexUpdated };
+    if (request.log !== false) {
+      const op = request.operation;
+      const type = op.op === "link" ? "CONNECT" : op.op === "move" ? "ROUTE" : ["supersede", "tidy"].includes(op.op) ? "RETHINK" : "EXTRACT";
+      const source = op.op === "move" || op.op === "link" ? notePath(op.from) : op.op === "supersede" ? notePath(op.old) : op.op === "delete" ? notePath(op.path) : `vmem:${op.op}`;
+      const dest = op.op === "move" || op.op === "link" ? notePath(op.to) : op.op === "supersede" ? notePath(op.next) : op.op === "delete" ? undefined : changes.find(change => change.after !== null)?.path;
+      const event: LogEvent = request.log ?? { type, project: "-", source, ...(dest ? { dest } : {}), note: op.op };
+      try { result.log = appendLog(home, { vault: request.vault, event, channel: request.channel }, { env: options.env, binding: { vault, denyPaths: config.denyPaths ?? [], piiPatterns: config.piiPatterns ?? [], dev: Number(identity.dev), ino: Number(identity.ino) } }); }
+      catch { result.log = { ok: false, appended: null, synced: false, bytesWritten: null, issues: [{ code: "LOG_IO", severity: "error", message: "log append failed after successful mutation" }] }; }
+      result.logged = result.log.appended === true && result.log.synced;
+    }
+  } catch (error) {
+    if (error instanceof WriteRefusal) issues.push(...error.issues);
+    else recordError("IO", "write operation failed; inspect filesystem permissions and retry");
+    result = { ok: false, applied, issues, changes: receipts(changes), ...(fingerprint ? { fingerprint } : {}), indexUpdated };
+  } finally {
+    try { index?.close(); } catch { recordError("INDEX", "derived index close failed"); }
+    for (const temp of temps) {
+      try { unlinkSync(temp); } catch { recordError("CLEANUP", "owned temporary cleanup failed; inspect .vmem temporary files"); }
+    }
+    // Only empty directories created by this invocation are eligible for removal on failure.
+    if (!applied) for (const dir of createdDirs.reverse()) { try { rmdirSync(dir); } catch { recordError("CLEANUP", "owned empty directory cleanup failed"); } }
+    if (lockFd !== undefined) {
+      try { closeSync(lockFd); } catch { recordError("CLEANUP", "mutation lock descriptor close failed"); }
+      try {
+        const stat = lstatSync(lockFile!);
+        if (Number(stat.ino) !== lockIdentity?.ino || Number(stat.dev) !== lockIdentity?.dev || stat.isSymbolicLink()) recordError("CLEANUP", "mutation lock ownership changed; retained lock");
+        else unlinkSync(lockFile!);
+      } catch { recordError("CLEANUP", "mutation lock retained; inspect ownership before manual recovery"); }
+    }
+    if (result) {
+      const possibleDuplicates = issues.filter(issue => issue.code === "V08" && issue.severity === "warning" && issue.path).map(issue => issue.path!);
+      if (possibleDuplicates.length) result.possibleDuplicates = possibleDuplicates;
+      if (issues.some(issue => issue.severity === "error")) result.ok = false;
+    }
+  }
+  return result!;
+}