@staix/vault-mem 0.12.0 → 0.13.0
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 +16 -0
- package/README.md +4 -2
- package/package.json +1 -1
- package/skills/skill-mine/SKILL.md +2 -0
- package/skills/vault-enrich/SKILL.md +31 -0
- package/src/assertion-coverage.ts +26 -0
- package/src/assertions-command.ts +2 -2
- package/src/assertions.ts +20 -14
- package/src/skills-install.ts +1 -1
- package/src/skills-mine.ts +22 -7
- package/src/ui/graph-snapshot.ts +88 -0
- package/src/ui/panel-types.ts +24 -17
- package/src/ui/panel.js +10 -0
- package/src/ui/plugin.ts +55 -1
- package/src/vault-graph.ts +23 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,22 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [0.13.0] - 2026-11-22
|
|
6
|
+
|
|
7
|
+
- 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.
|
|
8
|
+
|
|
9
|
+
- Fixed: assertion coverage counts excluded entries per damaged segment and partial batch, and shows the same coverage messages in CLI text and the console.
|
|
10
|
+
|
|
11
|
+
- Fixed: the Graph panel says no vault is selected when none is, instead of an empty unknown-vault id, and offers First page next to a page error.
|
|
12
|
+
|
|
13
|
+
- Add a Graph console panel with revision-bound, byte-bounded snapshot pages, unresolved-link placeholders, and existing neighborhood and path queries.
|
|
14
|
+
|
|
15
|
+
- `vmem skills mine` skips host-injected `UserPromptSubmit` envelopes (`<task-notification>`, `<channel `, `<agent-message `), counted as `dropped.synthetic`, and no longer fails over 20,000 records or 64 MiB: it keeps the newest records, counts the rest in `dropped.overCap` and names the narrowing step in the report. CLI flags and MCP arguments are unchanged.
|
|
16
|
+
|
|
17
|
+
## [0.12.1] - 2026-11-22
|
|
18
|
+
|
|
19
|
+
- Add the bundled `vault-enrich` skill for hash-bound offline enrichment intake, review and reconciliation.
|
|
20
|
+
|
|
5
21
|
## [0.12.0] - 2026-11-22
|
|
6
22
|
|
|
7
23
|
- N-1: 0.11.0 shares the note and spec index files; 0.11.0 supports config format 4; format 5 adds default vault and graph options, and format 6 adds per-vault enrichment. Older readers preserve but ignore new keys in newer formats. The older CLI lacks settings and enrichment options; its MCP server lacks the enrichment tools and vector arguments. Older readers ignore local sidecars, may treat inferred links as extracted and do not expose assertion origin metadata; older writers refuse newly introduced `inferred_links` metadata and the `infer-link` proposal operation. Bundled skills and their setup and export commands are new in 0.12.0; 0.11.0 leaves those installed skill directories alone.
|
package/README.md
CHANGED
|
@@ -62,7 +62,7 @@ Enrichment is opt-in per vault through `vmem settings` or the Settings panel. A
|
|
|
62
62
|
|
|
63
63
|
## Skills
|
|
64
64
|
|
|
65
|
-
The package includes `vault-connect`, `vault-extract`, `vault-graph`, `vault-learn`, `vault-lint`, `vault-refactor`, `vault-remember`, `vault-rethink`, `vault-stats`, `vault-sync`, `vault-update`, `vmem-status` and `skill-mine`. They run with vmem alone; workspace-specific steps are optional.
|
|
65
|
+
The package includes `vault-connect`, `vault-enrich`, `vault-extract`, `vault-graph`, `vault-learn`, `vault-lint`, `vault-refactor`, `vault-remember`, `vault-rethink`, `vault-stats`, `vault-sync`, `vault-update`, `vmem-status` and `skill-mine`. They run with vmem alone; workspace-specific steps are optional.
|
|
66
66
|
|
|
67
67
|
`vmem setup claude|codex|kimi|qwen --apply` installs the skills alongside the MCP entry. `--undo` removes only unmodified vmem-owned skills. Pi, jcode and agy do not have an automatic skill root; use `vmem skills export <dir>` to prepare self-contained directories for another host.
|
|
68
68
|
|
|
@@ -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 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, 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`
|
|
@@ -124,6 +124,8 @@ The only runtime dependency is the first-party range <!-- facts:amem-pin -->`@st
|
|
|
124
124
|
|
|
125
125
|
<!-- /facts:exports -->
|
|
126
126
|
|
|
127
|
+
The `./ui-plugin` entry also exports `GraphSnapshotPage`, `GraphPanelPage`, `GraphNodeColumns` and `GraphEdgeColumns`.
|
|
128
|
+
|
|
127
129
|
## Development
|
|
128
130
|
|
|
129
131
|
```sh
|
package/package.json
CHANGED
|
@@ -31,6 +31,8 @@ vmem skills mine <vault> --days 30 \
|
|
|
31
31
|
|
|
32
32
|
- MCP만 있으면 `vmem_skills_mine`에 `vault`, `days`, `vocab`, `skills`를 전달한다. amem 데이터가 없으면 이용 가능한 vault 노트로 실행하고 누락된 입력을 보고한다.
|
|
33
33
|
- 입력: amem curated(decision·finding·contract·fail), amem capture(사용자 프롬프트·observation·summary), vault 노트(person·moc·reference 제외). 기간은 `--days`(기본 30), 프로젝트는 기본 전체이고 `--project <key>`로 좁힌다.
|
|
34
|
+
- 호스트가 `UserPromptSubmit`으로 주입한 합성 프롬프트(`<task-notification>`, `<channel `, `<agent-message `로 시작)는 사람 프롬프트가 아니므로 제외되고 리포트 `dropped:` 줄의 `synthetic N`으로 집계된다.
|
|
35
|
+
- 상한(20,000건·총 64 MiB)을 넘으면 실패하지 않고 최신 레코드만 남긴다. 리포트 머리의 `over cap:` 줄이 남긴 건수와 제외한 건수를 알려 준다. 그 줄이 보이면 `--days`를 줄이거나 `--project <key>`로 프로젝트별로 나눠 다시 실행한다.
|
|
34
36
|
- 표준출력이 리포트 본문(markdown)이다. `--json`은 후보·점수·출처별 건수를 구조화해 돌려준다. MCP에서는 `vmem_skills_mine`.
|
|
35
37
|
- workspace가 있으면 리포트를 `<workspace-root>/_meta/reports/skill-candidates-YYMMDD.md`로 저장한다. 없으면 사용자에게 결과를 보여주고 workspace 저장을 건너뛰었다고 보고한다. 같은 날 재실행은 덮어쓴다.
|
|
36
38
|
- `--skills`는 novelty 비교용 기존 스킬 카탈로그다. 사용 가능한 호스트 스킬 설치 디렉토리를 반복해서 넘긴다.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vault-enrich
|
|
3
|
+
description: Enrich opted-in vault notes with externally produced embeddings, summaries, community labels, inferred links or assertion facts through vmem's hash-bound intake.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Vault enrichment
|
|
7
|
+
|
|
8
|
+
Before the first vmem call, read `references/vault-adapter.md` for runtime discovery and bind a vault id. Pass that `vault` to each tool. Workspace-specific steps in the adapter are optional.
|
|
9
|
+
|
|
10
|
+
Enrichment requires the selected vault's explicit opt-in and an allowed write channel. Inspect effective settings with `vmem settings <vault>`; if enrichment is disabled, stop and let the person decide whether to enable it using the settings preview and confirmation. Respect current secret, PII and path policies when reading, producing and submitting results. Do not send protected content to an external service without authorization. A host agent may perform the model or embedding work; vmem does not call models.
|
|
11
|
+
|
|
12
|
+
## Work and intake
|
|
13
|
+
|
|
14
|
+
1. Call `vmem_enrichment_work` with `vault`, `kind` (one of `embedding`, `summary`, `community-label`, `inferred-link`, `fact`) and optional `limit` (1..100). Each item supplies `path` and `contentHash`; use `next` as `after` for another page. An item with `status: needs-reconciliation` must be resolved before retrying that path and kind.
|
|
15
|
+
2. Read the selected note with `vmem_read`, including continuation pages as needed, and generate a result for that exact content. Do not infer missing note text. If the content has changed since the work item was listed, obtain fresh work and recompute.
|
|
16
|
+
3. Call `vmem_enrichment_intake` with `vault`, `path`, `contentHash`, `kind`, `producer: {skill, version, model}`, `createdAt` (canonical UTC ISO timestamp with milliseconds, such as `2026-11-22T00:00:00.000Z`) and `value`. The producer is caller-supplied and unverified. Values depend on kind:
|
|
17
|
+
- `embedding`: a numeric vector with 1..4096 dimensions. Every value must be finite and remain finite after Float32 conversion; at least one value must remain nonzero after conversion. Each vault sidecar accepts one model and dimension; reuse them. Stored values are rounded to Float32.
|
|
18
|
+
- `summary` or `community-label`: nonempty text up to 8192 UTF-8 bytes.
|
|
19
|
+
- `inferred-link`: `{target: "note-stem"}` for a different flat lowercase note stem. Intake submits an `infer-link` proposal, not a direct note edit. Review the proposal and use the existing preview, fingerprint and confirmation flow to apply it; applying adds a plain body link and the target to `inferred_links` together.
|
|
20
|
+
- `fact`: an array of assertion operations including `assert` or `revise`, with the existing assertion journal's evidence or source requirements. Resolve subjects and heads from the journal; do not fabricate evidence or treat producer metadata as verification.
|
|
21
|
+
4. Inspect the complete receipt, including `ok`, `applied`, nested `receipt`, `issues` and `issue` when present. A stale-hash refusal requires rereading the note, requesting fresh work and recomputing. Do not retry a partial or uncertain fact/link intake until its publication state is resolved.
|
|
22
|
+
|
|
23
|
+
Use `vmem_enrichment_get` with `vault`, `path` and `kind` to inspect status (`current`, `stale`, `missing` or `needs-reconciliation`). Sidecar data is local to the vmem home and is not synced across machines.
|
|
24
|
+
|
|
25
|
+
## Uncertain fact or link intake
|
|
26
|
+
|
|
27
|
+
If the outcome is uncertain or the work/get status is `needs-reconciliation`, do not replay it. Preview `vmem_enrichment_reconcile` with `vault`, `path`, `kind` and a candidate `resolution` (`published` or `not_published`), without `confirm`; its `intakeId` identifies the reservation. Inspect assertion journal entries via `vmem_assertions` for the matching origin intake id, or inspect proposals with `vmem_proposal_list` and `vmem_proposal_show` (the proposal id is the intake id and its agent label is `enrichment:<intakeId>`). Check the available journal/proposal coverage and any nested receipt before deciding. If evidence is incomplete or ambiguous, stop and report it rather than guessing. After inspection, request a fresh preview for the verified resolution, then confirm with its returned `fingerprint`. A `not_published` resolution allows new work; a `published` resolution prevents replay. Respect any refusal and inspect or repair its stated cause first.
|
|
28
|
+
|
|
29
|
+
## Vector reads
|
|
30
|
+
|
|
31
|
+
Use `vmem_similar` with `vault` and `path` for neighbors of a note with a current stored embedding. Before calling `vmem_search` with a vector, use `vmem_enrichment_get` on a current embedding record to read its producer model and vector length. Provide both `model` and `vector` using that model and dimension. If no embeddings are stored, search retains lexical ranking. When embeddings are stored, a model or dimension mismatch is an error; use the recorded model and dimension. A valid query also retains lexical ranking if no current eligible vectors match. Both results are suggestions, not evidence of a factual claim or permission to write links.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { AssertionsReadResult } from "./assertion-read.ts";
|
|
2
|
+
|
|
3
|
+
export interface CoverageWarning { tone: "err" | "warn" | "neutral"; message: string }
|
|
4
|
+
|
|
5
|
+
/** Describe coverage once for both the console and the CLI. */
|
|
6
|
+
export function assertionCoverageWarnings(coverage: AssertionsReadResult["coverage"] | undefined): CoverageWarning[] {
|
|
7
|
+
if (!coverage) return [];
|
|
8
|
+
const out: CoverageWarning[] = [];
|
|
9
|
+
if (coverage.untrusted.length) {
|
|
10
|
+
const count = coverage.untrusted.reduce((n, item) => n + item.entries, 0);
|
|
11
|
+
const details = coverage.untrusted.slice(0, 3).map(u => `${u.segment}#${u.seq}, failed #${u.failedSeq}, ${u.entries} left out: ${u.reason}`).join("; ");
|
|
12
|
+
out.push({ tone: "err", message: `${count} journal ${count === 1 ? "entry is" : "entries are"} untrusted and left out (${details}); run \`vmem assertions <vault> --history --json\` and inspect the journal segments` });
|
|
13
|
+
}
|
|
14
|
+
if (coverage.unsupported.length) {
|
|
15
|
+
const count = coverage.unsupported.reduce((n, item) => n + item.entries, 0);
|
|
16
|
+
const details = coverage.unsupported.slice(0, 3).map(u => `${u.segment}#${u.seq}, failed #${u.failedSeq}, ${u.entries} left out`).join("; ");
|
|
17
|
+
out.push({ tone: "warn", message: `${count} journal ${count === 1 ? "entry is" : "entries are"} left out after an unsupported schema (${details}); upgrade vmem to read them` });
|
|
18
|
+
}
|
|
19
|
+
if (coverage.tornTail.length) out.push({ tone: "warn", message: `torn journal tail in ${coverage.tornTail.join(", ")}: the incomplete last entry is ignored; the next append repairs it` });
|
|
20
|
+
for (const batch of coverage.partialBatch) out.push({ tone: "warn", message: `batch ${batch.segment}:${batch.seq} has ${batch.entries} of ${batch.size} entries; all ${batch.entries} are left out; resubmit the batch` });
|
|
21
|
+
if (coverage.purged) out.push({ tone: "neutral", message: `${coverage.purged} purged ${coverage.purged === 1 ? "payload is" : "payloads are"} not shown` });
|
|
22
|
+
if (coverage.unsynced) out.push({ tone: "warn", message: `${coverage.unsynced} assertion ${coverage.unsynced === 1 ? "file is" : "files are"} not committed; run \`vmem sync\` to share them` });
|
|
23
|
+
if (coverage.unsynced === null) out.push({ tone: "neutral", message: "journal sync state is unknown (no Git repository or Git unavailable)" });
|
|
24
|
+
if (coverage.indexIssue) out.push({ tone: "warn", message: coverage.indexIssue });
|
|
25
|
+
return out;
|
|
26
|
+
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
/** CLI surface for the shared assertion read provider. */
|
|
2
2
|
import { readAssertions } from "./assertion-read.ts";
|
|
3
|
+
import { assertionCoverageWarnings } from "./assertion-coverage.ts";
|
|
3
4
|
import { scanAssertionExposure, writeReplaceFile, type ExposureReceipt } from "./assertion-exposure.ts";
|
|
4
5
|
import { purgeAssertions, type PurgeReceipt } from "./assertions.ts";
|
|
5
6
|
import { blocks, clean, heading, issueTable, nextCommand, paragraph, plural, status, table, PLAIN, UsageError, type TextOptions } from "./text-output.ts";
|
|
@@ -34,8 +35,7 @@ export function runAssertionsCommand(args: string[], home: string, env: NodeJS.P
|
|
|
34
35
|
const rows = result.items.map(item => [clean(item.subject), clean(item.relation), item.answer ?? "-", typeof item.value === "string" ? clean(item.value) : item.value ? "withheld" : "-", item.id]);
|
|
35
36
|
return { text: blocks(heading(`Assertions in ${clean(result.vault)}`, text), table(["SUBJECT", "RELATION", "ANSWER", "VALUE", "ID"], rows, text),
|
|
36
37
|
result.truncated ? status("pending", `more results: rerun with --cursor ${result.continuation}`, text) : status("ok", `${result.items.length} assertion(s) shown`, text),
|
|
37
|
-
result.coverage.
|
|
38
|
-
result.coverage.indexIssue ? status("warn", result.coverage.indexIssue, text) : undefined), code: 0 };
|
|
38
|
+
...assertionCoverageWarnings(result.coverage).map(w => status(w.tone === "err" ? "fail" : w.tone === "warn" ? "warn" : "unknown", w.message, text))), code: 0 };
|
|
39
39
|
}
|
|
40
40
|
|
|
41
41
|
/** What a purge receipt means in words; `argv` is the command without `vmem`, so the confirm line is pasteable. */
|
package/src/assertions.ts
CHANGED
|
@@ -63,9 +63,9 @@ export interface SegmentReport {
|
|
|
63
63
|
verifiedBytes: number;
|
|
64
64
|
size: number;
|
|
65
65
|
tornTail: boolean;
|
|
66
|
-
partialBatch: { seq: number } | null;
|
|
67
|
-
untrusted: { seq: number; reason: string } | null;
|
|
68
|
-
unsupported: { seq: number; version: unknown } | null;
|
|
66
|
+
partialBatch: { seq: number; entries: number; size: number } | null;
|
|
67
|
+
untrusted: { seq: number; failedSeq: number; entries: number; reason: string } | null;
|
|
68
|
+
unsupported: { seq: number; failedSeq: number; entries: number; version: unknown } | null;
|
|
69
69
|
}
|
|
70
70
|
export interface VerifiedJournal { present: boolean; segments: SegmentReport[]; ignored: string[]; bytes: number; entries: number }
|
|
71
71
|
|
|
@@ -86,8 +86,8 @@ export interface AssertionAnswerSet {
|
|
|
86
86
|
pin: { segment: string; seq: number; hash: string }[];
|
|
87
87
|
coverage: {
|
|
88
88
|
journal: "present" | "absent"; beforeFirstEntry: boolean;
|
|
89
|
-
untrusted: { segment: string; seq: number; reason: string }[]; unsupported: { segment: string; seq: number }[];
|
|
90
|
-
tornTail: string[]; partialBatch: { segment: string; seq: number }[]; purged: number;
|
|
89
|
+
untrusted: { segment: string; seq: number; failedSeq: number; entries: number; reason: string }[]; unsupported: { segment: string; seq: number; failedSeq: number; entries: number }[];
|
|
90
|
+
tornTail: string[]; partialBatch: { segment: string; seq: number; entries: number; size: number }[]; purged: number;
|
|
91
91
|
};
|
|
92
92
|
items: AssertionItem[];
|
|
93
93
|
overlaps: { subject: string; relation: string; ids: string[]; possible?: true }[];
|
|
@@ -218,12 +218,12 @@ export function verifySegment(segment: string, bytes: Buffer): SegmentReport {
|
|
|
218
218
|
const newline = bytes.indexOf(10, offset);
|
|
219
219
|
if (newline < 0) { report.tornTail = true; break; }
|
|
220
220
|
const seq = report.entries.length + pending.length + 1, raw = bytes.subarray(offset, newline);
|
|
221
|
-
const fail = (reason: string) => { report.untrusted = { seq, reason }; };
|
|
221
|
+
const fail = (reason: string) => { report.untrusted = { seq, failedSeq: seq, entries: 0, reason }; };
|
|
222
222
|
let entry: JournalEntry;
|
|
223
223
|
try {
|
|
224
224
|
const text = decoder.decode(raw), parsed = JSON.parse(text) as Record<string, unknown>;
|
|
225
225
|
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) { fail("not an object"); break; }
|
|
226
|
-
if (parsed.v !== ASSERTION_SCHEMA_VERSION) { report.unsupported = { seq, version: parsed.v }; break; }
|
|
226
|
+
if (parsed.v !== ASSERTION_SCHEMA_VERSION) { report.unsupported = { seq, failedSeq: seq, entries: 0, version: parsed.v }; break; }
|
|
227
227
|
if (canonical(parsed) !== text) { fail("not canonical JSON"); break; }
|
|
228
228
|
const problem = shapeProblem(parsed);
|
|
229
229
|
if (problem) { fail(problem); break; }
|
|
@@ -248,8 +248,14 @@ export function verifySegment(segment: string, bytes: Buffer): SegmentReport {
|
|
|
248
248
|
report.entries.push(...pending.map(item => item.entry)); report.verifiedBytes = offset; pending = [];
|
|
249
249
|
}
|
|
250
250
|
}
|
|
251
|
-
if (pending.length && !report.untrusted && !report.unsupported) report.partialBatch = { seq: pending[0]!.entry.seq };
|
|
252
|
-
|
|
251
|
+
if (pending.length && !report.untrusted && !report.unsupported) report.partialBatch = { seq: pending[0]!.entry.seq, entries: pending.length, size: pending[0]!.entry.batch.size };
|
|
252
|
+
if (report.untrusted || report.unsupported) {
|
|
253
|
+
let entries = 0;
|
|
254
|
+
for (let i = report.verifiedBytes; i < bytes.length; i++) if (bytes[i] === 10) entries++;
|
|
255
|
+
const failure = report.untrusted ?? report.unsupported!;
|
|
256
|
+
failure.entries = entries;
|
|
257
|
+
if (pending.length) failure.seq = pending[0]!.entry.seq;
|
|
258
|
+
}
|
|
253
259
|
const tail = report.entries.at(-1);
|
|
254
260
|
if (tail) report.tail = { seq: tail.seq, hash: tail.hash, recordedAt: tail.recorded_at };
|
|
255
261
|
return report;
|
|
@@ -289,7 +295,7 @@ export function readJournal(vaultPath: string, denyPaths: readonly string[] = []
|
|
|
289
295
|
|
|
290
296
|
/** `depth` is the longest parent chain below the entry, so a parent always sorts before its child. */
|
|
291
297
|
interface Kept { entry: JournalEntry; effective: string; inverted: boolean; depth: number; assertionId?: string }
|
|
292
|
-
interface Resolved { kept: Map<string, Kept>; untrusted: { segment: string; seq: number; reason: string }[] }
|
|
298
|
+
interface Resolved { kept: Map<string, Kept>; untrusted: { segment: string; seq: number; failedSeq: number; entries: number; reason: string }[] }
|
|
293
299
|
/** Steps 2: effective record times across segments; an entry whose parent is missing, untrusted or foreign is untrusted. */
|
|
294
300
|
function resolveEntries(journal: VerifiedJournal): Resolved {
|
|
295
301
|
const byHash = new Map<string, JournalEntry>();
|
|
@@ -321,7 +327,7 @@ function resolveEntries(journal: VerifiedJournal): Resolved {
|
|
|
321
327
|
const kept = new Map<string, Kept>(), untrusted: Resolved["untrusted"] = [];
|
|
322
328
|
for (const segment of journal.segments) for (const entry of segment.entries) {
|
|
323
329
|
const result = resolve(entry);
|
|
324
|
-
if (typeof result === "string") untrusted.push({ segment: entry.seg, seq: entry.seq, reason: result });
|
|
330
|
+
if (typeof result === "string") untrusted.push({ segment: entry.seg, seq: entry.seq, failedSeq: entry.seq, entries: 1, reason: result });
|
|
325
331
|
else kept.set(entry.hash, result);
|
|
326
332
|
}
|
|
327
333
|
return { kept, untrusted };
|
|
@@ -446,10 +452,10 @@ export function evaluateAssertions(journal: VerifiedJournal, query: AssertionQue
|
|
|
446
452
|
coverage: {
|
|
447
453
|
journal: journal.present ? "present" : "absent",
|
|
448
454
|
beforeFirstEntry: !!asOf && all.length > 0 && kept.length === 0,
|
|
449
|
-
untrusted: [...journal.segments.filter(s => s.untrusted).map(s => ({ segment: s.segment,
|
|
450
|
-
unsupported: journal.segments.filter(s => s.unsupported).map(s => ({ segment: s.segment, seq: s.unsupported!.seq })),
|
|
455
|
+
untrusted: [...journal.segments.filter(s => s.untrusted).map(s => ({ segment: s.segment, ...s.untrusted! })), ...resolved.untrusted],
|
|
456
|
+
unsupported: journal.segments.filter(s => s.unsupported).map(s => ({ segment: s.segment, seq: s.unsupported!.seq, failedSeq: s.unsupported!.failedSeq, entries: s.unsupported!.entries })),
|
|
451
457
|
tornTail: journal.segments.filter(s => s.tornTail).map(s => s.segment),
|
|
452
|
-
partialBatch: journal.segments.filter(s => s.partialBatch).map(s => ({ segment: s.segment,
|
|
458
|
+
partialBatch: journal.segments.filter(s => s.partialBatch).map(s => ({ segment: s.segment, ...s.partialBatch! })),
|
|
453
459
|
purged,
|
|
454
460
|
},
|
|
455
461
|
items, overlaps,
|
package/src/skills-install.ts
CHANGED
|
@@ -9,7 +9,7 @@ import { version } from "../package.json";
|
|
|
9
9
|
import type { SetupMode, SetupTarget } from "./setup.ts";
|
|
10
10
|
import { shellWord } from "./text-output.ts";
|
|
11
11
|
|
|
12
|
-
export const SKILL_NAMES = ["vault-connect", "vault-extract", "vault-graph", "vault-learn", "vault-lint", "vault-refactor", "vault-remember", "vault-rethink", "vault-stats", "vault-sync", "vault-update", "vmem-status", "skill-mine"] as const;
|
|
12
|
+
export const SKILL_NAMES = ["vault-connect", "vault-enrich", "vault-extract", "vault-graph", "vault-learn", "vault-lint", "vault-refactor", "vault-remember", "vault-rethink", "vault-stats", "vault-sync", "vault-update", "vmem-status", "skill-mine"] as const;
|
|
13
13
|
const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
|
|
14
14
|
const MARKER = ".vmem-skill.json", MAX_FILE = 2 * 1024 * 1024, MAX_BYTES = 16 * 1024 * 1024, MAX_FILES = 512;
|
|
15
15
|
export interface SkillAction { name: string; path: string; change: "install" | "replace" | "remove" | "unchanged" | "absent" | "modified" | "foreign" | "refused"; reason?: string }
|
package/src/skills-mine.ts
CHANGED
|
@@ -47,7 +47,7 @@ export interface MineOptions {
|
|
|
47
47
|
export interface MineResult {
|
|
48
48
|
vault: string; days: number; since: string; projects: string[];
|
|
49
49
|
records: Record<RecordSource, number>;
|
|
50
|
-
dropped: { secret: number; policy: number; oversized: number; duplicate: number; unreadable: number; truncatedCapture: number; malformedRecord: number;
|
|
50
|
+
dropped: { synthetic: number; overCap: number; secret: number; policy: number; oversized: number; duplicate: number; unreadable: number; truncatedCapture: number; malformedRecord: number;
|
|
51
51
|
recordOutsideWindow: number; recordOutsideCapped: number; recordOutsideUnavailable: number };
|
|
52
52
|
graph: { nodes: number; edges: number; communities: number; partitioner: "leiden" };
|
|
53
53
|
godNodes: { id: string; degree: number }[];
|
|
@@ -120,6 +120,14 @@ export function maskText(text: string, people: readonly string[]): string {
|
|
|
120
120
|
}
|
|
121
121
|
return masked;
|
|
122
122
|
}
|
|
123
|
+
/** Host runtimes inject these envelopes through UserPromptSubmit; they are not human prompts. */
|
|
124
|
+
const SYNTHETIC_PREFIXES = ["<task-notification>", "<task-notification ", "<channel ", "<agent-message "] as const;
|
|
125
|
+
/** True for a capture UserPromptSubmit record whose text, after leading whitespace, starts with a synthetic envelope. */
|
|
126
|
+
export function isSyntheticPrompt(record: Pick<MineRecord, "source" | "kind" | "text">): boolean {
|
|
127
|
+
if (record.source !== "capture" || record.kind !== "UserPromptSubmit") return false;
|
|
128
|
+
const text = record.text.trimStart();
|
|
129
|
+
return SYNTHETIC_PREFIXES.some(prefix => text.startsWith(prefix));
|
|
130
|
+
}
|
|
123
131
|
/** The vault config's `piiPatterns` (regular expressions, as everywhere in vmem) redact sample text from every source to `[PII]`. */
|
|
124
132
|
export function redactPatterns(text: string, patterns: readonly string[]): string {
|
|
125
133
|
let out = text;
|
|
@@ -320,24 +328,30 @@ export interface MineInputs {
|
|
|
320
328
|
vocab: { actions: VocabEntry[]; objects: VocabEntry[] }; registry: RegistryProject[]; skills: SkillEntry[];
|
|
321
329
|
minSize: number; minNovelty: number; today: string; piiPatterns?: string[];
|
|
322
330
|
dropped?: Partial<MineResult["dropped"]>;
|
|
331
|
+
/** Kept-set bounds; default MAX_RECORDS and MAX_TOTAL_BYTES. */
|
|
332
|
+
limits?: { records?: number; bytes?: number };
|
|
323
333
|
}
|
|
324
334
|
/** The pure part: screen, mask, match, cluster, score and render. */
|
|
325
335
|
export function mineRecords(input: MineInputs): MineResult {
|
|
326
|
-
const dropped: MineResult["dropped"] = { secret: 0, policy: 0, oversized: 0, duplicate: 0, unreadable: 0, truncatedCapture: 0, malformedRecord: 0, recordOutsideWindow: 0, recordOutsideCapped: 0, recordOutsideUnavailable: 0, ...input.dropped };
|
|
336
|
+
const dropped: MineResult["dropped"] = { synthetic: 0, overCap: 0, secret: 0, policy: 0, oversized: 0, duplicate: 0, unreadable: 0, truncatedCapture: 0, malformedRecord: 0, recordOutsideWindow: 0, recordOutsideCapped: 0, recordOutsideUnavailable: 0, ...input.dropped };
|
|
327
337
|
const ordered = [...input.records].sort((a, b) => compare(a.at, b.at) || compare(a.source, b.source) || compare(a.project, b.project) || compare(a.text, b.text));
|
|
328
|
-
const kept: MineRecord[] = [], texts = new Set<string>();
|
|
338
|
+
const kept: MineRecord[] = [], sizes: number[] = [], texts = new Set<string>();
|
|
329
339
|
let total = 0;
|
|
330
340
|
for (const record of ordered) {
|
|
341
|
+
if (isSyntheticPrompt(record)) { dropped.synthetic++; continue; }
|
|
331
342
|
const text = record.text.trim();
|
|
332
343
|
if (SECRET_PATTERNS.some(pattern => pattern.test(text))) { dropped.secret++; continue; }
|
|
333
344
|
const bytes = Buffer.byteLength(text);
|
|
334
345
|
if (bytes > MAX_RECORD_BYTES) { dropped.oversized++; continue; }
|
|
335
346
|
if (texts.has(text)) { dropped.duplicate++; continue; }
|
|
336
|
-
texts.add(text); kept.push({ ...record, text });
|
|
347
|
+
texts.add(text); kept.push({ ...record, text }); sizes.push(bytes);
|
|
337
348
|
total += bytes;
|
|
338
|
-
if (kept.length > MAX_RECORDS) throw new Error(`skills mine: more than ${MAX_RECORDS} records; narrow --days or --project`);
|
|
339
|
-
if (total > MAX_TOTAL_BYTES) throw new Error("skills mine: records exceed 64 MiB; narrow --days or --project");
|
|
340
349
|
}
|
|
350
|
+
// Over a bound, keep the newest records: `ordered` is oldest first, so leave out from the front.
|
|
351
|
+
const maxRecords = input.limits?.records ?? MAX_RECORDS, maxBytes = input.limits?.bytes ?? MAX_TOTAL_BYTES;
|
|
352
|
+
let cut = 0;
|
|
353
|
+
while (cut < kept.length && (kept.length - cut > maxRecords || total > maxBytes)) total -= sizes[cut++]!;
|
|
354
|
+
if (cut) { kept.splice(0, cut); dropped.overCap += cut; }
|
|
341
355
|
const index = buildSurfaceIndex(input.vocab.actions, input.vocab.objects, input.registry), people = allPeople(input.registry);
|
|
342
356
|
const recordIds = new Map<string, MineRecord>(), neighbors = new Map<string, Set<string>>(), edges: [string, string][] = [];
|
|
343
357
|
const width = String(kept.length).length;
|
|
@@ -398,7 +412,8 @@ export function renderReport(result: Omit<MineResult, "report">, today: string,
|
|
|
398
412
|
`# Skill Candidates (${today}, memory-based)`, "",
|
|
399
413
|
`- corpus: ${total} records / ${result.days} days (curated ${result.records.curated}, capture ${result.records.capture}, vault ${result.records.vault})`,
|
|
400
414
|
`- projects: ${result.projects.length}`,
|
|
401
|
-
`-
|
|
415
|
+
...(result.dropped.overCap ? [`- over cap: kept the newest ${total} records, left out ${result.dropped.overCap} older ones over the record or byte bound; narrow --days or --project to mine them`] : []),
|
|
416
|
+
`- dropped: synthetic ${result.dropped.synthetic}, secret ${result.dropped.secret}, policy ${result.dropped.policy}, oversized ${result.dropped.oversized}, duplicate ${result.dropped.duplicate}, unreadable ${result.dropped.unreadable}, malformed Record ${result.dropped.malformedRecord}`,
|
|
402
417
|
`- truncated capture machine shards: ${result.dropped.truncatedCapture}; rows of any event beyond maxReadRows were not read`,
|
|
403
418
|
`- Record rows outside the read window: ${result.dropped.recordOutsideCapped ? "at least " : ""}${result.dropped.recordOutsideWindow}${result.dropped.recordOutsideUnavailable ? `; ${result.dropped.recordOutsideUnavailable} truncated ${result.dropped.recordOutsideUnavailable === 1 ? "shard" : "shards"} could not be counted (no Record index yet, or no bounded index plan; an off-hook \`amem search\` in the project builds a missing index)` : ""}`,
|
|
404
419
|
`- graph: ${result.graph.nodes} nodes, ${result.graph.edges} edges, ${result.graph.communities} communities (deterministic Leiden)`, "",
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import type { AnalysisSnapshot } from "../analysis-types.ts";
|
|
3
|
+
import { scalarText } from "../analysis-yaml.ts";
|
|
4
|
+
import { buildGraph, collectUnresolvedGraph, codePointCompare, graphFrontmatter, pythonTitle } from "../vault-graph.ts";
|
|
5
|
+
import type { GraphEdge } from "../vault-graph.ts";
|
|
6
|
+
import type { GraphSnapshotPage, GraphNodeColumns, GraphEdgeColumns } from "./panel-types.ts";
|
|
7
|
+
|
|
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
|
+
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[] }
|
|
11
|
+
const MAX_BYTES = 1_048_576 - 32;
|
|
12
|
+
const MAX_NODES = 10_000, MAX_EDGES = 100_000;
|
|
13
|
+
const scalar = (v: unknown): string | null => scalarText(v) ?? (typeof v === "string" || typeof v === "number" || typeof v === "boolean" || typeof v === "bigint" ? String(v) : null);
|
|
14
|
+
const token = (vault: string, revision: string, kind: string, offset: number): string => Buffer.from(JSON.stringify([1, vault, revision, kind, offset])).toString("base64url");
|
|
15
|
+
export const encodeGraphPage = (assembly: GraphSnapshotAssembly, page: GraphSnapshotPage): string => token(assembly.vault, assembly.revision, page.kind, page.offset);
|
|
16
|
+
export function resolveGraphPage(assembly: GraphSnapshotAssembly, page?: string): GraphSnapshotPage {
|
|
17
|
+
if (page === undefined) return assembly.pages[0]!;
|
|
18
|
+
try {
|
|
19
|
+
const decoded: unknown = JSON.parse(Buffer.from(page, "base64url").toString("utf8"));
|
|
20
|
+
if (!Array.isArray(decoded) || decoded.length !== 5 || decoded[0] !== 1 || decoded[1] !== assembly.vault || decoded[2] !== assembly.revision || (decoded[3] !== "nodes" && decoded[3] !== "edges") || !Number.isSafeInteger(decoded[4]) || decoded[4] < 0 || token(decoded[1], decoded[2], decoded[3], decoded[4]) !== page) throw new Error();
|
|
21
|
+
const found = assembly.pages.find(p => p.kind === decoded[3] && p.offset === decoded[4]);
|
|
22
|
+
if (found) return found;
|
|
23
|
+
} catch { /* Invalid tokens all receive the same refusal. */ }
|
|
24
|
+
throw new Error("graph page is invalid or expired; restart from the first page");
|
|
25
|
+
}
|
|
26
|
+
function nodeColumns(rows: NodeRow[]): GraphNodeColumns {
|
|
27
|
+
return { id: rows.map(r => r.id), label: rows.map(r => r.label), type: rows.map(r => r.type), domain: rows.map(r => r.domain), source_file: rows.map(r => r.source_file), community: rows.map(r => r.community), degree: rows.map(r => r.degree), updated: rows.map(r => r.updated), date: rows.map(r => r.date), placeholder: rows.map(r => r.placeholder), description: rows.map(r => r.description), confidence: rows.map(r => r.confidence), topics: rows.map(r => r.topics) };
|
|
28
|
+
}
|
|
29
|
+
export function graphEdgeColumns(rows: GraphEdgeRow[]): GraphEdgeColumns {
|
|
30
|
+
const relations = [...new Set(rows.map(r => r.relation))], tags = rows.map(r => r.confidence_tag), confidence = rows.map(r => r.confidence);
|
|
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
|
+
}
|
|
33
|
+
export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string): GraphSnapshotAssembly {
|
|
34
|
+
const graph = buildGraph(snapshot), unresolved = collectUnresolvedGraph(snapshot);
|
|
35
|
+
const grouped = new Map<string, GraphEdge[]>();
|
|
36
|
+
for (const edge of unresolved) { const list = grouped.get(edge.target) ?? []; list.push(edge); grouped.set(edge.target, list); }
|
|
37
|
+
const notes = new Map(snapshot.notes.map(n => [n.path.replace(/^notes\//, "").slice(0, -3), n]));
|
|
38
|
+
const nodes: NodeRow[] = graph.nodes.map(n => {
|
|
39
|
+
const fm = graphFrontmatter(notes.get(n.id)!.source);
|
|
40
|
+
return { ...n, description: n.description || null, confidence: n.confidence || null, topics: n.topics || null, updated: scalar(fm.updated), date: scalar(fm.created) ?? scalar(fm.date), placeholder: false };
|
|
41
|
+
});
|
|
42
|
+
const extra: GraphEdge[] = [];
|
|
43
|
+
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; }
|
|
46
|
+
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
|
+
extra.push(...edges);
|
|
48
|
+
}
|
|
49
|
+
extra.sort((a, b) => codePointCompare(a.source, b.source) || codePointCompare(a.target, b.target));
|
|
50
|
+
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 }));
|
|
52
|
+
const metadata = { directed: graph.directed, multigraph: graph.multigraph, ...graph.graph };
|
|
53
|
+
const totals = { nodes: nodes.length, edges: edges.length, placeholders: nodes.length - graph.nodes.length, placeholdersOmitted: omitted };
|
|
54
|
+
const revision = createHash("sha256").update(JSON.stringify([1, vault, metadata, totals, nodes, edges])).digest("hex");
|
|
55
|
+
const pages: GraphSnapshotPage[] = [];
|
|
56
|
+
const envelope = (kind: "nodes" | "edges", offset: number, count: number, columns: GraphNodeColumns | GraphEdgeColumns): GraphSnapshotPage => {
|
|
57
|
+
const total = kind === "nodes" ? nodes.length : edges.length;
|
|
58
|
+
const next = offset + count < total ? token(vault, revision, kind, offset + count)
|
|
59
|
+
: kind === "nodes" && edges.length ? token(vault, revision, "edges", 0) : null;
|
|
60
|
+
return { schema: 1, vault, revision, graph: metadata, totals, kind, offset, count, columns, next };
|
|
61
|
+
};
|
|
62
|
+
// Binary search each page boundary: every candidate is measured before its rows are accepted.
|
|
63
|
+
function paginate<T>(kind: "nodes" | "edges", rows: T[], columns: (items: T[]) => GraphNodeColumns | GraphEdgeColumns): void {
|
|
64
|
+
let offset = 0;
|
|
65
|
+
while (offset < rows.length || (kind === "nodes" && !pages.length)) {
|
|
66
|
+
let low = 0, high = rows.length - offset;
|
|
67
|
+
const all = envelope(kind, offset, high, columns(rows.slice(offset)));
|
|
68
|
+
if (Buffer.byteLength(JSON.stringify(all)) <= MAX_BYTES) { pages.push(all); break; }
|
|
69
|
+
if (!high) throw new Error("graph page envelope exceeds the page budget; shorten the vault id and retry");
|
|
70
|
+
// The last page can be smaller because it has no next token; it was checked above.
|
|
71
|
+
high--;
|
|
72
|
+
while (low < high) {
|
|
73
|
+
const mid = Math.ceil((low + high) / 2), candidate = envelope(kind, offset, mid, columns(rows.slice(offset, offset + mid)));
|
|
74
|
+
if (Buffer.byteLength(JSON.stringify(candidate)) <= MAX_BYTES) low = mid; else high = mid - 1;
|
|
75
|
+
}
|
|
76
|
+
if (!low && rows.length > offset) {
|
|
77
|
+
const row = rows[offset] as NodeRow | GraphEdgeRow;
|
|
78
|
+
const id = "id" in row ? row.id : nodes[row.source]?.id ?? "unknown";
|
|
79
|
+
throw new Error(`graph row ${id.slice(0, 80)} exceeds the page budget; shorten its metadata and retry`);
|
|
80
|
+
}
|
|
81
|
+
pages.push(envelope(kind, offset, low, columns(rows.slice(offset, offset + low))));
|
|
82
|
+
offset += low;
|
|
83
|
+
if (!low) break;
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
paginate("nodes", nodes, nodeColumns); paginate("edges", edges, graphEdgeColumns);
|
|
87
|
+
return { vault, revision, pages };
|
|
88
|
+
}
|
package/src/ui/panel-types.ts
CHANGED
|
@@ -9,8 +9,9 @@ import type { ChangesResult, HistoryResult } from "../vault-history.ts";
|
|
|
9
9
|
|
|
10
10
|
export type ProposalState = "pending" | "applied" | "rejected" | "apply_unknown";
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
export
|
|
12
|
+
export { assertionCoverageWarnings } from "../assertion-coverage.ts";
|
|
13
|
+
export type { CoverageWarning } from "../assertion-coverage.ts";
|
|
14
|
+
import type { CoverageWarning } from "../assertion-coverage.ts";
|
|
14
15
|
|
|
15
16
|
/** `proposals` panel: params `vault`, `state` (default pending), `after` page cursor, `id` to show one proposal. */
|
|
16
17
|
export interface ProposalsSnapshot {
|
|
@@ -21,21 +22,6 @@ export interface ProposalsSnapshot {
|
|
|
21
22
|
error?: string;
|
|
22
23
|
}
|
|
23
24
|
|
|
24
|
-
/** Coverage notices for an assertion read: anything short of a fully verified, synced and indexed journal is named with its next step. */
|
|
25
|
-
export function assertionCoverageWarnings(coverage: AssertionsReadResult["coverage"] | undefined): CoverageWarning[] {
|
|
26
|
-
if (!coverage) return [];
|
|
27
|
-
const out: CoverageWarning[] = [];
|
|
28
|
-
if (coverage.untrusted.length) out.push({ tone: "err", message: `${coverage.untrusted.length} journal ${coverage.untrusted.length === 1 ? "entry is" : "entries are"} untrusted and left out (${coverage.untrusted.slice(0, 3).map(u => `${u.segment}#${u.seq}: ${u.reason}`).join("; ")}); run \`vmem assertions <vault> --history --json\` and inspect the journal segments` });
|
|
29
|
-
if (coverage.unsupported.length) out.push({ tone: "warn", message: `${coverage.unsupported.length} journal ${coverage.unsupported.length === 1 ? "entry uses" : "entries use"} an unsupported schema and ${coverage.unsupported.length === 1 ? "is" : "are"} left out; upgrade vmem to read them` });
|
|
30
|
-
if (coverage.tornTail.length) out.push({ tone: "warn", message: `torn journal tail in ${coverage.tornTail.join(", ")}: the incomplete last entry is ignored; the next append repairs it` });
|
|
31
|
-
if (coverage.partialBatch.length) out.push({ tone: "warn", message: `${coverage.partialBatch.length} ${coverage.partialBatch.length === 1 ? "entry belongs" : "entries belong"} to an incomplete batch and ${coverage.partialBatch.length === 1 ? "is" : "are"} left out; resubmit the batch` });
|
|
32
|
-
if (coverage.purged) out.push({ tone: "neutral", message: `${coverage.purged} purged ${coverage.purged === 1 ? "payload is" : "payloads are"} not shown` });
|
|
33
|
-
if (coverage.unsynced) out.push({ tone: "warn", message: `${coverage.unsynced} assertion ${coverage.unsynced === 1 ? "file is" : "files are"} not committed; run \`vmem sync\` to share them` });
|
|
34
|
-
if (coverage.unsynced === null) out.push({ tone: "neutral", message: "journal sync state is unknown (no Git repository or Git unavailable)" });
|
|
35
|
-
if (coverage.indexIssue) out.push({ tone: "warn", message: coverage.indexIssue });
|
|
36
|
-
return out;
|
|
37
|
-
}
|
|
38
|
-
|
|
39
25
|
/** `assertions` panel: params `vault`, `subject`, `relation`, `at`, `asOf`, `history`, `cursor`, as `vmem_assertions`. */
|
|
40
26
|
export interface AssertionsSnapshot {
|
|
41
27
|
vault: string | null;
|
|
@@ -53,3 +39,24 @@ export interface HistorySnapshot {
|
|
|
53
39
|
changes: ChangesResult | null;
|
|
54
40
|
error?: string;
|
|
55
41
|
}
|
|
42
|
+
|
|
43
|
+
export interface GraphNodeColumns {
|
|
44
|
+
id: string[]; label: string[]; type: (string | null)[]; domain: (string | null)[];
|
|
45
|
+
source_file: (string | null)[]; community: (number | null)[]; degree: number[];
|
|
46
|
+
updated: (string | null)[]; date: (string | null)[]; placeholder: boolean[];
|
|
47
|
+
description: (string | null)[]; confidence: (string | null)[]; topics: (string | null)[];
|
|
48
|
+
}
|
|
49
|
+
export interface GraphEdgeColumns {
|
|
50
|
+
source: number[]; target: number[]; relations: string[]; relation: number[];
|
|
51
|
+
field: (string | null)[]; rel: (string | null)[];
|
|
52
|
+
confidence_tag: string | string[]; confidence: number | number[];
|
|
53
|
+
}
|
|
54
|
+
export interface GraphSnapshotPage {
|
|
55
|
+
schema: 1; vault: string; revision: string;
|
|
56
|
+
graph: { directed: boolean; multigraph: boolean; partitioner: string; resolution: number; modularity: number; iterations: number; max_iterations: number };
|
|
57
|
+
totals: { nodes: number; edges: number; placeholders: number; placeholdersOmitted: number };
|
|
58
|
+
kind: "nodes" | "edges"; offset: number; count: number;
|
|
59
|
+
columns: GraphNodeColumns | GraphEdgeColumns; next: string | null;
|
|
60
|
+
}
|
|
61
|
+
/** The provider attaches a numeric cursor for console conditional polling. */
|
|
62
|
+
export type GraphPanelPage = GraphSnapshotPage & { cursor: number };
|
package/src/ui/panel.js
CHANGED
|
@@ -21,6 +21,16 @@ export default (host) => {
|
|
|
21
21
|
const assertionQuery = () => Object.fromEntries(["subject", "relation", "at", "asOf", "history", "limit"].filter((k) => params[k] !== undefined && params[k] !== "").map((k) => [k, params[k]]));
|
|
22
22
|
|
|
23
23
|
const views = {
|
|
24
|
+
graph(s) {
|
|
25
|
+
if (s.error) return [ui.notice(s.error, "err"), ...(params.page ? [h("div", { class: "vmem-bar" }, ui.button("First page", () => go("graph")))] : [])];
|
|
26
|
+
const graph = s.graph ?? {}, totals = s.totals ?? {};
|
|
27
|
+
return [h("section", { class: "card" }, h("h2", { text: `Graph · ${s.vault}` }),
|
|
28
|
+
h("p", { text: `Revision: ${s.revision}` }),
|
|
29
|
+
h("p", { text: `Nodes: ${totals.nodes} · edges: ${totals.edges} · placeholders: ${totals.placeholders} · omitted: ${totals.placeholdersOmitted}` }),
|
|
30
|
+
h("p", { text: `${graph.partitioner} · resolution ${graph.resolution} · modularity ${graph.modularity} · iterations ${graph.iterations}/${graph.max_iterations}` }),
|
|
31
|
+
h("p", { text: `${s.kind} · offset ${s.offset} · ${s.count} of ${totals[s.kind]} rows · ${s.next !== null ? "more pages follow" : "last page"}` })),
|
|
32
|
+
h("div", { class: "vmem-bar" }, ...(params.page ? [ui.button("First page", () => go("graph"))] : []), ...(s.next ? [ui.button("Next page", () => go("graph", { page: s.next }))] : []))];
|
|
33
|
+
},
|
|
24
34
|
settings(s) {
|
|
25
35
|
if (s.error) return [ui.notice(s.error, "err")];
|
|
26
36
|
const defaultVault = h("input", { type: "text", name: "defaultVault", value: s.defaultVault ?? "", class: "vmem-input", "aria-label": "Default vault" });
|
package/src/ui/plugin.ts
CHANGED
|
@@ -11,6 +11,8 @@ 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";
|
|
15
|
+
import type { GraphSnapshotAssembly } from "./graph-snapshot.ts";
|
|
14
16
|
import { assertionCoverageWarnings } from "./panel-types.ts";
|
|
15
17
|
import type { AssertionsReadResult } from "../assertion-read.ts";
|
|
16
18
|
import { createInboxSnapshot } from "./inbox.ts";
|
|
@@ -22,6 +24,38 @@ const asset = (name: string) => readFileSync(new URL(name, import.meta.url), "ut
|
|
|
22
24
|
const VERSION = (JSON.parse(asset("../../package.json")) as { version: string }).version;
|
|
23
25
|
const LINT_ERRORS: LintCode[] = ["L01", "L02", "L13"];
|
|
24
26
|
const CACHE_MS = 60_000;
|
|
27
|
+
/** Revision-bound assemblies, shared between concurrent requests and bounded to two vaults. */
|
|
28
|
+
export function createGraphSnapshotCache(revision: () => number, load: (vault: string) => Promise<GraphSnapshotAssembly>, now: () => number = Date.now) {
|
|
29
|
+
type Entry = { stamp: number; at: number; assembly: GraphSnapshotAssembly; cursors: Map<string, number> };
|
|
30
|
+
const cache = new Map<string, Entry>(), flights = new Map<string, Promise<Entry>>();
|
|
31
|
+
return {
|
|
32
|
+
async snapshot(vault: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
|
|
33
|
+
let entry: Entry | undefined;
|
|
34
|
+
for (let attempts = 0; attempts < 3; attempts++) {
|
|
35
|
+
const stamp = revision(), hit = cache.get(vault);
|
|
36
|
+
if (hit && hit.stamp === stamp && now() - hit.at < CACHE_MS) { entry = hit; break; }
|
|
37
|
+
let flight = flights.get(vault);
|
|
38
|
+
if (!flight) {
|
|
39
|
+
flight = load(vault).then(assembly => ({ stamp, at: now(), assembly, cursors: new Map<string, number>() }));
|
|
40
|
+
flights.set(vault, flight);
|
|
41
|
+
}
|
|
42
|
+
try { entry = await flight; } finally { if (flights.get(vault) === flight) flights.delete(vault); }
|
|
43
|
+
if (entry.stamp === revision()) { cache.delete(vault); cache.set(vault, entry); while (cache.size > 2) cache.delete(cache.keys().next().value!); break; }
|
|
44
|
+
entry = undefined;
|
|
45
|
+
}
|
|
46
|
+
if (!entry) throw new Error("graph changed while assembling; restart from the first page");
|
|
47
|
+
cache.delete(vault); cache.set(vault, entry);
|
|
48
|
+
while (cache.size > 2) cache.delete(cache.keys().next().value!);
|
|
49
|
+
if (args.page !== undefined && typeof args.page !== "string") throw new Error("graph page is invalid; restart from the first page");
|
|
50
|
+
const page = resolveGraphPage(entry.assembly, args.page as string | undefined);
|
|
51
|
+
const key = `${page.kind}:${page.offset}`;
|
|
52
|
+
let cursor = entry.cursors.get(key);
|
|
53
|
+
if (cursor === undefined) { cursor = nextSnapshotCursor(); entry.cursors.set(key, cursor); }
|
|
54
|
+
if (args.after === cursor) return { changed: false, cursor };
|
|
55
|
+
return { ...page, cursor };
|
|
56
|
+
},
|
|
57
|
+
};
|
|
58
|
+
}
|
|
25
59
|
const POLL_MS = 15_000;
|
|
26
60
|
// The shell reuses a snapshot for maxAgeMs, then serves it stale once more while it refreshes, and drops it on every
|
|
27
61
|
// console action. Half the poll keeps both windows inside one poll, so the shell cache never delays a refresh past the
|
|
@@ -96,6 +130,7 @@ export const plugin: ConsolePlugin = {
|
|
|
96
130
|
{ id: "proposals", title: "Proposals", order: 8, maxAgeMs: REUSE_MS },
|
|
97
131
|
{ id: "assertions", title: "Assertions", order: 9 },
|
|
98
132
|
{ id: "history", title: "History", order: 10 },
|
|
133
|
+
{ id: "graph", title: "Graph", order: 11, maxAgeMs: REUSE_MS },
|
|
99
134
|
],
|
|
100
135
|
capabilities: { actions: ["delete", "move", "promote", "promote-from-amem", "settings", "proposal-apply", "proposal-reject"], confirm: true, inbox: true, inboxMaxAgeMs: REUSE_MS, search: true },
|
|
101
136
|
},
|
|
@@ -156,6 +191,10 @@ export const plugin: ConsolePlugin = {
|
|
|
156
191
|
};
|
|
157
192
|
|
|
158
193
|
const promote = createPromoteSnapshot(revision.current, candidates);
|
|
194
|
+
const graph = createGraphSnapshotCache(revision.current, async id => {
|
|
195
|
+
const spec = mcp.vaults.find(v => v.id === id)!;
|
|
196
|
+
return assembleGraphSnapshot(analysisInput(home, id, { expectedVault: spec }).snapshot, id);
|
|
197
|
+
});
|
|
159
198
|
const inbox = createInboxSnapshot(home, mcp.vaults, ctx.log, undefined, revision.current);
|
|
160
199
|
// One cursor for the whole Promote failure: a fresh one per failed scan would rebuild the panel every poll.
|
|
161
200
|
let promoteErrorCursor: number | undefined;
|
|
@@ -194,6 +233,21 @@ export const plugin: ConsolePlugin = {
|
|
|
194
233
|
async snapshot(input) {
|
|
195
234
|
const args = input as Args;
|
|
196
235
|
switch (input.panel) {
|
|
236
|
+
case "graph": {
|
|
237
|
+
const vault = vaultOf(args);
|
|
238
|
+
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" };
|
|
239
|
+
const stem = (value: unknown) => typeof value === "string" && value.startsWith("notes/") && value.endsWith(".md") ? value.slice(6, -3) : value;
|
|
240
|
+
if (args.neighbors !== undefined) {
|
|
241
|
+
const r = await readTool("vmem_graph_neighbors", args, { vault: vault.id, path: stem(args.neighbors) });
|
|
242
|
+
return "error" in r ? r : { neighborhood: r.result };
|
|
243
|
+
}
|
|
244
|
+
if (args.from !== undefined || args.to !== undefined) {
|
|
245
|
+
const r = await readTool("vmem_graph_path", args, { vault: vault.id, from: stem(args.from), to: stem(args.to) });
|
|
246
|
+
return "error" in r ? r : { path: r.result };
|
|
247
|
+
}
|
|
248
|
+
try { return await graph.snapshot(vault.id, args); }
|
|
249
|
+
catch (error) { return { error: error instanceof Error ? error.message : String(error) }; }
|
|
250
|
+
}
|
|
197
251
|
case "settings": {
|
|
198
252
|
const vault = vaultOf(args);
|
|
199
253
|
if (!vault) return { error: "settings: no selected vault; select a registered vault" };
|
|
@@ -392,5 +446,5 @@ export const plugin: ConsolePlugin = {
|
|
|
392
446
|
};
|
|
393
447
|
|
|
394
448
|
export default plugin;
|
|
395
|
-
export type { ProposalState, ProposalsSnapshot, AssertionsSnapshot, HistorySnapshot, CoverageWarning } from "./panel-types.ts";
|
|
449
|
+
export type { ProposalState, ProposalsSnapshot, AssertionsSnapshot, HistorySnapshot, CoverageWarning, GraphSnapshotPage, GraphPanelPage, GraphNodeColumns, GraphEdgeColumns } from "./panel-types.ts";
|
|
396
450
|
export { assertionCoverageWarnings } from "./panel-types.ts";
|
package/src/vault-graph.ts
CHANGED
|
@@ -114,6 +114,29 @@ function parse(source: string): { fm: Record<string, unknown>; body: string } {
|
|
|
114
114
|
}
|
|
115
115
|
return { fm, body: source.slice(match[0].length) };
|
|
116
116
|
}
|
|
117
|
+
/** Frontmatter for consumers of the same analysis snapshot as buildGraph. */
|
|
118
|
+
export function graphFrontmatter(source: string): Record<string, unknown> { return parse(source).fm; }
|
|
119
|
+
|
|
120
|
+
/** Unresolved edges use the same normalization and duplicate semantics as the resolved graph. */
|
|
121
|
+
export function collectUnresolvedGraph(snapshot: AnalysisSnapshot): GraphEdge[] {
|
|
122
|
+
const sources = [...snapshot.notes].sort((a, b) => compare(a.path, b.path));
|
|
123
|
+
const stems = new Set(sources.map(note => note.path.replace(/^notes\//, "").slice(0, -3)));
|
|
124
|
+
const edges = new Map<string, GraphEdge>();
|
|
125
|
+
for (const note of sources) {
|
|
126
|
+
const id = note.path.replace(/^notes\//, "").slice(0, -3), { fm, body } = parse(note.source);
|
|
127
|
+
const inferredTargets = inferredLinkTargets(fm.inferred_links), authored = authoredLinkOffsets(body);
|
|
128
|
+
for (const match of body.matchAll(LEGACY_LINK)) {
|
|
129
|
+
const target = legacyTarget(match[1]!.split("#", 1)[0]!);
|
|
130
|
+
if (!target || stems.has(target)) continue;
|
|
131
|
+
const key = JSON.stringify([id, target]), prior = edges.get(key);
|
|
132
|
+
const rel = prior?.rel ?? linkRelation(body, match.index, match[0].length);
|
|
133
|
+
const inferred = inferredTargets.has(target) && authored.has(match.index);
|
|
134
|
+
edges.set(key, { source: id, target, relation: "wiki_link", ...(rel ? { rel } : {}),
|
|
135
|
+
confidence_tag: inferred || prior?.confidence_tag === "INFERRED" ? "INFERRED" : "EXTRACTED", confidence: 1 });
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
return [...edges.values()].sort((a, b) => compare(a.target, b.target) || compare(a.source, b.source));
|
|
139
|
+
}
|
|
117
140
|
function adjacency(graph: Pick<VaultGraph, "nodes" | "edges">): Map<string, Set<string>> {
|
|
118
141
|
const neighbors = new Map(graph.nodes.map(node => [node.id, new Set<string>()]));
|
|
119
142
|
for (const edge of graph.edges) { neighbors.get(edge.source)?.add(edge.target); neighbors.get(edge.target)?.add(edge.source); }
|