@staix/vault-mem 0.13.1 → 0.14.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,16 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.14.1] - 2026-11-23
6
+
7
+ - Fixed: setup accepts an override profile skill root linked to the host's real default skill root; other links remain refused.
8
+
9
+ ## [0.14.0] - 2026-11-22
10
+
11
+ - N-1: 0.13.1 and 0.14.0 share the note and spec index files, config format 6 and the enrichment sidecar format. CLI commands and MCP tool names, arguments and receipts are unchanged. Only the console provider differs: its Graph snapshot adds the first-page `enrichment` field and the `similar` and `semantic` arguments, which the 0.13.1 provider does not offer.
12
+
13
+ - Add Graph enrichment capability metadata, similar-note queries and opt-in paged semantic similarity edges; embeddings remain inside the provider.
14
+
5
15
  ## [0.13.1] - 2026-11-22
6
16
 
7
17
  - Add directed `supersedes` and `superseded_by` frontmatter edges to Graph console snapshots. CLI and MCP graph outputs keep their existing behavior.
package/README.md CHANGED
@@ -81,7 +81,7 @@ Each installed directory has a `.vmem-skill.json` ownership marker with its pack
81
81
 
82
82
  ## Library
83
83
 
84
- The only runtime dependency is the first-party range <!-- facts:amem-pin -->`@staix/agent-mem@>=0.33.0 <1.0.0`<!-- /facts:amem-pin -->; host API 1 is checked at load before any agent-mem store opens. Registry commands do not load the agent-mem root. New compatible minors are resolved on installation or update; an existing installation keeps its resolved version. Public library exports (`@staix/vault-mem`, from `src/index.ts`) cover configuration and home resolution, registry operations, frontmatter, link resolution and the derived index, validated writes, the append-only log, the MCP server and its vault tools, host setup, the CLI command table and completion, promotion from agent-mem and to org vaults, lint and graph analysis, sync, source references, migration tidy, the temporal assertion journal and its evaluation, and the spec source registry, graph, validation and freshness. `@staix/vault-mem/ui-plugin` is the console plugin entry, with panels for graph snapshots, proposals (list, show, apply, reject), assertions and note history and changes, and their snapshot types (see [Console plugin](docs/reference/mcp-and-setup.md#console-plugin)). No console bin is shipped. Exported functions and constants by module:
84
+ The only runtime dependency is the first-party range <!-- facts:amem-pin -->`@staix/agent-mem@>=0.33.0 <1.0.0`<!-- /facts:amem-pin -->; host API 1 is checked at load before any agent-mem store opens. Registry commands do not load the agent-mem root. New compatible minors are resolved on installation or update; an existing installation keeps its resolved version. Public library exports (`@staix/vault-mem`, from `src/index.ts`) cover configuration and home resolution, registry operations, frontmatter, link resolution and the derived index, validated writes, the append-only log, the MCP server and its vault tools, host setup, the CLI command table and completion, promotion from agent-mem and to org vaults, lint and graph analysis, sync, source references, migration tidy, the temporal assertion journal and its evaluation, and the spec source registry, graph, validation and freshness. `@staix/vault-mem/ui-plugin` is the console plugin entry, with panels for graph snapshots with optional enrichment and semantic edges, proposals (list, show, apply, reject), assertions and note history and changes, and their snapshot types (see [Console plugin](docs/reference/mcp-and-setup.md#console-plugin)). No console bin is shipped. Exported functions and constants by module:
85
85
  <!-- facts:exports -->
86
86
 
87
87
  - `src/assertion-read.ts`: `readAssertions`, `ASSERTIONS_PAGE_LIMIT`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@staix/vault-mem",
3
- "version": "0.13.1",
3
+ "version": "0.14.1",
4
4
  "description": "Validated Obsidian-compatible knowledge vaults for agents and people",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -35,7 +35,7 @@
35
35
  "LICENSE"
36
36
  ],
37
37
  "scripts": {
38
- "check": "bun x tsc --noEmit && bun scripts/check-boundary.ts && bun scripts/readme-facts.ts && bun scripts/check-docs.mjs && bun test && bun pm pack --dry-run && bun scripts/package-smoke.ts",
38
+ "check": "bun x tsc --noEmit && bun scripts/check-boundary.ts && bun scripts/refusal-inventory.ts && bun scripts/readme-facts.ts && bun scripts/check-docs.mjs && bun test && bun pm pack --dry-run && bun scripts/package-smoke.ts",
39
39
  "smoke:package": "bun scripts/package-smoke.ts",
40
40
  "bench:release": "bun scripts/release-performance.ts",
41
41
  "parity:release": "bun scripts/release-parity.ts",
@@ -1,5 +1,7 @@
1
1
  /** Bounded hybrid ranking over current indexed notes and local stored vectors. */
2
2
  import { join } from "node:path";
3
+ import { createHash } from "node:crypto";
4
+ import type { AnalysisSnapshot } from "./analysis-types.ts";
3
5
  import { loadRegistry } from "./registry.ts";
4
6
  import { logBinding, matchesBinding } from "./vault-log.ts";
5
7
  import { canonicalPath, isDenied } from "./platform.ts";
@@ -39,6 +41,25 @@ function candidates(ctx: ReturnType<typeof queryContext>, index: VaultIndex, que
39
41
  return [{ id, score: vectorSimilarity(query.values, r.value as number[]), note }];
40
42
  }).sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
41
43
  }
44
+ /** Internal graph inputs: only current, allowed vectors; callers must never serialize values. */
45
+ export function graphEnrichmentInputs(home: string, vault: string, snapshot: AnalysisSnapshot) {
46
+ const ctx = queryContext(home, vault);
47
+ if (!ctx.store) { ctx.check(); return undefined; }
48
+ const metadata = new Map(snapshot.notes.map(note => {
49
+ const path = note.path.replace(/^notes\//, "");
50
+ return [path, createHash("sha256").update(note.source).digest("hex")] as const;
51
+ }));
52
+ const vectors = ctx.store.records.flatMap(record => {
53
+ if (record.kind !== "embedding" || !Array.isArray(record.value)) return [];
54
+ const path = record.path.slice(6);
55
+ if (!allowed(ctx, path) || metadata.get(path) !== record.contentHash) return [];
56
+ return [{ path, values: record.value as number[] }];
57
+ }).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
58
+ const hash = createHash("sha256").update(JSON.stringify([ctx.store.model ?? null, snapshot.notes.length]));
59
+ for (const item of vectors) hash.update(JSON.stringify([item.path, item.values]));
60
+ ctx.check();
61
+ return { model: ctx.store.model ?? null, embedded: vectors.length, total: snapshot.notes.length, digest: hash.digest("hex"), vectors };
62
+ }
42
63
  export function hybridSearch(home: string, vault: string, index: VaultIndex, query: string, options: SearchOptions, vector: QueryVector): SearchResult[] {
43
64
  const limit = resultLimit(options.limit), ctx = queryContext(home, vault);
44
65
  if (index.vault.id !== ctx.vault.id || index.vault.path !== ctx.vault.path || !index.sourceIdentityCurrent()) throw new Error("enrichment: index is unscanned or belongs to another vault; reopen and scan the selected vault before retrying");
@@ -111,6 +111,17 @@ function readFile(loc: ReturnType<typeof location>): EnrichmentStore {
111
111
  export function readEnrichmentStore(home: string, vault: VaultSpec, roots: VaultSpec[], denyPaths: string[]): EnrichmentStore {
112
112
  return readFile(location(home, vault, roots, denyPaths, false));
113
113
  }
114
+ /** Metadata-only identity for invalidating in-process views after an atomic sidecar replacement. */
115
+ export function enrichmentStoreStamp(home: string, vault: VaultSpec, roots: VaultSpec[], denyPaths: string[]): string {
116
+ const loc = location(home, vault, roots, denyPaths, false);
117
+ try {
118
+ const stat = lstatSync(loc.file, { bigint: true });
119
+ return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
120
+ } catch (error) {
121
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
122
+ throw new Error("enrichment: sidecar identity cannot be read; inspect the local enrichment store", { cause: error });
123
+ }
124
+ }
114
125
  /** Validate complete metadata and vector shape before any side effects. */
115
126
  export function validateEnrichmentRecord(record: EnrichmentRecord): void {
116
127
  if (!record || typeof record !== "object") fail("intake record is missing; supply a complete result");
package/src/setup.ts CHANGED
@@ -4,7 +4,7 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
4
4
  import { createHash, randomUUID } from "node:crypto";
5
5
  import { isDeepStrictEqual } from "node:util";
6
6
  import { shellWord } from "./text-output.ts";
7
- import { installSkills, skillRoot, type SkillInstallReport } from "./skills-install.ts";
7
+ import { installSkills, resolveHostSkillRoot, type SkillInstallReport } from "./skills-install.ts";
8
8
  import { fileURLToPath } from "node:url";
9
9
 
10
10
  /** Hosts whose MCP configuration `vmem setup` can register; `all` covers every user-level host (not agy). */
@@ -302,9 +302,11 @@ export function runSetup(target: string, mode: SetupMode, options: { home: strin
302
302
  }
303
303
  for (const name of targets) {
304
304
  try {
305
- const path = skillRoot(name, env);
306
- if (!path) { report.skills!.push({ target: name, reason: "skills are not installed for this host; use vmem skills export <dir>" }); continue; }
307
- report.skills!.push({ target: name, report: installSkills(path, mode, root?.path, root?.version, ["vmem", "setup", name, ...(root ? ["--root", root.path] : []), mode === "undo" ? "--undo" : "--apply"].map(shellWord).join(" ")) });
305
+ const resolved = resolveHostSkillRoot(name, env);
306
+ if (!resolved) { report.skills!.push({ target: name, reason: "skills are not installed for this host; use vmem skills export <dir>" }); continue; }
307
+ const skills = installSkills(resolved.root, mode, root?.path, root?.version, ["vmem", "setup", name, ...(root ? ["--root", root.path] : []), mode === "undo" ? "--undo" : "--apply"].map(shellWord).join(" "), resolved.recheck);
308
+ if (resolved.linkedFrom) for (const item of skills.actions) item.reason = `via linked root ${resolved.linkedFrom} to ${skills.root}${item.reason ? `; ${item.reason}` : ""}`;
309
+ report.skills!.push({ target: name, report: skills });
308
310
  } catch (error) { report.skills!.push({ target: name, refused: true, reason: error instanceof Error ? error.message : "skill setup failed; inspect the host configuration" }); }
309
311
  }
310
312
  report.console = consoleManifest(mode, env, root?.path);
@@ -1,5 +1,5 @@
1
1
  /** Install package-owned skills without replacing foreign or locally modified trees. */
2
- import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, opendirSync, readSync, realpathSync, rmSync, writeFileSync, type Stats } from "node:fs";
2
+ import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, opendirSync, readlinkSync, readSync, realpathSync, rmSync, writeFileSync, type Stats } from "node:fs";
3
3
  import { createHash, randomUUID } from "node:crypto";
4
4
  import { isAbsolute, join, relative, resolve, sep } from "node:path";
5
5
  import { homedir } from "node:os";
@@ -114,10 +114,10 @@ function stage(root: string, files: Files, digestValue: string, packageVersion:
114
114
  } catch (error) { rmSync(dir, { recursive: true, force: true }); throw error; }
115
115
  }
116
116
  function existingRoot(path: string): string | undefined {
117
- try { const info = lstatSync(path); if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("skill root is linked or not a directory; choose a real directory"); return realpathSync(path); }
117
+ try { const info = lstatSync(path); if (info.isSymbolicLink()) throw new Error(`skill root link points to ${readlinkSync(path)}; vmem installs only into a real directory or a link to the host's default skill root`); if (!info.isDirectory()) throw new Error("skill root is not a directory; choose a real directory"); return realpathSync(path); }
118
118
  catch (error) {
119
119
  if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
120
- if (error instanceof Error && error.message.startsWith("skill root is linked")) throw error;
120
+ if (error instanceof Error && error.message.startsWith("skill root ")) throw error;
121
121
  throw new Error("skill root cannot be inspected; check its path and permissions", { cause: error });
122
122
  }
123
123
  }
@@ -127,12 +127,13 @@ function removeVerified(path: string, sha: string): boolean {
127
127
  catch { return false; }
128
128
  }
129
129
  /** Plan or install one complete skill tree per name. `root` must be an absolute target directory. */
130
- export function installSkills(root: string, mode: SetupMode, packageRoot = PACKAGE_ROOT, packageVersion = version, retryCommand = ["vmem", "skills", "export", root].map(shellWord).join(" ")): SkillInstallReport {
130
+ export function installSkills(root: string, mode: SetupMode, packageRoot = PACKAGE_ROOT, packageVersion = version, retryCommand = ["vmem", "skills", "export", root].map(shellWord).join(" "), rootGuard?: () => void): SkillInstallReport {
131
131
  if (!isAbsolute(root)) throw new Error("skills: target must be absolute; provide an absolute skill root");
132
132
  if (mode !== "undo" && (typeof packageVersion !== "string" || !packageVersion.trim() || Buffer.byteLength(packageVersion) > 128 || /[\p{Cc}\p{Zl}\p{Zp}]/u.test(packageVersion))) throw new Error("skills: package version is invalid; reinstall a valid vmem package");
133
133
  const requested = resolve(root), actions: SkillAction[] = [];
134
+ rootGuard?.();
134
135
  let actual = existingRoot(requested);
135
- if (!actual && mode !== "dry-run" && mode !== "undo") { mkdirSync(requested, { recursive: true, mode: 0o700 }); actual = existingRoot(requested); }
136
+ if (!actual && mode !== "dry-run" && mode !== "undo") { rootGuard?.(); mkdirSync(requested, { recursive: true, mode: 0o700 }); actual = existingRoot(requested); }
136
137
  if (!actual && mode === "apply") throw new Error("skills: target directory could not be created; inspect the target and retry");
137
138
  for (const name of SKILL_NAMES) {
138
139
  const target = join(actual ?? requested, name), action: SkillAction = { name, path: target, change: "absent" }; actions.push(action);
@@ -149,6 +150,7 @@ export function installSkills(root: string, mode: SetupMode, packageRoot = PACKA
149
150
  }
150
151
  if (mode === "undo") {
151
152
  if (!before) continue;
153
+ rootGuard?.();
152
154
  action.change = "remove";
153
155
  const moved = join(actual!, `.vmem-skill-${randomUUID()}`);
154
156
  renameAtomic(target, moved, false);
@@ -166,9 +168,11 @@ export function installSkills(root: string, mode: SetupMode, packageRoot = PACKA
166
168
  if (before && own?.sha256 === sha && own.version === packageVersion) { action.change = "unchanged"; continue; }
167
169
  action.change = before ? "replace" : "install";
168
170
  if (mode === "dry-run") continue;
171
+ rootGuard?.();
169
172
  const temp = stage(actual!, files, sha, packageVersion), staged = lstatSync(temp);
170
173
  let preserve = false, published = false;
171
174
  try {
175
+ rootGuard?.();
172
176
  if (!before) { renameAtomic(temp, target, false); published = true; }
173
177
  else {
174
178
  if (!identical(before, lstatSync(target))) throw new Error("skill changed before replacement; inspect it and retry");
@@ -203,6 +207,40 @@ export function skillRoot(target: SetupTarget, env: NodeJS.ProcessEnv): string |
203
207
  return join(value ? resolve(value) : join(home, spec[1]), "skills");
204
208
  }
205
209
 
210
+ /** Only an override profile may link its skill root to that host's real default root. */
211
+ export function resolveHostSkillRoot(target: SetupTarget, env: NodeJS.ProcessEnv): { root: string; linkedFrom?: string; recheck?: () => void } | undefined {
212
+ const requested = skillRoot(target, env);
213
+ if (!requested) return undefined;
214
+ let info: Stats;
215
+ try { info = lstatSync(requested); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return { root: requested }; throw error; }
216
+ if (!info.isSymbolicLink()) return { root: requested };
217
+ const targetText = readlinkSync(requested);
218
+ const refused = () => new Error(`skill root link points to ${targetText}; vmem installs only into a real directory or a link to the host's default skill root`);
219
+ const vars: Partial<Record<SetupTarget, string>> = { claude: "CLAUDE_CONFIG_DIR", codex: "CODEX_HOME", kimi: "KIMI_CODE_HOME", qwen: "QWEN_HOME" };
220
+ const variable = vars[target];
221
+ if (!variable || !env[variable]?.trim()) throw refused();
222
+ const defaults = { ...env }; delete defaults[variable];
223
+ const defaultRoot = skillRoot(target, defaults)!;
224
+ let defaultInfo: Stats, actual: string;
225
+ try {
226
+ defaultInfo = lstatSync(defaultRoot);
227
+ if (!defaultInfo.isDirectory() || defaultInfo.isSymbolicLink()) throw refused();
228
+ actual = realpathSync(defaultRoot);
229
+ if (realpathSync(requested) !== actual) throw refused();
230
+ } catch { throw refused(); }
231
+ const recheck = () => {
232
+ try {
233
+ const link = lstatSync(requested), current = lstatSync(defaultRoot);
234
+ if (!link.isSymbolicLink() || link.dev !== info.dev || link.ino !== info.ino || readlinkSync(requested) !== targetText || !identical(defaultInfo, current) || realpathSync(defaultRoot) !== actual || realpathSync(requested) !== actual) throw new Error();
235
+ } catch {
236
+ let target = targetText;
237
+ try { target = readlinkSync(requested); } catch { /* Keep the last observed target when the link disappeared. */ }
238
+ throw new Error(`skill root link changed (target ${target}); inspect ${requested} before retrying`);
239
+ }
240
+ };
241
+ return { root: actual, linkedFrom: requested, recheck };
242
+ }
243
+
206
244
  /** Export into a dedicated directory. Unknown entries mean it is not a vmem export root. */
207
245
  export function exportSkills(destination: string): SkillInstallReport {
208
246
  if (typeof destination !== "string" || !destination.trim() || /[\p{Cc}\p{Zl}\p{Zp}]/u.test(destination)) throw new Error("skills export: destination is missing or invalid; choose a directory path");
@@ -3,13 +3,16 @@ import type { AnalysisSnapshot } from "../analysis-types.ts";
3
3
  import { scalarText } from "../analysis-yaml.ts";
4
4
  import { buildGraph, collectUnresolvedGraph, collectSupersedesEdges, codePointCompare, graphFrontmatter, pythonTitle } from "../vault-graph.ts";
5
5
  import type { GraphEdge } from "../vault-graph.ts";
6
- import type { GraphSnapshotPage, GraphNodeColumns, GraphEdgeColumns } from "./panel-types.ts";
6
+ import type { GraphSnapshotPage, GraphNodeColumns, GraphEdgeColumns, SemanticGraphPage } from "./panel-types.ts";
7
7
 
8
8
  type NodeRow = { id: string; label: string; type: string | null; domain: string | null; source_file: string | null; community: number | null; degree: number; updated: string | null; date: string | null; placeholder: boolean; description: string | null; confidence: string | null; topics: string | null };
9
9
  export type GraphEdgeRow = { source: number; target: number; relation: string; field: string | null; rel: string | null; confidence_tag: string; confidence: number };
10
- export interface GraphSnapshotAssembly { vault: string; revision: string; pages: GraphSnapshotPage[] }
10
+ export interface GraphEnrichmentInputs { model: string | null; embedded: number; total: number; digest: string; vectors: { path: string; values: number[] }[] }
11
+ export interface GraphSnapshotAssembly { vault: string; revision: string; pages: GraphSnapshotPage[]; enrichment?: GraphEnrichmentInputs }
11
12
  const MAX_BYTES = 1_048_576 - 32;
12
13
  const MAX_NODES = 10_000, MAX_EDGES = 100_000;
14
+ // ponytail: exact all-pairs search is bounded here; larger vaults need ANN or precomputed neighbors.
15
+ const MAX_SEMANTIC_EMBEDDINGS = 3_000;
13
16
  const scalar = (v: unknown): string | null => scalarText(v) ?? (typeof v === "string" || typeof v === "number" || typeof v === "boolean" || typeof v === "bigint" ? String(v) : null);
14
17
  const token = (vault: string, revision: string, kind: string, offset: number): string => Buffer.from(JSON.stringify([1, vault, revision, kind, offset])).toString("base64url");
15
18
  export const encodeGraphPage = (assembly: GraphSnapshotAssembly, page: GraphSnapshotPage): string => token(assembly.vault, assembly.revision, page.kind, page.offset);
@@ -30,7 +33,7 @@ export function graphEdgeColumns(rows: GraphEdgeRow[]): GraphEdgeColumns {
30
33
  const relations = [...new Set(rows.map(r => r.relation))], tags = rows.map(r => r.confidence_tag), confidence = rows.map(r => r.confidence);
31
34
  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
35
  }
33
- export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string): GraphSnapshotAssembly {
36
+ export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string, enrichment?: GraphEnrichmentInputs): GraphSnapshotAssembly {
34
37
  const graph = buildGraph(snapshot), ids = new Set(graph.nodes.map(node => node.id));
35
38
  const supersedes = collectSupersedesEdges(snapshot), resolved = supersedes.filter(edge => ids.has(edge.target));
36
39
  if (graph.edges.length + resolved.length > MAX_EDGES) throw new Error(`graph: exceeds ${MAX_EDGES} edges`);
@@ -54,13 +57,13 @@ export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string)
54
57
  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 }));
55
58
  const metadata = { directed: graph.directed, multigraph: graph.multigraph, ...graph.graph };
56
59
  const totals = { nodes: nodes.length, edges: edges.length, placeholders: nodes.length - graph.nodes.length, placeholdersOmitted: omitted };
57
- const revision = createHash("sha256").update(JSON.stringify([1, vault, metadata, totals, nodes, edges])).digest("hex");
60
+ const revision = createHash("sha256").update(JSON.stringify([1, vault, metadata, totals, nodes, edges, ...(enrichment ? [enrichment.digest] : [])])).digest("hex");
58
61
  const pages: GraphSnapshotPage[] = [];
59
62
  const envelope = (kind: "nodes" | "edges", offset: number, count: number, columns: GraphNodeColumns | GraphEdgeColumns): GraphSnapshotPage => {
60
63
  const total = kind === "nodes" ? nodes.length : edges.length;
61
64
  const next = offset + count < total ? token(vault, revision, kind, offset + count)
62
65
  : kind === "nodes" && edges.length ? token(vault, revision, "edges", 0) : null;
63
- return { schema: 1, vault, revision, graph: metadata, totals, kind, offset, count, columns, next };
66
+ return { schema: 1, vault, revision, graph: metadata, totals, kind, offset, count, columns, next, ...(enrichment && kind === "nodes" && offset === 0 ? { enrichment: { model: enrichment.model, embedded: enrichment.embedded, total: enrichment.total } } : {}) };
64
67
  };
65
68
  // Binary search each page boundary: every candidate is measured before its rows are accepted.
66
69
  function paginate<T>(kind: "nodes" | "edges", rows: T[], columns: (items: T[]) => GraphNodeColumns | GraphEdgeColumns): void {
@@ -87,5 +90,68 @@ export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string)
87
90
  }
88
91
  }
89
92
  paginate("nodes", nodes, nodeColumns); paginate("edges", edges, graphEdgeColumns);
90
- return { vault, revision, pages };
93
+ return { vault, revision, pages, ...(enrichment ? { enrichment } : {}) };
94
+ }
95
+
96
+ /** Exact undirected union of each note's top-k cosine neighbors. Vectors remain in process. */
97
+ export function assembleSemanticPages(assembly: GraphSnapshotAssembly, k: number, minScore: number): SemanticGraphPage[] {
98
+ if (!Number.isInteger(k) || k < 1 || k > 20 || typeof minScore !== "number" || !Number.isFinite(minScore) || minScore < 0 || minScore > 1)
99
+ throw new Error("graph semantic: k must be 1..20 and minScore must be 0..1; correct the parameters and restart");
100
+ if (!assembly.enrichment) throw new Error("enrichment: enrichment is disabled; enable it in settings");
101
+ if (assembly.enrichment.embedded > MAX_SEMANTIC_EMBEDDINGS) throw new Error(`graph semantic: exceeds ${MAX_SEMANTIC_EMBEDDINGS} current embeddings; reduce the embedded set or use similar notes`);
102
+ const ids = new Map<string, number>();
103
+ for (const page of assembly.pages) if (page.kind === "nodes") {
104
+ const columns = page.columns as GraphNodeColumns;
105
+ columns.source_file.forEach((path, i) => { if (path) ids.set(path.slice(6), page.offset + i); });
106
+ }
107
+ const vectors = assembly.enrichment.vectors.flatMap(item => {
108
+ const index = ids.get(item.path); if (index === undefined) return [];
109
+ let scale = 0; for (const v of item.values) scale = Math.max(scale, Math.abs(v));
110
+ let norm = 0; for (const v of item.values) norm += (v / scale) ** 2;
111
+ norm = Math.sqrt(norm);
112
+ return [{ index, vector: Float64Array.from(item.values, v => v / scale / norm) }];
113
+ }).sort((a, b) => a.index - b.index);
114
+ const tops: { index: number; score: number }[][] = vectors.map(() => []);
115
+ const insert = (list: { index: number; score: number }[], index: number, score: number) => {
116
+ let at = 0;
117
+ while (at < list.length && (list[at]!.score > score || (list[at]!.score === score && list[at]!.index < index))) at++;
118
+ if (at >= k) return;
119
+ list.splice(at, 0, { index, score }); if (list.length > k) list.pop();
120
+ };
121
+ for (let i = 0; i < vectors.length; i++) for (let j = i + 1; j < vectors.length; j++) {
122
+ const left = vectors[i]!.vector, right = vectors[j]!.vector;
123
+ let score = 0; for (let d = 0; d < left.length; d++) score += left[d]! * right[d]!;
124
+ score = Math.max(-1, Math.min(1, score));
125
+ if (score >= minScore) { insert(tops[i]!, j, score); insert(tops[j]!, i, score); }
126
+ }
127
+ const unique = new Map<string, { source: number; target: number; score: number }>();
128
+ tops.forEach((list, i) => { for (const item of list) {
129
+ const source = Math.min(vectors[i]!.index, vectors[item.index]!.index), target = Math.max(vectors[i]!.index, vectors[item.index]!.index);
130
+ unique.set(`${source}:${target}`, { source, target, score: item.score });
131
+ } });
132
+ const rows = [...unique.values()].sort((a, b) => a.source - b.source || a.target - b.target);
133
+ const encode = (offset: number) => Buffer.from(JSON.stringify([1, assembly.vault, assembly.revision, "semantic", k, minScore, offset])).toString("base64url");
134
+ const make = (offset: number, count: number): SemanticGraphPage => {
135
+ const slice = rows.slice(offset, offset + count);
136
+ return { schema: 1, vault: assembly.vault, revision: assembly.revision, kind: "semantic", offset, count, semantic: { source: slice.map(r => r.source), target: slice.map(r => r.target), score: slice.map(r => r.score) }, next: offset + count < rows.length ? encode(offset + count) : null };
137
+ };
138
+ const pages: SemanticGraphPage[] = []; let offset = 0;
139
+ do {
140
+ let low = 0, high = rows.length - offset;
141
+ if (Buffer.byteLength(JSON.stringify(make(offset, high))) <= MAX_BYTES) { pages.push(make(offset, high)); break; }
142
+ high--;
143
+ while (low < high) { const mid = Math.ceil((low + high) / 2); if (Buffer.byteLength(JSON.stringify(make(offset, mid))) <= MAX_BYTES) low = mid; else high = mid - 1; }
144
+ if (!low) throw new Error("graph semantic: page exceeds the byte budget; reduce the vault id and restart");
145
+ pages.push(make(offset, low)); offset += low;
146
+ } while (offset < rows.length);
147
+ return pages;
148
+ }
149
+ export function resolveSemanticPage(assembly: GraphSnapshotAssembly, pages: SemanticGraphPage[], k: number, minScore: number, page?: string): SemanticGraphPage {
150
+ if (page === undefined) return pages[0]!;
151
+ try {
152
+ const value: unknown = JSON.parse(Buffer.from(page, "base64url").toString("utf8"));
153
+ if (!Array.isArray(value) || value.length !== 7 || value[0] !== 1 || value[1] !== assembly.vault || value[2] !== assembly.revision || value[3] !== "semantic" || value[4] !== k || value[5] !== minScore || !Number.isSafeInteger(value[6]) || value[6] < 0 || Buffer.from(JSON.stringify(value)).toString("base64url") !== page) throw new Error();
154
+ const found = pages.find(p => p.offset === value[6]); if (found) return found;
155
+ } catch { /* All invalid tokens get the same recovery instruction. */ }
156
+ throw new Error("graph semantic page is invalid or expired; restart from the first page");
91
157
  }
@@ -57,6 +57,11 @@ export interface GraphSnapshotPage {
57
57
  totals: { nodes: number; edges: number; placeholders: number; placeholdersOmitted: number };
58
58
  kind: "nodes" | "edges"; offset: number; count: number;
59
59
  columns: GraphNodeColumns | GraphEdgeColumns; next: string | null;
60
+ enrichment?: { model: string | null; embedded: number; total: number };
61
+ }
62
+ export interface SemanticGraphPage {
63
+ schema: 1; vault: string; revision: string; kind: "semantic"; offset: number; count: number;
64
+ semantic: { source: number[]; target: number[]; score: number[] }; next: string | null;
60
65
  }
61
66
  /** The provider attaches a numeric cursor for console conditional polling. */
62
67
  export type GraphPanelPage = GraphSnapshotPage & { cursor: number };
package/src/ui/plugin.ts CHANGED
@@ -11,8 +11,11 @@ import { validArguments } from "../mcp.ts";
11
11
  import { listPromotionCandidates } from "../promote.ts";
12
12
  import { changeSettings, settingsSnapshot, loadRegistry } from "../registry.ts";
13
13
  import { createSnapshotRevision, createPromoteSnapshot, nextSnapshotCursor } from "./snapshot-cache.ts";
14
- import { assembleGraphSnapshot, resolveGraphPage } from "./graph-snapshot.ts";
14
+ import { assembleGraphSnapshot, resolveGraphPage, assembleSemanticPages, resolveSemanticPage } from "./graph-snapshot.ts";
15
15
  import type { GraphSnapshotAssembly } from "./graph-snapshot.ts";
16
+ import type { SemanticGraphPage } from "./panel-types.ts";
17
+ import { graphEnrichmentInputs } from "../enrichment-query.ts";
18
+ import { enrichmentStoreStamp } from "../enrichment-store.ts";
16
19
  import { assertionCoverageWarnings } from "./panel-types.ts";
17
20
  import type { AssertionsReadResult } from "../assertion-read.ts";
18
21
  import { createInboxSnapshot } from "./inbox.ts";
@@ -26,32 +29,48 @@ const VERSION = (JSON.parse(asset("../../package.json")) as { version: string })
26
29
  const LINT_ERRORS: LintCode[] = ["L01", "L02", "L13"];
27
30
  const CACHE_MS = 60_000;
28
31
  /** Revision-bound assemblies, shared between concurrent requests and bounded to two vaults. */
29
- export function createGraphSnapshotCache(revision: () => number, load: (vault: string) => Promise<GraphSnapshotAssembly>, now: () => number = Date.now) {
30
- type Entry = { stamp: number; at: number; assembly: GraphSnapshotAssembly; cursors: Map<string, number> };
32
+ export function createGraphSnapshotCache(revision: (vault: string) => number | string, load: (vault: string) => Promise<GraphSnapshotAssembly>, now: () => number = Date.now) {
33
+ type Entry = { stamp: number | string; at: number; assembly: GraphSnapshotAssembly; cursors: Map<string, number>; semantic: Map<string, SemanticGraphPage[]> };
31
34
  const cache = new Map<string, Entry>(), flights = new Map<string, Promise<Entry>>();
32
35
  return {
33
36
  async snapshot(vault: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
34
37
  let entry: Entry | undefined;
35
38
  for (let attempts = 0; attempts < 3; attempts++) {
36
- const stamp = revision(), hit = cache.get(vault);
39
+ const stamp = revision(vault), hit = cache.get(vault);
37
40
  if (hit && hit.stamp === stamp && now() - hit.at < CACHE_MS) { entry = hit; break; }
38
41
  let flight = flights.get(vault);
39
42
  if (!flight) {
40
- flight = load(vault).then(assembly => ({ stamp, at: now(), assembly, cursors: new Map<string, number>() }));
43
+ flight = load(vault).then(assembly => ({ stamp, at: now(), assembly, cursors: new Map<string, number>(), semantic: new Map<string, SemanticGraphPage[]>() }));
41
44
  flights.set(vault, flight);
42
45
  }
43
46
  try { entry = await flight; } finally { if (flights.get(vault) === flight) flights.delete(vault); }
44
- if (entry.stamp === revision()) { cache.delete(vault); cache.set(vault, entry); while (cache.size > 2) cache.delete(cache.keys().next().value!); break; }
47
+ if (entry.stamp === revision(vault)) { cache.delete(vault); cache.set(vault, entry); while (cache.size > 2) cache.delete(cache.keys().next().value!); break; }
45
48
  entry = undefined;
46
49
  }
47
50
  if (!entry) throw new Error("graph changed while assembling; restart from the first page");
48
51
  cache.delete(vault); cache.set(vault, entry);
49
52
  while (cache.size > 2) cache.delete(cache.keys().next().value!);
50
53
  if (args.page !== undefined && typeof args.page !== "string") throw new Error("graph page is invalid; restart from the first page");
51
- const page = resolveGraphPage(entry.assembly, args.page as string | undefined);
52
- const key = `${page.kind}:${page.offset}`;
54
+ let page: ReturnType<typeof resolveGraphPage> | SemanticGraphPage;
55
+ let query = "";
56
+ if (args.semantic !== undefined) {
57
+ const options = args.semantic;
58
+ if (!options || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some(key => key !== "k" && key !== "minScore")) throw new Error("graph semantic: supply k and minScore; correct the parameters and restart");
59
+ const { k, minScore } = options as Record<string, unknown>;
60
+ if (typeof k !== "number" || !Number.isInteger(k) || k < 1 || k > 20 || typeof minScore !== "number" || !Number.isFinite(minScore) || minScore < 0 || minScore > 1) throw new Error("graph semantic: k must be 1..20 and minScore must be 0..1; correct the parameters and restart");
61
+ query = JSON.stringify([k, minScore]);
62
+ let pages = entry.semantic.get(query);
63
+ if (!pages) {
64
+ pages = assembleSemanticPages(entry.assembly, k, minScore);
65
+ if (entry.stamp !== revision(vault)) throw new Error("graph changed while assembling semantic edges; restart from the first page");
66
+ if (entry.semantic.size >= 4) entry.semantic.delete(entry.semantic.keys().next().value!);
67
+ entry.semantic.set(query, pages);
68
+ }
69
+ page = resolveSemanticPage(entry.assembly, pages, k, minScore, args.page as string | undefined);
70
+ } else page = resolveGraphPage(entry.assembly, args.page as string | undefined);
71
+ const key = `${page.kind}:${query}:${page.offset}`;
53
72
  let cursor = entry.cursors.get(key);
54
- if (cursor === undefined) { cursor = nextSnapshotCursor(); entry.cursors.set(key, cursor); }
73
+ if (cursor === undefined) { if (entry.cursors.size >= 256) entry.cursors.delete(entry.cursors.keys().next().value!); cursor = nextSnapshotCursor(); entry.cursors.set(key, cursor); }
55
74
  if (args.after === cursor) return { changed: false, cursor };
56
75
  return { ...page, cursor };
57
76
  },
@@ -192,9 +211,15 @@ export const plugin: ConsolePlugin = {
192
211
  };
193
212
 
194
213
  const promote = createPromoteSnapshot(revision.current, candidates);
195
- const graph = createGraphSnapshotCache(revision.current, async id => {
214
+ const graphStamp = (id: string) => {
215
+ const config = loadRegistry(home), vault = config.vaults.find(v => v.id === id);
216
+ if (!vault) throw new Error("graph: vault is no longer registered; select a registered vault");
217
+ return `${revision.current()}:${vault.enrichment?.enabled ? enrichmentStoreStamp(home, vault, config.vaults, config.denyPaths ?? []) : "disabled"}`;
218
+ };
219
+ const graph = createGraphSnapshotCache(graphStamp, async id => {
196
220
  const spec = mcp.vaults.find(v => v.id === id)!;
197
- return assembleGraphSnapshot(analysisInput(home, id, { expectedVault: spec }).snapshot, id);
221
+ const snapshot = analysisInput(home, id, { expectedVault: spec }).snapshot;
222
+ return assembleGraphSnapshot(snapshot, id, graphEnrichmentInputs(home, id, snapshot));
198
223
  });
199
224
  const inbox = createInboxSnapshot(home, mcp.vaults, ctx.log, undefined, revision.current);
200
225
  // One cursor for the whole Promote failure: a fresh one per failed scan would rebuild the panel every poll.
@@ -243,6 +268,10 @@ export const plugin: ConsolePlugin = {
243
268
  case "graph": {
244
269
  const vault = vaultOf(args);
245
270
  if (!vault) return { vault: null, error: str(args.vault) ? `unknown vault ${str(args.vault)}; pick a registered vault from Overview` : "graph: no selected vault; select a registered vault" };
271
+ if (args.similar !== undefined) {
272
+ const result = await readTool("vmem_similar", args, { vault: vault.id, path: args.similar });
273
+ return "error" in result ? result : { similar: result.result.hits };
274
+ }
246
275
  const stem = (value: unknown) => typeof value === "string" && value.startsWith("notes/") && value.endsWith(".md") ? value.slice(6, -3) : value;
247
276
  if (args.neighbors !== undefined) {
248
277
  const r = await readTool("vmem_graph_neighbors", args, { vault: vault.id, path: stem(args.neighbors) });
@@ -461,5 +490,5 @@ export const plugin: ConsolePlugin = {
461
490
  };
462
491
 
463
492
  export default plugin;
464
- export type { ProposalState, ProposalsSnapshot, AssertionsSnapshot, HistorySnapshot, CoverageWarning, GraphSnapshotPage, GraphPanelPage, GraphNodeColumns, GraphEdgeColumns } from "./panel-types.ts";
493
+ export type { ProposalState, ProposalsSnapshot, AssertionsSnapshot, HistorySnapshot, CoverageWarning, GraphSnapshotPage, GraphPanelPage, GraphNodeColumns, GraphEdgeColumns, SemanticGraphPage } from "./panel-types.ts";
465
494
  export { assertionCoverageWarnings } from "./panel-types.ts";