@staix/vault-mem 0.5.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +147 -23
  3. package/package.json +5 -4
  4. package/src/amem/seam.ts +15 -6
  5. package/src/analysis-commands.ts +1 -1
  6. package/src/analysis-input.ts +24 -3
  7. package/src/analysis-reports.ts +1 -1
  8. package/src/analysis-types.ts +13 -1
  9. package/src/canon-tables.ts +190 -0
  10. package/src/cli-output.ts +15 -1
  11. package/src/cli.ts +3 -1
  12. package/src/commands-table.ts +7 -2
  13. package/src/config.ts +31 -3
  14. package/src/frontmatter.ts +10 -3
  15. package/src/links.ts +13 -1
  16. package/src/mcp-spec.ts +19 -11
  17. package/src/mcp-vault.ts +20 -12
  18. package/src/mcp.ts +4 -2
  19. package/src/org-promote.ts +29 -12
  20. package/src/promote.ts +25 -13
  21. package/src/read-commands.ts +1 -2
  22. package/src/read-output.ts +7 -5
  23. package/src/registry.ts +1 -0
  24. package/src/skills-mine.ts +5 -4
  25. package/src/spec-command-table.ts +10 -1
  26. package/src/spec-commands.ts +7 -3
  27. package/src/spec-gitlinks.ts +106 -0
  28. package/src/spec-output.ts +30 -0
  29. package/src/spec-source.ts +9 -3
  30. package/src/spec-validate.ts +6 -3
  31. package/src/spec-write.ts +469 -0
  32. package/src/ui/inbox.ts +28 -10
  33. package/src/ui/panel.js +26 -5
  34. package/src/ui/plugin.ts +38 -12
  35. package/src/ui/snapshot-cache.ts +123 -0
  36. package/src/vault-brief.ts +90 -0
  37. package/src/vault-index.ts +158 -21
  38. package/src/vault-lint.ts +53 -5
  39. package/src/vault-log.ts +3 -2
  40. package/src/vault-stats.ts +110 -5
  41. package/src/write-commands.ts +4 -3
  42. package/src/write-files.ts +72 -0
  43. package/src/write-operations.ts +175 -25
  44. package/src/write-output.ts +20 -9
  45. package/src/write-types.ts +8 -1
  46. package/src/write-validation.ts +46 -17
  47. package/src/writer.ts +145 -42
  48. package/src/yaml-quoted.ts +12 -2
package/src/mcp-spec.ts CHANGED
@@ -6,23 +6,27 @@ import { resolveHome } from "./home.ts";
6
6
  import { loadRegistry } from "./registry.ts";
7
7
  import { PLAIN, type TextOptions } from "./text-output.ts";
8
8
  import { renderSpec } from "./spec-output.ts";
9
+ import type { SpecWriteResult } from "./spec-write.ts";
9
10
 
10
- /** Spec tool definitions; every spec tool is read-only. */
11
+ /** Spec definitions retain read annotations for reads; create/update/delete are policy-gated mutations. */
11
12
  export const specTools = (): McpTool[] => SPEC_COMMANDS.map(item => ({ name: item.name, description: item.description, inputSchema: item.inputSchema,
12
- annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } }));
13
+ annotations: { readOnlyHint: !["create", "update", "delete"].includes(item.command), destructiveHint: item.command === "delete", idempotentHint: item.command !== "create" && item.command !== "delete", openWorldHint: false } }));
13
14
 
