agent-doc-system 1.4.0 → 1.5.0

package/core/fsx.mjs

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

package/core/graph.mjs

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

package/core/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/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.4.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

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.