@staix/vault-mem 0.3.0 → 0.3.2

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-graph.ts

@@ -0,0 +1,117 @@
+import { extractLinks } from "./links.ts";
+import type { SpecDiagnostic, SpecDocument, SpecSnapshot } from "./spec-source.ts";
+
+export const SPEC_EDGE_KINDS = ["parent", "depends-on", "references", "implements", "superseded-by", "body_link"] as const;
+/** Pure transforms keep the discovery ceiling and bound resolved plus unresolved edges together. */
+export const MAX_SPEC_INPUTS = 10000, MAX_SPEC_EDGES = 100000;
+export type SpecEdgeKind = typeof SPEC_EDGE_KINDS[number];
+export interface SpecNode { id: string; path: string; title: string; type: string; status?: string }
+export interface SpecEdge { source: string; target: string; kind: SpecEdgeKind }
+export interface SpecGraph {
+  nodes: SpecNode[];
+  edges: SpecEdge[];
+  unresolved: SpecEdge[];
+  diagnostics: SpecDiagnostic[];
+}
+export interface SpecSliceOptions {
+  direction?: "subtree" | "ancestors" | "neighbors";
+  depth?: number;
+  limit?: number;
+  edge?: SpecEdgeKind;
+}
+export interface SpecSlice { nodes: SpecNode[]; edges: SpecEdge[]; truncated: boolean }
+
+const compare = (a: string, b: string): number => a < b ? -1 : a > b ? 1 : 0;
+const pathOrder = (a: SpecDocument, b: SpecDocument): number => compare(a.path.normalize("NFC"), b.path.normalize("NFC")) || compare(a.path, b.path) || compare(a.id, b.id);
+const edgeOrder = (a: SpecEdge, b: SpecEdge): number => compare(a.source, b.source) || SPEC_EDGE_KINDS.indexOf(a.kind) - SPEC_EDGE_KINDS.indexOf(b.kind) || compare(a.target, b.target);
+function reference(value: unknown): string | undefined {
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  const text = value.trim(), wiki = /^\[\[([^\]|#]+)\]\]$/.exec(text);
+  return wiki ? wiki[1]!.trim() : text;
+}
+
+/** Build only the read graph: unknown types/statuses remain visible for the later validation pass. */
+export function buildSpecGraph(snapshot: SpecSnapshot): SpecGraph {
+  if (snapshot.specs.length > MAX_SPEC_INPUTS) throw new Error(`spec graph: more than ${MAX_SPEC_INPUTS} input specs; pass a smaller SpecSnapshot before building the graph`);
+  const documents = new Map<string, SpecDocument>(), diagnostics = [...snapshot.diagnostics];
+  for (const document of [...snapshot.specs].sort(pathOrder)) {
+    const first = documents.get(document.id);
+    if (first) {
+      if (!diagnostics.some(item => item.code === "duplicate_id" && item.path === document.path && item.id === document.id)) diagnostics.push({
+        code: "duplicate_id", path: document.path, id: document.id, firstPath: first.path,
+        message: "duplicate spec id; give each spec a unique frontmatter id and rebuild the graph",
+      });
+      continue;
+    }
+    documents.set(document.id, document);
+  }
+  const nodes = [...documents.values()].map(document => ({
+    id: document.id, path: document.path,
+    title: typeof document.frontmatter.title === "string" ? document.frontmatter.title : document.id,
+    type: typeof document.frontmatter.type === "string" ? document.frontmatter.type : "",
+    ...(typeof document.frontmatter.status === "string" ? { status: document.frontmatter.status } : {}),
+  })).sort((a, b) => compare(a.id, b.id));
+  const edges: SpecEdge[] = [], unresolved: SpecEdge[] = [];
+  const seenEdges = new Map<string, Map<SpecEdgeKind, Set<string>>>();
+  const add = (source: string, value: unknown, kind: SpecEdgeKind) => {
+    const target = reference(value);
+    if (!target) return;
+    let kinds = seenEdges.get(source);
+    if (!kinds) seenEdges.set(source, kinds = new Map());
+    let targets = kinds.get(kind);
+    if (!targets) kinds.set(kind, targets = new Set());
+    if (targets.has(target)) return;
+    if (edges.length + unresolved.length >= MAX_SPEC_EDGES) throw new Error(`spec graph: more than ${MAX_SPEC_EDGES} unique edges; reduce link lists or pass a smaller SpecSnapshot before rebuilding`);
+    targets.add(target);
+    const collection = documents.has(target) ? edges : unresolved;
+    collection.push({ source, target, kind });
+  };
+  for (const document of documents.values()) {
+    for (const kind of ["parent", "superseded-by"] as const) add(document.id, document.frontmatter[kind], kind);
+    for (const kind of ["depends-on", "references", "implements"] as const) {
+      const values = document.frontmatter[kind];
+      if (Array.isArray(values)) for (const value of values) add(document.id, value, kind);
+    }
+    for (const link of extractLinks(document.body)) add(document.id, link.target, "body_link");
+  }
+  diagnostics.sort((a, b) => compare(a.path.normalize("NFC"), b.path.normalize("NFC")) || compare(a.path, b.path) || compare(a.code, b.code));
+  return { nodes, edges: edges.sort(edgeOrder), unresolved: unresolved.sort(edgeOrder), diagnostics };
+}
+
+/** A deterministic BFS; parent edges point child -> parent, while subtree traversal reverses them. */
+export function specSlice(graph: SpecGraph, id: string, options: SpecSliceOptions = {}): SpecSlice {
+  const direction = options.direction ?? "subtree", depth = options.depth ?? 1, limit = options.limit ?? 50;
+  if (!["subtree", "ancestors", "neighbors"].includes(direction)) throw new Error("spec slice: invalid direction; choose subtree, ancestors or neighbors");
+  if (!Number.isInteger(depth) || depth < 0 || depth > 3) throw new Error("spec slice: depth must be an integer from 0 to 3; pass a smaller depth");
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw new Error("spec slice: limit must be an integer from 1 to 500; pass a valid node limit");
+  if (options.edge !== undefined && !SPEC_EDGE_KINDS.includes(options.edge)) throw new Error("spec slice: unknown edge kind; choose a kind from SPEC_EDGE_KINDS");
+  const nodes = new Map(graph.nodes.map(node => [node.id, node]));
+  if (typeof id !== "string" || !nodes.has(id)) throw new Error("spec slice: unknown spec id; select an id from buildSpecGraph(...).nodes");
+  const edge = options.edge ?? (direction === "neighbors" ? undefined : "parent");
+  const edges = graph.edges.filter(item => (edge === undefined || item.kind === edge) && nodes.has(item.source) && nodes.has(item.target));
+  const adjacency = new Map<string, Set<string>>();
+  const add = (from: string, to: string) => {
+    let neighbors = adjacency.get(from);
+    if (!neighbors) adjacency.set(from, neighbors = new Set());
+    neighbors.add(to);
+  };
+  for (const item of edges) {
+    if (direction === "ancestors" || direction === "neighbors") add(item.source, item.target);
+    if (direction === "subtree" || direction === "neighbors") add(item.target, item.source);
+  }
+  const selected = new Set([id]), queue: { id: string; depth: number }[] = [{ id, depth: 0 }];
+  for (let cursor = 0; cursor < queue.length; cursor++) {
+    const current = queue[cursor]!;
+    for (const neighbor of [...(adjacency.get(current.id) ?? [])].sort(compare)) {
+      if (selected.has(neighbor)) continue;
+      if (current.depth >= depth || selected.size >= limit) continue;
+      selected.add(neighbor); queue.push({ id: neighbor, depth: current.depth + 1 });
+    }
+  }
+  const truncated = [...selected].some(node => [...(adjacency.get(node) ?? [])].some(neighbor => !selected.has(neighbor)));
+  return {
+    nodes: graph.nodes.filter(node => selected.has(node.id)).sort((a, b) => compare(a.id, b.id)),
+    edges: edges.filter(item => selected.has(item.source) && selected.has(item.target)).sort(edgeOrder),
+    truncated,
+  };
+}

package/src/spec-source.ts

@@ -0,0 +1,204 @@
+import { spawnSync } from "node:child_process";
+import { lstatSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { absolute, type SpecSourceSpec } from "./config.ts";
+import { realPath, memoryGitArgv, memoryGitEnv } from "./platform.ts";
+import { VaultIndex, IndexCacheError, type IndexSourceAdapter, type SearchOptions, type SearchResult } from "./vault-index.ts";
+
+/** Private spec input snapshot; raw sources are for library transforms, never graph results. */
+export interface SpecDocument {
+  id: string;
+  path: string;
+  hash: string;
+  source: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+export interface SpecDiagnostic {
+  code: "duplicate_id" | "invalid_frontmatter" | "invalid_identity" | "skipped_path";
+  path: string;
+  id?: string;
+  firstPath?: string;
+  message: string;
+}
+export interface SpecSnapshot {
+  root: string;
+  commonDir: string;
+  specs: SpecDocument[];
+  diagnostics: SpecDiagnostic[];
+}
+
+export interface SpecSourceOptions { worktree?: string; env?: NodeJS.ProcessEnv }
+export interface SpecIndexOptions extends SpecSourceOptions { memory?: boolean; reuseCache?: boolean; protectedRoots?: string[] }
+export interface SpecSearchResult extends SearchResult { id: string }
+interface Binding { root: string; registeredRoot: string; commonDir: string; rootIdentity: string; env: NodeJS.ProcessEnv }
+const compare = (a: string, b: string) => a < b ? -1 : a > b ? 1 : 0;
+const pathOrder = (a: string, b: string) => compare(a.normalize("NFC"), b.normalize("NFC")) || compare(a, b);
+function git(root: string, args: string[], env: NodeJS.ProcessEnv, maxBuffer = 65536): Buffer {
+  const argv = memoryGitArgv(["-C", root, ...args]);
+  const result = spawnSync(argv[0]!, argv.slice(1), { env: memoryGitEnv({ ...env, GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" }, { repositoryIsolation: true }), 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 = args[0] === "ls-files" ? "ignore large or vendored Markdown via .gitignore and untrack already-tracked excluded files with git rm --cached before retrying" : "inspect git -C <path> rev-parse --show-toplevel and repair unexpected output before retrying";
+      throw new Error(`spec source: git output exceeded ${maxBuffer} bytes; ${advice}`, { 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 });
+  }
+  if (result.status !== 0) {
+    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 ${result.status ?? "signal"}): ${first}; inspect git -C <path> rev-parse --show-toplevel and repair the repository or ownership configuration`);
+  }
+  return result.stdout;
+}
+function rootInfo(path: string, env: NodeJS.ProcessEnv): { root: string; commonDir: string } {
+  try { absolute(path, "spec worktree"); }
+  catch { throw new Error("spec source: worktree must be an absolute path without control characters; pass the repository root"); }
+  let root: string;
+  try { root = realPath(path); } catch { throw new Error("spec source: worktree root is unavailable; restore the repository or select an existing worktree"); }
+  // rev-parse has no NUL-output mode: root paths reject control characters, and exactly two lines are required.
+  const lines = git(root, ["rev-parse", "--show-toplevel", "--git-common-dir"], env).toString("utf8").replace(/\n$/, "").split("\n");
+  if (lines.length !== 2 || lines[0]?.normalize("NFC") !== root.normalize("NFC") || !lines[1]) throw new Error("spec source: selected path is not a git working-tree root; select the root from git rev-parse --show-toplevel");
+  let commonDir: string;
+  try { commonDir = realPath(resolve(root, lines[1])); } catch { throw new Error("spec source: git common directory is unavailable; repair the repository before retrying"); }
+  return { root, commonDir };
+}
+function directoryIdentity(root: string): string | undefined {
+  try {
+    const stat = lstatSync(root, { bigint: true });
+    return stat.isDirectory() && !stat.isSymbolicLink() ? `${stat.dev}:${stat.ino}` : undefined;
+  } catch (error) { throw new Error("spec source: canonical root cannot be inspected; restore the worktree directory and access, then reopen the source index", { cause: error }); }
+}
+function bind(source: SpecSourceSpec, options: SpecSourceOptions): Binding {
+  const env = options.env ?? process.env, registered = rootInfo(source.path, env);
+  if (registered.root !== source.path) throw new Error("spec source: registered root is no longer canonical; re-register it with vmem specs add");
+  const selected = options.worktree === undefined ? registered : rootInfo(options.worktree, env);
+  if (selected.commonDir !== registered.commonDir) throw new Error("spec source: worktree belongs to another repository; select a worktree sharing the registered repository's git common directory");
+  const rootIdentity = directoryIdentity(selected.root);
+  if (rootIdentity === undefined) throw new Error("spec source: selected root is not a plain directory; restore the canonical worktree root and retry");
+  return { root: selected.root, registeredRoot: registered.root, commonDir: selected.commonDir, rootIdentity, env };
+}
+export function resolveSpecWorktree(source: SpecSourceSpec, worktree?: string, env: NodeJS.ProcessEnv = process.env): string {
+  return bind(source, { worktree, env }).root;
+}
+function validate(binding: Binding): void {
+  const registered = rootInfo(binding.registeredRoot, binding.env), selected = rootInfo(binding.root, binding.env);
+  if (registered.root !== binding.registeredRoot || selected.root !== binding.root || registered.commonDir !== binding.commonDir || selected.commonDir !== binding.commonDir || directoryIdentity(binding.root) !== binding.rootIdentity) throw new Error("spec source: repository/worktree binding changed; resolve the registered source again before retrying");
+}
+/** A canonical root plus component checks permits filesystem spelling aliases without following links. */
+function pathProblem(binding: Binding, path: string): string | undefined {
+  const root = binding.root;
+  const parts = path.split("/"), contained = relative(root, resolve(root, path));
+  if (!path.endsWith(".md") || isAbsolute(path) || parts.some(part => !part || part === "." || part === "..") || contained === ".." || contained.startsWith(`..${sep}`) || isAbsolute(contained)) throw new Error(`spec source ${path}: git returned an unsafe Markdown path; repair the index and retry discovery`);
+  let rootIdentity: string | undefined;
+  try { rootIdentity = directoryIdentity(root); }
+  catch (error) { throw new Error(`spec source ${path}: canonical root cannot be inspected; restore root access and retry`, { cause: error }); }
+  if (rootIdentity !== binding.rootIdentity) return `spec source ${path}: root directory identity changed; restore the original root before retrying`;
+  let current = root;
+  for (let i = 0; i < parts.length; i++) {
+    current = join(current, parts[i]!);
+    let stat;
+    try { stat = lstatSync(current); }
+    catch (error) {
+      if (["ENOENT", "ENOTDIR"].includes((error as NodeJS.ErrnoException).code ?? "")) return `spec source ${path}: path is missing; restore the tracked file or stage its deletion before retrying`;
+      throw new Error(`spec source ${path}: Markdown path cannot be inspected; restore read access and retry discovery`, { cause: error });
+    }
+    if (stat.isSymbolicLink()) return `spec source ${path}: symlink component excluded; replace it with a plain file or directory before retrying`;
+    if (i < parts.length - 1 ? !stat.isDirectory() : !stat.isFile()) return `spec source ${path}: path is not a regular Markdown file with directory parents; restore the plain file and retry`;
+  }
+  let physical: string;
+  try { physical = realPath(current); }
+  catch (error) { throw new Error(`spec source ${path}: physical Markdown path cannot be resolved; restore read access and a plain path, then retry`, { cause: error }); }
+  // Git's full spelling may differ, but the file must stay below the captured physical root.
+  const physicalRelative = relative(root, physical);
+  if (physicalRelative === ".." || physicalRelative.startsWith(`..${sep}`) || isAbsolute(physicalRelative)) return `spec source ${path}: physical path leaves the registered root; restore the original root and plain in-repository file before retrying`;
+  return undefined;
+}
+function adapter(binding: Binding) {
+  let specs: SpecDocument[] = [], diagnostics: SpecDiagnostic[] = [];
+  const seen = new Map<string, string>();
+  const source: IndexSourceAdapter = {
+    validate: () => validate(binding),
+    paths: () => {
+      specs = []; diagnostics = []; seen.clear();
+      const bytes = git(binding.root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "*.md"], binding.env, 8 * 1024 * 1024);
+      let output: string;
+      try { output = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
+      catch { throw new Error("spec source: Git paths are not valid UTF-8; repair the filenames before retrying discovery"); }
+      if (output && !output.endsWith("\0")) throw new Error("spec source: git returned incomplete NUL-delimited paths; retry discovery on a stable repository");
+      const paths = [...new Set(output.split("\0").filter(Boolean))].sort(pathOrder);
+      if (paths.length > 10000) throw new Error("spec source: more than 10000 Markdown paths; ignore large or vendored Markdown via .gitignore and untrack already-tracked excluded files with git rm --cached before rebuilding");
+      return paths.filter(path => {
+        const problem = pathProblem(binding, path);
+        if (problem === undefined) return true;
+        diagnostics.push({ code: "skipped_path", path, message: problem });
+        return false;
+      });
+    },
+    validatePath: path => {
+      const problem = pathProblem(binding, path);
+      if (problem !== undefined) throw new Error(problem);
+    },
+    invalid: path => diagnostics.push({ code: "invalid_frontmatter", path, message: "spec source: invalid frontmatter; repair the Markdown YAML before rebuilding" }),
+    accept: (path, document, hash) => {
+      const data = document.data;
+      if (!Object.hasOwn(data, "id") || !Object.hasOwn(data, "type")) return false;
+      if (typeof data.id !== "string" || !data.id.trim() || typeof data.type !== "string" || !data.type.trim()) {
+        diagnostics.push({ code: "invalid_identity", path, message: "spec source: id and type must be nonempty strings; repair the frontmatter before rebuilding" });
+        return false;
+      }
+      const firstPath = seen.get(data.id);
+      if (firstPath !== undefined) {
+        diagnostics.push({ code: "duplicate_id", path, id: data.id, firstPath, message: "duplicate spec id; give each spec a unique frontmatter id before rebuilding" });
+        return false;
+      }
+      seen.set(data.id, path);
+      specs.push({ id: data.id, path, hash, source: document.source, frontmatter: data, body: document.body });
+      return true;
+    },
+  };
+  return { source, snapshot: (): SpecSnapshot => ({ root: binding.root, commonDir: binding.commonDir, specs: [...specs], diagnostics: [...diagnostics] }) };
+}
+/** Call scan() to refresh. Search and snapshots use the last completed scan, like VaultIndex. */
+export class SpecIndex {
+  private readonly index: VaultIndex<SpecSourceSpec>;
+  private readonly adapter: ReturnType<typeof adapter>;
+  private current?: SpecSnapshot;
+  constructor(home: string, source: SpecSourceSpec, options: SpecIndexOptions = {}) {
+    const binding = bind(source, options);
+    this.adapter = adapter(binding);
+    try {
+      this.index = new VaultIndex(home, { ...source, path: binding.root }, [...new Set([source.path, binding.root, ...(options.protectedRoots ?? [])])], { memory: options.memory, reuseCache: options.reuseCache, adapter: this.adapter.source });
+    } catch (error) {
+      if (error instanceof IndexCacheError) {
+        if (error.message.startsWith("spec index:")) throw error;
+        const message = error.message.replace(/^(?:index|analysis): /, "");
+        throw new Error(`spec index: ${message}; choose a readable plain cache directory outside protected sources and retry`, { cause: error });
+      }
+      throw error;
+    }
+  }
+  get file(): string { return this.index.file; }
+  close(): void { this.index.close(); }
+  scan(rebuild = false): ReturnType<VaultIndex["scan"]> {
+    const result = this.index.scan(rebuild);
+    this.current = this.adapter.snapshot();
+    return result;
+  }
+  snapshot(): SpecSnapshot { if (!this.current) this.scan(); return this.current!; }
+  search(query: string, options: SearchOptions = {}): SpecSearchResult[] {
+    const snapshot = this.snapshot(), ids = new Map(snapshot.specs.map(spec => [spec.path, spec.id]));
+    const hashes = new Map(snapshot.specs.map(spec => [spec.path, spec.hash]));
+    return this.index.search(query, options, hashes).flatMap(hit => {
+      const id = ids.get(hit.path);
+      return id === undefined ? [] : [{ ...hit, id }];
+    });
+  }
+}
+/** One-shot discovery is in memory and never opens or creates a cache on disk. */
+export function discoverSpecs(source: SpecSourceSpec, options: SpecSourceOptions = {}): SpecSnapshot {
+  const index = new SpecIndex(tmpdir(), source, { ...options, memory: true, reuseCache: false, protectedRoots: [] });
+  try { index.scan(); return index.snapshot(); } finally { index.close(); }
+}

package/src/sync.ts

@@ -52,19 +52,30 @@ function gitIn(cwd: string, env: NodeJS.ProcessEnv): Git {
     return out;
   };
 }
+/**
+ * insteadOf/pushInsteadOf rules that could rewrite any of `urls` or origin's configured URLs. Git applies a rule
+ * when its value is a literal prefix of the configured URL, so the raw config values are checked too; this covers
+ * an explicit pushurl, whose rewrite git does not report. A rule without a value is treated as matching.
+ */
+function applicableRewrites(lines: (args: string[]) => string[], urls: string[]): string[] {
+  const all = [...urls, ...lines(["config", "--get-all", "remote.origin.url"]), ...lines(["config", "--get-all", "remote.origin.pushurl"])];
+  return lines(["config", "--get-regexp", "^url\\..*\\.(insteadof|pushinsteadof)$"]).filter(line => {
+    const at = line.indexOf(" "), prefix = at < 0 ? "" : line.slice(at + 1);
+    return !prefix || all.some(url => url.startsWith(prefix));
+  });
+}
 /** Local-only origin validation shared by doctor and sync; never fetches or pushes. */
 export function originCheck(root: string, remote: string, env: NodeJS.ProcessEnv = process.env): { ok: boolean; origin: string | null; fetchUrls: string[]; pushUrls: string[]; issue?: string } {
   const git = gitIn(root, env);
   if (realpathSync(git(["rev-parse", "--show-toplevel"]).stdout.trim()) !== root) throw new Error("vault path is not the root of its git repository");
   const origin = git(["remote", "get-url", "origin"], { allowFail: true });
   const originUrl = origin.status === 0 ? origin.stdout.trim() : null;
-  // Every effective fetch and push URL must be the configured remote; URL rewrites are refused outright
-  // because git does not report pushInsteadOf rewrites of an explicit pushurl.
+  // Every effective fetch and push URL must be the configured remote, and no URL rewrite may apply to it.
   const lines = (args: string[]) => { const out = git(args, { allowFail: true }); return out.status === 0 ? out.stdout.split("\n").map(line => line.trim()).filter(Boolean) : []; };
   const fetchUrls = lines(["remote", "get-url", "--all", "origin"]), pushUrls = lines(["remote", "get-url", "--push", "--all", "origin"]);
-  const rewrites = lines(["config", "--get-regexp", "^url\\..*\\.(insteadof|pushinsteadof)$"]);
+  const rewrites = applicableRewrites(lines, [remote, ...fetchUrls, ...pushUrls]);
   const ok = originUrl !== null && rewrites.length === 0 && fetchUrls.length > 0 && pushUrls.length > 0 && [...fetchUrls, ...pushUrls].every(url => sameRemote(url, remote));
-  return { ok, origin: originUrl, fetchUrls, pushUrls, ...(!ok ? { issue: originUrl === null ? "repository has no origin remote" : rewrites.length ? "git url insteadOf/pushInsteadOf rewrites are configured; refusing because the push destination cannot be verified" : "an origin fetch or push URL does not match the configured remote; nothing was fetched or pushed" } : {}) };
+  return { ok, origin: originUrl, fetchUrls, pushUrls, ...(!ok ? { issue: originUrl === null ? "repository has no origin remote" : rewrites.length ? `git url rewrite ${rewrites[0]} applies to the vault remote; refusing because the push destination cannot be verified` : "an origin fetch or push URL does not match the configured remote; nothing was fetched or pushed" } : {}) };
 }
 function planned(path: string): boolean { return STAGE_FILES.includes(path) || STAGE_PREFIXES.some(prefix => path.startsWith(prefix)); }
 /** Parse `status --porcelain=v1 -z` into changed paths (renames contribute both sides). */
@@ -141,7 +152,8 @@ export function syncVault(home: string, request: { vault: string; confirm?: bool
       }
     }
     if (!result.commit && (!hasUpstream ? false : git(["rev-list", "--count", `${upstream}..HEAD`]).stdout.trim() === "0")) return { ...result, ok: true, applied: false, pushed: false };
-    if (lines(["remote", "get-url", "--push", "--all", "origin"]).some(url => !sameRemote(url, spec.remote!)) || lines(["config", "--get-regexp", "^url\\..*\\.(insteadof|pushinsteadof)$"]).length) return { ...result, applied: Boolean(result.commit), pushed: false, issues: [issue("REMOTE", "push destination changed before push; nothing was pushed")] };
+    const pushNow = lines(["remote", "get-url", "--push", "--all", "origin"]);
+    if (pushNow.some(url => !sameRemote(url, spec.remote!)) || applicableRewrites(lines, [spec.remote, ...fetchUrls, ...pushNow]).length) return { ...result, applied: Boolean(result.commit), pushed: false, issues: [issue("REMOTE", "push destination changed before push; nothing was pushed")] };
     const push = git(["push", "--quiet", "--porcelain", "origin", `HEAD:refs/heads/${result.branch}`], { allowFail: true });
     if (push.status !== 0) return { ...result, applied: Boolean(result.commit), pushed: false, issues: [issue("PUSH", `push failed: ${push.stderr.trim().split("\n").at(-1)?.slice(0, 300) ?? "error"}; the local commit was kept`)] };
     // Verify the remote really has our head before reporting success.

package/src/tidy.ts

@@ -329,7 +329,7 @@ function rewriteLog(root: string, expected: string, next: string, state: { commi
  * is then written through applyWrite (atomic per note, under the vault lock), the log is rewritten only for
  * `--log`, and one LINT event summarises the run. A rerun after an interruption completes the rest.
  */
-export function tidyVault(home: string, request: TidyRequest, options: { env?: NodeJS.ProcessEnv } = {}): TidyResult {
+export function tidyVault(home: string, request: TidyRequest, options: { env?: NodeJS.ProcessEnv; validate?: boolean } = {}): TidyResult {
   const rules = [...new Set(request.rules)].filter((rule): rule is TidyRule => (TIDY_RULES as readonly string[]).includes(rule)).sort((a, b) => TIDY_RULES.indexOf(a) - TIDY_RULES.indexOf(b));
   const result: TidyResult = { ok: false, applied: false, rules, counts: {}, notes: [], reported: [], written: [], issues: [] };
   if (!rules.length) return { ...result, issues: [issue("V01", "select at least one rule or --all")] };
@@ -374,6 +374,12 @@ export function tidyVault(home: string, request: TidyRequest, options: { env?: N
       if (sanitized.text !== before) { logPlan = { before, ...sanitized }; result.counts.log = sanitized.redactions + sanitized.formats; }
     }
   }
+  // Doctor needs planning counts only: do not resnapshot the vault once per planned note.
+  // A confirmation always keeps writer validation, even if this internal option is supplied.
+  if (options.validate === false && request.confirm !== true) {
+    for (const change of planned) for (const [rule, n] of Object.entries(change.counts)) if (n > 0) ruleCount(result.counts, rule, n);
+    return { ...result, ok: true, preview: true };
+  }
   // Validate every planned note with the writer (dry-run). A note the writer would refuse is reported and skipped
   // (left fully unchanged for manual repair) instead of blocking the rest of the migration.
   for (const change of [...planned]) {