14
15
  export function createSpecMcp(home: string, env: NodeJS.ProcessEnv = process.env): { tools: McpTool[]; handlers: Record<string, McpHandler> } {
15
16
  const registered = loadRegistry(home).specs ?? [];
16
17
  const tools = specTools();
17
18
  const handlers: Record<string, McpHandler> = {};
18
- for (const item of SPEC_COMMANDS) handlers[item.name] = args => {
19
+ for (const [index, item] of SPEC_COMMANDS.entries()) handlers[item.name] = args => {
19
20
  const invalid = argumentError(args, item.inputSchema);
20
- if (invalid) throw new Error(invalid);
21
+ if (invalid) throw new Error(`${invalid}; see vmem spec ${item.command} --help to correct the arguments`);
21
22
  const selected = registered.find(source => source.id === (args.source ?? registered[0]?.id));
22
23
  if (!selected) throw new Error("spec source: no matching source in the server's startup registry; pass the source argument with a registered id, or register with vmem specs add and restart the MCP server");
23
24
  const current = loadRegistry(home).specs?.find(source => source.id === selected.id);
24
- if (!current || JSON.stringify(current) !== JSON.stringify(selected)) throw new Error("spec source: registry changed since server startup; restart the MCP server before reading");
25
- return executeSpecCommand(home, item.command, { ...args, source: selected.id }, env);
25
+ if (!current || JSON.stringify(current) !== JSON.stringify(selected)) throw new Error("spec source: registry changed since server startup; restart the MCP server before retrying the spec command");
26
+ const result = executeSpecCommand(home, item.command, { ...args, source: selected.id }, env, { channel: "mcp", binding: selected });
27
+ if (tools[index]!.annotations.readOnlyHint !== false) return result;
28
+ const receipt = result as SpecWriteResult;
29
+ return !receipt.ok && !receipt.changed ? { ...receipt, refused: true } : receipt;
26
30
  };
27
31
  return { tools, handlers };
28
32
  }
@@ -33,7 +37,9 @@ export function runSpecCommand(args: string[], env: NodeJS.ProcessEnv = process.
33
37
  if (!item) throw new Error("spec: unknown command; use vmem spec --help");
34
38
  const values: Record<string, unknown> = {}, positional: string[] = [];
35
39
  const properties = item.inputSchema.properties as Record<string, { type: string }>;
36
- const flags = new Map(Object.keys(properties).filter(key => key !== "id" && key !== "query").map(key => ["--" + key.replace(/[A-Z]/g, value => "-" + value.toLowerCase()), key]));
40
+ const takesId = item.command === "get" || item.command === "graph" || item.command === "update" || item.command === "delete";
41
+ const positionalKey = item.command === "create" ? "path" : takesId ? "id" : item.command === "grep" ? "query" : undefined;
42
+ const flags = new Map(Object.keys(properties).filter(key => key !== positionalKey).map(key => ["--" + key.replace(/[A-Z]/g, value => "-" + value.toLowerCase()), key]));
37
43
  const seen = new Set<string>(); let json = false, repo: string | undefined, positionalOnly = false;
38
44
  for (let i = 1; i < args.length; i++) {
39
45
  const flag = args[i]!;
@@ -55,17 +61,19 @@ export function runSpecCommand(args: string[], env: NodeJS.ProcessEnv = process.
55
61
  if (properties[key!]!.type === "integer") {
56
62
  if (!/^[0-9]+$/.test(value)) throw new Error(`${flag}: expected integer; see vmem spec ${item.command} --help for its bounds`);
57
63
  values[key!] = Number(value);
64
+ } else if (properties[key!]!.type === "object" || properties[key!]!.type === "array") {
65
+ try { values[key!] = JSON.parse(value); }
66
+ catch { throw new Error(`${flag}: invalid JSON; supply a JSON ${properties[key!]!.type} as shown by vmem spec ${item.command} --help`); }
58
67
  } else values[key!] = value;
59
68
  }
60
- const takesId = item.command === "get" || item.command === "graph";
61
- if (positional.length > (item.command === "validate" ? 0 : 1) || (takesId && positional.length !== 1)) throw new Error(`spec ${item.command}: unexpected targets; use vmem ${item.usage}`);
62
- if (positional[0] !== undefined) values[takesId ? "id" : "query"] = positional[0];
69
+ if (positional.length > (item.command === "validate" ? 0 : 1) || ((takesId || item.command === "create") && positional.length !== 1)) throw new Error(`spec ${item.command}: unexpected targets; use vmem ${item.usage}`);
70
+ if (positional[0] !== undefined && positionalKey !== undefined) values[positionalKey] = positional[0];
63
71
  const invalid = argumentError(values, item.inputSchema);
64
72
  if (invalid) throw new Error(`${invalid}; see vmem spec ${item.command} --help to correct the arguments`);
65
73
  if (repo !== undefined && (values.source !== undefined || values.worktree !== undefined)) throw new Error("--repo cannot be combined with --source or --worktree; choose registry-free or registered validation");
66
74
  const result = repo !== undefined
67
75
  ? validateSpecRepo(repo, { requireFresh: values.requireFresh as boolean | undefined, limit: values.limit as number | undefined, env }).report
68
76
  : executeSpecCommand(resolveHome(env).home, item.command, values, env);
69
- const code = item.command === "validate" && !(result as { ok: boolean }).ok ? 1 : 0;
77
+ const code = ["validate", "create", "update", "delete"].includes(item.command) && !(result as { ok: boolean }).ok ? 1 : 0;
70
78
  return { text: json ? JSON.stringify(result) : renderSpec(item.command, result, text, { args, values, ...(repo !== undefined ? { repo } : {}) }), code };
71
79
  }
package/src/mcp-vault.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { vaultBrief } from "./vault-brief.ts";
1
2
  import { createSpecMcp } from "./mcp-spec.ts";
2
3
  import { SPEC_COMMANDS } from "./spec-command-table.ts";
3
4
  import { analysisInput } from "./analysis-input.ts";
@@ -32,8 +33,11 @@ const scalar = { type: ["string", "number", "boolean", "null", "array"], maxLeng
32
33
  const metadata = { type: "object", maxProperties: 32, properties: { authors: { type: "array", minItems: 1, maxItems: 100, items: string(1024) } }, additionalProperties: scalar };
33
34
 
34
35
  /** Tool names for the implemented read, write, log, analysis and promotion providers. */
35
- 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",
36
- "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", "vmem_skills_mine", "vmem_read_file", "vmem_list_files", "vmem_report", "vmem_stats", ...SPEC_COMMANDS.map(item => item.name)] as const;
36
+ export const VMEM_TOOL_NAMES = ["vmem_status", "vmem_search", "vmem_brief", "vmem_read", "vmem_read_many", "vmem_list", "vmem_links", "vmem_mocs", "vmem_check", "vmem_log_tail",
37
+ "vmem_create", "vmem_patch", "vmem_append", "vmem_set_frontmatter", "vmem_link", "vmem_supersede", "vmem_log_append", "vmem_move", "vmem_merge", "vmem_delete", "vmem_promote_from_amem", "vmem_lint", "vmem_graph_build", "vmem_graph_neighbors", "vmem_promote", "vmem_skills_mine", "vmem_read_file", "vmem_list_files", "vmem_report", "vmem_stats", ...SPEC_COMMANDS.map(item => item.name)] as const;
38
+
39
+ /** Server `initialize` instructions: purpose, navigation order and the write contract. Pinned by a test, under 400 bytes. */
40
+ export const VMEM_INSTRUCTIONS = "vmem is a vault of durable, linked knowledge: notes with frontmatter, wiki-links and an append-only log. Search first with vmem_search, then read the best match with vmem_read, using section for one H2. Writes are validated and receipted: a refusal lists issues, and a failure after publication can leave changes behind, so read the receipt and its issues before retrying.";
37
41
 
38
42
  /** Tool definitions for a fixed vault set: `vault` is an enum of the registered ids. */
39
43
  export function vaultTools(ids: readonly string[], orgIds: readonly string[] = []): McpTool[] {
@@ -43,10 +47,11 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
43
47
  return [
44
48
  tool("vmem_status", "Registered vaults with health, write policy, effective pii and the piiPolicy matrix (read-only).", object({})),
45
49
  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"])),
50
+ tool("vmem_brief", "Intent-ranked note pointers and one-hop neighbors, with metadata PII/deny screening and whole-line byte cap including the result JSON. No note bodies; read a selected pointer with vmem_read.", object({ vault, intent: string(1024), paths: { type: "array", maxItems: 16, items: string(1024) }, bytes: integer(256, 4096) }, ["intent"])),
46
51
  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"])),
47
52
  tool("vmem_read_many", "Read up to 20 notes (8 KiB each).", object({ paths: { type: "array", minItems: 1, maxItems: 20, items: note }, vault }, ["paths"])),
48
53
  tool("vmem_list", "List indexed notes under notes/ in path order, optionally by stem prefix, with each note's mtime and the filtered total. Pass the returned nextCursor as cursor for the next page.", object({ vault, prefix: string(256, 0), limit: integer(1, 500), cursor: string(1024) })),
49
- 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"])),
54
+ tool("vmem_links", "Outgoing links (with resolution) and/or incoming backlinks of a note. Each dead link carries at most one suggested existing target from the title search, with its score; it is a hint and the link is never rewritten.", object({ path: note, vault, direction: { type: "string", enum: ["out", "in", "both"] }, limit: integer(1, 200) }, ["path"])),
50
55
  tool("vmem_mocs", "MOC notes with incoming link counts.", object({ vault })),
51
56
  tool("vmem_check", "Validate a prospective note text without writing.", object({ vault, path: string(200), text: string(262144, 0) }, ["text"])),
52
57
  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) })),
@@ -58,20 +63,21 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
58
63
  tool("vmem_supersede", "Mark a note superseded by another.", object({ vault, old: note, next: note, log: logEvent }, ["old", "next"]), "write"),
59
64
  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"),
60
65
  tool("vmem_move", "Two-step rename with link rewrites: without confirm returns preview and fingerprint; then confirm=true with that fingerprint (pass log on the confirm call).", object({ vault, from: note, to: note, ...twoStep, log: logEvent }, ["from", "to"]), "confirm"),
66
+ tool("vmem_merge", "Two-step note merge: without confirm returns merged body, source/topic unions, inbound link rewrites and fingerprint without writing. Then confirm=true with that fingerprint writes keep, repoints inbound links and marks absorb superseded under one mutation lock (pass log on the confirm call). Different types, person/moc notes and oversized results refuse.", object({ vault, keep: note, absorb: note, ...twoStep, log: logEvent }, ["keep", "absorb"]), "confirm"),
61
67
  tool("vmem_delete", "Two-step delete: without confirm returns preview (or refusal), backlinks and fingerprint; then confirm=true with that fingerprint (pass log on the confirm call).", object({ vault, path: note, ...twoStep, log: logEvent }, ["path"]), "confirm"),
62
- 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.",
68
+ 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. Configured canonTables add advisory canonical row matches and link-existing choices, outside the fingerprint and never blocking confirm.",
63
69
  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"),
64
70
  tool("vmem_lint", "Lint a private derived snapshot; write=true writes a screened report.", object({ vault, write: { type: "boolean" }, dryRun: { type: "boolean" } }), "write"),
65
71
  tool("vmem_graph_build", "Build a deterministic graph and screened reports; dryRun changes nothing.", object({ vault, dryRun: { type: "boolean" }, workspace: { type: "boolean" } }), "write"),
