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

package/src/mcp-vault.ts

@@ -0,0 +1,167 @@
+import { analysisInput } from "./analysis-input.ts";
+import { buildGraph, graphNeighbors } from "./vault-graph.ts";
+import { lintVault } from "./vault-lint.ts";
+import { writeAnalysisReports } from "./analysis-reports.ts";
+import { parseFrontmatter } from "./frontmatter.ts";
+import type { VaultSpec } from "./config.ts";
+import { loadRegistry, registryStatus } from "./registry.ts";
+import { VaultIndex, MAX_NOTE_BYTES } from "./vault-index.ts";
+import { appendLog, readLog } from "./vault-log.ts";
+import { applyWrite } from "./writer.ts";
+import { notePath } from "./write-operations.ts";
+import type { LogEvent } from "./log-types.ts";
+import type { WriteOp, WriteReceipt, WriteRequest } from "./write-types.ts";
+import type { McpHandler, McpTool } from "./mcp.ts";
+
+const string = (maxLength: number, minLength = 1) => ({ type: "string", minLength, maxLength });
+const integer = (minimum: number, maximum: number) => ({ type: "integer", minimum, maximum });
+const object = (properties: Record<string, unknown>, required: string[] = []) => ({ type: "object", properties, required, additionalProperties: false });
+const tool = (name: string, description: string, inputSchema: Record<string, unknown>, kind: "read" | "write" | "confirm" = "read"): McpTool => ({
+  name, description, inputSchema, annotations: { readOnlyHint: kind === "read", destructiveHint: kind === "confirm", idempotentHint: kind === "read", openWorldHint: false },
+});
+const RELATIONS = ["supports", "contradicts", "extends", "applies-to", "context-for"];
+const LOG_TYPES = ["INGEST", "ROUTE", "EXTRACT", "CONNECT", "DIGEST", "LEARN", "LINT", "TASK", "GRAPH", "SYNC", "RETHINK", "SOURCE"];
+const note = string(1024), sha = { type: "string", minLength: 64, maxLength: 64 };
+const logEvent = object({ type: { type: "string", enum: LOG_TYPES }, project: string(64), source: string(512), dest: string(512), note: string(500) }, ["type", "project", "source", "note"]);
+const scalar = { type: ["string", "number", "boolean", "null", "array"], maxLength: 4096, maxItems: 64, items: { type: ["string", "number", "boolean"], maxLength: 1024 } };
+
+/** Tool names for the implemented read, write, log, analysis and promotion providers. */
+export const VMEM_TOOL_NAMES = ["vmem_status", "vmem_search", "vmem_read", "vmem_read_many", "vmem_list", "vmem_links", "vmem_mocs", "vmem_check", "vmem_log_tail",
+  "vmem_create", "vmem_patch", "vmem_append", "vmem_set_frontmatter", "vmem_link", "vmem_supersede", "vmem_log_append", "vmem_move", "vmem_delete", "vmem_promote_from_amem", "vmem_lint", "vmem_graph_build", "vmem_graph_neighbors", "vmem_promote"] as const;
+
+/** Tool definitions for a fixed vault set: `vault` is an enum of the registered ids. */
+export function vaultTools(ids: readonly string[], orgIds: readonly string[] = []): McpTool[] {
+  const vault = ids.length ? { type: "string", enum: [...ids] } : string(32);
+  const twoStep = { confirm: { type: "boolean" }, fingerprint: sha };
+  const orgVault = orgIds.length ? { type: "string", enum: [...orgIds] } : string(32);
+  return [
+    tool("vmem_status", "Registered vaults with health, write policy and effective pii.", object({})),
+    tool("vmem_search", "Full-text (BM25) search over indexed notes. Literal AND terms.", object({ query: string(1000), vault, limit: integer(1, 50), type: string(64), domain: string(64) }, ["query"])),
+    tool("vmem_read", "Read one note by stem, alias or notes/ path: frontmatter, body, sha256. Bounded by maxBytes; section selects an exact H2, offset pages UTF-8 byte ranges, and truncated reads list H2 headings/nextOffset.", object({ path: note, vault, maxBytes: integer(1, 65536), section: string(1024), offset: integer(0, MAX_NOTE_BYTES) }, ["path"])),
+    tool("vmem_read_many", "Read up to 20 notes (8 KiB each).", object({ paths: { type: "array", minItems: 1, maxItems: 20, items: note }, vault }, ["paths"])),
+    tool("vmem_list", "List indexed notes under notes/, optionally by stem prefix.", object({ vault, prefix: string(256, 0), limit: integer(1, 500) })),
+    tool("vmem_links", "Outgoing links (with resolution) and/or incoming backlinks of a note.", object({ path: note, vault, direction: { type: "string", enum: ["out", "in", "both"] }, limit: integer(1, 200) }, ["path"])),
+    tool("vmem_mocs", "MOC notes with incoming link counts.", object({ vault })),
+    tool("vmem_check", "Validate a prospective note text without writing.", object({ vault, path: string(200), text: string(262144, 0) }, ["text"])),
+    tool("vmem_log_tail", "Read the newest vault log lines, optionally filtered.", object({ vault, n: integer(1, 200), type: { type: "string", enum: LOG_TYPES }, grep: string(256) })),
+    tool("vmem_create", "Create a validated note. Requires a vault with write=mcp.", object({ vault, stem: string(200), type: string(64), domain: string(64), topics: { type: "array", maxItems: 32, items: string(200) }, description: string(1000), title: string(300), body: string(65536, 0), source: { type: ["string", "array"], minLength: 1, maxLength: 512, minItems: 1, maxItems: 32, items: string(512) }, confidence: string(32), status: string(32), extra: { type: "object", maxProperties: 32, additionalProperties: scalar }, log: logEvent }, ["stem", "type", "domain", "description"]), "write"),
+    tool("vmem_patch", "Replace one exact string in a note.", object({ vault, path: note, oldString: string(8192), newString: string(8192, 0), expectedSha: sha }, ["path", "oldString", "newString"]), "write"),
+    tool("vmem_append", "Append markdown to a section of a note.", object({ vault, path: note, section: string(120), markdown: string(16384), expectedSha: sha }, ["path", "section", "markdown"]), "write"),
+    tool("vmem_set_frontmatter", "Set or unset frontmatter keys of a note.", object({ vault, path: note, set: { type: "object", maxProperties: 32, additionalProperties: scalar }, unset: { type: "array", maxItems: 32, items: string(64) }, expectedSha: sha }, ["path"]), "write"),
+    tool("vmem_link", "Add a typed relation link between two notes (bidirectional by default).", object({ vault, from: note, to: note, relation: { type: "string", enum: RELATIONS }, context: string(500), bidirectional: { type: "boolean" }, log: logEvent }, ["from", "to", "relation"]), "write"),
+    tool("vmem_supersede", "Mark a note superseded by another.", object({ vault, old: note, next: note, log: logEvent }, ["old", "next"]), "write"),
+    tool("vmem_log_append", "Append one validated event line to the vault log.", object({ vault, type: { type: "string", enum: LOG_TYPES }, project: string(64), source: string(512), dest: string(512), note: string(500) }, ["type", "project", "source", "note"]), "write"),
+    tool("vmem_move", "Two-step rename with link rewrites: without confirm returns preview and fingerprint; then confirm=true with that fingerprint.", object({ vault, from: note, to: note, ...twoStep }, ["from", "to"]), "confirm"),
+    tool("vmem_delete", "Two-step delete: without confirm returns preview (or refusal), backlinks and fingerprint; then confirm=true with that fingerprint.", object({ vault, path: note, ...twoStep }, ["path"]), "confirm"),
+    tool("vmem_promote_from_amem", "Two-step promotion of one durable agent-mem entry (id from amem_vault_candidates) into a vault note: without confirm returns the full note text, possible duplicates and fingerprint; confirm=true with that fingerprint creates the note, logs LEARN and records the agent-mem vault link. linkTo links an existing note instead.",
+      object({ vault, id: { type: "string", minLength: 32, maxLength: 36 }, stem: string(120), type: string(64), domain: string(64), topics: { type: "array", maxItems: 32, items: string(200) }, description: string(1000), title: string(300), body: string(65536, 0), linkTo: note, project: string(400), ...twoStep }, ["id"]), "confirm"),
+    tool("vmem_lint", "Lint a private derived snapshot; write=true writes a screened report.", object({ vault, write: { type: "boolean" }, dryRun: { type: "boolean" } }), "write"),
+    tool("vmem_graph_build", "Build a deterministic graph and screened reports; dryRun changes nothing.", object({ vault, dryRun: { type: "boolean" } }), "write"),
+    tool("vmem_graph_neighbors", "Read a bounded graph neighborhood.", object({ vault, path: note, hops: integer(1,2), limit: integer(1,500) }, ["path"])),
+    tool("vmem_promote", "Two-step promotion of a personal note into a local org vault clone (never pushes): without confirm returns the full transformed text, dropped links, screen result and fingerprint; confirm=true with that fingerprint writes the org note, source provenance and SYNC log lines. Publishing is the separate `vmem sync` CLI.",
+      object({ path: note, to: orgVault, topics: { type: "array", maxItems: 32, items: string(200) }, again: { type: "boolean" }, ...twoStep }, ["path", "to"]), "confirm"),
+  ];
+}
+type Issue = { code: string; severity: "error"; message: string };
+const refusal = (code: string, message: string) => ({ refused: true as const, issues: [{ code, severity: "error", message } as Issue] });
+const str = (value: unknown): string | undefined => typeof value === "string" ? value : undefined;
+
+/**
+ * Handlers over the shared providers (VaultIndex, applyWrite, appendLog/readLog). The vault set and
+ * the default (first personal) are fixed when the server starts; later registry changes need a restart.
+ */
+export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.env): { tools: McpTool[]; handlers: Record<string, McpHandler>; vaults: VaultSpec[]; defaultVault: string | undefined } {
+  const vaults = loadRegistry(home).vaults, ids = vaults.map(v => v.id);
+  const defaultVault = (vaults.find(v => v.kind === "personal") ?? vaults[0])?.id;
+  const pick = (args: Record<string, unknown>): VaultSpec => {
+    const id = str(args.vault) ?? defaultVault;
+    const spec = vaults.find(v => v.id === id);
+    if (!spec) throw Object.assign(new Error(ids.length ? "unknown vault id" : "no vaults registered"), { code: "V04" });
+    return spec;
+  };
+  const read = <T>(args: Record<string, unknown>, body: (index: VaultIndex) => T): T => {
+    const spec = pick(args), index = new VaultIndex(home, spec, vaults.map(v => v.path));
+    try { index.scan(); return body(index); } finally { index.close(); }
+  };
+  const write = (args: Record<string, unknown>, operation: WriteOp, extra: Partial<WriteRequest> = {}): WriteReceipt | ReturnType<typeof refusal> & Partial<WriteReceipt> => {
+    const request: WriteRequest = { vault: pick(args).id, operation, channel: "mcp", ...extra, ...(args.log ? { log: args.log as LogEvent } : {}) };
+    const receipt = applyWrite(home, request, { env });
+    return receipt.ok ? receipt : { ...receipt, refused: true };
+  };
+  const twoStep = (args: Record<string, unknown>) => ({ confirm: args.confirm === true, ...(str(args.fingerprint) ? { fingerprint: str(args.fingerprint) } : {}) });
+  const document = (result: ReturnType<VaultIndex["show"]>) => {
+    const { path, content, hash, truncated, ...metadata } = result;
+    if (truncated || result.section !== undefined || result.offset !== undefined) return { path, sha256: hash, truncated, frontmatter: null, body: content, ...metadata };
+    const parsed = parseFrontmatter(content);
+    return { path, sha256: hash, truncated, frontmatter: parsed.data, body: parsed.body };
+  };
+  const handlers: Record<string, McpHandler> = {
+    vmem_promote: async args => {
+      const { promoteToOrg } = await import("./org-promote.ts");
+      const source = vaults.find(v => v.id === defaultVault && v.kind === "personal");
+      if (!source) return refusal("POLICY", "no personal vault registered");
+      const result = promoteToOrg(home, { from: source.id, note: str(args.path)!, to: str(args.to)!, channel: "mcp", again: args.again === true, confirm: args.confirm === true,
+        ...(Array.isArray(args.topics) ? { topics: args.topics as string[] } : {}), ...(str(args.fingerprint) ? { fingerprint: str(args.fingerprint) } : {}) }, { env });
+      return result.ok ? result : { ...result, refused: true };
+    },
+    vmem_promote_from_amem: async args => {
+      const { promoteFromAmem } = await import("./promote.ts");
+      const id = str(args.id)!.replace(/^mem:/, "");
+      const result = await promoteFromAmem(home, { vault: pick(args).id, id, channel: "mcp", confirm: args.confirm === true,
+        ...Object.fromEntries(["stem", "type", "domain", "description", "title", "body", "linkTo", "fingerprint"].filter(key => str(args[key]) !== undefined).map(key => [key, str(args[key])])),
+        ...(Array.isArray(args.topics) ? { topics: args.topics as string[] } : {}) }, { env, ...(str(args.project) ? { project: str(args.project) } : {}) });
+      return result.ok ? result : { ...result, refused: true };
+    },
+    vmem_lint: args => args.write === true ? writeAnalysisReports(home,{vault:pick(args).id,kind:"lint",channel:"mcp",expectedVault:pick(args),dryRun:args.dryRun === true},env) : lintVault(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot),
+    vmem_graph_build: args => writeAnalysisReports(home,{vault:pick(args).id,kind:"graph",channel:"mcp",expectedVault:pick(args),dryRun:args.dryRun === true},env),
+    vmem_graph_neighbors: args => graphNeighbors(buildGraph(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot),str(args.path)!, (args.hops as 1|2|undefined) ?? 1, (args.limit as number|undefined) ?? 50),
+    vmem_status: () => ({ defaultVault: defaultVault ?? null, vaults: registryStatus(home).filter(v => ids.includes(v.id)) }),
+    vmem_search: args => read(args, index => ({ hits: index.search(str(args.query)!, { limit: (args.limit as number | undefined) ?? 20, type: str(args.type), domain: str(args.domain) }) })),
+    vmem_read: args => read(args, index => { const r = index.show(str(args.path)!, (args.maxBytes as number | undefined) ?? 16384, str(args.section), args.offset as number | undefined); return document(r); }),
+    vmem_read_many: args => read(args, index => ({ notes: (args.paths as string[]).map(path => {
+      try { const r = index.show(path, 8192); return document(r); }
+      catch (error) { return { path, ...refusal("V04", error instanceof Error ? error.message : "unreadable") }; }
+    }) })),
+    vmem_list: args => read(args, index => ({ notes: index.list(str(args.prefix) ?? "", (args.limit as number | undefined) ?? 100) })),
+    vmem_links: args => read(args, index => {
+      const direction = str(args.direction) ?? "both", limit = (args.limit as number | undefined) ?? 50;
+      const out = direction === "in" ? [] : index.links(str(args.path)!, limit);
+      return { out: out.filter(l => l.resolved), dead: out.filter(l => !l.resolved), in: direction === "out" ? [] : index.backlinks(str(args.path)!, limit) };
+    }),
+    vmem_mocs: args => read(args, index => ({ mocs: index.mocs() })),
+    vmem_check: args => write(args, { op: "check", path: notePath(str(args.path) ?? "checked-note"), text: str(args.text)! }),
+    vmem_log_tail: args => readLog(home, { vault: pick(args).id, limit: (args.n as number | undefined) ?? 50, ...(str(args.type) ? { type: str(args.type) } : {}), ...(str(args.grep) ? { grep: str(args.grep) } : {}) }),
+    vmem_create: args => {
+      const frontmatter: Record<string, unknown> = { ...(args.extra as Record<string, unknown> | undefined ?? {}) };
+      for (const key of ["type", "domain", "description", "title", "source", "confidence", "status"]) if (str(args[key]) !== undefined) frontmatter[key] = args[key];
+      if (Array.isArray(args.source)) frontmatter.source = args.source as string[];
+      if (Array.isArray(args.topics)) frontmatter.topics = (args.topics as string[]).map(v => v.startsWith("[[") ? v : `[[${v}]]`);
+      return write(args, { op: "create", path: str(args.stem)!, frontmatter, ...(str(args.body) !== undefined ? { body: str(args.body) } : {}) });
+    },
+    vmem_patch: args => write(args, { op: "patch", path: str(args.path)!, oldString: str(args.oldString)!, newString: str(args.newString)!, expectedSha: str(args.expectedSha) }),
+    vmem_append: args => write(args, { op: "append", path: str(args.path)!, section: str(args.section)!, markdown: str(args.markdown)!, expectedSha: str(args.expectedSha) }),
+    vmem_set_frontmatter: args => write(args, { op: "frontmatter", path: str(args.path)!, set: (args.set as Record<string, unknown> | undefined) ?? {}, ...(args.unset ? { unset: args.unset as string[] } : {}), expectedSha: str(args.expectedSha) }),
+    vmem_link: args => write(args, { op: "link", from: str(args.from)!, to: str(args.to)!, relation: args.relation as Extract<WriteOp, { op: "link" }>["relation"], ...(str(args.context) ? { context: str(args.context) } : {}), bidirectional: args.bidirectional !== false }),
+    vmem_supersede: args => write(args, { op: "supersede", old: str(args.old)!, next: str(args.next)! }),
+    vmem_log_append: args => {
+      const event: LogEvent = { type: str(args.type)!, project: str(args.project)!, source: str(args.source)!, note: str(args.note)!, ...(str(args.dest) ? { dest: str(args.dest) } : {}) };
+      const receipt = appendLog(home, { vault: pick(args).id, event, channel: "mcp" }, { env });
+      return receipt.ok ? receipt : { ...receipt, refused: true };
+    },
+    vmem_move: args => write(args, { op: "move", from: str(args.from)!, to: str(args.to)! }, twoStep(args)),
+    vmem_delete: args => {
+      const receipt = write(args, { op: "delete", path: str(args.path)! }, twoStep(args));
+      if (args.confirm === true) return receipt;
+      let backlinks: { source: string; line: number }[] = [];
+      try { backlinks = read(args, index => index.backlinks(str(args.path)!, 200).map(l => ({ source: l.source, line: l.line }))); } catch { /* preview stays valid without backlinks */ }
+      return { ...receipt, backlinks };
+    },
+  };
+  // Every handler returns a structured value; provider errors become refusals, never protocol errors.
+  const guarded: Record<string, McpHandler> = {};
+  for (const [name, handler] of Object.entries(handlers)) guarded[name] = async args => {
+    try { return await handler(args); }
+    catch (error) { return refusal((error as { code?: unknown }).code === "V04" ? "V04" : "REFUSED", error instanceof Error ? error.message.slice(0, 500) : "operation refused"); }
+  };
+  return { tools: vaultTools(ids, vaults.filter(v => v.kind === "org").map(v => v.id)), handlers: guarded, vaults, defaultVault };
+}

