@staix/vault-mem 0.3.1 → 0.3.3

package/src/mcp.ts

@@ -9,31 +9,54 @@ export interface McpServerOptions { tools: readonly McpTool[]; handlers: Record<
 const protocols = ["2025-06-18", "2025-03-26", "2024-11-05"];
 const plain = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
 
-/** Runtime validation for the small schema vocabulary the tools use. Unknown keywords never widen acceptance. */
-export function validArguments(value: unknown, raw: unknown): boolean {
+/** First schema failure only; paths and schema limits are reported, never argument values. */
+export function argumentError(value: unknown, raw: unknown, path = ""): string | undefined {
+  const at = path || "arguments", fail = (reason: string) => `${at}: ${reason}`;
+  if (!plain(raw)) return fail("invalid schema");
   const s = raw as Record<string, any>, type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
   const types: unknown[] = Array.isArray(s.type) ? s.type : [s.type];
-  if (!types.includes(type) && !(type === "number" && Number.isSafeInteger(value) && types.includes("integer"))) return false;
-  if (type === "number" && !types.includes("number") && !Number.isSafeInteger(value)) return false;
-  if (s.enum && !s.enum.includes(value)) return false;
-  if (typeof value === "string" && (value.length < (s.minLength ?? 0) || value.length > (s.maxLength ?? FRAME_BYTES) || value.includes("\0"))) return false;
-  if (typeof value === "number" && (!Number.isFinite(value) || value < (s.minimum ?? -Infinity) || value > (s.maximum ?? Infinity))) return false;
-  if (Array.isArray(value)) {
-    if (value.length < (s.minItems ?? 0) || value.length > (s.maxItems ?? 64) || !plain(s.items)) return false;
-    return value.every(item => validArguments(item, s.items));
+  if (!types.includes(type) && !(type === "number" && Number.isSafeInteger(value) && types.includes("integer"))) return fail(`expected ${types.join(" or ")}`);
+  if (type === "number" && !types.includes("number") && !Number.isSafeInteger(value)) return fail("expected safe integer");
+  if (s.enum && !s.enum.includes(value)) return fail("not an allowed value");
+  if (typeof value === "string") {
+    if (value.length < (s.minLength ?? 0)) return fail(`shorter than ${s.minLength}`);
+    if (value.length > (s.maxLength ?? FRAME_BYTES)) return fail(`longer than ${s.maxLength ?? FRAME_BYTES}`);
+    if (value.includes("\0")) return fail("NUL is not allowed");
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return fail("expected finite number");
+    if (value < (s.minimum ?? -Infinity)) return fail(`less than ${s.minimum}`);
+    if (value > (s.maximum ?? Infinity)) return fail(`greater than ${s.maximum}`);
   }
-  if (plain(value)) {
+  if (Array.isArray(value)) {
+    if (value.length < (s.minItems ?? 0)) return fail(`fewer than ${s.minItems} items`);
+    if (value.length > (s.maxItems ?? 64)) return fail(`more than ${s.maxItems ?? 64} items`);
+    if (!plain(s.items)) return fail("invalid item schema");
+    for (let i = 0; i < value.length; i++) {
+      const error = argumentError(value[i], s.items, `${path}[${i}]`);
+      if (error) return error;
+    }
+  } else if (plain(value)) {
     const keys = Object.keys(value);
-    if (keys.length < (s.minProperties ?? 0) || keys.length > (s.maxProperties ?? 64)) return false;
-    if ((s.required ?? []).some((key: string) => !Object.hasOwn(value, key))) return false;
+    if (keys.length < (s.minProperties ?? 0)) return fail(`fewer than ${s.minProperties} properties`);
+    if (keys.length > (s.maxProperties ?? 64)) return fail(`more than ${s.maxProperties ?? 64} properties`);
+    for (const key of s.required ?? []) if (!Object.hasOwn(value, key)) return `${path ? path + "." : ""}${key}: required`;
     for (const key of keys) {
-      if (["__proto__", "prototype", "constructor"].includes(key) || key.length > 200) return false;
-      if (Object.hasOwn(s.properties ?? {}, key)) { if (!validArguments(value[key], s.properties[key])) return false; }
-      else if (s.additionalProperties === false || !plain(s.additionalProperties) || !validArguments(value[key], s.additionalProperties)) return false;
+      if (key.length > 200) return fail("property name longer than 200");
+      const child = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? (path ? `${path}.${key}` : key) : `${path || "$"}[${JSON.stringify(key)}]`;
+      if (["__proto__", "prototype", "constructor"].includes(key)) return `${child}: forbidden property name`;
+      let schema;
+      if (Object.hasOwn(s.properties ?? {}, key)) schema = s.properties[key];
+      else if (s.additionalProperties === false || !plain(s.additionalProperties)) return `${path ? path + ": " : ""}unknown argument: ${key}`;
+      else schema = s.additionalProperties;
+      const error = argumentError(value[key], schema, child);
+      if (error) return error;
     }
-  } else if (type === "object") return false;
-  return true;
+  } else if (type === "object") return fail("expected plain object");
+  return undefined;
 }
+/** Boolean compatibility API for the same closed, bounded schema vocabulary. */
+export function validArguments(value: unknown, raw: unknown): boolean { return argumentError(value, raw) === undefined; }
 
 /** Serve until input ends. stdout carries protocol messages only; nothing else is written to `output`. */
 export async function serveMcp(options: McpServerOptions): Promise<void> {
@@ -70,7 +93,9 @@ export async function serveMcp(options: McpServerOptions): Promise<void> {
     if (!plain(params) || Object.keys(params).some(k => !["name", "arguments", "_meta"].includes(k)) || typeof params.name !== "string") { await error(id, -32602, "Invalid tool call"); return; }
     const definition = options.tools.find(t => t.name === params.name), args = params.arguments ?? {};
     const handler = definition && options.handlers[definition.name];
-    if (!definition || !handler || !validArguments(args, definition.inputSchema)) { await error(id, -32602, "Invalid tool name or arguments"); return; }
+    if (!definition || !handler) { await error(id, -32602, `unknown tool: ${params.name.slice(0, 200)}`); return; }
+    const invalid = argumentError(args, definition.inputSchema);
+    if (invalid) { await error(id, -32602, invalid); return; }
     let result: unknown;
     try {
       const text = JSON.stringify(await handler(args as Record<string, unknown>));

package/src/org-promote.ts

@@ -8,7 +8,7 @@ import { normalizeTarget, proseLines } from "./links.ts";
 import { loadRegistry } from "./registry.ts";
 import { VaultIndex } from "./vault-index.ts";
 import { applyWrite } from "./writer.ts";
-import { notePath } from "./write-operations.ts";
+import { notePath, replaceTopicsSection } from "./write-operations.ts";
 import { screenContent } from "./write-validation.ts";
 import { appendLog, logBinding } from "./vault-log.ts";
 import type { WriteIssue, WriteReceipt } from "./write-types.ts";
@@ -97,19 +97,6 @@ function screenDroppedLinks(home: string, source: VaultSpec, all: VaultSpec[], d
   // Counts and categories only: the linked names are exactly what must not be echoed.
   return [...found].map(([category, count]) => issue("SCREEN", `${category}: ${count} body link${count === 1 ? "" : "s"} point at notes that are never promoted; remove those links from the source note first`));
 }
-/** Replace the last prose `## Topics` section (never one inside a fence) with the given topics; append one if absent. */
-export function replaceTopicsSection(body: string, topics: string[]): string {
-  const prose = proseLines(body), raw = body.split("\n");
-  let start = -1;
-  for (let i = prose.length - 1; i >= 0; i--) if (/^ {0,3}##[ \t]+Topics[ \t]*#*[ \t]*$/.test(prose[i]!)) { start = i; break; }
-  const section = ["## Topics", "", ...topics.map(topic => `- ${topic}`), ""];
-  if (start < 0) return `${body.replace(/\n*$/, "")}\n\n${section.join("\n")}`;
-  // The section ends at the next prose heading of level 1 or 2.
-  let end = raw.length;
-  for (let i = start + 1; i < prose.length; i++) if (/^ {0,3}#{1,2}[ \t]/.test(prose[i]!)) { end = i; break; }
-  const tail = raw.slice(end);
-  return [...raw.slice(0, start), ...section, ...(tail.length ? tail : [])].join("\n").replace(/\n*$/, "\n");
-}
 /** Replace visible wiki links whose target does not resolve in the target vault with their plain text. */
 export function dropUnresolvedLinks(body: string, resolves: (target: string) => boolean): { body: string; dropped: string[] } {
   const prose = proseLines(body), raw = body.split("\n"), dropped: string[] = [];

package/src/registry.ts

@@ -1,8 +1,10 @@
 import { closeSync, constants, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { realPath, memoryGitArgv, memoryGitEnv } from "./platform.ts";
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
-import { CONFIG_FILE, MAX_CONFIG_BYTES, parseConfig, parsePii, parseVault, piiExtensions, readConfig, type VaultSpec, type VmemConfig } from "./config.ts";
+import { CONFIG_FILE, MAX_CONFIG_BYTES, parseConfig, parsePii, parseVault, parseSpec, piiExtensions, readConfig, type VaultSpec, type SpecSourceSpec, type VmemConfig } from "./config.ts";
 import { loosenedCells, piiPolicy, piiShorthand } from "./pii.ts";
 export const LOCK_FILE = "config.lock";
 const TEMP = /^\.config-[0-9a-f-]{36}\.tmp$/;
@@ -41,6 +43,7 @@ function mutate<T>(home: string, update: (config: VmemConfig) => T): T {
     const owner: LockOwner = { pid: process.pid, host: hostname(), created: new Date().toISOString() };
     writeFileSync(lockFd, JSON.stringify(owner) + "\n");
     const config = loadRegistry(home), result = update(config);
+    if (config.specs !== undefined) config.version = Math.max(config.version ?? 1, 2);
     parseConfig(config);
     const text = JSON.stringify(config, null, 2) + "\n";
     if (Buffer.byteLength(text) > MAX_CONFIG_BYTES) throw new Error(`${join(home, CONFIG_FILE)}: serialized config exceeds 64 KiB`);
@@ -148,7 +151,7 @@ export function addVault(home: string, value: unknown): VaultSpec {
   if (!isDir) throw new Error(`vault ${vault.id}: ${vault.path} must contain notes directory`);
   if (realpathSync(notes) !== notes) throw new Error(`vault ${vault.id}: ${notes} must not be a symlink`);
   return mutate(home, config => {
-    if (config.vaults.some(v => v.id === vault.id)) throw new Error(`vault ${vault.id}: id already registered`);
+    if ([...config.vaults, ...(config.specs ?? [])].some(v => v.id === vault.id)) throw new Error(`vault ${vault.id}: id already registered; use vmem vaults list and vmem specs list, then choose a unique id`);
     if (config.vaults.some(v => {
       if (v.path === vault.path) return true;
       try { return realpathSync(v.path) === vault.path; }
@@ -199,3 +202,61 @@ export function registryStatus(home: string) {
     } catch { return { ...base, healthy: false, issue: "vault path or notes directory unavailable or changed" }; }
   });
 }
+
+/** Inspect only local git metadata, with inherited repository overrides removed and bounded output/time. */
+function requireSpecRoot(path: string, env: NodeJS.ProcessEnv): void {
+  const argv = memoryGitArgv(["-C", path, "rev-parse", "--show-toplevel"]);
+  const result = spawnSync(argv[0]!, argv.slice(1), { env: memoryGitEnv({ ...env, GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" }, { repositoryIsolation: true }), encoding: "utf8", timeout: 5000, maxBuffer: 65536, stdio: ["ignore", "pipe", "pipe"] });
+  if (result.error) {
+    const code = (result.error as NodeJS.ErrnoException).code;
+    if (code === "ETIMEDOUT") throw new Error("spec source: git root check timed out after 5000 ms; retry and check for a locked repository or slow mount");
+    if (code === "ENOBUFS") throw new Error("spec source: git root check output exceeded 64 KiB; inspect git -C <path> rev-parse --show-toplevel and repair unexpected output before retrying");
+    throw new Error(`spec source: git could not run (${code ?? "spawn failure"}); install git or fix PATH, then retry the root check`);
+  }
+  if (result.status !== 0) {
+    const firstLine = result.stderr.split(/\r?\n/, 1)[0]?.split(path).join("<path>").slice(0, 240) || "no diagnostic";
+    throw new Error(`spec source: git refused the root check (exit ${result.status ?? "signal"}): ${firstLine}; inspect git -C <path> rev-parse --show-toplevel and repair the repository or ownership configuration`);
+  }
+  const root = result.stdout.replace(/\r?\n$/, "");
+  if (root !== path) throw new Error(`spec source: selected path is inside a work tree but not its root; register the reported root ${root} with vmem specs add <id> <absolute-path>`);
+}
+export function addSpec(home: string, value: unknown, env: NodeJS.ProcessEnv = process.env): SpecSourceSpec {
+  const spec = parseSpec(value);
+  try { spec.path = realPath(spec.path); }
+  catch { throw new Error(`spec source ${spec.id}: path is unavailable; restore the repository or pass its existing absolute root to vmem specs add`); }
+  requireSpecRoot(spec.path, env);
+  return mutate(home, config => {
+    if ([...config.vaults, ...(config.specs ?? [])].some(source => source.id === spec.id)) throw new Error(`spec source ${spec.id}: id already registered; use vmem specs list and vmem vaults list, then choose a unique id`);
+    if ((config.specs ?? []).some(source => {
+      if (source.path === spec.path) return true;
+      try { return realPath(source.path) === spec.path; }
+      catch (error) {
+        if (["ENOENT", "ENOTDIR", "EACCES", "ELOOP"].includes((error as NodeJS.ErrnoException).code ?? "")) return false;
+        throw error;
+      }
+    })) throw new Error(`spec source ${spec.id}: path already registered; use vmem specs list to select its existing id`);
+    (config.specs ??= []).push(spec);
+    return spec;
+  });
+}
+export function removeSpec(home: string, id: string, confirm = false): { applied: boolean; spec: SpecSourceSpec } {
+  const remove = (config: VmemConfig) => {
+    const spec = config.specs?.find(source => source.id === id);
+    if (!spec) throw new Error(`unknown spec source id ${id}; use vmem specs list to select a registered id`);
+    if (confirm) config.specs = config.specs!.filter(source => source.id !== id);
+    return { applied: confirm, spec };
+  };
+  return confirm ? mutate(home, remove) : remove(loadRegistry(home));
+}
+export function specStatus(home: string, env: NodeJS.ProcessEnv = process.env) {
+  return (loadRegistry(home).specs ?? []).map(spec => {
+    try {
+      if (realPath(spec.path) !== spec.path) throw new Error("spec source path changed; restore the canonical repository root or unregister it with vmem specs remove <id>");
+      requireSpecRoot(spec.path, env);
+      return { ...spec, healthy: true };
+    } catch (error) {
+      const cause = error instanceof Error ? error.message : "spec source path inspection failed";
+      return { ...spec, healthy: false, issue: `${cause}; restore a readable canonical root, or unregister it with vmem specs remove <id>` };
+    }
+  });
+}

package/src/spec-command-table.ts

@@ -0,0 +1,15 @@
+import { SPEC_EDGE_KINDS } from "./spec-graph.ts";
+
+const string = (maxLength: number, minLength = 1) => ({ type: "string", minLength, maxLength });
+const integer = (maximum: number, minimum = 0) => ({ type: "integer", minimum, maximum });
+const common = { source: string(64), worktree: string(4096) };
+const schema = (properties: Record<string, unknown>, required: string[] = []) => ({ type: "object", properties: { ...common, ...properties }, required, additionalProperties: false, maxProperties: 20 });
+/** Implemented read commands only; CLI flags and MCP definitions share these schemas. */
+export const SPEC_COMMANDS = [
+  { command: "get", name: "vmem_spec_get", usage: "spec get <id> [--source ID] [--worktree PATH] [--body] [--section TEXT] [--offset N] [--max-bytes 1..65536] [--json]", description: "Read spec metadata, resolved links, backlinks, children and freshness; body reads are optional and paged.", inputSchema: schema({ id: string(1024), body: { type: "boolean" }, section: string(1024), offset: integer(2097152), maxBytes: integer(65536, 1) }, ["id"]) },
+  { command: "graph", name: "vmem_spec_graph", usage: "spec graph <id> [--source ID] [--worktree PATH] [--direction subtree|ancestors|neighbors] [--edge KIND] [--depth 0..3] [--limit 1..500] [--json]", description: "Read a bounded spec graph slice without raw source content.", inputSchema: schema({ id: string(1024), direction: { type: "string", enum: ["subtree", "ancestors", "neighbors"] }, edge: { type: "string", enum: [...SPEC_EDGE_KINDS] }, depth: integer(3), limit: integer(500, 1) }, ["id"]) },
+  { command: "grep", name: "vmem_spec_grep", usage: "spec grep [query] [--source ID] [--worktree PATH] [--literal] [--type TYPE] [--status STATUS] [--tag TAG] [--parent ID] [--depends-on ID] [--covers-path FILE] [--offset 0..10000] [--limit 1..500] [--json]", description: "Search specs with FTS terms or literal substring, metadata/path-scope filters and continuation offsets.", inputSchema: schema({ query: string(1024, 0), literal: { type: "boolean" }, type: string(256), status: string(256), tag: string(1024), parent: string(1024), dependsOn: string(1024), coversPath: string(4096), offset: integer(10000), limit: integer(500, 1) }) },
+  { command: "validate", name: "vmem_spec_validate", usage: "spec validate [--source ID] [--worktree PATH] [--require-fresh] [--limit 1..500] [--json] | spec validate --repo PATH [--require-fresh] [--limit 1..500] [--json]", description: "Validate spec candidates and report bounded errors, warnings and computed freshness; requireFresh makes stale scopes fatal.", inputSchema: schema({ requireFresh: { type: "boolean" }, limit: integer(500, 1) }) },
+] as const;
+export type SpecCommand = typeof SPEC_COMMANDS[number]["command"];
+export const specCommandSchema = (command: SpecCommand) => SPEC_COMMANDS.find(item => item.command === command)!.inputSchema;

package/src/spec-commands.ts

@@ -0,0 +1,174 @@
+import { isDeepStrictEqual } from "node:util";
+import { argumentError } from "./mcp.ts";
+import { specCommandSchema, type SpecCommand } from "./spec-command-table.ts";
+import { loadRegistry } from "./registry.ts";
+import { h2Sections, headingMetadata } from "./vault-index.ts";
+import { SpecIndex, discoverSpecs, type SpecDocument, type SpecSnapshot, type SpecSearchResult } from "./spec-source.ts";
+import { buildSpecGraph, specReference, specSlice, type SpecEdgeKind } from "./spec-graph.ts";
+import { specFreshness, specsCoveringPath } from "./spec-freshness.ts";
+import { validateSpecs } from "./spec-validate.ts";
+
+const MAX_RESPONSE_BYTES = 240 * 1024, MAX_RELATIONS = 500, BUDGET_RESERVE = 512;
+const text = (value: unknown): string => typeof value === "string" ? value : "";
+const compare = (a: string, b: string) => a < b ? -1 : a > b ? 1 : 0;
+function bytes(value: unknown): number {
+  try { return Buffer.byteLength(JSON.stringify(value)); }
+  catch (error) { throw new Error("spec result: metadata cannot be serialized safely; remove cyclic or unsupported frontmatter values before retrying", { cause: error }); }
+}
+function fits(result: unknown): boolean { return bytes(result) + BUDGET_RESERVE <= MAX_RESPONSE_BYTES; }
+function checkBudget(result: unknown): void {
+  if (bytes(result) > MAX_RESPONSE_BYTES) throw new Error("spec result: required metadata/body exceeds 240 KiB; reduce maxBytes (--max-bytes) or oversized frontmatter before retrying");
+}
+function rows<T>(result: Record<string, unknown>, key: string, values: readonly T[], limit = MAX_RELATIONS): T[] {
+  const out: T[] = []; result[key] = out;
+  let used = bytes(result) + BUDGET_RESERVE;
+  for (const value of values) {
+    if (out.length >= limit) break;
+    const size = bytes(value) + (out.length ? 1 : 0);
+    if (used + size > MAX_RESPONSE_BYTES) break;
+    out.push(value); used += size;
+  }
+  if (out.length < values.length) result.truncated = true;
+  return out;
+}
+function clip(value: string, maximum: number): string {
+  const data = Buffer.from(value); if (data.length <= maximum) return value;
+  let end = maximum; while (end > 0 && (data[end]! & 0xc0) === 0x80) end--;
+  return data.subarray(0, end).toString("utf8");
+}
+function bodyPage(document: SpecDocument, args: Record<string, unknown>): Record<string, unknown> {
+  const section = typeof args.section === "string" ? args.section : undefined, offset = (args.offset as number | undefined) ?? 0, maximum = (args.maxBytes as number | undefined) ?? 16384;
+  if (section !== undefined && (!section.trim() || /[\r\n]/.test(section) || Buffer.byteLength(section) > 1024)) throw new Error("spec get: section must be one exact H2 name within 1024 UTF-8 bytes; choose a heading from the spec body");
+  let body = document.body;
+  const all = h2Sections(body);
+  if (section !== undefined) {
+    const selected = all.filter(item => item.name === section);
+    if (selected.length !== 1) throw new Error(selected.length ? "spec get: section is ambiguous; rename duplicate H2 headings before requesting this section" : "spec get: section was not found; select an exact H2 heading from the spec body");
+    body = body.slice(selected[0]!.start, selected[0]!.end);
+  }
+  const data = Buffer.from(body);
+  if (offset > data.length) throw new Error("spec get: offset exceeds the selected body/section; restart at offset 0 or use the last returned nextOffset");
+  if (offset < data.length && (data[offset]! & 0xc0) === 0x80) throw new Error("spec get: offset is not a UTF-8 boundary; use a nextOffset returned by the previous page");
+  let end = Math.min(offset + maximum, data.length);
+  while (end > offset && end < data.length && (data[end]! & 0xc0) === 0x80) end--;
+  if (end === offset && offset < data.length) throw new Error("spec get: maxBytes cannot fit the next UTF-8 character; increase maxBytes (--max-bytes) before retrying");
+  const truncated = end < data.length;
+  return { body: data.subarray(offset, end).toString("utf8"), bodyTruncated: truncated,
+    ...(truncated ? { nextOffset: end, ...headingMetadata(all) } : {}),
+    ...(section === undefined ? {} : { section }), ...(args.offset === undefined ? {} : { offset }) };
+}
+function metadataMatch(document: SpecDocument, args: Record<string, unknown>): boolean {
+  const data = document.frontmatter;
+  if (args.type !== undefined && data.type !== args.type || args.status !== undefined && data.status !== args.status) return false;
+  if (args.tag !== undefined && !(Array.isArray(data.tags) ? data.tags : [data.tags]).some(tag => tag === args.tag)) return false;
+  if (args.parent !== undefined && specReference(data.parent) !== specReference(args.parent)) return false;
+  if (args.dependsOn !== undefined && (!Array.isArray(data["depends-on"]) || !data["depends-on"].some(value => specReference(value) === specReference(args.dependsOn)))) return false;
+  return true;
+}
+function grep(index: SpecIndex, snapshot: SpecSnapshot, args: Record<string, unknown>, env: NodeJS.ProcessEnv, source: string): Record<string, unknown> {
+  const rawQuery = text(args.query), query = args.literal === true ? rawQuery : rawQuery.trim(), offset = (args.offset as number | undefined) ?? 0, limit = (args.limit as number | undefined) ?? 50;
+  if (Buffer.byteLength(rawQuery) > 1024) throw new Error("spec grep: query exceeds 1024 UTF-8 bytes; shorten the query before retrying");
+  let documents = snapshot.specs.filter(document => metadataMatch(document, args));
+  if (typeof args.coversPath === "string") {
+    const covered = new Set(specsCoveringPath({ ...snapshot, specs: documents }, args.coversPath, { env }).map(document => document.path));
+    documents = documents.filter(document => covered.has(document.path));
+  }
+  const byPath = new Map(documents.map(document => [document.path, document]));
+  const selected: Record<string, unknown>[] = [];
+  const hit = (document: SpecDocument, indexed?: SpecSearchResult): Record<string, unknown> => {
+    let start = query ? Math.max(0, document.source.indexOf(query) - 80) : 0;
+    // The context window is measured in UTF-16 units; do not start on an emoji's low surrogate.
+    if (start > 0 && (document.source.codePointAt(start - 1) ?? 0) > 0xffff) start--;
+    return { id: document.id, path: document.path, title: clip(text(document.frontmatter.title) || document.id, 512), type: text(document.frontmatter.type),
+      ...(typeof document.frontmatter.status === "string" ? { status: document.frontmatter.status } : {}),
+      snippet: indexed?.snippet ?? clip(document.source.slice(start), 1024), ...(indexed ? { score: indexed.score } : {}) };
+  };
+  let matched = 0;
+  if (!query || args.literal === true) {
+    for (const document of [...documents].sort((a, b) => compare(a.path.normalize("NFC"), b.path.normalize("NFC")) || compare(a.path, b.path))) {
+      if (query && !document.source.includes(query)) continue;
+      if (matched++ < offset) continue;
+      selected.push(hit(document)); if (selected.length > limit) break;
+    }
+  } else {
+    // A peer may rescan the cache while this request runs. Materialize one bounded
+    // statement result so metadata filtering and continuation use a stable hit set.
+    for (const item of index.searchAll(query)) {
+      const document = byPath.get(item.path); if (!document) continue;
+      if (matched++ < offset) continue;
+      selected.push(hit(document, item)); if (selected.length > limit) break;
+    }
+  }
+  const result: Record<string, unknown> = { source, worktree: snapshot.root, hits: [], offset, truncated: false };
+  const kept = rows(result, "hits", selected.slice(0, limit), limit);
+  if (selected.length > kept.length) {
+    if (!kept.length) throw new Error("spec grep: matching result metadata exceeds the response budget; narrow metadata filters or shorten oversized source metadata before retrying");
+    result.truncated = true; result.nextOffset = offset + kept.length;
+  }
+  return result;
+}
+
+/** Shared read-only provider for CLI and MCP; caches may be derived outside all registered sources. */
+export function executeSpecCommand(home: string, command: SpecCommand, args: Record<string, unknown>, env: NodeJS.ProcessEnv = process.env): unknown {
+  if (!["get", "graph", "grep", "validate"].includes(command)) throw new Error("spec provider: unknown command; choose get, graph, grep or validate");
+  const invalid = argumentError(args, specCommandSchema(command));
+  if (invalid) throw new Error(`spec ${command}: ${invalid}; use vmem spec ${command} --help to correct the arguments`);
+  if (command === "grep") for (const field of ["parent", "dependsOn"] as const) {
+    if (args[field] !== undefined && specReference(args[field]) === undefined) throw new Error(`spec grep: ${field} filter resolves to no id; pass an id or [[id]]`);
+  }
+  const config = loadRegistry(home), sources = config.specs ?? [];
+  const source = args.source === undefined ? sources[0] : sources.find(item => item.id === args.source);
+  if (!source) throw new Error(sources.length ? "spec source is not registered; use vmem specs list and pass source (--source) with a registered id" : "no spec sources are registered; run vmem specs add <id> <absolute-repository-root> first");
+  const currentRegistry = () => {
+    let current;
+    try { current = loadRegistry(home); }
+    catch (error) { throw new Error("spec registry became unreadable during the request; run vmem doctor to diagnose the registry, repair it and retry the read", { cause: error }); }
+    if (!isDeepStrictEqual(current.specs?.find(item => item.id === source.id), source) || args.source === undefined && current.specs?.[0]?.id !== source.id) throw new Error("spec registry changed during the request; use vmem specs list to select the current source (--source) and retry the read");
+  };
+  let snapshot: SpecSnapshot, result: Record<string, unknown>;
+  if (command === "validate") {
+    snapshot = discoverSpecs(source, { env, ...(typeof args.worktree === "string" ? { worktree: args.worktree } : {}) });
+    result = { ...validateSpecs(snapshot, { env, requireFresh: args.requireFresh === true, ...(typeof args.limit === "number" ? { limit: args.limit } : {}) }) };
+  } else {
+    const index = new SpecIndex(home, source, { env, ...(typeof args.worktree === "string" ? { worktree: args.worktree } : {}), protectedRoots: [...config.vaults, ...sources].map(item => item.path) });
+    try {
+      index.scan(); snapshot = index.snapshot();
+      if (command === "grep") result = grep(index, snapshot, args, env, source.id);
+      else {
+        const graph = buildSpecGraph(snapshot), id = text(args.id), document = snapshot.specs.find(item => item.id === id);
+        if (!document) throw new Error("spec id was not found; pass an id from vmem spec grep with the matching source (--source)");
+        if (command === "graph") {
+          const slice = specSlice(graph, id, { ...(typeof args.direction === "string" ? { direction: args.direction as "subtree" | "ancestors" | "neighbors" } : {}), ...(typeof args.edge === "string" ? { edge: args.edge as SpecEdgeKind } : {}), ...(typeof args.depth === "number" ? { depth: args.depth } : {}), ...(typeof args.limit === "number" ? { limit: args.limit } : {}) });
+          result = { source: source.id, worktree: snapshot.root, nodes: [], edges: [], truncated: slice.truncated };
+          const root = slice.nodes.find(node => node.id === id)!;
+          if (!fits({ ...result, nodes: [root] })) throw new Error("spec graph: root metadata exceeds the response budget; shorten oversized spec metadata before requesting its graph");
+          const ordered = [root, ...slice.nodes.filter(node => node.id !== id)];
+          const nodes = rows(result, "nodes", ordered), ids = new Set(nodes.map(node => node.id));
+          rows(result, "edges", slice.edges.filter(edge => ids.has(edge.source) && ids.has(edge.target)));
+        } else {
+          const freshness = specFreshness({ ...snapshot, specs: [document], candidates: [document] }, { env });
+          const links = [], backlinks = [], childIds = new Set<string>();
+          for (const edge of graph.edges) {
+            if (edge.source === id) links.push(edge);
+            if (edge.target === id) {
+              backlinks.push(edge);
+              if (edge.kind === "parent") childIds.add(edge.source);
+            }
+          }
+          const children = graph.nodes.filter(node => childIds.has(node.id));
+          result = { source: source.id, worktree: snapshot.root, id, path: document.path, sha256: document.hash, frontmatter: document.frontmatter, links: [], backlinks: [], children: [], freshness: freshness.items[0] ?? null, freshnessIssues: freshness.issues,
+            truncated: false, totals: { links: links.length, backlinks: backlinks.length, children: children.length } };
+          if (args.body === true || args.maxBytes !== undefined || args.section !== undefined || args.offset !== undefined) {
+            Object.assign(result, bodyPage(document, args)); if (result.bodyTruncated === true) result.truncated = true;
+          }
+          if (!fits(result)) throw new Error("spec get: frontmatter/body metadata exceeds the response budget; reduce maxBytes (--max-bytes) or shorten oversized frontmatter before retrying");
+          rows(result, "links", links); rows(result, "backlinks", backlinks); rows(result, "children", children);
+        }
+      }
+    } finally { index.close(); }
+  }
+  currentRegistry();
+  result = { source: source.id, worktree: snapshot.root, ...result };
+  checkBudget(result);
+  return result;
+}

package/src/spec-freshness.ts

@@ -0,0 +1,163 @@
+import { isAbsolute, posix, win32 } from "node:path";
+import { specGit } from "./spec-git.ts";
+import type { SpecCandidate, SpecDocument, SpecSnapshot } from "./spec-source.ts";
+import type { SpecValidationIssue } from "./spec-validate.ts";
+
+export interface SpecFreshnessEntry { path: string; id?: string; state: "fresh" | "stale"; commits: number; dirty: boolean }
+export interface SpecFreshnessReport { items: SpecFreshnessEntry[]; issues: SpecValidationIssue[] }
+export interface SpecFreshnessOptions { env?: NodeJS.ProcessEnv }
+const PATH_OUTPUT_BYTES = 8 * 1024 * 1024;
+const compare = (a: string, b: string) => a < b ? -1 : a > b ? 1 : 0;
+const ordered = <T extends { path: string }>(items: readonly T[]): T[] => [...items].sort((a, b) => compare(a.path.normalize("NFC"), b.path.normalize("NFC")) || compare(a.path, b.path));
+const idOf = (candidate: SpecCandidate): { id?: string } => typeof candidate.frontmatter.id === "string" && candidate.frontmatter.id.trim().length > 0 ? { id: candidate.frontmatter.id } : {};
+function issue(candidate: SpecCandidate, code: string, field: string, message: string): SpecValidationIssue {
+  return { code, severity: "error", path: candidate.path, ...idOf(candidate), field, message };
+}
+function pathsShape(value: unknown): value is string[] {
+  return Array.isArray(value) && value.length > 0 && value.every(item => typeof item === "string" && item.length > 0);
+}
+/** Strip only Git's magic header for the relative/no-parent check; Git interprets the original pathspec. */
+function pathspecBody(value: string): string | undefined {
+  if (value.startsWith(":(")) {
+    const end = value.indexOf(")");
+    return end < 0 ? undefined : value.slice(end + 1);
+  }
+  return value.startsWith(":") ? value.replace(/^:[!^/]*:?/, "") : value;
+}
+function relativePathspec(value: string): boolean {
+  const body = pathspecBody(value);
+  return body !== undefined && !value.includes("\0") && !isAbsolute(body) && !win32.isAbsolute(body) && !body.split(/[\\/]/).includes("..");
+}
+function hasPaths(bytes: Buffer): boolean {
+  if (bytes.length && bytes[bytes.length - 1] !== 0) throw new Error("spec freshness: Git returned incomplete NUL-delimited paths; retry on a stable repository");
+  return bytes.length > 0;
+}
+function pathRecords(bytes: Buffer): Buffer[] {
+  hasPaths(bytes);
+  const paths: Buffer[] = [];
+  for (let start = 0; start < bytes.length;) {
+    const end = bytes.indexOf(0, start);
+    if (end > start) paths.push(bytes.subarray(start, end));
+    start = end + 1;
+  }
+  return paths;
+}
+type ScopeMatch = { files: Buffer } | { invalid: "syntax" | "unmatched"; diagnostic?: string };
+function trackedScope(root: string, paths: string[], options: SpecFreshnessOptions): ScopeMatch {
+  // This conflict is known before Git quotes a possibly long pattern into a truncated diagnostic.
+  if (paths.some(path => {
+    if (!path.startsWith(":(")) return false;
+    const magic = path.slice(2, path.indexOf(")")).split(",");
+    return magic.includes("literal") && magic.includes("glob");
+  })) return { invalid: "syntax" };
+  const result = specGit(root, ["ls-files", "--cached", "-z", "--error-unmatch", "--", ...paths], { env: options.env, maxBuffer: PATH_OUTPUT_BYTES, allowedExitCodes: [0, 1, 128] });
+  if (result.status === 128) {
+    // A library caller may have a stale snapshot: distinguish a broken index from bad scope syntax.
+    specGit(root, ["ls-files", "--cached", "-z"], { env: options.env, maxBuffer: PATH_OUTPUT_BYTES });
+    const diagnostic = result.stderr.toString("utf8").split(/\r?\n/, 1)[0]?.split(root).join("<path>").slice(0, 240) || "no diagnostic";
+    return { invalid: "syntax", diagnostic };
+  }
+  if (result.status !== 0 || !hasPaths(result.stdout)) return { invalid: "unmatched" };
+  return { files: result.stdout };
+}
+function fullHash(bytes: Buffer): string {
+  const value = bytes.toString("utf8").replace(/\n$/, "");
+  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value)) throw new Error("spec freshness: Git returned an invalid full commit identity; inspect git rev-parse HEAD and repair the repository before retrying");
+  return value;
+}
+function candidatePaths(candidate: SpecCandidate, issues: SpecValidationIssue[]): string[] | undefined {
+  const value = candidate.frontmatter.paths;
+  if (value === undefined) return undefined;
+  if (!pathsShape(value)) {
+    issues.push(issue(candidate, "wrong_shape", "paths", "paths must be a nonempty list of nonempty strings; write repository-relative Git pathspecs as a YAML list"));
+    return undefined;
+  }
+  if (!value.every(relativePathspec)) {
+    issues.push(issue(candidate, "invalid_paths", "paths", "paths must use well-formed relative Git pathspecs without parent traversal or NUL; correct magic syntax or replace absolute/parent-relative entries with in-repository scopes"));
+    return undefined;
+  }
+  return value;
+}
+
+/** Pure metadata checks remain available when callers intentionally disable native Git inspection. */
+export function specMetadataIssues(candidate: SpecCandidate): SpecValidationIssue[] {
+  const issues: SpecValidationIssue[] = [];
+  candidatePaths(candidate, issues);
+  const stamp = candidate.frontmatter["verified-against"];
+  if (stamp !== undefined && (typeof stamp !== "string" || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(stamp))) issues.push(issue(candidate, "invalid_verified_against", "verified-against", "verified-against must be a full commit SHA; set it to the full git rev-parse HEAD result after reviewing the spec"));
+  return issues;
+}
+
+/** Computed freshness only: malformed metadata is reported, while Git operational failures propagate. */
+export function specFreshness(snapshot: SpecSnapshot, options: SpecFreshnessOptions = {}): SpecFreshnessReport {
+  const items: SpecFreshnessEntry[] = [], issues: SpecValidationIssue[] = [];
+  let loadedHead = false, head: string | undefined;
+  const stampChecks = new Map<string, string | undefined>();
+  const headCommit = () => {
+    if (!loadedHead) {
+      const result = specGit(snapshot.root, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], { env: options.env, allowedExitCodes: [0, 1] });
+      head = result.status === 0 ? fullHash(result.stdout) : undefined;
+      loadedHead = true;
+    }
+    return head;
+  };
+  const checkStamp = (stamp: string): string | undefined => {
+    if (stampChecks.has(stamp)) return stampChecks.get(stamp);
+    const current = headCommit();
+    let failure: string | undefined;
+    const commit = specGit(snapshot.root, ["rev-parse", "--verify", "--quiet", "--end-of-options", `${stamp}^{commit}`], { env: options.env, allowedExitCodes: [0, 1] });
+    if (commit.status !== 0 || fullHash(commit.stdout) !== stamp.toLowerCase()) failure = "verified-against does not name a commit in this repository; choose a full commit SHA from git log after reviewing the spec";
+    else if (current === undefined) failure = "verified-against cannot be checked without a HEAD commit; commit the tracked source and review it before recording a verification stamp";
+    else if (specGit(snapshot.root, ["merge-base", "--is-ancestor", stamp, current], { env: options.env, allowedExitCodes: [0, 1] }).status !== 0) failure = "verified-against is not an ancestor of HEAD; review the spec against a reachable commit and update the full verification SHA";
+    stampChecks.set(stamp, failure);
+    return failure;
+  };
+  for (const candidate of ordered(snapshot.candidates ?? snapshot.specs)) {
+    const paths = candidatePaths(candidate, issues);
+    let validPaths: string[] | undefined;
+    if (paths !== undefined) {
+      const scope = trackedScope(snapshot.root, paths, options);
+      if ("invalid" in scope) issues.push(issue(candidate, "invalid_paths", "paths", scope.invalid === "syntax"
+        ? `paths contain invalid Git pathspec syntax${scope.diagnostic ? ` (${scope.diagnostic})` : ""}; correct the pathspec magic or use a repository-relative tracked path from git ls-files`
+        : "one or more paths match no tracked files, or exclusions leave the scope empty; choose matching pathspecs from git ls-files and correct the paths list"));
+      else validPaths = paths;
+    }
+    const stamp = candidate.frontmatter["verified-against"];
+    if (stamp === undefined) continue;
+    if (typeof stamp !== "string" || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(stamp)) {
+      issues.push(issue(candidate, "invalid_verified_against", "verified-against", "verified-against must be a full commit SHA; set it to the full git rev-parse HEAD result after reviewing the spec"));
+      continue;
+    }
+    const failure = checkStamp(stamp);
+    if (failure) { issues.push(issue(candidate, "invalid_verified_against", "verified-against", failure)); continue; }
+    if (validPaths === undefined) continue;
+    const count = specGit(snapshot.root, ["rev-list", "--count", "--full-history", `${stamp}..${head!}`, "--", ...validPaths], { env: options.env }).stdout.toString("utf8").trim();
+    if (!/^\d+$/.test(count) || !Number.isSafeInteger(Number(count))) throw new Error("spec freshness: Git returned an invalid source commit count; inspect the scoped history before retrying");
+    const trackedDirty = specGit(snapshot.root, ["diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--name-only", "-z", head!, "--", ...validPaths], { env: options.env, maxBuffer: PATH_OUTPUT_BYTES }).stdout;
+    const stagedDirty = specGit(snapshot.root, ["diff", "--cached", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--name-only", "-z", head!, "--", ...validPaths], { env: options.env, maxBuffer: PATH_OUTPUT_BYTES }).stdout;
+    const untrackedDirty = specGit(snapshot.root, ["ls-files", "--others", "--exclude-standard", "-z", "--", ...validPaths], { env: options.env, maxBuffer: PATH_OUTPUT_BYTES }).stdout;
+    const changedTracked = hasPaths(trackedDirty), changedStaged = hasPaths(stagedDirty), changedUntracked = hasPaths(untrackedDirty);
+    const dirty = changedTracked || changedStaged || changedUntracked, commits = Number(count);
+    items.push({ path: candidate.path, ...idOf(candidate), state: commits > 0 || dirty ? "stale" : "fresh", commits, dirty });
+  }
+  return { items, issues };
+}
+
+/** Match tracked files through Git's own pathspec engine; invalid metadata has no invented ownership. */
+export function specsCoveringPath(snapshot: SpecSnapshot, relativeFile: string, options: SpecFreshnessOptions = {}): SpecDocument[] {
+  if (typeof relativeFile !== "string" || !relativeFile || relativeFile.includes("\0") || isAbsolute(relativeFile) || win32.isAbsolute(relativeFile) || relativeFile.split(/[\\/]/).includes("..")) throw new Error("spec coversPath: expected a tracked repository-relative filename without parent traversal or NUL; pass a file listed by git ls-files");
+  const file = posix.normalize(relativeFile);
+  if (file === ".") return [];
+  const requested = specGit(snapshot.root, ["ls-files", "--cached", "-z", "--error-unmatch", "--", `:(literal)${file}`], { env: options.env, maxBuffer: PATH_OUTPUT_BYTES, allowedExitCodes: [0, 1] });
+  if (requested.status !== 0) return [];
+  // A literal directory pathspec also lists descendants; coversPath accepts a file, not a directory.
+  const spelling = file.normalize("NFC").toLowerCase();
+  const tracked = pathRecords(requested.stdout).filter(path => path.toString("utf8").normalize("NFC").toLowerCase() === spelling);
+  if (!tracked.length) return [];
+  return ordered(snapshot.specs).filter(document => {
+    const paths = document.frontmatter.paths;
+    if (!pathsShape(paths) || !paths.every(relativePathspec)) return false;
+    const scope = trackedScope(snapshot.root, paths, options);
+    return "files" in scope && pathRecords(scope.files).some(path => tracked.some(file => file.equals(path)));
+  });
+}

package/src/spec-git.ts

@@ -0,0 +1,33 @@
+import { spawnSync } from "node:child_process";
+import { memoryGitArgv, memoryGitEnv } from "./platform.ts";
+
+export interface SpecGitOptions {
+  env?: NodeJS.ProcessEnv;
+  maxBuffer?: number;
+  allowedExitCodes?: readonly number[];
+  discovery?: boolean;
+}
+export interface SpecGitResult { status: number; stdout: Buffer; stderr: Buffer }
+/** Internal bounded Git inspection, shared by discovery and validation; callers build readonly argv. */
+export function specGit(root: string, args: string[], options: SpecGitOptions = {}): SpecGitResult {
+  const argv = memoryGitArgv(["-C", root, ...args]), maxBuffer = options.maxBuffer ?? 65536;
+  const env = memoryGitEnv({ ...(options.env ?? process.env), GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" }, { repositoryIsolation: true });
+  for (const key of ["GIT_LITERAL_PATHSPECS", "GIT_GLOB_PATHSPECS", "GIT_NOGLOB_PATHSPECS", "GIT_ICASE_PATHSPECS"]) delete env[key];
+  const result = spawnSync(argv[0]!, argv.slice(1), { env, timeout: 10000, maxBuffer, stdio: ["ignore", "pipe", "pipe"] });
+  if (result.error) {
+    const code = (result.error as NodeJS.ErrnoException).code;
+    if (code === "ETIMEDOUT") throw new Error("spec source: git inspection timed out after 10000 ms; retry and check for a locked repository or slow mount", { cause: result.error });
+    if (code === "ENOBUFS") {
+      const advice = options.discovery ? "ignore large or vendored Markdown via .gitignore and untrack already-tracked excluded files with git rm --cached before retrying" : "make SPEC.md paths more specific, or inspect the failed Git command if its output is unexpected, before retrying";
+      throw new Error(`spec source: git output exceeded ${maxBuffer} bytes; ${advice}`, { cause: result.error });
+    }
+    if (code === "E2BIG") throw new Error("spec source: git arguments exceed the platform limit; shorten the paths list before retrying", { cause: result.error });
+    throw new Error(`spec source: git could not run (${code ?? "spawn failure"}); install git or fix PATH before retrying`, { cause: result.error });
+  }
+  const status = result.status;
+  if (status === null || !(options.allowedExitCodes ?? [0]).includes(status)) {
+    const first = result.stderr.toString("utf8").split(/\r?\n/, 1)[0]?.split(root).join("<path>").slice(0, 240) || "no diagnostic";
+    throw new Error(`spec source: git refused inspection (exit ${status ?? "signal"}): ${first}; inspect git -C <path> rev-parse --show-toplevel and repair the repository or ownership configuration`);
+  }
+  return { status, stdout: result.stdout, stderr: result.stderr };
+}