@staix/vault-mem 0.0.0-bootstrap.0 → 0.1.0

package/src/vault-log.ts

@@ -0,0 +1,229 @@
+import { compileLogFilter } from "./log-filter.ts";
+import { closeSync, constants, fstatSync, fsyncSync, ftruncateSync, lstatSync, openSync, readSync, realpathSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { hostname } from "node:os";
+import { loadRegistry, syncDirectory } from "./registry.ts";
+import { canonicalPath, isDenied } from "./platform.ts";
+import { formatLogEvent, LOG_TYPES } from "./log-format.ts";
+import type { LogBinding, LogContext, LogReadOptions, LogReadResult, LogReceipt, LogRequest } from "./log-types.ts";
+import type { WriteIssue } from "./write-types.ts";
+export const LOG_LOCK = "log.lock";
+export const MAX_LOG_READ_BYTES = 32 * 1024 * 1024;
+export const LARGE_LOG_LINES = 20000;
+const MAX_READ_LINE_BYTES = 4096;
+export const MAX_LOG_RESULT_BYTES = 128 * 1024;
+class LogRefused extends Error {
+  constructor(readonly issues: WriteIssue[]) { super(issues[0]?.message ?? "log refused"); }
+}
+function refuse(code: string, message: string): never { throw new LogRefused([{ code, severity: "error", message }]); }
+function boundedPlain(file: string, maximum: number): string {
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.size > maximum) refuse("L09", "registry must be a bounded plain file");
+    const buffer = Buffer.alloc(before.size + 1); let size = 0;
+    while (size < buffer.length) { const count = readSync(fd, buffer, size, buffer.length - size, null); if (!count) break; size += count; }
+    const after = fstatSync(fd);
+    if (size !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) refuse("L09", "registry changed while reading");
+    const bytes = buffer.subarray(0, size), text = bytes.toString("utf8");
+    if (!Buffer.from(text).equals(bytes)) refuse("L09", "registry must be UTF-8");
+    return text;
+  } finally { closeSync(fd); }
+}
+function registryIds(file: string, denyPaths: string[] = []): Set<string> {
+  if (isDenied(canonicalPath(file), denyPaths)) refuse("L09", "registry path is denied");
+  let parsed: unknown;
+  try { parsed = Bun.YAML.parse(boundedPlain(file, 1024 * 1024)); }
+  catch (error) { if (error instanceof LogRefused) throw error; refuse("L09", "cannot read project registry"); }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !Array.isArray((parsed as Record<string, unknown>).projects)) refuse("L09", "registry requires a projects array");
+  const result = new Set<string>(), visited = new Set<object>();
+  function collect(items: unknown[], depth: number): void {
+    if (depth > 8 || visited.has(items)) refuse("L09", "registry nesting is invalid");
+    visited.add(items);
+    for (const item of items) {
+      if (!item || typeof item !== "object" || Array.isArray(item)) refuse("L09", "registry projects must be objects");
+      const entry = item as Record<string, unknown>;
+      if (typeof entry.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(entry.id) || result.has(entry.id) || result.size >= 10000) refuse("L09", "registry project id is invalid, duplicated or exceeds bound");
+      result.add(entry.id);
+      if (entry.sub_projects !== undefined) {
+        if (!Array.isArray(entry.sub_projects)) refuse("L09", "registry sub_projects must be an array");
+        collect(entry.sub_projects, depth + 1);
+      }
+    }
+  }
+  collect((parsed as { projects: unknown[] }).projects, 0);
+  return result;
+}
+function context(home: string, id: string, channel: "cli" | "mcp" | undefined, write: boolean): LogContext {
+  const config = loadRegistry(home), vault = config.vaults.find(item => item.id === id);
+  if (!vault) refuse("L09", "unknown vault id");
+  if (channel !== undefined && channel !== "cli" && channel !== "mcp") refuse("POLICY", "unknown log channel");
+  if (write && (vault.write === "none" || (channel === "mcp" && vault.write !== "mcp"))) refuse("POLICY", "vault write policy refuses log append");
+  if (realpathSync(vault.path) !== vault.path || !lstatSync(vault.path).isDirectory()) refuse("L09", "registered vault path changed");
+  if (isDenied(join(vault.path, "log"), config.denyPaths)) refuse("V06", "log path is denied");
+  return { vault, config, channel, ...(write && vault.registry ? { projectIds: registryIds(vault.registry, config.denyPaths) } : {}) };
+}
+/** One O_APPEND write per event. A separate cooperative lock permits safe short-write rollback. */
+export function appendLog(home: string, request: LogRequest, options: { env?: NodeJS.ProcessEnv; now?: Date; binding?: LogBinding } = {}): LogReceipt {
+  const result: LogReceipt = { ok: false, appended: false, synced: false, bytesWritten: 0, issues: [] };
+  let fd: number | undefined, lockFd: number | undefined, lockFile: string | undefined, identity: { ino: number; dev: number } | undefined;
+  const error = (code: string, message: string) => result.issues.push({ code, severity: "error", message });
+  try {
+    if (!request || typeof request !== "object" || typeof request.vault !== "string" || Object.keys(request).some(key => !["vault", "event", "channel"].includes(key))) refuse("L09", "invalid log request");
+    const ctx = context(home, request.vault, request.channel, true);
+    const rootIdentity = lstatSync(ctx.vault.path);
+    if (options.binding) {
+      const bound = options.binding;
+      if (JSON.stringify(ctx.vault) !== JSON.stringify(bound.vault) || rootIdentity.dev !== bound.dev || rootIdentity.ino !== bound.ino || JSON.stringify(ctx.config.denyPaths ?? []) !== JSON.stringify(bound.denyPaths) || JSON.stringify(ctx.config.piiPatterns ?? []) !== JSON.stringify(bound.piiPatterns)) refuse("LOG_DRIFT", "vault identity or policy changed after mutation; log not appended");
+    }
+    const formatted = formatLogEvent(request.event, { ...ctx, env: options.env ?? process.env, now: options.now });
+    if (!formatted.line || formatted.issues.some(issue => issue.severity === "error")) { result.issues.push(...formatted.issues); return result; }
+    const buffer = Buffer.from(formatted.line), root = ctx.vault.path;
+    lockFile = join(root, LOG_LOCK);
+    const deadline = Date.now() + 2000, sleeper = new Int32Array(new SharedArrayBuffer(4));
+    for (;;) {
+      try { lockFd = openSync(lockFile, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); break; }
+      catch (caught) {
+        if ((caught as NodeJS.ErrnoException).code !== "EEXIST" || Date.now() >= deadline) { lockFile = undefined; refuse("LOG_LOCKED", "log lock unavailable; existing lock is preserved"); }
+        Atomics.wait(sleeper, 0, 0, 5);
+      }
+    }
+    const lockStat = fstatSync(lockFd); identity = { ino: Number(lockStat.ino), dev: Number(lockStat.dev) };
+    writeFileSync(lockFd, JSON.stringify({ pid: process.pid, host: hostname(), created: new Date().toISOString() }) + "\n");
+    const stillRoot = lstatSync(root);
+    if (stillRoot.dev !== rootIdentity.dev || stillRoot.ino !== rootIdentity.ino) refuse("LOG_DRIFT", "vault identity changed while acquiring log lock");
+    const file = join(root, "log"); let existed = true;
+    try { const stat = lstatSync(file); if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) refuse("L09", "log must be a plain nonlinked file"); }
+    catch (caught) { if ((caught as NodeJS.ErrnoException).code !== "ENOENT") throw caught; existed = false; }
+    fd = openSync(file, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1) refuse("L09", "log must be a plain nonlinked file");
+    if (before.size > 0) {
+      const last = Buffer.alloc(1); if (readSync(fd, last, 0, 1, before.size - 1) !== 1 || last[0] !== 10) refuse("L09", "log ends in an incomplete line; inspect before appending");
+    }
+    let written: number;
+    try { written = writeSync(fd, buffer, 0, buffer.length, null); result.bytesWritten = written; }
+    catch {
+      // Preserve unknown state unless a bounded read proves our entire append or prefix.
+      result.appended = null; result.bytesWritten = null;
+      const after = fstatSync(fd), linked = lstatSync(file), added = after.size - before.size;
+      if (linked.ino === before.ino && linked.dev === before.dev && added >= 0 && added <= buffer.length) {
+        const tail = Buffer.alloc(added);
+        if (readSync(fd, tail, 0, tail.length, before.size) === tail.length && tail.equals(buffer.subarray(0, added))) {
+          result.bytesWritten = added;
+          if (added === buffer.length) result.appended = true;
+          else {
+            result.appended = false;
+            if (added) { ftruncateSync(fd, before.size); fsyncSync(fd); result.rolledBack = true; }
+          }
+        }
+      }
+      refuse("LOG_WRITE", "log write failed; inspect append state before retrying");
+    }
+    if (written !== buffer.length) {
+      const after = fstatSync(fd), linked = lstatSync(file);
+      if (written >= 0 && after.size === before.size + written && linked.ino === before.ino && linked.dev === before.dev) {
+        const tail = Buffer.alloc(written);
+        if (readSync(fd, tail, 0, written, before.size) === written && tail.equals(buffer.subarray(0, written))) {
+          ftruncateSync(fd, before.size); fsyncSync(fd); result.rolledBack = true;
+        }
+      }
+      refuse("LOG_WRITE", "short log write refused; inspect rollback state before retrying");
+    }
+    result.appended = true;
+    fsyncSync(fd);
+    if (!existed) syncDirectory(root);
+    let sameIdentity = false;
+    try {
+      const finalLog = lstatSync(file), finalRoot = lstatSync(root);
+      sameIdentity = !finalLog.isSymbolicLink() && finalLog.ino === before.ino && finalLog.dev === before.dev && finalRoot.ino === rootIdentity.ino && finalRoot.dev === rootIdentity.dev;
+    } catch { /* A removed path is drift, not proof that the fd's event is accessible. */ }
+    if (!sameIdentity) {
+      result.appended = null;
+      refuse("LOG_DRIFT", "log or vault identity changed during append; current path persistence is unknown");
+    }
+    result.synced = true; result.ok = true;
+  } catch (caught) {
+    if (caught instanceof LogRefused) result.issues.push(...caught.issues);
+    else error("LOG_IO", "log operation failed; inspect file permissions and append state");
+  } finally {
+    if (fd !== undefined) { try { closeSync(fd); } catch { error("LOG_CLOSE", "log descriptor close failed"); } }
+    if (lockFd !== undefined) {
+      try { closeSync(lockFd); } catch { error("LOG_CLEANUP", "log lock descriptor close failed"); }
+      try {
+        const stat = lstatSync(lockFile!);
+        if (stat.isSymbolicLink() || Number(stat.ino) !== identity?.ino || Number(stat.dev) !== identity?.dev) error("LOG_CLEANUP", "log lock ownership changed; retained lock");
+        else unlinkSync(lockFile!);
+      } catch { error("LOG_CLEANUP", "log lock retained; inspect before manual recovery"); }
+    }
+    if (result.issues.some(issue => issue.severity === "error")) result.ok = false;
+  }
+  return result;
+}
+/** Bounded-memory streaming tail/filter reader. It never creates a home, lock or log file. */
+export function readLog(home: string, options: LogReadOptions): LogReadResult {
+  const result: LogReadResult = { ok: false, lines: [], dataLines: null, warnings: [], issues: [] };
+  let fd: number | undefined;
+  try {
+    if (!options || typeof options !== "object" || typeof options.vault !== "string" || Object.keys(options).some(key => !["vault", "limit", "grep", "type"].includes(key))) refuse("L09", "invalid log read options");
+    const limit = options.limit ?? 50;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) refuse("L09", "log limit must be an integer 1..200");
+    if (options.type !== undefined && !(LOG_TYPES as readonly string[]).includes(options.type)) refuse("L09", "unknown log type filter");
+    let filter: ((line: string) => boolean) | undefined;
+    if (options.grep !== undefined) {
+      if (typeof options.grep !== "string" || options.grep.length > 256) refuse("L09", "grep pattern exceeds 256 characters");
+      try { filter = compileLogFilter(options.grep); } catch { refuse("L09", "invalid or unsupported bounded grep expression"); }
+    }
+    const ctx = context(home, options.vault, undefined, false), file = join(ctx.vault.path, "log");
+    try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+    catch (caught) { if ((caught as NodeJS.ErrnoException).code === "ENOENT") return { ...result, ok: true, dataLines: 0 }; throw caught; }
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) refuse("L09", "log must be a plain file");
+    if (stat.size > MAX_LOG_READ_BYTES) refuse("LOG_SIZE", "log exceeds 32 MiB read bound; archive manually");
+    const decoder = new TextDecoder("utf-8", { fatal: true }), buffer = Buffer.alloc(64 * 1024);
+    let pending = "", oversized = false, nonblank = false, comment: boolean | undefined, dataLines = 0, offset = 0, resultBytes = 2;
+    const consume = (piece: string, end: boolean, incomplete = false) => {
+      if (piece.trim()) nonblank = true;
+      if (comment === undefined) { const leading = piece.trimStart(); if (leading) comment = leading.startsWith("#"); }
+      if (!oversized) {
+        if (Buffer.byteLength(pending) + Buffer.byteLength(piece) > MAX_READ_LINE_BYTES) { oversized = true; pending = ""; }
+        else pending += piece;
+      }
+      if (!end) return;
+      if (nonblank && !comment) {
+        dataLines++;
+        if (incomplete || oversized) {
+          const warning = incomplete ? "incomplete final log line omitted" : "historical log line over 4096 bytes omitted";
+          if (!result.warnings.includes(warning)) result.warnings.push(warning);
+        } else {
+          const line = pending.endsWith("\r") ? pending.slice(0, -1) : pending;
+          const type = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}\s+(\S+)/.exec(line)?.[1];
+          if ((!options.type || options.type === type) && (!filter || filter(line))) {
+            result.lines.push(line); resultBytes += Buffer.byteLength(JSON.stringify(line)) + 1;
+            while (result.lines.length > limit || resultBytes > MAX_LOG_RESULT_BYTES) resultBytes -= Buffer.byteLength(JSON.stringify(result.lines.shift()!)) + 1;
+          }
+        }
+      }
+      pending = ""; oversized = false; nonblank = false; comment = undefined;
+    };
+    // Read a fixed descriptor snapshot; concurrent appends belong to the next call.
+    while (offset < stat.size) {
+      const count = readSync(fd, buffer, 0, Math.min(buffer.length, stat.size - offset), offset);
+      if (!count) refuse("LOG_READ", "log changed while reading");
+      offset += count;
+      const parts = decoder.decode(buffer.subarray(0, count), { stream: true }).split("\n");
+      for (let i = 0; i < parts.length; i++) consume(parts[i]!, i < parts.length - 1);
+    }
+    const final = decoder.decode(); if (final) consume(final, false);
+    if (pending || oversized || nonblank) consume("", true, true);
+    if (dataLines > LARGE_LOG_LINES) result.warnings.push("log exceeds 20000 data lines; manual archival recommended");
+    result.dataLines = dataLines; result.ok = true;
+  } catch (caught) {
+    result.lines = [];
+    if (caught instanceof LogRefused) result.issues.push(...caught.issues);
+    else result.issues.push({ code: "LOG_READ", severity: "error", message: "cannot read plain UTF-8 log" });
+  } finally {
+    if (fd !== undefined) { try { closeSync(fd); } catch { result.ok = false; result.issues.push({ code: "LOG_CLOSE", severity: "error", message: "log descriptor close failed" }); } }
+  }
+  return result;
+}