package/src/mcp.ts

@@ -0,0 +1,110 @@
+import { once } from "node:events";
+import type { Readable, Writable } from "node:stream";
+
+/** Newline-delimited JSON-RPC stdio transport (MCP basic + tools). Sequential, bounded, no timers. */
+export const FRAME_BYTES = 65_536, RESULT_BYTES = 262_144;
+export interface McpTool { name: string; description: string; inputSchema: Record<string, unknown>; annotations: Record<string, boolean> }
+export type McpHandler = (args: Record<string, unknown>) => unknown | Promise<unknown>;
+export interface McpServerOptions { tools: readonly McpTool[]; handlers: Record<string, McpHandler>; input?: Readable; output?: Writable; name?: string; version?: string }
+const protocols = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const plain = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+
+/** Runtime validation for the small schema vocabulary the tools use. Unknown keywords never widen acceptance. */
+export function validArguments(value: unknown, raw: unknown): boolean {
+  const s = raw as Record<string, any>, type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+  const types: unknown[] = Array.isArray(s.type) ? s.type : [s.type];
+  if (!types.includes(type) && !(type === "number" && Number.isSafeInteger(value) && types.includes("integer"))) return false;
+  if (type === "number" && !types.includes("number") && !Number.isSafeInteger(value)) return false;
+  if (s.enum && !s.enum.includes(value)) return false;
+  if (typeof value === "string" && (value.length < (s.minLength ?? 0) || value.length > (s.maxLength ?? FRAME_BYTES) || value.includes("\0"))) return false;
+  if (typeof value === "number" && (!Number.isFinite(value) || value < (s.minimum ?? -Infinity) || value > (s.maximum ?? Infinity))) return false;
+  if (Array.isArray(value)) {
+    if (value.length < (s.minItems ?? 0) || value.length > (s.maxItems ?? 64) || !plain(s.items)) return false;
+    return value.every(item => validArguments(item, s.items));
+  }
+  if (plain(value)) {
+    const keys = Object.keys(value);
+    if (keys.length < (s.minProperties ?? 0) || keys.length > (s.maxProperties ?? 64)) return false;
+    if ((s.required ?? []).some((key: string) => !Object.hasOwn(value, key))) return false;
+    for (const key of keys) {
+      if (["__proto__", "prototype", "constructor"].includes(key) || key.length > 200) return false;
+      if (Object.hasOwn(s.properties ?? {}, key)) { if (!validArguments(value[key], s.properties[key])) return false; }
+      else if (s.additionalProperties === false || !plain(s.additionalProperties) || !validArguments(value[key], s.additionalProperties)) return false;
+    }
+  } else if (type === "object") return false;
+  return true;
+}
+
+/** Serve until input ends. stdout carries protocol messages only; nothing else is written to `output`. */
+export async function serveMcp(options: McpServerOptions): Promise<void> {
+  const input = options.input ?? process.stdin, output = options.output ?? process.stdout;
+  let phase: "new" | "initializing" | "ready" = "new";
+  const send = async (response: unknown) => { if (!output.write(JSON.stringify(response) + "\n")) await once(output, "drain"); };
+  const error = (id: unknown, code: number, message: string) => send({ jsonrpc: "2.0", id, error: { code, message } });
+  const handle = async (line: string) => {
+    let msg: unknown;
+    try { msg = JSON.parse(line); } catch { await error(null, -32700, "Parse error"); return; }
+    if (!plain(msg) || msg.jsonrpc !== "2.0" || typeof msg.method !== "string") { await error(null, -32600, "Invalid request"); return; }
+    if (!Object.hasOwn(msg, "id")) {
+      if (msg.method === "notifications/initialized" && phase === "initializing") phase = "ready";
+      return; // Notifications never invoke a handler.
+    }
+    const id = msg.id;
+    if (!(typeof id === "string" && id.length <= 200 || typeof id === "number" && Number.isSafeInteger(id))) { await error(null, -32600, "Invalid request id"); return; }
+    if (msg.method === "ping") { await send({ jsonrpc: "2.0", id, result: {} }); return; }
+    if (msg.method === "initialize") {
+      if (phase !== "new" || !plain(msg.params) || typeof msg.params.protocolVersion !== "string" || !plain(msg.params.capabilities) || !plain(msg.params.clientInfo)) { await error(id, -32602, "Invalid initialization"); return; }
+      phase = "initializing";
+      await send({ jsonrpc: "2.0", id, result: { protocolVersion: protocols.includes(msg.params.protocolVersion) ? msg.params.protocolVersion : protocols[0],
+        capabilities: { tools: { listChanged: false } }, serverInfo: { name: options.name ?? "vmem", version: options.version ?? "unreleased" } } });
+      return;
+    }
+    if (phase !== "ready") { await error(id, -32002, "Initialize the session first"); return; }
+    if (msg.method === "tools/list") {
+      const params = msg.params;
+      if (params !== undefined && params !== null && (!plain(params) || Object.keys(params).some(key => key !== "cursor" && key !== "_meta") || params.cursor !== undefined && params.cursor !== null)) { await error(id, -32602, "Invalid tool listing arguments"); return; }
+      await send({ jsonrpc: "2.0", id, result: { tools: options.tools } }); return;
+    }
+    if (msg.method !== "tools/call") { await error(id, -32601, "Method not found"); return; }
+    const params = msg.params;
+    if (!plain(params) || Object.keys(params).some(k => !["name", "arguments", "_meta"].includes(k)) || typeof params.name !== "string") { await error(id, -32602, "Invalid tool call"); return; }
+    const definition = options.tools.find(t => t.name === params.name), args = params.arguments ?? {};
+    const handler = definition && options.handlers[definition.name];
+    if (!definition || !handler || !validArguments(args, definition.inputSchema)) { await error(id, -32602, "Invalid tool name or arguments"); return; }
+    let result: unknown;
+    try {
+      const text = JSON.stringify(await handler(args as Record<string, unknown>));
+      if (text === undefined) throw new Error("tool returned no result");
+      result = Buffer.byteLength(text) > RESULT_BYTES
+        ? { isError: true, content: [{ type: "text", text: JSON.stringify({ refused: true, issues: [{ code: "LIMIT", severity: "error", message: "result exceeds 256 KiB; narrow the request" }] }) }] }
+        : { content: [{ type: "text", text }] };
+    } catch (failure) {
+      // Handlers return structured refusals; anything thrown is reported without stack or content.
+      const message = failure instanceof Error ? failure.message.slice(0, 500) : "operation failed";
+      result = { isError: true, content: [{ type: "text", text: JSON.stringify({ refused: true, issues: [{ code: "ERROR", severity: "error", message }] }) }] };
+    }
+    await send({ jsonrpc: "2.0", id, result });
+  };
+  let pending = "", overflow = false;
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const consume = async (chunk: string) => {
+    let start = 0;
+    for (;;) {
+      const newline = chunk.indexOf("\n", start), part = chunk.slice(start, newline < 0 ? undefined : newline);
+      if (!overflow) {
+        if (Buffer.byteLength(pending) + Buffer.byteLength(part) > FRAME_BYTES) { overflow = true; pending = ""; }
+        else pending += part;
+      }
+      if (newline < 0) return;
+      if (overflow) await error(null, -32600, "Request exceeds the 64 KiB frame bound");
+      else if (pending.trim()) await handle(pending);
+      pending = ""; overflow = false; start = newline + 1;
+    }
+  };
+  try {
+    for await (const chunk of input) await consume(typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true }));
+  } catch { await error(null, -32700, "Invalid UTF-8 input"); return; }
+  await consume(decoder.decode());
+  // A truncated frame at EOF is never executed.
+  if (pending.trim() || overflow) await error(null, -32700, "Incomplete request at EOF");
+}