66
72
  tool("vmem_graph_neighbors", "Read a bounded graph neighborhood.", object({ vault, path: note, hops: integer(1,2), limit: integer(1,500), relation: { type: "string", enum: ["wiki_link", ...LINK_RELATIONS] } }, ["path"])),
67
- 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.",
73
+ 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. Configured target-vault canonTables add advisory canonical row matches and link-existing choices; personal rows are never included and matches do not affect the fingerprint or block confirm. Publishing is the separate `vmem sync` CLI.",
68
74
  object({ path: note, to: orgVault, topics: { type: "array", maxItems: 32, items: string(200) }, again: { type: "boolean" }, ...twoStep }, ["path", "to"]), "confirm"),
69
75
  tool("vmem_skills_mine", "Read-only skill-candidate mining over amem curated entries, amem capture rows and vault notes: dictionary matching, deterministic communities and novelty scoring. Returns counts, masked candidates and a markdown report; writes nothing.",
70
76
  object({ vault, days: integer(1, 3650), project: string(400), allProjects: { type: "boolean" }, vocab: string(4096), skills: { type: "array", maxItems: 16, items: string(4096) }, minSize: integer(1, 10000), minNovelty: { type: "number", minimum: 0, maximum: 1 } })),
71
77
  tool("vmem_read_file", "Read one UTF-8 file outside notes/: ops/, reports/, self/, templates/, AGENTS.md or README.md. Same bounds and paging as vmem_read (maxBytes, offset, nextOffset); notes/ use vmem_read, the log vmem_log_tail. Never locks or writes.", object({ vault, path: string(1024), maxBytes: integer(1, 65536), offset: integer(0, MAX_NOTE_BYTES) }, ["path"])),
72
78
  tool("vmem_list_files", "List one directory level under ops/, reports/, self/ or templates/ (up to 500 entries; dot, linked and denied entries omitted). Never locks or writes.", object({ vault, dir: string(1024) }, ["dir"])),
73
79
  tool("vmem_report", "Write a screened report file under reports/ or ops/ (the MCP form of `vmem report`): same path rules, screening, write policy (write=mcp), receipt and EXTRACT log event; log overrides it, for example a LINT or GRAPH event. dryRun changes nothing.", object({ vault, path: string(200), body: string(65536, 0), dryRun: { type: "boolean" }, log: logEvent }, ["path", "body"]), "write"),
74
- tool("vmem_stats", "Read-only vault statistics: note counts by type, domain and status, notes modified in the last 7 and 30 days, and log event counts by type over the last `days` (default 30). Writes no vault file or log and takes no vault or log lock.", object({ vault, days: integer(1, STATS_MAX_DAYS) })),
80
+ tool("vmem_stats", "Read-only vault statistics: note counts by type, domain and status, note bytes and words in total and by type and domain, and the note-to-source byte ratio (median, p90 and the largest notes) over the workspace files the notes cite. A source counts at its own byte size on disk, so a decoded byte count never inflates a file that is not UTF-8; non-file, unreadable and over-cap sources are skipped and counted, and `truncatedNotes` counts the sourced notes the ratio's 10000-note cap left out. Also notes modified in the last 7 and 30 days, and log event counts by type over the last `days` (default 30). Writes no vault file or log and takes no vault or log lock.", object({ vault, days: integer(1, STATS_MAX_DAYS) })),
75
81
  ];
76
82
  }
77
83
  type Issue = { code: string; severity: "error"; message: string };
@@ -82,7 +88,7 @@ const str = (value: unknown): string | undefined => typeof value === "string" ?
82
88
  * Handlers over the shared providers (VaultIndex, applyWrite, appendLog/readLog). The vault set and
83
89
  * the default (first personal) are fixed when the server starts; later registry changes need a restart.
84
90
  */
85
- export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.env): { tools: McpTool[]; handlers: Record<string, McpHandler>; vaults: VaultSpec[]; defaultVault: string | undefined } {
91
+ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.env): { tools: McpTool[]; handlers: Record<string, McpHandler>; vaults: VaultSpec[]; defaultVault: string | undefined; instructions: string } {
86
92
  const vaults = loadRegistry(home).vaults, ids = vaults.map(v => v.id);
87
93
  const defaultVault = (vaults.find(v => v.kind === "personal") ?? vaults[0])?.id;
88
94
  const pick = (args: Record<string, unknown>): VaultSpec => {
@@ -98,7 +104,7 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
98
104
  const write = (args: Record<string, unknown>, operation: WriteOp, extra: Partial<WriteRequest> = {}): WriteReceipt | ReturnType<typeof refusal> & Partial<WriteReceipt> => {
99
105
  const request: WriteRequest = { vault: pick(args).id, operation, channel: "mcp", ...extra, ...(args.log ? { log: args.log as LogEvent } : {}) };
100
106
  const receipt = applyWrite(home, request, { env });
101
- return receipt.ok ? receipt : { ...receipt, refused: true };
107
+ return receipt.ok || receipt.applied ? receipt : { ...receipt, refused: true };
102
108
  };
103
109
  const twoStep = (args: Record<string, unknown>) => ({ confirm: args.confirm === true, ...(str(args.fingerprint) ? { fingerprint: str(args.fingerprint) } : {}) });
104
110
  const document = (result: ReturnType<VaultIndex["show"]>) => {
@@ -108,13 +114,14 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
108
114
  return { path, sha256: hash, truncated, frontmatter: parsed.data, body: parsed.body };
109
115
  };
110
116
  const handlers: Record<string, McpHandler> = {
117
+ vmem_brief: args => vaultBrief(home, { vault: pick(args).id, intent: args.intent as string, paths: args.paths as string[] | undefined, bytes: args.bytes as number | undefined }, pick(args)),
111
118
  vmem_promote: async args => {
112
119
  const { promoteToOrg } = await import("./org-promote.ts");
113
120
  const source = vaults.find(v => v.id === defaultVault && v.kind === "personal");
114
121
  if (!source) return refusal("POLICY", "no personal vault registered");
115
122
  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,
116
123
  ...(Array.isArray(args.topics) ? { topics: args.topics as string[] } : {}), ...(str(args.fingerprint) ? { fingerprint: str(args.fingerprint) } : {}) }, { env });
117
- return result.ok ? result : { ...result, refused: true };
124
+ return result.ok || result.applied ? result : { ...result, refused: true };
118
125
  },
119
126
  vmem_promote_from_amem: async args => {
120
127
  const { promoteFromAmem } = await import("./promote.ts");
@@ -122,7 +129,7 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
122
129
  const result = await promoteFromAmem(home, { vault: pick(args).id, id, channel: "mcp", confirm: args.confirm === true,
123
130
  ...Object.fromEntries(["stem", "type", "domain", "description", "title", "body", "linkTo", "fingerprint"].filter(key => str(args[key]) !== undefined).map(key => [key, str(args[key])])),
124
131
  ...(Array.isArray(args.topics) ? { topics: args.topics as string[] } : {}) }, { env, ...(str(args.project) ? { project: str(args.project) } : {}) });
125
- return result.ok ? result : { ...result, refused: true };
132
+ return result.ok || result.applied ? result : { ...result, refused: true };
126
133
  },
127
134
  vmem_skills_mine: async args => {
128
135
  const { mineSkills } = await import("./skills-mine.ts");
@@ -133,7 +140,7 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
133
140
  vmem_read_file: args => readVaultFile(pick(args), loadRegistry(home).denyPaths ?? [], str(args.path)!, (args.maxBytes as number | undefined) ?? 16384, args.offset as number | undefined),
134
141
  vmem_list_files: args => listVaultFiles(pick(args), loadRegistry(home).denyPaths ?? [], str(args.dir)!),
135
142
  vmem_report: args => write(args, { op: "report", path: str(args.path)!, text: str(args.body)! }, args.dryRun === true ? { dryRun: true } : {}),
136
- 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),
143
+ 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),hints:true}).snapshot),
137
144
  vmem_graph_build: args => writeAnalysisReports(home,{vault:pick(args).id,kind:"graph",workspace:args.workspace === true,channel:"mcp",expectedVault:pick(args),dryRun:args.dryRun === true},env),