package/src/write-commands.ts

@@ -0,0 +1,93 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { canonicalPath, isDenied } from "./platform.ts";
+import { loadRegistry } from "./registry.ts";
+import { basename } from "node:path";
+import { applyWrite, MAX_WRITE_BYTES } from "./writer.ts";
+import { notePath } from "./write-operations.ts";
+import type { WriteOp, WriteRequest } from "./write-types.ts";
+import { parseTidyMap, tidyVault, TIDY_RULES } from "./tidy.ts";
+const COMMANDS = new Set(["new", "patch", "append", "frontmatter", "link", "supersede", "move", "delete", "tidy", "report", "check"]);
+export function isWriteCommand(command: string): boolean { return COMMANDS.has(command); }
+function object(text: string, label: string): Record<string, unknown> {
+  let value: unknown;
+  try { value = JSON.parse(text); } catch { throw new Error(`${label}: invalid JSON`); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label}: expected object`);
+  return value as Record<string, unknown>;
+}
+function input(file: string, home: string): string {
+  if (file !== "-" && isDenied(canonicalPath(file), loadRegistry(home).denyPaths)) throw new Error("V06: input path denied");
+  const fd = file === "-" ? 0 : openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const stat = fstatSync(fd);
+    if (file !== "-" && (!stat.isFile() || stat.size > MAX_WRITE_BYTES)) throw new Error("input: expected regular file <=256 KiB");
+    const buffer = Buffer.alloc(MAX_WRITE_BYTES + 1); let size = 0;
+    while (size < buffer.length) { const count = readSync(fd, buffer, size, buffer.length - size, null); if (!count) break; size += count; }
+    if (size > MAX_WRITE_BYTES) throw new Error("input: exceeds 256 KiB");
+    const bytes = buffer.subarray(0, size), text = bytes.toString("utf8");
+    if (!Buffer.from(text).equals(bytes)) throw new Error("input: invalid UTF-8");
+    return text;
+  } finally { if (file !== "-") closeSync(fd); }
+}
+export function runWriteCommand(command: string, args: string[], home: string, env: NodeJS.ProcessEnv = process.env): { text: string; code: number } {
+  const valueOptions: Record<string, string[]> = {
+    new: ["--type", "--domain", "--topics", "--description", "--title", "--source", "--confidence", "--status", "--extra", "--body"],
+    patch: ["--old", "--new", "--expected-sha"], append: ["--section", "--markdown", "--expected-sha"],
+    frontmatter: ["--set", "--unset", "--expected-sha"], link: ["--relation", "--context"],
+    move: ["--fingerprint"], delete: ["--fingerprint"], tidy: ["--fingerprint", "--map"], report: ["--body"], check: ["--path"], supersede: [],
+  };
+  // For tidy, --log selects the log-redaction rule; tidy always writes its own LINT event.
+  const values = valueOptions[command] ? [...valueOptions[command]!, ...(command === "tidy" ? [] : ["--log"])] : undefined;
+  if (!values) throw new Error("unknown writer command");
+  const twoStep = ["move", "delete", "tidy"].includes(command);
+  const booleans = ["--json", "--dry-run", ...(twoStep ? ["--confirm"] : []), ...(command === "link" ? ["--one-way"] : []), ...(command === "tidy" ? TIDY_RULES.map(rule => `--${rule}`).concat("--all") : [])];
+  const flags: Record<string, string | boolean> = {}, positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (!arg.startsWith("--")) { positional.push(arg); continue; }
+    if (Object.hasOwn(flags, arg) || (!values.includes(arg) && !booleans.includes(arg))) throw new Error(`${command}: unknown or repeated option`);
+    if (booleans.includes(arg)) flags[arg] = true;
+    else {
+      const value = args[++i];
+      if (value === undefined || value.startsWith("--")) throw new Error(`${arg}: value required`);
+      flags[arg] = value;
+    }
+  }
+  const required = (name: string): string => { if (typeof flags[name] !== "string") throw new Error(`${name}: required`); return flags[name] as string; };
+  const optional = (name: string): string | undefined => typeof flags[name] === "string" ? flags[name] as string : undefined;
+  const count = ["move", "link", "supersede"].includes(command) ? 3 : command === "tidy" ? 1 : 2;
+  if (positional.length !== count) throw new Error(`${command}: requires vault id${count > 1 ? " and target(s)" : ""}`);
+  const vault = positional[0]!, target = positional[1]!;
+  if (command === "tidy") {
+    const all = flags["--all"] === true, rules = TIDY_RULES.filter(rule => all || flags[`--${rule}`] === true);
+    if (all && TIDY_RULES.some(rule => flags[`--${rule}`] === true)) throw new Error("tidy: use rule flags or --all, not both");
+    if (!rules.length) throw new Error("tidy: select at least one rule (--connections --escapes --enums --keys --sources --topics --secrets --log) or --all");
+    if (flags["--dry-run"] && flags["--confirm"]) throw new Error("tidy: --dry-run and --confirm are exclusive");
+    const mapText = optional("--map") !== undefined ? input(required("--map"), home) : undefined;
+    const result = tidyVault(home, { vault, rules, ...(mapText !== undefined ? { map: parseTidyMap(mapText), mapText } : {}), confirm: flags["--confirm"] === true && !flags["--dry-run"], fingerprint: optional("--fingerprint"), channel: "cli" }, { env });
+    return { text: JSON.stringify(result, null, flags["--json"] ? undefined : 2), code: result.ok ? 0 : 1 };
+  }
+  let operation: WriteOp;
+  switch (command) {
+    case "new": {
+      const frontmatter = optional("--extra") ? object(required("--extra"), "extra") : {};
+      for (const key of ["type", "domain", "description", "title", "source", "confidence", "status"]) if (optional(`--${key}`) !== undefined) frontmatter[key] = optional(`--${key}`);
+      if(optional("--source")?.trim().startsWith("["))try{frontmatter.source=JSON.parse(required("--source"));}catch{throw new Error("--source: expected a string or JSON array of strings");}
+      if (optional("--topics") !== undefined) frontmatter.topics = required("--topics").split(",").filter(Boolean).map(value => value.startsWith("[[") ? value : `[[${value}]]`);
+      operation = { op: "create", path: target, frontmatter, ...(optional("--body") ? { body: input(required("--body"), home) } : {}) }; break;
+    }
+    case "patch": operation = { op: "patch", path: target, oldString: required("--old"), newString: required("--new"), expectedSha: optional("--expected-sha") }; break;
+    case "append": operation = { op: "append", path: target, section: required("--section"), markdown: required("--markdown"), expectedSha: optional("--expected-sha") }; break;
+    case "frontmatter": operation = { op: "frontmatter", path: target, set: optional("--set") ? object(required("--set"), "set") : {}, unset: optional("--unset")?.split(","), expectedSha: optional("--expected-sha") }; break;
+    case "link": operation = { op: "link", from: target, to: positional[2]!, relation: required("--relation") as Extract<WriteOp, { op: "link" }>["relation"], context: optional("--context"), bidirectional: !flags["--one-way"] }; break;
+    case "supersede": operation = { op: "supersede", old: target, next: positional[2]! }; break;
+    case "move": operation = { op: "move", from: target, to: positional[2]! }; break;
+    case "delete": operation = { op: "delete", path: target }; break;
+    case "tidy": operation = { op: "tidy" }; break;
+    case "report": operation = { op: "report", path: target, text: input(required("--body"), home) }; break;
+    case "check": operation = { op: "check", path: notePath(optional("--path") ?? (target === "-" ? "checked-note" : basename(target))), text: input(target, home) }; break;
+    default: throw new Error("unknown writer command");
+  }
+  const request: WriteRequest = { vault, operation, channel: "cli", dryRun: flags["--dry-run"] === true, confirm: flags["--confirm"] === true, fingerprint: optional("--fingerprint"), ...(optional("--log") ? { log: object(required("--log"), "log") as unknown as import("./log-types.ts").LogEvent } : {}) };
+  const result = applyWrite(home, request, { env });
+  return { text: JSON.stringify(result, null, flags["--json"] ? undefined : 2), code: result.ok && result.log?.ok !== false ? 0 : 1 };
+}

package/src/write-operations.ts

@@ -0,0 +1,181 @@
+import { normalizeSource } from "./source.ts";
+import { parseFrontmatter, emitFrontmatter } from "./frontmatter.ts";
+import { normalizeTarget, proseLines, rewriteLinkTargets, extractLinks, resolveLinks, type LinkNote } from "./links.ts";
+import type { PlannedChange, WriteIssue, WriteOp } from "./write-types.ts";
+export class WriteRefusal extends Error {
+  constructor(readonly issues: WriteIssue[]) { super(issues[0]?.message ?? "write refused"); }
+}
+export function refuse(code: string, message: string, path?: string): never {
+  throw new WriteRefusal([{ code, severity: "error", message, ...(path ? { path } : {}) }]);
+}
+export function notePath(path: string): string {
+  if (typeof path !== "string") refuse("V04", "expected note path");
+  const value = path.startsWith("notes/") ? path : `notes/${path.endsWith(".md") ? path : `${path}.md`}`;
+  if (!/^notes\/[a-z0-9][a-z0-9-]*\.md$/.test(value) || Buffer.byteLength(value) > 200) refuse("V04", "expected flat lowercase ASCII note path <=200 bytes");
+  return value;
+}
+function needed(notes: Map<string, string>, path: string): string {
+  const source = notes.get(path);
+  if (source === undefined) refuse("V04", "note does not exist", path);
+  return source;
+}
+function document(source: string, path: string) {
+  try { return parseFrontmatter(source); } catch { return refuse("V01", "invalid frontmatter", path); }
+}
+export function h2Sections(body: string): { name: string; start: number; end: number }[] {
+  const visible = proseLines(body), raw = body.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+  const sections: { name: string; start: number; end: number }[] = [];
+  let offset = 0;
+  for (let i = 0; i < raw.length; i++) {
+    const heading = /^ {0,3}##[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/.exec(visible[i] ?? "");
+    if (heading) {
+      if (sections.length) sections[sections.length - 1]!.end = offset;
+      sections.push({ name: heading[1]!, start: offset, end: body.length });
+    }
+    offset += raw[i]!.length;
+  }
+  return sections;
+}
+export function appendSection(source: string, section: string, markdown: string, path: string): string {
+  if (typeof section !== "string" || !section.trim() || section.length > 120 || /[\r\n]/.test(section) || section.trim().replace(/[ \t]+#+$/, "").trim().toLowerCase() === "topics") refuse("V05", "append cannot target Topics or an invalid section");
+  if (typeof markdown !== "string" || Buffer.byteLength(markdown) > 16384 || proseLines(markdown).some(line => /^ {0,3}##[ \t]+Topics(?:[ \t]+#+)?[ \t]*$/i.test(line))) refuse("V05", "append cannot introduce a Topics section or exceed 16384 bytes");
+  const doc = document(source, path), sections = h2Sections(doc.body);
+  const found = sections.filter(item => normalizeTarget(item.name) === normalizeTarget(section.trim()));
+  if (found.length > 1) refuse("V05", "append section is ambiguous");
+  const end = found[0]?.end ?? sections.find(item => item.name.toLowerCase() === "topics")?.start ?? doc.body.length;
+  const addition = found.length ? `\n${markdown.trimEnd()}\n\n` : `\n## ${section.trim()}\n\n${markdown.trimEnd()}\n\n`;
+  return (doc.frontmatter ?? "") + doc.body.slice(0, end).trimEnd() + "\n" + addition + doc.body.slice(end);
+}
+/** Fold scattered `## Connections (...)` sections into `## Relevant Notes`. */
+export function foldConnections(source: string, path: string): string {
+  const doc = document(source, path), sections = h2Sections(doc.body);
+  const connections = sections.filter(section => /^Connections(?:\s*\(.*\))?$/i.test(section.name));
+  if (!connections.length) return source;
+  let body = doc.body, collected: string[] = [];
+  for (const section of connections) collected.push(body.slice(section.start, section.end).replace(/^[^\n]*(?:\n|$)/, "").trim());
+  for (const section of [...connections].reverse()) body = body.slice(0, section.start) + body.slice(section.end);
+  return appendSection((doc.frontmatter ?? "") + body, "Relevant Notes", collected.join("\n\n"), path);
+}
+function normalizedSourceChanges(data:Record<string,unknown>):Record<string,unknown>{
+  const result={...data};
+  if(Object.hasOwn(result,"source")&&result.source!==undefined)try{result.source=normalizeSource(result.source);}catch{refuse("V01","source must contain workspace-relative paths, mem ids or URLs");}
+  return result;
+}
+function bodyAlreadyLinks(notes:Map<string,string>,from:string,to:string):boolean{
+  const doc=document(needed(notes,from),from);let body=doc.body;
+  for(const section of h2Sections(body).filter(section=>section.name.toLowerCase()==="topics").reverse())body=body.slice(0,section.start)+body.slice(section.start,section.end).replace(/[^\r\n]/g," ")+body.slice(section.end);
+  const references=extractLinks(body).map(link=>({...link,heading:null,block:null}));
+  if(!references.length)return false;
+  const metadata:LinkNote[]=[];
+  for(const [path,source] of notes)try{
+    const parsed=parseFrontmatter(source),aliases=parsed.data.aliases??parsed.data.alias;
+    metadata.push({path,title:typeof parsed.data.title==="string"?parsed.data.title:path,aliases:typeof aliases==="string"?[aliases]:Array.isArray(aliases)?aliases.filter((value):value is string=>typeof value==="string"):[],body:""});
+  }catch{ /* Unrelated malformed legacy YAML cannot resolve an alias. */ }
+  return resolveLinks(metadata,new Map([[from,references]])).some(link=>link.source===from&&link.resolved===to);
+}
+/** Plan transformations in memory. This function never touches files. */
+export function planOperation(operation: WriteOp, notes: Map<string, string>, reportBefore?: string | null): PlannedChange[] {
+  const planned = new Map<string, PlannedChange>();
+  const set = (path: string, after: string | null) => {
+    const before = notes.get(path) ?? (operation.op === "report" ? reportBefore ?? null : null);
+    if (after !== before) planned.set(path, { path, before, after });
+  };
+  const existing = (value: string) => { const path = notePath(value); return { path, source: needed(notes, path) }; };
+  switch (operation.op) {
+    case "check": {
+      const path = notePath(operation.path);
+      if (typeof operation.text !== "string") refuse("V01", "check input must be text");
+      // Include unchanged candidates too, so check still validates existing content.
+      planned.set(path, { path, before: notes.get(path) ?? null, after: operation.text });
+      break;
+    }
+    case "create": {
+      const path = notePath(operation.path);
+      if (notes.has(path)) refuse("V08", "note already exists", path);
+      if (!operation.frontmatter || typeof operation.frontmatter !== "object" || Array.isArray(operation.frontmatter)) refuse("V01", "frontmatter must be a mapping");
+      const title = typeof operation.frontmatter.title === "string" ? operation.frontmatter.title : path.slice(6, -3).replaceAll("-", " ");
+      const topics = Array.isArray(operation.frontmatter.topics) ? operation.frontmatter.topics.filter(v => typeof v === "string").join("\n- ") : "";
+      const body = operation.body ?? `# ${title}\n\nThis note argues that ${title}.\n\n## Relevant Notes\n\n## Topics\n\n${topics ? `- ${topics}\n` : ""}`;
+      if (typeof body !== "string") refuse("V01", "body must be text");
+      try { const doc=parseFrontmatter(body),fields={...operation.frontmatter};if(!Object.hasOwn(fields,"source")&&doc.data.source!==undefined)fields.source=doc.data.source;set(path, emitFrontmatter(doc, normalizedSourceChanges(fields))); }
+      catch (error) { if (error instanceof WriteRefusal) throw error; refuse("V01", "cannot emit frontmatter", path); }
+      break;
+    }
+    case "patch": {
+      const { path, source } = existing(operation.path);
+      if (typeof operation.oldString !== "string" || !operation.oldString || typeof operation.newString !== "string" || Buffer.byteLength(operation.oldString) > 8192 || Buffer.byteLength(operation.newString) > 8192) refuse("V09", "patch strings must be bounded and oldString nonempty", path);
+      const first = source.indexOf(operation.oldString);
+      if (first < 0 || source.indexOf(operation.oldString, first + 1) >= 0) refuse("V09", "oldString must match exactly once", path);
+      if(first < (document(source,path).frontmatter?.length ?? 0))refuse("V01","patch cannot target frontmatter; use vmem_set_frontmatter or the frontmatter command",path);
+      set(path, source.slice(0, first) + operation.newString + source.slice(first + operation.oldString.length));
+      break;
+    }
+    case "append": { const { path, source } = existing(operation.path); set(path, appendSection(source, operation.section, operation.markdown, path)); break; }
+    case "frontmatter": {
+      const { path, source } = existing(operation.path);
+      if (!operation.set || typeof operation.set !== "object" || Array.isArray(operation.set) || (operation.unset !== undefined && (!Array.isArray(operation.unset) || operation.unset.some(key => typeof key !== "string")))) refuse("V01", "invalid frontmatter update");
+      const changes = {...operation.set};
+      for (const key of operation.unset ?? []) changes[key] = undefined;
+      try { set(path, emitFrontmatter(document(source, path), normalizedSourceChanges(changes))); } catch (error) { if (error instanceof WriteRefusal) throw error; refuse("V01", "cannot emit frontmatter", path); }
+      break;
+    }
+    case "link": {
+      const from = existing(operation.from), to = existing(operation.to);
+      if (!["supports", "contradicts", "extends", "applies-to", "context-for"].includes(operation.relation)) refuse("V01", "invalid relation");
+      if (operation.context !== undefined && (typeof operation.context !== "string" || /[\r\n]/.test(operation.context) || operation.context.length > 500)) refuse("V01", "link context must be one line <=500 characters");
+      if (from.path === to.path) refuse("V01", "link endpoints must differ");
+      const line = (path: string) => `- [[${path.slice(6, -3)}]] (${operation.relation})${operation.context ? `: ${operation.context}` : ""}`;
+      if(!bodyAlreadyLinks(notes,from.path,to.path))set(from.path, appendSection(from.source, "Relevant Notes", line(to.path), from.path));
+      if (operation.bidirectional !== false && !bodyAlreadyLinks(notes,to.path,from.path)) set(to.path, appendSection(to.source, "Relevant Notes", line(from.path), to.path));
+      break;
+    }
+    case "supersede": {
+      const old = existing(operation.old), next = existing(operation.next);
+      if (old.path === next.path) refuse("V10", "supersession endpoints must differ");
+      set(old.path, emitFrontmatter(document(old.source, old.path), { status: "superseded", superseded_by: `[[${next.path.slice(6, -3)}]]` }));
+      set(next.path, appendSection(next.source, "Relevant Notes", `- Supersedes [[${old.path.slice(6, -3)}]]`, next.path));
+      break;
+    }
+    case "delete": { const { path } = existing(operation.path); set(path, null); break; }
+    case "move": {
+      const from = existing(operation.from), to = notePath(operation.to);
+      if (notes.has(to)) refuse("V08", "move destination already exists", to);
+      const names = new Map<string, Set<string>>();
+      for (const [path, source] of notes) {
+        document(source, path); // Every note must still parse before a move rewrites links.
+        // Links resolve by path only, so alias-only links are left untouched.
+        const key = normalizeTarget(path.slice(6, -3)), values = names.get(key) ?? new Set<string>(); values.add(path); names.set(key, values);
+      }
+      const replace = (target: string): string | undefined => {
+        const candidates = names.get(normalizeTarget(target.replace(/^\.\//, "").replace(/^notes\//i, "").replace(/\.md$/i, "")));
+        return candidates?.size === 1 && candidates.has(from.path) ? to.slice(6, -3) : undefined;
+      };
+      const rewriteValue = (value: unknown): unknown => {
+        if (typeof value === "string") return rewriteLinkTargets(value, replace);
+        if (Array.isArray(value)) return value.map(rewriteValue);
+        if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, rewriteValue(item)]));
+        return value;
+      };
+      for (const [path, source] of notes) {
+        const doc = document(source, path), changes: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(doc.data)) changes[key] = rewriteValue(value);
+        const frontmatter = emitFrontmatter(doc, changes).slice(0, -doc.body.length || undefined);
+        const output = (doc.body.length ? frontmatter : emitFrontmatter(doc, changes)) + rewriteLinkTargets(doc.body, replace);
+        if (path === from.path) { set(path, null); set(to, output); }
+        else set(path, output);
+      }
+      break;
+    }
+    case "tidy": { for (const [path, source] of notes) set(path, foldConnections(source, path)); break; }
+    case "sanitize": {
+      if (typeof operation.path !== "string" || !notes.has(operation.path) || typeof operation.text !== "string") refuse("V04", "sanitize requires an existing snapshot note path and text");
+      set(operation.path, operation.text); break;
+    }
+    case "report": {
+      if (typeof operation.path !== "string" || !/^(?:reports|ops)\/[a-z0-9][a-z0-9./-]*$/.test(operation.path) || operation.path.split("/").some(part => !part || part === "." || part === "..") || Buffer.byteLength(operation.path) > 200 || typeof operation.text !== "string") refuse("V04", "invalid report path");
+      set(operation.path, operation.text); break;
+    }
+    default: refuse("V01", "unknown write operation");
+  }
+  return [...planned.values()].sort((a, b) => a.path.localeCompare(b.path));
+}