package/src/org-commands.ts

@@ -0,0 +1,31 @@
+import { promoteToOrg } from "./org-promote.ts";
+import { syncVault } from "./sync.ts";
+
+function parse(command: string, args: string[], values: string[], booleans: string[]) {
+  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 ${arg}`);
+    if (booleans.includes(arg)) { flags[arg] = true; continue; }
+    const value = args[++i];
+    if (value === undefined || value.startsWith("--")) throw new Error(`${arg}: value required`);
+    flags[arg] = value;
+  }
+  return { flags, positional, value: (name: string) => typeof flags[name] === "string" ? flags[name] as string : undefined };
+}
+/** `vmem promote <vault> <note> --to <org>` and `vmem sync <vault>`: both preview unless `--confirm --fingerprint`. */
+export function runOrgCommand(command: string, args: string[], home: string, env: NodeJS.ProcessEnv): { text: string; code: number } {
+  if (command === "promote") {
+    const { flags, positional, value } = parse(command, args, ["--to", "--topics", "--fingerprint", "--log-project"], ["--again", "--confirm", "--json"]);
+    if (positional.length !== 2 || !value("--to")) throw new Error("promote: requires personal vault id, note and --to <org vault>");
+    const result = promoteToOrg(home, { from: positional[0]!, note: positional[1]!, to: value("--to")!, again: flags["--again"] === true, confirm: flags["--confirm"] === true,
+      ...(value("--topics") ? { topics: value("--topics")!.split(",").map(t => t.trim()).filter(Boolean) } : {}),
+      ...(value("--fingerprint") ? { fingerprint: value("--fingerprint") } : {}), ...(value("--log-project") ? { logProject: value("--log-project") } : {}), channel: "cli" }, { env });
+    return { text: JSON.stringify(result, null, flags["--json"] ? undefined : 2), code: result.ok ? 0 : 1 };
+  }
+  const { flags, positional, value } = parse(command, args, ["--fingerprint", "--message"], ["--confirm", "--json"]);
+  if (positional.length !== 1) throw new Error("sync: requires vault id");
+  const result = syncVault(home, { vault: positional[0]!, confirm: flags["--confirm"] === true, ...(value("--fingerprint") ? { fingerprint: value("--fingerprint") } : {}), ...(value("--message") ? { message: value("--message") } : {}) }, { env });
+  return { text: JSON.stringify(result, null, flags["--json"] ? undefined : 2), code: result.ok ? 0 : 1 };
+}

package/src/org-promote.ts

@@ -0,0 +1,259 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, openSync, readSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import type { VaultSpec, VmemConfig } from "./config.ts";
+import { emitFrontmatter, parseFrontmatter } from "./frontmatter.ts";
+import { normalizeTarget, proseLines } from "./links.ts";
+import { loadRegistry } from "./registry.ts";
+import { VaultIndex } from "./vault-index.ts";
+import { applyWrite } from "./writer.ts";
+import { notePath } from "./write-operations.ts";
+import { screenContent } from "./write-validation.ts";
+import { appendLog } from "./vault-log.ts";
+import type { WriteIssue, WriteReceipt } from "./write-types.ts";
+import type { LogReceipt } from "./log-types.ts";
+import { analysisInput } from "./analysis-input.ts";
+import { lintVault } from "./vault-lint.ts";
+import type { AnalysisSnapshot } from "./analysis-types.ts";
+
+export interface OrgPromoteRequest {
+  /** Personal vault id and note (stem, alias or notes/ path). */
+  from: string;
+  note: string;
+  /** Target org vault id. */
+  to: string;
+  /** Override target topics; each must be an existing MOC in the target. */
+  topics?: string[];
+  again?: boolean;
+  confirm?: boolean;
+  fingerprint?: string;
+  channel?: "cli" | "mcp";
+  logProject?: string;
+}
+export interface OrgPromoteResult {
+  ok: boolean;
+  applied: boolean;
+  preview?: boolean;
+  source: string | null;
+  target: string | null;
+  text?: string;
+  droppedLinks?: string[];
+  screen: { passed: boolean; issues: WriteIssue[] };
+  fingerprint?: string;
+  issues: WriteIssue[];
+  note?: WriteReceipt;
+  provenance?: WriteReceipt;
+  logs?: { source: LogReceipt | null; target: LogReceipt | null };
+  lint?: { passed: boolean; issues: WriteIssue[]; summary?: string };
+  /** Set when the org note already exists from this source and only the source provenance is missing. */
+  recovery?: "provenance-only";
+}
+const issue = (code: string, message: string, path?: string): WriteIssue => ({ code, severity: "error", message, ...(path ? { path } : {}) });
+const sha = (value: unknown) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const strings = (value: unknown): string[] => typeof value === "string" ? [value] : Array.isArray(value) ? value.filter((v): v is string => typeof v === "string") : [];
+
+// ponytail: keyword heuristics from hub-contract §2 never_upload; the org clone's git diff before `vmem sync` is the review surface.
+const CORRESPONDENCE = [/^inbox\//i, /(^|[\s/])inbox\//i, /^outlook:/i, /telegram\(/i, /kakao/i];
+const MEETING = [/(^|\/)meetings\//i];
+/**
+ * Fail-closed org screen over the transformed text and source frontmatter: secrets, PII under the
+ * target's policy (org default deny), person/people records, private correspondence and internal
+ * meeting sources. Returns error issues only; any issue refuses promotion.
+ */
+export function screenForOrg(text: string, data: Record<string, unknown>, target: VaultSpec, config: VmemConfig): WriteIssue[] {
+  const issues: WriteIssue[] = screenContent(text, target, config).map(found => ({ ...found, severity: "error" as const }));
+  if (data.type === "person" || data.domain === "people") issues.push(issue("SCREEN", "personal_data: person or people records are never promoted"));
+  const sources = [...strings(data.source), ...strings(data.source_ref)];
+  if (sources.some(value => MEETING.some(pattern => pattern.test(value)))) issues.push(issue("SCREEN", "internal_meeting_notes: source under meetings/"));
+  if (sources.some(value => CORRESPONDENCE.some(pattern => pattern.test(value)))) issues.push(issue("SCREEN", "private_correspondence: inbox, mail or chat source"));
+  return issues;
+}
+
+/** Categories that make a linked source-vault note unpublishable; its name must not reach the org vault either. */
+export function sensitiveCategory(data: Record<string, unknown>): string | undefined {
+  if (data.type === "person" || data.domain === "people") return "personal_data";
+  const sources = [...strings(data.source), ...strings(data.source_ref)];
+  if (sources.some(value => MEETING.some(pattern => pattern.test(value)))) return "internal_meeting_notes";
+  if (sources.some(value => CORRESPONDENCE.some(pattern => pattern.test(value)))) return "private_correspondence";
+  return undefined;
+}
+/** Dropped links resolved in the source vault: any that point at a sensitive note refuse the promotion. */
+function screenDroppedLinks(home: string, source: VaultSpec, all: VaultSpec[], dropped: string[]): WriteIssue[] {
+  if (!dropped.length) return [];
+  const index = new VaultIndex(home, source, all.map(v => v.path)), found = new Map<string, number>();
+  try {
+    index.scan();
+    for (const link of dropped) {
+      let category: string | undefined;
+      try {
+        const note = index.show(link, 65536);
+        category = note.truncated ? "unreadable_link_target" : sensitiveCategory(parseFrontmatter(note.content).data);
+      } catch { category = undefined; } // unresolved in the source too: plain text only
+      if (category) found.set(category, (found.get(category) ?? 0) + 1);
+    }
+  } finally { index.close(); }
+  // Counts and categories only: the linked names are exactly what must not be echoed.
+  return [...found].map(([category, count]) => issue("SCREEN", `${category}: ${count} body link${count === 1 ? "" : "s"} point at notes that are never promoted; remove those links from the source note first`));
+}
+/** Replace the last prose `## Topics` section (never one inside a fence) with the given topics; append one if absent. */
+export function replaceTopicsSection(body: string, topics: string[]): string {
+  const prose = proseLines(body), raw = body.split("\n");
+  let start = -1;
+  for (let i = prose.length - 1; i >= 0; i--) if (/^ {0,3}##[ \t]+Topics[ \t]*#*[ \t]*$/.test(prose[i]!)) { start = i; break; }
+  const section = ["## Topics", "", ...topics.map(topic => `- ${topic}`), ""];
+  if (start < 0) return `${body.replace(/\n*$/, "")}\n\n${section.join("\n")}`;
+  // The section ends at the next prose heading of level 1 or 2.
+  let end = raw.length;
+  for (let i = start + 1; i < prose.length; i++) if (/^ {0,3}#{1,2}[ \t]/.test(prose[i]!)) { end = i; break; }
+  const tail = raw.slice(end);
+  return [...raw.slice(0, start), ...section, ...(tail.length ? tail : [])].join("\n").replace(/\n*$/, "\n");
+}
+/** Replace visible wiki links whose target does not resolve in the target vault with their plain text. */
+export function dropUnresolvedLinks(body: string, resolves: (target: string) => boolean): { body: string; dropped: string[] } {
+  const prose = proseLines(body), raw = body.split("\n"), dropped: string[] = [];
+  const out = raw.map((line, index) => {
+    const visible = (prose[index] ?? "").replace(/(`+)[^`]*?\1/g, match => " ".repeat(match.length));
+    let result = line;
+    for (const match of [...visible.matchAll(/(!?)\[\[([^\]\n]+)\]\]/g)].reverse()) {
+      if (match.index! > 0 && visible[match.index! - 1] === "\\") continue;
+      const [address, ...labels] = match[2]!.split("|");
+      const hash = address!.indexOf("#"), target = (hash < 0 ? address! : address!.slice(0, hash)).trim();
+      if (!target || resolves(target)) continue;
+      dropped.push(target);
+      const plain = labels.length ? labels.join("|") : address!.replace("#", " ").trim();
+      result = result.slice(0, match.index!) + plain + result.slice(match.index! + match[0].length);
+    }
+    return result;
+  });
+  return { body: out.join("\n"), dropped: [...new Set(dropped)].sort() };
+}
+
+/** Target-vault facts read once from its index: link resolution (path stems only, as Obsidian resolves), MOCs and existing paths. */
+function targetFacts(home: string, spec: VaultSpec, all: VaultSpec[], links: string[], targetPath: string): { resolved: Set<string>; mocs: Set<string>; exists: boolean } {
+  const index = new VaultIndex(home, spec, all.map(v => v.path));
+  try {
+    index.scan();
+    const targets = index.linkTargets(), resolved = new Set([...new Set(links)].map(linkKey).filter(key => targets.has(key)));
+    // Path existence is checked without alias lookup, so another note's alias cannot hide the target.
+    return { resolved, mocs: new Set(index.mocs(500).map(moc => linkKey(moc.path))), exists: targets.has(linkKey(targetPath)) };
+  } finally { index.close(); }
+}
+function readSource(spec: VaultSpec, path: string): string {
+  const file = join(realpathSync(spec.path), path);
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const size = fstatSync(fd).size;
+    if (!fstatSync(fd).isFile() || size > 256 * 1024) throw new Error("source note: expected plain file <=256 KiB");
+    const buffer = Buffer.alloc(size); let read = 0;
+    while (read < size) { const n = readSync(fd, buffer, read, size - read, null); if (!n) break; read += n; }
+    return buffer.subarray(0, read).toString("utf8");
+  } finally { closeSync(fd); }
+}
+const linkKey = (value: string) => normalizeTarget(value.replace(/^\[\[|\]\]$/g, "").split(/[|#]/)[0]!.trim().replace(/^notes\//i, "").replace(/\.md$/i, ""));
+
+/**
+ * The single org-lint call site: the promoted text is overlaid on the org vault's analysis snapshot and
+ * `lintVault` is scoped to that note. It passes when the note has no lint errors (L01/L02/L13); vault-wide
+ * warnings are reported separately and do not fail the promotion.
+ */
+export function lintPromoted(home: string, target: VaultSpec, path: string, text: string): { passed: boolean; issues: WriteIssue[]; summary?: string } {
+  let snapshot: AnalysisSnapshot;
+  try { snapshot = analysisInput(home, target.id).snapshot; }
+  catch (error) { return { passed: false, issues: [issue("LINT", `org lint unavailable: ${error instanceof Error ? error.message.slice(0, 200) : "error"}`)] }; }
+  const relative = path.replace(/^notes\//, "");
+  snapshot = { ...snapshot, notes: [...snapshot.notes.filter(note => note.path !== relative), { path: relative, source: text }] };
+  const report = lintVault(snapshot, path);
+  const errors = (["L01", "L02", "L13"] as const).flatMap(code => report.findings[code].map(finding => issue(code, finding.slice(0, 500), path)));
+  return { passed: errors.length === 0, issues: errors, summary: report.summary };
+}
+
+/**
+ * Two-step personal-to-org promotion. Writes only local clones: never commits or pushes; publishing is `syncVault`.
+ * Preview and refusal write nothing; confirm needs the fingerprint of the current preview.
+ */
+export function promoteToOrg(home: string, request: OrgPromoteRequest, options: { env?: NodeJS.ProcessEnv; now?: Date } = {}): OrgPromoteResult {
+  const result: OrgPromoteResult = { ok: false, applied: false, source: null, target: null, screen: { passed: false, issues: [] }, issues: [] };
+  const fail = (found: WriteIssue) => ({ ...result, issues: [found] });
+  const config = loadRegistry(home), all = config.vaults;
+  const source = all.find(v => v.id === request.from), target = all.find(v => v.id === request.to);
+  if (!source || !target) return fail(issue("V04", "unknown source or target vault id"));
+  if (source.kind !== "personal") return fail(issue("POLICY", "promotion source must be a personal vault"));
+  if (target.kind !== "org" || target.write === "none") return fail(issue("POLICY", "promotion target must be a writable org vault"));
+  if (request.channel === "mcp" && target.write !== "mcp") return fail(issue("POLICY", "target vault write policy refuses MCP"));
+  if (request.channel === "mcp" && source.write !== "mcp") return fail(issue("POLICY", "source provenance write needs write=mcp on the personal vault"));
+  let path: string;
+  const index = new VaultIndex(home, source, all.map(v => v.path));
+  try { index.scan(); path = `notes/${index.show(request.note, 1).path}`; }
+  catch (error) { return fail(issue("V04", error instanceof Error ? error.message : "unknown source note")); }
+  finally { index.close(); }
+  result.source = `${source.id}:${path}`;
+  const original = readSource(source, path);
+  let parsed;
+  try { parsed = parseFrontmatter(original); } catch { return fail(issue("V01", "source frontmatter is not parseable", path)); }
+  const promotedTo = `${target.id}:${path}`;
+  const prior = strings(parsed.data.promoted_to);
+  if (prior.length && !request.again) return fail(issue("AGAIN", `already promoted to ${prior.join(", ")}; pass --again to promote again`, path));
+  const targetPath = notePath(path);
+  // Topics: explicit override, else the source topics; each must be an existing MOC in the target.
+  const topics = (request.topics ?? strings(parsed.data.topics)).map(value => value.startsWith("[[") ? value : `[[${value}]]`);
+  const bodyLinks = [...parsed.body.matchAll(/\[\[([^\]\n|#]+)/g)].map(match => match[1]!.trim());
+  const fieldLinks = ["project", "superseded_by", "supersedes", "source_ref"].flatMap(key => strings(parsed.data[key]).filter(value => value.includes("[[")).map(linkKey));
+  const targetNotes = targetFacts(home, target, all, [...bodyLinks, ...fieldLinks], targetPath);
+  // The org note is never overwritten; a repeat promotion (--again) needs the earlier org copy moved or deleted first.
+  if (targetNotes.exists) {
+    // Recovery: an earlier confirm created this org note but the source provenance write failed.
+    let existing: Record<string, unknown> = {};
+    try { existing = parseFrontmatter(readSource(target, targetPath)).data; } catch { /* unreadable: treated as foreign */ }
+    if (existing.promoted_from !== result.source || prior.includes(promotedTo)) return fail(issue("V08", `${target.id} already has ${targetPath}; move or delete it in the org vault first`, targetPath));
+    const set = { promoted_to: prior.length ? [...prior, promotedTo] : promotedTo };
+    const plan = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env });
+    const fingerprint = sha({ recover: plan.fingerprint, promotedTo });
+    const recovery: OrgPromoteResult = { ...result, target: `${target.id}:${targetPath}`, screen: { passed: true, issues: [] }, fingerprint, recovery: "provenance-only" };
+    if (!plan.ok) return { ...recovery, issues: plan.issues };
+    if (request.confirm !== true) return { ...recovery, ok: true, preview: true };
+    if (request.fingerprint !== fingerprint) return { ...recovery, issues: [issue("V09", "stale or missing preview fingerprint")] };
+    const provenance = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set }, channel: request.channel ?? "cli", log: false }, { env: options.env });
+    return { ...recovery, ok: provenance.ok, applied: provenance.applied, provenance, issues: provenance.ok ? [] : provenance.issues };
+  }
+  const missingTopics = topics.filter(topic => !targetNotes.mocs.has(linkKey(topic)));
+  if (!topics.length || missingTopics.length) return fail(issue("V02", `target topics must name existing MOCs in ${target.id}${missingTopics.length ? `: missing ${missingTopics.join(", ")}` : ""}; use --topics`));
+  const transformed = dropUnresolvedLinks(parsed.body, value => targetNotes.resolved.has(linkKey(value)));
+  // Body Topics section follows the target topics.
+  const body = replaceTopicsSection(transformed.body, topics);
+  const day = (options.now ?? new Date()).toISOString().slice(0, 10);
+  const frontmatter: Record<string, unknown> = { topics, promoted_from: result.source, promoted_at: day, promoted_to: undefined };
+  // Wiki-valued fields that point outside the target vault are dropped as well.
+  for (const key of ["project", "superseded_by", "supersedes", "source_ref"]) {
+    const values = strings(parsed.data[key]);
+    if (values.some(value => value.includes("[[") && !targetNotes.resolved.has(linkKey(value)))) { frontmatter[key] = undefined; transformed.dropped.push(`${key}:${values.join(",")}`); }
+  }
+  const text = emitFrontmatter(parseFrontmatter(parsed.source.slice(0, parsed.source.length - parsed.body.length) + body), frontmatter);
+  result.target = `${target.id}:${targetPath}`; result.text = text; result.droppedLinks = transformed.dropped;
+  const screen = [...screenForOrg(text, parsed.data, target, config), ...screenDroppedLinks(home, source, all, transformed.dropped.filter(link => !link.includes(":")))];
+  result.screen = { passed: screen.length === 0, issues: screen };
+  if (screen.length) return { ...result, issues: screen };
+  const planned = applyWrite(home, { vault: target.id, operation: { op: "create", path: targetPath, frontmatter: {}, body: text }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env });
+  const provenanceSet = { promoted_to: prior.length ? [...prior.filter(p => p !== promotedTo), promotedTo] : promotedTo };
+  const provenanceText = emitFrontmatter(parsed, provenanceSet);
+  const provenancePlan = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set: provenanceSet }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env });
+  result.fingerprint = sha({ target: planned.fingerprint, source: provenancePlan.fingerprint, text, provenanceText });
+  // Org lint runs on the preview too (the note overlaid on the org snapshot), so a note that would fail lint is never written.
+  const previewLint = lintPromoted(home, target, targetPath, text);
+  result.lint = previewLint;
+  const blocking = [...planned.issues, ...provenancePlan.issues, ...previewLint.issues].filter(found => found.severity === "error");
+  if (blocking.length) return { ...result, issues: blocking };
+  if (request.confirm !== true) return { ...result, ok: true, preview: true, issues: [...planned.issues, ...provenancePlan.issues] };
+  if (request.fingerprint !== result.fingerprint) return { ...result, issues: [issue("V09", "stale or missing preview fingerprint")] };
+  const event = { type: "SYNC", project: request.logProject ?? "-", source: `${source.id}:${path}`, dest: `${target.id}:${targetPath}`, note: `promoted: ${typeof parsed.data.type === "string" ? parsed.data.type : "note"}` };
+  const note = applyWrite(home, { vault: target.id, operation: { op: "create", path: targetPath, frontmatter: {}, body: text }, channel: request.channel ?? "cli", log: false }, { env: options.env });
+  if (!note.ok || !note.applied) return { ...result, note, issues: note.issues };
+  const provenance = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set: provenanceSet }, channel: request.channel ?? "cli", log: false }, { env: options.env });
+  const logs = { source: null as LogReceipt | null, target: null as LogReceipt | null };
+  for (const [key, vault] of [["target", target], ["source", source]] as const) {
+    try { logs[key] = appendLog(home, { vault: vault.id, event, channel: request.channel ?? "cli" }, { env: options.env }); }
+    catch { logs[key] = { ok: false, appended: null, synced: false, bytesWritten: null, issues: [issue("LOG_IO", "log append failed")] }; }
+  }
+  const lint = lintPromoted(home, target, targetPath, text);
+  const issues = [...(provenance.ok ? [] : provenance.issues), ...(logs.source?.ok ? [] : logs.source?.issues ?? []), ...(logs.target?.ok ? [] : logs.target?.issues ?? []), ...lint.issues];
+  return { ...result, ok: issues.length === 0, applied: true, note, provenance, logs, lint, issues };
+}

package/src/platform.ts

@@ -0,0 +1 @@
+export { realPath, canonicalPath, isDenied, DENY_SEGMENTS, memoryGitArgv, memoryGitEnv } from "@staix/agent-mem/platform";