@staix/vault-mem 0.9.1 → 0.10.1

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 (49) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/README.md +19 -6
  3. package/bin/vmem.js +2 -2
  4. package/package.json +2 -2
  5. package/src/analysis-commands.ts +24 -14
  6. package/src/analysis-input.ts +12 -0
  7. package/src/analysis-types.ts +5 -1
  8. package/src/assert-command.ts +48 -0
  9. package/src/assertion-exposure.ts +367 -0
  10. package/src/assertion-index.ts +86 -0
  11. package/src/assertion-policy.ts +63 -0
  12. package/src/assertion-read.ts +170 -0
  13. package/src/assertions-command.ts +123 -0
  14. package/src/assertions.ts +1013 -0
  15. package/src/cli-output.ts +9 -3
  16. package/src/cli.ts +44 -23
  17. package/src/commands-table.ts +16 -2
  18. package/src/evidence.ts +222 -0
  19. package/src/graph-evidence.ts +169 -0
  20. package/src/index.ts +14 -0
  21. package/src/links.ts +18 -0
  22. package/src/log-commands.ts +7 -7
  23. package/src/mcp-spec.ts +11 -11
  24. package/src/mcp-vault.ts +105 -6
  25. package/src/mcp.ts +4 -0
  26. package/src/org-commands.ts +5 -5
  27. package/src/org-promote.ts +9 -0
  28. package/src/promote-command.ts +6 -6
  29. package/src/proposal-commands.ts +100 -0
  30. package/src/proposal-provider.ts +335 -0
  31. package/src/proposal-storage.ts +334 -0
  32. package/src/proposals.ts +170 -0
  33. package/src/read-commands.ts +44 -12
  34. package/src/read-output.ts +42 -14
  35. package/src/skills-mine.ts +12 -7
  36. package/src/source-age.ts +131 -0
  37. package/src/spec-output.ts +14 -13
  38. package/src/sync.ts +14 -7
  39. package/src/text-output.ts +86 -21
  40. package/src/vault-brief.ts +8 -4
  41. package/src/vault-graph.ts +12 -3
  42. package/src/vault-history.ts +662 -0
  43. package/src/vault-index.ts +2 -0
  44. package/src/vault-lint.ts +15 -4
  45. package/src/write-commands.ts +18 -17
  46. package/src/write-output.ts +6 -6
  47. package/src/write-types.ts +1 -0
  48. package/src/write-validation.ts +3 -1
  49. package/src/writer.ts +257 -11
package/src/cli-output.ts CHANGED
@@ -7,7 +7,7 @@ import type { ResolvedHome } from "./home.ts";
7
7
  import type { PiiMatrix, PiiRow } from "./pii.ts";
8
8
  import { effectivePii, type RecoveryReport } from "./registry.ts";
9
9
  import type { SetupReport } from "./setup.ts";
10
- import { blocks, clean, fields, heading, issueTable, nextCommand, paint, paragraph, plural, shellWord, table, tone, type CellInput, type TextOptions } from "./text-output.ts";
10
+ import { blocks, clean, fields, heading, issueTable, marker, nextCommand, paragraph as formatParagraph, plural, shellWord, status, table, tone, type CellInput, type TextOptions, type Tone } from "./text-output.ts";
11
11
  import { MAX_RATIO_NOTES } from "./vault-index.ts";
12
12
  import type { VaultStats } from "./vault-stats.ts";
13
13
 
@@ -18,12 +18,17 @@ export type SpecRow = SpecSourceSpec & { healthy?: boolean; issue?: string };
18
18
  export interface StatusResult extends ResolvedHome { version: string; healthy: boolean; vaults: VaultRow[]; specs?: SpecRow[] }
19
19
  export interface Manifest { name: string; version: string; configVersion: number; mcp: { server: string; tools: (string | { name: string; readOnly: boolean })[] }; commands: string[] }
20
20
 
21
- const OK = tone("ok", "ok"), WARN = tone("warn", "warn"), FAIL = tone("fail", "fail");
21
+ const statuses = (o: TextOptions) => {
22
+ const plain = { ...o, color: false };
23
+ return { OK: tone(`${marker("ok", plain)} ok`, "ok"), WARN: tone(`${marker("warn", plain)} warn`, "warn"), FAIL: tone(`${marker("fail", plain)} fail`, "fail") };
24
+ };
25
+ const paragraph = (text: string, o: TextOptions, toneName?: Tone, indent = "") => formatParagraph(toneName === "ok" || toneName === "warn" || toneName === "fail" ? `${marker(toneName, { ...o, color: false })} ${text}` : text, o, toneName, indent);
22
26
  const homeLine = (r: StatusResult, o: TextOptions) => `${heading(`vmem ${r.version}`, o)} home ${clean(r.home)} (${r.source})`;
23
27
  const NO_VAULTS = "no vaults registered; add one with vmem vaults add <id> <absolute-path> --kind personal|org --write mcp|cli|none";
24
28
 