package/src/write-types.ts

@@ -0,0 +1,50 @@
+import type { LogEvent, LogReceipt } from "./log-types.ts";
+import type { VaultSpec, VmemConfig } from "./config.ts";
+export type WriteOp =
+  | { op: "check"; path: string; text: string }
+  | { op: "create"; path: string; frontmatter: Record<string, unknown>; body?: string }
+  | { op: "patch"; path: string; oldString: string; newString: string; expectedSha?: string }
+  | { op: "append"; path: string; section: string; markdown: string; expectedSha?: string }
+  | { op: "frontmatter"; path: string; set: Record<string, unknown>; unset?: string[]; expectedSha?: string }
+  | { op: "link"; from: string; to: string; relation: "supports" | "contradicts" | "extends" | "applies-to" | "context-for"; context?: string; bidirectional?: boolean }
+  | { op: "supersede"; old: string; next: string }
+  | { op: "move"; from: string; to: string }
+  | { op: "delete"; path: string }
+  | { op: "tidy" }
+  /** Whole-note replacement used by `tidy` rules; the text is validated like any other write. */
+  | { op: "sanitize"; path: string; text: string }
+  | { op: "report"; path: string; text: string };
+export interface WriteRequest {
+  vault: string;
+  operation: WriteOp;
+  channel?: "cli" | "mcp";
+  dryRun?: boolean;
+  confirm?: boolean;
+  fingerprint?: string;
+  expectedShas?: Record<string, string>;
+  log?: LogEvent | false;
+}
+export interface WriteIssue { code: string; severity: "error" | "warning"; path?: string; message: string }
+export interface PlannedChange { path: string; before: string | null; after: string | null }
+export interface ValidationContext {
+  vault: VaultSpec;
+  config: VmemConfig;
+  /** Original flat notes snapshot, paths prefixed with notes/. */
+  notes: Map<string, string>;
+  operation: WriteOp;
+}
+export interface ChangeReceipt { path: string; beforeSha: string | null; sha256: string | null; bytes: number }
+export interface WriteReceipt {
+  ok: boolean;
+  applied: boolean;
+  /** A link request whose requested sides already have body references made no changes. */
+  unchanged?: boolean;
+  issues: WriteIssue[];
+  changes: ChangeReceipt[];
+  fingerprint?: string;
+  preview?: boolean;
+  possibleDuplicates?: string[];
+  indexUpdated: boolean;
+  logged?: boolean;
+  log?: LogReceipt;
+}