agent-doc-system 1.3.0 → 1.5.0

package/core/query.mjs

@@ -130,7 +130,7 @@ function contractsOf(graph) {
 
 export function queryContext(graph, needle, opts = {}) {
   const budget = { ...DEFAULT_BUDGET, ...(opts.budget || {}) };
-  const idx = new ContextIndex(graph);
+  const idx = opts.index || new ContextIndex(graph);
   const entity = idx.resolve(needle);
   if (!entity) {
     throw new AgentDocError(
@@ -379,8 +379,21 @@ export function renderContext(ctx, opts = {}) {
   if (ctx.placement.domains.length) L.push("- domain: " + ctx.placement.domains.join(", "));
   if (ctx.apis.provided.length) L.push("- provides: " + ctx.apis.provided.map((a) => a.api).join(", "));
   if (ctx.apis.consumed.length) L.push("- consumes: " + ctx.apis.consumed.map((a) => a.api + " (via " + a.provider + ")").join(", "));
+  if (ctx.apis.provider) L.push("- API provider: " + ctx.apis.provider);
+  if (ctx.apis.consumers.length) L.push("- API consumers: " + ctx.apis.consumers.join(", "));
+  if (ctx.apis.contract) L.push("- API contract: " + JSON.stringify(ctx.apis.contract));
   if (ctx.resources.used.length) L.push("- uses resource: " + ctx.resources.used.join(", "));
-  if (ctx.events.items.length) L.push("- events: " + ctx.events.items.map((x) => x.pattern + " [" + x.resolution + "]").join(", "));
+  if (ctx.resources.usedBy.length) L.push("- resource users: " + ctx.resources.usedBy.join(", "));
+  if (ctx.relations.items.length) {
+    L.push("- relations:");
+    for (const r of ctx.relations.items) {
+      L.push("  - " + r.direction + " " + r.type + " " + r.other + " [" + r.evidenceClass + "]" +
+        (r.attributes ? " " + JSON.stringify(r.attributes) : ""));
+    }
+  }
+  if (ctx.events.items.length) L.push("- events: " + ctx.events.items.map((x) => x.pattern + " [" + x.resolution + "]" +
+    " producers=" + JSON.stringify(x.producers) + " consumers=" + JSON.stringify(x.consumers) +
+    (x.contract ? " contract=" + JSON.stringify(x.contract) : "")).join(", "));
   if (ctx.externalDependencies.items.length) L.push("- external: " + ctx.externalDependencies.items.map((x) => x.name + " (" + x.role + ")").join(", "));
   if (ctx.capabilities.items.length) L.push("- capabilities: " + ctx.capabilities.items.map((x) => x.name).join(", "));
   for (const key of ["constraints", "docs", "runbooks"]) {
@@ -395,13 +408,36 @@ export function renderContext(ctx, opts = {}) {
   }
   if (ctx.verification.items.length) {
     L.push("- verify:");
-    for (const v of ctx.verification.items) L.push("  - [" + v.tier + "] " + v.command);
+    for (const v of ctx.verification.items) L.push("  - [" + v.tier + "] " + v.command + " (" + v.id +
+      (v.configPaths?.length ? "; config: " + v.configPaths.join(", ") : "") + ")");
+  }
+  if (ctx.globalGates.length) {
+    L.push("- repository gates (required in addition to scoped checks):");
+    for (const v of ctx.globalGates) L.push("  - [" + v.tier + "] " + v.command + " (" + v.id + ")");
   }
   if (ctx.journeys.items.length) L.push("- journeys: " + ctx.journeys.items.map((j) => j.id).join(", "));
-  if (ctx.authority.conflicts.items.length) {
-    L.push("- CONFLICTS (do not assume one is true):");
-    for (const c of ctx.authority.conflicts.items) {
+  if (ctx.journeyPeers.length) L.push("- journey peers: " + ctx.journeyPeers.join(", "));
+  if (ctx.contracts.items.length) {
+    L.push("- contracts:");
+    for (const c of ctx.contracts.items) L.push("  - " + JSON.stringify(c));
+  }
+  if (ctx.authority.assertions.items.length) {
+    L.push("- assertions:");
+    for (const a of ctx.authority.assertions.items) {
+      L.push("  - " + a.key + " [" + a.evidenceClass + "/" + a.confidence + "/" + a.status + "]: " +
+        JSON.stringify(a.value) + (a.semantics ? " (" + a.semantics + ")" : ""));
+    }
+  }
+  for (const [settled, title] of [
+    [false, "CONFLICTS (do not assume one is true)"],
+    [true, "RESOLVED CONFLICTS (use the recorded election; re-check its review condition)"],
+  ]) {
+    const conflicts = ctx.authority.conflicts.items.filter((c) => (c.status !== "unresolved") === settled);
+    if (!conflicts.length) continue;
+    L.push("- " + title + ":");
+    for (const c of conflicts) {
       L.push("  - " + c.key + " [" + c.kind + "/" + c.status + "] " + (c.detail || ""));
+      if (c.election) L.push("    - election: " + JSON.stringify(c.election));
       for (const a of c.assertions) L.push("    - " + a.evidenceClass + "/" + a.confidence + ": " + JSON.stringify(a.value));
     }
   }
@@ -421,9 +457,24 @@ export function renderContext(ctx, opts = {}) {
   const obs = ctx.authority.observations;
   if (obs.length) {
     L.push("- RUNTIME OBSERVATIONS:");
-    for (const o of obs) L.push("  - " + o.environment + " via " + o.sourceSystem + " at " + o.capturedAt + " (evidence " + o.evidenceBundle + ")");
+    for (const o of obs) {
+      L.push("  - " + o.environment + " via " + o.sourceSystem + " at " + o.capturedAt + " (evidence " + o.evidenceBundle + ")");
+      for (const f of o.facts) L.push("    - " + f.key + ": " + JSON.stringify(f.value) +
+        (f.semantics ? " (" + f.semantics + ")" : ""));
+    }
   }
   const neighbours = ctx.neighbours.filter((n) => n.ref !== e.ref);
   if (neighbours.length) L.push("- neighbours: " + neighbours.map((n) => n.ref).join(", "));
+  if (ctx.provenance.items.length) {
+    L.push("- evidence:");
+    for (const p of ctx.provenance.items) L.push("  - " + p.id + " " + p.path + " [" + p.class + "] " + p.contentHash);
+  }
+  if (ctx.truncated.length) {
+    L.push("- INCOMPLETE CONTEXT (request a larger --budget before treating these sections as complete):");
+    for (const name of ctx.truncated) {
+      const section = name.split(".").reduce((value, key) => value[key], ctx);
+      L.push("  - " + name + " [truncated: " + section.items.length + " of " + section.total + "]");
+    }
+  }
   return L.join("\n");
 }

package/core/session/results.mjs

@@ -0,0 +1,138 @@
+import { CODES } from "../codes.mjs";
+// Imported runner evidence is scoped to one repository snapshot and execution
+// context. This module never executes a check or promotes a recommendation into
+// a success. Any changed graph or evidence invalidates the imported result.
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { compileSnapshot } from "../snapshot.mjs";
+import { canonicalPath } from "../paths.mjs";
+import { observationFreshness } from "../observations.mjs";
+import { assertNoSecretsInText } from "../secrets.mjs";
+
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+const graphHash = (graph) => digest(JSON.stringify(graph));
+function reject(message) { throw Object.assign(new Error(message), { code: CODES.SESSION_RESULT }); }
+function object(value, keys, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) reject(name + " must be an object");
+  for (const key of Object.keys(value)) if (!keys.includes(key)) reject("unknown " + name + " field: " + key);
+}
+function nonempty(value, name) {
+  if (typeof value !== "string" || !value.trim()) reject(name + " must be a nonempty string");
+}
+function sessionFile(root, session) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(session || "")) reject("invalid session reference");
+  return path.join(path.resolve(root), ".agentdoc", "sessions", "check-results", session + ".json");
+}
+function repositoryPath(root, value, directory = false) {
+  const rel = canonicalPath(value);
+  if (rel === null || typeof value !== "string" || !value) reject("execution paths must stay inside the repository");
+  let real;
+  try {
+    real = fs.realpathSync(path.join(root, rel));
+    const stat = fs.statSync(real);
+    if (directory ? !stat.isDirectory() : !stat.isFile()) reject("wrong execution path kind: " + rel);
+  } catch { reject("execution path unavailable: " + rel); }
+  const base = fs.realpathSync(root);
+  if (real !== base && !real.startsWith(base + path.sep)) reject("execution path escapes repository: " + rel);
+  return { rel, real };
+}
+function current(root, snapshot) {
+  if (!snapshot || !/^[a-f0-9]{64}$/.test(snapshot.graphHash || "")) reject("snapshot.graphHash must identify the full graph");
+  const res = compileSnapshot(root);
+  if (res.errors.length) reject("cannot validate results against a failing compilation");
+  if (snapshot.graphHash !== graphHash(res.graph)) reject("snapshot changed; imported checks must be run again");
+  if (observationFreshness(res.graph.observations).some((o) => o.stale)) reject("runtime observation expired; refresh context before importing checks");
+  return res.graph;
+}
+function execution(result, root, graph) {
+  object(result, ["checkId", "command", "cwd", "status", "exitCode", "runner", "evidence"], "result");
+  nonempty(result.checkId, "checkId");
+  nonempty(result.command, "command");
+  const check = [...graph.verification, ...graph.gates].find((v) => v.id === result.checkId);
+  if (!check || check.command !== result.command) reject("result must name the exact registered check and command");
+  const cwd = repositoryPath(root, result.cwd, true).rel;
+  if (!["succeeded", "failed"].includes(result.status) || !Number.isSafeInteger(result.exitCode) || result.exitCode < 0 ||
+      (result.status === "succeeded") !== (result.exitCode === 0)) reject("execution status must agree with its exit code");
+  object(result.runner, ["name", "version"], "runner");
+  nonempty(result.runner.name, "runner.name"); nonempty(result.runner.version, "runner.version");
+  object(result.evidence, ["path", "sha256"], "evidence");
+  if (!/^[a-f0-9]{64}$/.test(result.evidence.sha256 || "")) reject("evidence requires a SHA-256 digest");
+  const evidencePath = repositoryPath(root, result.evidence.path);
+  const bytes = fs.readFileSync(evidencePath.real);
+  if (digest(bytes) !== result.evidence.sha256) reject("execution evidence changed");
+  let report;
+  try { report = JSON.parse(bytes.toString("utf8")); } catch { reject("execution evidence must be a JSON runner report"); }
+  if (!report || typeof report !== "object" || report.snapshot?.graphHash !== graphHash(graph) ||
+      report.checkId !== result.checkId || report.command !== result.command || report.cwd !== cwd ||
+      report.status !== result.status || report.exitCode !== result.exitCode ||
+      report.runner?.name !== result.runner.name || report.runner?.version !== result.runner.version) reject("runner report does not corroborate the imported result");
+  return { ...result, cwd, runner: { ...result.runner }, evidence: { path: evidencePath.rel, sha256: result.evidence.sha256 } };
+}
+function read(root, session) {
+  const file = sessionFile(root, session);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const stored = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (stored.digest !== digest(JSON.stringify(stored.data)) || stored.data.repository !== fs.realpathSync(root) ||
+        stored.data.session !== session || stored.data.schemaVersion !== "agentdoc.dev/check-results/v1" || !Array.isArray(stored.data.results)) reject("invalid stored results");
+    return stored.data;
+  } catch { reject("stored session results are invalid; forget the session and rerun its checks"); }
+}
+
+export function importCheckResults(root, request) {
+  object(request, ["session", "snapshot", "results"], "import");
+  const file = sessionFile(root, request.session);
+  if (!Array.isArray(request.results) || !request.results.length) reject("results must be a nonempty execution list");
+  const graph = current(root, request.snapshot);
+  const incoming = request.results.map((r) => execution(r, root, graph));
+  const previous = read(root, request.session);
+  const combined = new Map();
+  if (previous?.graphHash === request.snapshot.graphHash) {
+    for (const r of previous.results) {
+      try { const valid = execution(r, root, graph); combined.set(JSON.stringify([valid.checkId, valid.command, valid.cwd, valid.runner]), valid); }
+      catch { /* An old evidence bundle may have been replaced by a rerun. */ }
+    }
+  }
+  for (const r of incoming) combined.set(JSON.stringify([r.checkId, r.command, r.cwd, r.runner]), r);
+  const data = { schemaVersion: "agentdoc.dev/check-results/v1", repository: fs.realpathSync(root), session: request.session,
+    graphHash: request.snapshot.graphHash, results: [...combined.values()] };
+  const serialized = JSON.stringify({ data, digest: digest(JSON.stringify(data)) });
+  assertNoSecretsInText(serialized, "session check results");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = file + "." + randomUUID() + ".tmp";
+  try { fs.writeFileSync(temp, serialized, { mode: 0o600 }); fs.renameSync(temp, file); }
+  finally { fs.rmSync(temp, { force: true }); }
+  return { session: request.session, graphHash: data.graphHash, results: data.results };
+}
+
+export function validResultsForSnapshot(root, session, snapshot) {
+  const data = read(root, session);
+  if (!data || data.graphHash !== snapshot?.graphHash) return [];
+  let graph;
+  try { graph = current(root, snapshot); } catch { return []; }
+  const valid = [];
+  for (const result of data.results) {
+    try { valid.push(execution(result, root, graph)); } catch { /* Expired or changed evidence is not a valid result. */ }
+  }
+  return valid;
+}
+
+export function forgetSession(root, session) {
+  const file = sessionFile(root, session);
+  const existed = fs.existsSync(file);
+  fs.rmSync(file, { force: true });
+  return existed;
+}
+
+export function clearSessions(root) {
+  const dir = path.dirname(sessionFile(root, "session"));
+  if (!fs.existsSync(dir)) return 0;
+  let removed = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isFile() && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}\.json$/.test(entry.name)) {
+      fs.unlinkSync(path.join(dir, entry.name)); removed++;
+    }
+  }
+  return removed;
+}

package/core/snapshot.mjs

@@ -0,0 +1,123 @@
+// Conservative persistent compilation reuse. Every visible file is hashed;
+// this deliberately over-invalidates rather than inventing extractor-level
+// dependencies. Full compile remains the oracle and is always available.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Repo, sha256Hex } from "./fsx.mjs";
+import { compile, CompileResult } from "./compile.mjs";
+import { loadConfig, loadSchemaBundle } from "./descriptors.mjs";
+import { AgentDocError, CODES } from "./codes.mjs";
+import { readCompiledCache, writeCompiledCache } from "./cache/compiled.mjs";
+import { ParseCache } from "./cache/parses.mjs";
+
+const implementationRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function implementationHash() {
+  const records = [];
+  for (const dir of ["core", "adapters", "schemas"]) {
+    const walk = (base) => {
+      for (const entry of fs.readdirSync(base, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        const file = path.join(base, entry.name);
+        if (entry.isDirectory()) walk(file);
+        else if (entry.isFile()) records.push([path.relative(implementationRoot, file), sha256Hex(fs.readFileSync(file))]);
+      }
+    };
+    walk(path.join(implementationRoot, dir));
+  }
+  return sha256Hex(JSON.stringify(records));
+}
+
+// A running process keeps its imported implementation even if files on disk
+// are replaced by an upgrade. Never label old code's result with the new hash.
+const implementationVersion = implementationHash();
+const sharedParses = new ParseCache();
+
+function capture(root, opts) {
+  const schema = loadSchemaBundle();
+  const cfg = loadConfig(new Repo(root, { noGit: true }), schema.bundle);
+  const repo = new Repo(root, { noGit: opts.noGit, generatedDirs: cfg.discovery.generatedDirs || opts.generatedDirs, snapshotReads: true });
+  const files = repo.walk("").filter((file) => file !== cfg.output.graph);
+  const content = files.map((file) => [file, sha256Hex(repo.readBytes(file))]);
+  // Empty directories and path kinds are captured too: exists/isDir/listDir
+  // probes may affect resolution even when there is no readable file yet.
+  let symlinks = false;
+  const listings = [];
+  const visit = (dir) => {
+    if (repo.isIgnored(dir)) return;
+    const entries = fs.readdirSync(repo.abs(dir), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    const visible = [];
+    for (const entry of entries) {
+      const rel = dir === "." ? entry.name : dir + "/" + entry.name;
+      if (repo.generatedDirs.has(entry.name) || repo.isIgnored(rel)) continue;
+      visible.push([entry.name, entry.isSymbolicLink() ? "link" : entry.isDirectory() ? "dir" : "file"]);
+      if (entry.isSymbolicLink()) symlinks = true;
+      if (entry.isDirectory()) visit(rel);
+    }
+    listings.push([dir, visible]);
+  };
+  visit(".");
+  const state = {
+    version: 1, implementation: implementationVersion, schemas: schema.versionInputs, noGit: Boolean(opts.noGit),
+    generatedDirs: [...repo.generatedDirs].sort(), commit: repo.headCommit(),
+    status: repo.statusRecords()?.filter((r) => r.xy !== "!!" && r.path !== cfg.output.graph) || null, content, listings,
+  };
+  return { key: sha256Hex(JSON.stringify(state)), repo, cfg, files: new Set(files), digests: new Map(content), symlinks };
+}
+
+/** Read-only result consumer API. Extraction-only fields (ctx/discovery) are
+ * available on a miss only; callers needing those must use compile().
+ * Time-dependent observation gates must run after every call, including hits.
+ */
+export function compileSnapshot(root, opts = {}) {
+  const started = performance.now();
+  const file = path.join(path.resolve(root), ".agentdoc", "cache", "compiled-v1.json");
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let before;
+    try { before = capture(root, opts); }
+    catch { return compile(root, { ...opts, snapshotReads: false }); }
+    // Explicit authored paths can follow a symlink even though discovery does
+    // not. Without a target manifest, reuse would miss changes outside the walk.
+    if (before.symlinks) return compile(root, { ...opts, snapshotReads: false });
+    const cached = opts.cache === false ? null : readCompiledCache(file, before.key);
+    let result;
+    if (cached) {
+      try {
+        const graph = JSON.parse(cached.serialized);
+        const invalid = loadSchemaBundle().bundle.validator("agentdoc.dev/schema/graph.schema.json").validate(graph);
+        if (!invalid) {
+          result = new CompileResult();
+          Object.assign(result, { graph, serialized: cached.serialized, stats: cached.stats, diagnostics: graph.diagnostics,
+            cfg: before.cfg, repo: before.repo, graphPath: before.cfg.output.graph });
+        }
+      } catch { /* corrupt cache: compile instead */ }
+    }
+    const hit = Boolean(result);
+    result ||= compile(root, { ...opts, snapshotReads: true, telemetry: true, parseCache: opts.parseCache || sharedParses });
+    if (!hit && result.repo) {
+      const excluded = [...result.repo.readPaths.keys()].some((p) => !before.files.has(p)) ||
+        [...result.repo.probes.keys()].some((p) => p.split("/").some((seg) => before.repo.generatedDirs.has(seg)) || p === before.cfg.output.graph);
+      if (excluded) return compile(root, { ...opts, snapshotReads: false });
+    }
+    let after;
+    try { after = capture(root, opts); }
+    catch { continue; }
+    if (before.key !== after.key) continue;
+    if (!hit && result.repo) {
+      if ([...result.repo.readPaths].some(([p, digest]) => after.digests.get(p) !== digest)) continue;
+      if ([...result.repo.probeRecords.values()].some((probe) => after.repo[probe.kind](probe.path) !== probe.value)) continue;
+      if ([...result.repo.listings].some(([p, names]) => JSON.stringify(after.repo.listDir(p)) !== JSON.stringify(names))) continue;
+      if ([...result.repo.walkInputs].some(([dir, entries]) => JSON.stringify(after.repo.directoryState(dir)) !== JSON.stringify(entries))) continue;
+    }
+    if (!hit && !result.errors.length && opts.cache !== false) writeCompiledCache(file, {
+      key: before.key, serialized: result.serialized, stats: result.stats,
+    });
+    // Consumers read evidence from the captured bytes, including on cache hits.
+    result.repo = before.repo;
+    result.cache = { hit, key: before.key, mode: "whole-compile", persisted: opts.cache !== false };
+    result.telemetry = { ...(result.telemetry || {}), durationMs: performance.now() - started,
+      captureReads: before.repo.metrics.physicalReads + after.repo.metrics.physicalReads };
+    return result;
+  }
+  throw new AgentDocError(CODES.SNAPSHOT_UNSTABLE, "repository changed during context capture; retry once edits have settled");
+}

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.5.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/CONTEXT.md

@@ -0,0 +1,136 @@
+# Task context protocol
+
+`prepare`, `expand` and `refresh` accept one JSON request on stdin (or `--request file`) and emit one compact JSON packet plus a newline. They operate on the current working tree and do not require a committed graph. They never execute repository verification commands.
+
+```sh
+printf '%s\n' '{"task":"Change the engine API","paths":["crates/engine"],"intent":"change-contract","budget":{"tokens":4096,"encoding":"o200k_base"}}' | agentdoc prepare
+```
+
+Intents are `implement` (default), `change-contract`, `debug-runtime` and `review`. The first implementation conservatively retains the same obligation closure across intents. The packet contains typed, versioned records, evidence references, selected checks, analysis limitations and stale runtime observation IDs. It does not infer that unsupported or dynamic dependencies are absent.
+
+## Budget and continuation
+
+The exact serialized output, including its final newline, metadata and continuation, is counted using pinned `js-tiktoken@1.0.21`. Select `o200k_base` or `cl100k_base` explicitly to match the encoding used by your model; AgentDoc does not guess model tokenization. The supported budget is 256–1,000,000 tokens. A budget too small for the envelope or next indivisible record fails with `AGENTDOC_CONTEXT_BUDGET` and must be increased.
+
+`delivery.partial` and `delivery.criticalOmitted` report incomplete delivery. Critical obligations are selected first, but a partial page must never be interpreted as the complete check or constraint list. Follow `continuation` until it is null:
+
+```json
+{"packet":"<64-character packet reference>","offset":8,"tokens":8192}
+```
+
+Pass that object to `agentdoc expand`. Continuations are tied to the original request, snapshot and protocol. A changed graph or runtime freshness state rejects expansion with `AGENTDOC_CONTEXT_STALE`; use `refresh` or `prepare`. Larger budgets allow reading a long constraint document without silently shortening it.
+
+## Session refresh
+
+```json
+{"packet":"<previous packet reference>","acknowledged":["<retained record ID>"]}
+```
+
+Send this to `agentdoc refresh`. Acknowledge only records still present in the agent's active context. Without acknowledgements, all records are delivered again. `reset:true` also requests full delivery. Refresh emits new or changed records, explicit retractions and active critical obligations. Critical records are repeated even if acknowledged. The resulting delta has its own packet reference and continuation.
+
+The harness must apply retractions, replace changed versions and manage its active context. Merely appending delta messages does not bound the model's history. Following a lost or compacted session, request a reset. A changed snapshot conservatively invalidates prior execution evidence.
+
+Packets are stored locally under `.agentdoc/context/`, excluded from compiler inputs. Treat references as local to a repository. The JavaScript API exposes `forget(root, packet)` to remove a retained packet. At most 64 packets are retained per repository; older continuations may require preparing again. The caller can delete packets sooner; packet files are not published with the repository.
+
+## Checks and evidence
+
+A recommended shell command is not an execution result. In this initial protocol, checks expose `execution.status:"requires-context"` and `cwd:null` when the compiler has not established a working directory. Resolve that context from the check's owner and evidence before executing it. Identical command text for different checks remains distinct.
+
+Constraint and document records carry their content and a content fingerprint. Other records carry graph provenance identifiers or paths. Facts retain their authority data; contradictory claims are not merged into one assumed truth. Stale observations are marked explicitly and must not be treated as current production evidence.
+
+## Cache and compatibility
+
+`cache:false` in a prepare request bypasses persistent compilation reuse. The full compiler remains the correctness reference. Cache reuse is conservative and does not imply extractor-level incremental recompilation. Protocol version `agentdoc.dev/context/v1` is separate from graph version `agentdoc.dev/graph/v1`.
+
+Existing `query` and `impact` keep their established freshness policies. See [QUERY.md](QUERY.md) for those commands.
+
+## Importing check execution results from JavaScript
+
+The result API accepts reports produced by the harness after execution. It does
+not run the command or independently observe its execution. Each report must name
+a registered check and its exact command, an explicit repository-relative working
+directory, a runner name/version, and a status matching its exit code:
+
+```json
+{
+  "snapshot": { "graphHash": "<graphHash from the prepared packet>" },
+  "checkId": "<registered check ID>",
+  "command": "<exact registered command>",
+  "cwd": "service",
+  "status": "succeeded",
+  "exitCode": 0,
+  "runner": { "name": "<harness name>", "version": "<harness version>" }
+}
+```
+
+Use `failed` with a positive integer exit code for a failed execution. A
+recommendation, missing working directory or disagreement between the status and
+exit code is refused. Store the report under `.agentdoc/executions/` so writing
+execution evidence does not itself change the source snapshot. The report's
+`graphHash` must be the snapshot actually used for the run, not a new snapshot
+captured after unrelated edits.
+
+```js
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import {
+  importCheckResults, validResultsForSnapshot, forgetSession, clearSessions,
+} from 'agent-doc-system/core/session/results.mjs';
+
+// root is the repository root; packet is its prepared context packet.
+const reportPath = '.agentdoc/executions/check.json';
+const bytes = fs.readFileSync(path.join(root, reportPath));
+const report = JSON.parse(bytes.toString('utf8'));
+const { checkId, command, cwd, status, exitCode, runner } = report;
+importCheckResults(root, {
+  session: 'change-engine',
+  snapshot: packet.snapshot,
+  results: [{ checkId, command, cwd, status, exitCode, runner, evidence: {
+    path: reportPath,
+    sha256: createHash('sha256').update(bytes).digest('hex'),
+  } }],
+});
+
+const results = validResultsForSnapshot(root, 'change-engine', packet.snapshot);
+const successes = results.filter(result => result.status === 'succeeded');
+forgetSession(root, 'change-engine'); // Returns whether a result record existed.
+clearSessions(root); // Removes all retained result sessions; returns their count.
+```
+
+Import verifies the current graph, registered command and hash-pinned JSON report.
+Reads verify them again: a changed graph, changed evidence, unavailable execution
+directory or expired runtime observation invalidates prior results. Both valid
+successes and valid failures are returned; the harness must inspect `status`.
+All import validation errors use `AGENTDOC_SESSION_RESULT`.
+
+Session names contain 1–64 ASCII letters, digits, underscores or hyphens and start
+with a letter or digit. Result records live under
+`.agentdoc/sessions/check-results/`, independently of context packets. Cleanup
+removes result records only; it preserves context packets and execution reports.
+Use the context API's `forget(root, packet)` separately when dropping a packet.
+
+## TypeScript symbol candidates from JavaScript
+
+The optional symbol experiment indexes only explicitly requested TypeScript
+files. It returns declarations and reference candidates with source line/column
+locations and a SHA-256 content fingerprint:
+
+```js
+import { indexTypeScriptSymbols } from 'agent-doc-system/core/context/symbols.mjs';
+
+const candidates = indexTypeScriptSymbols(root, ['src/api.ts', 'src/consumer.ts']);
+for (const file of candidates.files) {
+  // file.path, file.sha256, file.declarations, file.references
+}
+```
+
+Supported paths end in `.ts`, `.tsx`, `.mts` or `.cts`; paths escaping the
+repository, including through a symlink, are refused. The experiment masks
+comments and quoted text, but does not resolve lexical scopes, imports,
+overloads, dynamic references, regex literals or template interpolation. Its
+output always declares `coverage.partial:true` and
+`coverage.checkSelection:"unchanged"`. Use candidates to navigate source, never
+to infer that an unlisted dependency is absent or to remove a required check.
+The experiment is a JavaScript API and is not enabled by the default context
+commands.