@staix/vault-mem 0.13.0 → 0.13.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.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,12 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.13.1] - 2026-11-22
6
+
7
+ - Add directed `supersedes` and `superseded_by` frontmatter edges to Graph console snapshots. CLI and MCP graph outputs keep their existing behavior.
8
+
9
+ - Add an opt-in two-step mode to `vmem_link` (`preview`, `confirm`, `fingerprint`; a stale fingerprint returns a fresh preview) and a console `link` action that previews both notes, the relation and the log event before confirming; an existing link is a no-op. Calls without `preview` or `confirm` write in one step as before.
10
+
5
11
  ## [0.13.0] - 2026-11-22
6
12
 
7
13
  - N-1: 0.12.1 and 0.13.0 share the note and spec index files and config format 6. The 0.13.0 CLI adds assertion coverage lines and changes skills-mine filtering and cap reporting; the 0.12.1 CLI keeps its previous behavior. MCP tool names and arguments are unchanged; `vmem_assertions` coverage and `vmem_skills_mine` dropped counts gain additive fields, which 0.12.1 clients may ignore; for an unsupported entry inside an incomplete batch, `coverage.unsupported[].seq` now identifies the first excluded batch entry, as `untrusted[].seq` already did. In 0.12.1 it identifies the unsupported line; `failedSeq` now retains that value. The 0.13.0 console provider adds the Graph panel; an older provider remains usable without it.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@staix/vault-mem",
3
- "version": "0.13.0",
3
+ "version": "0.13.1",
4
4
  "description": "Validated Obsidian-compatible knowledge vaults for agents and people",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/mcp-vault.ts CHANGED
@@ -92,7 +92,7 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
92
92
  tool("vmem_patch", "Replace exact strings in a note: one oldString/newString pair, or edits (1..32 pairs, each matching once in the original text, non-overlapping) applied all-or-nothing with one receipt and one log event.", object({ vault, path: note, oldString: string(8192), newString: string(8192, 0), edits: { type: "array", minItems: 1, maxItems: 32, items: object({ oldString: string(8192), newString: string(8192, 0) }, ["oldString", "newString"]) }, expectedSha: sha, log: logEvent }, ["path"]), "write"),
93
93
  tool("vmem_append", "Append markdown to a section of a note.", object({ vault, path: note, section: string(120), markdown: string(16384), expectedSha: sha, log: logEvent }, ["path", "section", "markdown"]), "write"),
94
94
  tool("vmem_set_frontmatter", "Set or unset frontmatter keys of a note.", object({ vault, path: note, set: metadata, unset: { type: "array", maxItems: 32, items: string(64) }, expectedSha: sha, log: logEvent }, ["path"]), "write"),
95
- tool("vmem_link", "Add a typed relation link between two notes (bidirectional by default).", object({ vault, from: note, to: note, relation: { type: "string", enum: RELATIONS }, context: string(500), bidirectional: { type: "boolean" }, log: logEvent }, ["from", "to", "relation"]), "write"),
95
+ tool("vmem_link", "Add a typed relation link between two notes (bidirectional by default). One step by default. Opt-in two-step: preview=true returns the planned changes to each note, the log event and a fingerprint without writing; confirm=true with that fingerprint writes only while it still matches, otherwise a fresh preview (stale=true) is returned and nothing is written.", object({ vault, from: note, to: note, relation: { type: "string", enum: RELATIONS }, context: string(500), bidirectional: { type: "boolean" }, preview: { type: "boolean" }, ...twoStep, log: logEvent }, ["from", "to", "relation"]), "write"),
96
96
  tool("vmem_supersede", "Mark a note superseded by another.", object({ vault, old: note, next: note, log: logEvent }, ["old", "next"]), "write"),
97
97
  tool("vmem_log_append", "Append one validated event line to the vault log.", object({ vault, type: { type: "string", enum: LOG_TYPES }, project: string(64), source: string(512), dest: string(512), note: string(500) }, ["type", "project", "source", "note"]), "write"),
