agent-doc-system 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -9,6 +9,58 @@ refused by the next with `AGENTDOC_COMPILER_MISMATCH` until it is recompiled.
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-11-10
+
+`impact` now treats a change under a Drizzle migration directory as a change
+to the database it migrates. It reaches every component bound to that
+database, not only the component that holds the file. Any other ORM layout can
+be declared on the database Resource with the new `spec.migrationPaths`.
+Existing `migrations/` and `alembic/versions/` paths give the same answer as
+before.
+
+Before you upgrade:
+
+- **Recompile committed graphs.** As with every release, a graph compiled by
+  1.3.0 is refused with `AGENTDOC_COMPILER_MISMATCH` until you run
+  `agentdoc compile` again. Graphs of repositories that enable the `database`
+  adapter also gain `derived.migrationDirs` and the provenance behind it.
+- **A Drizzle config whose `out` is not a plain string** (an environment
+  variable, an expression, a spread) now raises the warning
+  `AGENTDOC_MIGRATION_DIR_UNRESOLVED`. Declare the directory with
+  `spec.migrationPaths`, or accept the warning ([#63]).
+
+### Added
+
+- A `logical-database` Resource can declare where its schema migrations live,
+  with `spec.migrationPaths` ([#63]). A change under a declared directory is a
+  change to that Resource, whichever component owns the file, so `impact`
+  reaches every component bound to the database. Paths are whole-segment
+  prefixes, not globs: `frontend/apps/web/drizzle` covers `0036_x.sql` and
+  `meta/_journal.json`, and never `drizzle-extra/`. A glob, a declaration on
+  another Resource type, or one path declared by two Resources fails with the
+  new `AGENTDOC_MIGRATION_PATH`; a path outside the repository fails with
+  `AGENTDOC_PATH_ESCAPE`, a missing one with `AGENTDOC_PATH_UNRESOLVED`. The
+  declaration never creates a binding.
+
+### Fixed
+
+- `impact` now classifies a change under a Drizzle migration directory as a
+  database change ([#63]). Only `migrations/`, `migration/` and
+  `alembic/versions/` used to count, so `impact
+  frontend/apps/web/drizzle/0036_email_locale.sql` reported the web component
+  alone and missed every other component bound to the same database. The
+  `database` adapter now reads Drizzle Kit's `out` from `drizzle.config.ts`
+  (`.js`, `.mjs`) as a string literal, without running it, and defaults to
+  `./drizzle`. An `out` it cannot read statically is reported with the
+  acceptable warning `AGENTDOC_MIGRATION_DIR_UNRESOLVED` instead of being
+  guessed. Detected directories, including `migrations` and `alembic/versions`,
+  are recorded in the graph as `derived.migrationDirs` with provenance, and
+  `impact` classifies from them. A detected directory still reaches a database
+  only through the component's existing bindings. The answer for an existing
+  `migrations/` or `alembic/versions/` path is unchanged. Committed graphs of
+  repositories that enable the `database` adapter gain `migrationDirs` and
+  must be recompiled.
+
 ## [1.3.0] - 2026-11-07
 
 A graph compiled on your machine now passes `check` in CI and in a clean
@@ -367,7 +419,8 @@ First public release.
   for project health.
 - An Agent Skill under `skills/agent-doc-system/`.
 
-[Unreleased]: https://github.com/lbframe/agent-doc-system/compare/v1.3.0...HEAD
+[Unreleased]: https://github.com/lbframe/agent-doc-system/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/lbframe/agent-doc-system/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/lbframe/agent-doc-system/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/lbframe/agent-doc-system/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/lbframe/agent-doc-system/compare/v1.0.0...v1.1.0
@@ -400,3 +453,4 @@ First public release.
 [#51]: https://github.com/lbframe/agent-doc-system/issues/51
 [#55]: https://github.com/lbframe/agent-doc-system/issues/55
 [#59]: https://github.com/lbframe/agent-doc-system/issues/59
+[#63]: https://github.com/lbframe/agent-doc-system/issues/63

package/adapters/database.mjs

@@ -9,7 +9,7 @@
 //     library shipped migrations but explicitly did not own a database.
 import { Adapter } from "./registry.mjs";
 import { firstExistingFile, findMigrationDirs } from "../core/sourcescan.mjs";
-import { joinPath } from "../core/paths.mjs";
+import { canonicalPath, joinPath } from "../core/paths.mjs";
 
 const ORM_CONFIG = [
   "drizzle.config.ts", "drizzle.config.js", "drizzle.config.mjs",
@@ -48,6 +48,12 @@ export class DatabaseAdapter extends Adapter {
       }
     }
     const pr = prov.add("observed", evidencePath, "migration-extractor", ["der:" + compRef + ":/bindings"]);
+    // Where this unit's migrations live, recorded in the graph so `impact`
+    // classifies a change from the graph rather than from a list of names.
+    // Authority over a directory, never ownership of a database: these records
+    // create no binding.
+    const recorded = recordMigrationDirs(ctx, unit, migrationDirs, ormConfig, pr);
+    const withDirs = (out) => (recorded.length ? { ...out, migrationDirs: recorded } : out);
 
     // A component that both migrates and opens a connection owns the database.
     const opensConnection = hasConnectionEvidence(ctx, unit);
@@ -66,7 +72,7 @@ export class DatabaseAdapter extends Adapter {
         evidenceClass: "DERIVED", confidence: "candidate", provRecs: [pr],
         semantics: "a schema exists here, but which component owns the logical database is unresolved",
       });
-      return { migrationAuthority: evidencePath };
+      return withDirs({ migrationAuthority: evidencePath });
     }
 
     const name = compRef.split("/")[1];
@@ -89,7 +95,7 @@ export class DatabaseAdapter extends Adapter {
         evidenceClass: "DERIVED", confidence: "candidate", provRecs: [pr],
         semantics: "this component opens a database connection, but no authored Resource claims ownership",
       });
-      return { migrationAuthority: evidencePath };
+      return withDirs({ migrationAuthority: evidencePath });
     }
     ctx.addFact(compRef, "resource.ownership", target.name, {
       evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
@@ -101,10 +107,10 @@ export class DatabaseAdapter extends Adapter {
     const client = ctx.clientKeyForResourceType("logical-database");
     const attrs = client ? { via: "migrations+connection", client } : { via: "migrations+connection" };
     ctx.addEdge("usesResource", compRef, target.ref, attrs, [pr], "DERIVED");
-    return {
+    return withDirs({
       migrationAuthority: evidencePath,
       bindings: [{ kind: "database", logicalResourceRef: target.ref, resolution: "resolved", provenanceIds: null, _provs: new Set([pr]) }],
-    };
+    });
   }
 }
 
@@ -129,3 +135,145 @@ function findDatabaseResource(ctx, name) {
   );
   return cands.length === 1 ? cands[0] : null;
 }
+
+// ── migration directories ───────────────────────────────────────────────────
+//
+// Two routes, each with its own evidence:
+//   - a directory named by convention (`migrations`, `migration`,
+//     `alembic/versions`), evidenced by a file inside it;
+//   - Drizzle Kit's `out`, evidenced by the config file that states it.
+// Prisma Migrate writes to `prisma/migrations`, which the first route covers.
+function recordMigrationDirs(ctx, unit, conventionDirs, ormConfig, pr) {
+  const { repo, prov, compRef } = ctx;
+  const subject = "der:" + compRef + ":/migrationDirs";
+  const byPath = new Map();
+  const add = (dir, via, rec) => {
+    if (!byPath.has(dir)) byPath.set(dir, { path: dir, via: new Set(), _provs: new Set() });
+    byPath.get(dir).via.add(via);
+    byPath.get(dir)._provs.add(rec);
+  };
+  for (const dir of conventionDirs) {
+    // A directory with no file in the input set has nothing a change could
+    // touch, and nothing to cite as evidence.
+    const file = repo.walkUnit(unit.root, dir)[0];
+    if (!file) continue;
+    let rec;
+    if (file === pr.path) {
+      rec = pr;
+      pr.subjects.add(subject);
+    } else {
+      rec = prov.add("observed", file, "migration-extractor", [subject]);
+    }
+    add(dir, /(^|\/)alembic\/versions$/.test(dir) ? "alembic-versions" : "directory-name", rec);
+  }
+  if (ormConfig && /(^|\/)drizzle\.config\.[cm]?[jt]s$/.test(ormConfig)) {
+    const dir = drizzleOutDir(ctx, unit, ormConfig);
+    if (dir) add(dir, "drizzle-config", prov.add("observed", ormConfig, "drizzle-config-extractor", [subject]));
+  }
+  return [...byPath.values()]
+    .sort((a, b) => (a.path < b.path ? -1 : 1))
+    .map((d) => ({ path: d.path, via: [...d.via].sort(), provenanceIds: null, _provs: d._provs }));
+}
+
+// Drizzle Kit writes migrations to `out`, `./drizzle` when absent. The config
+// is code, and it is never executed: only a string literal is read. Anything
+// else — an expression, an environment variable, a spread that could carry
+// `out`, several `out` keys — is reported and not guessed, because a wrong
+// directory would route migrations to the wrong database silently.
+function drizzleOutDir(ctx, unit, configPath) {
+  const { repo, compRef } = ctx;
+  const unresolved = (why) => {
+    ctx.diagnostics.push({
+      severity: "warning",
+      code: "AGENTDOC_MIGRATION_DIR_UNRESOLVED",
+      subject: compRef,
+      refs: [compRef],
+      message:
+        "Drizzle migration directory in '" + configPath + "' is not recorded: " + why + ". " +
+        "Declare it with spec.migrationPaths on the logical-database Resource it migrates",
+      paths: [configPath],
+    });
+    return null;
+  };
+  const parsed = drizzleOut(repo.readText(configPath));
+  if (parsed.error) return unresolved(parsed.error);
+  const value = parsed.value ?? "./drizzle";
+  // Relative to the directory drizzle-kit runs from, which is the config's own
+  // directory in the documented layout (and the unit root here).
+  const base = configPath.includes("/") ? configPath.slice(0, configPath.lastIndexOf("/")) : ".";
+  const dir = value.startsWith("/") ? null : canonicalPath(joinPath(base, value));
+  if (!dir || dir === "." || dir === canonicalPath(unit.root)) {
+    return unresolved("out " + JSON.stringify(value) + " is not a directory inside the unit at '" + unit.root + "'");
+  }
+  if (!repo.ownsUnitPath(unit.root, dir)) {
+    return unresolved("out " + JSON.stringify(value) + " is outside the unit at '" + unit.root + "'");
+  }
+  // Not generated yet: nothing to classify. The probe is an input, so the
+  // first generated migration invalidates the graph.
+  if (!repo.isDir(dir)) return null;
+  return dir;
+}
+
+// Static read of `out` from a Drizzle config. Comments are removed and string
+// literals set aside first, so neither `// out: "x"` nor a string containing
+// "out:" is mistaken for the key.
+export function drizzleOut(text) {
+  const strings = [];
+  let code = "";
+  for (let i = 0; i < text.length; ) {
+    const c = text[i];
+    if (c === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2);
+      i = end < 0 ? text.length : end + 2;
+      code += " ";
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      let j = i + 1;
+      let value = "";
+      let closed = false;
+      while (j < text.length) {
+        if (text[j] === "\\") {
+          value += text[j + 1] ?? "";
+          j += 2;
+          continue;
+        }
+        if (text[j] === c) { closed = true; break; }
+        if (c !== "`" && text[j] === "\n") break;
+        value += text[j];
+        j++;
+      }
+      if (!closed) return { error: "the config could not be read statically" };
+      // A template with a substitution is an expression, not a literal.
+      strings.push(c === "`" && value.includes("${") ? null : value);
+      code += "\u0000" + (strings.length - 1) + "\u0000";
+      i = j + 1;
+      continue;
+    }
+    code += c;
+    i++;
+  }
+  const hits = [];
+  for (const m of code.matchAll(/(?:^|[{,\s])(?:out|\u0000(\d+)\u0000)\s*(:|[,}])/g)) {
+    // A quoted key counts only when it says "out".
+    if (m[1] !== undefined && strings[Number(m[1])] !== "out") continue;
+    hits.push(m);
+  }
+  if (hits.length === 0) {
+    // A spread could bring `out` in from elsewhere; the default is then a guess.
+    if (/\.\.\.\s*[A-Za-z_$(]/.test(code)) return { error: "the config spreads another object that may set out" };
+    return { value: null };
+  }
+  if (hits.length > 1) return { error: "out is set more than once" };
+  const m = hits[0];
+  if (m[2] !== ":") return { error: "out is a shorthand property, not a string literal" };
+  const rest = code.slice(m.index + m[0].length);
+  const lit = /^\s*\u0000(\d+)\u0000\s*(?:[,}]|$)/.exec(rest);
+  const value = lit ? strings[Number(lit[1])] : null;
+  if (typeof value !== "string" || value.trim() === "") return { error: "out is not a string literal" };
+  return { value };
+}

package/core/codes.mjs

@@ -23,6 +23,7 @@ export const CODES = {
   GLOB: "AGENTDOC_GLOB",
   PATH_ESCAPE: "AGENTDOC_PATH_ESCAPE",
   PATH_UNRESOLVED: "AGENTDOC_PATH_UNRESOLVED",
+  MIGRATION_PATH: "AGENTDOC_MIGRATION_PATH",
   SECRET: "AGENTDOC_SECRET",
 
   // identity & references
@@ -98,6 +99,7 @@ export const ACCEPTABLE_WARNING_CODES = Object.freeze([
   "AGENTDOC_NORMATIVE_UNCOVERED",
   "AGENTDOC_REQUIREMENT_UNVERIFIED",
   "AGENTDOC_PYTHON_SPECIFIER",
+  "AGENTDOC_MIGRATION_DIR_UNRESOLVED",
 ]);
 
 export class AgentDocError extends Error {

package/core/compile.mjs

@@ -498,6 +498,10 @@ export function compile(root, opts = {}) {
       "entf:" + e.ref + ":/metadata/description",
     ];
     if (e.doc.spec !== undefined) subjects.push("entf:" + e.ref + ":/spec");
+    // A declared migration path is the one authored path whose meaning reaches
+    // past the descriptor (impact routes every change below it to this
+    // Resource), so it is pointed at directly rather than through `/spec`.
+    if (e.doc.spec?.migrationPaths) subjects.push("entf:" + e.ref + ":/spec/migrationPaths");
     prov.add("declared", e.file, "descriptor-reader", subjects);
   }
 
@@ -777,7 +781,7 @@ export function compile(root, opts = {}) {
     return earlyOut(res, { entities: sources.entities.length, units: discovery.eligible.length });
   }
   for (const d of derivedMap.values()) {
-    for (const list of [d.bindings || [], d.healthContracts || []]) {
+    for (const list of [d.bindings || [], d.healthContracts || [], d.migrationDirs || []]) {
       for (const b of list) {
         b.provenanceIds = [...(b._provs || [])].map((p) => provFinal.idOf.get(p)).filter(Boolean).sort();
         delete b._provs;

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/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.4.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);
       }
     }
   }

package/docs/ADAPTERS.md

@@ -107,7 +107,7 @@ cannot name the file a fact came from, you cannot add the fact.
 | `dockerfile` | `Dockerfile`, `Containerfile` | deployable evidence |
 | `deploy-config` | `fly.toml`, `Procfile`, … | deployable evidence |
 | `wrangler` | `wrangler.toml/json` | bindings, crons, service bindings, trigger targets |
-| `database` | migrations, ORM config, pool evidence | logical-database ownership, or a candidate |
+| `database` | migrations, ORM config, pool evidence | logical-database ownership, or a candidate; the unit's migration directories |
 | `object-store` | bucket literals | logical-dataset edges, or an ambiguity |
 | `cache` | cache client evidence | cache bindings |
 | `events` | subject literals, declared constants, event-contract files | producers, consumers, reserved subjects |
@@ -312,6 +312,45 @@ the result is `AGENTDOC_BINDING_AMBIGUOUS` and no edge.
 file pulled in with `-r` / `-c`; a lockfile's resolved versions; a PDM
 workspace; a workspace manifest deeper than the search bound.
 
+### `database`
+
+Migration authority and a connection string in one unit resolve to an authored
+logical-database Resource (by name: `<component>-postgres`, `-database`,
+`-db`, or the single Resource whose name starts with the component's).
+Migrations alone give a candidate and `AGENTDOC_RESOURCE_CANDIDATE`, never an
+edge.
+
+The adapter also records where the unit's migrations live, as
+`derived.migrationDirs` (`path`, `via`, `provenanceIds`). `impact` classifies a
+change under one of them as a resource change. Two routes, each with its own
+evidence:
+
+| `via` | directory | evidence |
+|---|---|---|
+| `directory-name` | a directory named `migrations` or `migration` inside the unit, at most five levels down; Prisma Migrate's `prisma/migrations` is one | the first file in it |
+| `alembic-versions` | `alembic/versions` | the first file in it |
+| `drizzle-config` | Drizzle Kit's `out` in the unit-root `drizzle.config.ts`, `.js` or `.mjs`; `./drizzle` when `out` is absent | the config file |
+
+The Drizzle config is code and is never executed. `out` is read only as a
+single string literal (a template literal without `${...}` counts), after
+comments are removed, and resolved against the config's directory. An `out`
+that is an expression, an environment variable, a shorthand property, set more
+than once, or possibly brought in by a spread is not guessed: the adapter
+records nothing and reports `AGENTDOC_MIGRATION_DIR_UNRESOLVED`, a warning that
+can be accepted. An `out` outside the unit is reported the same way. An `out`
+directory that does not exist yet records nothing; the existence probe is an
+input, so generating the first migration invalidates the graph.
+
+A recorded directory is migration authority, not ownership: it creates no
+binding. A migration change reaches a database only through the enclosing
+component's existing `usesResource` relations, or through a Resource that
+declares the directory in `spec.migrationPaths` (see `SPEC.md`).
+
+**What it cannot see:** a Drizzle config passed with `--config` under another
+name, a config below the unit root, and the migration layouts of Knex, Goose,
+Sequelize or TypeORM outside a `migrations` directory. Declare those with
+`spec.migrationPaths`.
+
 `asyncapi` is a contract **type** (declared on an API descriptor, validated by
 the contract layer), not an adapter — there is no `asyncapi` entry in
 `adapters: [...]`.
@@ -373,9 +412,14 @@ places, and those are the honest exceptions worth naming:
   part of the input hash. A repository that does not enable `python` is not
   probed, and its graph does not change.
 - `core/impact.mjs` classifies a changed file by consulting the compiled graph —
-  its contracts, its provenance paths, its extractor identities — rather than a
-  hand-written list of technology filenames. A list would silently under-report
-  for every repository that is not Node-and-Go.
+  its contracts, its provenance paths, its extractor identities, its declared
+  and detected migration directories — rather than a hand-written list of
+  technology filenames. A list would silently under-report for every
+  repository that is not Node-and-Go. One name rule remains as a fallback: a
+  path under a `migrations/`, `migration/` or `alembic/versions/` segment is a
+  resource change even where the graph records no migration directory (the
+  `database` adapter is off, or the directory is deeper than its walk), so
+  those repositories keep the answer they had.
 - `core/discover.mjs` excludes `agentdoc`, `docs`, `scripts`, `node_modules`, and
   `.github` by default. `discovery.notUnitRoots` replaces that list (`[]`
   disables it). These roots and their descendants cannot be inferred from

package/docs/CI.md

@@ -20,7 +20,7 @@ jobs:
         with: { fetch-depth: 0 }
       - uses: actions/setup-node@v4
         with: { node-version: '24' }
-      # Pin a tag for reproducibility, e.g. github:lbframe/agent-doc-system#v1.3.0 —
+      # Pin a tag for reproducibility, e.g. github:lbframe/agent-doc-system#v1.4.0 —
       # a compiler upgrade intentionally invalidates every committed graph.
       - run: npm install -g github:lbframe/agent-doc-system
       - run: agentdoc validate
@@ -93,6 +93,8 @@ YAML or schema error names its file and line and needs no table.
 | `AGENTDOC_COMPILER_MISMATCH` | the compiler was upgraded | `compile` and commit |
 | `AGENTDOC_OVERRIDE_STALE` | a reviewed override's cited evidence changed | review the interpretation, then `pin-evidence` and update the digest |
 | `AGENTDOC_VERIFICATION_UNTIERED` | a check task has no recognisable tier | name the task, or extend the adapter |
+| `AGENTDOC_MIGRATION_PATH` | a Resource's `spec.migrationPaths` is a glob, is on a non-database Resource, or is shared by two Resources | declare the directory itself, once, on the logical database it migrates |
+| `AGENTDOC_MIGRATION_DIR_UNRESOLVED` | a Drizzle config's `out` is not a single string literal inside the unit | declare the directory with `spec.migrationPaths`, or accept the warning |
 
 ## Ordering inside `check`
 

package/docs/QUERY.md

@@ -215,10 +215,31 @@ receives the files no other component owns. A file nothing owns is listed in
 
 Reachability rules: a contract change reaches its provider and every consumer;
 a Resource change reaches components bound to that exact Resource. A migration
-change (including Alembic `alembic/versions`) reports its changed path and the
-logical databases bound to its enclosing component through existing
-`usesResource` / `resourceUsedBy` relations. Migration authority alone never
-establishes ownership or invents a Resource binding.
+change is a Resource change. Which Resource is decided from the graph, most
+specific directory first, by whole path segment (`drizzle` never matches
+`drizzle-extra/`):
+
+1. **Declared.** Under a path a logical-database Resource lists in
+   `spec.migrationPaths`: that Resource, whichever component owns the file and
+   whatever that component is bound to. An authored declaration beats a
+   detected directory.
+2. **Detected.** Under a directory the `database` adapter recorded in a
+   component's `derived.migrationDirs` (a `migrations` directory, Alembic
+   `alembic/versions`, Drizzle Kit's `out`): the logical databases bound to
+   that component through existing `usesResource` / `resourceUsedBy`
+   relations. The changed path is listed too.
+3. **By name.** Under a `migrations/`, `migration/` or `alembic/versions/`
+   segment the graph does not record (the `database` adapter is off): the same
+   as detected, from the enclosing component.
+
+Every component bound to a reached Resource is affected, with the reason
+`resource change touches <ref>`. When the directory was declared or found
+through an ORM config, a second reason names the migration:
+`migration drizzle/0001_x.sql changes resource:default/app-db (migration
+directory drizzle, detected from drizzle-config in component:default/web)`.
+Migration authority alone never establishes ownership or invents a Resource
+binding: a detected directory whose component has no binding reaches no
+Resource, and a declaration routes changes without creating a relation.
 
 A component change reaches its reverse build/test dependency closure, plus
 direct runtime-call and schedule peers. Dependencies are not affected just

package/docs/SPEC.md

@@ -77,6 +77,47 @@ authored in exactly one file, and the location is validated.
 The namespace comes from the configuration, so two repositories in one graph
 never collide.
 
+### Resource migration paths
+
+A `logical-database` Resource may list the repository directories that hold its
+schema migrations:
+
+```yaml
+apiVersion: agentdoc.dev/v1
+kind: Resource
+metadata:
+  name: app-postgres
+  description: "Primary Postgres database of the application."
+spec:
+  type: logical-database
+  system: app
+  migrationPaths:
+    - frontend/apps/web/drizzle
+```
+
+Each entry is a repository path matched as a whole-segment prefix (the rules
+of `core/paths.mjs`): `frontend/apps/web/drizzle` covers every file below it,
+including `meta/_journal.json`, and never `frontend/apps/web/drizzle-extra/`.
+`impact` treats a change under it as a change to this Resource, whichever
+component owns the file, and reaches every component bound to the Resource.
+The declaration is AUTHORED: it beats a migration directory the `database`
+adapter detects, and it is pointed at by its own provenance subject
+(`/entities/<i>/entity/spec/migrationPaths`). It never creates a
+`usesResource` relation; which components use the database is still derived.
+
+Validation, at load time:
+
+| case | code |
+|---|---|
+| absolute, backslash, `.` or `..` segment, whitespace | `AGENTDOC_PATH_ESCAPE` |
+| a path that does not exist (or is git-ignored) | `AGENTDOC_PATH_UNRESOLVED` |
+| a glob (`*`, `?`, `[`, `{`, `!`): declare the directory itself | `AGENTDOC_MIGRATION_PATH` |
+| the field on a Resource whose type is not `logical-database` | `AGENTDOC_MIGRATION_PATH` |
+| the same path declared by two Resources | `AGENTDOC_MIGRATION_PATH` |
+
+Nested declarations on different Resources are allowed; the longest prefix
+wins.
+
 ### Why no further entities
 
 A `Team`, `Milestone` or `Tag` entity was considered and rejected: none of them
@@ -142,6 +183,7 @@ least one provenance id and an evidence class.
 ```
 schemaVersion, source{commit, dirty, inputHash}, compiler{name, version, adapters}
 entities[]      ref, kind, name, entity, source, sourcePaths[], derived?
+                (derived.migrationDirs[]: path, via[], provenanceIds[])
 relations[]     type, sourceRef, targetRef, evidenceClass, attributes, provenanceIds[]
 interfaces.events[]              pattern, producers, consumers, contract, resolution
 externalDependencies[]           componentRef, name, role, mechanism, evidenceClass

package/docs/ci/github-actions.yml

@@ -21,7 +21,7 @@ jobs:
         with: { node-version: '24' }
       - name: Install the agentdoc CLI
         # Unpinned tracks main. For CI reproducibility pin a tag or commit:
-        #   github:lbframe/agent-doc-system#v1.3.0
+        #   github:lbframe/agent-doc-system#v1.4.0
         # A compiler upgrade intentionally invalidates committed graphs.
         run: npm install -g github:lbframe/agent-doc-system
       - name: Validate and compile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-doc-system",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "Portable documentation and software-catalog system with an explicit authority model, for AI coding agents",
   "keywords": [

package/schemas/resource.schema.json

@@ -16,7 +16,15 @@
         "type": { "enum": ["logical-database", "logical-dataset", "event-bus", "queue", "cache", "object-store", "search-index", "secret-store", "other"] },
         "placementRationale": { "$ref": "common.json#/$defs/rationale" },
         "system": { "$ref": "common.json#/$defs/name" },
-        "context": { "$ref": "common.json#/$defs/context" }
+        "context": { "$ref": "common.json#/$defs/context" },
+        "migrationPaths": {
+          "description": "Repository directories (or files) holding this logical database's schema migrations, matched as whole-segment path prefixes. Authoritative for change impact: a change under one of them is a change to this Resource, whichever component owns the file. Never a binding: which components use the database is still derived. Only a logical-database may declare them.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": { "$ref": "common.json#/$defs/repoPath" }
+        }
       },
       "oneOf": [
         { "required": ["system"] },

package/templates/ci.yml

@@ -17,7 +17,7 @@ jobs:
         with: { node-version: '24' }
       - name: Install the agentdoc CLI
         # Unpinned tracks main. For CI reproducibility pin a tag or commit:
-        #   github:lbframe/agent-doc-system#v1.3.0
+        #   github:lbframe/agent-doc-system#v1.4.0
         # A compiler upgrade intentionally invalidates committed graphs.
         run: npm install -g github:lbframe/agent-doc-system
       - name: Validate and compile