@staix/vault-mem 0.3.1 → 0.3.3

package/src/spec-graph.ts

@@ -0,0 +1,128 @@
+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);
+/** Metadata wiki addresses use the same id/label/heading split as body links. */
+export function specReference(value: unknown): string | undefined {
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  const text = value.trim();
+  if (!text.startsWith("[[") && !text.endsWith("]]")) return text;
+  const wiki = /^\[\[([^\]\n]+)\]\]$/.exec(text);
+  if (!wiki) return undefined;
+  const address = wiki[1]!.split("|")[0]!, hash = address.indexOf("#");
+  return (hash < 0 ? address : address.slice(0, hash)).trim() || undefined;
+}
+
+/** 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 = specReference(value);
+    if (!target) return false;
+    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 true;
+    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 });
+    return true;
+  };
+  for (const document of documents.values()) {
+    const wrongShape = (field: string) => diagnostics.push({ code: "wrong_shape", path: document.path, id: document.id, field, message: "frontmatter link has the wrong shape; use one link for parent/superseded-by and a list for dependency/reference/implementation links" });
+    for (const kind of ["parent", "superseded-by"] as const) if (document.frontmatter[kind] !== undefined && !add(document.id, document.frontmatter[kind], kind)) wrongShape(kind);
+    for (const kind of ["depends-on", "references", "implements"] as const) {
+      const values = document.frontmatter[kind];
+      if (values === undefined) continue;
+      if (!Array.isArray(values)) { wrongShape(kind); continue; }
+      let invalid = false;
+      for (const value of values) if (!add(document.id, value, kind)) invalid = true;
+      if (invalid) wrongShape(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,225 @@
+import { lstatSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { absolute, type SpecSourceSpec } from "./config.ts";
+import { realPath } from "./platform.ts";
+import { specGit } from "./spec-git.ts";
+import { parseFrontmatter } from "./frontmatter.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 SpecCandidate {
+  path: string;
+  hash: string;
+  source: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+export interface SpecDocument extends SpecCandidate { id: string }
+export interface SpecDiagnostic {
+  code: "duplicate_id" | "invalid_frontmatter" | "invalid_identity" | "skipped_path" | "wrong_shape";
+  path: string;
+  id?: string;
+  firstPath?: string;
+  field?: string;
+  message: string;
+}
+export interface SpecSnapshot {
+  root: string;
+  commonDir: string;
+  specs: SpecDocument[];
+  candidates?: SpecCandidate[];
+  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 {
+  return specGit(root, args, { env, maxBuffer, discovery: args[0] === "ls-files" }).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; restore the canonical root or preview unregistering it with vmem specs remove <id>, then confirm removal before adding the new root");
+  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 namedSpec(path: string): boolean { return basename(path) === "SPEC.md"; }
+function candidateData(path: string, data: Record<string, unknown>): boolean { return namedSpec(path) || Object.hasOwn(data, "id") || Object.hasOwn(data, "type"); }
+function candidateProbe(path: string, reason: "oversized" | "invalid_utf8", bytes: Buffer): boolean {
+  if (namedSpec(path)) return true;
+  try {
+    const document = parseFrontmatter(bytes.toString("utf8"));
+    if (!document.frontmatter) return false;
+    // This is a conservative signal only: visible reserved keys keep the blocking encoding error.
+    // Accepted documents are still decoded strictly by the scanner.
+    return candidateData(path, document.data);
+  } catch (error) {
+    if (reason === "oversized" && error instanceof Error && error.message === "frontmatter: missing closing delimiter") throw new Error(`spec source ${path}: frontmatter exceeds the bounded candidate probe; shorten the header before validating`, { cause: error });
+    return false;
+  }
+}
+function adapter(binding: Binding) {
+  let specs: SpecDocument[] = [], candidates: SpecCandidate[] = [], diagnostics: SpecDiagnostic[] = [];
+  const seen = new Map<string, string>();
+  const source: IndexSourceAdapter = {
+    validate: () => validate(binding),
+    paths: () => {
+      specs = []; candidates = []; 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 => {
+      if (!namedSpec(path)) return false;
+      diagnostics.push({ code: "invalid_frontmatter", path, message: "spec source: invalid frontmatter; repair the SPEC.md YAML before validating" });
+      return true;
+    },
+    skipFile: (path, reason, bytes) => {
+      if (candidateProbe(path, reason, bytes)) return false;
+      diagnostics.push({ code: "skipped_path", path, message: `non-candidate Markdown ${path}: ${reason === "oversized" ? "file exceeds the bounded read size" : "file is not valid UTF-8"}; split/re-encode it or exclude it via .gitignore` });
+      return true;
+    },
+    accept: (path, document, hash) => {
+      const data = document.data;
+      if (candidateData(path, data)) candidates.push({ path, hash, source: document.source, frontmatter: data, body: document.body });
+      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], candidates: [...candidates], 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"]> {
+    try {
+      const result = this.index.scan(rebuild);
+      this.current = this.adapter.snapshot();
+      return result;
+    } catch (error) { this.current = undefined; throw error; }
+  }
+  snapshot(): SpecSnapshot { if (!this.current) this.scan(); return this.current!; }
+  search(query: string, options: SearchOptions & { offset?: number } = {}): SpecSearchResult[] {
+    if (options.offset !== undefined && (!Number.isSafeInteger(options.offset) || options.offset < 0 || options.offset > 10000)) throw new Error("spec search offset: expected integer 0..10000; choose a bounded continuation offset");
+    return this.searchRows(query, options, false);
+  }
+  /** One bounded query materializes the matching snapshot before callers filter or page it. */
+  searchAll(query: string): SpecSearchResult[] { return this.searchRows(query, {}, true); }
+  private searchRows(query: string, options: SearchOptions & { offset?: number }, all: boolean): 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, options.offset ?? 0, all).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/spec-validate.ts