138
145
  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, str(args.relation)),
139
146
  vmem_status: () => ({ defaultVault: defaultVault ?? null, vaults: registryStatus(home).filter(v => ids.includes(v.id)) }),
@@ -175,6 +182,7 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
175
182
  return receipt.ok ? receipt : { ...receipt, refused: true };
176
183
  },
177
184
  vmem_move: args => write(args, { op: "move", from: str(args.from)!, to: str(args.to)! }, twoStep(args)),
185
+ vmem_merge: args => write(args, { op: "merge", keep: str(args.keep)!, absorb: str(args.absorb)! }, twoStep(args)),
178
186
  vmem_delete: args => {
179
187
  const receipt = write(args, { op: "delete", path: str(args.path)! }, twoStep(args));
180
188
  if (args.confirm === true) return receipt;
@@ -191,5 +199,5 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
191
199
  try { return await handler(args); }
192
200
  catch (error) { return refusal((error as { code?: unknown }).code === "V04" ? "V04" : "REFUSED", error instanceof Error ? error.message.slice(0, 500) : "operation refused"); }
193
201
  };
194
- return { tools: [...vaultTools(ids, vaults.filter(v => v.kind === "org").map(v => v.id)), ...specs.tools], handlers: guarded, vaults, defaultVault };
202
+ return { tools: [...vaultTools(ids, vaults.filter(v => v.kind === "org").map(v => v.id)), ...specs.tools], handlers: guarded, vaults, defaultVault, instructions: VMEM_INSTRUCTIONS };
195
203
  }
package/src/mcp.ts CHANGED
@@ -5,7 +5,7 @@ import type { Readable, Writable } from "node:stream";
5
5
  export const FRAME_BYTES = 65_536, RESULT_BYTES = 262_144;
6
6
  export interface McpTool { name: string; description: string; inputSchema: Record<string, unknown>; annotations: Record<string, boolean> }
7
7
  export type McpHandler = (args: Record<string, unknown>) => unknown | Promise<unknown>;
8
- export interface McpServerOptions { tools: readonly McpTool[]; handlers: Record<string, McpHandler>; input?: Readable; output?: Writable; name?: string; version?: string }
8
+ export interface McpServerOptions { tools: readonly McpTool[]; handlers: Record<string, McpHandler>; input?: Readable; output?: Writable; name?: string; version?: string; instructions?: string }
9
9
  const protocols = ["2025-06-18", "2025-03-26", "2024-11-05"];
10
10
  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);
11
11
 
@@ -22,6 +22,7 @@ export function argumentError(value: unknown, raw: unknown, path = ""): string |
22
22
  if (value.length < (s.minLength ?? 0)) return fail(`shorter than ${s.minLength}`);
23
23
  if (value.length > (s.maxLength ?? FRAME_BYTES)) return fail(`longer than ${s.maxLength ?? FRAME_BYTES}`);
24
24
  if (value.includes("\0")) return fail("NUL is not allowed");
25
+ if (s.pattern && !new RegExp(s.pattern).test(value)) return fail("does not match the required pattern");
25
26
  }
26
27
  if (typeof value === "number") {
27
28
  if (!Number.isFinite(value)) return fail("expected finite number");
@@ -79,7 +80,8 @@ export async function serveMcp(options: McpServerOptions): Promise<void> {
79
80
  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; }
80
81
  phase = "initializing";
81
82
  await send({ jsonrpc: "2.0", id, result: { protocolVersion: protocols.includes(msg.params.protocolVersion) ? msg.params.protocolVersion : protocols[0],
82
- capabilities: { tools: { listChanged: false } }, serverInfo: { name: options.name ?? "vmem", version: options.version ?? "unreleased" } } });
83
+ capabilities: { tools: { listChanged: false } }, serverInfo: { name: options.name ?? "vmem", version: options.version ?? "unreleased" },
84
+ ...(options.instructions !== undefined ? { instructions: options.instructions } : {}) } });
83
85
  return;
84
86
  }
85
87
  if (phase !== "ready") { await error(id, -32002, "Initialize the session first"); return; }
@@ -1,3 +1,4 @@
1
+ import { canonRowsForVault, matchCanonRows, type CanonRowIndex, type CanonRowMatch } from "./canon-tables.ts";
1
2
  import { domainProblem } from "./config.ts";
2
3
  import { localDate } from "./local-date.ts";
3
4
  import { createHash } from "node:crypto";
@@ -9,7 +10,7 @@ import { normalizeTarget, proseLines } from "./links.ts";
9
10
  import { loadRegistry } from "./registry.ts";
10
11
  import { VaultIndex } from "./vault-index.ts";
11
12
  import { applyWrite } from "./writer.ts";
12
- import { notePath, replaceTopicsSection } from "./write-operations.ts";
13
+ import { planOperation, stampContentChanges, notePath, replaceTopicsSection } from "./write-operations.ts";
13
14
  import { screenContent } from "./write-validation.ts";
14
15
  import { appendLog, logBinding } from "./vault-log.ts";
15
16
  import type { WriteIssue, WriteReceipt } from "./write-types.ts";
