@staix/vault-mem 0.3.2 → 0.4.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.
@@ -16,7 +16,40 @@ export const MAX_RESULTS = 500;
16
16
  * share the unversioned `<digest>.sqlite`; the first run of a newer version builds its own file once.
17
17
  */
18
18
  export const LINK_RESOLUTION = 2;
19
- const indexName = (root: string) => `${digest(root)}-links${LINK_RESOLUTION}.sqlite`;
19
+ /** Bump when tables or FTS columns change. Named per value like LINK_RESOLUTION. 2 = CJK bigram table. */
20
+ export const INDEX_SCHEMA = 2;
21
+ const indexName = (root: string) => `${digest(root)}-links${LINK_RESOLUTION}-schema${INDEX_SCHEMA}.sqlite`;
22
+ /**
23
+ * unicode61 keeps each Hangul/CJK run as one token, so `사업단` misses `사업단은`. A side table holds the
24
+ * overlapping bigrams of every CJK run of 2+ characters, runs split by a `0` token; a CJK query term then matches
25
+ * one bigram (2 characters) or a phrase of consecutive bigrams, which is exact substring matching. A separate
26
+ * table keeps bm25 of the unicode61 table, whose document length spans all columns, unchanged for Latin queries.
27
+ */
28
+ export const GRAMS_COLUMNS = "path UNINDEXED, title, description, body";
29
+ const CJK = "\\p{sc=Hangul}\\p{sc=Han}\\p{sc=Hiragana}\\p{sc=Katakana}";
30
+ const CJK_RUN = new RegExp(`[${CJK}]{2,}`, "gu"), CJK_TERM = new RegExp(`^[${CJK}]{2,}$`, "u");
31
+ function bigrams(run: string): string[] {
32
+ const chars = [...run];
33
+ return chars.slice(1).map((char, i) => chars[i]! + char);
34
+ }
35
+ export function grams(text: string): string {
36
+ return [...text.normalize("NFC").matchAll(CJK_RUN)].map(([run]) => `${bigrams(run).join(" ")} 0`).join(" ");
37
+ }
38
+ export const gramPhrase = (run: string) => `"${bigrams(run).join(" ")}"`;
39
+ /**
40
+ * Literal AND terms: users cannot inject FTS operators, columns or SQL. A term whose letters and digits form one
41
+ * CJK run of 2+ characters (`runs`) matches as a substring through the bigram table; any other term (`tokens`,
42
+ * quoted) keeps unicode61 token matching.
43
+ */
44
+ export function splitTerms(words: string[]): { tokens: string[]; runs: string[] } {
45
+ const tokens: string[] = [], runs: string[] = [];
46
+ for (const term of words) {
47
+ const letters = term.normalize("NFC").match(/[\p{L}\p{N}]+/gu);
48
+ if (letters?.length === 1 && CJK_TERM.test(letters[0]!)) runs.push(letters[0]!);
49
+ else tokens.push(`"${term.replaceAll('"', '""')}"`);
50
+ }
51
+ return { tokens, runs };
52
+ }
20
53
  export const MAX_READ_BYTES = 64 * 1024;
21
54
  export interface IndexedNote extends LinkNote { hash: string; description: string; type: string; domain: string }
