@staix/vault-mem 0.5.1 → 0.6.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.
Files changed (47) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +138 -23
  3. package/package.json +5 -4
  4. package/src/amem/seam.ts +15 -6
  5. package/src/analysis-commands.ts +1 -1
  6. package/src/analysis-input.ts +24 -3
  7. package/src/analysis-reports.ts +1 -1
  8. package/src/analysis-types.ts +13 -1
  9. package/src/canon-tables.ts +190 -0
  10. package/src/cli-output.ts +15 -1
  11. package/src/cli.ts +1 -1
  12. package/src/commands-table.ts +6 -2
  13. package/src/config.ts +31 -3
  14. package/src/frontmatter.ts +10 -3
  15. package/src/links.ts +13 -1
  16. package/src/mcp-spec.ts +19 -11
  17. package/src/mcp-vault.ts +14 -9
  18. package/src/mcp.ts +4 -2
  19. package/src/org-promote.ts +29 -12
  20. package/src/promote.ts +24 -12
  21. package/src/read-commands.ts +1 -2
  22. package/src/read-output.ts +7 -5
  23. package/src/registry.ts +1 -0
  24. package/src/skills-mine.ts +5 -4
  25. package/src/spec-command-table.ts +10 -1
  26. package/src/spec-commands.ts +7 -3
  27. package/src/spec-gitlinks.ts +106 -0
  28. package/src/spec-output.ts +30 -0
  29. package/src/spec-source.ts +9 -3
  30. package/src/spec-validate.ts +6 -3
  31. package/src/spec-write.ts +469 -0
  32. package/src/ui/inbox.ts +28 -10
  33. package/src/ui/panel.js +26 -5
  34. package/src/ui/plugin.ts +38 -12
  35. package/src/ui/snapshot-cache.ts +123 -0
  36. package/src/vault-index.ts +109 -19
  37. package/src/vault-lint.ts +53 -5
  38. package/src/vault-log.ts +3 -2
  39. package/src/vault-stats.ts +110 -5
  40. package/src/write-commands.ts +4 -3
  41. package/src/write-files.ts +63 -0
  42. package/src/write-operations.ts +175 -25
  43. package/src/write-output.ts +20 -9
  44. package/src/write-types.ts +8 -1
  45. package/src/write-validation.ts +46 -17
  46. package/src/writer.ts +137 -41
  47. package/src/yaml-quoted.ts +12 -2
@@ -3,9 +3,9 @@ import { sourceReferences, sourceWorkspaceRoot, missingSourceWarnings } from "./
3
3
  import { basename, resolve } from "node:path";
4
4
  import { domainProblem, type VaultSpec, type VmemConfig } from "./config.ts";
5
5
  import { parseFrontmatter } from "./frontmatter.ts";
6
- import { extractLinks, normalizeTarget, proseLines, resolveLinks, type Link, type LinkNote, type ResolvedLink } from "./links.ts";
6
+ import { extractLinks, normalizeTarget, proseLines, visibleProseLines, resolveLinks, type Link, type LinkNote, type ResolvedLink } from "./links.ts";
7
7
  import { canonicalPath, isDenied } from "./platform.ts";
8
- import type { PlannedChange, ValidationContext, WriteIssue } from "./write-types.ts";
8
+ import { MAX_WRITE_BYTES, type PlannedChange, type ValidationContext, type WriteIssue } from "./write-types.ts";
9
9
  import type { PiiSurface } from "./config.ts";
10
10
  import { screenPii } from "./pii.ts";
11
11
  import { moveSourcePath } from "./write-operations.ts";
@@ -34,7 +34,7 @@ const SECRETS = [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, /\bAKIA[0-9A-Z]{16}\b/, /
34
34
  /\bxox[abprs]-[A-Za-z0-9-]{10,}/, /\bAIza[0-9A-Za-z_-]{35}\b/, /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, /\b(?:password|passwd|secret|api[_-]?key|token)\s*[:=]\s*\S{8,}/i];
35
35
  export const SECRET_PATTERNS: readonly RegExp[] = SECRETS;
36
36
  export { EMAIL_PATTERN } from "./pii.ts";
37
- const MAX_BYTES = 256 * 1024;
37
+ const MAX_BYTES = MAX_WRITE_BYTES;
38
38
  export const MAX_REPORT_BYTES = 16 * 1024 * 1024;