@@ -40,6 +41,10 @@ export interface OrgPromoteResult {
40
41
  target: string | null;
41
42
  text?: string;
42
43
  droppedLinks?: string[];
44
+ /** Target-vault advisory data, excluded from the promotion fingerprint. */
45
+ canonRowMatches?: CanonRowMatch[];
46
+ canonTableWarnings?: string[];
47
+ choices?: string[];
43
48
  screen: { passed: boolean; issues: WriteIssue[] };
44
49
  fingerprint?: string;
45
50
  issues: WriteIssue[];
@@ -119,13 +124,13 @@ export function dropUnresolvedLinks(body: string, resolves: (target: string) =>
119
124
  }
120
125
 
121
126
  /** Target-vault facts read once from its index: link resolution (path stems only, as Obsidian resolves), MOCs and existing paths. */
122
- function targetFacts(home: string, spec: VaultSpec, all: VaultSpec[], links: string[], targetPath: string): { resolved: Set<string>; mocs: Set<string>; exists: boolean } {
127
+ function targetFacts(home: string, spec: VaultSpec, all: VaultSpec[], links: string[], targetPath: string, denyPaths: string[] = []): { resolved: Set<string>; mocs: Set<string>; exists: boolean; canon?: CanonRowIndex } {
123
128
  const index = new VaultIndex(home, spec, all.map(v => v.path));
124
129
  try {
125
130
  index.scan();
126
131
  const targets = index.linkTargets(), resolved = new Set([...new Set(links)].map(linkKey).filter(key => targets.has(key)));
127
132
  // Path existence is checked without alias lookup, so another note's alias cannot hide the target.
128
- return { resolved, mocs: new Set(index.mocs(500).map(moc => linkKey(moc.path))), exists: targets.has(linkKey(targetPath)) };
133
+ return { resolved, mocs: new Set(index.mocs(500).map(moc => linkKey(moc.path))), exists: targets.has(linkKey(targetPath)), ...(spec.canonTables !== undefined ? { canon: canonRowsForVault(index, spec, denyPaths) } : {}) };
129
134
  } finally { index.close(); }
130
135
  }
131
136
  function readSource(spec: VaultSpec, path: string): string {
@@ -162,6 +167,7 @@ export function lintPromoted(home: string, target: VaultSpec, path: string, text
162
167
  * Preview and refusal write nothing; confirm needs the fingerprint of the current preview.
163
168
  */
164
169
  export function promoteToOrg(home: string, request: OrgPromoteRequest, options: { env?: NodeJS.ProcessEnv; now?: Date } = {}): OrgPromoteResult {
170
+ const now = options.now ?? new Date();
165
171
  const result: OrgPromoteResult = { ok: false, applied: false, source: null, target: null, screen: { passed: false, issues: [] }, issues: [] };
166
172
  const fail = (found: WriteIssue) => ({ ...result, issues: [found] });
167
173
  const config = loadRegistry(home), all = config.vaults;
@@ -194,7 +200,8 @@ export function promoteToOrg(home: string, request: OrgPromoteRequest, options:
194
200
  const topics = (request.topics ?? strings(parsed.data.topics)).map(value => value.startsWith("[[") ? value : `[[${value}]]`);
195
201
  const bodyLinks = [...parsed.body.matchAll(/\[\[([^\]\n|#]+)/g)].map(match => match[1]!.trim());
196
202
  const fieldLinks = ["project", "superseded_by", "supersedes", "source_ref"].flatMap(key => strings(parsed.data[key]).filter(value => value.includes("[[")).map(linkKey));
197
- const targetNotes = targetFacts(home, target, all, [...bodyLinks, ...fieldLinks], targetPath);
203
+ const targetNotes = targetFacts(home, target, all, [...bodyLinks, ...fieldLinks], targetPath, config.denyPaths ?? []);
204
+ if (targetNotes.canon?.warnings.length) result.canonTableWarnings = [...targetNotes.canon.warnings];
198
205
  // The org note is never overwritten; a repeat promotion (--again) needs the earlier org copy moved or deleted first.
199
206
  if (targetNotes.exists) {
200
207
  // Recovery: an earlier confirm created this org note but the source provenance write failed.
@@ -202,13 +209,13 @@ export function promoteToOrg(home: string, request: OrgPromoteRequest, options:
202
209
  try { existing = parseFrontmatter(readSource(target, targetPath)).data; } catch { /* unreadable: treated as foreign */ }
203
210
  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));
204
211
  const set = { promoted_to: prior.length ? [...prior, promotedTo] : promotedTo };
205
- const plan = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, binding: bindings.source });
212
+ const plan = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, binding: bindings.source, now });
206
213
  const fingerprint = sha({ recover: plan.fingerprint, promotedTo });
207
214
  const recovery: OrgPromoteResult = { ...result, target: `${target.id}:${targetPath}`, screen: { passed: true, issues: [] }, fingerprint, recovery: "provenance-only" };
208
215
  if (!plan.ok) return { ...recovery, issues: plan.issues };
209
216
  if (request.confirm !== true) return { ...recovery, ok: true, preview: true };
210
217
  if (request.fingerprint !== fingerprint) return { ...recovery, issues: [issue("V09", "stale or missing preview fingerprint")] };
211
- const provenance = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set }, channel: request.channel ?? "cli", log: false }, { env: options.env, binding: bindings.source });
218
+ const provenance = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set }, channel: request.channel ?? "cli", log: false }, { env: options.env, binding: bindings.source, now });
212
219
  return { ...recovery, ok: provenance.ok, applied: provenance.applied, provenance, issues: provenance.ok ? [] : provenance.issues };
213
220
  }
214
221
  const missingTopics = topics.filter(topic => !targetNotes.mocs.has(linkKey(topic)));
@@ -216,24 +223,34 @@ export function promoteToOrg(home: string, request: OrgPromoteRequest, options:
216
223
  const transformed = dropUnresolvedLinks(parsed.body, value => targetNotes.resolved.has(linkKey(value)));
217
224
  // Body Topics section follows the target topics.
218
225
  const body = replaceTopicsSection(transformed.body, topics);
219
- const day = localDate(options.now ?? new Date());
226
+ const day = localDate(now);
220
227
  const frontmatter: Record<string, unknown> = { topics, promoted_from: result.source, promoted_at: day, promoted_to: undefined };
221
228
  // Wiki-valued fields that point outside the target vault are dropped as well.
222
229
  for (const key of ["project", "superseded_by", "supersedes", "source_ref"]) {
223
230
  const values = strings(parsed.data[key]);
224
231
  if (values.some(value => value.includes("[[") && !targetNotes.resolved.has(linkKey(value)))) { frontmatter[key] = undefined; transformed.dropped.push(`${key}:${values.join(",")}`); }
225
232
  }
226
- const text = emitFrontmatter(parseFrontmatter(parsed.source.slice(0, parsed.source.length - parsed.body.length) + body), frontmatter);
233
+ let text = emitFrontmatter(parseFrontmatter(parsed.source.slice(0, parsed.source.length - parsed.body.length) + body), frontmatter);
227
234
  result.target = `${target.id}:${targetPath}`; result.text = text; result.droppedLinks = transformed.dropped;
228
235
  const screen = [...screenForOrg(text, parsed.data, target, config), ...screenDroppedLinks(home, source, all, transformed.dropped.filter(link => !link.includes(":")))];
229
236
  const refusing = screen.filter(found => found.severity === "error");
230
237
  result.screen = { passed: refusing.length === 0, issues: screen };
231
238
  if (refusing.length) return { ...result, issues: screen };
232
- const planned = applyWrite(home, { vault: target.id, operation: { op: "create", path: targetPath, frontmatter: {}, body: text }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, piiSurface: "promotion", binding: bindings.target });
239
+ const planned = applyWrite(home, { vault: target.id, operation: { op: "create", path: targetPath, frontmatter: {}, body: text }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, piiSurface: "promotion", binding: bindings.target, now });
240
+ if (planned.ok) {
241
+ const operation = { op: "create" as const, path: targetPath, frontmatter: {}, body: text };
242
+ text = stampContentChanges(operation, planOperation(operation, new Map()), day)[0]!.after!;
243
+ result.text = text;
244
+ }
233
245
  const provenanceSet = { promoted_to: prior.length ? [...prior.filter(p => p !== promotedTo), promotedTo] : promotedTo };
234
246
  const provenanceText = emitFrontmatter(parsed, provenanceSet);
235
- const provenancePlan = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set: provenanceSet }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, binding: bindings.source });
247
+ const provenancePlan = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set: provenanceSet }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, binding: bindings.source, now });
236
248
  result.fingerprint = sha({ target: planned.fingerprint, source: provenancePlan.fingerprint, text, provenanceText });
249
+ if (targetNotes.canon !== undefined) {
250
+ const matches = planned.ok ? matchCanonRows(targetNotes.canon, `${String(parsed.data.title ?? "")}\n${parseFrontmatter(text).body}`) : [];
251
+ result.canonRowMatches = matches;
252
+ if (matches.length) result.choices = [...new Set(matches.map(row => `link-existing ${row.path}`))];
253
+ }
237
254
  // Org lint runs on the preview too (the note overlaid on the org snapshot), so a note that would fail lint is never written.