25
29
  export function renderStatus(r: StatusResult, o: TextOptions): string {
26
- const title = `${homeLine(r, o)} ${r.healthy ? paint("healthy", "ok", o) : paint("unhealthy", "fail", o)}`;
30
+ const { OK, FAIL } = statuses(o);
31
+ const title = `${homeLine(r, o)} ${status(r.healthy ? "ok" : "fail", r.healthy ? "healthy" : "unhealthy", o)}`;
27
32
  const vaults = r.vaults.length ? table(["VAULT", "KIND", "WRITE", "PII", "HEALTH", "PATH"], r.vaults.map(v => [v.id, v.kind, v.write, v.pii, v.healthy ? OK : FAIL, v.path]), o) : paragraph(NO_VAULTS, o);
28
33
  const issues = r.vaults.filter(v => v.issue).map(v => paragraph(`${v.id}: ${v.issue}`, o, "fail")).join("\n");
29
34
  const specs = r.specs?.length ? table(["SOURCE", "WRITE", "PII", "PATH"], r.specs.map(s => [s.id, s.write, s.pii, s.path]), o) : undefined;
@@ -35,6 +40,7 @@ function tidyFinding(t: NonNullable<VaultRow["tidy"]>): string {
35
40
  return [`${plural(t.notes, "note")} to migrate${pending ? ` (${pending})` : ""}`, t.unparsable.length ? `${plural(t.unparsable.length, "unparsable note")} skipped` : ""].filter(Boolean).join("; ");
36
41
  }
37
42
  export function renderDoctor(r: StatusResult, o: TextOptions): string {
43
+ const { OK, WARN, FAIL } = statuses(o);
38
44
  let failed = 0;
39
45
  const vaults = r.vaults.map(v => {
40
46
  const rows: CellInput[][] = [[v.healthy ? OK : FAIL, "path", v.healthy ? v.path : `${v.path}: ${v.issue ?? "unavailable"}`]];
package/src/cli.ts CHANGED
@@ -1,10 +1,13 @@
1
1
  import { runBriefCommand } from "./vault-brief.ts";
2
+ import { runProposalCommand } from "./proposal-commands.ts";
2
3
  import { runSpecCommand, specTools } from "./mcp-spec.ts";
3
4
  import { tidyVault, TIDY_RULES } from "./tidy.ts";
4
5
  import { originCheck } from "./sync.ts";
5
6
  import { registryIds } from "./vault-log.ts";
6
7
  import { runAnalysisCommand } from "./analysis-commands.ts";
7
8
  import { runLogCommand } from "./log-commands.ts";
9
+ import { runAssertCommand } from "./assert-command.ts";
10
+ import { runAssertionsCommand } from "./assertions-command.ts";
8
11
  import { runOrgCommand } from "./org-commands.ts";
9
12
  import { isWriteCommand, runWriteCommand } from "./write-commands.ts";
10
13
  import { isReadCommand, runReadCommand } from "./read-commands.ts";
@@ -17,17 +20,17 @@ import { resolveHome } from "./home.ts";
17
20
  import { addVault, addSpec, removeSpec, specStatus, effectivePii, loadRegistry, recoverRegistry, registryStatus, removeVault, setVaultPii } from "./registry.ts";
18
21
  import { piiPolicy } from "./pii.ts";
19
22
  import { vaultStats } from "./vault-stats.ts";
20
- import { PLAIN, shellWord, takeColorFlag, textOptions, type TextOptions } from "./text-output.ts";
23
+ import { PLAIN, UsageError, errorLine, shellWord, takeColorFlag, textOptions, type TextOptions } from "./text-output.ts";
21
24
  import { renderDoctor, renderManifest, renderRecover, renderRemove, renderSetup, renderSpecAdd, renderSpecsList, renderStats, renderStatus, renderVaultAdd, renderVaultPii, renderVaultsList, type StatusResult } from "./cli-output.ts";
22
25
  function parse(args: string[], allowed: string[], values: string[]) {
23
26
  const flags: Record<string, string | boolean> = {}, positional: string[] = [];
24
27
  for (let i = 0; i < args.length; i++) {
25
28
  const word = args[i]!;
26
29
  if (!word.startsWith("-")) { positional.push(word); continue; }
27
- if (!allowed.includes(word) || word in flags) throw new Error(`unknown or repeated option: ${word}`);
30
+ if (!allowed.includes(word) || word in flags) throw new UsageError(`unknown or repeated option: ${word}`);
28
31
  if (values.includes(word)) {
29
32
  const value = args[++i];
30
- if (!value || value.startsWith("--")) throw new Error(`${word}: value required`);
33
+ if (!value || value.startsWith("--")) throw new UsageError(`${word}: value required`);
31
34
  flags[word] = value;
32
35
  } else flags[word] = true;
33
36
  }
@@ -38,7 +41,7 @@ function commandHelp(args: string[], o: TextOptions): string | undefined {
38
41
  if (args[0] === "help" && args.length > 1) {
39
42
  const name = args.slice(1).join(" ");
40
43
  const text = commandUsage(name, o);
41
- if (!text) throw new Error(`help: unknown command ${name}; run vmem help for the command list`);
44
+ if (!text) throw new UsageError(`help: unknown command ${name}; run vmem help for the command list`);
42
45
  return text;
43
46
  }
44
47
  if (args.includes("--")) return undefined;
@@ -61,7 +64,7 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
61
64
  if (args.length === 1 && args[0] === "--version") return { text: version, code: 0 };
62
65
  if (args[0] === "manifest") {
63
66
  const { flags, positional } = parse(args.slice(1), ["--json"], []);
64
- if (positional.length) throw new Error("manifest: unexpected arguments");
67
+ if (positional.length) throw new UsageError("manifest: unexpected arguments");
65
68
  // Read-only tools are published as { name, readOnly: true } so installers can approve them without a hard-coded list.
66
69
  const readOnly = new Set([...vaultTools([]), ...specTools()].filter(t => t.annotations.readOnlyHint).map(t => t.name));
67
70
  const tools = VMEM_TOOL_NAMES.map(name => readOnly.has(name) ? { name, readOnly: true } : name);
@@ -70,20 +73,23 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
70
73
  }
71
74
  if (args[0] === "setup") {
72
75
  const { flags, positional } = parse(args.slice(1), ["--apply", "--undo", "--json", "--root"], ["--root"]);
73
- if (positional.length !== 1 || (flags["--apply"] && flags["--undo"])) throw new Error("setup: requires one target and at most one of --apply/--undo");
76
+ if (positional.length !== 1 || (flags["--apply"] && flags["--undo"])) throw new UsageError("setup: requires one target and at most one of --apply/--undo");
74
77
  const mode: SetupMode = flags["--apply"] ? "apply" : flags["--undo"] ? "undo" : "dry-run";
75
78
  const report = runSetup(positional[0]!, mode, { home: resolveHome(env).home, env, ...(typeof flags["--root"] === "string" ? { root: flags["--root"] } : {}) });
76
79
  const apply = ["vmem", "setup", positional[0]!, "--apply", ...(typeof flags["--root"] === "string" ? ["--root", flags["--root"]] : [])].map(shellWord).join(" ");
77
80
  return { text: flags["--json"] ? JSON.stringify(report) : renderSetup(report, text, apply), code: [...report.actions, report.console].some(a => a?.change === "refused") ? 1 : 0 };
78
81
  }
79
82
  if (args[0] === "completion") {
80
- if (args.length !== 2) throw new Error("completion: requires bash, zsh or fish");
83
+ if (args.length !== 2) throw new UsageError("completion: requires bash, zsh or fish");
81
84
  return { text: completionScript(args[1]!).trimEnd(), code: 0 };
82
85
  }
83
86
  if (args[0] === "spec") return runSpecCommand(args.slice(1), env, text);
87
+ if (args[0] === "proposal") return runProposalCommand(args.slice(1), resolveHome(env).home, env, text);
84
88
  if (args[0] === "lint" || args[0] === "graph") return runAnalysisCommand(args[0],args.slice(1),resolveHome(env).home,env,text);
85
89
  if (args[0] === "promote" || args[0] === "sync") return runOrgCommand(args[0], args.slice(1), resolveHome(env).home, env, text);
86
90
  if (args[0] === "log") return runLogCommand(args.slice(1), resolveHome(env).home, env, text);
91
+ if (args[0] === "assertions") return runAssertionsCommand(args.slice(1), resolveHome(env).home, env, text);
92
+ if (args[0] === "assert") return runAssertCommand(args.slice(1), resolveHome(env).home, env, text);
87
93
  if (isWriteCommand(args[0]!)) return runWriteCommand(args[0]!, args.slice(1), resolveHome(env).home, env, text);
88
94
  if (args[0] === "brief") return runBriefCommand(args.slice(1), resolveHome(env).home);
89
95
  if (isReadCommand(args[0]!)) return runReadCommand(args[0]!, args.slice(1), resolveHome(env).home, text);
@@ -96,7 +102,7 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
96
102
  let result: unknown, code = 0, render: () => string;
97
103
  switch (command) {
98
104
  case "status": case "doctor": {
99
- if (positional.length) throw new Error(`${command}: unexpected arguments`);
105
+ if (positional.length) throw new UsageError(`${command}: unexpected arguments`);
100
106
  const config = loadRegistry(home.home);
101
107
  const vaults = registryStatus(home.home).map(vault => {
102
108
  if (command !== "doctor" || !vault.healthy) return { ...vault, checks: undefined };
@@ -134,29 +140,29 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
134
140
  break;
135
141
  }
136
142
  case "stats": {
137
- if (positional.length !== 1) throw new Error("stats: requires one vault id; use vmem stats <vault> [--days 1..3650]");
143
+ if (positional.length !== 1) throw new UsageError("stats: requires one vault id; use vmem stats <vault> [--days 1..3650]");
138
144
  const days = flags["--days"];
139
- if (days !== undefined && !/^[0-9]+$/.test(String(days))) throw new Error("stats: --days expects an integer 1..3650; omit it for the 30-day default");
145
+ if (days !== undefined && !/^[0-9]+$/.test(String(days))) throw new UsageError("stats: --days expects an integer 1..3650; omit it for the 30-day default");
140
146
  const stats = vaultStats(home.home, positional[0]!, days === undefined ? {} : { days: Number(days) });
141
147
  result = stats; render = () => renderStats(stats, text);
142
148
  if (stats.log.issues.length) code = 1;
143
149
  break;
144
150
  }
145
151
  case "recover": {
146
- if (positional.length) throw new Error("recover: unexpected arguments");
152
+ if (positional.length) throw new UsageError("recover: unexpected arguments");
147
153
  const report = recoverRegistry(home.home, flags["--confirm"] === true);
148
154
  result = report; render = () => renderRecover(report, text);
149
155
  if (report.blocked) code = 1;
150
156
  break;
151
157
  }
152
158
  case "specs list": {
153
- if (positional.length) throw new Error("specs list: unexpected targets; use vmem specs list [--json]");
159
+ if (positional.length) throw new UsageError("specs list: unexpected targets; use vmem specs list [--json]");
154
160
  const specs = loadRegistry(home.home).specs ?? [];
155
161
  result = specs; render = () => renderSpecsList(specs, text);
156
162
  break;
157
163
  }
158
164
  case "specs add": {
159
- if (positional.length !== 2) throw new Error("specs add: requires id and absolute repository root; use vmem specs add <id> <absolute-path> [--write mcp|cli|none] [--pii allow|deny]");
165
+ if (positional.length !== 2) throw new UsageError("specs add: requires id and absolute repository root; use vmem specs add <id> <absolute-path> [--write mcp|cli|none] [--pii allow|deny]");
160
166
  const value: Record<string, unknown> = { id: positional[0], path: positional[1] };
161
167
  for (const option of options) if (flags[option] !== undefined) value[option.slice(2)] = flags[option];
162
168
  const added = { applied: true, spec: addSpec(home.home, value, env) };
@@ -164,19 +170,19 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
164
170
  break;
165
171
  }
166
172
  case "specs remove": {
167
- if (positional.length !== 1) throw new Error("specs remove: requires one id; use vmem specs list, then vmem specs remove <id> [--confirm]");
173
+ if (positional.length !== 1) throw new UsageError("specs remove: requires one id; use vmem specs list, then vmem specs remove <id> [--confirm]");
168
174
  const removed = removeSpec(home.home, positional[0]!, flags["--confirm"] === true);
169
175
  result = removed; render = () => renderRemove("specs", removed, text);
170
176
  break;
171
177
  }
172
178
  case "vaults list": {
173
- if (positional.length) throw new Error("vaults list: unexpected arguments");
179
+ if (positional.length) throw new UsageError("vaults list: unexpected arguments");
174
180
  const vaults = loadRegistry(home.home).vaults.map(v => ({ ...v, domains: effectiveDomains(v), pii: effectivePii(v), piiPolicy: piiPolicy(v) }));
175
181
  result = vaults; render = () => renderVaultsList(vaults, text);
176
182
  break;
177
183
  }
178
184
  case "vaults add": {
179
- if (positional.length !== 2) throw new Error("vaults add: requires id and absolute path");
185
+ if (positional.length !== 2) throw new UsageError("vaults add: requires id and absolute path");
180
186
  const value: Record<string, unknown> = { id: positional[0], path: positional[1] };
181
187
  for (const option of options) if (flags[option] !== undefined) value[option.slice(2)] = flags[option];
182
188
  const added = { applied: true, vault: addVault(home.home, value) };
@@ -184,23 +190,23 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
184
190
  break;
185
191
  }
186
192
  case "vaults pii": {
187
- if (positional.length !== 1) throw new Error("vaults pii: requires id");
193
+ if (positional.length !== 1) throw new UsageError("vaults pii: requires id");
188
194
  const raw = flags["--set"];
189
- if (raw === undefined && flags["--confirm"] === true) throw new Error("vaults pii: --confirm requires --set");
195
+ if (raw === undefined && flags["--confirm"] === true) throw new UsageError("vaults pii: --confirm requires --set");
190
196
  let value: unknown;
191
- if (typeof raw === "string") { if (raw === "allow" || raw === "deny") value = raw; else { try { value = JSON.parse(raw); } catch { throw new Error("vaults pii: --set expects allow, deny or a JSON policy object"); } } }
197
+ if (typeof raw === "string") { if (raw === "allow" || raw === "deny") value = raw; else { try { value = JSON.parse(raw); } catch { throw new UsageError("vaults pii: --set expects allow, deny or a JSON policy object"); } } }
192
198
  const pii = setVaultPii(home.home, positional[0]!, value, flags["--confirm"] === true);
193
199
  const confirm = typeof raw === "string" ? ["vmem", "vaults", "pii", positional[0]!, "--set", raw, "--confirm"].map(shellWord).join(" ") : undefined;
194
200
  result = pii; render = () => renderVaultPii(pii, text, confirm);
195
201
  break;
196
202
  }
197
203
  case "vaults remove": {
198
- if (positional.length !== 1) throw new Error("vaults remove: requires id");
204
+ if (positional.length !== 1) throw new UsageError("vaults remove: requires id");
199
205
  const removed = removeVault(home.home, positional[0]!, flags["--confirm"] === true);
200
206
  result = removed; render = () => renderRemove("vaults", removed, text);
201
207
  break;
202
208
  }
203
- default: throw new Error(`unknown command: ${command}; use --help`);
209
+ default: throw new UsageError(`unknown command: ${command}; use --help`);
204
210
  }
205
211
  return { text: flags["--json"] ? JSON.stringify(result) : render(), code };
206
212
  }
@@ -231,9 +237,24 @@ export async function runAsync(argv: string[], env: NodeJS.ProcessEnv = process.
231
237
  }
232
238
  export async function mainAsync(args: string[]): Promise<number> {
233
239
  try { const output = await runAsync(args, process.env, { stdinIsTTY: process.stdin.isTTY === true, stdout: process.stdout }); console.log(output.text); return output.code; }
234
- catch (error) { console.error(`vmem: ${error instanceof Error ? error.message : "operation failed"}`); return 1; }
240
+ catch (error) { return reportError(error, args); }
235
241
  }
236
242
  export function main(args: string[]): number {
237
243
  try { const output = run(args, process.env, process.stdout); console.log(output.text); return output.code; }
238
- catch (error) { console.error(`vmem: ${error instanceof Error ? error.message : "operation failed"}`); return 1; }
244
+ catch (error) { return reportError(error, args); }
245
+ }
246
+
247
+ export function reportError(error: unknown, args: string[]): number {
248
+ let color: string | undefined;
249
+ try { color = takeColorFlag(args).color; } catch { color = "never"; }
250
+ let options: TextOptions;
251
+ try { options = textOptions(color, process.env, process.stderr); } catch { options = PLAIN; }
252
+ console.error(errorLine(error instanceof Error ? error.message : "operation failed", options, process.stderr.isTTY === true));
253
+ if (!(error instanceof UsageError)) return 1;
254
+ let words = args;
255
+ try { words = takeColorFlag(args).args; } catch { /* invalid color still receives a general usage */ }
256
+ const entry = [...COMMANDS].sort((a, b) => b.name.length - a.name.length).find(item => item.name.split(" ").every((word, i) => words[i] === word));
257
+ console.error(`Usage: vmem ${entry?.usage ?? "<command> [args]"}`);
258
+ console.error(`Run 'vmem help${entry ? ` ${entry.name}` : ""}' for details.`);
259
+ return 2;
239
260
  }
@@ -16,16 +16,29 @@ export const HELP_SECTIONS = ["Registry", "Read", "Write", "Log", "Analysis", "P
16
16
  interface CommandEntry { name: string; usage: string; mutates: boolean | string; section: typeof HELP_SECTIONS[number]; description: string }
17
17
  export const COMMANDS = [
18
18
  ...SPEC_COMMANDS.map(item => ({ name: `spec ${item.command}`, usage: item.usage, mutates: ["create", "update", "delete"].includes(item.command), section: "Design specs" as const, description: SPEC_HELP[item.command] })),
19
+ { name: "proposal submit", usage: "proposal submit <vault> <file|-> [--agent-label TEXT] [--json]", mutates: true, section: "Write", description: "screen and save one create or exact-patch proposal from JSON" },
20
+ { name: "proposal list", usage: "proposal list <vault> [--state STATE] [--limit 1..100] [--after ID] [--json]", mutates: false, section: "Read", description: "list screened proposal summaries, pending by default" },
21
+ { name: "proposal show", usage: "proposal show <vault> <id> [--offset N] [--max-bytes 1..16384] [--json]", mutates: false, section: "Read", description: "read a screened proposal operation in bounded pages" },
22
+ { name: "proposal apply", usage: "proposal apply <vault> <id> [--confirm --fingerprint SHA] [--json]", mutates: "confirm", section: "Write", description: "preview or confirm a proposal using the current writer plan" },
23
+ { name: "proposal reject", usage: "proposal reject <vault> <id> --reason TEXT [--confirm --fingerprint SHA] [--json]", mutates: "confirm", section: "Write", description: "preview or confirm a rejection without changing the vault" },
24
+ { name: "proposal reconcile", usage: "proposal reconcile <vault> <id> [--confirm --fingerprint SHA] [--json]", mutates: "confirm", section: "Write", description: "preview or confirm receipt-backed reconciliation of an uncertain apply" },
19
25
  { name: "lint", usage: "lint <vault> [--note PATH] [--write] [--dry-run] [--json]", mutates: "write", section: "Analysis", description: "lint links, schema, filenames and the log; --write saves a screened report" },
20
26
  { name: "graph build", usage: "graph build <vault> [--workspace] [--dry-run] [--json]", mutates: true, section: "Analysis", description: "build the vault graph, or the workspace graph with --workspace, under reports/" },
21
27
  { name: "graph neighbors", usage: "graph neighbors <vault> <stem> [--hops 1..2] [--limit 1..500] [--relation REL] [--json]", mutates: false, section: "Analysis", description: "read a note's graph neighborhood up to two hops, optionally over one link relation" },
22
28
  { name: "graph path", usage: "graph path <vault> <from> <to> [--max-hops 1..6] [--relation REL] [--via-hubs] [--json]", mutates: false, section: "Analysis", description: "read the shortest link path between two notes, skipping MOC/bu hubs unless --via-hubs" },
29
+ { name: "graph explain", usage: "graph explain <vault> <from> <to> [--max-hops 1..6] [--relation REL] [--via-hubs] [--json]", mutates: false, section: "Analysis", description: "explain each hop of the shortest path by its source link occurrences; structural only" },
23
30
  { name: "skills mine", usage: "skills mine <vault> [--days N] [--project KEY|--all-projects] [--vocab DIR] [--skills DIR] [--min-size N] [--min-novelty X] [--json]", mutates: false, section: "Analysis", description: "rank repeated work patterns in agent memory as new-skill candidates" },
24
31
  { name: "rebuild", usage: "rebuild <vault> [--json]", mutates: "cache", section: "Read", description: "rebuild the derived search index from the vault files" },
25
32
  { name: "brief", usage: "brief <vault> --for INTENT [--paths PATH]... [--bytes 256..4096] [--json]", mutates: "cache", section: "Read", description: "rank screened note pointers and one-hop neighbors within a byte cap" },
26
33
  { name: "search", usage: "search <vault> <query> [--type TYPE] [--domain DOMAIN] [--limit 1..500] [--json]", mutates: "cache", section: "Read", description: "full-text search notes, optionally by type and domain" },
27
- { name: "show", usage: "show <vault> <target> [--section TEXT] [--offset 0..2097152] [--max-bytes 1..65536] [--json]", mutates: "cache", section: "Read", description: "print a note's fields and body, paged by section, offset and size" },
34
+ { name: "show", usage: "show <vault> <target> [--revision OID] [--section TEXT] [--offset 0..2097152] [--max-bytes 1..65536] [--json]", mutates: "cache", section: "Read", description: "print a note's fields and body, paged by section, offset and size, or one historical Git blob with --revision" },
35
+ { name: "assertions", usage: "assertions <vault> [--subject S] [--relation R] [--at DATE] [--as-of INSTANT|DATE] [--history] [--limit N] [--cursor C] [--json]", mutates: false, section: "Read", description: "read verified temporal assertions with current policy and bounded pages" },
36
+ { name: "assertions purge", usage: "assertions purge <vault> <assertion-id> --reason TEXT [--confirm --fingerprint SHA] [--json]", mutates: "confirm", section: "Write", description: "preview, then confirm with the fingerprint, removal of one assertion's payloads from the journal" },
37
+ { name: "assertions exposure", usage: "assertions exposure <vault> [<assertion-id>] [--replace-file PATH] [--json]", mutates: false, section: "Read", description: "report purged payloads still reachable in Git history, and write a git-filter-repo replace file on request" },
38
+ { name: "evidence", usage: "evidence <vault> <note> [--json]", mutates: false, section: "Read", description: "verify a note's evidence quotes against same-vault source notes; read-only, no cache" },
28
39
  { name: "links", usage: "links <vault> <target> [--limit 1..500] [--json]", mutates: "cache", section: "Read", description: "list a note's outgoing, dead and incoming links" },
40
+ { name: "history", usage: "history <vault> <note> [--limit 1..100] [--cursor C] [--json]", mutates: false, section: "Read", description: "list one note path's Git snapshot revisions newest first, pinned to the HEAD the page started from" },
41
+ { name: "changes", usage: "changes <vault> --from OID --to OID [--limit 1..500] [--cursor C] [--json]", mutates: false, section: "Read", description: "compare two pinned Git snapshots over notes/ with before/after blob ids and status" },
29
42
  { name: "status", usage: "status [--json]", mutates: false, section: "Registry", description: "show the home, registered vaults and spec sources, and vault health" },
30
43
  { name: "doctor", usage: "doctor [--json]", mutates: false, section: "Registry", description: "check vault paths, remotes, project registries, pending tidy and spec sources; exits 1 when unhealthy" },
31
44
  { name: "recover", usage: "recover [--confirm] [--json]", mutates: "confirm", section: "Registry", description: "preview, then remove with --confirm, a stale registry lock and leftover temporary files" },
@@ -47,6 +60,7 @@ export const COMMANDS = [
47
60
  { name: "delete", usage: "delete <vault> <note> [--confirm --fingerprint SHA] [--log JSON] [--dry-run] [--json]", mutates: "confirm", section: "Write", description: "preview backlinks, then confirm with the fingerprint, a note deletion" },
48
61
  { name: "tidy", usage: "tidy <vault> [--connections] [--escapes] [--enums] [--keys] [--sources] [--topics] [--secrets] [--log] [--all] [--map file] [--confirm --fingerprint SHA] [--dry-run] [--json]", mutates: "confirm", section: "Write", description: "preview, then confirm with the fingerprint, migration tidy of notes and the log" },
49
62
  { name: "report", usage: "report <vault> <reports/path|ops/path> --body file|- [--log JSON] [--dry-run] [--json]", mutates: true, section: "Write", description: "write a screened file under reports/ or ops/" },
63
+ { name: "assert", usage: "assert <vault> --batch FILE|- [--dry-run] [--log JSON] [--json]", mutates: true, section: "Write", description: "append a validated batch of temporal assertions to the vault's assertions/ journal; writes no note" },
50
64
  { name: "check", usage: "check <vault> <file|-> [--path stem] [--json]", mutates: false, section: "Read", description: "validate a note file or stdin without writing it" },
51
65
  { name: "log tail", usage: "log tail <vault> [--limit 1..200] [--type TYPE] [--json]", mutates: false, section: "Log", description: "print the latest log events" },
52
66
  { name: "log grep", usage: "log grep <vault> <pattern> [--limit 1..200] [--type TYPE] [--json]", mutates: false, section: "Log", description: "search log events by pattern" },
@@ -102,7 +116,7 @@ export function completionScript(shell: string): string {
102
116
  cur="\${COMP_WORDS[COMP_CWORD]}"
103
117
  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W ${quote(top.join(" "))} -- "$cur")); return; fi
104
118
  key="\${COMP_WORDS[1]}"
105
- case "$key" in spec) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W '${SPEC_COMMANDS.map(item => item.command).join(" ")}' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors path' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; skills) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'mine' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; specs) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'list add remove' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; vaults|log) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W "$( [ "$key" = vaults ] && echo 'list add remove' || echo 'tail grep append')" -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; esac
119
+ case "$key" in spec) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W '${SPEC_COMMANDS.map(item => item.command).join(" ")}' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors path explain' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; skills) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'mine' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; specs) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'list add remove' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; vaults|log) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W "$( [ "$key" = vaults ] && echo 'list add remove' || echo 'tail grep append')" -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; esac
106
120
  case "$key" in
107
121
  ${cases.join("\n")}
108
122
  *) words='' ;;
@@ -0,0 +1,222 @@
1
+ import { createHash } from "node:crypto";
2
+ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync } from "node:fs";
3
+ import { join, resolve, sep } from "node:path";
4
+ import type { VaultSpec } from "./config.ts";
5
+ import { parseFrontmatter } from "./frontmatter.ts";
6
+ import { canonicalPath, isDenied } from "./platform.ts";
7
+ import { sourceReferences, sourceWorkspaceRoot, type SourceReference } from "./source.ts";
8
+ import { MAX_NOTE_BYTES, h2Sections } from "./vault-index.ts";
9
+
10
+ /** Version-1 evidence entry: quoted bytes that occur in one version of one source. Not a claim of truth. */
11
+ export interface EvidenceEntry { source: string; sha256: string; quote: string; section?: string }
12
+ export const EVIDENCE_SCHEMA_VERSION = 1;
13
+ export const MAX_EVIDENCE_ENTRIES = 16, MAX_EVIDENCE_BYTES = 16 * 1024, MAX_QUOTE_BYTES = 2048, MAX_SECTION_BYTES = 1024;
14
+ export type EvidenceStatus = "verified" | "stale" | "missing" | "ambiguous" | "unverified_external" | "unsupported";
15
+ export type EvidenceReason = "sha_mismatch" | "source_not_found" | "quote_not_found" | "section_not_found" | "section_ambiguous" | "quote_ambiguous"
16
+ | "outside_vault" | "denied" | "oversized" | "invalid_utf8" | "not_a_file" | "unresolved_source_root" | "invalid_metadata" | "external_reference" | "read_budget";
17
+ export interface EvidenceResult {
18
+ index: number;
19
+ source: string | null;
20
+ kind: SourceReference["kind"] | null;
21
+ section?: string;
22
+ expectedSha256: string | null;
23
+ observedSha256?: string;
24
+ status: EvidenceStatus;
25
+ reason?: EvidenceReason;
26
+ /** Zero-based UTF-8 byte offsets of the single match in the full source file. */
27
+ match?: { start: number; end: number };
28
+ matches?: number;
29
+ }
30
+ export interface EvidenceReport {
31
+ schemaVersion: 1;
32
+ vault: string;
33
+ note: { path: string; sha256: string };
34
+ evidence: EvidenceResult[];
35
+ truncated: false;
36
+ }
37
+
38
+ const KEYS = new Set(["source", "sha256", "quote", "section"]);
39
+ const sha256 = (data: Buffer | string) => createHash("sha256").update(data).digest("hex");
40
+ const bytes = (text: string) => Buffer.byteLength(text);
41
+
42
+ /** One entry's problem, or the entry. `sources` are the note's normalized source references. */
43
+ function entryProblem(value: unknown, sources: Set<string>): string | EvidenceEntry {
44
+ if (!value || typeof value !== "object" || Array.isArray(value)) return "entry must be an object";
45
+ const entry = value as Record<string, unknown>;
46
+ for (const key of Object.keys(entry)) if (!KEYS.has(key)) return `unknown key ${key.slice(0, 32)}`;
47
+ if (typeof entry.source !== "string") return "source must be a string";
48
+ let ref: SourceReference;
49
+ try { [ref] = sourceReferences(entry.source) as [SourceReference]; } catch { return "source must be one valid source reference"; }
50
+ if (!sources.has(ref.value)) return "source must also be listed in the note source field";
51
+ if (typeof entry.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(entry.sha256)) return "sha256 must be 64 lowercase hex characters";
52
+ if (typeof entry.quote === "string" && !entry.quote.isWellFormed()) return "quote must be well-formed Unicode (no unpaired surrogates)";
53
+ if (typeof entry.section === "string" && !entry.section.isWellFormed()) return "section must be well-formed Unicode (no unpaired surrogates)";
54
+ if (typeof entry.quote !== "string" || !entry.quote || bytes(entry.quote) > MAX_QUOTE_BYTES) return `quote must be 1..${MAX_QUOTE_BYTES} UTF-8 bytes`;
55
+ if (entry.section !== undefined && (typeof entry.section !== "string" || !entry.section.trim() || /[\r\n]/.test(entry.section) || bytes(entry.section) > MAX_SECTION_BYTES)) return `section must be one exact H2 heading <=${MAX_SECTION_BYTES} bytes`;
56
+ return { source: ref.value, sha256: entry.sha256, quote: entry.quote, ...(entry.section !== undefined ? { section: entry.section as string } : {}) };
57
+ }
58
+ function noteSources(source: unknown): Set<string> {
59
+ try { return new Set(source === undefined ? [] : sourceReferences(source).map(ref => ref.value)); } catch { return new Set(); }
60
+ }
61
+ /** The first schema problem of an `evidence` field, or undefined when valid. Used by write validation. */
62
+ export function evidenceProblem(value: unknown, source: unknown): string | undefined {
63
+ if (!Array.isArray(value) || value.length < 1 || value.length > MAX_EVIDENCE_ENTRIES) return `evidence must be a list of 1..${MAX_EVIDENCE_ENTRIES} entries`;
64
+ if (bytes(JSON.stringify(value)) > MAX_EVIDENCE_BYTES) return `evidence must serialize to at most ${MAX_EVIDENCE_BYTES} bytes`;
65
+ const sources = noteSources(source);
66
+ for (const [index, item] of value.entries()) {
67
+ const found = entryProblem(item, sources);
68
+ if (typeof found === "string") return `evidence[${index}]: ${found}`;
69
+ }
70
+ return undefined;
71
+ }
72
+ /** Parse evidence leniently: valid entries, or the problem per entry. A non-list or oversized field is one problem. */
73
+ export function parseEvidence(value: unknown, source: unknown): { entries: (EvidenceEntry | { problem: string })[]; problem?: string } {
74
+ if (value === undefined) return { entries: [] };
75
+ if (!Array.isArray(value) || value.length < 1 || value.length > MAX_EVIDENCE_ENTRIES || bytes(JSON.stringify(value)) > MAX_EVIDENCE_BYTES)
76
+ return { entries: [], problem: `evidence must be a list of 1..${MAX_EVIDENCE_ENTRIES} entries within ${MAX_EVIDENCE_BYTES} bytes` };
77
+ const sources = noteSources(source);
78
+ return { entries: value.map(item => { const found = entryProblem(item, sources); return typeof found === "string" ? { problem: found } : found; }) };
79
+ }
80
+
81
+ /** Read a plain file without following a final symlink, refusing over the note bound. */
82
+ export interface EvidenceReadBudget { remainingBytes: number; remainingFiles: number }
83
+ function boundedRead(file: string, budget?: EvidenceReadBudget): Buffer | "not_a_file" | "oversized" | "read_budget" {
84
+ if (budget && budget.remainingBytes <= 0) return "read_budget";
85
+ const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
86
+ try {
87
+ const stat = fstatSync(fd);
88
+ if (!stat.isFile()) return "not_a_file";
89
+ if (stat.size > MAX_NOTE_BYTES) return "oversized";
90
+ if (budget && stat.size > budget.remainingBytes) return "read_budget";
91
+ if (budget) budget.remainingBytes -= stat.size;
92
+ const buffer = Buffer.alloc(stat.size); let read = 0;
93
+ while (read < stat.size) { const n = readSync(fd, buffer, read, stat.size - read, null); if (!n) break; read += n; }
94
+ if (fstatSync(fd).size !== stat.size) return "oversized";
95
+ return buffer.subarray(0, read);
96
+ } finally { closeSync(fd); }
97
+ }
98
+ const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
99
+
100
+ /** Resolve a workspace-relative path reference to a flat `notes/*.md` of `vault`, or the reason it is not one. */
101
+ type Resolved = { ok: true; path: string } | { ok: false; reason: EvidenceReason };
102
+ function resolveVaultNote(vault: VaultSpec, root: string, value: string, denyPaths: readonly string[]): Resolved {
103
+ const lexical = resolve(root, value);
104
+ if (isDenied(canonicalPath(lexical), [...denyPaths]) || isDenied(value, [...denyPaths])) return { ok: false, reason: "denied" };
105
+ let real: string, vaultReal: string;
106
+ try { vaultReal = realpathSync(vault.path); } catch { return { ok: false, reason: "source_not_found" }; }
107
+ try { real = realpathSync(lexical); } catch { return { ok: false, reason: "source_not_found" }; }
108
+ const notes = join(vaultReal, "notes") + sep;
109
+ if (!real.startsWith(notes) || real.slice(notes.length).includes(sep) || !/^[^/\\]+\.md$/.test(real.slice(notes.length))) return { ok: false, reason: "outside_vault" };
110
+ if (isDenied(real, [...denyPaths])) return { ok: false, reason: "denied" };
111
+ try { if (lstatSync(real).isSymbolicLink()) return { ok: false, reason: "outside_vault" }; } catch { return { ok: false, reason: "source_not_found" }; }
112
+ return { ok: true, path: real };
113
+ }
114
+ /** Literal occurrence count (overlapping) and the first index, capped at two. */
115
+ function occurrences(haystack: string, needle: string): { count: number; first: number } {
116
+ const first = haystack.indexOf(needle);
117
+ if (first < 0) return { count: 0, first };
118
+ return { count: haystack.indexOf(needle, first + 1) < 0 ? 1 : 2, first };
119
+ }
120
+
121
+ /** Verify one parsed entry. Every call reads the source afresh; nothing is cached. */
122
+ /** Per-run read memo keyed by resolved real path. Callers create one per run; it is never kept across calls. */
123
+ export type EvidenceReads = Map<string, ReturnType<typeof boundedRead>>;
124
+ export function verifyEvidenceEntry(vault: VaultSpec, entry: EvidenceEntry, index: number, denyPaths: readonly string[] = [], reads?: EvidenceReads, budget?: EvidenceReadBudget): EvidenceResult {
125
+ const ref = sourceReferences(entry.source)[0]!;
126
+ const base: EvidenceResult = { index, source: ref.value, kind: ref.kind, ...(entry.section !== undefined ? { section: entry.section } : {}), expectedSha256: entry.sha256, status: "unsupported" };
127
+ if (ref.kind !== "path") return { ...base, status: "unverified_external", reason: "external_reference" };
128
+ if (budget) {
129
+ if (budget.remainingFiles <= 0 || budget.remainingBytes <= 0) return { ...base, reason: "read_budget" };
130
+ budget.remainingFiles--;
131
+ }
132
+ const root = sourceWorkspaceRoot(vault);
133
+ if (!root) return { ...base, reason: "unresolved_source_root" };
134
+ const located = resolveVaultNote(vault, root, ref.value, denyPaths);
135
+ if (!located.ok) return located.reason === "source_not_found" ? { ...base, status: "missing", reason: located.reason } : { ...base, reason: located.reason };
136
+ let data: ReturnType<typeof boundedRead>;
137
+ try {
138
+ const cached = reads?.get(located.path);
139
+ data = cached ?? boundedRead(located.path, budget);
140
+ if (!cached) reads?.set(located.path, data);
141
+ } catch { return { ...base, status: "missing", reason: "source_not_found" }; }
142
+ if (data === "not_a_file" || data === "oversized" || data === "read_budget") return { ...base, reason: data };
143
+ let text: string;
144
+ try { text = utf8.decode(data); } catch { return { ...base, reason: "invalid_utf8" }; }
145
+ const observed = sha256(data), seen = { ...base, observedSha256: observed };
146
+ let start = 0, end = text.length;
147
+ if (entry.section !== undefined) {
148
+ let body: string;
149
+ try { body = parseFrontmatter(text).body; } catch { body = text; }
150
+ const offset = text.length - body.length, found = h2Sections(body).filter(s => s.name === entry.section);
151
+ if (!found.length) return { ...seen, status: "missing", reason: "section_not_found" };
152
+ if (found.length > 1) return { ...seen, status: "ambiguous", reason: "section_ambiguous" };
153
+ start = offset + found[0]!.start; end = offset + found[0]!.end;
154
+ }
155
+ const { count, first } = occurrences(text.slice(start, end), entry.quote);
156
+ if (count === 0) return { ...seen, status: observed === entry.sha256 ? "missing" : "stale", reason: observed === entry.sha256 ? "quote_not_found" : "sha_mismatch", matches: 0 };
157
+ if (count > 1) return { ...seen, status: observed === entry.sha256 ? "ambiguous" : "stale", reason: observed === entry.sha256 ? "quote_ambiguous" : "sha_mismatch", matches: count };
158
+ const byteStart = bytes(text.slice(0, start + first)), match = { start: byteStart, end: byteStart + bytes(entry.quote) };
159
+ if (observed !== entry.sha256) return { ...seen, status: "stale", reason: "sha_mismatch", matches: 1, match };
160
+ return { ...seen, status: "verified", matches: 1, match };
161
+ }
162
+ /** Verify every evidence entry of a parsed note's frontmatter, in order. Malformed entries are `unsupported`/`invalid_metadata`. */
163
+ export function verifyNoteEvidence(vault: VaultSpec, data: Record<string, unknown>, denyPaths: readonly string[] = [], reads?: EvidenceReads): EvidenceResult[] {
164
+ const parsed = parseEvidence(data.evidence, data.source);
165
+ if (parsed.problem) return [{ index: 0, source: null, kind: null, expectedSha256: null, status: "unsupported", reason: "invalid_metadata" }];
166
+ return parsed.entries.map((entry, index) => "problem" in entry
167
+ ? { index, source: null, kind: null, expectedSha256: null, status: "unsupported", reason: "invalid_metadata" }
168
+ : verifyEvidenceEntry(vault, entry, index, denyPaths, reads));
169
+ }
170
+
171
+ /** Locate a flat note of `vault` by stem or `notes/<stem>.md` without the index, refusing links and denied paths. */
172
+ function noteFile(vault: VaultSpec, target: string, denyPaths: readonly string[]): string {
173
+ const stem = target.replace(/^notes\//, "").replace(/\.md$/, "");
174
+ if (!stem || Buffer.byteLength(stem) > 200 || /[/\\\0]/.test(stem) || stem.startsWith(".")) throw Object.assign(new Error("note: expected a flat note stem or notes/<stem>.md"), { code: "V04" });
175
+ const root = realpathSync(vault.path);
176
+ if (root !== resolve(vault.path)) throw Object.assign(new Error(`vault ${vault.id}: registered path changed; re-register it with vmem vaults add and restart the MCP server`), { code: "V04" });
177
+ const file = join(root, "notes", `${stem}.md`);
178
+ if (isDenied(file, [...denyPaths])) throw Object.assign(new Error("note: denied by the denyPaths setting or built-in secret rules; check the policy with vmem status"), { code: "V06" });
179
+ for (const part of [join(root, "notes"), file]) {
180
+ let stat;
181
+ try { stat = lstatSync(part); } catch { throw Object.assign(new Error(`note: unknown target; find the note stem with vmem search ${vault.id} <query>`), { code: "V04" }); }
182
+ if (stat.isSymbolicLink()) throw Object.assign(new Error("note: symlinked paths are refused; replace the link with the note file itself"), { code: "V04" });
183
+ }
184
+ return file;
185
+ }
186
+
187
+ /**
188
+ * Shared read provider for `vmem evidence` and `vmem_evidence`. Pass the vault spec freshly loaded from the registry:
189
+ * the source root is rebound on every call. Writes nothing, takes no lock and keeps no cache.
190
+ */
191
+ export function evidenceReport(vault: VaultSpec, target: string, denyPaths: readonly string[] = []): EvidenceReport {
192
+ const file = noteFile(vault, target, denyPaths), data = boundedRead(file);
193
+ if (typeof data === "string") throw Object.assign(new Error(`note: ${data === "oversized" ? "exceeds the 2 MiB read bound; split the note" : "not a regular file"}`), { code: "V09" });
194
+ let text: string;
195
+ try { text = utf8.decode(data); } catch { throw Object.assign(new Error(`note: not valid UTF-8; validate it with vmem check ${vault.id} <file>`), { code: "V01" }); }
196
+ let fm: Record<string, unknown>;
197
+ try { fm = parseFrontmatter(text).data; } catch { throw Object.assign(new Error(`note: frontmatter is not parseable; validate it with vmem check ${vault.id} <file>`), { code: "V01" }); }
198
+ const path = `notes/${file.slice(file.lastIndexOf(sep) + 1)}`;
199
+ return { schemaVersion: 1, vault: vault.id, note: { path, sha256: sha256(data) }, evidence: verifyNoteEvidence(vault, fm, denyPaths), truncated: false };
200
+ }
201
+
202
+ /**
203
+ * Org promotion screen: keep only entries whose source stays meaningful at `target`. URLs stay unverified external;
204
+ * memory ids and paths that do not resolve to a target-vault note are removed. Removal reasons carry no path or quote.
205
+ */
206
+ export function screenEvidenceForTarget(value: unknown, source: unknown, target: VaultSpec, denyPaths: readonly string[] = []): { kept: EvidenceEntry[] | undefined; removed: { index: number; reason: string }[] } {
207
+ if (value === undefined) return { kept: undefined, removed: [] };
208
+ const parsed = parseEvidence(value, source);
209
+ if (parsed.problem) return { kept: undefined, removed: [{ index: 0, reason: "invalid_metadata" }] };
210
+ const root = sourceWorkspaceRoot(target), kept: EvidenceEntry[] = [], removed: { index: number; reason: string }[] = [];
211
+ for (const [index, entry] of parsed.entries.entries()) {
212
+ if ("problem" in entry) { removed.push({ index, reason: "invalid_metadata" }); continue; }
213
+ const ref = sourceReferences(entry.source)[0]!;
214
+ if (ref.kind === "url") { kept.push(entry); continue; }
215
+ if (ref.kind === "memory") { removed.push({ index, reason: "memory_not_retained" }); continue; }
216
+ if (!root) { removed.push({ index, reason: "unresolved_source_root" }); continue; }
217
+ const located = resolveVaultNote(target, root, ref.value, denyPaths);
218
+ if (located.ok) kept.push(entry);
219
+ else removed.push({ index, reason: located.reason === "denied" ? "denied" : "not_in_destination" });
220
+ }
221
+ return { kept: kept.length ? kept : undefined, removed };
222
+ }