22
55
  export interface NoteReadResult {
@@ -62,6 +95,11 @@ function aliases(value: unknown): string[] {
62
95
  function metadata(stat: NonNullable<ReturnType<typeof lstatSync>>): string {
63
96
  return [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
64
97
  }
98
+ /** The mtime (epoch ms) stored in a `metadata()` stamp, or null when the stamp has another shape. */
99
+ function stampMtime(stamp: string): number | null {
100
+ const value = Number(stamp.split(":")[3]);
101
+ return stamp.split(":").length === 5 && Number.isFinite(value) ? value : null;
102
+ }
65
103
  /** Adapter file I/O gets path-specific guidance without rewriting unrelated Git or binding errors. */
66
104
  function specFileIO<T>(path: string, action: string, operation: () => T): T {
67
105
  try { return operation(); }
@@ -78,7 +116,7 @@ function boundedText(value: string, bytes: number): { content: string; truncated
78
116
  while (end > 0 && (buffer[end]! & 0xc0) === 0x80) end--;
79
117
  return { content: buffer.subarray(0, end).toString("utf8"), truncated: true };
80
118
  }
81
- function readPage(prefix: Buffer, maxBytes: number, offset: number, totalBytes: number): Pick<NoteReadResult, "content" | "truncated" | "nextOffset"> {
119
+ export function readPage(prefix: Buffer, maxBytes: number, offset: number, totalBytes: number): Pick<NoteReadResult, "content" | "truncated" | "nextOffset"> {
82
120
  if (offset > totalBytes) throw new Error("offset: exceeds requested note or section");
83
121
  if (prefix.length && (prefix[0]! & 0xc0) === 0x80) throw new Error("offset: must be a UTF-8 character boundary");
84
122
  let end = Math.min(maxBytes, prefix.length);
@@ -87,7 +125,7 @@ function readPage(prefix: Buffer, maxBytes: number, offset: number, totalBytes:
87
125
  const truncated = offset + end < totalBytes;
88
126
  return { content: prefix.subarray(0, end).toString("utf8"), truncated, ...(truncated ? { nextOffset: offset + end } : {}) };
89
127
  }
90
- function h2Sections(body: string): { name: string; start: number; end: number }[] {
128
+ export function h2Sections(body: string): { name: string; start: number; end: number }[] {
91
129
  const visible = proseLines(body), lines = body.match(/[^\n]*\n|[^\n]+$/g) ?? [];
92
130
  const sections: { name: string; start: number; end: number }[] = [];
93
131
  let offset = 0, active: number | undefined;
@@ -104,7 +142,7 @@ function h2Sections(body: string): { name: string; start: number; end: number }[
104
142
  }
105
143
  return sections;
106
144
  }
107
- function headingMetadata(sections: { name: string }[]): Pick<NoteReadResult, "headings" | "headingsTruncated"> {
145
+ export function headingMetadata(sections: { name: string }[]): Pick<NoteReadResult, "headings" | "headingsTruncated"> {
108
146
  const headings: string[] = [];
109
147
  let bytes = 2, truncated = false;
110
148
  for (const { name } of sections) {
@@ -120,7 +158,8 @@ export interface IndexSourceAdapter {
120
158
  paths(): string[];
121
159
  validatePath(path: string): void;
122
160
  accept(path: string, document: FrontmatterDocument, hash: string): boolean;
123
- invalid(path: string): void;
161
+ invalid(path: string): boolean | void;
162
+ skipFile?(path: string, reason: "oversized" | "invalid_utf8", bytes: Buffer): boolean;
124
163
  }
125
164
  export class IndexCacheError extends Error {}
126
165
  export interface IndexOptions { memory?: boolean; adapter?: IndexSourceAdapter; reuseCache?: boolean }
@@ -164,6 +203,7 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
164
203
  title TEXT NOT NULL, description TEXT NOT NULL, body TEXT NOT NULL,
165
204
  type TEXT NOT NULL, domain TEXT NOT NULL, aliases TEXT NOT NULL, source TEXT NOT NULL);
166
205
  CREATE VIRTUAL TABLE IF NOT EXISTS fts USING fts5(path UNINDEXED, title, description, body, tokenize='unicode61');
206
+ CREATE VIRTUAL TABLE IF NOT EXISTS grams USING fts5(${GRAMS_COLUMNS}, tokenize='unicode61');
167
207
  CREATE TABLE IF NOT EXISTS analysis_notes (path TEXT PRIMARY KEY, source TEXT NOT NULL, hash TEXT NOT NULL, metadata TEXT NOT NULL);
168
208
  CREATE TABLE IF NOT EXISTS links (source TEXT NOT NULL, ordinal INTEGER NOT NULL, data TEXT NOT NULL, PRIMARY KEY(source, ordinal));`);
169
209
  // Dry runs reuse the derived cache via a readonly connection, then refresh only changed notes in memory.
@@ -181,7 +221,7 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
181
221
  if (size.count > 10000 || size.bytes > 64 * 1024 * 1024) throw new Error("analysis: cached snapshot exceeds bound");
182
222
  for (const row of disk.query<Omit<StoredNote,"aliases"> & {aliases:string}, []>("SELECT * FROM notes").all()) {
183
223
  this.db.query("INSERT INTO notes VALUES (?,?,?,?,?,?,?,?,?,?)").run(row.path,row.hash,row.metadata,row.title,row.description,row.body,row.type,row.domain,row.aliases,row.source);
184
- this.db.query("INSERT INTO fts VALUES (?,?,?,?)").run(row.path,row.title,row.description,row.body);
224
+ this.indexText(row.path, row.title, row.description, row.body);
185
225
  }
186
226
  for (const row of disk.query<{source:string;ordinal:number;data:string}, []>("SELECT * FROM links").all()) this.db.query("INSERT INTO links VALUES (?,?,?)").run(row.source,row.ordinal,row.data);
187
227
  this.db.run(`PRAGMA user_version = ${Number(disk.query<{ user_version: number }, []>("PRAGMA user_version").get()?.user_version ?? 0)}`);
@@ -201,38 +241,53 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
201
241
  }
202
242
  }
203
243
  close(): void { this.db.close(); }
244
+ // ponytail: grams stores its bigram text (about 2.3x the CJK bytes); contentless with stable rowids would save it.
245
+ private indexText(path: string, title: string, description: string, body: string): void {
246
+ this.db.query("INSERT INTO fts VALUES (?,?,?,?)").run(path, title, description, body);
247
+ this.db.query("INSERT INTO grams VALUES (?,?,?,?)").run(path, grams(title), grams(description), grams(body));
248
+ }
249
+ private unindex(path: string): void {
250
+ this.db.query("DELETE FROM fts WHERE path=?").run(path);
251
+ this.db.query("DELETE FROM grams WHERE path=?").run(path);
252
+ }
204
253
  private stored(): LinkNote[] {
205
254
  return this.db.query<Omit<LinkNote, "aliases"> & { aliases: string }, []>("SELECT path,title,aliases,body FROM notes ORDER BY path").all().map(row => ({ ...row, aliases: JSON.parse(row.aliases) as string[] }));
206
255
  }
207
256
  /** Scan metadata each call; hash only new or metadata-changed files. Atomic cache update. */
208
257
  scan(rebuild = false, options: { skipInvalidFrontmatter?: boolean; captureInvalidFrontmatter?: boolean } = {}): { notes: number; changed: number; removed: number; skipped?: string[] } {
209
- return this.db.transaction(() => {
258
+ // Discovery/binding Git calls must never hold a SQLite writer lock.
259
+ let preparedPaths: string[] | undefined;
260
+ if (this.adapter) { this.adapter.validate(); preparedPaths = this.adapter.paths(); }
261
+ const result = this.db.transaction(() => {
210
262
  const notesDir = join(this.root, "notes");
211
- if (this.adapter) this.adapter.validate();
212
- else if (realpathSync(this.root) !== this.root || realpathSync(notesDir) !== notesDir || !lstatSync(notesDir).isDirectory()) throw new Error(`vault ${this.vault.id}: path or notes directory changed`);
263
+ if (!this.adapter && (realpathSync(this.root) !== this.root || realpathSync(notesDir) !== notesDir || !lstatSync(notesDir).isDirectory())) throw new Error(`vault ${this.vault.id}: path or notes directory changed`);
213
264
  const indexed = this.adapter ? new Set(this.db.query<{path:string}, []>("SELECT path FROM notes").all().map(row => row.path)) : undefined;
214
265
  const previous = new Map(this.db.query<{ path: string; hash: string; metadata: string }, []>(this.adapter ? "SELECT path,hash,metadata FROM analysis_notes" : options.captureInvalidFrontmatter ? "SELECT path,hash,metadata FROM notes UNION SELECT path,hash,metadata FROM analysis_notes" : "SELECT path,hash,metadata FROM notes").all().map(note => [note.path, note]));
215
- if (rebuild) this.db.run("DELETE FROM fts");
266
+ if (rebuild) this.db.run("DELETE FROM fts; DELETE FROM grams;");
216
267
  const live = new Set<string>(), present = new Set<string>();
217
268
  let changed = 0, analysisBytes = 0;
218
269
  const skipped: string[] = [], touched = new Set<string>(), keys = new Set<string>();
219
270
  // Links resolve by path only, so other notes re-resolve only when they target a touched path.
220
271
  const touch = (path: string) => { touched.add(path); keys.add(noteKey(path)); };
221
- const paths = this.adapter ? this.adapter.paths() : readdirSync(notesDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).filter(entry => entry.name.endsWith(".md") && entry.isFile()).map(entry => entry.name);
272
+ const paths = preparedPaths ?? readdirSync(notesDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).filter(entry => entry.name.endsWith(".md") && entry.isFile()).map(entry => entry.name);
222
273
  for (const path of paths) {
223
274
  this.adapter?.validatePath(path);
224
275
  const file = join(this.adapter ? this.root : notesDir, path);
225
276
  const before = this.adapter ? specFileIO(path, "inspect", () => lstatSync(file)) : lstatSync(file);
226
277
  if (!before.isFile() || before.isSymbolicLink()) throw new Error(this.adapter ? `spec discovery ${path}: selected path changed; restore a plain file and retry` : `vault ${this.vault.id}: note path changed`);
227
- if (before.size > MAX_NOTE_BYTES) throw new Error(this.adapter ? `spec discovery ${path}: Markdown exceeds ${MAX_NOTE_BYTES} bytes; split the file before rebuilding` : `vault ${this.vault.id}, ${path}: note exceeds ${MAX_NOTE_BYTES} bytes`);
278
+ if (!this.adapter && before.size > MAX_NOTE_BYTES) throw new Error(`vault ${this.vault.id}, ${path}: note exceeds ${MAX_NOTE_BYTES} bytes`);
228
279
  live.add(path); present.add(path);
229
- if (options.captureInvalidFrontmatter || this.adapter) {
280
+ if (options.captureInvalidFrontmatter && !this.adapter) {
230
281
  analysisBytes += before.size;
231
282
  if (present.size > 10000 || analysisBytes > 64 * 1024 * 1024) throw new Error(this.adapter ? `spec discovery ${path}: more than 10000 Markdown files or 64 MiB of input; ignore large or vendored Markdown via .gitignore and untrack already-tracked excluded files with git rm --cached before rebuilding` : "analysis: snapshot exceeds bound");
232
283
  }
284
+ if (this.adapter) {
285
+ analysisBytes += Math.min(before.size, MAX_NOTE_BYTES + 1);
286
+ if (present.size > 10000 || analysisBytes > 64 * 1024 * 1024) throw new Error(`spec discovery ${path}: more than 10000 Markdown inputs or 64 MiB of bounded reads; ignore vendored Markdown via .gitignore and untrack excluded files with git rm --cached`);
287
+ }
233
288
  const old = previous.get(path), stamp = metadata(before);
234
289
  if (!this.adapter && !rebuild && old?.metadata === stamp && this.db.query("SELECT 1 FROM analysis_notes WHERE path=?").get(path)) continue;
235
- const cached = this.adapter && !rebuild && old?.metadata === stamp ? this.db.query<{source:string}, [string]>("SELECT source FROM analysis_notes WHERE path=?").get(path) : null;
290
+ const cached = this.adapter && before.size <= MAX_NOTE_BYTES && !rebuild && old?.metadata === stamp ? this.db.query<{source:string}, [string]>("SELECT source FROM analysis_notes WHERE path=?").get(path) : null;
236
291
  let source: string, hash: string;
237
292
  if (cached && old) { source = cached.source; hash = old.hash; }
238
293
  else {
@@ -240,7 +295,7 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
240
295
  let buffer: Buffer;
241
296
  try {
242
297
  const stat = this.adapter ? specFileIO(path, "inspect", () => fstatSync(fd)) : fstatSync(fd);
243
- if (!stat.isFile() || stat.size > MAX_NOTE_BYTES || metadata(stat) !== stamp) throw new Error(this.adapter ? `spec discovery ${path}: file changed during scan; retry on a stable worktree` : `vault ${this.vault.id}, ${path}: note changed during scan`);
298
+ if (!stat.isFile() || (!this.adapter && stat.size > MAX_NOTE_BYTES) || metadata(stat) !== stamp) throw new Error(this.adapter ? `spec discovery ${path}: file changed during scan; retry on a stable worktree` : `vault ${this.vault.id}, ${path}: note changed during scan`);
244
299
  // Fixed bound even if a concurrent writer grows the file.
245
300
  buffer = Buffer.alloc(MAX_NOTE_BYTES + 1);
246
301
  let size = 0;
@@ -250,15 +305,28 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
250
305
  if (!count || size === buffer.length) break;
251
306
  }
252
307
  buffer = buffer.subarray(0, size);
253
- if (size > MAX_NOTE_BYTES || metadata(this.adapter ? specFileIO(path, "inspect", () => fstatSync(fd)) : fstatSync(fd)) !== stamp) throw new Error(this.adapter ? `spec discovery ${path}: file changed during scan; retry on a stable worktree` : `vault ${this.vault.id}, ${path}: note changed during scan`);
308
+ if ((!this.adapter && size > MAX_NOTE_BYTES) || metadata(this.adapter ? specFileIO(path, "inspect", () => fstatSync(fd)) : fstatSync(fd)) !== stamp) throw new Error(this.adapter ? `spec discovery ${path}: file changed during scan; retry on a stable worktree` : `vault ${this.vault.id}, ${path}: note changed during scan`);
254
309
  } finally { if (this.adapter) specFileIO(path, "close", () => closeSync(fd)); else closeSync(fd); }
310
+ this.adapter?.validatePath(path);
311
+ if (this.adapter && metadata(specFileIO(path, "inspect", () => lstatSync(file))) !== stamp) throw new Error(`spec discovery ${path}: file changed during read; retry on a stable worktree`);
255
312
  if (this.adapter) {
313
+ const skip = (reason: "oversized" | "invalid_utf8") => {
314
+ if (!this.adapter?.skipFile?.(path, reason, buffer.subarray(0, MAX_NOTE_BYTES))) return false;
315
+ live.delete(path); skipped.push(path);
316
+ this.db.query("DELETE FROM analysis_notes WHERE path=?").run(path);
317
+ return true;
318
+ };
319
+ if (before.size > MAX_NOTE_BYTES || buffer.length > MAX_NOTE_BYTES) {
320
+ if (skip("oversized")) continue;
321
+ throw new Error(`spec discovery ${path}: Markdown exceeds ${MAX_NOTE_BYTES} bytes; split the candidate before validating`);
322
+ }
256
323
  try { source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buffer); }
257
- catch { throw new Error(`spec discovery ${path}: Markdown is not valid UTF-8; re-encode the file as UTF-8 before rebuilding`); }
324
+ catch {
325
+ if (skip("invalid_utf8")) continue;
326
+ throw new Error(`spec discovery ${path}: Markdown is not valid UTF-8; re-encode the candidate as UTF-8 before validating`);
327
+ }
258
328
  } else source = buffer.toString("utf8");
259
329
  hash = digest(buffer);
260
- this.adapter?.validatePath(path);
261
- if (this.adapter && metadata(specFileIO(path, "inspect", () => lstatSync(file))) !== stamp) throw new Error(`spec discovery ${path}: file changed during read; retry on a stable worktree`);
262
330
  this.db.query("INSERT OR REPLACE INTO analysis_notes VALUES (?,?,?,?)").run(path, source, hash, stamp);
263
331
  }
264
332
  if (!this.adapter && !rebuild && old?.hash === hash) { this.db.query("UPDATE notes SET metadata=? WHERE path=?").run(stamp, path); continue; }
@@ -266,8 +334,8 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
266
334
  try { document = parseFrontmatter(source); }
267
335
  catch {
268
336
  if (!this.adapter && !options.skipInvalidFrontmatter && !options.captureInvalidFrontmatter) throw new Error(`vault ${this.vault.id}, ${path}: invalid frontmatter`);
269
- this.adapter?.invalid(path);
270
- live.delete(path); skipped.push(path); continue;
337
+ const report = this.adapter?.invalid(path);
338
+ live.delete(path); if (report !== false) skipped.push(path); continue;
271
339
  }
272
340
  if (this.adapter) {
273
341
  this.adapter.validatePath(path);
@@ -278,19 +346,19 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
278
346
  }
279
347
  const { data, body } = document;
280
348
  touch(path);
349
+ const title = text(data.title) || path.slice(0, -3), description = text(data.description);
281
350
  this.db.query("INSERT OR REPLACE INTO notes VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)").run(path, hash, stamp,
282
- text(data.title) || path.slice(0, -3), text(data.description), body, text(data.type), text(data.domain), JSON.stringify(aliases(data.aliases ?? data.alias)), source);
283
- this.db.query("DELETE FROM fts WHERE path=?").run(path);
284
- this.db.query("INSERT INTO fts(path,title,description,body) SELECT path,title,description,body FROM notes WHERE path=?").run(path);
351
+ title, description, body, text(data.type), text(data.domain), JSON.stringify(aliases(data.aliases ?? data.alias)), source);
352
+ this.unindex(path);
353
+ this.indexText(path, title, description, body);
285
354
  changed++;
286
355
  }
287
356
  for (const row of this.db.query<{path:string}, []>("SELECT path FROM analysis_notes").all()) if (!present.has(row.path)) this.db.query("DELETE FROM analysis_notes WHERE path=?").run(row.path);
288
357
  let removed = 0;
289
- for (const path of indexed ?? previous.keys()) if (!live.has(path)) { touch(path); this.db.query("DELETE FROM notes WHERE path=?").run(path); this.db.query("DELETE FROM fts WHERE path=?").run(path); removed++; }
358
+ for (const path of indexed ?? previous.keys()) if (!live.has(path)) { touch(path); this.db.query("DELETE FROM notes WHERE path=?").run(path); this.unindex(path); removed++; }
290
359
  if (this.adapter) {
291
360
  // Spec links are resolved by frontmatter id in buildSpecGraph, never by vault paths.
292
361
  this.db.run("DELETE FROM links");
293
- this.adapter.validate();
294
362
  return { notes: live.size, changed, removed, ...(skipped.length ? { skipped } : {}) };
295
363
  }
296
364
  const stale = this.db.query<{ user_version: number }, []>("PRAGMA user_version").get()?.user_version !== LINK_RESOLUTION;
@@ -313,6 +381,8 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
313
381
  if (stale) this.db.run(`PRAGMA user_version = ${LINK_RESOLUTION}`);
314
382
  return { notes: live.size, changed, removed, ...(skipped.length ? { skipped } : {}) };
315
383
  }).immediate();
384
+ this.adapter?.validate();
385
+ return result;
316
386
  }
317
387
  /** Consume cached note sources only. Auxiliary inputs are captured separately by analysisInput. */
318
388
  analysisSnapshot(inputs: Omit<AnalysisSnapshot, "notes">): AnalysisSnapshot {
@@ -321,16 +391,26 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
321
391
  const notes = this.db.query<{path: string; source: string}, []>("SELECT path,source FROM analysis_notes ORDER BY path").all();
322
392
  return { ...inputs, notes };
323
393
  }
324
- search(query: string, options: SearchOptions = {}, snapshot?: ReadonlyMap<string, string>): SearchResult[] {
394
+ search(query: string, options: SearchOptions = {}, snapshot?: ReadonlyMap<string, string>, snapshotOffset = 0, allSnapshotRows = false): SearchResult[] {
325
395
  const limit = resultLimit(options.limit);
326
396
  if (!query.trim() || Buffer.byteLength(query) > 1024) throw new Error("search: query must contain 1..1024 bytes");
327
- // Literal AND terms: users cannot inject FTS operators, columns or SQL.
328
- const terms = query.trim().split(/\s+/).map(term => `"${term.replaceAll('"', '""')}"`).join(" AND ");
397
+ const { tokens, runs } = splitTerms(query.trim().split(/\s+/));
329
398
  const hashColumn = snapshot ? ",n.hash AS sourceHash" : "";
330
- return this.db.query<SearchResult & { sourceHash?: string }, [string, string | null, string | null, string | null, string | null, number]>(`SELECT n.path, n.title, substr(n.description,1,512) AS description, n.type, n.domain,
399
+ const filters = [options.type ?? null, options.type ?? null, options.domain ?? null, options.domain ?? null, snapshot ? 10000 : limit];
400
+ // Latin-only queries run the unicode61 query unchanged. With a CJK term the bigram table drives the match, and a
401
+ // note where every CJK term is a standalone word or sits in the title/description ranks before substring-only hits.
402
+ const strong = runs.map(() => "(n.path IN (SELECT path FROM fts WHERE fts MATCH ?) OR n.path IN (SELECT path FROM grams WHERE grams MATCH ?))").join(" AND ");
403
+ const rows = !runs.length
404
+ ? this.db.query<SearchResult & { sourceHash?: string }, (string | number | null)[]>(`SELECT n.path, n.title, substr(n.description,1,512) AS description, n.type, n.domain,
331
405
  bm25(fts,0,5,2,1) AS score, snippet(fts,3,'','',' ... ',32) AS snippet${hashColumn} FROM fts JOIN notes n ON n.path=fts.path
332
- WHERE fts MATCH ? AND (? IS NULL OR n.type=?) AND (? IS NULL OR n.domain=?) ORDER BY score,n.path LIMIT ?`).all(terms, options.type ?? null, options.type ?? null, options.domain ?? null, options.domain ?? null, limit)
333
- .filter(row => !snapshot || snapshot.get(row.path) === row.sourceHash)
406
+ WHERE fts MATCH ? AND (? IS NULL OR n.type=?) AND (? IS NULL OR n.domain=?) ORDER BY score,n.path LIMIT ?`).all(tokens.join(" AND "), ...filters)
407
+ : this.db.query<SearchResult & { sourceHash?: string }, (string | number | null)[]>(`SELECT n.path, n.title, substr(n.description,1,512) AS description, n.type, n.domain,
408
+ bm25(grams,0,5,2,1) AS score, substr(n.body, max(1, instr(n.body, ?) - 48), 160) AS snippet${hashColumn} FROM grams JOIN notes n ON n.path=grams.path
409
+ WHERE grams MATCH ? ${tokens.length ? "AND n.path IN (SELECT path FROM fts WHERE fts MATCH ?)" : ""} AND (? IS NULL OR n.type=?) AND (? IS NULL OR n.domain=?)
410
+ ORDER BY NOT (${strong}),score,n.path LIMIT ?`).all(runs[0]!, runs.map(gramPhrase).join(" AND "), ...(tokens.length ? [tokens.join(" AND ")] : []), ...filters.slice(0, 4),
411
+ ...runs.flatMap(run => [`"${run}"`, `{title description} : ${gramPhrase(run)}`]), filters[4]!);
412
+ return rows.filter(row => !snapshot || snapshot.get(row.path) === row.sourceHash)
413
+ .slice(snapshot ? snapshotOffset : 0, (snapshot ? snapshotOffset : 0) + (snapshot && allSnapshotRows ? 10000 : limit))
334
414
  .map(({ sourceHash: _, ...row }) => ({ ...row, title: boundedText(row.title, 512).content, snippet: boundedText(row.snippet, 1024).content, type: boundedText(row.type, 256).content, domain: boundedText(row.domain, 256).content }));
335
415
  }
336
416
  private find(target: string): string {
@@ -375,13 +455,51 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
375
455
  }
376
456
  return { path, hash: note.hash, ...readPage(Buffer.from(note.prefix), maxBytes, start, note.bytes), ...metadata, ...headingMetadata(sections) };
377
457
  }
378
- /** Indexed notes (paths relative to notes/) ordered by path, optionally filtered by a literal stem prefix. */
379
- list(prefix = "", limit = 50): { path: string; title: string; type: string; domain: string; description: string }[] {
458
+ /**
459
+ * Indexed notes (paths relative to notes/) ordered by path, optionally filtered by a literal stem prefix.
460
+ * `cursor` is the previous page's `nextCursor` (its last path, exclusive); `total` counts the filtered set.
461
+ */
462
+ list(prefix = "", limit = 50, cursor?: string): { notes: { path: string; title: string; type: string; domain: string; description: string; mtime: string | null }[]; total: number; nextCursor?: string } {
380
463
  if (Buffer.byteLength(prefix) > 1024) throw new Error("prefix: expected <=1024 bytes");
381
- const key = prefix.replace(/^notes\//i, "");
382
- return this.db.query<{ path: string; title: string; type: string; domain: string; description: string }, [number, string, number]>(
383
- "SELECT path,title,type,domain,substr(description,1,512) AS description FROM notes WHERE substr(path,1,?)=? ORDER BY path LIMIT ?"
384
- ).all(key.length, key, resultLimit(limit)).map(row => ({ ...row, title: boundedText(row.title, 512).content, type: boundedText(row.type, 256).content, domain: boundedText(row.domain, 256).content, description: boundedText(row.description, 512).content }));
464
+ const key = prefix.replace(/^notes\//i, ""), max = resultLimit(limit);
465
+ if (cursor !== undefined && (!cursor || Buffer.byteLength(cursor) > 1024 || !cursor.startsWith(key))) throw new Error("cursor: expected the nextCursor of a previous page listed with the same prefix; list again without cursor to restart");
466
+ const rows = this.db.query<{ path: string; title: string; type: string; domain: string; description: string; metadata: string }, [number, string, string, number]>(
467
+ "SELECT path,title,type,domain,substr(description,1,512) AS description,metadata FROM notes WHERE substr(path,1,?)=? AND path>? ORDER BY path LIMIT ?"
468
+ ).all(key.length, key, cursor ?? "", max + 1);
469
+ const total = this.db.query<{ count: number }, [number, string]>("SELECT count(*) AS count FROM notes WHERE substr(path,1,?)=?").get(key.length, key)!.count;
470
+ const notes = rows.slice(0, max).map(({ metadata: stamp, ...row }) => {
471
+ const mtime = stampMtime(stamp);
472
+ return { ...row, title: boundedText(row.title, 512).content, type: boundedText(row.type, 256).content, domain: boundedText(row.domain, 256).content, description: boundedText(row.description, 512).content, mtime: mtime === null ? null : new Date(mtime).toISOString() };
473
+ });
474
+ return { notes, total, ...(rows.length > max ? { nextCursor: notes.at(-1)!.path } : {}) };
475
+ }
476
+ /**
477
+ * Note counts by type, domain and frontmatter `status` ("(none)" when empty), and how many notes have an mtime at or
478
+ * after each cutoff (epoch ms). Streams rows; returns no note text.
479
+ */
480
+ noteStats(cutoffs: readonly number[]): { total: number; byType: Record<string, number>; byDomain: Record<string, number>; byStatus: Record<string, number>; modified: number[] } {
481
+ const add = (map: Map<string, number>, value: string, count = 1) => { const key = value ? boundedText(value, 256).content : "(none)"; map.set(key, (map.get(key) ?? 0) + count); };
482
+ const sorted = (map: Map<string, number>) => Object.fromEntries([...map].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
483
+ const grouped = (column: "type" | "domain") => {
484
+ const map = new Map<string, number>();
485
+ for (const row of this.db.query<{ value: string; count: number }, []>(`SELECT ${column} AS value, count(*) AS count FROM notes GROUP BY ${column}`).all()) add(map, row.value, row.count);
486
+ return sorted(map);
487
+ };
488
+ // Status is not a column: stream each stored source once, parsing only its frontmatter.
489
+ const byStatus = new Map<string, number>(), modified = cutoffs.map(() => 0);
490
+ let total = 0;
491
+ const rows = this.db.prepare<{ metadata: string; source: string }, []>("SELECT metadata,source FROM notes");
492
+ try {
493
+ for (const row of rows.iterate()) {
494
+ total++;
495
+ let status: unknown;
496
+ try { status = parseFrontmatter(row.source).data.status; } catch { /* counted as (none) */ }
497
+ add(byStatus, text(status));
498
+ const mtime = stampMtime(row.metadata);
499
+ cutoffs.forEach((cutoff, i) => { if (mtime !== null && mtime >= cutoff) modified[i]!++; });
500
+ }
501
+ } finally { rows.finalize(); }
502
+ return { total, byType: grouped("type"), byDomain: grouped("domain"), byStatus: sorted(byStatus), modified };
385
503
  }
386
504
  /** Links that resolve to the target note, ordered by source. */
387
505
  backlinks(target: string, limit = 50): ResolvedLink[] {
package/src/vault-log.ts CHANGED
@@ -67,6 +67,16 @@ function context(home: string, id: string, channel: "cli" | "mcp" | undefined, w
67
67
  if (isDenied(join(vault.path, "log"), config.denyPaths)) refuse("V06", "log path is denied");
68
68
  return { vault, config, channel, ...(write && vault.registry ? { projectIds: registryIds(vault.registry, config.denyPaths) } : {}) };
69
69
  }
70
+ /** Validate and screen an event exactly as `appendLog` would, writing nothing. Returns the blocking issues (empty when valid). */
71
+ export function checkLogEvent(home: string, request: LogRequest, env: NodeJS.ProcessEnv = process.env): WriteIssue[] {
72
+ try {
73
+ const ctx = context(home, request.vault, request.channel, true);
74
+ return formatLogEvent(request.event, { ...ctx, env }).issues.filter(issue => issue.severity === "error");
75
+ } catch (caught) {
76
+ if (caught instanceof LogRefused) return caught.issues;
77
+ throw caught;
78
+ }
79
+ }
70
80
  /** One O_APPEND write per event. A separate cooperative lock permits safe short-write rollback. */
71
81
  /** Bind a later append to the vault spec, path policy and root identity resolved now (refused with LOG_DRIFT if they change). */
72
82
  export function logBinding(vault: VaultSpec, config: VmemConfig): LogBinding {
@@ -189,7 +199,7 @@ export function readLog(home: string, options: LogReadOptions): LogReadResult {
189
199
  const result: LogReadResult = { ok: false, lines: [], dataLines: null, warnings: [], issues: [] };
190
200
  let fd: number | undefined;
191
201
  try {
192
- if (!options || typeof options !== "object" || typeof options.vault !== "string" || Object.keys(options).some(key => !["vault", "limit", "grep", "type"].includes(key))) refuse("L09", "invalid log read options");
202
+ if (!options || typeof options !== "object" || typeof options.vault !== "string" || Object.keys(options).some(key => !["vault", "limit", "grep", "type", "visit"].includes(key)) || (options.visit !== undefined && typeof options.visit !== "function")) refuse("L09", "invalid log read options");
193
203
  const limit = options.limit ?? 50;
194
204
  if (!Number.isInteger(limit) || limit < 1 || limit > 200) refuse("L09", "log limit must be an integer 1..200");
195
205
  if (options.type !== undefined && !(LOG_TYPES as readonly string[]).includes(options.type)) refuse("L09", "unknown log type filter");
@@ -222,6 +232,7 @@ export function readLog(home: string, options: LogReadOptions): LogReadResult {
222
232
  } else {
223
233
  const line = pending.endsWith("\r") ? pending.slice(0, -1) : pending;
224
234
  const type = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}\s+(\S+)/.exec(line)?.[1];
235
+ options.visit?.(line);
225
236
  if ((!options.type || options.type === type) && (!filter || filter(line))) {
226
237
  result.lines.push(line); resultBytes += Buffer.byteLength(JSON.stringify(line)) + 1;
227
238
  while (result.lines.length > limit || resultBytes > MAX_LOG_RESULT_BYTES) resultBytes -= Buffer.byteLength(JSON.stringify(result.lines.shift()!)) + 1;
@@ -0,0 +1,50 @@
1
+ import { localDate } from "./local-date.ts";
2
+ import { LOG_TYPES } from "./log-format.ts";
3
+ import { loadRegistry } from "./registry.ts";
4
+ import { VaultIndex } from "./vault-index.ts";
5
+ import { readLog } from "./vault-log.ts";
6
+ import type { WriteIssue } from "./write-types.ts";
7
+ import type { VaultSpec } from "./config.ts";
8
+
9
+ export const STATS_DEFAULT_DAYS = 30;
10
+ export const STATS_MAX_DAYS = 3650;
11
+ export interface VaultStats {
12
+ vault: string;
13
+ /** Local calendar date the windows end on (today included). */
14
+ asOf: string;
15
+ notes: { total: number; byType: Record<string, number>; byDomain: Record<string, number>; byStatus: Record<string, number> };
16
+ /** Notes whose indexed mtime falls within the last 7 and 30 local calendar days, today included. */
17
+ modified: { last7Days: number; last30Days: number };
18
+ /** Log events dated on or after `since` (local date), by type; types outside the known set count as "(other)". */
19
+ log: { days: number; since: string; total: number | null; byType: Record<string, number> | null; warnings: string[]; issues: WriteIssue[] };
20
+ }
21
+ /**
22
+ * Read-only vault statistics over the derived index (refreshed like every read tool) and the log streamed by `readLog`:
23
+ * no vault file or log is written and no vault or log lock is taken.
24
+ */
25
+ export function vaultStats(home: string, id: string, options: { days?: number; now?: Date; expectedVault?: VaultSpec } = {}): VaultStats {
26
+ const days = options.days ?? STATS_DEFAULT_DAYS, now = options.now ?? new Date();
27
+ if (!Number.isInteger(days) || days < 1 || days > STATS_MAX_DAYS) throw new Error(`stats: days must be an integer 1..${STATS_MAX_DAYS}; omit it for the ${STATS_DEFAULT_DAYS}-day default`);
28
+ const registry = loadRegistry(home), vault = registry.vaults.find(v => v.id === id);
29
+ if (!vault) throw Object.assign(new Error("stats: unknown vault id; run vmem vaults list for the registered ids"), { code: "V04" });
30
+ // An MCP server reads the vault set fixed at startup; a re-registered id would otherwise count a different vault.
31
+ if (options.expectedVault && JSON.stringify(options.expectedVault) !== JSON.stringify(vault)) throw new Error("stats: the vault registration changed since the MCP server started; restart the MCP server");
32
+ // Local midnight that opens a window of n calendar days ending today.
33
+ const start = (n: number) => new Date(now.getFullYear(), now.getMonth(), now.getDate() - (n - 1));
34
+ const index = new VaultIndex(home, vault, registry.vaults.map(v => v.path));
35
+ let notes: ReturnType<VaultIndex["noteStats"]>;
36
+ try { index.scan(); notes = index.noteStats([start(7).getTime(), start(30).getTime()]); } finally { index.close(); }
37
+ const since = localDate(start(days)), byType: Record<string, number> = Object.fromEntries(LOG_TYPES.map(type => [type, 0]));
38
+ let total = 0;
39
+ const log = readLog(home, { vault: vault.id, limit: 1, visit: line => {
40
+ const match = /^(\d{4}-\d{2}-\d{2}) \d{2}:\d{2}\s+(\S+)/.exec(line);
41
+ if (!match || match[1]! < since) return;
42
+ const type = (LOG_TYPES as readonly string[]).includes(match[2]!) ? match[2]! : "(other)";
43
+ total++; byType[type] = (byType[type] ?? 0) + 1;
44
+ } });
45
+ const { modified: [last7Days = 0, last30Days = 0], ...counts } = notes;
46
+ return {
47
+ vault: vault.id, asOf: localDate(now), notes: counts, modified: { last7Days, last30Days },
48
+ log: { days, since, total: log.ok ? total : null, byType: log.ok ? byType : null, warnings: log.warnings, issues: log.issues },
49
+ };
50
+ }
@@ -5,7 +5,10 @@ import { loadRegistry } from "./registry.ts";
5
5
  import { basename } from "node:path";
6
6
  import { applyWrite, MAX_WRITE_BYTES } from "./writer.ts";
7
7
  import { notePath } from "./write-operations.ts";
8
- import type { WriteOp, WriteRequest } from "./write-types.ts";
8
+ import type { PatchEdit, WriteOp, WriteRequest } from "./write-types.ts";
9
+ import type { LogEvent } from "./log-types.ts";
10
+ import { LOG_EVENT_SCHEMA } from "./log-format.ts";
11
+ import { argumentError } from "./mcp.ts";
9
12
  import { parseTidyMap, tidyVault, TIDY_RULES } from "./tidy.ts";
10
13
  const COMMANDS = new Set(["new", "patch", "append", "frontmatter", "link", "supersede", "move", "delete", "tidy", "report", "check"]);
11
14
  export function isWriteCommand(command: string): boolean { return COMMANDS.has(command); }
@@ -29,15 +32,24 @@ function input(file: string, home: string): string {
29
32
  return text;
30
33
  } finally { if (file !== "-") closeSync(fd); }
31
34
  }
35
+ /** `--log JSON` checked against the same closed schema as the MCP `log` argument; registry and screening checks follow in applyWrite. */
36
+ function logOption(text: string | undefined): { log?: LogEvent } {
37
+ if (text === undefined) return {};
38
+ let value: unknown;
39
+ try { value = JSON.parse(text); } catch { throw new Error("--log: invalid JSON; expected {\"type\", \"project\", \"source\", \"note\"[, \"dest\"]}"); }
40
+ const error = argumentError(value, LOG_EVENT_SCHEMA, "--log");
41
+ if (error) throw new Error(`${error}; expected {"type", "project", "source", "note"[, "dest"]} as for log append`);
42
+ return { log: value as LogEvent };
43
+ }
32
44
  export function runWriteCommand(command: string, args: string[], home: string, env: NodeJS.ProcessEnv = process.env): { text: string; code: number } {
33
45
  const valueOptions: Record<string, string[]> = {
34
46
  new: ["--type", "--domain", "--topics", "--description", "--title", "--source", "--confidence", "--status", "--extra", "--body"],
35
- patch: ["--old", "--new", "--expected-sha"], append: ["--section", "--markdown", "--expected-sha"],
47
+ patch: ["--old", "--new", "--edits", "--expected-sha"], append: ["--section", "--markdown", "--expected-sha"],
36
48
  frontmatter: ["--set", "--unset", "--expected-sha"], link: ["--relation", "--context"],
37
49
  move: ["--fingerprint"], delete: ["--fingerprint"], tidy: ["--fingerprint", "--map"], report: ["--body"], check: ["--path"], supersede: [],
38
50
  };
39
- // For tidy, --log selects the log-redaction rule; tidy always writes its own LINT event.
40
- const values = valueOptions[command] ? [...valueOptions[command]!, ...(command === "tidy" ? [] : ["--log"])] : undefined;
51
+ // For tidy, --log selects the log-redaction rule; tidy always writes its own LINT event. Check never appends an event.
52
+ const values = valueOptions[command] ? [...valueOptions[command]!, ...(["tidy", "check"].includes(command) ? [] : ["--log"])] : undefined;
41
53
  if (!values) throw new Error("unknown writer command");
42
54
  const twoStep = ["move", "delete", "tidy"].includes(command);
43
55
  const booleans = ["--json", "--dry-run", ...(twoStep ? ["--confirm"] : []), ...(command === "link" ? ["--one-way"] : []), ...(command === "tidy" ? TIDY_RULES.map(rule => `--${rule}`).concat("--all") : [])];
@@ -80,7 +92,16 @@ export function runWriteCommand(command: string, args: string[], home: string, e
80
92
  if (optional("--topics") !== undefined) frontmatter.topics = required("--topics").split(",").filter(Boolean).map(value => value.startsWith("[[") ? value : `[[${value}]]`);
81
93
  operation = { op: "create", path: target, frontmatter, ...(optional("--body") ? { body: input(required("--body"), home) } : {}) }; break;
82
94
  }
83
- case "patch": operation = { op: "patch", path: target, oldString: required("--old"), newString: required("--new"), expectedSha: optional("--expected-sha") }; break;
95
+ case "patch": {
96
+ // --edits takes the same JSON array as the MCP `edits` argument.
97
+ if (optional("--edits") === undefined) { operation = { op: "patch", path: target, oldString: required("--old"), newString: required("--new"), expectedSha: optional("--expected-sha") }; break; }
98
+ if (optional("--old") !== undefined || optional("--new") !== undefined) throw new Error("patch: use --old/--new or --edits, not both");
99
+ const text = input(required("--edits"), home);
100
+ let edits: unknown;
101
+ try { edits = JSON.parse(text); } catch { throw new Error("--edits: invalid JSON; expected an array of {oldString, newString}"); }
102
+ if (!Array.isArray(edits)) throw new Error("--edits: expected a JSON array of {oldString, newString}");
103
+ operation = { op: "patch", path: target, edits: edits as PatchEdit[], expectedSha: optional("--expected-sha") }; break;
104
+ }
84
105
  case "append": operation = { op: "append", path: target, section: required("--section"), markdown: required("--markdown"), expectedSha: optional("--expected-sha") }; break;
85
106
  case "frontmatter": operation = { op: "frontmatter", path: target, set: optional("--set") ? object(required("--set"), "set") : {}, unset: optional("--unset")?.split(","), expectedSha: optional("--expected-sha") }; break;
86
107
  case "link": operation = { op: "link", from: target, to: positional[2]!, relation: required("--relation") as Extract<WriteOp, { op: "link" }>["relation"], context: optional("--context"), bidirectional: !flags["--one-way"] }; break;
@@ -92,7 +113,7 @@ export function runWriteCommand(command: string, args: string[], home: string, e
92
113
  case "check": operation = { op: "check", path: notePath(optional("--path") ?? (target === "-" ? "checked-note" : basename(target))), text: input(target, home) }; break;
93
114
  default: throw new Error("unknown writer command");
94
115
  }
95
- const request: WriteRequest = { vault, operation, channel: "cli", dryRun: flags["--dry-run"] === true, confirm: flags["--confirm"] === true, fingerprint: optional("--fingerprint"), ...(optional("--log") ? { log: object(required("--log"), "log") as unknown as import("./log-types.ts").LogEvent } : {}) };
116
+ const request: WriteRequest = { vault, operation, channel: "cli", dryRun: flags["--dry-run"] === true, confirm: flags["--confirm"] === true, fingerprint: optional("--fingerprint"), ...logOption(optional("--log")) };
96
117
  const result = applyWrite(home, request, { env });
97
118
  return { text: JSON.stringify(result, null, flags["--json"] ? undefined : 2), code: result.ok && result.log?.ok !== false ? 0 : 1 };
98
119
  }
@@ -2,7 +2,7 @@ import { isDeepStrictEqual } from "node:util";
2
2
  import { normalizeSource } from "./source.ts";
3
3
  import { parseFrontmatter, emitFrontmatter } from "./frontmatter.ts";
4
4
  import { normalizeTarget, proseLines, rewriteLinkTargets, extractLinks, resolveLinks, type LinkNote } from "./links.ts";
5
- import type { PlannedChange, WriteIssue, WriteOp } from "./write-types.ts";
5
+ import type { PatchEdit, PlannedChange, WriteIssue, WriteOp } from "./write-types.ts";
6
6
  export class WriteRefusal extends Error {
7
7
  constructor(readonly issues: WriteIssue[]) { super(issues[0]?.message ?? "write refused"); }
8
8
  }
@@ -149,11 +149,28 @@ export function planOperation(operation: WriteOp, notes: Map<string, string>, re
149
149
  }
150
150
  case "patch": {
151
151
  const { path, source } = existing(operation.path);
152
- if (typeof operation.oldString !== "string" || !operation.oldString || typeof operation.newString !== "string" || Buffer.byteLength(operation.oldString) > 8192 || Buffer.byteLength(operation.newString) > 8192) refuse("V09", "patch strings must be bounded and oldString nonempty", path);
153
- const first = source.indexOf(operation.oldString);
154
- if (first < 0 || source.indexOf(operation.oldString, first + 1) >= 0) refuse("V09", "oldString must match exactly once", path);
155
- if(first < (document(source,path).frontmatter?.length ?? 0))refuse("V01","patch cannot target frontmatter; use vmem_set_frontmatter or the frontmatter command",path);
156
- set(path, source.slice(0, first) + operation.newString + source.slice(first + operation.oldString.length));
152
+ const single = operation.oldString !== undefined || operation.newString !== undefined;
153
+ if (single === (operation.edits !== undefined)) refuse("V01", "patch takes either oldString/newString or edits, not both or neither; send one form", path);
154
+ const edits: unknown[] = single ? [{ oldString: operation.oldString, newString: operation.newString }] : Array.isArray(operation.edits) ? operation.edits : [];
155
+ if (edits.length < 1 || edits.length > 32) refuse("V09", "edits must list 1 to 32 replacements; split a larger change into several patches", path);
156
+ const frontmatterEnd = document(source, path).frontmatter?.length ?? 0;
157
+ // Every edit is located in the original text, so earlier edits cannot create or remove a later match.
158
+ const spans = edits.map((edit, index) => {
159
+ const at = single ? "" : `edits[${index}]: `;
160
+ if (!edit || typeof edit !== "object" || Array.isArray(edit) || Object.keys(edit).some(key => key !== "oldString" && key !== "newString")) refuse("V01", `${at}an edit is exactly {oldString, newString}`, path);
161
+ const { oldString, newString } = edit as Partial<PatchEdit>;
162
+ if (typeof oldString !== "string" || !oldString || typeof newString !== "string" || Buffer.byteLength(oldString) > 8192 || Buffer.byteLength(newString) > 8192) refuse("V09", `${at}patch strings must be bounded and oldString nonempty`, path);
163
+ const first = source.indexOf(oldString);
164
+ if (first < 0 || source.indexOf(oldString, first + 1) >= 0) refuse("V09", single ? "oldString must match exactly once" : `${at}oldString must match exactly once in the original note; re-read the note and widen the string`, path);
165
+ if (first < frontmatterEnd) refuse("V01", `${at}patch cannot target frontmatter; use vmem_set_frontmatter or the frontmatter command`, path);
166
+ return { start: first, end: first + oldString.length, text: newString, index };
167
+ }).sort((a, b) => a.start - b.start);
168
+ let after = "", cursor = 0;
169
+ for (const span of spans) {
170
+ if (span.start < cursor) refuse("V09", `edits[${span.index}]: oldString overlaps another edit; merge overlapping edits into one`, path);
171
+ after += source.slice(cursor, span.start) + span.text; cursor = span.end;
172
+ }
173
+ set(path, after + source.slice(cursor));
157
174
  break;
158
175
  }
159
176
  case "append": { const { path, source } = existing(operation.path); set(path, appendSection(source, operation.section, operation.markdown, path)); break; }
@@ -1,10 +1,12 @@
1
1
  import type { PiiSurface } from "./config.ts";
2
2
  import type { LogEvent, LogReceipt } from "./log-types.ts";
3
3
  import type { VaultSpec, VmemConfig } from "./config.ts";
4
+ export interface PatchEdit { oldString: string; newString: string }
4
5
  export type WriteOp =
5
6
  | { op: "check"; path: string; text: string }
6
7
  | { op: "create"; path: string; frontmatter: Record<string, unknown>; body?: string }
7
- | { op: "patch"; path: string; oldString: string; newString: string; expectedSha?: string }
8
+ /** One `oldString`/`newString` pair or `edits` (1..32 pairs), never both; edits apply all-or-nothing against the original text. */
9
+ | { op: "patch"; path: string; oldString?: string; newString?: string; edits?: PatchEdit[]; expectedSha?: string }
8
10
  | { op: "append"; path: string; section: string; markdown: string; expectedSha?: string }
9
11
  | { op: "frontmatter"; path: string; set: Record<string, unknown>; unset?: string[]; expectedSha?: string }
10
12
  | { op: "link"; from: string; to: string; relation: "supports" | "contradicts" | "extends" | "applies-to" | "context-for"; context?: string; bidirectional?: boolean }