238
255
  const previewLint = lintPromoted(home, target, targetPath, text);
239
256
  result.lint = previewLint;
@@ -242,10 +259,10 @@ export function promoteToOrg(home: string, request: OrgPromoteRequest, options:
242
259
  if (request.confirm !== true) return { ...result, ok: true, preview: true, issues: [...planned.issues, ...provenancePlan.issues] };
243
260
  if (request.fingerprint !== result.fingerprint) return { ...result, issues: [issue("V09", "stale or missing preview fingerprint")] };
244
261
  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"}` };
245
- const note = applyWrite(home, { vault: target.id, operation: { op: "create", path: targetPath, frontmatter: {}, body: text }, channel: request.channel ?? "cli", log: false }, { env: options.env, piiSurface: "promotion", binding: bindings.target });
262
+ const note = applyWrite(home, { vault: target.id, operation: { op: "create", path: targetPath, frontmatter: {}, body: text }, channel: request.channel ?? "cli", log: false }, { env: options.env, piiSurface: "promotion", binding: bindings.target, now });
246
263
  // A create that committed and then failed a later step (cleanup) is still a written org note.
247
264
  if (!note.ok || !note.applied) return { ...result, applied: note.applied === true, note, issues: note.issues };
248
- const provenance = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set: provenanceSet }, channel: request.channel ?? "cli", log: false }, { env: options.env, binding: bindings.source });
265
+ const provenance = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set: provenanceSet }, channel: request.channel ?? "cli", log: false }, { env: options.env, binding: bindings.source, now });
249
266
  const logs = { source: null as LogReceipt | null, target: null as LogReceipt | null };