39
39
  function issue(code: string, message: string, severity: WriteIssue["severity"] = "error", path?: string): WriteIssue {
40
40
  return { code, severity, message, ...(path ? { path } : {}) };
@@ -47,7 +47,7 @@ export function screenContent(text: string, vault: VaultSpec, config: VmemConfig
47
47
  }
48
48
 
49
49
  /** Quoted escapes must not hide semantic metadata from the same content policy. */
50
- function screenMetadata(data:Record<string,unknown>,context:ValidationContext,path:string):WriteIssue[]{
50
+ export function screenMetadata(data:Record<string,unknown>,context:Pick<ValidationContext,"vault"|"config"|"piiSurface">,path:string):WriteIssue[]{
51
51
  const found=new Map<string,WriteIssue>(),active=new WeakSet<object>();let nodes=0,bytes=0;
52
52
  const inspect=(text:string)=>{
53
53
  bytes+=Buffer.byteLength(text);if(bytes>MAX_BYTES*4)throw new Error("budget");
@@ -74,11 +74,12 @@ function strings(value: unknown): string[] {
74
74
  }
75
75
  function fold(value: string): string { return value.normalize("NFKC").toLowerCase().replace(/[-_\s]+/g, " ").trim(); }
76
76
  /** Notes whose path and text match `reuse` keep that parsed object, so link analysis is shared too. */
77
- function parseNotes(notes: Map<string, string>, reuse?: Map<string, ParsedNote>): Map<string, ParsedNote> {
77
+ function parseNotes(notes: Map<string, string>, reuse?: Map<string, ParsedNote>, baseline?: Map<string, ParsedNote>): Map<string, ParsedNote> {
78
78
  const parsed = new Map<string, ParsedNote>();
79
79
  for (const [path, text] of notes) {
80
- const previous = reuse?.get(path);
81
- if (previous?.text === text) { parsed.set(path, previous); continue; }
80
+ const previous = reuse?.get(path), original = baseline?.get(path);
81
+ const cached = previous?.text === text ? previous : original?.text === text ? original : undefined;
82
+ if (cached) { parsed.set(path, cached); continue; }
82
83
  try {
83
84
  const { data, body } = parseFrontmatter(text);
84
85
  const h1 = proseLines(body).map(line => /^ {0,3}#(?:[ \t]+(.*)|[ \t]*)$/.exec(line)).find(match => match)?.[1]?.replace(/[ \t]+#+[ \t]*$/, "").trim() ?? "";
@@ -126,13 +127,14 @@ function movedFrom(value: string, context: ValidationContext): string {
126
127
  function changedBrokenLinks(oldNotes: Map<string, ParsedNote>, newNotes: Map<string, ParsedNote>, context: ValidationContext): WriteIssue[] {
127
128
  const oldCounts = new Map<string, number>();
128
129
  const move = context.operation.op === "move" ? context.operation : undefined;
129
- const from = move ? movedFrom(move.from, context) : "";
130
- const to = move ? `notes/${move.to.replace(/^notes\//, "").replace(/\.md$/, "")}.md` : "";
131
- const oldNames = move ? names(oldNotes) : undefined;
130
+ const merge = context.operation.op === "merge" ? context.operation : undefined;
131
+ const from = move ? movedFrom(move.from, context) : merge ? `notes/${merge.absorb.replace(/^notes\//, "").replace(/\.md$/, "")}.md` : "";
132
+ const to = move ? `notes/${move.to.replace(/^notes\//, "").replace(/\.md$/, "")}.md` : merge ? `notes/${merge.keep.replace(/^notes\//, "").replace(/\.md$/, "")}.md` : "";
133
+ const oldNames = move || merge ? names(oldNotes) : undefined;
132
134
  for (const link of references(oldNotes)) if (link.reason) {
133
135
  const candidates = oldNames?.get(noteKey(link.target));
134
136
  const renamedTarget = candidates?.size === 1 && [...candidates][0]!.path === from;
135
- const signature = linkSignature(renamedTarget ? { ...link, target: to } : link, link.source === from ? to : link.source);
137
+ const signature = linkSignature(renamedTarget ? { ...link, target: to } : link, move && link.source === from ? to : link.source);
136
138
  oldCounts.set(signature, (oldCounts.get(signature) ?? 0) + 1);
137
139
  }
138
140
  const issues: WriteIssue[] = [];
@@ -195,7 +197,7 @@ function topicIssues(note: ParsedNote, index: Map<string, Set<ParsedNote>>, seve
195
197
  function topicProblems(note: ParsedNote): Set<"placement" | "content"> {
196
198
  const problems = new Set<"placement" | "content">();
197
199
  if (note.data.type === "moc" && note.data.topics === undefined) return problems;
198
- const lines = proseLines(note.body), h2s = lines.flatMap((line, index) => /^ {0,3}##[ \t]+/.test(line) ? [index] : []);
200
+ const lines = visibleProseLines(note.body), h2s = lines.flatMap((line, index) => /^ {0,3}##[ \t]+/.test(line) ? [index] : []);
199
201
  const topics = h2s.filter(index => /^ {0,3}##[ \t]+Topics(?:[ \t]+#+)?[ \t]*$/i.test(lines[index]!));
200
202
  if (topics.length !== 1 || h2s[h2s.length - 1] !== topics[0]) problems.add("placement");
201
203
  const last = topics[topics.length - 1], end = h2s.find(index => last !== undefined && index > last) ?? lines.length;
@@ -221,13 +223,13 @@ function topicPlacement(note: ParsedNote, old: ParsedNote | undefined, context:
221
223
  return [issue("V05", "Topics must be the final H2 and list exactly the frontmatter topics", retained ? "warning" : "error", note.path)];
222
224
  }
223
225
 
224
- /** Validate a complete mutation plan against the final overlaid snapshot, without filesystem writes. */
225
- export function validateWrite(changes: PlannedChange[], context: ValidationContext): WriteIssue[] {
226
+ /** Run every validation rule over one candidate, reusing only source-identical parsed notes. */
227
+ function validateChanges(changes: PlannedChange[], context: ValidationContext, oldNotes: Map<string, ParsedNote>, oldNames: Map<string, Set<ParsedNote>>, reuse?: Map<string, ParsedNote>): { issues: WriteIssue[]; notes: Map<string, ParsedNote> } {
226
228
  const issues: WriteIssue[] = [], final = new Map(context.notes), touched = new Set(changes.map(change => change.path));
227
229
  const report = context.operation.op === "report";
228
230
  for (const change of changes) {
229
231
  // Sanitize and move may touch an existing legacy-named note (L13 names stay until moved); move destinations stay strict.
230
- const legacy = context.notes.has(change.path) && (context.operation.op === "sanitize" || context.operation.op === "move");
232
+ const legacy = context.notes.has(change.path) && (context.operation.op === "sanitize" || context.operation.op === "move" || context.operation.op === "merge");
231
233
  if (!validPath(change.path, report) && !legacy) issues.push(issue("V04", "invalid mutation path"));
232
234
  if (change.after === null) final.delete(change.path);
233
235
  else if (change.path.startsWith("notes/")) final.set(change.path, change.after);
@@ -237,7 +239,7 @@ export function validateWrite(changes: PlannedChange[], context: ValidationConte
237
239
  try{issues.push(...screenMetadata(parseFrontmatter(change.after).data,context,change.path));}catch{ /* Invalid note YAML is reported separately; reports remain schema-exempt. */ }
238
240
  }
239
241
  const sourceRoot=sourceWorkspaceRoot(context.vault);
240
- const oldNotes = parseNotes(context.notes), newNotes = parseNotes(final, oldNotes), oldNames = names(oldNotes), newNames = names(newNotes);
242
+ const newNotes = parseNotes(final, reuse ?? oldNotes, oldNotes), newNames = names(newNotes);
241
243
  const citekeys = new Map<string, ParsedNote[]>();
242
244
  for (const note of newNotes.values()) if (typeof note.data.citekey === "string") {
243
245
  const peers = citekeys.get(note.data.citekey.toLowerCase()) ?? [];
@@ -291,5 +293,32 @@ export function validateWrite(changes: PlannedChange[], context: ValidationConte
291
293
  }
292
294
  issues.push(...changedBrokenLinks(oldNotes, newNotes, context));
293
295
  }
294
- return issues;
296
+ return { issues, notes: newNotes };
297
+ }
298
+
299
+ function sameSources(notes: Map<string, string>, previous: Map<string, string> | undefined): boolean {
300
+ if (!previous || notes.size !== previous.size) return false;
301
+ const entries = previous.entries();
302
+ for (const [path, source] of notes) {
303
+ const before = entries.next().value;
304
+ if (!before || before[0] !== path || before[1] !== source) return false;
305
+ }
306
+ return true;
307
+ }
308
+ /** A write-local raw/stamped validation session. Policy, screens and graph rules run on every call. */
309
+ export function createWriteValidator(context: ValidationContext): (changes: PlannedChange[]) => WriteIssue[] {
310
+ let sources: Map<string, string> | undefined, baseline = new Map<string, ParsedNote>(), baselineNames = names(baseline), prospective: Map<string, ParsedNote> | undefined;
311
+ return changes => {
312
+ if (!sameSources(context.notes, sources)) {
313
+ baseline = parseNotes(context.notes, baseline); baselineNames = names(baseline);
314
+ sources = new Map(context.notes); prospective = undefined;
315
+ }
316
+ const result = validateChanges(changes, context, baseline, baselineNames, prospective);
317
+ prospective = result.notes;
318
+ return result.issues;
319
+ };
320
+ }
321
+ /** Compatible one-shot validation; callers with raw/stamped passes can share a write-local session. */
322
+ export function validateWrite(changes: PlannedChange[], context: ValidationContext): WriteIssue[] {
323
+ return createWriteValidator(context)(changes);
295
324
  }
package/src/writer.ts CHANGED
@@ -1,6 +1,9 @@
1
+ import { capturePublicationPath, publishFile, cleanupOwnedFile, PublicationDrift, type PublicationPath } from "./write-files.ts";
2
+ import { anchorIndex, normalizeTarget, noteKey, extractLinks } from "./links.ts";
3
+ import { localDate } from "./local-date.ts";
1
4
  import { appendLog, checkLogEvent, matchesBinding } from "./vault-log.ts";
2
5
  import type { LogEvent } from "./log-types.ts";
3
- import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
6
+ import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, realpathSync, rmdirSync, writeFileSync } from "node:fs";
4
7
  import { createHash, randomUUID } from "node:crypto";
5
8
  import { dirname, join } from "node:path";
6
9
  import { hostname } from "node:os";
@@ -9,14 +12,15 @@ import { loadRegistry, syncDirectory } from "./registry.ts";
9
12
  import { VaultIndex, MAX_NOTE_BYTES, GRAMS_COLUMNS, gramPhrase, grams, splitTerms } from "./vault-index.ts";
10
13
  import { parseFrontmatter } from "./frontmatter.ts";
11
14
  import { canonicalPath, isDenied } from "./platform.ts";
12
- import { moveSourcePath, notePath, planOperation, refuse, WriteRefusal } from "./write-operations.ts";
13
- import { MAX_REPORT_BYTES, validateWrite } from "./write-validation.ts";
15
+ import { moveSourcePath, notePath, planOperation, planMerge, stampContentChanges, refuse, WriteRefusal } from "./write-operations.ts";
16
+ import { MAX_REPORT_BYTES, createWriteValidator } from "./write-validation.ts";
14
17
  import type { PiiSurface } from "./config.ts";
15
- import { unenforceablePii } from "./config.ts";
18
+ import { unenforceablePii, mutationVault } from "./config.ts";
16
19
  import type { LogBinding } from "./log-types.ts";
17
- import type { ChangeReceipt, PlannedChange, WriteIssue, WriteReceipt, WriteRequest } from "./write-types.ts";
20
+ import type { MergePreview, ChangeReceipt, PlannedChange, WriteIssue, WriteReceipt, WriteRequest } from "./write-types.ts";
18
21
  export const MUTATION_LOCK = "mutation.lock";
19
- export const MAX_WRITE_BYTES = 256 * 1024;
22
+ export { MAX_WRITE_BYTES } from "./write-types.ts";
23
+ const MAX_MERGE_ACK_BYTES = 224 * 1024;
20
24
  export function sha256(text: string): string { return createHash("sha256").update(text).digest("hex"); }
21
25
  function canonical(value: unknown): string {
22
26
  if (value === undefined) return "null";
@@ -93,6 +97,26 @@ function checkExpected(request: WriteRequest, notes: Map<string, string>): void
93
97
  if (typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash) || source === undefined || sha256(source) !== hash) refuse("V09", "expected SHA mismatch", canonical);
94
98
  }
95
99
  }
100
+ /** Preserve referenced content identity and the existing no-self-supersession invariant. */
101
+ function checkMergeReferences(preview: MergePreview, notes: Map<string, string>, copiedBody: string): void {
102
+ const anchors = anchorIndex(parseFrontmatter(notes.get(preview.keep)!).body);
103
+ const absorbed = parseFrontmatter(notes.get(preview.absorb)!);
104
+ const supersedes = typeof absorbed.data.supersedes === "string" ? [absorbed.data.supersedes] : Array.isArray(absorbed.data.supersedes) ? absorbed.data.supersedes : [];
105
+ if (supersedes.some(value => typeof value === "string" && extractLinks(value).some(link => noteKey(link.target) === noteKey(preview.keep)))) {
106
+ refuse("V10", `${preview.absorb} supersedes ${preview.keep}, so keep is the older note; swap keep and absorb, then request a fresh merge preview`, preview.absorb);
107
+ }
108
+ // Only surviving copied self-fragments change their containing note to keep.
109
+ // Removed title/Topics content is excluded; these links need no target rewrite.
110
+ const selfFragments = extractLinks(copiedBody)
111
+ .filter(link => link.target === "" && (link.heading !== null || link.block !== null))
112
+ .map(link => ({ path: preview.absorb, field: "body", heading: link.heading ?? undefined, block: link.block ?? undefined }));
113
+ for (const link of [...preview.inboundLinks, ...selfFragments]) {
114
+ if (link.path === preview.keep && /^superseded_by(?:$|\[)/.test(link.field)) refuse("V10", `${preview.keep} is superseded by ${preview.absorb}; swap keep and absorb, then request a fresh merge preview`, preview.keep);
115
+ const fragment = link.block ? `^${link.block}` : link.heading;
116
+ const collides = link.block ? anchors.blocks.has(normalizeTarget(link.block)) : link.heading ? anchors.headings.has(normalizeTarget(link.heading)) : false;
117
+ if (fragment && collides) refuse("V03", `merge fragment ${JSON.stringify(fragment)} from ${preview.absorb} collides with ${preview.keep}; rename the heading or block anchor in one note and rerun the merge preview`, link.path);
118
+ }
119
+ }
96
120
  function duplicateWarnings(request: WriteRequest, notes: Map<string, string>, changes: PlannedChange[]): WriteIssue[] {
97
121
  if (request.operation.op !== "create" || !notes.size || !changes[0]?.after) return [];
98
122
  const doc = parseFrontmatter(changes[0].after);
@@ -121,12 +145,24 @@ function duplicateWarnings(request: WriteRequest, notes: Map<string, string>, ch
121
145
  }
122
146
  /** Single mutation entry point. Preview/dry-run perform no writes, including locks and caches. */
123
147
  /** `options.binding` (internal callers composing several writes) refuses with VAULT_DRIFT unless the registry still matches it. */
124
- export function applyWrite(home: string, request: WriteRequest, options: { env?: NodeJS.ProcessEnv; piiSurface?: PiiSurface; binding?: LogBinding } = {}): WriteReceipt {
125
- let lockFd: number | undefined, lockFile: string | undefined, lockIdentity: { ino: number; dev: number } | undefined;
148
+ export function applyWrite(home: string, request: WriteRequest, options: { env?: NodeJS.ProcessEnv; piiSurface?: PiiSurface; binding?: LogBinding; now?: Date } = {}): WriteReceipt {
149
+ let lockFd: number | undefined, lockFile: string | undefined;
126
150
  let index: VaultIndex | undefined;
127
- const temps = new Set<string>(), createdDirs: string[] = [], committed: PlannedChange[] = [];
151
+ const temps = new Map<string, { fd: number; remove: boolean }>(), publicationPaths = new Map<string, PublicationPath>(), createdDirs: string[] = [], committed: PlannedChange[] = [];
128
152
  let changes: PlannedChange[] = [], issues: WriteIssue[] = [], fingerprint: string | undefined, root = "", applied = false, indexUpdated = false;
129
153
  let result: WriteReceipt | undefined;
154
+ let appliedPaths: Set<string> | undefined;
155
+ const backups = new Map<string, string>(), backupNames = new Set<string>(), retainedBackups = new Set<string>();
156
+ const retainBackup = (path: string) => {
157
+ const backup = backups.get(path);
158
+ if (backup && temps.get(backup)?.remove) {
159
+ temps.get(backup)!.remove = false; retainedBackups.add(backup.slice(root.length + 1));
160
+ }
161
+ };
162
+ const reportedChanges = () => receipts(changes).map(change => appliedPaths
163
+ ? { ...change, applied: appliedPaths.has(change.path) } : change);
164
+ const dateWarnings: WriteIssue[] = [];
165
+ let mergePreview: MergePreview | undefined, mergeCopiedBody = "";
130
166
  const recordError = (code: string, message: string, path?: string) => issues.push({ code, severity: "error", message, ...(path ? { path } : {}) });
131
167
  try {
132
168
  if (!request || typeof request !== "object" || !request.operation || typeof request.operation !== "object" || typeof request.vault !== "string") refuse("V01", "invalid write request");
@@ -147,13 +183,12 @@ export function applyWrite(home: string, request: WriteRequest, options: { env?:
147
183
  const logIssues = checkLogEvent(home, { vault: request.vault, event: request.log, channel: request.channel }, options.env);
148
184
  if (logIssues.length) throw new WriteRefusal(logIssues.map(issue => ({ ...issue, message: `log event refused, nothing written: ${issue.message}; fix the event fields (rules as for \`log append\`) or omit the event for the default line` })));
149
185
  }
150
- const twoStep = ["move", "delete", "tidy"].includes(request.operation.op);
186
+ const twoStep = ["move", "delete", "tidy", "merge"].includes(request.operation.op);
151
187
  const preview = request.operation.op === "check" || request.dryRun === true || (twoStep && request.confirm !== true);
152
188
  if (!preview) {
153
189
  lockFile = join(root, MUTATION_LOCK);
154
190
  try { lockFd = openSync(lockFile, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
155
191
  catch { lockFile = undefined; refuse("LOCKED", "vault mutation lock unavailable; existing lock is preserved"); }
156
- const stat = fstatSync(lockFd); lockIdentity = { ino: Number(stat.ino), dev: Number(stat.dev) };
157
192
  writeFileSync(lockFd, JSON.stringify({ pid: process.pid, host: hostname(), token: randomUUID(), created: new Date().toISOString() }) + "\n");
158
193
  fsyncSync(lockFd);
159
194
  }
@@ -166,22 +201,45 @@ export function applyWrite(home: string, request: WriteRequest, options: { env?:
166
201
  if (isDenied(join(root, request.operation.path), config.denyPaths)) refuse("V06", "report output path is denied");
167
202
  reportBefore = readPlain(root, request.operation.path, MAX_REPORT_BYTES);
168
203
  }
169
- changes = planOperation(request.operation, notes, reportBefore);
204
+ if (request.operation.op === "merge") {
205
+ const plan = planMerge(request.operation, notes); changes = plan.changes; mergePreview = plan.preview; mergeCopiedBody = plan.copiedBody;
206
+ } else changes = planOperation(request.operation, notes, reportBefore);
170
207
  for (const change of changes) if (isDenied(join(root, change.path), config.denyPaths)) refuse("V06", "planned mutation path is denied", change.path);
171
- issues = validateWrite(changes, { vault, config, notes, operation: request.operation, ...(options.piiSurface ? { piiSurface: options.piiSurface } : {}) });
172
- if (!issues.some(issue => issue.severity === "error")) issues.push(...duplicateWarnings(request, notes, changes));
208
+ const validation = { vault, config, notes, operation: request.operation, ...(options.piiSurface ? { piiSurface: options.piiSurface } : {}) };
209
+ // Validate the caller's candidate first: replacing `updated` must not hide a
210
+ // secret, oversized input or other refusal that existing validation catches.
211
+ const validateCandidate = createWriteValidator(validation);
212
+ const validate = (candidate: PlannedChange[]) => validateCandidate(candidate).map(issue => request.operation.op === "merge" && issue.severity === "error"
213
+ ? { ...issue, message: `${issue.message}; repair the indicated notes or links, then request a fresh merge preview` } : issue);
214
+ issues = validate(changes);
215
+ if (!issues.some(issue => issue.severity === "error")) {
216
+ // Check only screened candidates: diagnostics must not echo an unsafe fragment.
217
+ if (mergePreview) checkMergeReferences(mergePreview, notes, mergeCopiedBody);
218
+ const stamped = stampContentChanges(request.operation, changes, localDate(options.now), dateWarnings);
219
+ if (stamped.some((change, index) => change.after !== changes[index]?.after) || stamped.length !== changes.length) {
220
+ changes = stamped;
221
+ issues = validate(changes);
222
+ }
223
+ issues.push(...dateWarnings);
224
+ if (!issues.some(issue => issue.severity === "error")) issues.push(...duplicateWarnings(request, notes, changes));
225
+ }
173
226
  // The log event is not part of the fingerprint: move/delete take it on the confirm call only.
174
227
  const input = { vault: request.vault, channel: request.channel ?? "cli", operation: request.operation, expectedShas: request.expectedShas ?? {} };
175
228
  const identity = lstatSync(root);
176
229
  // The identity every later commit check uses must still be the bound root, not a directory swapped in meanwhile.
177
230
  if (options.binding && (Number(identity.dev) !== options.binding.dev || Number(identity.ino) !== options.binding.ino)) refuse("VAULT_DRIFT", "vault root changed since the run started; nothing written");
178
- fingerprint = sha256(canonical({ input, vault, policy: { denyPaths: config.denyPaths ?? [], piiPatterns: config.piiPatterns ?? [], piiSurface: options.piiSurface ?? "notes" }, root, identity: [identity.dev, identity.ino], files: [...notes].map(([path, text]) => [path, sha256(text)]), changes: receipts(changes) }));
179
- if (twoStep && request.confirm === true && (typeof request.fingerprint !== "string" || request.fingerprint !== fingerprint)) refuse("V09", "stale or missing preview fingerprint");
231
+ fingerprint = sha256(canonical({ input, vault: mutationVault(vault), policy: { denyPaths: config.denyPaths ?? [], piiPatterns: config.piiPatterns ?? [], piiSurface: options.piiSurface ?? "notes" }, root, identity: [identity.dev, identity.ino], files: [...notes].map(([path, text]) => [path, sha256(text)]), changes: receipts(changes) }));
232
+ if (twoStep && request.confirm === true && (typeof request.fingerprint !== "string" || request.fingerprint !== fingerprint)) refuse("V09", request.operation.op === "merge" ? "stale or missing merge fingerprint; request a fresh merge preview and confirm with that fingerprint" : "stale or missing preview fingerprint");
233
+ if (mergePreview && request.channel === "mcp" && !issues.some(issue => issue.severity === "error") && Buffer.byteLength(JSON.stringify({ merge: mergePreview, issues, changes: receipts(changes), fingerprint })) > MAX_MERGE_ACK_BYTES) {
234
+ // The complete plan must be reviewable before a merge can publish. Keep the refusal compact too.
235
+ changes = []; mergePreview = undefined; issues = [];
236
+ refuse("V09", "merge preview exceeds the bounded MCP acknowledgement size; use CLI --json for both preview and confirm, or reduce the notes and inbound links before requesting a fresh preview");
237
+ }
180
238
  if (issues.some(issue => issue.severity === "error")) return result = { ok: false, applied: false, issues, changes: receipts(changes), fingerprint, indexUpdated: false };
181
239
  if (preview) return result = { ok: true, applied: false, preview: true, ...(request.operation.op === "link" && !changes.length ? {unchanged:true} : {}), issues, changes: receipts(changes), fingerprint, indexUpdated: false };
182
240
  if (!changes.length) return result = { ok: true, applied: false, ...(request.operation.op === "link" ? {unchanged:true} : {}), issues, changes: [], fingerprint, indexUpdated: false };
183
241
  index = new VaultIndex(home, vault, config.vaults.map(value => value.path));
184
- const backups = new Map<string, string>(), staged = new Map<string, string>();
242
+ const staged = new Map<string, string>();
185
243
  const ensureDir = (dir: string) => {
186
244
  if (dir === root) return;
187
245
  try { if (!lstatSync(dir).isDirectory() || lstatSync(dir).isSymbolicLink()) refuse("V04", "unsafe output directory"); }
@@ -190,16 +248,19 @@ export function applyWrite(home: string, request: WriteRequest, options: { env?:
190
248
  ensureDir(dirname(dir)); mkdirSync(dir, { mode: 0o700 }); createdDirs.push(dir);
191
249
  }
192
250
  };
251
+ // ponytail: staging holds up to two descriptors per changed note until cleanup; the process fd ceiling
252
+ // may refuse a large batch with EMFILE before publication. Split such a batch before retrying.
193
253
  const stage = (file: string, text: string) => {
194
254
  const temp = join(dirname(file), `.vmem-${randomUUID()}.tmp`);
195
255
  const fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
196
- temps.add(temp);
197
- try { writeFileSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
256
+ temps.set(temp, { fd, remove: true });
257
+ writeFileSync(fd, text); fsyncSync(fd);
198
258
  return temp;
199
259
  };
200
260
  for (const change of changes) {
201
261
  const file = safePath(root, change.path); ensureDir(dirname(file));
202
- if (change.before !== null) backups.set(change.path, stage(file, change.before));
262
+ publicationPaths.set(change.path, capturePublicationPath(root, file));
263
+ if (change.before !== null) { const backup = stage(file, change.before); backups.set(change.path, backup); backupNames.add(backup); }
203
264
  if (change.after !== null) staged.set(change.path, stage(file, change.after));
204
265
  }
205
266
  try {
@@ -212,28 +273,52 @@ export function applyWrite(home: string, request: WriteRequest, options: { env?:
212
273
  for (const change of changes) {
213
274
  const file = safePath(root, change.path);
214
275
  if (readPlain(root, change.path, request.operation.op === "report" ? MAX_REPORT_BYTES : MAX_NOTE_BYTES) !== change.before) refuse("V09", "file changed while staging", change.path);
215
- if (change.after === null) unlinkSync(file);
216
- else { const temp = staged.get(change.path)!; renameSync(temp, file); temps.delete(temp); }
217
- committed.push(change);
276
+ const temp = staged.get(change.path);
277
+ publishFile(publicationPaths.get(change.path)!, change.after === null ? { kind: "unlink" } : { kind: "rename", temp: temp! }, () => {
278
+ committed.push(change);
279
+ if (temp) temps.get(temp)!.remove = false;
280
+ });
218
281
  }
219
282
  for (const dir of new Set(changes.map(change => dirname(join(root, change.path))))) syncDirectory(dir);
220
283
  const refreshed = index.scan(false, { skipInvalidFrontmatter: true });
221
284
  for (const path of refreshed.skipped ?? []) issues.push({ code: "V01", severity: "warning", path: `notes/${path}`, message: "legacy invalid frontmatter omitted from derived index; note unchanged" });
222
285
  indexUpdated = true; applied = true;
223
286
  } catch (error) {
287
+ if (error instanceof PublicationDrift) {
288
+ // Namespace ownership is no longer proved. Do not roll back, flush or rescan through that path.
289
+ applied = committed.length > 0;
290
+ appliedPaths = new Set(committed.map(change => change.path));
291
+ for (const change of committed) retainBackup(change.path);
292
+ throw error;
293
+ }
294
+ const outstanding = new Set(committed.map(change => change.path));
295
+ let rollbackDrift: PublicationDrift | undefined;
224
296
  for (const change of [...committed].reverse()) {
297
+ let restored = false;
225
298
  try {
226
299
  const file = safePath(root, change.path);
227
300
  if (readPlain(root, change.path, request.operation.op === "report" ? MAX_REPORT_BYTES : MAX_NOTE_BYTES) !== change.after) throw new Error("external write detected before rollback");
228
- if (change.before === null) unlinkSync(file);
229
- else { const backup = backups.get(change.path)!; renameSync(backup, file); temps.delete(backup); }
230
- } catch {
231
- applied = true;
232
301
  const backup = backups.get(change.path);
233
- if (backup) temps.delete(backup); // Recovery copy must survive failed rollback or external drift.
302
+ publishFile(publicationPaths.get(change.path)!, change.before === null ? { kind: "unlink" } : { kind: "rename", temp: backup! }, () => {
303
+ restored = true; outstanding.delete(change.path);
304
+ if (backup) temps.get(backup)!.remove = false;
305
+ });
306
+ } catch (rollbackError) {
307
+ if (!restored) retainBackup(change.path);
308
+ const backup = backups.get(change.path);
309
+ if (rollbackError instanceof PublicationDrift) {
310
+ rollbackDrift = rollbackError;
311
+ recordError("ROLLBACK", `${restored
312
+ ? "rollback restored the original target; its backup name was consumed by publication"
313
+ : "rollback was not published; inspect the listed retained backup"}; ${rollbackError.message}`, change.path);
314
+ for (const path of outstanding) retainBackup(path);
315
+ break;
316
+ }
234
317
  recordError("ROLLBACK", "rollback refused or failed; external edits preserved and original backup retained when available", backup ? backup.slice(root.length + 1) : change.path);
235
318
  }
236
319
  }
320
+ applied = outstanding.size > 0;
321
+ if (rollbackDrift) { appliedPaths = outstanding; throw rollbackDrift; }
237
322
  for (const dir of new Set(committed.map(change => dirname(join(root, change.path))))) {
238
323
  try { syncDirectory(dir); } catch { recordError("ROLLBACK", "rollback directory flush failed"); }
239
324
  }
@@ -243,37 +328,48 @@ export function applyWrite(home: string, request: WriteRequest, options: { env?:
243
328
  result = { ok: true, applied, issues, changes: receipts(changes), fingerprint, indexUpdated };
244
329
  if (request.log !== false) {
245
330
  const op = request.operation;
246
- const type = op.op === "link" ? "CONNECT" : op.op === "move" ? "ROUTE" : ["supersede", "tidy"].includes(op.op) ? "RETHINK" : "EXTRACT";
247
- const source = op.op === "move" ? moveSourcePath(op.from, notes) : op.op === "link" ? notePath(op.from) : op.op === "supersede" ? notePath(op.old) : op.op === "delete" ? notePath(op.path) : `vmem:${op.op}`;
248
- const dest = op.op === "move" || op.op === "link" ? notePath(op.to) : op.op === "supersede" ? notePath(op.next) : op.op === "delete" ? undefined : changes.find(change => change.after !== null)?.path;
331
+ const type = op.op === "link" ? "CONNECT" : op.op === "move" ? "ROUTE" : ["supersede", "tidy", "merge"].includes(op.op) ? "RETHINK" : "EXTRACT";
332
+ const source = op.op === "move" ? moveSourcePath(op.from, notes) : op.op === "link" ? notePath(op.from) : op.op === "supersede" ? notePath(op.old) : op.op === "merge" ? notePath(op.absorb) : op.op === "delete" ? notePath(op.path) : `vmem:${op.op}`;
333
+ const dest = op.op === "move" || op.op === "link" ? notePath(op.to) : op.op === "supersede" ? notePath(op.next) : op.op === "merge" ? notePath(op.keep) : op.op === "delete" ? undefined : changes.find(change => change.after !== null)?.path;
249
334
  const event: LogEvent = request.log ?? { type, project: "-", source, ...(dest ? { dest } : {}), note: op.op };
250
335
  try { result.log = appendLog(home, { vault: request.vault, event, channel: request.channel }, { env: options.env, binding: { vault, denyPaths: config.denyPaths ?? [], piiPatterns: config.piiPatterns ?? [], dev: Number(identity.dev), ino: Number(identity.ino) } }); }
251
336
  catch { result.log = { ok: false, appended: null, synced: false, bytesWritten: null, issues: [{ code: "LOG_IO", severity: "error", message: "log append failed after successful mutation" }] }; }
252
337
  result.logged = result.log.appended === true && result.log.synced;
253
338
  }
254
339
  } catch (error) {
255
- if (error instanceof WriteRefusal) issues.push(...error.issues);
340
+ if (error instanceof WriteRefusal) issues.push(...error.issues.map(issue => request?.operation?.op === "merge" && !issue.message.includes(";")
341
+ ? { ...issue, message: `${issue.message}; repair the indicated merge input or note, then request a fresh preview` } : issue));
342
+ else if (error instanceof PublicationDrift) recordError("V09", error.message, error.file.slice(root.length + 1));
256
343
  else recordError("IO", "write operation failed; inspect filesystem permissions and retry");
257
- result = { ok: false, applied, issues, changes: receipts(changes), ...(fingerprint ? { fingerprint } : {}), indexUpdated };
344
+ result = { ok: false, applied, issues, changes: reportedChanges(), ...(fingerprint ? { fingerprint } : {}), indexUpdated };
258
345
  } finally {
259
346
  try { index?.close(); } catch { recordError("INDEX", "derived index close failed"); }
260
- for (const temp of temps) {
261
- try { unlinkSync(temp); } catch { recordError("CLEANUP", "owned temporary cleanup failed; inspect .vmem temporary files"); }
347
+ for (const [temp, owned] of temps) {
348
+ try { if (owned.remove) cleanupOwnedFile(temp, owned.fd); }
349
+ catch (error) {
350
+ // A swapped parent can make the original name unreachable while the owned backup still has a link.
351
+ // Report its original name for inspection, but never claim an unlinked/replaced inode was retained.
352
+ if (backupNames.has(temp)) {
353
+ try { if (fstatSync(owned.fd).nlink > 0) retainedBackups.add(temp.slice(root.length + 1)); } catch { /* The cleanup issue below remains authoritative. */ }
354
+ }
355
+ recordError("CLEANUP", `owned temporary cleanup failed; inspect .vmem temporary files and preserve replacements: ${error instanceof Error ? error.message : String(error)}`, temp.slice(root.length + 1));
356
+ }
357
+ finally { try { closeSync(owned.fd); } catch { recordError("CLEANUP", "temporary descriptor close failed; inspect retained .vmem files"); } }
262
358
  }
263
359
  // Only empty directories created by this invocation are eligible for removal on failure.
264
360
  if (!applied) for (const dir of createdDirs.reverse()) { try { rmdirSync(dir); } catch { recordError("CLEANUP", "owned empty directory cleanup failed"); } }
265
361
  if (lockFd !== undefined) {
266
- try { closeSync(lockFd); } catch { recordError("CLEANUP", "mutation lock descriptor close failed"); }
267
- try {
268
- const stat = lstatSync(lockFile!);
269
- if (Number(stat.ino) !== lockIdentity?.ino || Number(stat.dev) !== lockIdentity?.dev || stat.isSymbolicLink()) recordError("CLEANUP", "mutation lock ownership changed; retained lock");
270
- else unlinkSync(lockFile!);
271
- } catch { recordError("CLEANUP", "mutation lock retained; inspect ownership before manual recovery"); }
362
+ try { cleanupOwnedFile(lockFile!, lockFd); }
363
+ catch (error) { recordError("CLEANUP", `mutation lock retained; inspect ownership before manual recovery: ${error instanceof Error ? error.message : String(error)}`); }
364
+ finally { try { closeSync(lockFd); } catch { recordError("CLEANUP", "mutation lock descriptor close failed"); } }
272
365
  }
273
366
  if (result) {
367
+ if (retainedBackups.size) result.retainedBackups = [...retainedBackups];
274
368
  const possibleDuplicates = issues.filter(issue => issue.code === "V08" && issue.severity === "warning" && issue.path).map(issue => issue.path!);
275
369
  if (possibleDuplicates.length) result.possibleDuplicates = possibleDuplicates;
276
370
  if (issues.some(issue => issue.severity === "error")) result.ok = false;
371
+ if (result.ok && result.applied) for (const warning of dateWarnings) warning.message = `content was saved; ${warning.message}`;
372
+ if (result.ok && mergePreview) result.merge = mergePreview;
277
373
  }
278
374
  }
279
375
  return result!;
@@ -64,16 +64,18 @@ function doubleQuoted(source:string,start:number):{value:string;end:number} {
64
64
  throw new Error("YAML: unterminated quoted scalar");
65
65
  }
66
66
 
67
+ export interface YamlReference { kind: "anchor" | "alias"; name: string; binding: number }
67
68
  /**
68
69
  * Parse structural YAML with Bun, replacing only double-quoted scalar nodes in its semantic input.
69
70
  * Original source and byte offsets remain the caller's property. Opaque scalars also avoid asking
70
71
  * older Bun YAML versions to parse decoded control characters or unsupported Unicode escapes.
71
72
  */
72
- export function parseYamlWithQuotedEscapes(source:string):unknown {
73
+ export function parseYamlWithQuotedEscapes(source:string,references?:YamlReference[]):unknown {
73
74
  const prefix=`vmem-quoted-${randomUUID()}-`,values=new Map<string,string>();
74
75
  const replacements:{start:number;end:number;token:string}[]=[];
75
76
  let offset=0,lineStart=0,flow=0,nodeStart=true,blockIndent:number|null=null;
76
77
  let effectiveIndent=0,mappingOnLine=false,plain=false,plainIndent=0;
78
+ const bindings=references ? new Map<string,number>() : undefined; let declaration=0;
77
79
  while(offset<source.length) {
78
80
  if(offset===lineStart) {
79
81
  const end=source.indexOf("\n",offset),line=source.slice(offset,end===-1 ? undefined : end),indent=line.match(/^[ \t]*/)![0].length;
@@ -106,8 +108,16 @@ export function parseYamlWithQuotedEscapes(source:string):unknown {
106
108
  blockIndent=mappingOnLine ? effectiveIndent : lineStart===offset ? 0 : source.slice(lineStart).match(/^[ \t]*/)![0].length;
107
109
  const end=source.indexOf("\n",offset);offset=end===-1 ? source.length : end;plain=false;continue;
108
110
  }
111
+ if(nodeStart && character === "*" && references) {
112
+ const name=/^\*[^\s,[\]{}]*/.exec(source.slice(offset))![0].slice(1);
113
+ references.push({kind:"alias",name,binding:bindings!.get(name) ?? -1});
114
+ }
109
115
  if(nodeStart && (character === "&" || character === "!")) {
110
- const prefix=/^[&!][^\s,[\]{}]*/.exec(source.slice(offset))![0];offset+=prefix.length;continue;
116
+ const prefix=/^[&!][^\s,[\]{}]*/.exec(source.slice(offset))![0];
117
+ if(character === "&" && references) {
118
+ const name=prefix.slice(1),binding=declaration++;bindings!.set(name,binding);references.push({kind:"anchor",name,binding});
119
+ }
120
+ offset+=prefix.length;continue;
111
121
  }
112
122
  if(nodeStart && (character === "[" || character === "{")) {flow++;offset++;nodeStart=true;plain=false;continue;}
113
123
  if(flow && (character === "]" || character === "}")) {flow--;offset++;nodeStart=false;plain=false;continue;}