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

package/src/promote-command.ts

@@ -0,0 +1,77 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync, readSync, rmSync, writeFileSync, mkdtempSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadRegistry } from "./registry.ts";
+import { canonicalPath, isDenied } from "./platform.ts";
+import { MAX_WRITE_BYTES } from "./writer.ts";
+import { listPromotionCandidates, promoteFromAmem, type PromoteRequest } from "./promote.ts";
+
+const VALUES = ["--project", "--limit", "--stem", "--type", "--domain", "--topics", "--description", "--title", "--body", "--link-to", "--log-project", "--fingerprint"];
+const BOOLEANS = ["--all-projects", "--edit", "--confirm", "--json"];
+function readBody(file: string, home: string): string {
+  if (file !== "-" && isDenied(canonicalPath(file), loadRegistry(home).denyPaths)) throw new Error("V06: body path denied");
+  const fd = file === "-" ? 0 : openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    if (file !== "-" && (!fstatSync(fd).isFile() || fstatSync(fd).size > MAX_WRITE_BYTES)) throw new Error("body: expected regular file <=256 KiB");
+    const buffer = Buffer.alloc(MAX_WRITE_BYTES + 1); let size = 0;
+    while (size < buffer.length) { const n = readSync(fd, buffer, size, buffer.length - size, null); if (!n) break; size += n; }
+    if (size > MAX_WRITE_BYTES) throw new Error("body: exceeds 256 KiB");
+    const bytes = buffer.subarray(0, size), text = bytes.toString("utf8");
+    if (!Buffer.from(text).equals(bytes)) throw new Error("body: invalid UTF-8");
+    return text;
+  } finally { if (file !== "-") closeSync(fd); }
+}
+/** Optional editor branch: the only place that looks at whether stdin is a terminal. */
+function editBody(draft: string, env: NodeJS.ProcessEnv, stdinIsTTY: boolean): string | undefined {
+  const editor = env.VISUAL?.trim() || env.EDITOR?.trim();
+  if (!stdinIsTTY || !editor) return undefined;
+  const dir = mkdtempSync(join(tmpdir(), "vmem-promote-")), file = join(dir, "note.md");
+  try {
+    writeFileSync(file, draft, { mode: 0o600 });
+    const result = spawnSync(editor, [file], { stdio: "inherit", shell: false });
+    if (result.status !== 0) throw new Error("editor exited with an error; nothing promoted");
+    return readFileSync(file, "utf8");
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+}
+/** `vmem promote-from-amem <vault> [<mem-id>] ...`: lists candidates, previews, or confirms one promotion. */
+export async function runPromoteCommand(args: string[], home: string, env: NodeJS.ProcessEnv, io: { stdinIsTTY?: boolean } = {}): Promise<{ text: string; code: number }> {
+  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(`promote-from-amem: unknown or repeated option ${arg}`);
+    if (BOOLEANS.includes(arg)) { flags[arg] = true; continue; }
+    const value = args[++i];
+    if (value === undefined || (value.startsWith("--") && value !== "-")) throw new Error(`${arg}: value required`);
+    flags[arg] = value;
+  }
+  const value = (name: string) => typeof flags[name] === "string" ? flags[name] as string : undefined;
+  const format = (result: unknown) => JSON.stringify(result, null, flags["--json"] ? undefined : 2);
+  if (positional.length < 1 || positional.length > 2) throw new Error("promote-from-amem: requires vault id and optional mem id");
+  const [vault, rawId] = positional as [string, string | undefined];
+  if (!loadRegistry(home).vaults.some(v => v.id === vault)) throw new Error("promote-from-amem: unknown vault id");
+  if (rawId === undefined) {
+    if (flags["--all-projects"] && value("--project")) throw new Error("choose either --all-projects or --project");
+    const limit = value("--limit") === undefined ? undefined : /^[0-9]+$/.test(value("--limit")!) ? Number(value("--limit")) : NaN;
+    const list = await listPromotionCandidates({ env, allProjects: flags["--all-projects"] === true, ...(value("--project") ? { project: value("--project") } : {}), ...(limit !== undefined ? { limit } : {}), piiPatterns: loadRegistry(home).piiPatterns });
+    return { text: format(list), code: 0 };
+  }
+  if (flags["--all-projects"]) throw new Error("--all-projects lists candidates only");
+  const request: PromoteRequest = { vault, id: rawId.replace(/^mem:/, ""), channel: "cli", confirm: flags["--confirm"] === true };
+  for (const [flag, key] of [["--stem", "stem"], ["--type", "type"], ["--domain", "domain"], ["--description", "description"], ["--title", "title"], ["--link-to", "linkTo"], ["--log-project", "logProject"], ["--fingerprint", "fingerprint"]] as const) {
+    if (value(flag) !== undefined) (request as unknown as Record<string, unknown>)[key] = value(flag);
+  }
+  if (value("--topics") !== undefined) request.topics = value("--topics")!.split(",").map(t => t.trim()).filter(Boolean);
+  if (value("--body") !== undefined) request.body = readBody(value("--body")!, home);
+  const options = { env, ...(value("--project") ? { project: value("--project") } : {}) };
+  // The editor runs on the preview only; confirm always uses exactly what the preview showed.
+  if (flags["--edit"] && request.body === undefined && !request.confirm) {
+    const draft = await promoteFromAmem(home, request, options);
+    const edited = draft.text !== undefined ? editBody(draft.text, env, io.stdinIsTTY === true) : undefined;
+    if (edited !== undefined) request.body = edited;
+  }
+  const result = await promoteFromAmem(home, request, options);
+  const edited = flags["--edit"] && request.body !== undefined && value("--body") === undefined;
+  return { text: format(edited ? { ...result, hint: "edited text is only previewed: save it and confirm with --body <file> and this fingerprint" } : result), code: result.ok ? 0 : 1 };
+}

