agent-doc-system 1.3.0 → 1.5.0

package/core/context/index.mjs

@@ -0,0 +1,173 @@
+import { CODES } from "../codes.mjs";
+// Task context protocol. Graph authority stays in the compiler; this module
+// selects and transports facts without turning an interpretation into a fact.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { getEncoding } from 'js-tiktoken';
+import { compileSnapshot } from '../snapshot.mjs';
+import { ContextIndex, queryContext } from '../query.mjs';
+import { impact } from '../impact.mjs';
+import { canonicalPath } from '../paths.mjs';
+import { observationFreshness } from '../observations.mjs';
+import { assertNoSecretsInText } from '../secrets.mjs';
+
+const VERSION = 'agentdoc.dev/context/v1';
+const INTENTS = ['implement', 'change-contract', 'debug-runtime', 'review'];
+const ENCODERS = new Map();
+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function error(code, message) { throw Object.assign(new Error(message), { code }); }
+function closed(value, keys, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) error(CODES.CONTEXT_REQUEST, name + ' must be an object');
+  for (const k of Object.keys(value)) if (!keys.includes(k)) error(CODES.CONTEXT_REQUEST, 'unknown ' + name + ' field: ' + k);
+}
+export function validateRequest(request) {
+  closed(request, ['task', 'paths', 'intent', 'budget', 'cache'], 'request');
+  if (typeof request.task !== 'string' || !request.task.trim()) error(CODES.CONTEXT_REQUEST, 'task must be a nonempty string');
+  if (!Array.isArray(request.paths) || !request.paths.length || request.paths.some(p => typeof p !== 'string' || !p || (!/^[a-z]+:[a-z0-9-]+\//.test(p) && canonicalPath(p) === null))) error(CODES.CONTEXT_REQUEST, 'paths must be repository paths or entity refs');
+  if (request.intent !== undefined && !INTENTS.includes(request.intent)) error(CODES.CONTEXT_REQUEST, 'unsupported intent');
+  if (request.cache !== undefined && typeof request.cache !== 'boolean') error(CODES.CONTEXT_REQUEST, 'cache must be boolean');
+  if (request.budget !== undefined) closed(request.budget, ['tokens', 'encoding'], 'budget');
+  const budget = { tokens: 4096, encoding: 'o200k_base', ...request.budget };
+  if (!Number.isSafeInteger(budget.tokens) || budget.tokens < 256 || budget.tokens > 1000000) error(CODES.CONTEXT_BUDGET, 'tokens must be an integer from 256 to 1000000');
+  if (!['o200k_base', 'cl100k_base'].includes(budget.encoding)) error(CODES.CONTEXT_TOKENIZER, 'supported pinned encodings: o200k_base, cl100k_base');
+  return { task: request.task.trim(), paths: [...new Set(request.paths)].sort(), intent: request.intent || 'implement', budget, cache: request.cache !== false };
+}
+export function countTokens(text, encoding = 'o200k_base') {
+  if (!ENCODERS.has(encoding)) ENCODERS.set(encoding, getEncoding(encoding));
+  return ENCODERS.get(encoding).encode(text, [], []).length;
+}
+export function serializePacket(packet) { return JSON.stringify(packet) + '\n'; }
+function record(kind, subject, key, value, evidence = [], critical = false) {
+  const id = hash([kind, subject, key]).slice(0, 24);
+  return JSON.parse(JSON.stringify({ id, version: hash([value, evidence]), kind, subject, key, value, evidence: [...evidence].sort(), critical }));
+}
+function collect(res, request) {
+  const g = res.graph, idx = new ContextIndex(g), refs = new Set(), records = new Map();
+  const im = impact(g, request.paths);
+  const put = r => records.set(r.id, r);
+  for (const p of request.paths) { const e = idx.resolve(p); if (e) refs.add(e.ref); }
+  for (const e of im.affectedComponents) refs.add(e.ref);
+  // Unlimited selection here: the single serialized token budget controls delivery.
+  const unlimited = Object.fromEntries(['relations','events','externals','capabilities','verification','journeys','conflicts','assertions','provenance','contracts'].map(k => [k, Number.MAX_SAFE_INTEGER]));
+  for (const ref of [...refs].sort()) {
+    const ctx = queryContext(g, ref, { budget: unlimited, index: idx });
+    put(record('entity', ref, 'identity', { description: ctx.entity.description, derived: ctx.entity.derived }, ctx.entity.sourcePaths));
+    for (const r of ctx.relations.items) put(record('relation', ref, r.type + ':' + r.direction + ':' + r.other, r, r.provenanceIds));
+    for (const a of ctx.authority.assertions.items) put(record('assertion', ref, a.key + ':' + a.id, a, [], a.key.startsWith('requirement.')));
+    for (const c of ctx.authority.conflicts.items) put(record('conflict', ref, c.id, c, [], true));
+    for (const [kind, paths] of Object.entries(ctx.constraints)) for (const p of paths) {
+      const bytes = res.repo.readBytes(p);
+      const expected = res.graph.provenance.filter(x => x.path === p).map(x => x.contentHash.replace(/^sha256:/, ''));
+      if (!expected.includes(createHash('sha256').update(bytes).digest('hex'))) error(CODES.CONTEXT_STALE, 'document is not pinned by this snapshot: ' + p);
+      const source = new TextDecoder('utf-8', { fatal: true }).decode(bytes).replace(/^\uFEFF/, '');
+      put(record(kind === 'constraints' ? 'requirement' : 'document', ref, p,
+        { path: p, sha256: createHash('sha256').update(bytes).digest('hex'), text: source }, [p], kind === 'constraints'));
+    }
+    for (const c of ctx.contracts.items) put(record('contract', ref, c.id || c.ref, c, c.provenanceIds));
+    for (const o of ctx.authority.observations) put(record('observation', ref, o.id, o, o.evidenceBundle ? [o.evidenceBundle] : [], true));
+    for (const r of ctx.reviewCommitments.filter(r => !r.subject || refs.has(r.subject))) put(record('review', r.subject || 'repository', r.key || r.kind, r, [], true));
+    for (const j of ctx.journeys.items) put(record('journey', ref, j.id, j));
+    for (const e of ctx.events.items) put(record('event', ref, e.pattern, e, [], true));
+  }
+  const checks = new Map();
+  for (const p of [...refs]) {
+    const ctx = queryContext(g, p, { budget: unlimited, index: idx });
+    for (const v of [...ctx.verification.items, ...ctx.globalGates]) checks.set(v.id, v);
+  }
+  for (const v of im.recommendedVerification) checks.set(v.id, v);
+  for (const v of checks.values()) {
+    const original = [...g.verification, ...g.gates].find(x => x.id === v.id);
+    const owners = original?.componentRefs || [];
+    // Command text alone cannot prove a working directory; keep that unknown.
+    put(record('check', 'repository', v.id, { ...v, componentRefs: owners, execution: { kind: 'shell', cwd: null, status: 'requires-context' }, status: 'recommended' }, original?.provenanceIds, true));
+  }
+  for (const f of observationFreshness(g.observations)) if (f.stale) put(record('freshness', 'repository', f.id, f, [], true));
+  const sort = (a, b) => Number(b.critical) - Number(a.critical) || a.kind.localeCompare(b.kind) || a.id.localeCompare(b.id);
+  return { records: [...records.values()].sort(sort), scope: [...refs].sort(), coverage: { unmatched: im.unmatchedFiles, limitations: ['component-level analysis; dynamic and unsupported relationships may be absent'], staleObservations: observationFreshness(g.observations).filter(f => f.stale).map(f => f.id) } };
+}
+function storeDir(root) { return path.join(root, '.agentdoc', 'context'); }
+function save(root, id, data) {
+  const dir = storeDir(root); fs.mkdirSync(dir, { recursive: true });
+  const temp = path.join(dir, id + '.' + randomUUID() + '.tmp');
+  fs.writeFileSync(temp, JSON.stringify({ identity: data.identity }), { mode: 0o600 });
+  fs.renameSync(temp, path.join(dir, id + '.json'));
+  const retained = fs.readdirSync(dir).filter(n => /^[a-f0-9]{64}\.json$/.test(n)).map(n => ({ n, time: fs.statSync(path.join(dir,n)).mtimeMs })).sort((a,b) => b.time-a.time || a.n.localeCompare(b.n));
+  for (const old of retained.slice(64)) if (old.n !== id + '.json') fs.rmSync(path.join(dir,old.n), { force: true });
+}
+function load(root, id) {
+  if (!/^[a-f0-9]{64}$/.test(id || '')) error(CODES.CONTEXT_REFERENCE, 'invalid packet reference');
+  try { const x = JSON.parse(fs.readFileSync(path.join(storeDir(root), id + '.json'), 'utf8')); if (hash(x.identity) !== id) throw new Error(); return { ...x.identity, id };  }
+  catch { error(CODES.CONTEXT_REFERENCE, 'packet unavailable; run prepare again'); }
+}
+function packetPage(state, offset, limit) {
+  const p = { schemaVersion: VERSION, packet: state.id, snapshot: state.snapshot, task: state.request.task, intent: state.request.intent, scope: state.scope, coverage: state.coverage,
+    records: [], delivery: { offset, total: state.records.length, omitted: state.records.length - offset, criticalOmitted: 0, partial: true },
+    continuation: { packet: state.id, offset }, budget: { limit, used: 0, encoding: state.request.budget.encoding, tokenizerVersion: 'js-tiktoken@1.0.21' } };
+  const measure = () => {
+    // Digit count feeds back into encoding; converge to the exact final size.
+    for (let i = 0; i < 12; i++) { const n = countTokens(serializePacket(p), p.budget.encoding); if (n === p.budget.used) return n; p.budget.used = n; }
+    error(CODES.CONTEXT_BUDGET, 'token accounting did not converge');
+  };
+  const update = () => {
+    const next = offset + p.records.length;
+    p.delivery.omitted = state.records.length - next;
+    p.delivery.criticalOmitted = state.records.slice(next).filter(r => r.critical).length;
+    p.delivery.partial = next < state.records.length;
+    p.continuation = next < state.records.length ? { packet: state.id, offset: next } : null;
+    return measure();
+  };
+  if (update() > limit) error(CODES.CONTEXT_BUDGET, 'budget cannot hold the minimum envelope');
+  for (const r of state.records.slice(offset)) {
+    p.records.push(r);
+    if (update() > limit) { p.records.pop(); update(); break; }
+  }
+  if (!p.records.length && offset < state.records.length) error(CODES.CONTEXT_BUDGET, 'next record exceeds budget; expand with a larger token limit');
+  assertNoSecretsInText(serializePacket(p), 'context packet');
+  return p;
+}
+export function prepare(root, input, options = {}) {
+  const request = validateRequest(input);
+  const res = compileSnapshot(root, { cache: request.cache, ...options });
+  if (res.errors.length) error(CODES.CONTEXT_COMPILE, res.errors.map(e => e.message).join('\n'));
+  const selected = collect(res, request);
+  const snapshot = { inputHash: res.stats.inputHash, compiler: res.graph.compiler, graphHash: hash(res.graph) };
+  const identity = { snapshot, request, records: selected.records, logicalRecords: selected.records, scope: selected.scope, coverage: selected.coverage };
+  assertNoSecretsInText(JSON.stringify(identity), 'context state');
+  const id = hash(identity);
+  const state = { identity, id, snapshot, request, ...selected };
+  const packet = packetPage(state, 0, request.budget.tokens);
+  save(root, id, state);
+  return packet;
+}
+export function expand(root, request) {
+  closed(request, ['packet', 'offset', 'tokens'], 'expand');
+  const state = load(root, request.packet);
+  const offset = request.offset ?? 0, tokens = request.tokens ?? state.request.budget.tokens;
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > state.records.length || !Number.isSafeInteger(tokens) || tokens < 256 || tokens > 1000000) error(CODES.CONTEXT_REQUEST, 'invalid offset or token limit');
+  const res = compileSnapshot(root, { cache: state.request.cache });
+  if (res.errors.length || hash(res.graph) !== state.snapshot.graphHash || JSON.stringify(observationFreshness(res.graph.observations).filter(f => f.stale).map(f => f.id)) !== JSON.stringify(state.coverage.staleObservations)) error(CODES.CONTEXT_STALE, 'snapshot changed; use refresh or prepare');
+  return packetPage(state, offset, tokens);
+}
+export function refresh(root, request) {
+  closed(request, ['packet', 'acknowledged', 'reset'], 'refresh');
+  const previous = load(root, request.packet);
+  if (request.reset !== undefined && typeof request.reset !== 'boolean') error(CODES.CONTEXT_REQUEST, 'reset must be boolean');
+  if (request.acknowledged !== undefined && (!Array.isArray(request.acknowledged) || request.acknowledged.some(x => typeof x !== 'string'))) error(CODES.CONTEXT_REQUEST, 'acknowledged must be record IDs');
+  const known = new Set(request.reset ? [] : request.acknowledged || []);
+  for (const id of known) if (!(previous.logicalRecords || previous.records).some(r => r.id === id)) error(CODES.CONTEXT_REQUEST, 'acknowledged ID is not in the previous packet');
+  const initial = prepare(root, previous.request);
+  const current = load(root, initial.packet);
+  const old = new Map((previous.logicalRecords || previous.records).filter(r => known.has(r.id)).map(r => [r.id, r]));
+  const currentIds = new Set(current.records.map(r => r.id));
+  const records = current.records.filter(r => r.critical || !old.has(r.id) || old.get(r.id).version !== r.version);
+  for (const [id, r] of old) if (!currentIds.has(id)) records.push(record('retraction', r.subject, id, { id, previousVersion: r.version }, [], true));
+  const state = { ...current, records };
+  // A delta is itself addressed and can be paged; acknowledge only IDs delivered.
+  state.identity = { base: previous.id, snapshot: current.snapshot, request: current.request, records, logicalRecords: current.logicalRecords || current.records, scope: current.scope, coverage: current.coverage };
+  state.id = hash(state.identity); save(root, state.id, state);
+  return packetPage(state, 0, current.request.budget.tokens);
+}
+export function forget(root, packet) {
+  load(root, packet); fs.unlinkSync(path.join(storeDir(root), packet + '.json'));
+}

package/core/context/symbols.mjs

@@ -0,0 +1,81 @@
+import { CODES } from "../codes.mjs";
+// On-demand lexical experiment. These are source navigation candidates, never
+// complete call/dependency analysis and never grounds for removing checks.
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { canonicalPath } from "../paths.mjs";
+
+function reject(message) { throw Object.assign(new Error(message), { code: CODES.SYMBOL_REQUEST }); }
+// Preserve source offsets while hiding comments and quoted text. Interpolated
+// template expressions and regex literals are deliberately unsupported.
+function codeOnly(text) {
+  let out = "", state = "code";
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i], next = text[i + 1];
+    if (state === "code") {
+      if (c === "/" && next === "/") { state = "line"; out += "  "; i++; }
+      else if (c === "/" && next === "*") { state = "block"; out += "  "; i++; }
+      else if (c === "'" || c === '"' || c === "`") { state = c; out += " "; }
+      else out += c;
+    } else if (state === "line") {
+      out += c === "\n" ? "\n" : " ";
+      if (c === "\n") state = "code";
+    } else if (state === "block") {
+      if (c === "*" && next === "/") { state = "code"; out += "  "; i++; }
+      else out += c === "\n" ? "\n" : " ";
+    } else if (c === "\\") {
+      out += " ";
+      if (next !== undefined) { out += next === "\n" ? "\n" : " "; i++; }
+    } else {
+      out += c === "\n" ? "\n" : " ";
+      if (c === state) state = "code";
+    }
+  }
+  return out;
+}
+
+export function indexTypeScriptSymbols(root, files) {
+  if (!Array.isArray(files) || !files.length || files.some((f) => typeof f !== "string")) reject("files must be a nonempty list of TypeScript paths");
+  const base = fs.realpathSync(root);
+  const paths = files.map((file) => {
+    const rel = canonicalPath(file);
+    if (rel === null || !/\.(?:[cm]?ts|tsx)$/.test(rel)) reject("only repository-relative TypeScript files are supported");
+    return rel;
+  });
+  const sources = [...new Set(paths)].sort().map((file) => {
+    let absolute, source;
+    try {
+      absolute = fs.realpathSync(path.join(base, file));
+      if (!absolute.startsWith(base + path.sep)) reject("source escapes repository");
+      source = fs.readFileSync(absolute, "utf8");
+    } catch (e) {
+      if (e.code === CODES.SYMBOL_REQUEST) throw e;
+      reject("source unavailable: " + file);
+    }
+    const clean = codeOnly(source);
+    const declarations = [];
+    const pattern = /\b(export\s+)?(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(function|class|interface|type|enum|const|let|var)\s+([A-Za-z_$][\w$]*)/g;
+    for (const match of clean.matchAll(pattern)) {
+      const offset = match.index + match[0].lastIndexOf(match[3]);
+      const before = source.slice(0, offset);
+      declarations.push({ name: match[3], kind: match[2], exported: Boolean(match[1]),
+        line: before.split("\n").length, column: offset - before.lastIndexOf("\n") });
+    }
+    return { path: file, sha256: createHash("sha256").update(source).digest("hex"), declarations, clean };
+  });
+  const names = new Set(sources.flatMap((s) => s.declarations.map((d) => d.name)));
+  const indexed = sources.map(({ clean, ...file }) => {
+    const references = [];
+    for (const match of clean.matchAll(/[A-Za-z_$][\w$]*/g)) {
+      if (!names.has(match[0])) continue;
+      const before = clean.slice(0, match.index);
+      const line = before.split("\n").length, column = match.index - before.lastIndexOf("\n");
+      const declaration = file.declarations.some((d) => d.line === line && d.column === column);
+      if (!declaration) references.push({ name: match[0], line, column });
+    }
+    return { ...file, references };
+  });
+  return { schemaVersion: "agentdoc.dev/symbol-candidates/v1", coverage: { partial: true, checkSelection: "unchanged",
+    limitations: ["lexical candidates only; scope, imports and overloads are not resolved", "dynamic uses, template interpolation and regex literals are not resolved", "coverage is restricted to the explicitly requested files"] }, files: indexed };
+}

package/core/descriptors.mjs

@@ -297,6 +297,7 @@ export function loadDescriptors(repo, cfg, bundle, refs) {
           throw new AgentDocError(CODES.PATH_UNRESOLVED, "context link does not resolve: " + p, { path: e.file, ref: e.ref });
         }
       }