250
267
  for (const [key, vault] of [["target", target], ["source", source]] as const) {
251
268
  try { logs[key] = appendLog(home, { vault: vault.id, event, channel: request.channel ?? "cli" }, { env: options.env, binding: bindings[key] }); }
package/src/promote.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { canonRowsForVault, matchCanonRows, type CanonRowIndex, type CanonRowMatch } from "./canon-tables.ts";
1
2
  import { localDate } from "./local-date.ts";
2
3
  import { createHash } from "node:crypto";
3
4
  import type { VaultSpec } from "./config.ts";
@@ -5,7 +6,7 @@ import { emitFrontmatter, parseFrontmatter } from "./frontmatter.ts";
5
6
  import { loadRegistry } from "./registry.ts";
6
7
  import { VaultIndex } from "./vault-index.ts";
7
8
  import { applyWrite } from "./writer.ts";
8
- import { notePath } from "./write-operations.ts";
9
+ import { notePath, planOperation, stampContentChanges } from "./write-operations.ts";
9
10
  import type { WriteIssue, WriteReceipt } from "./write-types.ts";
10
11
  import type { AmemCandidate, AmemSeam, AmemOptions } from "./amem/seam.ts";
11
12
 
@@ -31,6 +32,9 @@ export interface PromoteResult {
31
32
  fingerprint?: string;
32
33
  issues: WriteIssue[];
33
34
  possibleDuplicates?: string[];
35
+ /** Advisory canonical table rows; never part of a fingerprint or a write refusal. */
36
+ canonRowMatches?: CanonRowMatch[];
37
+ canonTableWarnings?: string[];
34
38
  /** Choices offered when the note may already exist in the vault. */
35
39
  choices?: string[];
36
40
  note?: WriteReceipt;
@@ -70,10 +74,10 @@ export function draftNote(entry: AmemCandidate, meta: PromoteMetadata, now = new
70
74
  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`;
71
75
  return { stem, frontmatter, text: emitFrontmatter(parseFrontmatter(body), frontmatter) };
72
76
  }
73
- function vaultSpec(home: string, id: string): { spec: VaultSpec; all: VaultSpec[] } {
74
- const all = loadRegistry(home).vaults, spec = all.find(v => v.id === id);
77
+ function vaultSpec(home: string, id: string): { spec: VaultSpec; all: VaultSpec[]; denyPaths: string[] } {
78
+ const config = loadRegistry(home), all = config.vaults, spec = all.find(v => v.id === id);
75
79
  if (!spec) throw new Error("promote: unknown vault id");
76
- return { spec, all };
80
+ return { spec, all, denyPaths: config.denyPaths ?? [] };
77
81
  }
78
82
  const fold = (value: string) => value.normalize("NFKC").toLowerCase().replace(/[-_\s]+/g, " ").trim();
79
83
  /** Existing notes with the same stem or title, plus close FTS title matches: the link-existing choices. */
@@ -87,14 +91,14 @@ function similar(home: string, spec: VaultSpec, all: VaultSpec[], title: string,
87
91
  return [...exact, ...hits].map(hit => `notes/${hit.path}`).filter((path, i, list) => list.indexOf(path) === i).slice(0, 5);
88
92
  } catch { return []; } finally { index.close(); }
89
93
  }
90
- function lookup(home: string, spec: VaultSpec, all: VaultSpec[], id: string, linkTo?: string): { promoted: string[]; target?: string } {
94
+ function lookup(home: string, spec: VaultSpec, all: VaultSpec[], id: string, linkTo?: string, denyPaths: string[] = []): { promoted: string[]; target?: string; canon?: CanonRowIndex } {
91
95
  const index = new VaultIndex(home, spec, all.map(v => v.path));
92
96
  try {
93
97
  index.scan();
94
98
  const promoted = index.promotedFrom(`mem:${id}`).map(path => `notes/${path}`);
95
99
  let target: string | undefined;
96
100
  if (linkTo !== undefined) target = `notes/${index.show(linkTo, 1).path}`;
97
- return { promoted, ...(target ? { target } : {}) };
101
+ return { promoted, ...(target ? { target } : {}), ...(spec.canonTables !== undefined ? { canon: canonRowsForVault(index, spec, denyPaths) } : {}) };
98
102
  } finally { index.close(); }
99
103
  }
100
104
 
@@ -106,16 +110,18 @@ function lookup(home: string, spec: VaultSpec, all: VaultSpec[], id: string, lin
106
110
  * the note through `promoted_from` and offers link-only instead of a second note.
107
111
  */
108
112
  export async function promoteFromAmem(home: string, request: PromoteRequest, options: { env?: NodeJS.ProcessEnv; project?: string; cwd?: string; seam?: SeamFactory; now?: Date } = {}): Promise<PromoteResult> {
113
+ const now = options.now ?? new Date();
109
114
  const base: PromoteResult = { ok: false, action: "create", applied: false, id: request.id, path: null, issues: [] };
110
115
  if (!ID.test(request.id)) return { ...base, issues: [issue("AMEM", "expected a 32-hex agent-mem entry id")] };
111
- const { spec, all } = vaultSpec(home, request.vault);
116
+ const { spec, all, denyPaths } = vaultSpec(home, request.vault);
112
117
  if (spec.write === "none" || (request.channel === "mcp" && spec.write !== "mcp")) return { ...base, issues: [issue("POLICY", "vault write policy refuses this channel")] };
113
118
  const seam = await (options.seam ?? defaultSeam)({ env: options.env, ...(options.project ? { project: options.project } : {}), ...(options.cwd ? { cwd: options.cwd } : {}), piiPatterns: loadRegistry(home).piiPatterns });
114
119
  try {
115
120
  const entry = await seam.entry(request.id);
116
121
  if (!entry) return { ...base, issues: [issue("AMEM", "entry is not an available curated entry of this project")] };
117
122
  const linked = seam.linkedPath(request.id) ?? null;
118
- const { promoted, target } = lookup(home, spec, all, request.id, request.linkTo);
123
+ const { promoted, target, canon } = lookup(home, spec, all, request.id, request.linkTo, denyPaths);
124
+ if (canon?.warnings.length) base.canonTableWarnings = [...canon.warnings];
119
125
  // Link-only: an earlier promotion already created the note, or the caller chose an existing note.
120
126
  const existing = target ?? promoted[0];
121
127
  if (existing) {
@@ -128,22 +134,28 @@ export async function promoteFromAmem(home: string, request: PromoteRequest, opt
128
134
  await seam.recordLink(request.id, existing);
129
135
  return { ...result, applied: true, linked: existing };
130
136
  }
131
- const draft = draftNote(entry, request, options.now);
137
+ const draft = draftNote(entry, request, now);
132
138
  if (!draft.stem) return { ...base, issues: [issue("V04", "cannot derive an ASCII stem from the title; pass --stem")] };
133
139
  let path: string;
134
140
  try { path = notePath(draft.stem); } catch { return { ...base, issues: [issue("V04", "expected a flat lowercase ASCII stem")] }; }
135
141
  const operation = { op: "create" as const, path: draft.stem, frontmatter: {}, body: draft.text };
136
- const planned = applyWrite(home, { vault: spec.id, operation, channel: request.channel ?? "cli", dryRun: true }, { env: options.env });
142
+ const planned = applyWrite(home, { vault: spec.id, operation, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, now });
137
143
  const v08 = planned.issues.some(i => i.code === "V08") || (planned.possibleDuplicates?.length ?? 0) > 0;
138
144
  const possibleDuplicates = v08 ? [...new Set([...(planned.possibleDuplicates ?? []), ...similar(home, spec, all, String(draft.frontmatter.title), draft.stem)])].filter(p => p !== path) : [];
139
145
  const fingerprint = sha({ action: "create", id: request.id, write: planned.fingerprint, text: draft.text, linked, vault: spec.id });
140
- const result: PromoteResult = { ...base, ok: planned.ok, path, text: draft.text, fingerprint, issues: planned.issues, linked,
146
+ const text = planned.ok ? stampContentChanges(operation, planOperation(operation, new Map()), localDate(now))[0]!.after! : draft.text;
147
+ const result: PromoteResult = { ...base, ok: planned.ok, path, text, fingerprint, issues: planned.issues, linked,
141
148
  ...(possibleDuplicates.length ? { possibleDuplicates, choices: ["create", ...possibleDuplicates.map(p => `link-existing ${p}`)] } : {}) };
149
+ if (canon !== undefined) {
150
+ const matches = planned.ok ? matchCanonRows(canon, `${String(draft.frontmatter.title ?? "")}\n${parseFrontmatter(text).body}`) : [];
151
+ result.canonRowMatches = matches;
152
+ if (matches.length) result.choices = [...new Set([...(result.choices ?? ["create"]), ...matches.map(row => `link-existing ${row.path}`)])];
153
+ }
142
154
  if (request.confirm !== true || !planned.ok) return { ...result, preview: request.confirm !== true };
143
155
  if (request.fingerprint !== fingerprint) return { ...result, ok: false, issues: [issue("V09", "stale or missing preview fingerprint")] };
144
156
  const note = applyWrite(home, { vault: spec.id, operation, channel: request.channel ?? "cli",
145
- log: { type: "LEARN", project: logProjectFor(seam.project, request.logProject), source: `mem:${request.id}`, dest: path, note: `promoted: ${entry.kind}` } }, { env: options.env });
146
- if (!note.ok || !note.applied) return { ...result, ok: false, note, issues: note.issues };
157
+ log: { type: "LEARN", project: logProjectFor(seam.project, request.logProject), source: `mem:${request.id}`, dest: path, note: `promoted: ${entry.kind}` } }, { env: options.env, now });
158
+ if (!note.ok || !note.applied) return { ...result, ok: false, applied: note.applied, note, issues: note.issues };
147
159
  try {
148
160
  await seam.recordLink(request.id, path);
149
161
  return { ...result, ok: note.log?.ok !== false, applied: true, note, linked: path, issues: note.log?.ok === false ? note.log.issues : [] };
@@ -3,7 +3,6 @@ import { VaultIndex, MAX_NOTE_BYTES } from "./vault-index.ts";
3
3
  import { PLAIN, type TextOptions } from "./text-output.ts";
4
4
  import { linksText, rebuildText, searchText, showText } from "./read-output.ts";
5
5
  import type { NoteReadResult, SearchResult } from "./vault-index.ts";
6
- import type { ResolvedLink } from "./links.ts";
7
6
  const READ_COMMANDS = new Set(["rebuild", "search", "show", "links"]);
8
7
  export function isReadCommand(command: string): boolean { return READ_COMMANDS.has(command); }
9
8
  export function runReadCommand(command: string, args: string[], home: string, text: TextOptions = PLAIN): { text: string; code: number } {
@@ -48,6 +47,6 @@ export function runReadCommand(command: string, args: string[], home: string, te
48
47
  const out = command === "rebuild" ? rebuildText(result as Parameters<typeof rebuildText>[0], text)
49
48
  : command === "search" ? searchText(result as SearchResult[], text, { vault: vaultId, query: target, limit: limit ?? 50, type: options["--type"] as string | undefined, domain: options["--domain"] as string | undefined })
50
49
  : command === "show" ? showText(result as NoteReadResult, text, { vault: vaultId, target, maxBytes })
51
- : linksText(result as ResolvedLink[], text, { vault: vaultId, target, limit: limit ?? 50 });
50
+ : linksText(result as Parameters<typeof linksText>[0], text, { vault: vaultId, target, limit: limit ?? 50 });
52
51
  return { text: out, code: 0 };
53
52
  }
@@ -3,12 +3,12 @@
3
3
  * command prints with `--json`, and never shows more than that result carries.
4
4
  */
5
5
  import type { SearchResult, NoteReadResult } from "./vault-index.ts";
6
- import type { ResolvedLink } from "./links.ts";
6
+ import type { ResolvedLink, SuggestedLink } from "./links.ts";
7
7
  import type { LogReadResult, LogReceipt } from "./log-types.ts";
8
8
  import type { LintCode, LintReport } from "./analysis-types.ts";
9
9
  import type { GraphNeighborhood } from "./vault-graph.ts";
10
10
  import type { WriteIssue, WriteReceipt } from "./write-types.ts";
11
- import { blocks, clean, fields, heading, issueTable, nextCommand, paint, paragraph, plural, shellWord, table, tone, type TextOptions, stripTerminal } from "./text-output.ts";
11
+ import { blocks, clean, fields, heading, issueTable, nextCommand, paint, paragraph, plural, shellWord, table, tone, type CellInput, type TextOptions, stripTerminal } from "./text-output.ts";
12
12
 
13
13
  const command = (...words: string[]) => ["vmem", ...words].map(shellWord).join(" ");
14
14
 
@@ -32,12 +32,14 @@ export function showText(r: NoteReadResult, o: TextOptions, c: { vault: string;
32
32
  return blocks(head, stripTerminal(r.content).replace(/\n+$/, ""), tail.join("\n"), headings);
33
33
  }
34
34
 
35
- export function linksText(links: ResolvedLink[], o: TextOptions, c: { vault: string; target: string; limit: number }): string {
35
+ /** A listed link; a dead one may carry the one hinted target, as `vmem links --json` and `vmem_links` return it. */
36
+ export function linksText(links: SuggestedLink[], o: TextOptions, c: { vault: string; target: string; limit: number }): string {
36
37
  const from = links[0]?.source ?? c.target;
37
38
  const count = `${plural(links.length, "link")} from ${clean(from)}`;
38
39
  if (!links.length) return count;
39
40
  const target = (l: ResolvedLink) => l.target + (l.heading !== null ? `#${l.heading}` : "") + (l.block !== null ? `#^${l.block}` : "");
40
- const rows = links.map(l => [target(l), l.resolved ?? tone(l.reason ?? "unresolved", "warn"), l.line]);
41
+ const resolution = (l: SuggestedLink): CellInput => l.resolved ?? tone(`${l.reason ?? "unresolved"}${l.suggested ? `; suggested ${clean(l.suggested.path)} (${l.suggested.score.toFixed(3)})` : ""}`, "warn");
42
+ const rows = links.map(l => [target(l), resolution(l), l.line]);
41
43
  const more = links.length >= c.limit && c.limit < 500 ? nextCommand("next", command("links", c.vault, c.target, "--limit", String(Math.min(500, c.limit * 2))), o) : undefined;
42
44
  return blocks(heading("OUT", o) + "\n" + table(["TARGET", "RESOLVED", "LINE"], rows, o), [count, more].filter(Boolean).join("\n"));
43
45
  }
@@ -60,7 +62,7 @@ export function logAppendText(r: LogReceipt, o: TextOptions, c: { vault: string;
60
62
  return blocks(line, issueTable(r.issues, o));
61
63
  }
62
64
 
63
- const LEVELS: Record<LintCode, "error" | "warn"> = { L01: "error", L02: "error", L03: "warn", L09: "warn", L10: "warn", L11: "warn", L12: "warn", L13: "error", L14: "warn" };
65
+ const LEVELS: Record<LintCode, "error" | "warn"> = { L01: "error", L02: "error", L03: "warn", L09: "warn", L10: "warn", L11: "warn", L12: "warn", L13: "error", L14: "warn", L15: "warn" };
64
66
  const verdict = (r: { errors: number; warnings: number; summary: string }, o: TextOptions) => paint(clean(r.summary), r.errors ? "fail" : r.warnings ? "warn" : "ok", o);
65
67
  export function lintText(d: { report: LintReport; notes: number; titles: Record<LintCode, string>; info: Partial<Record<LintCode, string>> }, o: TextOptions, c: { vault: string; note?: string }): string {
66
68
  const rows = (Object.keys(d.report.findings) as LintCode[]).flatMap(code => {
package/src/registry.ts CHANGED
@@ -45,6 +45,7 @@ function mutate<T>(home: string, update: (config: VmemConfig) => T): T {
45
45
  const config = loadRegistry(home), result = update(config);
46
46
  if (config.specs !== undefined) config.version = Math.max(config.version ?? 1, 2);
47
47
  if (config.vaults.some(vault => vault.domains !== undefined)) config.version = Math.max(config.version ?? 1, 3);
48
+ if (config.vaults.some(vault => vault.canonTables !== undefined)) config.version = Math.max(config.version ?? 1, 4);
48
49
  parseConfig(config);
49
50
  const text = JSON.stringify(config, null, 2) + "\n";
50
51
  if (Buffer.byteLength(text) > MAX_CONFIG_BYTES) throw new Error(`${join(home, CONFIG_FILE)}: serialized config exceeds 64 KiB`);
@@ -47,7 +47,7 @@ export interface MineOptions {
47
47
  export interface MineResult {
48
48
  vault: string; days: number; since: string; projects: string[];
49
49
  records: Record<RecordSource, number>;
50
- dropped: { secret: number; policy: number; oversized: number; duplicate: number; unreadable: number; truncatedCapture: number };
50
+ dropped: { secret: number; policy: number; oversized: number; duplicate: number; unreadable: number; truncatedCapture: number; malformedRecord: number };
51
51
  graph: { nodes: number; edges: number; communities: number; partitioner: "leiden" };
52
52
  godNodes: { id: string; degree: number }[];
53
53
  candidates: Candidate[];
@@ -322,7 +322,7 @@ export interface MineInputs {
322
322
  }
323
323
  /** The pure part: screen, mask, match, cluster, score and render. */
324
324
  export function mineRecords(input: MineInputs): MineResult {
325
- const dropped: MineResult["dropped"] = { secret: 0, policy: 0, oversized: 0, duplicate: 0, unreadable: 0, truncatedCapture: 0, ...input.dropped };
325
+ const dropped: MineResult["dropped"] = { secret: 0, policy: 0, oversized: 0, duplicate: 0, unreadable: 0, truncatedCapture: 0, malformedRecord: 0, ...input.dropped };
326
326
  const ordered = [...input.records].sort((a, b) => compare(a.at, b.at) || compare(a.source, b.source) || compare(a.project, b.project) || compare(a.text, b.text));
327
327
  const kept: MineRecord[] = [], texts = new Set<string>();
328
328
  let total = 0;
@@ -397,7 +397,8 @@ export function renderReport(result: Omit<MineResult, "report">, today: string,
397
397
  `# Skill Candidates (${today}, memory-based)`, "",
398
398
  `- corpus: ${total} records / ${result.days} days (curated ${result.records.curated}, capture ${result.records.capture}, vault ${result.records.vault})`,
399
399
  `- projects: ${result.projects.length}`,
400
- `- dropped: secret ${result.dropped.secret}, policy ${result.dropped.policy}, oversized ${result.dropped.oversized}, duplicate ${result.dropped.duplicate}, unreadable ${result.dropped.unreadable}`,
400
+ `- dropped: secret ${result.dropped.secret}, policy ${result.dropped.policy}, oversized ${result.dropped.oversized}, duplicate ${result.dropped.duplicate}, unreadable ${result.dropped.unreadable}, malformed Record ${result.dropped.malformedRecord}`,
401
+ `- truncated capture machine shards: ${result.dropped.truncatedCapture}; rows of any event beyond maxReadRows were not read`,
401
402
  `- graph: ${result.graph.nodes} nodes, ${result.graph.edges} edges, ${result.graph.communities} communities (deterministic Leiden)`, "",
402
403
  ];
403
404
  if (result.godNodes.length) {
@@ -449,7 +450,7 @@ export async function mineSkills(home: string, options: MineOptions): Promise<Mi
449
450
  const amem = await readAmemForMining({ env: options.env, since, ...(options.project ? { project: options.project } : {}), piiPatterns: local.config.piiPatterns ?? [] });
450
451
  return mineRecords({
451
452
  vault: options.vault, days, since, projects: amem.projects, records: [...amem.records, ...local.records], vocab, registry, skills, minSize, minNovelty, piiPatterns: local.config.piiPatterns ?? [],
452
- today: localDate(now), dropped: { policy: amem.screened, unreadable: amem.unreadable + local.unreadable, truncatedCapture: amem.truncatedCapture },
453
+ today: localDate(now), dropped: { policy: amem.screened, unreadable: amem.unreadable + local.unreadable, truncatedCapture: amem.truncatedCapture, malformedRecord: amem.malformedRecord },
453
454
  });
454
455
  }
455
456