@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 +10 -0
- package/README.md +1 -1
- package/package.json +2 -2
- package/src/enrichment-query.ts +21 -0
- package/src/enrichment-store.ts +11 -0
- package/src/setup.ts +6 -4
- package/src/skills-install.ts +43 -5
- package/src/ui/graph-snapshot.ts +72 -6
- package/src/ui/panel-types.ts +5 -0
- package/src/ui/plugin.ts +41 -12
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.
|
|
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",
|
package/src/enrichment-query.ts
CHANGED
|
@@ -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");
|
package/src/enrichment-store.ts
CHANGED
|
@@ -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,
|
|
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
|
|
306
|
-
if (!
|
|
307
|
-
|
|
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);
|
package/src/skills-install.ts
CHANGED
|
@@ -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 (
|
|
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
|
|
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");
|
package/src/ui/graph-snapshot.ts
CHANGED
|
@@ -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
|
|
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
|
}
|
package/src/ui/panel-types.ts
CHANGED
|
@@ -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
|
-
|
|
52
|
-
|
|
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
|
|
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
|
-
|
|
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";
|