agent-doc-system 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -9,6 +9,79 @@ refused by the next with `AGENTDOC_COMPILER_MISMATCH` until it is recompiled.
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-11-13
+
+### Added
+
+- Task-oriented `prepare`, `expand` and `refresh` JSON operations with versioned facts, evidence references, explicit coverage, snapshot-bound pagination and exact serialized token budgets for `o200k_base` and `cl100k_base`.
+- Local persistent compilation reuse, shared reads and content-addressed JSON parsing. Changed files, directory probes, ignore rules and compiler inputs invalidate reuse; full compilation remains the reference.
+- Session check-result imports with pinned execution evidence and conservative snapshot invalidation, plus an opt-in JavaScript TypeScript symbol-candidate index that never narrows checks.
+- An agent evaluation runner with independent validators, a 30-task synthetic starter corpus, a local Codex driver, bounded campaigns and conservative candidate selection. No model-efficiency improvement is claimed from the starter corpus.
+- Local context benchmarks with graph and packet equivalence checks.
+
+### Fixed
+
+- Default Markdown now reports capped conflicts and checks, repository gates, typed relationships and runtime facts. Settled conflicts are distinguished from unresolved ones.
+- Test fixtures no longer inherit local Git commit or tag signing requirements.
+
+### Upgrade
+
+- Recompile committed graphs with `agentdoc compile` after upgrading.
+- Exact token budgets use the pinned `js-tiktoken` runtime dependency. The compiler itself remains independent of model APIs. See [the task context protocol](docs/CONTEXT.md).
+
+
+## [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 +440,9 @@ 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.5.0...HEAD
+[1.5.0]: https://github.com/lbframe/agent-doc-system/compare/v1.4.0...v1.5.0
+[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 +475,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/INSTALL_FOR_AGENTS.md

@@ -37,7 +37,7 @@ npm install -g github:lbframe/agent-doc-system
 The command is idempotent: run it again to upgrade to the latest `main`.
 If a specific ref is required, append it: `github:lbframe/agent-doc-system#<ref>`.
 
-The package has zero runtime dependencies. If `npm install -g` fails on
+The task context commands use a pinned tokenizer dependency. If `npm install -g` fails on
 permissions, do **not** use `sudo`; fix the npm global prefix instead
 (`npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to `PATH`),
 or report the blocker.

package/README.md

@@ -45,6 +45,10 @@ AgentDoc gives them a map.
 
 ![AgentDoc in action — query, impact, check](docs/assets/readme/agentdoc-in-action.webp)
 
+## Task context for agents
+
+Use `agentdoc prepare` with a JSON task request to obtain a versioned context packet with an exact token budget. `expand` continues a partial packet; `refresh` updates retained context after edits. [Protocol and examples](docs/CONTEXT.md).
+
 ## Three commands, one workflow
 
 ```bash
@@ -102,7 +106,7 @@ Measured, reproducible, and with no model in the loop. Method and caveats are in
 - **Seconds to map a real repository.** A fresh `init` → `scaffold` → `compile` takes 1.0–4.6 s on four public repositories, from 141 to 5,142 files (axum, pydantic-ai, full-stack-fastapi-template, create-t3-turbo). No edit was needed beyond choosing each component's placement.
 - **A briefing, not a dump.** A `query` answer is about 100–260 tokens: what the change reaches, what to read, and which checks to run.
 - **The same graph every time.** Compiles are byte-identical, and CI can verify it.
-- **Small and strict.** Zero runtime dependencies, a package of about 285 kB packed, 21 adapters, and 709/709 cases on the official TOML 1.0 conformance suite.
+- **Small and strict.** A pinned tokenizer dependency, 21 adapters, and 709/709 cases on the official TOML 1.0 conformance suite.
 
 ## Install manually
 

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/bin/agentdoc.mjs

@@ -188,7 +188,16 @@ try {
     process.stdout.write(commandHelp(cmd));
     process.exit(0);
   }
-  if (cmd === "validate") {
+  if (["prepare", "expand", "refresh"].includes(cmd)) {
+    if (positional.length) throw new UsageError("context operations accept JSON via --request or stdin");
+    const file = opt("request");
+    const raw = fs.readFileSync(!file || file === "-" ? 0 : file, "utf8");
+    if (Buffer.byteLength(raw) > 1024 * 1024) throw new UsageError("context request exceeds 1 MiB");
+    const request = JSON.parse(raw);
+    const { prepare, expand, refresh, serializePacket } = await import("../core/context/index.mjs");
+    const result = ({ prepare, expand, refresh })[cmd](ROOT, request);
+    process.stdout.write(serializePacket(result));
+  } else if (cmd === "validate") {
     const res = compile(ROOT);
     printDiagnostics(res);
     if (res.errors.length) fail(res.errors, res.stats);
@@ -492,6 +501,12 @@ try {
     usage(2);
   }
 } catch (e) {
+  if (e instanceof UsageError || e instanceof SyntaxError && ["prepare", "expand", "refresh"].includes(cmd)) {
+    console.error("ERROR " + CODES.CONTEXT_REQUEST + ": " + e.message); process.exit(2);
+  }
+  if (Object.values(CODES).includes(e.code)) {
+    console.error("ERROR " + e.code + ": " + e.message); process.exit(1);
+  }
   if (e instanceof AgentDocError) {
     console.error("ERROR " + e.format());
     process.exit(1);

package/bin/commands.mjs

@@ -13,6 +13,21 @@ const JSON_FLAG = { json: { desc: "print the machine-readable report" } };
 const JSON_ALWAYS = { json: { desc: "accepted for explicitness; the output is always JSON" } };
 
 export const COMMANDS = {
+  prepare: {
+    synopsis: "agentdoc prepare [--request file|-]",
+    summary: "prepare a versioned task context packet from JSON (stdin by default)",
+    flags: { request: { value: "file|-", desc: "JSON request file, or - for stdin" }, ...JSON_ALWAYS },
+  },
+  expand: {
+    synopsis: "agentdoc expand [--request file|-]",
+    summary: "expand a packet continuation on the same snapshot",
+    flags: { request: { value: "file|-", desc: "JSON continuation request" }, ...JSON_ALWAYS },
+  },
+  refresh: {
+    synopsis: "agentdoc refresh [--request file|-]",
+    summary: "refresh context with explicit retained record IDs",
+    flags: { request: { value: "file|-", desc: "JSON refresh request" }, ...JSON_ALWAYS },
+  },
   init: {
     synopsis: "agentdoc init [--force]",
     summary: "write a configuration and documentation skeleton",

package/bin/usage.txt

@@ -4,6 +4,10 @@ agentdoc — portable documentation & software-catalog system
   agentdoc --help                    show this help
   agentdoc <command> --help          every flag one command accepts (also: agentdoc help <command>)
 
+  agentdoc prepare [--request file|-] task context packet (JSON stdin/stdout)
+  agentdoc expand [--request file|-]  continue a packet on its snapshot
+  agentdoc refresh [--request file|-] update retained context after changes
+
   agentdoc init [--force]            write a configuration and documentation skeleton
                                      (docs skeleton goes to the configured docs.* paths;
                                      agentdoc/docs/ when there is no configuration yet)

package/core/cache/compiled.mjs

@@ -0,0 +1,34 @@
+// One bounded, atomic cache record per repository. Cache errors only cost work.
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { sha256Hex } from "../fsx.mjs";
+
+const LIMIT = 32 * 1024 * 1024;
+const digest = (record) => sha256Hex(JSON.stringify([record.key, record.serialized, record.stats]));
+export function readCompiledCache(file, key) {
+  try {
+    if (fs.statSync(file).size > LIMIT) return null;
+    const record = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (record.version !== 1 || record.key !== key || typeof record.serialized !== "string") return null;
+    if (!record.stats || digest(record) !== record.digest) return null;
+    return record;
+  } catch { return null; }
+}
+
+export function writeCompiledCache(file, record) {
+  let temporary;
+  try {
+    for (const dir of [path.dirname(file), path.dirname(path.dirname(file))]) {
+      if (fs.existsSync(dir) && fs.lstatSync(dir).isSymbolicLink()) return false;
+    }
+    const text = JSON.stringify({ ...record, version: 1, digest: digest(record) });
+    if (Buffer.byteLength(text) > LIMIT) return false;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    temporary = file + "." + randomUUID() + ".tmp";
+    fs.writeFileSync(temporary, text, { flag: "wx", mode: 0o600 });
+    fs.renameSync(temporary, file);
+    return true;
+  } catch { return false; }
+  finally { if (temporary) { try { fs.rmSync(temporary, { force: true }); } catch { /* cache is optional */ } } }
+}

package/core/cache/parses.mjs

@@ -0,0 +1,33 @@
+import { sha256Hex } from "../fsx.mjs";
+
+// Bounded content-addressed JSON parsing across snapshots in one process.
+// Values are cloned on both boundaries: extractors may mutate their result.
+export class ParseCache {
+  constructor(maxBytes = 8 * 1024 * 1024) {
+    this.maxBytes = maxBytes;
+    this.bytes = 0;
+    this.entries = new Map();
+  }
+  get(text) {
+    const key = sha256Hex("json@1\0" + text);
+    const entry = this.entries.get(key);
+    if (!entry) return undefined;
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return structuredClone(entry.value);
+  }
+  set(text, value) {
+    const bytes = Buffer.byteLength(text);
+    if (bytes > this.maxBytes) return;
+    const key = sha256Hex("json@1\0" + text);
+    if (this.entries.has(key)) this.bytes -= this.entries.get(key).bytes;
+    this.entries.delete(key);
+    while ((this.bytes + bytes > this.maxBytes || this.entries.size >= 1000) && this.entries.size) {
+      const oldest = this.entries.keys().next().value;
+      this.bytes -= this.entries.get(oldest).bytes;
+      this.entries.delete(oldest);
+    }
+    this.entries.set(key, { bytes, value: structuredClone(value) });
+    this.bytes += bytes;
+  }
+}

package/core/codes.mjs

@@ -2,6 +2,17 @@
 // produce is named here so tests, CI and the skill can match on identity
 // rather than on human-readable message text.
 export const CODES = {
+  // Task context, session evidence and snapshot capture.
+  CONTEXT_REQUEST: "AGENTDOC_CONTEXT_REQUEST",
+  CONTEXT_BUDGET: "AGENTDOC_CONTEXT_BUDGET",
+  CONTEXT_TOKENIZER: "AGENTDOC_CONTEXT_TOKENIZER",
+  CONTEXT_COMPILE: "AGENTDOC_CONTEXT_COMPILE",
+  CONTEXT_REFERENCE: "AGENTDOC_CONTEXT_REFERENCE",
+  CONTEXT_STALE: "AGENTDOC_CONTEXT_STALE",
+  SESSION_RESULT: "AGENTDOC_SESSION_RESULT",
+  SYMBOL_REQUEST: "AGENTDOC_SYMBOL_REQUEST",
+  SNAPSHOT_UNSTABLE: "AGENTDOC_SNAPSHOT_UNSTABLE",
+
   // source & schema
   UTF8: "AGENTDOC_UTF8",
   YAML_PARSE: "AGENTDOC_YAML_PARSE",
@@ -23,6 +34,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 +110,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

@@ -49,7 +49,27 @@ function earlyOut(res, extra = {}) {
 }
 
 export function compile(root, opts = {}) {
+  const started = performance.now();
+  const result = compileOnce(root, opts);
+  if (opts.telemetry) result.telemetry = {
+    durationMs: performance.now() - started,
+    ...result.repo?.metrics,
+    serializedBytes: result.serialized ? Buffer.byteLength(result.serialized) : 0,
+    heapUsedBytes: process.memoryUsage().heapUsed,
+    stages: result.phaseTimings || {},
+  };
+  return result;
+}
+
+function compileOnce(root, opts = {}) {
   const res = new CompileResult();
+  let stageStart = opts.telemetry ? performance.now() : 0;
+  const stage = (name) => {
+    if (!opts.telemetry) return;
+    const now = performance.now();
+    (res.phaseTimings ||= {})[name] = now - stageStart;
+    stageStart = now;
+  };
   // A peek load, only to read the generated-directory list: a project that keeps
   // build output in a directory this build does not know about must be able to
   // say so.
@@ -60,7 +80,7 @@ export function compile(root, opts = {}) {
   } catch {
     // No configuration, or an invalid one: the real load below reports it.
   }
-  const repo = new Repo(root, { noGit: opts.noGit, generatedDirs: cfgGeneratedDirs });
+  const repo = new Repo(root, { noGit: opts.noGit, generatedDirs: cfgGeneratedDirs, snapshotReads: opts.snapshotReads, parseCache: opts.parseCache });
   let bundle;
   let schemaInputs;
   try {
@@ -83,6 +103,7 @@ export function compile(root, opts = {}) {
   // a coverage failure is what scaffolding exists to fix.
   res.repo = repo;
   res.cfg = cfg;
+  stage("configuration");
   const refs = makeRefs(cfg.namespace);
   const graphPath = cfg.output.graph;
 
@@ -145,6 +166,7 @@ export function compile(root, opts = {}) {
     throw e;
   }
   const discovery = discoverUnits(repo, cfg, adapters);
+  stage("sourcesAndDiscovery");
   repo.nestedUnitRoots = discovery.nestedRoots;
   // Eligibility is the compiler's own answer to "which directories are units" —
   // exposed on the result so scaffold can write descriptors for exactly these
@@ -498,6 +520,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 +803,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;
@@ -785,6 +811,7 @@ export function compile(root, opts = {}) {
     }
   }
 
+  stage("extractionAndAuthority");
   const graph = assembleGraph(sources, rel, indexes, derivedMap, facts, rawConflicts, observationOut, provFinal, diagnostics);
   graph.compiler = { name: COMPILER_NAME, version: COMPILER_VERSION, adapters: adapterStamp(adapters) };
 
@@ -861,6 +888,7 @@ export function compile(root, opts = {}) {
     commit,
     dirty,
   };
+  stage("assemblyAndValidation");
   return res;
 }