98
98
  tool("vmem_move", "Two-step rename with link rewrites: without confirm returns preview and fingerprint; then confirm=true with that fingerprint (pass log on the confirm call).", object({ vault, from: note, to: note, ...twoStep, log: logEvent }, ["from", "to"]), "confirm"),
@@ -313,7 +313,24 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
313
313
  vmem_patch: args => write(args, { op: "patch", path: str(args.path)!, ...(args.oldString !== undefined ? { oldString: str(args.oldString) } : {}), ...(args.newString !== undefined ? { newString: str(args.newString) } : {}), ...(args.edits !== undefined ? { edits: args.edits as PatchEdit[] } : {}), expectedSha: str(args.expectedSha) }),
314
314
  vmem_append: args => write(args, { op: "append", path: str(args.path)!, section: str(args.section)!, markdown: str(args.markdown)!, expectedSha: str(args.expectedSha) }),
315
315
  vmem_set_frontmatter: args => write(args, { op: "frontmatter", path: str(args.path)!, set: (args.set as Record<string, unknown> | undefined) ?? {}, ...(args.unset ? { unset: args.unset as string[] } : {}), expectedSha: str(args.expectedSha) }),
316
- vmem_link: args => write(args, { op: "link", from: str(args.from)!, to: str(args.to)!, relation: args.relation as Extract<WriteOp, { op: "link" }>["relation"], ...(str(args.context) ? { context: str(args.context) } : {}), bidirectional: args.bidirectional !== false }),
316
+ vmem_link: args => {
317
+ const operation: WriteOp = { op: "link", from: str(args.from)!, to: str(args.to)!, relation: args.relation as Extract<WriteOp, { op: "link" }>["relation"], ...(str(args.context) ? { context: str(args.context) } : {}), bidirectional: args.bidirectional !== false };
318
+ if (args.confirm === true && !str(args.fingerprint)) throw new Error("link: confirm requires the preview fingerprint; request a preview with preview=true");
319
+ if (args.confirm !== true && args.fingerprint !== undefined) throw new Error("link: fingerprint requires confirm=true; request a new preview");
320
+ // The default log event the write would append; a given `log` replaces it.
321
+ const preview = (stale: boolean) => {
322
+ const receipt = write(args, operation, { dryRun: true });
323
+ if (!receipt.ok) return receipt;
324
+ const event = (args.log as LogEvent | undefined) ?? { type: "CONNECT", project: "-", source: notePath(operation.from), dest: notePath(operation.to), note: "link" };
325
+ return { ...receipt, logEvent: event, ...(stale ? { stale: true } : {}) };
326
+ };
327
+ if (args.confirm === true) {
328
+ const receipt = write(args, operation, twoStep(args));
329
+ const staleFingerprint = !receipt.ok && !receipt.applied && receipt.issues.length === 1 && receipt.issues[0]?.code === "V09" && /fingerprint/.test(receipt.issues[0].message);
330
+ return staleFingerprint ? preview(true) : receipt;
331
+ }
332
+ return args.preview === true ? preview(false) : write(args, operation);
333
+ },
317
334
  vmem_supersede: args => write(args, { op: "supersede", old: str(args.old)!, next: str(args.next)! }),
