@staix/vault-mem 0.3.2 → 0.3.3

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 };
+}

package/src/spec-graph.ts

@@ -24,10 +24,15 @@ export interface SpecSlice { nodes: SpecNode[]; edges: SpecEdge[]; truncated: bo
 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 {
+/** 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(), wiki = /^\[\[([^\]|#]+)\]\]$/.exec(text);
-  return wiki ? wiki[1]!.trim() : text;
+  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. */
@@ -54,23 +59,29 @@ export function buildSpecGraph(snapshot: SpecSnapshot): SpecGraph {
   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;
+    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;
+    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()) {
-    for (const kind of ["parent", "superseded-by"] as const) add(document.id, document.frontmatter[kind], kind);
+    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 (Array.isArray(values)) for (const value of values) add(document.id, value, 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");
   }

package/src/spec-source.ts

@@ -1,31 +1,34 @@
-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 { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { absolute, type SpecSourceSpec } from "./config.ts";
-import { realPath, memoryGitArgv, memoryGitEnv } from "./platform.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 SpecDocument {
-  id: string;
+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";
+  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[];
 }
 
@@ -36,22 +39,7 @@ interface Binding { root: string; registeredRoot: string; commonDir: string; roo
 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;
+  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"); }
@@ -73,7 +61,7 @@ function directoryIdentity(root: string): string | undefined {
 }
 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");
+  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);
@@ -116,13 +104,28 @@ function pathProblem(binding: Binding, path: string): string | undefined {
   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[] = [], diagnostics: SpecDiagnostic[] = [];
+  let specs: SpecDocument[] = [], candidates: SpecCandidate[] = [], diagnostics: SpecDiagnostic[] = [];
   const seen = new Map<string, string>();
   const source: IndexSourceAdapter = {
     validate: () => validate(binding),
     paths: () => {
-      specs = []; diagnostics = []; seen.clear();
+      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); }
@@ -141,9 +144,19 @@ function adapter(binding: Binding) {
       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" }),
+    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" });
@@ -159,7 +172,7 @@ function adapter(binding: Binding) {
       return true;
     },
   };
-  return { source, snapshot: (): SpecSnapshot => ({ root: binding.root, commonDir: binding.commonDir, specs: [...specs], diagnostics: [...diagnostics] }) };
+  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 {
@@ -183,15 +196,23 @@ export class SpecIndex {
   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;
+    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 = {}): SpecSearchResult[] {
+  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).flatMap(hit => {
+    return this.index.search(query, options, hashes, options.offset ?? 0, all).flatMap(hit => {
       const id = ids.get(hit.path);
       return id === undefined ? [] : [{ ...hit, id }];
     });