+      if (e.kind === "Resource" && spec.migrationPaths) checkMigrationPaths(repo, e);
       if (e.kind === "API") {
         const prov = spec.provider;
         if (!refs.isValidRef(prov) || refs.kindOfRef(prov) !== "Component") {
@@ -335,9 +336,57 @@ export function loadDescriptors(repo, cfg, bundle, refs) {
     }, errors);
   }
 
+  // One directory migrates one database. Two Resources declaring the same path
+  // would make every migration under it ambiguous, and impact must not pick.
+  // Nested declarations are fine: the longest prefix wins, as for ownership.
+  const declaredBy = new Map();
+  for (const e of entities) {
+    if (e.kind !== "Resource") continue;
+    for (const p of e.doc.spec?.migrationPaths || []) {
+      if (!declaredBy.has(p)) declaredBy.set(p, []);
+      declaredBy.get(p).push(e);
+    }
+  }
+  for (const [p, owners] of [...declaredBy.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    if (owners.length < 2) continue;
+    const names = owners.map((o) => o.ref).sort();
+    errors.push(new AgentDocError(
+      CODES.MIGRATION_PATH,
+      "migration path " + JSON.stringify(p) + " is declared by several Resources (" + names.join(", ") + "); a migration directory migrates one logical database",
+      { path: owners[0].file, ref: names[0] }
+    ));
+  }
+
   return { entities, byRef, byKindName, componentFiles: new Set(componentFiles), errors, componentSet, centralSet };
 }
 