318
335
  vmem_log_append: args => {
319
336
  const event: LogEvent = { type: str(args.type)!, project: str(args.project)!, source: str(args.source)!, note: str(args.note)!, ...(str(args.dest) ? { dest: str(args.dest) } : {}) };
@@ -1,7 +1,7 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import type { AnalysisSnapshot } from "../analysis-types.ts";
3
3
  import { scalarText } from "../analysis-yaml.ts";
4
- import { buildGraph, collectUnresolvedGraph, codePointCompare, graphFrontmatter, pythonTitle } from "../vault-graph.ts";
4
+ import { buildGraph, collectUnresolvedGraph, collectSupersedesEdges, codePointCompare, graphFrontmatter, pythonTitle } from "../vault-graph.ts";
5
5
  import type { GraphEdge } from "../vault-graph.ts";
6
6
  import type { GraphSnapshotPage, GraphNodeColumns, GraphEdgeColumns } from "./panel-types.ts";
7
7
 
@@ -31,7 +31,10 @@ export function graphEdgeColumns(rows: GraphEdgeRow[]): GraphEdgeColumns {
31
31
  return { source: rows.map(r => r.source), target: rows.map(r => r.target), relations, relation: rows.map(r => relations.indexOf(r.relation)), field: rows.map(r => r.field), rel: rows.map(r => r.rel), confidence_tag: tags.every(t => t === tags[0]) ? tags[0] ?? [] : tags, confidence: confidence.every(c => c === confidence[0]) ? confidence[0] ?? [] : confidence };
32
32
  }
33
33
  export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string): GraphSnapshotAssembly {
34
- const graph = buildGraph(snapshot), unresolved = collectUnresolvedGraph(snapshot);
34
+ const graph = buildGraph(snapshot), ids = new Set(graph.nodes.map(node => node.id));
35
+ const supersedes = collectSupersedesEdges(snapshot), resolved = supersedes.filter(edge => ids.has(edge.target));
36
+ if (graph.edges.length + resolved.length > MAX_EDGES) throw new Error(`graph: exceeds ${MAX_EDGES} edges`);
37
+ const unresolved = [...collectUnresolvedGraph(snapshot), ...supersedes.filter(edge => !ids.has(edge.target))];
35
38
  const grouped = new Map<string, GraphEdge[]>();
36
39
  for (const edge of unresolved) { const list = grouped.get(edge.target) ?? []; list.push(edge); grouped.set(edge.target, list); }
37
40
  const notes = new Map(snapshot.notes.map(n => [n.path.replace(/^notes\//, "").slice(0, -3), n]));
@@ -41,14 +44,14 @@ export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string)
41
44
  });
42
45
  const extra: GraphEdge[] = [];
43
46
  let omitted = 0, full = false;
44
- for (const [id, edges] of grouped) {
45
- if (full || nodes.length >= MAX_NODES || graph.edges.length + extra.length + edges.length > MAX_EDGES) { full = true; omitted++; continue; }
47
+ for (const [id, edges] of [...grouped].sort(([a], [b]) => codePointCompare(a, b))) {
48
+ if (full || nodes.length >= MAX_NODES || graph.edges.length + resolved.length + extra.length + edges.length > MAX_EDGES) { full = true; omitted++; continue; }
46
49
  nodes.push({ id, label: pythonTitle(id.replaceAll("-", " ")), type: null, domain: null, source_file: null, community: null, degree: edges.length, updated: null, date: null, placeholder: true, description: null, confidence: null, topics: null });
47
50
  extra.push(...edges);
48
51
  }
49
52
  extra.sort((a, b) => codePointCompare(a.source, b.source) || codePointCompare(a.target, b.target));
50
53
  const indices = new Map(nodes.map((n, i) => [n.id, i]));
51
- const edges: GraphEdgeRow[] = [...graph.edges, ...extra].map(e => ({ source: indices.get(e.source)!, target: indices.get(e.target)!, relation: e.relation, field: e.field ?? null, rel: e.rel ?? null, confidence_tag: e.confidence_tag, confidence: e.confidence }));
54
+ const edges: GraphEdgeRow[] = [...graph.edges, ...resolved, ...extra].map(e => ({ source: indices.get(e.source)!, target: indices.get(e.target)!, relation: e.relation, field: e.field ?? null, rel: e.rel ?? null, confidence_tag: e.confidence_tag, confidence: e.confidence }));
52
55
  const metadata = { directed: graph.directed, multigraph: graph.multigraph, ...graph.graph };
53
56
  const totals = { nodes: nodes.length, edges: edges.length, placeholders: nodes.length - graph.nodes.length, placeholdersOmitted: omitted };
54
57
  const revision = createHash("sha256").update(JSON.stringify([1, vault, metadata, totals, nodes, edges])).digest("hex");
package/src/ui/plugin.ts CHANGED
@@ -16,6 +16,7 @@ import type { GraphSnapshotAssembly } from "./graph-snapshot.ts";
16
16
  import { assertionCoverageWarnings } from "./panel-types.ts";
17
17
  import type { AssertionsReadResult } from "../assertion-read.ts";
18
18
  import { createInboxSnapshot } from "./inbox.ts";
19
+ import { LINK_RELATIONS } from "../links.ts";
19
20
  import { lintVault } from "../vault-lint.ts";
20
21
  import { readLogSince } from "../vault-log.ts";
21
22
  import type { LintCode } from "../analysis-types.ts";
@@ -132,7 +133,7 @@ export const plugin: ConsolePlugin = {
132
133
  { id: "history", title: "History", order: 10 },
133
134
  { id: "graph", title: "Graph", order: 11, maxAgeMs: REUSE_MS },
134
135
  ],
135
- capabilities: { actions: ["delete", "move", "promote", "promote-from-amem", "settings", "proposal-apply", "proposal-reject"], confirm: true, inbox: true, inboxMaxAgeMs: REUSE_MS, search: true },
136
+ capabilities: { actions: ["delete", "move", "promote", "promote-from-amem", "settings", "proposal-apply", "proposal-reject", "link"], confirm: true, inbox: true, inboxMaxAgeMs: REUSE_MS, search: true },
136
137
  },
137
138
  async open(ctx): Promise<ConsoleProvider> {
138
139
  const home = resolveHome().home;
@@ -204,11 +205,17 @@ export const plugin: ConsolePlugin = {
204
205
  if (typeof args === "string") return { ok: false, error: args };
205
206
  const preview = await call(tool, args);
206
207
  if (preview.refused || preview.ok === false || typeof preview.fingerprint !== "string") return { ok: false, error: firstIssue(preview) };
208
+ if (preview.unchanged === true) return { ok: true, message: `${describe(preview).verb}: already done, nothing changed` };
207
209
  if (!confirmed || fingerprint !== preview.fingerprint) {
208
210
  const d = describe(preview);
209
211
  return { ok: false, needsConfirm: true, fingerprint: preview.fingerprint, verb: d.verb, preview: d.preview, changes: d.changes, ...(d.warnings.length ? { warnings: d.warnings } : {}) };
210
212
  }
211
213
  const done = await call(tool, { ...args, confirm: true, fingerprint });
214
+ // A tool that answers a stale fingerprint with a fresh preview (vmem_link) gets a new confirmation, never a write.
215
+ if (done.stale === true && typeof done.fingerprint === "string") {
216
+ const d = describe(done);
217
+ return { ok: false, needsConfirm: true, fingerprint: done.fingerprint, verb: d.verb, preview: d.preview, changes: d.changes, warnings: ["the notes changed since the preview; review the fresh preview", ...d.warnings] };
218
+ }
212
219
  if (done.applied === true) { lintCache.clear(); revision.invalidate(); inbox.invalidate(); }
213
220
  return confirmedOutcome(done, describe(preview).verb);
214
221
  }
@@ -370,6 +377,14 @@ export const plugin: ConsolePlugin = {
370
377
  warnings: backlinks.length ? [`${backlinks.length} links point here: ${[...new Set(backlinks.map(b => b.source))].slice(0, 5).join(", ")}`] : [] };
371
378
  });
372
379
  }