package/src/promote.ts

@@ -0,0 +1,167 @@
+import { createHash } from "node:crypto";
+import type { VaultSpec } from "./config.ts";
+import { emitFrontmatter, parseFrontmatter } from "./frontmatter.ts";
+import { loadRegistry } from "./registry.ts";
+import { VaultIndex } from "./vault-index.ts";
+import { applyWrite } from "./writer.ts";
+import { notePath } from "./write-operations.ts";
+import type { WriteIssue, WriteReceipt } from "./write-types.ts";
+import type { AmemCandidate, AmemSeam, AmemOptions } from "./amem/seam.ts";
+
+/** Explicit metadata that overrides the prefill from the agent-mem entry. */
+export interface PromoteMetadata { stem?: string; type?: string; domain?: string; topics?: string[]; description?: string; title?: string; body?: string; logProject?: string }
+export interface PromoteRequest extends PromoteMetadata {
+  vault: string;
+  id: string;
+  /** Link the candidate to an existing note instead of creating one. */
+  linkTo?: string;
+  confirm?: boolean;
+  fingerprint?: string;
+  channel?: "cli" | "mcp";
+}
+export interface PromoteResult {
+  ok: boolean;
+  action: "create" | "link";
+  applied: boolean;
+  preview?: boolean;
+  id: string;
+  path: string | null;
+  text?: string;
+  fingerprint?: string;
+  issues: WriteIssue[];
+  possibleDuplicates?: string[];
+  /** Choices offered when the note may already exist in the vault. */
+  choices?: string[];
+  note?: WriteReceipt;
+  linked?: string | null;
+  alreadyLinked?: boolean;
+}
+export interface SeamFactory { (options: AmemOptions): Promise<AmemSeam> }
+const defaultSeam: SeamFactory = async options => (await import("./amem/seam.ts")).openAmem(options);
+const ID = /^[a-f0-9]{32}$/;
+const sha = (value: unknown) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const issue = (code: string, message: string, path?: string): WriteIssue => ({ code, severity: "error", message, ...(path ? { path } : {}) });
+
+export function stemFor(title: string): string {
+  const stem = title.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80).replace(/-+$/, "");
+  return /^[a-z0-9]/.test(stem) ? stem : "";
+}
+/** The vault log's project field: an explicit value, else the last segment of the agent-mem project key. */
+export function logProjectFor(project: string, explicit?: string): string {
+  if (explicit !== undefined) return explicit;
+  const slug = (project.split(/[/:]/).filter(Boolean).at(-1) ?? "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return /^[a-z0-9][a-z0-9-]*$/.test(slug) ? slug : "-";
+}
+function firstSentence(text: string): string {
+  const line = text.replace(/\s+/g, " ").trim(), cut = /^(.{20,200}?[.!?])(?:\s|$)/.exec(line)?.[1] ?? line.slice(0, 200);
+  return cut.trim();
+}
+/** Prefilled note text: H1 from the title, body from the entry text, about[] as hints, provenance in frontmatter. */
+export function draftNote(entry: AmemCandidate, meta: PromoteMetadata, now = new Date()): { stem: string; frontmatter: Record<string, unknown>; text: string } {
+  const title = meta.title ?? entry.title ?? firstSentence(entry.text);
+  const stem = meta.stem ?? stemFor(title);
+  const topics = (meta.topics ?? []).map(value => value.startsWith("[[") ? value : `[[${value}]]`);
+  const frontmatter: Record<string, unknown> = {
+    title, description: meta.description ?? firstSentence(entry.text), type: meta.type ?? (entry.kind === "decision" ? "decision" : entry.kind === "fail" ? "method" : "insight"),
+    ...(meta.domain ? { domain: meta.domain } : {}), topics, promoted_from: `mem:${entry.id}`, promoted_at: now.toISOString().slice(0, 10),
+  };
+  const hints = entry.about.length ? `${entry.about.slice(0, 20).map(node => `- ${node.replace(/[\r\n[\]]/g, " ")}`).join("\n")}\n` : "";
+  const body = meta.body ?? `# ${title}\n\n${entry.text.trim()}\n\n## Relevant Notes\n\n${hints}\n## Topics\n\n${topics.map(topic => `- ${topic}`).join("\n")}\n`;
+  return { stem, frontmatter, text: emitFrontmatter(parseFrontmatter(body), frontmatter) };
+}
+function vaultSpec(home: string, id: string): { spec: VaultSpec; all: VaultSpec[] } {
+  const all = loadRegistry(home).vaults, spec = all.find(v => v.id === id);
+  if (!spec) throw new Error("promote: unknown vault id");
+  return { spec, all };
+}
+const fold = (value: string) => value.normalize("NFKC").toLowerCase().replace(/[-_\s]+/g, " ").trim();
+/** Existing notes with the same stem or title, plus close FTS title matches: the link-existing choices. */
+function similar(home: string, spec: VaultSpec, all: VaultSpec[], title: string, stem: string): string[] {
+  const index = new VaultIndex(home, spec, all.map(v => v.path));
+  try {
+    index.scan();
+    const words = title.normalize("NFKC").split(/[^\p{L}\p{N}]+/u).filter(word => word.length > 2).slice(0, 8);
+    const hits = words.length ? index.search(words.join(" "), { limit: 5 }) : [];
+    const exact = hits.filter(hit => fold(hit.title) === fold(title) || hit.path === `${stem}.md`);
+    return [...exact, ...hits].map(hit => `notes/${hit.path}`).filter((path, i, list) => list.indexOf(path) === i).slice(0, 5);
+  } catch { return []; } finally { index.close(); }
+}
+function lookup(home: string, spec: VaultSpec, all: VaultSpec[], id: string, linkTo?: string): { promoted: string[]; target?: string } {
+  const index = new VaultIndex(home, spec, all.map(v => v.path));
+  try {
+    index.scan();
+    const promoted = index.promotedFrom(`mem:${id}`).map(path => `notes/${path}`);
+    let target: string | undefined;
+    if (linkTo !== undefined) target = `notes/${index.show(linkTo, 1).path}`;
+    return { promoted, ...(target ? { target } : {}) };
+  } finally { index.close(); }
+}
+
+/**
+ * Two-step promotion of one agent-mem entry. Without `confirm` nothing is written and the result carries
+ * the full note text (or the link to record) and a fingerprint. With `confirm` the fingerprint must match
+ * the recomputed preview; then the note is created through applyWrite, one LEARN event is appended, and
+ * the vault link is recorded last. If that last step fails the candidate stays listed, and a rerun finds
+ * the note through `promoted_from` and offers link-only instead of a second note.
+ */
+export async function promoteFromAmem(home: string, request: PromoteRequest, options: { env?: NodeJS.ProcessEnv; project?: string; cwd?: string; seam?: SeamFactory; now?: Date } = {}): Promise<PromoteResult> {
+  const base: PromoteResult = { ok: false, action: "create", applied: false, id: request.id, path: null, issues: [] };
+  if (!ID.test(request.id)) return { ...base, issues: [issue("AMEM", "expected a 32-hex agent-mem entry id")] };
+  const { spec, all } = vaultSpec(home, request.vault);
+  if (spec.write === "none" || (request.channel === "mcp" && spec.write !== "mcp")) return { ...base, issues: [issue("POLICY", "vault write policy refuses this channel")] };
+  const seam = await (options.seam ?? defaultSeam)({ env: options.env, ...(options.project ? { project: options.project } : {}), ...(options.cwd ? { cwd: options.cwd } : {}), piiPatterns: loadRegistry(home).piiPatterns });
+  try {
+    const entry = await seam.entry(request.id);
+    if (!entry) return { ...base, issues: [issue("AMEM", "entry is not an available curated entry of this project")] };
+    const linked = seam.linkedPath(request.id) ?? null;
+    const { promoted, target } = lookup(home, spec, all, request.id, request.linkTo);
+    // Link-only: an earlier promotion already created the note, or the caller chose an existing note.
+    const existing = target ?? promoted[0];
+    if (existing) {
+      const fingerprint = sha({ action: "link", id: request.id, path: existing, linked, vault: spec.id });
+      const result: PromoteResult = { ...base, action: "link", path: existing, fingerprint, linked, alreadyLinked: linked === existing, ok: true,
+        ...(promoted.length && !target ? { choices: [`link-only ${existing}`] } : {}) };
+      if (request.confirm !== true) return { ...result, preview: true };
+      if (request.fingerprint !== fingerprint) return { ...result, ok: false, issues: [issue("V09", "stale or missing preview fingerprint")] };
+      if (linked === existing) return { ...result, applied: false };
+      await seam.recordLink(request.id, existing);
+      return { ...result, applied: true, linked: existing };
+    }
+    const draft = draftNote(entry, request, options.now);
+    if (!draft.stem) return { ...base, issues: [issue("V04", "cannot derive an ASCII stem from the title; pass --stem")] };
+    let path: string;
+    try { path = notePath(draft.stem); } catch { return { ...base, issues: [issue("V04", "expected a flat lowercase ASCII stem")] }; }
+    const operation = { op: "create" as const, path: draft.stem, frontmatter: {}, body: draft.text };
+    const planned = applyWrite(home, { vault: spec.id, operation, channel: request.channel ?? "cli", dryRun: true }, { env: options.env });
+    const v08 = planned.issues.some(i => i.code === "V08") || (planned.possibleDuplicates?.length ?? 0) > 0;
+    const possibleDuplicates = v08 ? [...new Set([...(planned.possibleDuplicates ?? []), ...similar(home, spec, all, String(draft.frontmatter.title), draft.stem)])].filter(p => p !== path) : [];
+    const fingerprint = sha({ action: "create", id: request.id, write: planned.fingerprint, text: draft.text, linked, vault: spec.id });
+    const result: PromoteResult = { ...base, ok: planned.ok, path, text: draft.text, fingerprint, issues: planned.issues, linked,
+      ...(possibleDuplicates.length ? { possibleDuplicates, choices: ["create", ...possibleDuplicates.map(p => `link-existing ${p}`)] } : {}) };
+    if (request.confirm !== true || !planned.ok) return { ...result, preview: request.confirm !== true };
+    if (request.fingerprint !== fingerprint) return { ...result, ok: false, issues: [issue("V09", "stale or missing preview fingerprint")] };
+    const note = applyWrite(home, { vault: spec.id, operation, channel: request.channel ?? "cli",
+      log: { type: "LEARN", project: logProjectFor(seam.project, request.logProject), source: `mem:${request.id}`, dest: path, note: `promoted: ${entry.kind}` } }, { env: options.env });
+    if (!note.ok || !note.applied) return { ...result, ok: false, note, issues: note.issues };
+    try {
+      await seam.recordLink(request.id, path);
+      return { ...result, ok: note.log?.ok !== false, applied: true, note, linked: path, issues: note.log?.ok === false ? note.log.issues : [] };
+    } catch (error) {
+      return { ...result, ok: false, applied: true, note, linked: null, choices: [`link-only ${path}`],
+        issues: [issue("LINK", `note created but the agent-mem link failed (${error instanceof Error ? error.message.slice(0, 200) : "error"}); rerun to record the link only`)] };
+    }
+  } finally { seam.close(); }
+}
+/** Candidate table: one project (default: the current one) or every readable project. */
+export async function listPromotionCandidates(options: { env?: NodeJS.ProcessEnv; project?: string; cwd?: string; allProjects?: boolean; limit?: number; piiPatterns?: string[]; seam?: SeamFactory }): Promise<{ projects: { project: string; candidates: { id: string; project: string; kind: string; title: string | null; at: string }[] }[] }> {
+  const limit = options.limit ?? 50;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new Error("limit: expected integer 1..200");
+  const brief = (c: AmemCandidate) => ({ id: c.id, project: c.project, kind: c.kind, title: c.title ?? firstSentence(c.text), at: c.at });
+  if (options.allProjects) {
+    const { allProjectCandidates } = await import("./amem/seam.ts");
+    return { projects: (await allProjectCandidates({ env: options.env, limit, piiPatterns: options.piiPatterns })).map(p => ({ project: p.project, candidates: p.candidates.map(brief) })) };
+  }
+  const seam = await (options.seam ?? defaultSeam)({ env: options.env, ...(options.project ? { project: options.project } : {}), ...(options.cwd ? { cwd: options.cwd } : {}), piiPatterns: options.piiPatterns });
+  try { return { projects: [{ project: seam.project, candidates: (await seam.candidates(limit)).map(brief) }] }; }
+  finally { seam.close(); }
+}

package/src/read-commands.ts

@@ -0,0 +1,43 @@
+import { loadRegistry } from "./registry.ts";
+import { VaultIndex, MAX_NOTE_BYTES } from "./vault-index.ts";
+const READ_COMMANDS = new Set(["rebuild", "search", "show", "links"]);
+export function isReadCommand(command: string): boolean { return READ_COMMANDS.has(command); }
+export function runReadCommand(command: string, args: string[], home: string): { text: string; code: number } {
+  const options: Record<string, string | boolean> = {}, positional: string[] = [];
+  const allowed = command === "search" ? ["--limit", "--type", "--domain"] : command === "show" ? ["--max-bytes", "--section", "--offset"] : command === "links" ? ["--limit"] : [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (!arg.startsWith("-")) { positional.push(arg); continue; }
+    if (Object.hasOwn(options, arg) || (arg !== "--json" && !allowed.includes(arg))) throw new Error(`${command}: unknown or repeated option ${arg}`);
+    if (arg === "--json") { options[arg] = true; continue; }
+    const value = args[++i];
+    if (!value || value.startsWith("--")) throw new Error(`${arg}: value required`);
+    options[arg] = value;
+  }
+  if (positional.length !== (command === "rebuild" ? 1 : 2)) throw new Error(`${command}: requires vault id${command === "rebuild" ? "" : " and query/target"}`);
+  const registry = loadRegistry(home), vault = registry.vaults.find(v => v.id === positional[0]);
+  if (!vault) throw new Error(`${command}: unknown vault id`);
+  const number = (name: string): number | undefined => {
+    if (options[name] === undefined) return undefined;
+    if (!/^[0-9]+$/.test(String(options[name]))) throw new Error(`${name}: expected integer`);
+    return Number(options[name]);
+  };
+  const limit = number("--limit"), maxBytes = number("--max-bytes"), offset = number("--offset");
+  // Validate bounds before opening or updating a derived cache.
+  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1 || limit > 500)) throw new Error("limit: expected integer 1..500");
+  if (maxBytes !== undefined && (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 65536)) throw new Error("max-bytes: expected integer 1..65536");
+  if (offset !== undefined && (!Number.isSafeInteger(offset) || offset < 0 || offset > MAX_NOTE_BYTES)) throw new Error(`offset: expected integer 0..${MAX_NOTE_BYTES}`);
+  const section = options["--section"] as string | undefined;
+  if (section !== undefined && (!section.trim() || /[\r\n]/.test(section) || Buffer.byteLength(section) > 1024)) throw new Error("section: expected one exact H2 heading <=1024 bytes");
+  const index = new VaultIndex(home, vault, registry.vaults.map(v => v.path));
+  let result: unknown;
+  try {
+    const scan = index.scan(command === "rebuild");
+    if (command === "rebuild") result = { vault: vault.id, ...scan };
+    else if (command === "search") result = index.search(positional[1]!, { limit, type: options["--type"] as string | undefined, domain: options["--domain"] as string | undefined });
+    else if (command === "show") result = index.show(positional[1]!, maxBytes, section, offset);
+    else if (command === "links") result = index.links(positional[1]!, limit);
+    else throw new Error("unknown read command");
+  } finally { index.close(); }
+  return { text: JSON.stringify(result, null, options["--json"] ? undefined : 2), code: 0 };
+}