@@ -0,0 +1,241 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { realPath } from "./platform.ts";
+import { extractLinks } from "./links.ts";
+import { specReference, MAX_SPEC_INPUTS } from "./spec-graph.ts";
+import { discoverSpecs, type SpecCandidate, type SpecDiagnostic, type SpecSnapshot } from "./spec-source.ts";
+import { specFreshness, specMetadataIssues, type SpecFreshnessEntry } from "./spec-freshness.ts";
+
+export interface SpecValidationIssue {
+  code: string;
+  severity: "error" | "warning";
+  path: string;
+  id?: string;
+  field?: string;
+  target?: string;
+  message: string;
+}
+export interface SpecValidationOptions { env?: NodeJS.ProcessEnv; requireFresh?: boolean; limit?: number; git?: boolean }
+export interface SpecValidationReport {
+  ok: boolean;
+  errors: number;
+  warnings: number;
+  items: SpecValidationIssue[];
+  diagnostics: SpecDiagnostic[];
+  freshness: SpecFreshnessEntry[];
+  truncated: boolean;
+}
+export interface SpecRepoValidationOptions { env?: NodeJS.ProcessEnv; requireFresh?: boolean; limit?: number }
+export interface SpecRepoValidation { code: 0 | 1; report: SpecValidationReport }
+const RANK: Readonly<Record<string, number>> = { goal: 0, architecture: 1, module: 2, submodule: 3 };
+const STATUSES = new Set(["draft", "active", "deprecated"]);
+const MAX_OPERATIONS = 200000, MAX_ITEMS = 500, MAX_REPORT_BYTES = 128 * 1024;
+const compare = (a: string, b: string) => a < b ? -1 : a > b ? 1 : 0;
+const nonempty = (value: unknown): value is string => typeof value === "string" && !!value.trim();
+const candidateId = (candidate: SpecCandidate) => nonempty(candidate.frontmatter.id) ? candidate.frontmatter.id : undefined;
+interface ErrorOwner { kind: "old" | "new"; path: string }
+interface Collected { records: { issue: SpecValidationIssue; key: string }[]; freshness: SpecFreshnessEntry[] }
+
+/** Complete collection is separate from display limits, so the introduced-error gate never compares samples. */
+function collect(snapshot: SpecSnapshot, options: SpecValidationOptions, owners?: ReadonlyMap<string, ErrorOwner>): Collected {
+  const candidates = [...(snapshot.candidates ?? snapshot.specs)].sort((a, b) => compare(a.path.normalize("NFC"), b.path.normalize("NFC")) || compare(a.path, b.path));
+  if (new Set(candidates.map(candidate => candidate.path)).size !== candidates.length) throw new Error("spec validation: duplicate candidate paths; provide one candidate record per file");
+  if (candidates.length > MAX_SPEC_INPUTS) throw new Error("spec validation: more than 10000 candidates; reduce the candidate tree before validating");
+  let operations = 0;
+  const tick = () => { if (++operations > MAX_OPERATIONS) throw new Error("spec validation: more than 200000 checks; reduce repeated links or metadata lists before validating"); };
+  const hashes = new Map<string, string>();
+  const digest = (value: string): string => {
+    let hash = hashes.get(value);
+    if (hash === undefined) { hash = createHash("sha256").update(value).digest("hex"); hashes.set(value, hash); }
+    return hash;
+  };
+  const records: Collected["records"] = [], keys = new Set<string>();
+  const addIssue = (issue: SpecValidationIssue) => {
+    tick();
+    const correspondence = owners?.get(issue.path) ?? { kind: owners === undefined ? "old" : "new", path: issue.path };
+    const owner = `${correspondence.kind}:${digest(correspondence.path)}`;
+    // Hash values independently: a long owner id is never copied once per relation/error key.
+    const key = JSON.stringify([digest(snapshot.commonDir), issue.severity, issue.code, owner, issue.field ?? "", issue.target === undefined ? "" : digest(issue.target)]);
+    if (!keys.has(key)) { keys.add(key); records.push({ issue, key }); }
+  };
+  const add = (candidate: SpecCandidate, code: string, severity: SpecValidationIssue["severity"], field: string, message: string, target?: string) => {
+    const id = candidateId(candidate);
+    addIssue({ code, severity, path: candidate.path, ...(id === undefined ? {} : { id }), field, message, ...(target === undefined ? {} : { target }) });
+  };
+  const nodes = new Map<string, SpecCandidate>(), first = new Map<string, string>();
+  for (const candidate of candidates) {
+    const id = candidateId(candidate);
+    if (id !== undefined) {
+      const previous = first.get(id);
+      if (previous !== undefined) add(candidate, "duplicate_id", "error", "id", "duplicate id; give each candidate a unique id", previous);
+      else first.set(id, candidate.path);
+      if (nonempty(candidate.frontmatter.type) && !nodes.has(id)) nodes.set(id, candidate);
+    }
+  }
+  const covers = new Map<string, Map<string, SpecCandidate>>();
+  for (const candidate of candidates) {
+    tick();
+    const data = candidate.frontmatter, id = candidateId(candidate);
+    if (options.git === false) for (const issue of specMetadataIssues(candidate)) addIssue(issue);
+    for (const field of ["id", "type", "title"] as const) {
+      if (data[field] === undefined) add(candidate, `missing_${field}`, "error", field, `required ${field} is missing; add a nonempty string field`);
+      else if (!nonempty(data[field])) add(candidate, "wrong_shape", "error", field, `${field} must be a nonempty string; correct the frontmatter field`);
+    }
+    if (nonempty(data.type) && !Object.hasOwn(RANK, data.type)) add(candidate, "unknown_type", "error", "type", "unknown type; use goal, architecture, module or submodule");
+    if (data.status !== undefined && (typeof data.status !== "string" || !STATUSES.has(data.status))) add(candidate, "unknown_status", "error", "status", "unknown status; use draft, active or deprecated");
+    if (data.parent === undefined && data.type !== "goal") add(candidate, "orphan", "warning", "parent", "non-goal spec has no parent; link it to its owning higher-level spec");
+    if (data.status === "active" && data.paths === undefined) add(candidate, "active_without_paths", "warning", "paths", "active spec has no paths; add relative Git pathspecs for its source scope");
+    const checkLink = (field: string, value: unknown, shapeField = field): string | undefined => {
+      tick();
+      const target = specReference(value);
+      if (target === undefined) { add(candidate, "wrong_shape", "error", shapeField, "link must be one id or wiki link; correct the frontmatter value"); return undefined; }
+      if (!nodes.has(target)) add(candidate, "dangling_link", "error", field, "frontmatter link names no graph node; link to an existing spec id or remove it", target);
+      return target;
+    };
+    let parent: string | undefined, replacement: string | undefined;
+    if (data.parent !== undefined) parent = checkLink("parent", data.parent);
+    if (data["superseded-by"] !== undefined) {
+      replacement = checkLink("superseded-by", data["superseded-by"]);
+      if (data.status !== "deprecated") add(candidate, "superseded_status", "error", "superseded-by", "replacement link requires deprecated status; deprecate the spec or remove the link");
+      if (replacement !== undefined && replacement === id) add(candidate, "superseded_self", "error", "superseded-by", "replacement points to this spec; link to a different replacement", replacement);
+    } else if (data.status === "deprecated") add(candidate, "deprecated_without_replacement", "warning", "superseded-by", "deprecated spec has no replacement; add a superseded-by id when one exists");
+    if (data.status === "deprecated" && replacement !== undefined && replacement !== id && nodes.get(replacement)?.frontmatter.status === "deprecated") add(candidate, "deprecated_replacement", "warning", "superseded-by", "replacement is also deprecated; link to an active replacement", replacement);
+    for (const field of ["depends-on", "references", "implements"] as const) {
+      if (data[field] === undefined) continue;
+      const values = data[field];
+      if (!Array.isArray(values)) { add(candidate, "wrong_shape", "error", field, `${field} must be a list of links; wrap the value in a list`); continue; }
+      for (let i = 0; i < values.length; i++) checkLink(field, values[i], `${field}[${i}]`);
+    }
+    if (parent !== undefined) {
+      const parentType = nodes.get(parent)?.frontmatter.type;
+      if (typeof data.type === "string" && typeof parentType === "string" && Object.hasOwn(RANK, data.type) && Object.hasOwn(RANK, parentType) && RANK[data.type]! <= RANK[parentType]!) add(candidate, "type_rank", "error", "parent", "child rank must exceed parent rank; choose a higher-level parent (levels may be skipped)", parent);
+    }
+    for (const field of ["covers", "tags"] as const) {
+      const values = data[field];
+      if (values === undefined) continue;
+      let valid = Array.isArray(values);
+      if (Array.isArray(values)) for (const value of values) { tick(); if (!nonempty(value)) valid = false; }
+      if (!valid) {
+        add(candidate, "wrong_shape", "error", field, `${field} must be a list of nonempty strings; correct the frontmatter field`);
+        continue;
+      }
+      if (field === "covers") for (const value of values as string[]) {
+        const token = value.trim();
+        let owners = covers.get(token); if (!owners) covers.set(token, owners = new Map());
+        owners.set(candidate.path, candidate);
+      }
+    }
+    for (const link of extractLinks(candidate.body)) {
+      tick();
+      if (link.target && !nodes.has(link.target)) add(candidate, "unknown_body_link", "warning", "body", "body wiki link names no graph node; correct the target id or remove the link", link.target);
+    }
+  }
+  for (const [token, owners] of covers) if (owners.size > 1) for (const candidate of owners.values()) add(candidate, "duplicate_covers", "warning", "covers", "covers token is claimed by multiple specs; choose a single owning spec", token);
+  const goals = [...nodes.values()].filter(candidate => candidate.frontmatter.type === "goal");
+  if (goals.length > 1) for (const candidate of goals) add(candidate, "multiple_goals", "warning", "type", "multiple goal roots exist; consolidate or document separate goal trees");
+  // Iterative traversal handles a 10000-node chain without overflowing the JS stack.
+  const finished = new Set<string>();
+  for (const id of nodes.keys()) {
+    if (finished.has(id)) continue;
+    const chain: string[] = [], positions = new Map<string, number>();
+    let next: string | undefined = id;
+    while (next !== undefined && nodes.has(next) && !finished.has(next) && !positions.has(next)) {
+      tick(); positions.set(next, chain.length); chain.push(next);
+      next = specReference(nodes.get(next)!.frontmatter.parent);
+    }
+    if (next !== undefined && positions.has(next)) for (const member of chain.slice(positions.get(next)!)) add(nodes.get(member)!, "parent_cycle", "error", "parent", "parent cycle detected; remove a cycle link and point to a higher-level parent", specReference(nodes.get(member)!.frontmatter.parent));
+    for (const member of chain) finished.add(member);
+  }
+  for (const diagnostic of snapshot.diagnostics) {
+    if (diagnostic.code === "invalid_frontmatter") addIssue({ code: "invalid_frontmatter", severity: "error", path: diagnostic.path, field: "frontmatter", message: diagnostic.message });
+    else if (snapshot.candidates === undefined && diagnostic.code === "duplicate_id") addIssue({ code: "duplicate_id", severity: "error", path: diagnostic.path, id: diagnostic.id, field: "id", target: diagnostic.firstPath, message: diagnostic.message });
+    else if (snapshot.candidates === undefined && diagnostic.code === "invalid_identity") addIssue({ code: "wrong_shape", severity: "error", path: diagnostic.path, field: "id/type", message: diagnostic.message });
+  }
+  if (options.requireFresh && options.git === false) throw new Error("spec validation: requireFresh needs Git inspection; enable Git checks before requiring freshness");
+  const freshness = options.git === false ? { items: [], issues: [] } : specFreshness(snapshot, { env: options.env });
+  for (const issue of freshness.issues) addIssue(issue);
+  if (options.requireFresh) for (const item of freshness.items) if (item.state === "stale") addIssue({ code: "stale", severity: "error", path: item.path, id: item.id, field: "verified-against", message: "spec source scope is stale; review its paths and refresh verified-against after verification" });
+  records.sort((a, b) => (a.issue.severity === b.issue.severity ? 0 : a.issue.severity === "error" ? -1 : 1) || compare(a.issue.path.normalize("NFC"), b.issue.path.normalize("NFC")) || compare(a.issue.path, b.issue.path) || compare(a.issue.code, b.issue.code) || compare(a.issue.field ?? "", b.issue.field ?? "") || compare(a.key, b.key));
+  return { records, freshness: freshness.items };
+}
+
+/** Display is count/byte bounded; oversized optional identifiers are omitted, never silently renamed. */
+function display<T extends object>(values: readonly T[], limit: number, budget: { bytes: number; truncated: boolean }): T[] {
+  const out: T[] = [];
+  for (const original of values) {
+    if (out.length >= limit) { budget.truncated = true; break; }
+    const value = { ...original } as T & { id?: string; target?: string };
+    for (const field of ["id", "target"] as const) if (typeof value[field] === "string" && Buffer.byteLength(value[field]!) > 1024) { delete value[field]; budget.truncated = true; }
+    const bytes = Buffer.byteLength(JSON.stringify(value)) + 1;
+    if (budget.bytes + bytes > MAX_REPORT_BYTES) { budget.truncated = true; break; }
+    budget.bytes += bytes; out.push(value);
+  }
+  return out;
+}
+function reportLimit(value = MAX_ITEMS): number {
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_ITEMS) throw new Error("spec validation: report limit must be 1..500; pass a smaller positive item limit");
+  return value;
+}
+export function validateSpecs(snapshot: SpecSnapshot, options: SpecValidationOptions = {}): SpecValidationReport {
+  const limit = reportLimit(options.limit), result = collect(snapshot, options), budget = { bytes: 1024, truncated: false };
+  const errors = result.records.filter(record => record.issue.severity === "error").length;
+  return { ok: errors === 0, errors, warnings: result.records.length - errors,
+    items: display(result.records.map(record => record.issue), limit, budget),
+    diagnostics: display(snapshot.diagnostics, limit, budget), freshness: display(result.freshness, limit, budget),
+    get truncated() { return budget.truncated; } };
+}
+/** Existing error identities are retained even when their display sample was truncated. */
+export function introducedSpecErrors(current: SpecSnapshot, prospective: SpecSnapshot, options: SpecValidationOptions = {}): SpecValidationIssue[] {
+  const limit = reportLimit(options.limit);
+  const pathsById = (input: SpecSnapshot) => {
+    const paths = new Map<string, Set<string>>();
+    const add = (id: string, path: string) => { let found = paths.get(id); if (!found) paths.set(id, found = new Set()); found.add(path); };
+    for (const candidate of input.candidates ?? input.specs) { const id = candidateId(candidate); if (id !== undefined) add(id, candidate.path); }
+    if (input.candidates === undefined) for (const diagnostic of input.diagnostics) if (diagnostic.code === "duplicate_id" && diagnostic.id !== undefined) add(diagnostic.id, diagnostic.path);
+    return paths;
+  };
+  const oldIds = pathsById(current), nextIds = pathsById(prospective), owners = new Map<string, ErrorOwner>(), reserved = new Set<string>();
+  for (const candidate of prospective.candidates ?? prospective.specs) {
+    const id = candidateId(candidate), previous = id === undefined ? undefined : oldIds.get(id);
+    if (previous?.size === 1 && nextIds.get(id!)?.size === 1) {
+      const path = previous.values().next().value!;
+      owners.set(candidate.path, { kind: "old", path }); reserved.add(path);
+    }
+  }
+  const previousPaths = new Set([...(current.candidates ?? current.specs).map(candidate => candidate.path), ...current.diagnostics.map(diagnostic => diagnostic.path)]);
+  const prospectivePaths = new Set([...(prospective.candidates ?? prospective.specs).map(candidate => candidate.path), ...prospective.diagnostics.map(diagnostic => diagnostic.path)]);
+  for (const path of prospectivePaths) if (!owners.has(path)) {
+    const retained = previousPaths.has(path) && !reserved.has(path);
+    owners.set(path, { kind: retained ? "old" : "new", path });
+    if (retained) reserved.add(path);
+  }
+  // Duplicate identity belongs to the id, even when a move changes the first file in path order.
+  // Keep collection keys unchanged so validation still reports each duplicate file.
+  const comparisonKey = (input: SpecSnapshot, record: Collected["records"][number]): string =>
+    record.issue.code === "duplicate_id" && record.issue.id !== undefined
+      ? JSON.stringify([createHash("sha256").update(input.commonDir).digest("hex"), "duplicate_id", createHash("sha256").update(record.issue.id).digest("hex")])
+      : record.key;
+  const old = new Map<string, number>();
+  for (const record of collect(current, options).records) if (record.issue.severity === "error") {
+    const key = comparisonKey(current, record); old.set(key, (old.get(key) ?? 0) + 1);
+  }
+  const prospectiveErrors = collect(prospective, options, owners).records.filter(record => record.issue.severity === "error");
+  // Retained owners consume existing debt before new or moved files do.
+  prospectiveErrors.sort((a, b) => Number(owners.get(b.issue.path)?.kind === "old") - Number(owners.get(a.issue.path)?.kind === "old"));
+  const next = prospectiveErrors.filter(record => {
+    const key = comparisonKey(prospective, record), count = old.get(key) ?? 0;
+    if (count === 0) return true;
+    old.set(key, count - 1); return false;
+  });
+  const result = display(next.map(record => record.issue), limit, { bytes: 1024, truncated: false });
+  if (next.length && !result.length) throw new Error("spec validation: introduced error metadata exceeds the report budget; reduce metadata before writing");
+  return result;
+}
+/** Registry-free CI logic; no home/config/cache creation and no authored freshness fields. */
+export function validateSpecRepo(repo: string, options: SpecRepoValidationOptions = {}): SpecRepoValidation {
+  let root: string;
+  try { root = realPath(resolve(repo)); } catch (error) { throw new Error("spec validation: repository root is unavailable; pass an existing checkout root", { cause: error }); }
+  const snapshot = discoverSpecs({ id: "repo", path: root, write: "none", pii: "deny" }, { env: options.env });
+  const report = validateSpecs(snapshot, options);
+  return { code: report.ok ? 0 : 1, report };
+}

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]) {