380
+ case "link": {
381
+ const from = str(args.from), to = str(args.to), relation = str(args.relation);
382
+ if (!from || !to || !relation) return { ok: false, error: "link: from, to and relation are required; pick both notes and a relation" };
383
+ if (!(LINK_RELATIONS as readonly string[]).includes(relation)) return { ok: false, error: `link: invalid relation ${relation}; use one of ${LINK_RELATIONS.join(", ")}` };
384
+ const both = args.bidirectional !== false && args.bidirectional !== "false";
385
+ return twoStep("vmem_link", forward("vmem_link", args, { preview: true, bidirectional: both }), confirmed, fingerprint, p => ({ verb: "Link notes",
386
+ preview: [`link ${from} → ${to} (${relation})${both ? ", both directions" : ", one way"}`, ...(p.logEvent ? [`log: ${JSON.stringify(p.logEvent)}`] : [])], changes: changesOf(p), warnings: [] }));
387
+ }
373
388
  case "move": {
374
389
  const from = str(args.from), to = str(args.to);
375
390
  if (!from || !to) return { ok: false, error: "from and to are required" };
@@ -1,5 +1,5 @@
1
1
  import type { AnalysisSnapshot } from "./analysis-types.ts";
2
- import { authoredLinkOffsets, LINK_RELATIONS } from "./links.ts";
2
+ import { authoredLinkOffsets, LINK_RELATIONS, noteKey } from "./links.ts";
3
3
  export { LINK_RELATIONS };
4
4
  import { AnalysisYamlUnsupported, parseAnalysisYaml, scalarText, yamlTruthy } from "./analysis-yaml.ts";
5
5
 
@@ -137,6 +137,32 @@ export function collectUnresolvedGraph(snapshot: AnalysisSnapshot): GraphEdge[]
137
137
  }