package/src/registry.ts

@@ -0,0 +1,170 @@
+import { closeSync, constants, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { CONFIG_FILE, MAX_CONFIG_BYTES, parseConfig, parseVault, readConfig, type VaultSpec, type VmemConfig } from "./config.ts";
+export const LOCK_FILE = "config.lock";
+const TEMP = /^\.config-[0-9a-f-]{36}\.tmp$/;
+export interface LockOwner { pid: number; host: string; created: string }
+export function loadRegistry(home: string): VmemConfig {
+  const config = readConfig(home);
+  if (config.home) throw new Error(`${join(home, CONFIG_FILE)}: redirected home cannot contain another home pointer`);
+  return config;
+}
+/** Effective pii policy: explicit value, else deny for org and allow for personal. */
+export function effectivePii(vault: VaultSpec): "allow" | "deny" { return vault.pii ?? (vault.kind === "org" ? "deny" : "allow"); }
+function message(error: unknown): string { return error instanceof Error ? error.message : String(error); }
+/**
+ * Directory fsync makes the rename durable on Linux. On macOS fsync(2) on a directory
+ * succeeds but does not force the drive cache (no F_FULLFSYNC); Windows cannot open
+ * directories for fsync, so the rename is atomic but durability is left to the OS there.
+ */
+export function syncDirectory(dir: string, platform: NodeJS.Platform = process.platform): boolean {
+  if (platform === "win32") return false;
+  const fd = openSync(dir, constants.O_RDONLY);
+  try { fsyncSync(fd); return true; } finally { closeSync(fd); }
+}
+function mutate<T>(home: string, update: (config: VmemConfig) => T): T {
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  const lock = join(home, LOCK_FILE);
+  let lockFd: number;
+  try { lockFd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`${lock}: registry is locked by another writer; run \`vmem recover\` if no writer is running`, { cause: error });
+    throw new Error(`${lock}: cannot create registry lock`, { cause: error });
+  }
+  let temporary: string | undefined;
+  let primary: unknown;
+  let failed = false;
+  try {
+    const owner: LockOwner = { pid: process.pid, host: hostname(), created: new Date().toISOString() };
+    writeFileSync(lockFd, JSON.stringify(owner) + "\n");
+    const config = loadRegistry(home), result = update(config);
+    parseConfig(config);
+    const text = JSON.stringify(config, null, 2) + "\n";
+    if (Buffer.byteLength(text) > MAX_CONFIG_BYTES) throw new Error(`${join(home, CONFIG_FILE)}: serialized config exceeds 64 KiB`);
+    const candidate = join(home, `.config-${randomUUID()}.tmp`);
+    const fd = openSync(candidate, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    temporary = candidate;
+    try { writeFileSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
+    renameSync(temporary, join(home, CONFIG_FILE));
+    temporary = undefined;
+    syncDirectory(home);
+    return result;
+  } catch (error) {
+    failed = true; primary = error;
+    throw error;
+  } finally {
+    // Each cleanup is independent: a temp cleanup error must not strand our lock.
+    const cleanupErrors: string[] = [];
+    for (const [label, cleanup] of [
+      ["temporary file", () => { if (temporary) unlinkSync(temporary); }],
+      ["lock descriptor", () => closeSync(lockFd)],
+      [`lock retained at ${lock}`, () => unlinkSync(lock)],
+    ] as const) {
+      try { cleanup(); } catch (error) { cleanupErrors.push(`${label}: ${message(error)}`); }
+    }
+    if (cleanupErrors.length) {
+      const note = `cleanup failed (${cleanupErrors.join("; ")})`;
+      // Keep the primary error as the thrown error and add the cleanup failure to it.
+      if (failed && primary instanceof Error) primary.message = `${primary.message}; ${note}`;
+      else if (!failed) throw new Error(`${home}: registry updated but ${note}`);
+    }
+  }
+}
+function lockOwner(lock: string): LockOwner | undefined {
+  try {
+    const value = JSON.parse(readFileSync(lock, "utf8")) as Partial<LockOwner>;
+    if (typeof value.pid === "number" && Number.isInteger(value.pid) && value.pid > 0 && typeof value.host === "string" && typeof value.created === "string") return value as LockOwner;
+  } catch { /* unreadable or legacy lock */ }
+  return undefined;
+}
+function alive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return (error as NodeJS.ErrnoException).code !== "ESRCH"; }
+}
+export interface RecoveryReport {
+  applied: boolean;
+  lock: { path: string; state: "absent" | "live" | "stale" | "unknown"; owner?: LockOwner; removed: boolean };
+  temporaryFiles: string[];
+  removedTemporaryFiles: string[];
+  blocked?: string;
+}
+/**
+ * Crash recovery. Preview unless confirm. A lock is stale only when its owner record names this host
+ * and a pid that no longer exists; live, foreign-host and unreadable locks are never removed.
+ * Leftover `.config-<uuid>.tmp` files are removed only when no live or unknown lock is held.
+ */
+export function recoverRegistry(home: string, confirm = false): RecoveryReport {
+  const path = join(home, LOCK_FILE);
+  let entries: string[] = [];
+  try { entries = readdirSync(home); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw new Error(`${home}: cannot list registry home`, { cause: error }); }
+  const temporaryFiles = entries.filter(name => TEMP.test(name)).sort();
+  const report: RecoveryReport = { applied: false, lock: { path, state: "absent", removed: false }, temporaryFiles, removedTemporaryFiles: [] };
+  if (entries.includes(LOCK_FILE)) {
+    const owner = lockOwner(path);
+    if (owner) report.lock.owner = owner;
+    report.lock.state = !owner || owner.host !== hostname() ? "unknown" : alive(owner.pid) ? "live" : "stale";
+  }
+  if (report.lock.state === "live" || report.lock.state === "unknown") {
+    report.blocked = report.lock.state === "live" ? "a live writer holds the lock" : "lock owner cannot be verified on this host; confirm no writer runs, then remove the lock manually";
+    return report;
+  }
+  if (!confirm) return report;
+  report.applied = true;
+  if (report.lock.state === "stale") {
+    // Re-check immediately before removal to narrow the window against a new writer.
+    const again = lockOwner(path);
+    if (!again || again.pid !== report.lock.owner?.pid || again.created !== report.lock.owner.created) { report.applied = false; report.blocked = "lock changed during recovery"; return report; }
+    unlinkSync(path); report.lock.removed = true;
+  }
+  for (const name of temporaryFiles) {
+    try { unlinkSync(join(home, name)); report.removedTemporaryFiles.push(name); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw new Error(`${join(home, name)}: cannot remove temporary file`, { cause: error }); }
+  }
+  return report;
+}
+export function addVault(home: string, value: unknown): VaultSpec {
+  const vault = parseVault(value);
+  try { vault.path = realpathSync(vault.path); }
+  catch (error) { throw new Error(`vault ${vault.id}: path ${vault.path} is unavailable`, { cause: error }); }
+  const notes = join(vault.path, "notes");
+  let isDir = false;
+  try { isDir = statSync(notes).isDirectory(); } catch { /* reported below */ }
+  if (!isDir) throw new Error(`vault ${vault.id}: ${vault.path} must contain notes directory`);
+  if (realpathSync(notes) !== notes) throw new Error(`vault ${vault.id}: ${notes} must not be a symlink`);
+  return mutate(home, config => {
+    if (config.vaults.some(v => v.id === vault.id)) throw new Error(`vault ${vault.id}: id already registered`);
+    if (config.vaults.some(v => {
+      if (v.path === vault.path) return true;
+      try { return realpathSync(v.path) === vault.path; }
+      catch (error) {
+        if (["ENOENT", "ENOTDIR", "EACCES", "ELOOP"].includes((error as NodeJS.ErrnoException).code ?? "")) return false;
+        throw error;
+      }
+    })) throw new Error(`vault ${vault.id}: path ${vault.path} already registered`);
+    config.vaults.push(vault);
+    return vault;
+  });
+}
+export function removeVault(home: string, id: string, confirm = false): { applied: boolean; vault: VaultSpec } {
+  const remove = (config: VmemConfig) => {
+    const vault = config.vaults.find(v => v.id === id);
+    if (!vault) throw new Error(`${join(home, CONFIG_FILE)}: unknown vault id ${id}`);
+    if (confirm) config.vaults = config.vaults.filter(v => v.id !== id);
+    return { applied: confirm, vault };
+  };
+  return confirm ? mutate(home, remove) : remove(loadRegistry(home));
+}
+export function registryStatus(home: string) {
+  const config = loadRegistry(home);
+  return config.vaults.map(vault => {
+    const base = { ...vault, pii: effectivePii(vault) };
+    try {
+      const root = realpathSync(vault.path), notes = join(root, "notes");
+      if (root !== vault.path || realpathSync(notes) !== notes || !statSync(notes).isDirectory()) throw new Error("changed");
+      return { ...base, healthy: true };
+    } catch { return { ...base, healthy: false, issue: "vault path or notes directory unavailable or changed" }; }
+  });
+}