@staix/vault-mem 0.11.0 → 0.12.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 (61) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +17 -2
  3. package/bin/vmem.js +5 -1
  4. package/package.json +2 -1
  5. package/skills/_shared/vault-adapter.md +131 -0
  6. package/skills/skill-mine/SKILL.md +52 -0
  7. package/skills/skill-mine/vocab/actions.yaml +110 -0
  8. package/skills/skill-mine/vocab/objects.yaml +123 -0
  9. package/skills/vault-connect/SKILL.md +75 -0
  10. package/skills/vault-enrich/SKILL.md +31 -0
  11. package/skills/vault-extract/README.md +20 -0
  12. package/skills/vault-extract/SKILL.md +139 -0
  13. package/skills/vault-graph/SKILL.md +120 -0
  14. package/skills/vault-learn/SKILL.md +111 -0
  15. package/skills/vault-lint/README.md +32 -0
  16. package/skills/vault-lint/SKILL.md +137 -0
  17. package/skills/vault-lint/references/lint-output.md +97 -0
  18. package/skills/vault-lint/references/vault-scope-rules.md +26 -0
  19. package/skills/vault-lint/references/work-scope-checks.md +71 -0
  20. package/skills/vault-refactor/SKILL.md +112 -0
  21. package/skills/vault-remember/SKILL.md +38 -0
  22. package/skills/vault-rethink/README.md +15 -0
  23. package/skills/vault-rethink/SKILL.md +58 -0
  24. package/skills/vault-stats/SKILL.md +49 -0
  25. package/skills/vault-sync/README.md +15 -0
  26. package/skills/vault-sync/SKILL.md +195 -0
  27. package/skills/vault-sync/references/r4-method-evidence.md +12 -0
  28. package/skills/vault-update/SKILL.md +68 -0
  29. package/skills/vmem-status/SKILL.md +30 -0
  30. package/src/amem/host-api.ts +5 -1
  31. package/src/analysis-input.ts +15 -0
  32. package/src/analysis-types.ts +3 -1
  33. package/src/assertion-policy.ts +4 -2
  34. package/src/assertions.ts +48 -8
  35. package/src/cli-output.ts +10 -3
  36. package/src/cli.ts +29 -3
  37. package/src/commands-table.ts +3 -1
  38. package/src/config.ts +21 -7
  39. package/src/enrichment-query.ts +65 -0
  40. package/src/enrichment-search.ts +69 -0
  41. package/src/enrichment-store.ts +197 -0
  42. package/src/enrichment.ts +245 -0
  43. package/src/graph-evidence.ts +2 -2
  44. package/src/index.ts +9 -0
  45. package/src/mcp-vault.ts +46 -8
  46. package/src/proposal-provider.ts +3 -2
  47. package/src/proposals.ts +10 -4
  48. package/src/read-output.ts +1 -1
  49. package/src/registry.ts +57 -2
  50. package/src/setup.ts +12 -3
  51. package/src/skills-install.ts +216 -0
  52. package/src/ui/panel-types.ts +55 -0
  53. package/src/ui/panel.js +76 -0
  54. package/src/ui/plugin.ts +95 -5
  55. package/src/vault-graph.ts +15 -7
  56. package/src/vault-index.ts +17 -0
  57. package/src/vault-lint.ts +12 -4
  58. package/src/write-operations.ts +38 -1
  59. package/src/write-types.ts +1 -0
  60. package/src/write-validation.ts +2 -1
  61. package/src/writer.ts +1 -1