138
138
  return [...edges.values()].sort((a, b) => compare(a.target, b.target) || compare(a.source, b.source));
139
139
  }
140
+ /** Directed frontmatter references for the console snapshot; the legacy graph stays unchanged. */
141
+ export function collectSupersedesEdges(snapshot: AnalysisSnapshot): GraphEdge[] {
142
+ const sources = [...snapshot.notes].sort((a, b) => compare(a.path, b.path));
143
+ const ids = new Map<string, string>();
144
+ for (const note of sources) {
145
+ const id = note.path.replace(/^notes\//, "").slice(0, -3);
146
+ ids.set(noteKey(note.path), id);
147
+ }
148
+ const edges: GraphEdge[] = [];
149
+ for (const note of sources) {
150
+ const source = note.path.replace(/^notes\//, "").slice(0, -3), fm = parse(note.source).fm;
151
+ for (const field of ["supersedes", "superseded_by"] as const) {
152
+ const values = Array.isArray(fm[field]) ? fm[field] : [fm[field]];
153
+ for (const value of values) {
154
+ if (typeof value !== "string") continue;
155
+ for (const match of value.matchAll(LEGACY_LINK)) {
156
+ const raw = match[1]!.split("#", 1)[0]!.trim(), key = noteKey(raw);
157
+ if (!key) continue;
158
+ const target = ids.get(key) ?? ids.get(noteKey(legacyTarget(key))) ?? legacyTarget(key);
159
+ edges.push({ source, target, relation: "supersedes", field, confidence_tag: "EXTRACTED", confidence: 1 });
160
+ }
161
+ }
162
+ }
163
+ }
164
+ return edges;
165
+ }
140
166
  function adjacency(graph: Pick<VaultGraph, "nodes" | "edges">): Map<string, Set<string>> {
141
167
  const neighbors = new Map(graph.nodes.map(node => [node.id, new Set<string>()]));
142
168
  for (const edge of graph.edges) { neighbors.get(edge.source)?.add(edge.target); neighbors.get(edge.target)?.add(edge.source); }
package/src/writer.ts CHANGED
@@ -360,7 +360,8 @@ function runWrite(home: string, request: WriteRequest, options: WriteOptions & {
360
360
  const logIssues = checkLogEvent(home, { vault: request.vault, event: request.log, channel: request.channel }, options.env);
361
361
  if (logIssues.length) throw new WriteRefusal(logIssues.map(issue => ({ ...issue, message: `log event refused, nothing written: ${issue.message}; fix the event fields (rules as for \`log append\`) or omit the event for the default line` })));
362
362
  }
363
- const twoStep = ["move", "delete", "tidy", "merge"].includes(request.operation.op);
363
+ // link is one-step unless the caller confirms a preview fingerprint (opt-in two-step, #295).
364
+ const twoStep = ["move", "delete", "tidy", "merge"].includes(request.operation.op) || (request.operation.op === "link" && request.confirm === true);
364
365
  const preview = request.operation.op === "check" || request.dryRun === true || (twoStep && request.confirm !== true);
365
366
  if (options.proposal && (preview || !options.binding || !["create", "patch", "infer-link"].includes(request.operation.op))) refuse("V01", "proposal confirmation requires one supported proposal operation and a bound vault; request a new preview");
366
367
  if (!preview) {