+// `spec.migrationPaths` on a Resource: repository directories (or files) whose
+// changes are changes to this database. They are whole-segment prefixes with
+// the semantics of `core/paths.mjs`, never globs: a glob would need an engine
+// this system does not ship, and `drizzle/**` means nothing a prefix does not.
+function checkMigrationPaths(repo, e) {
+  if (e.doc.spec.type !== "logical-database") {
+    throw new AgentDocError(
+      CODES.MIGRATION_PATH,
+      "spec.migrationPaths is only meaningful on a logical-database Resource, not on type '" + e.doc.spec.type + "'",
+      { path: e.file, ref: e.ref }
+    );
+  }
+  for (const p of e.doc.spec.migrationPaths) {
+    assertRepoPath(p, e.file);
+    if (/[*?[\]{}!]/.test(p)) {
+      throw new AgentDocError(
+        CODES.MIGRATION_PATH,
+        "migration path " + JSON.stringify(p) + " is a glob; declare the directory itself (e.g. \"" + p.replace(/\/?[^/]*[*?[\]{}!].*$/, "") + "\"), which covers everything below it",
+        { path: e.file, ref: e.ref }
+      );
+    }
+    if (!repo.exists(p)) {
+      throw new AgentDocError(CODES.PATH_UNRESOLVED, "migration path does not resolve: " + p, { path: e.file, ref: e.ref });
+    }
+  }
+}
+
 export function loadJourneys(repo, cfg, bundle, byRef) {
   const errors = [];
   const jPath = cfg.discovery.journeyDefinitions;

package/core/fsx.mjs

@@ -70,11 +70,19 @@ export class Repo {
     this.root = path.resolve(root);
     this.readPaths = new Map();
     this.probes = new Map();
+    this.probeRecords = new Map();
     this.walks = new Map();
+    this.walkInputs = new Map();
     this.listings = new Map();
     this.nestedUnitRoots = new Map();
     this.generatedDirs = new Set(opts.generatedDirs || DEFAULT_GENERATED_DIRS);
     this.noGit = Boolean(opts.noGit);
+    this.snapshotReads = Boolean(opts.snapshotReads);
+    this.byteCache = new Map();
+    this.textCache = new Map();
+    this.jsonCache = new Map();
+    this.parseCache = opts.parseCache;
+    this.metrics = { physicalReads: 0, bytesRead: 0, readCacheHits: 0, jsonParses: 0, jsonCacheHits: 0, sharedJsonHits: 0 };
     // Per-Repo git caches. undefined = not asked yet; null = no answer.
     this._hasGit = undefined;
     this._prefix = undefined;
@@ -148,15 +156,18 @@ export class Repo {
   exists(rel) {
     const r = !this.isIgnored(rel) && fs.existsSync(this.abs(rel));
     this.probes.set(rel, r);
+    this.probeRecords.set("exists:" + rel, { kind: "exists", path: rel, value: r });
     return r;
   }
   isDir(rel) {
     try {
       const r = !this.isIgnored(rel) && fs.statSync(this.abs(rel)).isDirectory();
       this.probes.set(rel, r);
+      this.probeRecords.set("isDir:" + rel, { kind: "isDir", path: rel, value: r });
       return r;
     } catch {
       this.probes.set(rel, false);
+      this.probeRecords.set("isDir:" + rel, { kind: "isDir", path: rel, value: false });
       return false;
     }
   }
@@ -172,9 +183,15 @@ export class Repo {
         { path: rel }
       );
     }
-    let buf;
+    let buf = this.snapshotReads ? this.byteCache.get(rel) : undefined;
+    if (buf) this.metrics.readCacheHits++;
     try {
-      buf = fs.readFileSync(a);
+      if (!buf) {
+        buf = fs.readFileSync(a);
+        this.metrics.physicalReads++;
+        this.metrics.bytesRead += buf.length;
+        if (this.snapshotReads) this.byteCache.set(rel, buf);
+      }
     } catch {
       throw new AgentDocError(CODES.PATH_UNRESOLVED, "path does not resolve inside the repository: " + rel, { path: rel });
     }
@@ -183,6 +200,7 @@ export class Repo {
   }
   readText(rel, opts = {}) {
     const buf = this.readBytes(rel, opts);
+    if (this.snapshotReads && this.textCache.has(rel)) return this.textCache.get(rel);
     let text;
     try {
       text = new TextDecoder("utf-8", { fatal: true }).decode(buf);
@@ -190,10 +208,26 @@ export class Repo {
       throw new AgentDocError(CODES.UTF8, "file is not valid UTF-8: " + rel, { path: rel });
     }
     if (text.startsWith("")) text = text.slice(1);
+    if (this.snapshotReads) this.textCache.set(rel, text);
     return text;
   }
   readJson(rel) {
-    return JSON.parse(this.readText(rel));
+    const text = this.readText(rel);
+    if (this.snapshotReads && this.jsonCache.has(rel)) {
+      this.metrics.jsonCacheHits++;
+      return structuredClone(this.jsonCache.get(rel));
+    }
+    const shared = this.parseCache?.get(text);
+    if (shared !== undefined) {
+      this.metrics.sharedJsonHits++;
+      if (this.snapshotReads) this.jsonCache.set(rel, structuredClone(shared));
+      return shared;
+    }
+    this.metrics.jsonParses++;
+    const value = JSON.parse(text);
+    this.parseCache?.set(text, value);
+    if (this.snapshotReads) this.jsonCache.set(rel, structuredClone(value));
+    return value;
   }
   readJsonUntracked(rel) {
     return JSON.parse(this.readText(rel, { track: false }));
@@ -215,6 +249,10 @@ export class Repo {
         continue;
       }
       entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+      if (this.snapshotReads) {
+        const rel = path.relative(this.root, dir).split(path.sep).join("/") || ".";
+        this.walkInputs.set(rel, this.directoryState(rel, entries));
+      }
       for (const ent of entries) {
         if (this.generatedDirs.has(ent.name)) continue;
         const full = path.join(dir, ent.name);
@@ -232,6 +270,15 @@ export class Repo {
     this.walks.set(relDir || ".", out);
     return out;
   }
+  // Raw visited-directory state, independent of extractor filter closures.
+  // Those closures may depend on discovery state which evolves during compile.
+  directoryState(relDir, entries = fs.readdirSync(this.abs(relDir), { withFileTypes: true })) {
+    const prefix = relDir && relDir !== "." ? relDir + "/" : "";
+    return entries
+      .filter(e => !this.generatedDirs.has(e.name) && !this.isIgnored(prefix + e.name))
+      .map(e => [e.name, e.isSymbolicLink() ? "link" : e.isDirectory() ? "dir" : "file"])
+      .sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+  }
   // Per-unit scans use the discovery result, never filesystem heuristics.
   // Keep walk() repository-wide for discovery, contracts and authored inputs.
   ownsUnitPath(unitRoot, rel) {

package/core/graph.mjs

@@ -9,7 +9,7 @@ import { assertDeterministic, structuralProjection } from "./determinism.mjs";
 import { sha256Hex } from "./fsx.mjs";
 
 export const COMPILER_NAME = "agentdoc-compiler";
-export const COMPILER_VERSION = "1.3.0";
+export const COMPILER_VERSION = "1.5.0";
 export const GRAPH_SCHEMA_VERSION = "agentdoc.dev/graph/v1";
 
 // Resolve symbolic provenance subjects to RFC 6901 pointers into the graph.

package/core/impact.mjs

@@ -5,7 +5,7 @@
 // from the graph alone, so the answer is available before any exploration.
 import { ContextIndex } from "./query.mjs";
 import { dependentScope, verificationForChange } from "./dependents.mjs";
-import { canonicalPath, ownsPath } from "./paths.mjs";
+import { canonicalPath, ownsPath, longestOwner } from "./paths.mjs";
 
 // Changed paths are compared in the graph's canonical form (git's: no "./").
 // A path that is not repository-relative is kept verbatim so it is reported
@@ -23,7 +23,10 @@ const canonical = (p) => canonicalPath(p) ?? p;
 //   - every extractor identity, which names the technology        -> dependency /
 //                                                                    verification
 //   - every documentation and constraint path on an entity         -> documentation
-function classify(graph, p, idx) {
+//   - every migration directory: declared on a logical-database    -> resource
+//     Resource (`spec.migrationPaths`), or detected per component
+//     by the database adapter (`derived.migrationDirs`)
+function classify(graph, p, idx, migrations) {
   for (const c of graph.contracts) if (c.ref === p) return "contract";
   for (const e of graph.entities) {
     const d = e.derived || {};
@@ -32,6 +35,13 @@ function classify(graph, p, idx) {
     for (const x of d.runbooks || []) if (x === p) return "documentation";
   }
   if (/\.(md|mdx|adoc|rst|txt)$/.test(p)) return "documentation";
+  if (migrationHit(migrations, p)) return "resource";
+  // Kept as a fallback, and the one name-based rule left: before the graph
+  // recorded migration directories this regex was the whole classification,
+  // and it still has to answer where nothing is recorded — a repository that
+  // does not enable the database adapter, a migration directory deeper than
+  // the adapter's bounded walk, a graph built by hand. Dropping it would change
+  // the answer for those repositories; what the graph records only adds to it.
   if (/(^|\/)(migrations?|alembic\/versions)\//.test(p)) return "resource";
   // A Resource named directly — by ref, or by the descriptor file that declares
   // it — is a resource change. Without this, `impact resource:default/x` reported
@@ -46,8 +56,43 @@ function classify(graph, p, idx) {
   return null;
 }
 
+// Migration directories recorded in the graph, with what made them one.
+function migrationDirs(graph) {
+  const declared = new Map(); // path -> Resource ref
+  const detected = new Map(); // path -> { componentRef, via }
+  for (const e of graph.entities) {
+    if (e.kind === "Resource") {
+      for (const p of e.entity?.spec?.migrationPaths || []) declared.set(p, e.ref);
+    }
+    if (e.kind === "Component") {
+      for (const d of e.derived?.migrationDirs || []) detected.set(d.path, { componentRef: e.ref, via: d.via || [] });
+    }
+  }
+  return { declared, detected };
+}
+
+// The migration directory a path is under, by whole path segments, the most
+// specific first. An authored declaration beats a detected directory: it names
+// the database, where detection only names the component whose bindings say
+// which database it is.
+function migrationHit(migrations, p) {
+  if (!migrations) return null;
+  const d = longestOwner(migrations.declared.keys(), p);
+  if (d) return { dir: d, resourceRef: migrations.declared.get(d), how: "declared on " + migrations.declared.get(d) };
+  const x = longestOwner(migrations.detected.keys(), p);
+  if (!x) return null;
+  const { componentRef, via } = migrations.detected.get(x);
+  // A directory found by its conventional name is exactly what the fallback
+  // regex already classified; only a directory nothing but the graph knows
+  // about is worth a reason of its own.
+  const conventional = via.every((v) => v === "directory-name" || v === "alembic-versions");
+  return { dir: x, componentRef, conventional, how: "detected from " + via.join(", ") + " in " + componentRef };
+}
+
 export function impact(graph, changedPaths) {
   const idx = new ContextIndex(graph);
+  const migrations = migrationDirs(graph);
+  const migrationReasons = new Map(); // Resource ref -> Set(reason)
   const affectedComponents = new Map(); // ref -> Set(reason)
   const add = (ref, reason) => {
     if (idx.byRef.get(ref)?.kind !== "Component") return;
@@ -72,18 +117,35 @@ export function impact(graph, changedPaths) {
     // while the components actually bound to it went unmentioned.
     if (entity && entity.kind === "Component") add(entity.ref, "direct file change inside " + entity.ref);
     else unmatched.push(p);
-    const kind = classify(graph, p, idx);
+    const kind = classify(graph, p, idx, migrations);
     if (kind === "contract") contracts.add(p);
     if (kind === "documentation") docs.add(p);
     if (kind === "resource") {
-      resources.add(entity?.kind === "Resource" ? entity.ref : p);
-      // Migration authority is not ownership. Only follow an existing binding
-      // from the component containing this migration to a logical database.
-      if (entity?.kind === "Component") {
-        for (const rel of graph.relations) {
-          const bound = rel.type === "usesResource" && rel.sourceRef === entity.ref ? rel.targetRef
-            : rel.type === "resourceUsedBy" && rel.targetRef === entity.ref ? rel.sourceRef : null;
-          if (idx.byRef.get(bound)?.entity.spec.type === "logical-database") resources.add(bound);
+      const hit = migrationHit(migrations, p);
+      const because = (ref) => {
+        if (!hit || hit.conventional) return;
+        if (!migrationReasons.has(ref)) migrationReasons.set(ref, new Set());
+        migrationReasons.get(ref).add("migration " + p + " changes " + ref + " (migration directory " + hit.dir + ", " + hit.how + ")");
+      };
+      if (hit?.resourceRef) {
+        // Authored: the declaration names the database, whichever component
+        // owns the file and whatever that component is bound to.
+        resources.add(hit.resourceRef);
+        because(hit.resourceRef);
+      } else {
+        resources.add(entity?.kind === "Resource" ? entity.ref : p);
+        // Migration authority is not ownership. Only follow an existing binding
+        // from the component containing this migration to a logical database.
+        const owner = hit?.componentRef ?? (entity?.kind === "Component" ? entity.ref : null);
+        if (owner) {
+          for (const rel of graph.relations) {
+            const bound = rel.type === "usesResource" && rel.sourceRef === owner ? rel.targetRef
+              : rel.type === "resourceUsedBy" && rel.targetRef === owner ? rel.sourceRef : null;
+            if (idx.byRef.get(bound)?.entity.spec.type === "logical-database") {
+              resources.add(bound);
+              because(bound);
+            }
+          }
         }
       }
     }
@@ -135,6 +197,7 @@ export function impact(graph, changedPaths) {
       const user = rel.type === "usesResource" ? rel.sourceRef : rel.targetRef;
       if (r === bound) {
         add(user, "resource change touches " + bound);
+        for (const reason of migrationReasons.get(bound) || []) add(user, reason);
       }
     }
   }