@@ -0,0 +1,245 @@
1
+ /** Explicit, offline enrichment work and intake. */
2
+ import { closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, readSync, realpathSync, writeFileSync } from "node:fs";
3
+ import { createHash, randomUUID } from "node:crypto";
4
+ import { join } from "node:path";
5
+ import { hostname } from "node:os";
6
+ import { cleanupOwnedFile } from "./write-files.ts";
7
+ import { applyWrite, MUTATION_LOCK } from "./writer.ts";
8
+ import { loadRegistry } from "./registry.ts";
9
+ import { logBinding, matchesBinding } from "./vault-log.ts";
10
+ import { isDenied } from "./platform.ts";
11
+ import { notePath } from "./write-operations.ts";
12
+ import { screenMetadata } from "./write-validation.ts";
13
+ import { VaultIndex, MAX_NOTE_BYTES } from "./vault-index.ts";
14
+ import { readEnrichmentStore, writeEnrichmentRecord, validateEnrichmentRecord, type EnrichmentKind, type EnrichmentProducer, type EnrichmentRecord } from "./enrichment-store.ts";
15
+ import type { VaultSpec } from "./config.ts";
16
+ import { appendAssertions, readJournal } from "./assertions.ts";
17
+ import { submitProposal, showProposal } from "./proposal-provider.ts";
18
+
19
+ const sha256 = (value: string | Uint8Array) => createHash("sha256").update(value).digest("hex");
20
+ const kinds: readonly EnrichmentKind[] = ["embedding", "summary", "community-label", "inferred-link", "fact"];
21
+ function fail(message: string): never { throw new Error(`enrichment: ${message}`); }
22
+ function context(home: string, id: string, channel?: "cli" | "mcp") {
23
+ const config = loadRegistry(home), vault = config.vaults.find(v => v.id === id);
24
+ if (!vault) return fail("vault is not registered; choose an id from vmem vaults list");
25
+ if (!vault.enrichment?.enabled) return fail("enrichment is disabled; enable it for this vault in settings");
26
+ if (channel && (vault.write === "none" || (channel === "mcp" && vault.write !== "mcp"))) return fail("vault write policy refuses this channel; change the policy in settings or use an allowed channel");
27
+ let binding: ReturnType<typeof logBinding>;
28
+ try { binding = logBinding(vault, config); } catch { return fail("vault root is unavailable; inspect the registered vault and retry"); }
29
+ const check = () => {
30
+ let current: ReturnType<typeof loadRegistry>;
31
+ try { current = loadRegistry(home); } catch { return fail("registry is unavailable after the read; inspect the configuration and retry"); }
32
+ if (!matchesBinding(current, vault.id, binding)) fail("vault binding or policy changed during the read; retry with the current registry");
33
+ };
34
+ return { config, vault, check };
35
+ }
36
+ function sourcePath(path: string): string {
37
+ if (typeof path !== "string") return fail("source path is missing; choose a note from vmem list");
38
+ const result = path.startsWith("notes/") ? path : `notes/${path.endsWith(".md") ? path : `${path}.md`}`;
39
+ if (!/^notes\/(?!\.)[^/\\\p{Cc}]+\.md$/u.test(result) || Buffer.byteLength(result) > 1024) return fail("source path is not a flat note path; choose a note from vmem list");
40
+ return result;
41
+ }
42
+ function noteBytes(vault: VaultSpec, path: string, denied: string[]): Buffer {
43
+ const normalized = sourcePath(path);
44
+ let root: string;
45
+ try { root = realpathSync(vault.path); } catch { return fail("vault root is unavailable; restore the registered vault and retry"); }
46
+ const notes = join(root, "notes"), file = join(root, normalized);
47
+ let plainNotes = false; try { plainNotes = realpathSync(notes) === notes; } catch { /* Missing notes are refused below. */ }
48
+ if (root !== vault.path || !plainNotes || isDenied(file, denied)) fail("note path is denied or vault identity changed; inspect the registered vault and policy");
49
+ let fd: number;
50
+ try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
51
+ catch { return fail("source note is unavailable or linked; inspect its path and retry"); }
52
+ try {
53
+ const before = fstatSync(fd);
54
+ if (!before.isFile() || before.size > MAX_NOTE_BYTES) fail("source note is not a bounded regular file; inspect or split the note");
55
+ const bytes = Buffer.alloc(before.size + 1); let length = 0;
56
+ while (length < bytes.length) { const n = readSync(fd, bytes, length, bytes.length - length, null); if (!n) break; length += n; }
57
+ const after = fstatSync(fd);
58
+ let named: ReturnType<typeof lstatSync>;
59
+ try { named = lstatSync(file); } catch { return fail("source note changed during read; reread it and retry"); }
60
+ if (named.isSymbolicLink() || named.dev !== after.dev || named.ino !== after.ino || length !== before.size || before.size !== after.size || before.ino !== after.ino || before.dev !== after.dev || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) fail("source note changed while reading; reread it and retry");
61
+ return bytes.subarray(0, length);
62
+ } finally { closeSync(fd); }
63
+ }
64
+ function withMutationLock<T>(vault: VaultSpec, denied: string[], work: (fd: number) => T): T {
65
+ const file = join(vault.path, MUTATION_LOCK);
66
+ if (isDenied(file, denied)) fail("vault mutation lock is denied; inspect configured deny paths");
67
+ let fd: number;
68
+ try { fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
69
+ catch { return fail("vault mutation lock is unavailable; stop concurrent writers and inspect the lock"); }
70
+ try { writeFileSync(fd, JSON.stringify({ pid: process.pid, host: hostname(), created: new Date().toISOString() }) + "\n"); fsyncSync(fd); return work(fd); }
71
+ finally { try { cleanupOwnedFile(file, fd); } finally { closeSync(fd); } }
72
+ }
73
+ export interface EnrichmentWorkRequest { vault: string; kind: EnrichmentKind; limit?: number; after?: string }
74
+ export function listEnrichmentWork(home: string, request: EnrichmentWorkRequest) {
75
+ if (!request || typeof request !== "object" || Object.keys(request).some(k => !["vault", "kind", "limit", "after"].includes(k))) fail("invalid work request; supply a vault and enrichment kind");
76
+ if (request.after !== undefined && (typeof request.after !== "string" || !/^notes\/(?!\.)[^/\\\p{Cc}]+\.md$/u.test(request.after) || Buffer.byteLength(request.after) > 1024)) fail("work cursor is invalid; restart without a cursor");
77
+ if (!kinds.includes(request.kind)) fail("unknown work kind; choose embedding, summary, community-label, inferred-link or fact");
78
+ const limit = request.limit ?? 50;
79
+ if (!Number.isInteger(limit) || limit < 1 || limit > 100) fail("work limit is outside 1..100; choose a smaller page");
80
+ const { config, vault, check } = context(home, request.vault), store = readEnrichmentStore(home, vault, config.vaults, config.denyPaths ?? []);
81
+ const index = new VaultIndex(home, vault, config.vaults.map(v => v.path), { memory: true });
82
+ try {
83
+ index.scan(false, { captureInvalidFrontmatter: true, denyPaths: config.denyPaths });
84
+ const snapshot = index.analysisSnapshot({ today: "", logPath: "", log: null, registryIds: null, reports: {} });
85
+ const records = new Map<string, EnrichmentRecord[]>();
86
+ for (const record of store.records) if (record.kind === request.kind) {
87
+ const group = records.get(record.path) ?? []; group.push(record); records.set(record.path, group);
88
+ }
89
+ const pending = snapshot.notes.map(n => {
90
+ const path = `notes/${n.path.replace(/^notes\//, "")}`, contentHash = sha256(n.source), relevant = records.get(path) ?? [];
91
+ const uncertain = relevant.some(r => (r.value as { state?: unknown } | undefined)?.state === "pending");
92
+ const current = relevant.some(r => r.contentHash === contentHash && (r.value as { state?: unknown } | undefined)?.state !== "released");
93
+ return { path, contentHash, current, ...(uncertain ? { status: "needs-reconciliation" as const } : {}) };
94
+ }).filter(n => (n.status || !n.current) && (!request.after || n.path > request.after)).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0).map(({ current: _, ...item }) => item);
95
+ const items = pending.slice(0, limit);
96
+ check();
97
+ return { vault: vault.id, kind: request.kind, items, ...(pending.length > limit ? { next: items.at(-1)!.path } : {}) };
98
+ } finally { index.close(); }
99
+ }
100
+ export interface EnrichmentIntakeRequest { vault: string; path: string; contentHash: string; kind: EnrichmentKind; producer: EnrichmentProducer; createdAt: string; value: unknown; channel: "cli" | "mcp" }
101
+ export function intakeEnrichment(home: string, request: EnrichmentIntakeRequest, options: { env?: NodeJS.ProcessEnv; expectedVault?: VaultSpec } = {}) {
102
+ if (!request || typeof request !== "object" || Object.keys(request).some(k => !["vault", "path", "contentHash", "kind", "producer", "createdAt", "value", "channel"].includes(k)) || !kinds.includes(request.kind) || (request.channel !== "cli" && request.channel !== "mcp") || typeof request.contentHash !== "string" || !/^[a-f0-9]{64}$/.test(request.contentHash)) fail("invalid intake request; supply a vault, source path, SHA-256, kind, producer, creation time and value");
103
+ const { config, vault, check } = context(home, request.vault, request.channel), path = sourcePath(request.path);
104
+ if (options.expectedVault && JSON.stringify(options.expectedVault) !== JSON.stringify(vault)) fail("vault binding changed since MCP startup; restart the MCP server");
105
+ const candidate: EnrichmentRecord = { path, contentHash: request.contentHash, kind: request.kind, producer: request.producer, createdAt: request.createdAt, value: request.value };
106
+ validateEnrichmentRecord(candidate);
107
+ const issues = screenMetadata({ producer: request.producer, ...(request.kind === "embedding" ? {} : { value: request.value }) }, { vault, config }, path);
108
+ if (issues.some(issue => issue.severity === "error")) fail("intake text is refused by the secret or PII policy; remove prohibited content or correct the vault policy");
109
+ if (sha256(noteBytes(vault, path, config.denyPaths ?? [])) !== request.contentHash) fail("source content hash is stale; reread the note and regenerate the result");
110
+ if (request.kind === "fact" || request.kind === "inferred-link") {
111
+ const bound = { vault: vault.id, path, contentHash: request.contentHash, producer: request.producer, createdAt: request.createdAt };
112
+ let operation: unknown;
113
+ const origin = { path, sha256: request.contentHash, producer: request.producer, createdAt: request.createdAt };
114
+ const checkSource = () => { if (sha256(noteBytes(vault, path, config.denyPaths ?? [])) !== request.contentHash) fail("source content hash is stale; reread the note and regenerate the result"); };
115
+ if (request.kind === "fact") {
116
+ if (!Array.isArray(request.value) || !request.value.some(op => op && typeof op === "object" && ["assert", "revise"].includes(String((op as { op?: unknown }).op)))) fail("fact intake requires assertion operations; include an assert or revise operation with evidence");
117
+ const dry = appendAssertions(home, { vault: vault.id, ops: request.value, channel: request.channel, dryRun: true }, { env: options.env, origin });
118
+ if (!dry.ok) { check(); return { ...bound, ok: false, applied: false, kind: request.kind, receipt: dry }; }
119
+ } else {
120
+ try { notePath(path); } catch { fail("proposal targets require a lowercase ASCII note name; rename the note before proposing a link"); }
121
+ const target = request.value && typeof request.value === "object" && !Array.isArray(request.value) && Object.keys(request.value).join(",") === "target" ? (request.value as { target?: unknown }).target : undefined;
122
+ if (typeof target !== "string" || !/^[a-z0-9][a-z0-9-]{0,190}$/.test(target) || `notes/${target}.md` === path) fail("inferred link target is invalid; provide a different flat note stem");
123
+ operation = { op: "infer-link", path, target, expectedSha: request.contentHash };
124
+ const dry = applyWrite(home, { vault: vault.id, operation: operation as import("./write-types.ts").WriteOp, channel: request.channel, dryRun: true }, { env: options.env });
125
+ if (!dry.ok) { check(); return { ...bound, ok: false, applied: false, kind: request.kind, receipt: dry }; }
126
+ }
127
+ // Reserve a durable intent before calling a second store. A crash or lost response can never auto-replay it.
128
+ const token = randomUUID(), pending: EnrichmentRecord = { path, contentHash: request.contentHash, kind: request.kind, producer: request.producer, createdAt: request.createdAt, value: { state: "pending", token } };
129
+ const reserved = writeEnrichmentRecord(home, vault, pending, checkSource, store => {
130
+ const previous = store.records.filter(r => r.path === path && r.kind === request.kind);
131
+ if (previous.some(r => (r.value as { state?: unknown } | undefined)?.state === "pending")) fail("a prior intake has an unresolved outcome; inspect the journal or proposals and reconcile it before retrying");
132
+ if (previous.some(r => r.contentHash === request.contentHash && (r.value as { state?: unknown } | undefined)?.state === "complete")) fail("this note version already has an intake record; inspect the existing result before retrying");
133
+ });
134
+ if (reserved.issues.length) return { ...bound, ok: false, applied: false, kind: request.kind, issues: reserved.issues, issue: "intake reservation needs inspection; inspect the sidecar before retrying" };
135
+ const releaseReservation = () => {
136
+ const released: EnrichmentRecord = { ...pending, value: { state: "released", token } };
137
+ return writeEnrichmentRecord(home, vault, released, () => {}, store => {
138
+ const prior = store.records.find(r => r.path === path && r.kind === request.kind && r.contentHash === request.contentHash)?.value as { state?: unknown; token?: unknown } | undefined;
139
+ if (prior?.state !== "pending" || prior.token !== token) fail("intake reservation changed; inspect it before retrying");
140
+ });
141
+ };
142
+ let started = false, sourceRefusal: unknown;
143
+ try {
144
+ const result = withMutationLock(vault, config.denyPaths ?? [], mutationFd => {
145
+ checkSource();
146
+ const currentConfig = loadRegistry(home), currentVault = currentConfig.vaults.find(v => v.id === vault.id);
147
+ if (!currentVault || JSON.stringify(currentVault) !== JSON.stringify(vault)) fail("vault binding changed; reload settings and retry");
148
+ const activeStore = readEnrichmentStore(home, currentVault, currentConfig.vaults, currentConfig.denyPaths ?? []);
149
+ const active = activeStore.records.find(r => r.path === path && r.kind === request.kind && r.contentHash === request.contentHash)?.value as { state?: unknown; token?: unknown } | undefined;
150
+ if (active?.state !== "pending" || active.token !== token) fail("intake reservation changed; inspect its outcome and request new work");
151
+ started = true;
152
+ const receipt = request.kind === "fact"
153
+ ? appendAssertions(home, { vault: vault.id, ops: request.value, channel: request.channel }, { env: options.env, origin: { ...origin, intakeId: token } })
154
+ : submitProposal(home, { vault: vault.id, operation, agentLabel: `enrichment:${token}` }, { channel: request.channel, env: options.env, expectedVault: options.expectedVault ?? vault, proposalId: token, validateBeforeStore: () => { try { checkSource(); } catch (error) { sourceRefusal = error; throw error; } } });
155
+ const applied = "stored" in receipt ? receipt.stored === true : receipt.applied === true;
156
+ if (!applied) return { receipt, applied: "stored" in receipt && receipt.stored === null ? null : false, trackingIssues: [] as string[] };
157
+ const complete: EnrichmentRecord = { ...pending, value: { state: "complete", token, receipt } };
158
+ try {
159
+ const stored = writeEnrichmentRecord(home, vault, complete, checkSource, store => {
160
+ const prior = store.records.find(r => r.path === path && r.kind === request.kind && r.contentHash === request.contentHash)?.value as { state?: unknown; token?: unknown } | undefined;
161
+ if (prior?.state !== "pending" || prior.token !== token) fail("intake reservation changed; inspect the journal or proposals and sidecar before retrying");
162
+ }, mutationFd);
163
+ return { receipt, applied: true, trackingIssues: stored.issues };
164
+ } catch { return { receipt, applied: true, trackingIssues: ["result was published but local intake tracking failed; inspect the journal or proposals and reconcile before retrying"] }; }
165
+ });
166
+ const { receipt, applied, trackingIssues } = result;
167
+ if (!applied) {
168
+ if (applied === false) {
169
+ try { const released = releaseReservation(); if (!released.issues.length) return { ...bound, ok: false, applied: false, kind: request.kind, receipt }; } catch { /* Keep the reservation when cleanup cannot be confirmed. */ }
170
+ }
171
+ return { ...bound, ok: false, applied, kind: request.kind, receipt, issue: "intake reservation remains unresolved; inspect the journal or proposals and reconcile before retrying" };
172
+ }
173
+ return { ...bound, ok: receipt.ok && trackingIssues.length === 0, applied: true, kind: request.kind, receipt, ...(trackingIssues.length ? { issues: trackingIssues } : {}) };
174
+ } catch (error) {
175
+ if (!started || sourceRefusal) {
176
+ try { const released = releaseReservation(); if (!released.issues.length) throw (sourceRefusal ?? error); } catch (cleanup) { if (cleanup === (sourceRefusal ?? error)) throw cleanup; }
177
+ return { ...bound, ok: false, applied: false, kind: request.kind, issue: `${error instanceof Error ? error.message : "intake failed before publication; inspect the source and retry"}; reservation cleanup failed, inspect and reconcile it before retrying` };
178
+ }
179
+ return { ...bound, ok: false, applied: null, kind: request.kind, issue: "intake outcome is uncertain; inspect the journal or proposals and reconcile before retrying" };
180
+ }
181
+ }
182
+ if (request.kind !== "embedding" && (typeof request.value !== "string" || !request.value.trim() || Buffer.byteLength(request.value) > 8192)) fail("summary or community label must be nonempty text of at most 8192 bytes; shorten the result");
183
+ const record: EnrichmentRecord = { path, contentHash: request.contentHash, kind: request.kind, producer: request.producer, createdAt: request.createdAt, value: request.value };
184
+ const stored = writeEnrichmentRecord(home, vault, record, () => {
185
+ if (sha256(noteBytes(vault, path, config.denyPaths ?? [])) !== request.contentHash) fail("source content hash is stale; reread the note and regenerate the result");
186
+ });
187
+ return { ok: stored.issues.length === 0, applied: true, vault: vault.id, path, contentHash: request.contentHash, kind: request.kind, producer: request.producer, createdAt: request.createdAt, issues: stored.issues };
188
+ }
189
+
190
+ /** Return one current record after rechecking path and disclosure policy. */
191
+ export function readEnrichment(home: string, request: { vault: string; path: string; kind: EnrichmentKind }) {
192
+ if (!request || typeof request !== "object" || Object.keys(request).some(k => !["vault", "path", "kind"].includes(k)) || !kinds.includes(request.kind)) fail("invalid record request; supply a vault, note path and enrichment kind");
193
+ const { config, vault, check } = context(home, request.vault), path = sourcePath(request.path);
194
+ const current = sha256(noteBytes(vault, path, config.denyPaths ?? []));
195
+ const store = readEnrichmentStore(home, vault, config.vaults, config.denyPaths ?? []);
196
+ const candidates = store.records.filter(r => r.path === path && r.kind === request.kind);
197
+ const uncertain = candidates.find(r => (r.value as { state?: unknown } | undefined)?.state === "pending");
198
+ if (uncertain) { check(); return { vault: vault.id, path, kind: request.kind, status: "needs-reconciliation" as const }; }
199
+ const record = candidates.find(r => r.contentHash === current) ?? candidates.at(-1);
200
+ if (!record) { check(); return { vault: vault.id, path, kind: request.kind, status: "missing" as const }; }
201
+ if (record.contentHash !== current) { check(); return { vault: vault.id, path, kind: request.kind, status: "stale" as const }; }
202
+ const issues = screenMetadata({ producer: record.producer, ...(record.kind === "embedding" ? {} : { value: record.value }) }, { vault, config }, path);
203
+ if (issues.some(issue => issue.severity === "error")) fail("current secret or PII policy refuses the stored result; inspect the vault policy");
204
+ check();
205
+ return { vault: vault.id, path, kind: request.kind, status: "current" as const, producer: record.producer, createdAt: record.createdAt, contentHash: record.contentHash, value: record.value };
206
+ }
207
+
208
+ /** Explicitly release an uncertain intake only after the caller has inspected its journal or proposal. */
209
+ export function reconcileEnrichment(home: string, request: { vault: string; path: string; kind: "fact" | "inferred-link"; resolution: "published" | "not_published"; confirm?: boolean; fingerprint?: string; channel: "cli" | "mcp" }, options: { expectedVault?: VaultSpec } = {}) {
210
+ if (!request || typeof request !== "object" || Object.keys(request).some(k => !["vault", "path", "kind", "resolution", "confirm", "fingerprint", "channel"].includes(k)) || !["fact", "inferred-link"].includes(request.kind) || !["published", "not_published"].includes(request.resolution) || !["cli", "mcp"].includes(request.channel) || (request.confirm !== undefined && typeof request.confirm !== "boolean")) fail("invalid reconciliation request; choose fact or inferred-link and preview first");
211
+ const { config, vault, check } = context(home, request.vault, request.channel), path = sourcePath(request.path);
212
+ if (options.expectedVault && JSON.stringify(options.expectedVault) !== JSON.stringify(vault)) fail("vault binding changed since MCP startup; restart the MCP server");
213
+ if (isDenied(path, config.denyPaths ?? []) || isDenied(join(vault.path, path), config.denyPaths ?? [])) fail("source path is denied; inspect the vault policy before reconciling");
214
+ const store = readEnrichmentStore(home, vault, config.vaults, config.denyPaths ?? []), prior = store.records.find(r => r.path === path && r.kind === request.kind && (r.value as { state?: unknown } | undefined)?.state === "pending");
215
+ const value = prior?.value as { state?: unknown; token?: unknown } | undefined;
216
+ if (!prior || value?.state !== "pending" || typeof value.token !== "string") fail("no unresolved intake reservation exists; inspect the work list before retrying");
217
+ const fingerprint = sha256(JSON.stringify([config, prior, request.resolution]));
218
+ if (request.confirm !== true) {
219
+ if (request.fingerprint !== undefined) fail("fingerprint requires confirmation; request a fresh preview first");
220
+ check();
221
+ return { ok: true, applied: false, fingerprint, path, kind: request.kind, resolution: request.resolution, intakeId: value.token, warning: "Inspect the journal or proposals first. An incorrect resolution can cause a duplicate or suppress needed work." };
222
+ }
223
+ if (request.fingerprint !== fingerprint) fail("reconciliation fingerprint is missing or stale; inspect the outcome and request a fresh preview");
224
+ const released: EnrichmentRecord = { ...prior, value: { state: request.resolution === "published" ? "complete" : "released", token: value.token, reconciled: request.resolution } };
225
+ const stored = writeEnrichmentRecord(home, vault, released, () => {}, current => {
226
+ const now = current.records.find(r => r.path === path && r.kind === request.kind && r.contentHash === prior.contentHash);
227
+ if (!now || sha256(JSON.stringify([loadRegistry(home), now, request.resolution])) !== fingerprint) fail("intake reservation changed; inspect the outcome and request a fresh preview");
228
+ if (request.resolution === "not_published") {
229
+ if (request.kind === "fact") {
230
+ const journal = readJournal(vault.path, config.denyPaths ?? []);
231
+ if (journal.ignored.length || journal.segments.some(segment => segment.untrusted || segment.unsupported || segment.tornTail || segment.partialBatch || segment.entries.some(entry => entry.purged))) fail("journal coverage cannot prove non-publication; inspect and repair the journal before reconciling");
232
+ if (journal.segments.some(segment => segment.entries.some(entry => (entry.payload?.origin as { intakeId?: unknown } | undefined)?.intakeId === value.token))) fail("the intake was published to the journal; reconcile it as published");
233
+ } else {
234
+ try {
235
+ showProposal(home, { vault: vault.id, id: value.token as string }, { channel: request.channel });
236
+ fail("the intake proposal was published; reconcile it as published");
237
+ } catch (error) {
238
+ const message = error instanceof Error ? error.message : "";
239
+ if (!((error as NodeJS.ErrnoException).code === "ENOENT" || message === "proposal: no proposal store for this vault; use proposal list to find an id")) throw error;
240
+ }
241
+ }
242
+ }
243
+ });
244
+ return { ok: stored.issues.length === 0, applied: true, path, kind: request.kind, issues: stored.issues };
245
+ }
@@ -41,7 +41,7 @@ export interface GraphHop {
41
41
  from: string;
42
42
  to: string;
43
43
  /** The deduplicated graph edge this hop used: structural metadata only, never a quote or a probability. */
44
- edge: { kind: "structural"; relation: GraphEdge["relation"]; rel?: string; field: "body" };
44
+ edge: { kind: "structural"; relation: GraphEdge["relation"]; rel?: string; field: "body"; confidence_tag?: "INFERRED" };
45
45
  occurrences: GraphOccurrence[];
46
46
  /** Occurrences found for this pair that the per-hop or byte bound left out. */
47
47
  omitted: number;
@@ -149,7 +149,7 @@ export function explainGraphPath(snapshot: AnalysisSnapshot, from: string, to: s
149
149
  const snapshotHash = sha(JSON.stringify({ algorithm: ALGORITHM, notes: identity, options: { maxHops, relation, viaHubs } }));
150
150
  const hops: GraphHop[] = path.edges.map((edge, index) => {
151
151
  const found = candidates(notes, edge.source, edge.target, edge.source);
152
- return { index, from: edge.source, to: edge.target, edge: { kind: "structural", relation: edge.relation, ...(edge.rel ? { rel: edge.rel } : {}), field: "body" },
152
+ return { index, from: edge.source, to: edge.target, edge: { kind: "structural", relation: edge.relation, ...(edge.rel ? { rel: edge.rel } : {}), field: "body", ...(edge.confidence_tag === "INFERRED" ? { confidence_tag: "INFERRED" as const } : {}) },
153
153
  occurrences: locate(notes, found.slice(0, EXPLAIN_OCCURRENCES_PER_HOP), edge.source), omitted: Math.max(0, found.length - EXPLAIN_OCCURRENCES_PER_HOP) };
154
154
  });
155
155
  const result: GraphExplanation = { schemaVersion: 1, snapshotHash,
package/src/index.ts CHANGED
@@ -66,3 +66,12 @@ export { validateSpecs, introducedSpecErrors, validateSpecRepo } from "./spec-va
66
66
  export type { SpecValidationIssue, SpecValidationOptions, SpecValidationReport, SpecRepoValidationOptions, SpecRepoValidation } from "./spec-validate.ts";
67
67
  export { specFreshness, specsCoveringPath } from "./spec-freshness.ts";
68
68
  export type { SpecFreshnessEntry, SpecFreshnessReport, SpecFreshnessOptions } from "./spec-freshness.ts";
69
+
70
+ export { settingsSnapshot, changeSettings } from "./registry.ts";
71
+ export type { SettingsChanges, SettingsRequest, SettingsSnapshot, SettingsResult } from "./registry.ts";
72
+ export { plugin as consolePlugin } from "./ui/plugin.ts";
73
+ export { listEnrichmentWork, intakeEnrichment, readEnrichment, reconcileEnrichment } from "./enrichment.ts";
74
+ export type { EnrichmentWorkRequest, EnrichmentIntakeRequest } from "./enrichment.ts";
75
+ export { hybridSearch, similarNotes } from "./enrichment-query.ts";
76
+ export type { QueryVector } from "./enrichment-query.ts";
77
+ export type { EnrichmentKind, EnrichmentProducer } from "./enrichment-store.ts";
package/src/mcp-vault.ts CHANGED
@@ -12,12 +12,15 @@ import { buildGraph, graphNeighbors, graphPath, LINK_RELATIONS } from "./vault-g
12
12
  import { lintVault } from "./vault-lint.ts";
13
13
  import { writeAnalysisReports } from "./analysis-reports.ts";
14
14
  import { parseFrontmatter } from "./frontmatter.ts";
15
+ import { listEnrichmentWork, intakeEnrichment, readEnrichment, reconcileEnrichment } from "./enrichment.ts";
16
+ import { hybridSearch, similarNotes } from "./enrichment-query.ts";
17
+ import type { EnrichmentKind } from "./enrichment-store.ts";
15
18
  import type { VaultSpec } from "./config.ts";
16
19
  import { loadRegistry, registryStatus } from "./registry.ts";
17
20
  import { VaultIndex, MAX_NOTE_BYTES } from "./vault-index.ts";
18
21
  import { CHANGES_PAGE_LIMIT, HISTORY_PAGE_LIMIT, SNAPSHOT_CURSOR_CHARS, readChanges, readHistory, readRevision } from "./vault-history.ts";
19
22
  import { listVaultFiles, readVaultFile } from "./vault-files.ts";
20
- import { appendLog, logBinding, readLog } from "./vault-log.ts";
23
+ import { appendLog, logBinding, matchesBinding, readLog } from "./vault-log.ts";
21
24
  import { STATS_MAX_DAYS, vaultStats } from "./vault-stats.ts";
22
25
  import { applyWrite } from "./writer.ts";
23
26
  import { notePath } from "./write-operations.ts";
@@ -45,13 +48,18 @@ const ASSERT_OP = object({ op: { type: "string", enum: ["declare", "relink", "as
45
48
  const oid = { type: "string", minLength: 40, maxLength: 64, pattern: "^(?:[0-9a-f]{40}|[0-9a-f]{64})$" };
46
49
  const logEvent = LOG_EVENT_SCHEMA;
47
50
  const scalar = { type: ["string", "number", "boolean", "null", "array"], maxLength: 4096, maxItems: 64, items: { type: ["string", "number", "boolean"], maxLength: 1024 } };
51
+ const enrichmentKinds = ["embedding", "summary", "community-label", "inferred-link", "fact"];
52
+ const enrichmentOperation = { type: "object", maxProperties: 32, properties: ASSERT_OP.properties, additionalProperties: false };
53
+ const enrichmentValue = { type: ["string", "array", "object"], maxLength: 8192, maxItems: 4096,
54
+ items: { type: ["number", "object"], maxProperties: 32, properties: enrichmentOperation.properties, additionalProperties: false },
55
+ maxProperties: 32, properties: { target: string(191) }, additionalProperties: scalar };
48
56
  const metadata = { type: "object", maxProperties: 32, properties: { authors: { type: "array", minItems: 1, maxItems: 100, items: string(1024) } }, additionalProperties: scalar };
49
57
  const proposalMetadata = { ...metadata, properties: { ...metadata.properties, evidence: { type: "array", maxItems: 16, items: object({ source: string(512), sha256: sha, quote: string(2048), section: string(1024) }, ["source", "sha256", "quote"]) } } };
50
- const proposalOperation = object({ op: { type: "string", enum: ["create", "patch"] }, path: string(200), frontmatter: proposalMetadata, body: string(32768, 0), expectedSha: sha,
58
+ const proposalOperation = object({ op: { type: "string", enum: ["create", "patch", "infer-link"] }, path: string(200), target: string(191), frontmatter: proposalMetadata, body: string(32768, 0), expectedSha: sha,
51
59
  edits: { type: "array", minItems: 1, maxItems: 32, items: object({ oldString: string(8192), newString: string(8192, 0) }, ["oldString", "newString"]) } }, ["op", "path"]);
52
60
 
53
61
  /** Tool names for the implemented read, write, log, analysis and promotion providers. */
54
- export const VMEM_TOOL_NAMES = ["vmem_status", "vmem_search", "vmem_brief", "vmem_read", "vmem_read_many", "vmem_list", "vmem_links", "vmem_history", "vmem_changes", "vmem_mocs", "vmem_check", "vmem_log_tail",
62
+ export const VMEM_TOOL_NAMES = ["vmem_status", "vmem_search", "vmem_enrichment_work", "vmem_enrichment_intake", "vmem_enrichment_get", "vmem_enrichment_reconcile", "vmem_similar", "vmem_brief", "vmem_read", "vmem_read_many", "vmem_list", "vmem_links", "vmem_history", "vmem_changes", "vmem_mocs", "vmem_check", "vmem_log_tail",
55
63
  "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_graph_path", "vmem_graph_explain", "vmem_promote", "vmem_skills_mine", "vmem_read_file", "vmem_list_files", "vmem_report", "vmem_evidence", "vmem_stats", "vmem_proposal_submit", "vmem_proposal_list", "vmem_proposal_show", "vmem_proposal_apply", "vmem_proposal_reject", "vmem_proposal_reconcile", "vmem_assert", "vmem_assertions", "vmem_assertions_purge", "vmem_assertions_exposure", ...SPEC_COMMANDS.map(item => item.name)] as const;
56
64
 
57
65
  /** Server `initialize` instructions: purpose, navigation order and the write contract. Pinned by a test, under 400 bytes. */
@@ -64,7 +72,12 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
64
72
  const orgVault = orgIds.length ? { type: "string", enum: [...orgIds] } : string(32);
65
73
  return [
66
74
  tool("vmem_status", "Registered vaults with health, write policy, effective pii and the piiPolicy matrix (read-only).", object({})),
67
- 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"])),
75
+ tool("vmem_search", "Full-text (BM25) search over indexed notes. Literal AND terms. Supply model and vector together for local hybrid ranking with stored embeddings.", object({ query: string(1000), vault, limit: integer(1, 50), type: string(64), domain: string(64), model: string(256), vector: { type: "array", minItems: 1, maxItems: 4096, items: { type: "number" } } }, ["query"])),
76
+ tool("vmem_enrichment_work", "List a bounded page of notes needing one implemented enrichment kind.", object({ vault, kind: { type: "string", enum: enrichmentKinds }, limit: integer(1, 100), after: string(1024) }, ["kind"])),
77
+ tool("vmem_enrichment_intake", "Submit bounded enrichment output for a source note. Kind-specific validation, PII screening, source hash checks and current vault write policy apply.", object({ vault, path: note, contentHash: sha, kind: { type: "string", enum: enrichmentKinds }, producer: object({ skill: string(128), version: string(64), model: string(256) }, ["skill", "version", "model"]), createdAt: string(32), value: enrichmentValue }, ["path", "contentHash", "kind", "producer", "createdAt", "value"]), "write"),
78
+ tool("vmem_enrichment_get", "Read one current enrichment record after rechecking its source hash and current disclosure policy.", object({ vault, path: note, kind: { type: "string", enum: enrichmentKinds } }, ["path", "kind"])),
79
+ tool("vmem_enrichment_reconcile", "Preview, then explicitly confirm after inspecting the journal or proposals, resolution of an uncertain intake as published or not_published. A wrong resolution can allow a duplicate or suppress work.", object({ vault, path: note, kind: { type: "string", enum: ["fact", "inferred-link"] }, resolution: { type: "string", enum: ["published", "not_published"] }, ...twoStep }, ["path", "kind", "resolution"]), "confirm"),
80
+ tool("vmem_similar", "Find notes nearest to a note with a current stored embedding.", object({ vault, path: note, limit: integer(1, 100) }, ["path"])),
68
81
  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"])),
69
82
  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. With revision, read that full commit id's blob for the path instead: the result carries revision, blob and content sha256 plus basis git_snapshot, within the 48 KiB transport bound.", object({ path: note, vault, maxBytes: integer(1, 65536), section: string(1024), offset: integer(0, MAX_NOTE_BYTES), revision: oid }, ["path"])),
70
83
  tool("vmem_read_many", "Read up to 20 notes (8 KiB each).", object({ paths: { type: "array", minItems: 1, maxItems: 20, items: note }, vault }, ["paths"])),
@@ -101,7 +114,7 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
101
114
  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"),
102
115
  tool("vmem_evidence", "Verify a note's version-1 evidence entries (source, sha256, quote, optional section): flat notes/*.md sources in the same vault are re-read on every call and reported verified, stale, missing, ambiguous or unsupported with UTF-8 byte offsets; other references are unverified_external without I/O. Proves that quoted bytes occur in a source version, not that a claim is true. Writes nothing, takes no lock, keeps no cache.", object({ vault, path: note }, ["path"])),
103
116
  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) })),
104
- tool("vmem_proposal_submit", "Screen and save one create or exact-patch proposal without modifying vault notes or the log. Agent labels are unverified.", object({ vault, operation: proposalOperation, agentLabel: string(256) }, ["operation"]), "write"),
117
+ tool("vmem_proposal_submit", "Screen and save one create, exact-patch or inferred-link proposal without modifying vault notes or the log. Agent labels are unverified.", object({ vault, operation: proposalOperation, agentLabel: string(256) }, ["operation"]), "write"),
105
118
  tool("vmem_proposal_list", "List screened proposal summaries, pending by default; pass nextCursor as after.", object({ vault, state: { type: "string", enum: ["pending", "applied", "rejected", "apply_unknown"] }, limit: integer(1, 100), after: string(36) })),
106
119
  tool("vmem_proposal_show", "Read a screened proposal operation in UTF-8 pages, with the complete encoded response bounded to 48 KiB.", object({ vault, id: string(36), offset: integer(0, 32768), maxBytes: integer(1, 16384) }, ["id"])),
107
120
  tool("vmem_proposal_apply", "Preview an apply, then confirm with its fingerprint. An interrupted apply remains apply_unknown and is never replayed automatically.", object({ vault, id: string(36), ...twoStep }, ["id"]), "confirm"),
@@ -164,7 +177,7 @@ export function exposureReply(reply: ExposureReceipt & { refused?: true }): unkn
164
177
  export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.env): { tools: McpTool[]; handlers: Record<string, McpHandler>; vaults: VaultSpec[]; defaultVault: string | undefined; instructions: string } {
165
178
  const startup = loadRegistry(home), vaults = startup.vaults, ids = vaults.map(v => v.id);
166
179
  const proposalBindings = new Map(vaults.map(v => { try { return [v.id, logBinding(v, startup)] as const; } catch { return [v.id, null] as const; } }));
167
- const defaultVault = (vaults.find(v => v.kind === "personal") ?? vaults[0])?.id;
180
+ const defaultVault = vaults.find(v => v.id === startup.defaultVault)?.id ?? (vaults.find(v => v.kind === "personal") ?? vaults[0])?.id;
168
181
  const pick = (args: Record<string, unknown>): VaultSpec => {
169
182
  const id = str(args.vault) ?? defaultVault;
170
183
  const spec = vaults.find(v => v.id === id);
@@ -175,6 +188,17 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
175
188
  const spec = pick(args), index = new VaultIndex(home, spec, vaults.map(v => v.path));
176
189
  try { index.scan(); return body(index); } finally { index.close(); }
177
190
  };
191
+ const assertStartupBinding = (spec: VaultSpec): void => {
192
+ const current = loadRegistry(home).vaults.find(v => v.id === spec.id);
193
+ if (!current || JSON.stringify(current) !== JSON.stringify(spec)) throw new Error("enrichment: vault binding changed since MCP startup; restart the MCP server");
194
+ };
195
+ const enrichmentReadGuard = (spec: VaultSpec) => {
196
+ const config = loadRegistry(home), current = config.vaults.find(v => v.id === spec.id);
197
+ if (!current || JSON.stringify(current) !== JSON.stringify(spec)) throw new Error("enrichment: vault binding changed since MCP startup; restart the MCP server");
198
+ let binding: ReturnType<typeof logBinding>;
199
+ try { binding = logBinding(spec, config); } catch { throw new Error("enrichment: vault root is unavailable; restore the registered vault and retry"); }
200
+ return () => { if (!matchesBinding(loadRegistry(home), spec.id, binding)) throw new Error("enrichment: vault binding or policy changed during the read; restart the MCP server and retry"); };
201
+ };
178
202
  const write = (args: Record<string, unknown>, operation: WriteOp, extra: Partial<WriteRequest> = {}): WriteReceipt | ReturnType<typeof refusal> & Partial<WriteReceipt> => {
179
203
  const request: WriteRequest = { vault: pick(args).id, operation, channel: "mcp", ...extra, ...(args.log ? { log: args.log as LogEvent } : {}) };
180
204
  const receipt = applyWrite(home, request, { env });
@@ -197,7 +221,7 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
197
221
  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)),
198
222
  vmem_promote: async args => {
199
223
  const { promoteToOrg } = await import("./org-promote.ts");
200
- const source = vaults.find(v => v.id === defaultVault && v.kind === "personal");
224
+ const source = vaults.find(v => v.id === defaultVault && v.kind === "personal") ?? vaults.find(v => v.kind === "personal");
201
225
  if (!source) return refusal("POLICY", "no personal vault registered");
202
226
  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,
203
227
  ...(Array.isArray(args.topics) ? { topics: args.topics as string[] } : {}), ...(str(args.fingerprint) ? { fingerprint: str(args.fingerprint) } : {}) }, { env });
@@ -226,7 +250,21 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
226
250
  vmem_graph_path: args => graphPath(buildGraph(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot),str(args.from)!,str(args.to)!,{maxHops:(args.maxHops as number|undefined) ?? 6,viaHubs:args.viaHubs === true,...(str(args.relation) === undefined ? {} : {relation:str(args.relation)!})}),
227
251
  vmem_graph_explain: args => explainGraphPath(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot,str(args.from)!,str(args.to)!,{maxHops:(args.maxHops as number|undefined) ?? 6,viaHubs:args.viaHubs === true,...(str(args.relation) === undefined ? {} : {relation:str(args.relation)!})}),
228
252
  vmem_status: () => ({ defaultVault: defaultVault ?? null, vaults: registryStatus(home).filter(v => ids.includes(v.id)) }),
229
- vmem_search: args => read(args, index => ({ hits: index.search(str(args.query)!, { limit: (args.limit as number | undefined) ?? 20, type: str(args.type), domain: str(args.domain) }) })),
253
+ vmem_search: args => {
254
+ const spec = pick(args), model = str(args.model), vector = args.vector;
255
+ if ((model === undefined) !== (vector === undefined)) throw new Error("enrichment: model and vector must be supplied together; provide both or omit both");
256
+ if (model !== undefined) {
257
+ const check = enrichmentReadGuard(spec);
258
+ const result = read(args, index => { check(); return { hits: hybridSearch(home, spec.id, index, str(args.query)!, { limit: (args.limit as number | undefined) ?? 20, type: str(args.type), domain: str(args.domain) }, { model, values: vector as number[] }) }; });
259
+ check(); return result;
260
+ }
261
+ return read(args, index => ({ hits: index.search(str(args.query)!, { limit: (args.limit as number | undefined) ?? 20, type: str(args.type), domain: str(args.domain) }) }));
262
+ },
263
+ vmem_enrichment_work: args => { const spec = pick(args), check = enrichmentReadGuard(spec); const result = listEnrichmentWork(home, { vault: spec.id, kind: str(args.kind) as EnrichmentKind, ...(typeof args.limit === "number" ? { limit: args.limit } : {}), ...(str(args.after) ? { after: str(args.after)! } : {}) }); check(); return result; },
264
+ vmem_enrichment_intake: args => { const spec = pick(args); assertStartupBinding(spec); return intakeEnrichment(home, { vault: spec.id, path: str(args.path)!, contentHash: str(args.contentHash)!, kind: str(args.kind) as EnrichmentKind, producer: args.producer as { skill: string; version: string; model: string }, createdAt: str(args.createdAt)!, value: args.value, channel: "mcp" }, { env, expectedVault: spec }); },
265
+ vmem_enrichment_get: args => { const spec = pick(args), check = enrichmentReadGuard(spec); const result = readEnrichment(home, { vault: spec.id, path: str(args.path)!, kind: str(args.kind) as EnrichmentKind }); check(); return result; },
266
+ vmem_enrichment_reconcile: args => { const spec = pick(args); assertStartupBinding(spec); return reconcileEnrichment(home, { vault: spec.id, path: str(args.path)!, kind: str(args.kind) as "fact" | "inferred-link", resolution: str(args.resolution) as "published" | "not_published", channel: "mcp", ...twoStep(args) }, { expectedVault: spec }); },
267
+ vmem_similar: args => { const spec = pick(args), check = enrichmentReadGuard(spec); const result = read(args, index => { check(); return { hits: similarNotes(home, spec.id, index, str(args.path)!, (args.limit as number | undefined) ?? 20) }; }); check(); return result; },
230
268
  vmem_read: args => str(args.revision) === undefined
231
269
  ? read(args, index => { const r = index.show(str(args.path)!, (args.maxBytes as number | undefined) ?? 16384, str(args.section), args.offset as number | undefined); return document(r); })
232
270
  : readRevision({ vault: pick(args), home, env, denyPaths: loadRegistry(home).denyPaths ?? [], note: str(args.path)!, revision: str(args.revision)!,
@@ -18,7 +18,7 @@ import { canonicalPath, isDenied } from "./platform.ts";
18
18
  import { cleanupOwnedFile } from "./write-files.ts";
19
19
 
20
20
  export interface ProposalSubmitRequest { vault: string; operation: unknown; agentLabel?: string }
21
- export interface ProposalContext { channel: "cli" | "mcp"; env?: NodeJS.ProcessEnv; now?: Date; expectedVault?: VaultSpec; expectedBinding?: LogBinding | null }
21
+ export interface ProposalContext { channel: "cli" | "mcp"; env?: NodeJS.ProcessEnv; now?: Date; expectedVault?: VaultSpec; expectedBinding?: LogBinding | null; validateBeforeStore?: () => void; proposalId?: string }
22
22
  export interface ProposalSubmitted { ok: boolean; stored: boolean | null; id: string; vault: string; path: string | null; state: "pending" | null; createdAt: string; payloadDigest: string | null; issues: WriteIssue[] }
23
23
  export interface ProposalSummary { id: string; vault: string; path: string; state: ProposalRecord["state"]; createdAt: string }
24
24
  export interface ProposalListRequest { vault: string; state?: ProposalRecord["state"]; limit?: number; after?: string }
@@ -113,7 +113,7 @@ export function submitProposal(home: string, request: ProposalSubmitRequest, opt
113
113
  if (!preview.ok) throw new Error(`proposal: validation refused (${[...new Set(preview.issues.filter(issue => issue.severity === "error").map(issue => issue.code))].join(", ") || "unknown"}); correct the proposal and retry`);
114
114
  if (preview.changes.length !== 1 || preview.changes[0]!.beforeSha === preview.changes[0]!.sha256) throw new Error("proposal: operation produces no note change; revise the proposal before submitting");
115
115
  const createdAt = (options.now ?? new Date()).toISOString();
116
- const record: ProposalRecord = { schemaVersion: 1, id: randomUUID(), vault: vault.id, bindingDigest, state: "pending", createdAt, updatedAt: createdAt, operation, payloadDigest: proposalPayloadDigest(operation), ...(request.agentLabel !== undefined ? { agentLabel: request.agentLabel } : {}) };
116
+ const record: ProposalRecord = { schemaVersion: 1, id: options.proposalId ?? randomUUID(), vault: vault.id, bindingDigest, state: "pending", createdAt, updatedAt: createdAt, operation, payloadDigest: proposalPayloadDigest(operation), ...(request.agentLabel !== undefined ? { agentLabel: request.agentLabel } : {}) };
117
117
  encodeProposalRecord(record);
118
118
  const placeholder = "0".repeat(64);
119
119
  encodeProposalRecord({ ...record, state: "applied", intent: { fingerprint: placeholder, beforeSha: placeholder, afterSha: placeholder }, receipt: { applied: true, logged: false, beforeSha: placeholder, afterSha: placeholder } });
@@ -137,6 +137,7 @@ export function submitProposal(home: string, request: ProposalSubmitRequest, opt
137
137
  const bindingIssues: WriteIssue[] = [];
138
138
  checkStoredBinding(home, vault.id, bindingDigest, config.denyPaths ?? [], bindingIssues);
139
139
  issues.push(...warningsOf(bindingIssues));
140
+ options.validateBeforeStore?.();
140
141
  attempted = true; stored = null;
141
142
  try { createStoredProposal(home, record, config.denyPaths ?? [], fd); stored = true; }
142
143
  catch (error) {
package/src/proposals.ts CHANGED
@@ -6,7 +6,7 @@ import type { PatchEdit, WriteOp } from "./write-types.ts";
6
6
  export const MAX_PROPOSAL_RECORD_BYTES = 32 * 1024;
7
7
  export const MAX_PROPOSAL_RPC_BYTES = 48 * 1024;
8
8
  export const MAX_PROPOSAL_EDITS = 32;
9
- export type ProposalOperation = Extract<WriteOp, { op: "create" | "patch" }>;
9
+ export type ProposalOperation = Extract<WriteOp, { op: "create" | "patch" | "infer-link" }>;
10
10
 
11
11
  function object(value: unknown): value is Record<string, unknown> {
12
12
  return value !== null && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
@@ -25,9 +25,9 @@ export function proposalRpcBytes(request: unknown): number { return jsonBytes(re
25
25
  export function checkProposalRpcSize(request: unknown): void {
26
26
  if (proposalRpcBytes(request) > MAX_PROPOSAL_RPC_BYTES) throw new Error("proposal: encoded JSON-RPC request exceeds 48 KiB; shorten the proposal");
27
27
  }
28
- /** Only create and exact-replacement patch operations are admissible, with one canonical flat note target. */
28
+ /** Create, exact-replacement patch and inferred-link proposals have one canonical flat note target. */
29
29
  export function parseProposalOperation(value: unknown): ProposalOperation {
30
- if (!object(value) || typeof value.path !== "string") throw new Error("proposal: expected one create or patch operation and note target");
30
+ if (!object(value) || typeof value.path !== "string") throw new Error("proposal: operation or note target is missing; supply a create, patch or infer-link operation with a path");
31
31
  if (jsonBytes(value) > MAX_PROPOSAL_RECORD_BYTES) throw new Error("proposal: operation exceeds the 32 KiB record limit; shorten the payload");
32
32
  const path = notePath(value.path);
33
33
  if (value.op === "create") {
@@ -45,7 +45,13 @@ export function parseProposalOperation(value: unknown): ProposalOperation {
45
45
  });
46
46
  return { op: "patch", path, edits, expectedSha: value.expectedSha };
47
47
  }
48
- throw new Error("proposal: unsupported operation; choose create or patch");
48
+ if (value.op === "infer-link") {
49
+ if (!exactKeys(value, ["op", "path", "target", "expectedSha"]) || typeof value.target !== "string" || typeof value.expectedSha !== "string" || !/^[a-f0-9]{64}$/.test(value.expectedSha)) throw new Error("proposal: infer-link requires a target and base SHA; select a target and reread the source for its current SHA-256");
50
+ const target = notePath(value.target).slice(6, -3);
51
+ if (path === `notes/${target}.md`) throw new Error("proposal: infer-link endpoints must differ; select another target note");
52
+ return { op: "infer-link", path, target, expectedSha: value.expectedSha };
53
+ }
54
+ throw new Error("proposal: unsupported operation; choose create, patch or infer-link");
49
55
  }
50
56
 
51
57
  /** Durable record schema: version 1 is local state, not an index or a note. */
@@ -64,7 +64,7 @@ export function logAppendText(r: LogReceipt, o: TextOptions, c: { vault: string;
64
64
  return blocks(line, issueTable(r.issues, o));
65
65
  }
66
66
 
67
- 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", L16: "warn", L17: "warn" };
67
+ 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", L16: "warn", L17: "warn", L18: "warn", L19: "warn" };
68
68
  const verdict = (r: { errors: number; warnings: number; summary: string }, o: TextOptions) => paint(clean(r.summary), r.errors ? "fail" : r.warnings ? "warn" : "ok", o);
69
69
  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 {
70
70
  const rows = (Object.keys(d.report.findings) as LintCode[]).flatMap(code => {
package/src/registry.ts CHANGED
@@ -3,7 +3,7 @@ import { spawnSync } from "node:child_process";
3
3
  import { realPath, memoryGitArgv, memoryGitEnv } from "./platform.ts";
4
4
  import { hostname } from "node:os";
5
5
  import { join } from "node:path";
6
- import { randomUUID } from "node:crypto";
6
+ import { createHash, randomUUID } from "node:crypto";
7
7
  import { CONFIG_FILE, MAX_CONFIG_BYTES, effectiveDomains, parseConfig, parsePii, parseVault, parseSpec, piiExtensions, readConfig, type VaultSpec, type SpecSourceSpec, type VmemConfig } from "./config.ts";
8
8
  import { loosenedCells, piiPolicy, piiShorthand } from "./pii.ts";
9
9
  export const LOCK_FILE = "config.lock";
@@ -46,6 +46,8 @@ function mutate<T>(home: string, update: (config: VmemConfig) => T): T {
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
48
  if (config.vaults.some(vault => vault.canonTables !== undefined)) config.version = Math.max(config.version ?? 1, 4);
49
+ if (config.defaultVault !== undefined || config.vaults.some(vault => vault.graph !== undefined)) config.version = Math.max(config.version ?? 1, 5);
50
+ if (config.vaults.some(vault => vault.enrichment !== undefined)) config.version = Math.max(config.version ?? 1, 6);
49
51
  parseConfig(config);
50
52
  const text = JSON.stringify(config, null, 2) + "\n";
51
53
  if (Buffer.byteLength(text) > MAX_CONFIG_BYTES) throw new Error(`${join(home, CONFIG_FILE)}: serialized config exceeds 64 KiB`);
@@ -170,7 +172,7 @@ export function removeVault(home: string, id: string, confirm = false): { applie
170
172
  const remove = (config: VmemConfig) => {
171
173
  const vault = config.vaults.find(v => v.id === id);
172
174
  if (!vault) throw new Error(`${join(home, CONFIG_FILE)}: unknown vault id ${id}`);
173
- if (confirm) config.vaults = config.vaults.filter(v => v.id !== id);
175
+ if (confirm) { config.vaults = config.vaults.filter(v => v.id !== id); if (config.defaultVault === id) delete config.defaultVault; }
174
176
  return { applied: confirm, vault };
175
177
  };
176
178
  return confirm ? mutate(home, remove) : remove(loadRegistry(home));
@@ -262,3 +264,56 @@ export function specStatus(home: string, env: NodeJS.ProcessEnv = process.env) {
262
264
  }
263
265
  });
264
266
  }
267
+
268
+ export interface SettingsChanges { defaultVault?: string; write?: VaultSpec["write"]; piiPatterns?: string[]; graphResolution?: number; enrichmentEnabled?: boolean }
269
+ export interface SettingsRequest { vault: string; changes: SettingsChanges; confirm?: boolean; fingerprint?: string }
270
+ export function settingsSnapshot(home: string, id: string) {
271
+ const config = loadRegistry(home), vault = config.vaults.find(v => v.id === id);
272
+ if (!vault) throw new Error("settings: vault is not registered; choose an id from vmem vaults list");
273
+ return { home, vault: vault.id, defaultVaultExplicit: config.vaults.some(v => v.id === config.defaultVault), defaultVault: config.vaults.find(v => v.id === config.defaultVault)?.id ?? (config.vaults.find(v => v.kind === "personal") ?? config.vaults[0])?.id ?? null, write: vault.write, piiPatterns: config.piiPatterns ?? [], graphResolution: vault.graph?.resolution ?? 1, enrichmentEnabled: vault.enrichment?.enabled ?? false };
274
+ }
275
+ export function changeSettings(home: string, request: SettingsRequest) {
276
+ if (!request || !request.changes || typeof request.changes !== "object" || Array.isArray(request.changes)) throw new Error("settings: changes must be an object; supply settings fields");
277
+ if (typeof request.vault !== "string" || !request.vault) throw new Error("settings: vault id is missing; select a registered vault");
278
+ const keys = Object.keys(request.changes);
279
+ if (keys.some(k => (request.changes as unknown as Record<string, unknown>)[k] === undefined)) throw new Error("settings: undefined values are invalid; supply a value for each setting");
280
+ if (!keys.length || keys.some(k => !["defaultVault", "write", "piiPatterns", "graphResolution", "enrichmentEnabled"].includes(k))) throw new Error("settings: missing or unknown changes; use defaultVault, write, piiPatterns, graphResolution or enrichmentEnabled");
281
+ const evaluate = (config: VmemConfig, apply: boolean) => {
282
+ const vault = config.vaults.find(v => v.id === request.vault);
283
+ if (!vault) throw new Error("settings: vault is not registered; choose an id from vmem vaults list");
284
+ const supplied = request.changes;
285
+ const next = structuredClone(config), selected = next.vaults.find(v => v.id === request.vault)!;
286
+ if (supplied.defaultVault !== undefined) {
287
+ if (!next.vaults.some(v => v.id === supplied.defaultVault)) throw new Error("settings: default vault is not registered; choose an id from vmem vaults list");
288
+ next.defaultVault = supplied.defaultVault;
289
+ }
290
+ if (supplied.write !== undefined) selected.write = supplied.write;
291
+ if (supplied.piiPatterns !== undefined) next.piiPatterns = supplied.piiPatterns;
292
+ if (supplied.graphResolution !== undefined) selected.graph = { ...selected.graph, resolution: supplied.graphResolution };
293
+ if (supplied.enrichmentEnabled !== undefined) selected.enrichment = { ...selected.enrichment, enabled: supplied.enrichmentEnabled };
294
+ try { parseConfig(next); } catch (error) { throw new Error(`settings: invalid change (${message(error)}); correct the settings and preview again`); }
295
+ const effectiveDefault = config.vaults.find(v => v.id === config.defaultVault)?.id ?? (config.vaults.find(v => v.kind === "personal") ?? config.vaults[0])?.id;
296
+ const changes: SettingsChanges = {};
297
+ if (supplied.defaultVault !== undefined && supplied.defaultVault !== effectiveDefault) changes.defaultVault = supplied.defaultVault;
298
+ if (supplied.write !== undefined && supplied.write !== vault.write) changes.write = supplied.write;
299
+ if (supplied.piiPatterns !== undefined && JSON.stringify(supplied.piiPatterns) !== JSON.stringify(config.piiPatterns ?? [])) changes.piiPatterns = supplied.piiPatterns;
300
+ if (supplied.graphResolution !== undefined && supplied.graphResolution !== (vault.graph?.resolution ?? 1)) changes.graphResolution = supplied.graphResolution;
301
+ if (supplied.enrichmentEnabled !== undefined && supplied.enrichmentEnabled !== (vault.enrichment?.enabled ?? false)) changes.enrichmentEnabled = supplied.enrichmentEnabled;
302
+ if (!Object.keys(changes).length) throw new Error("settings: no values changed; change a setting before previewing");
303
+ // Rebuild from the current config so unchanged effective defaults are not written explicitly.
304
+ const actual = structuredClone(config), target = actual.vaults.find(v => v.id === request.vault)!;
305
+ if (changes.defaultVault !== undefined) actual.defaultVault = changes.defaultVault;
306
+ if (changes.write !== undefined) target.write = changes.write;
307
+ if (changes.piiPatterns !== undefined) actual.piiPatterns = changes.piiPatterns;
308
+ if (changes.graphResolution !== undefined) target.graph = { ...target.graph, resolution: changes.graphResolution };
309
+ if (changes.enrichmentEnabled !== undefined) target.enrichment = { ...target.enrichment, enabled: changes.enrichmentEnabled };
310
+ const fingerprint = createHash("sha256").update(JSON.stringify([config, request.vault, changes])).digest("hex");
311
+ if (apply && request.fingerprint !== fingerprint) throw new Error("settings: preview is stale or fingerprint is missing; run the preview again and confirm its fingerprint");
312
+ if (apply) Object.assign(config, actual);
313
+ return { applied: apply, fingerprint, changes };
314
+ };
315
+ return request.confirm ? mutate(home, config => evaluate(config, true)) : evaluate(loadRegistry(home), false);
316
+ }
317
+
318
+ export type SettingsSnapshot = ReturnType<typeof settingsSnapshot>;
319
+ export type SettingsResult = ReturnType<typeof changeSettings>;