agent-doc-system 0.0.0-stage → 1.0.0

package/core/graph.mjs

@@ -0,0 +1,260 @@
+// Graph assembly, deterministic serialization, subject resolution, freshness
+// validation, and atomic replacement.
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AgentDocError, CODES } from "./codes.mjs";
+import { assertNoSecretsInText } from "./secrets.mjs";
+import { assertDeterministic, structuralProjection } from "./determinism.mjs";
+import { sha256Hex } from "./fsx.mjs";
+
+export const COMPILER_NAME = "agentdoc-compiler";
+export const COMPILER_VERSION = "1.0.0";
+export const GRAPH_SCHEMA_VERSION = "agentdoc.dev/graph/v1";
+
+// Resolve symbolic provenance subjects to RFC 6901 pointers into the graph.
+export function subjectResolver(graph) {
+  const entIdx = new Map(graph.entities.map((e, i) => [e.ref, i]));
+  const relIdx = new Map(graph.relations.map((r, i) => [r.type + "|" + r.sourceRef + "|" + r.targetRef + "|" + JSON.stringify(r.attributes), i]));
+  const evtIdx = new Map(graph.interfaces.events.map((e, i) => [e.pattern, i]));
+  const extIdx = new Map(graph.externalDependencies.map((e, i) => [e.componentRef + "|" + e.name, i]));
+  const capIdx = new Map(graph.capabilities.map((e, i) => [e.componentRef + "|" + e.name, i]));
+  const verIdx = new Map(graph.verification.map((e, i) => [e.id, i]));
+  const jouIdx = new Map(graph.journeys.map((e, i) => [e.id, i]));
+  const assIdx = new Map(graph.assertions.map((a, i) => [a.id, i]));
+  const conIdx = new Map(graph.conflicts.map((c, i) => [c.id, i]));
+  const obsIdx = new Map(graph.observations.map((o, i) => [o.id, i]));
+  const ctrIdx = new Map(graph.contracts.map((c, i) => [c.apiRef, i]));
+  const gateIdx = new Map(graph.gates.map((g, i) => [g.id, i]));
+
+  return (sym) => {
+    const splitAt = sym.indexOf(":/");
+    const head = splitAt >= 0 ? sym.slice(0, splitAt) : sym;
+    const tail = splitAt >= 0 ? sym.slice(splitAt + 1) : null;
+    const idx = (m, key, what) => {
+      const i = m.get(key);
+      if (i === undefined) throw new AgentDocError(CODES.PROVENANCE, "dangling provenance subject " + sym + " (" + what + ")");
+      return i;
+    };
+    if (sym.startsWith("entf:")) return "/entities/" + idx(entIdx, sym.slice(5, splitAt), "entity") + "/entity" + tail;
+    if (sym.startsWith("ent:")) return "/entities/" + idx(entIdx, sym.slice(4), "entity");
+    if (sym.startsWith("der:")) return "/entities/" + idx(entIdx, sym.slice(4, splitAt), "entity") + "/derived" + tail;
+    if (sym.startsWith("rel:")) return "/relations/" + idx(relIdx, sym.slice(4), "relation");
+    if (sym.startsWith("evt:")) return "/interfaces/events/" + idx(evtIdx, sym.slice(4), "event");
+    if (sym.startsWith("ext:")) return "/externalDependencies/" + idx(extIdx, sym.slice(4), "external dependency");
+    if (sym.startsWith("cap:")) return "/capabilities/" + idx(capIdx, sym.slice(4), "capability");
+    if (sym.startsWith("ver:")) return "/verification/" + idx(verIdx, sym.slice(4), "verification");
+    if (sym.startsWith("jou:")) return "/journeys/" + idx(jouIdx, sym.slice(4), "journey");
+    if (sym.startsWith("ass:")) return "/assertions/" + idx(assIdx, sym.slice(4), "assertion");
+    if (sym.startsWith("con:")) return "/conflicts/" + idx(conIdx, sym.slice("con:".length), "conflict");
+    if (sym.startsWith("ctr:")) return "/contracts/" + idx(ctrIdx, sym.slice("ctr:".length), "contract");
+    if (sym.startsWith("obs:")) return "/observations/" + idx(obsIdx, sym.slice(4), "observation");
+    if (sym.startsWith("gate:")) return "/gates/" + idx(gateIdx, sym.slice("gate:".length), "gate");
+    throw new AgentDocError(CODES.PROVENANCE, "unknown provenance subject " + sym);
+  };
+}
+
+export function assembleGraph(sources, rel, indexes, derivedMap, facts, conflicts, observations, provFinal, diagnostics) {
+  const entities = sources.entities
+    .map((e) => {
+      const rec = {
+        ref: e.ref,
+        kind: e.kind,
+        name: e.name,
+        entity: e.doc,
+        source: "authored",
+        sourcePaths: [e.file],
+      };
+      const d = derivedMap.get(e.ref);
+      if (d && Object.keys(d).length) rec.derived = d;
+      return rec;
+    })
+    .sort((a, b) => (a.ref < b.ref ? -1 : 1));
+
+  const relations = rel.relations.map((r) => ({
+    type: r.type,
+    sourceRef: r.sourceRef,
+    targetRef: r.targetRef,
+    evidenceClass: r.evidenceClass,
+    attributes: r.attributes || {},
+    provenanceIds: [...r.provs].map((p) => provFinal.idOf.get(p)).filter(Boolean).sort(),
+  }));
+
+  const strip = (arr, extra) =>
+    arr.map((r) => {
+      const { provs, _provs, ...rest } = r;
+      const add = extra ? extra(r) : {};
+      const out = { ...add, ...rest };
+      if (add && add._drop) {
+        delete out._drop;
+        delete out.provenanceIds;
+        return out;
+      }
+      out.provenanceIds = [...(provs || _provs || [])].map((p) => provFinal.idOf.get(p)).filter(Boolean).sort();
+      if (Array.isArray(out.provenanceIds) && out.provenanceIds.length === 0) delete out.provenanceIds;
+      for (const k of Object.keys(out)) if (out[k] === null) delete out[k];
+      return out;
+    });
+
+  const assertions = facts.facts
+    .slice()
+    .sort((a, b) => (a.id < b.id ? -1 : 1))
+    .map((a) => {
+      const out = {
+        id: a.id,
+        subject: a.subject,
+        key: a.key,
+        value: a.value,
+        evidenceClass: a.evidenceClass,
+        confidence: a.confidence,
+        status: a.status,
+        provenanceIds: [...a.provRecs].map((p) => provFinal.idOf.get(p)).filter(Boolean).sort(),
+      };
+      if (a.semantics) out.semantics = a.semantics;
+      if (a.observed) out.observed = a.observed;
+      if (a.review) out.review = a.review;
+      return out;
+    });
+
+  // A conflict is corroborated by the evidence of the assertions it holds apart:
+  // that is exactly the evidence a reviewer needs in order to settle it.
+  const provByAssertion = new Map(
+    facts.facts.map((a) => [a.id, [...a.provRecs].map((p) => provFinal.idOf.get(p)).filter(Boolean).sort()])
+  );
+  const idsBySubjectKey = new Map();
+  for (const a of facts.facts) {
+    const k = a.subject + "|" + a.key;
+    if (!idsBySubjectKey.has(k)) idsBySubjectKey.set(k, []);
+    idsBySubjectKey.get(k).push(a.id);
+  }
+  const conflictOut = conflicts.map((c, i) => {
+    const out = {
+      id: "c-" + String(i + 1).padStart(4, "0"),
+      subject: c.subject,
+      key: c.key,
+      kind: c.kind,
+      status: c.status,
+      assertionIds: c.assertionIds,
+      election: {
+        electedAssertionId: c.election.elected ? c.election.elected.id : null,
+        basis: c.election.basis,
+        ruleId: c.election.ruleId,
+      },
+    };
+    if (c.election.rationale) out.election.rationale = c.election.rationale;
+    // Carried explicitly, including when it is null, so a consumer can tell
+    // "this decision has a review condition" from "no rule governs this key".
+    out.election.reviewWhen = c.election.reviewWhen ?? null;
+    if (c.election.contradicted && c.election.contradicted.length) out.election.contradictedAssertionIds = c.election.contradicted;
+    if (c.detail) out.detail = c.detail;
+    if (c.acceptance) out.acceptance = c.acceptance;
+    out.provenanceIds = (idsBySubjectKey.get(c.subject + "|" + c.key) || [])
+      .flatMap((id) => provByAssertion.get(id) || [])
+      .filter(Boolean)
+      .sort();
+    return out;
+  });
+
+  return {
+    schemaVersion: GRAPH_SCHEMA_VERSION,
+    source: { commit: "0000000", dirty: false, inputHash: "sha256:" + "0".repeat(64) },
+    compiler: { name: COMPILER_NAME, version: COMPILER_VERSION, adapters: [] },
+    entities,
+    relations,
+    interfaces: { events: strip(indexes.events) },
+    externalDependencies: strip(indexes.externalDependencies),
+    capabilities: strip(indexes.capabilities),
+    verification: strip(indexes.verification, () => ({})),
+    journeys: strip(indexes.journeys, () => ({})),
+    gates: strip(indexes.gates || [], () => ({})),
+    contracts: strip(indexes.contracts || []),
+    assertions,
+    conflicts: conflictOut,
+    observations: strip(observations),
+    provenance: provFinal.list,
+    diagnostics,
+  };
+}
+
+export function serializeGraph(graph) {
+  // Objects are constructed in schema order, arrays are pre-sorted, and no
+  // wall-clock value, host path, username or random id is introduced anywhere.
+  return JSON.stringify(graph, null, 2) + "\n";
+}
+
+export function finalizeSerialization(text, graph, { allowedTimestamps = [] } = {}) {
+  assertNoSecretsInText(text, "compiled graph");
+  assertDeterministic(text, { allowedTimestamps, what: "graph", structural: structuralProjection(graph) });
+  return text;
+}
+
+export function writeGraphAtomic(repo, relPath, content) {
+  const abs = repo.abs(relPath);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  const tmp = abs + ".tmp-" + process.pid;
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, abs);
+}
+
+// Freshness: a consumer MUST refuse a graph whose provenance does not match the
+// current checkout. No silent fallback, ever.
+// Freshness deliberately does NOT compare the recorded commit with HEAD.
+//
+// The graph is often committed alongside the change that produced it, and
+// committing a file changes HEAD — so a commit-equality gate can never be
+// satisfied, and a graph produced by an agent mid-task would always look stale.
+// What actually determines whether the graph still describes the repository is
+// the input hash (every byte the compiler read) and the dirty flag (whether a
+// compiler input differs from HEAD). The commit is kept as provenance so a
+// reader can see which checkout produced the graph, not as a gate.
+export function assertFresh(graph, { inputHash, dirty, compilerVersion = COMPILER_VERSION, schemaVersion = GRAPH_SCHEMA_VERSION }) {
+  if (graph.schemaVersion !== schemaVersion) {
+    throw new AgentDocError(CODES.GRAPH_SCHEMA, "unsupported graph schemaVersion '" + graph.schemaVersion + "' (expected " + schemaVersion + ")");
+  }
+  if (graph.compiler?.name !== COMPILER_NAME || graph.compiler?.version !== compilerVersion) {
+    throw new AgentDocError(
+      CODES.COMPILER_MISMATCH,
+      "graph was compiled by " + JSON.stringify(graph.compiler) + ", this compiler is " + COMPILER_NAME + "@" + compilerVersion + " — recompile"
+    );
+  }
+  if (graph.source?.inputHash !== inputHash) {
+    throw new AgentDocError(
+      CODES.GRAPH_FRESHNESS,
+      "graph inputHash differs from current inputs — rebuild the graph"
+    );
+  }
+  if (graph.source?.dirty !== dirty) {
+    throw new AgentDocError(
+      CODES.GRAPH_FRESHNESS,
+      "graph dirty flag (" + graph.source?.dirty + ") differs from the current input state (" + dirty + ") — rebuild the graph"
+    );
+  }
+}
+
+export function readGraph(repo, relPath) {
+  const abs = repo.abs(relPath);
+  if (!fs.existsSync(abs)) {
+    throw new AgentDocError(
+      CODES.GRAPH_MISSING,
+      "no compiled graph at " + relPath + " — run `agentdoc compile` first",
+      { path: relPath }
+    );
+  }
+  let text;
+  try {
+    text = fs.readFileSync(abs, "utf8");
+  } catch {
+    throw new AgentDocError(CODES.GRAPH_SCHEMA, "compiled graph is not readable — rebuild it");
+  }
+  try {
+    return { graph: JSON.parse(text), text };
+  } catch {
+    throw new AgentDocError(CODES.GRAPH_SCHEMA, "compiled graph is not valid JSON — rebuild the graph", { path: relPath });
+  }
+}
+
+export function hashText(t) {
+  return "sha256:" + sha256Hex(Buffer.from(t, "utf8"));
+}
+
+export { createHash };

package/core/impact.mjs

@@ -0,0 +1,175 @@
+// Change impact.
+//
+// When an agent edits a file, the question is not "what does this file do" but
+// "what must I keep consistent, and which gate proves it". This answers that
+// from the graph alone, so the answer is available before any exploration.
+import path from "node:path";
+import { ContextIndex } from "./query.mjs";
+
+// The affected-file classification is derived from the compiled graph, not from
+// a hand-written list of technology filenames. A list would go stale for every
+// repository that is not Node-and-Go, and `impact` would silently under-report
+// there — which is worse than not answering.
+//
+// Sources of truth, all from the graph:
+//   - the canonical contract of every API entity                  -> contract
+//   - every file the compiler read                                 -> input
+//   - every extractor identity, which names the technology        -> dependency /
+//                                                                    verification
+//   - every documentation and constraint path on an entity         -> documentation
+function classify(graph, p, idx) {
+  for (const c of graph.contracts) if (c.ref === p) return "contract";
+  for (const e of graph.entities) {
+    const d = e.derived || {};
+    for (const x of d.docs || []) if (x === p) return "documentation";
+    for (const x of d.constraints || []) if (x === p) return "documentation";
+    for (const x of d.runbooks || []) if (x === p) return "documentation";
+  }
+  if (/\.(md|mdx|adoc|rst|txt)$/.test(p)) return "documentation";
+  if (/(^|\/)migrations?\//.test(p)) return "resource";
+  // A Resource named directly — by ref, or by the descriptor file that declares
+  // it — is a resource change. Without this, `impact resource:default/x` reported
+  // nothing at all, and a change to a dataset's owner was invisible. The loop
+  // below that walks `usesResource` was written for exactly this case and could
+  // never run, because nothing ever populated `resources` for a Resource entity.
+  const entity = idx && idx.resolve(p);
+  if (entity && entity.kind === "Resource") return "resource";
+  if (/\.ya?ml$/.test(p) && /\.github\/workflows\//.test(p)) return "verification";
+  const inputs = new Set(graph.provenance.map((x) => x.path));
+  if (inputs.has(p)) return "input";
+  return null;
+}
+
+export function impact(graph, changedPaths) {
+  const idx = new ContextIndex(graph);
+  const affectedComponents = new Map(); // ref -> Set(reason)
+  const add = (ref, reason) => {
+    if (!idx.byRef.has(ref)) return;
+    if (!affectedComponents.has(ref)) affectedComponents.set(ref, new Set());
+    affectedComponents.get(ref).add(reason);
+  };
+
+  const contracts = new Set();
+  const docs = new Set();
+  const resources = new Set();
+  const verificationPaths = new Set();
+  const dependencyPaths = new Set();
+  const catalogPaths = new Set();
+  const unmatched = [];
+
+  for (const raw of changedPaths) {
+    const p = raw.replace(/^\.\//, "");
+    const entity = idx.resolve(p);
+    // A Resource is not a component. Adding it to `affectedComponents` put a
+    // `resource:` ref in a list an agent reads as "components you must check",
+    // while the components actually bound to it went unmentioned.
+    if (entity && entity.kind === "Component") add(entity.ref, "direct file change inside " + entity.ref);
+    else unmatched.push(p);
+    const kind = classify(graph, p, idx);
+    if (kind === "contract") contracts.add(p);
+    if (kind === "documentation") docs.add(p);
+    if (kind === "resource") resources.add(p);
+    if (kind === "verification") verificationPaths.add(p);
+    if (kind === "input") dependencyPaths.add(p);
+    if (p.startsWith("agentdoc/")) catalogPaths.add(p);
+  }
+
+  // A contract change reaches its provider and every consumer.
+  for (const c of contracts) {
+    for (const api of graph.entities.filter((e) => e.kind === "API")) {
+      if (api.entity.spec.contract?.ref !== c) continue;
+      for (const r of graph.relations.filter((r) => (r.type === "providesApi" && r.targetRef === api.ref) || (r.type === "consumesApi" && r.targetRef === api.ref))) {
+        add(r.sourceRef, "affected by contract " + c);
+      }
+    }
+  }
+
+  // Changing a component reaches the components that depend on it, and the
+  // components it schedules or is scheduled by. Two hops: a direct dependent
+  // and a dependent-of-a-dependent is the practical blast radius; beyond that
+  // the graph stops being a routing aid and becomes a dump.
+  for (const start of [...affectedComponents.keys()]) {
+    for (let hop = 0; hop < 2; hop++) {
+      for (const r of graph.relations) {
+        if (r.type === "buildDependencyOf" || r.type === "testDependencyOf" || r.type === "buildDependsOn" || r.type === "testDependsOn") {
+          if (r.targetRef === start) add(r.sourceRef, "depends on a changed component");
+          if (r.sourceRef === start) add(r.targetRef, "a dependent of a changed component");
+        }
+        if (r.type === "schedules" || r.type === "scheduledBy" || r.type === "runtimeCalls" || r.type === "runtimeCalledBy") {
+          if (r.sourceRef === start) add(r.targetRef, "connected to a changed component by " + r.type);
+          if (r.targetRef === start) add(r.sourceRef, "connected to a changed component by " + r.type);
+        }
+      }
+    }
+  }
+
+  // A dependency manifest change reaches both directions of the edge.
+  for (const d of dependencyPaths) {
+    for (const r of graph.relations) {
+      if (r.type !== "buildDependsOn" && r.type !== "testDependsOn") continue;
+      if (r.attributes?.package === path.basename(d)) {
+        add(r.sourceRef, "dependency manifest " + d + " changed");
+        add(r.targetRef, "depended on by a component whose manifest changed");
+      }
+    }
+  }
+
+  // A documentation change reaches the component that owns it.
+  for (const d of docs) {
+    for (const e of graph.entities) {
+      const d2 = e.derived || {};
+      if ((d2.docs || []).includes(d) || (d2.constraints || []).includes(d) || (d2.runbooks || []).includes(d)) {
+        add(e.ref, "owns documentation " + d);
+      }
+      if (e.entity.spec?.context && Object.values(e.entity.spec.context).flat().includes(d)) add(e.ref, "declared context link " + d);
+    }
+  }
+
+  // A resource change reaches every component bound to it. Matched on the full
+  // ref or on a path that lies under the Resource's own source root, so a
+  // Resource ref and its migration directory both reach the same components.
+  for (const r of resources) {
+    const refMatch = r.match(/^[a-z]+:[^/]+\/(.+)$/);
+    const refName = refMatch ? refMatch[1] : null;
+    for (const rel of graph.relations) {
+      if (rel.type !== "usesResource" && rel.type !== "resourceUsedBy") continue;
+      const bound = rel.type === "usesResource" ? rel.targetRef : rel.sourceRef;
+      const user = rel.type === "usesResource" ? rel.sourceRef : rel.targetRef;
+      const name = bound.split("/").slice(1).join("/");
+      if ((refName && name === refName) || r.includes(name)) {
+        add(user, "resource change touches " + bound);
+      }
+    }
+  }
+
+  const refs = [...affectedComponents.keys()].sort();
+  const verification = graph.verification.filter((v) => v.componentRefs.some((r) => refs.includes(r)));
+  const conflicts = graph.conflicts.filter((c) => refs.includes(c.subject));
+  const journeys = graph.journeys.filter((j) => j.components.some((r) => refs.includes(r)));
+
+  return {
+    changedFiles: changedPaths.slice().sort(),
+    unmatchedFiles: unmatched.sort(),
+    affectedComponents: refs.map((ref) => ({ ref, reasons: [...affectedComponents.get(ref)].sort() })),
+    affectedContracts: [...contracts].sort(),
+    affectedDocs: [...docs].sort(),
+    affectedResources: [...resources].sort(),
+    affectedInputs: [...dependencyPaths].sort(),
+    affectedVerification: [...verificationPaths].sort(),
+    affectedCatalog: [...catalogPaths].sort(),
+    catalogSourceChanged: catalogPaths.size > 0,
+    // Any file the compiler read is a graph input: changing it invalidates the
+    // committed graph even when no descriptor changed.
+    graphWillBeStale: graphAffected(graph, changedPaths),
+    recommendedVerification: verification.map((v) => ({ id: v.id, tier: v.tier, command: v.command })).slice(0, 25),
+    openConflicts: conflicts.map((c) => ({ id: c.id, subject: c.subject, key: c.key, status: c.status, kind: c.kind })),
+    relatedJourneys: journeys.map((j) => ({ id: j.id, description: j.description })),
+  };
+}
+
+function graphAffected(graph, changedPaths) {
+  const inputs = new Set(graph.provenance.map((p) => p.path));
+  for (const p of changedPaths) if (inputs.has(p)) return true;
+  const idx = new ContextIndex(graph);
+  return changedPaths.some((p) => idx.resolve(p));
+}

package/core/indexes.mjs

@@ -0,0 +1,165 @@
+// Typed non-entity indexes: interfaces.events, externalDependencies,
+// capabilities, verification, journeys. Nothing here is an entity and nothing
+// here may appear as a relation endpoint.
+import { CODES, AgentDocError } from "./codes.mjs";
+import { contractDefRegex } from "./contracts.mjs";
+
+const classifyContractDef = contractDefRegex;
+
+// A literal like "orders.created.v1" folds into a declared family
+// "orders.created.*" when that family is also declared. Folding is
+// deterministic and its provenance is rebound to the merged record.
+function familyOf(pattern, families) {
+  for (const fam of families) {
+    const prefix = fam.replace(/\*$/, "").replace(/>$/, "");
+    if (prefix && pattern.startsWith(prefix)) return fam;
+  }
+  return null;
+}
+
+export function plausibilityCheck(ctx) {
+  const prefixes = ctx.cfg.discovery.eventPatternPrefixes;
+  const ok = (p) => {
+    if (typeof p !== "string" || p.length === 0 || p.length > 200) return false;
+    if (!/^[A-Za-z0-9][A-Za-z0-9._>\*-]*$/.test(p)) return false;
+    if (!prefixes || prefixes.length === 0) return true;
+    return prefixes.some((pre) => p.startsWith(pre));
+  };
+  return ok;
+}
+
+export function buildIndexes(ctx) {
+  const { prov, diagnostics } = ctx;
+  const plausible = plausibilityCheck(ctx);
+  const events = [];
+  const merged = new Map();
+  const mergeInto = (pattern, rec) => {
+    if (!merged.has(pattern)) merged.set(pattern, { producers: new Set(), consumers: new Set(), provs: new Set(), contract: rec.contract });
+    const m = merged.get(pattern);
+    if (rec.contract) m.contract = rec.contract;
+    for (const x of rec.producers) m.producers.add(x);
+    for (const x of rec.consumers) m.consumers.add(x);
+    for (const p of rec.provs) m.provs.add(p);
+  };
+  const raw = [...ctx.events.keys()].filter((p) => plausible(p));
+  for (const [p, rec] of ctx.events) {
+    if (plausible(p)) continue;
+    diagnostics.push({
+      severity: "warning",
+      code: "AGENTDOC_EVENT_UNRESOLVED",
+      subject: p,
+      message: "event subject '" + p + "' does not match the configured event subject shape; left out of the interface index",
+    });
+    // The subject is not in the index, so its evidence must stop claiming to
+    // prove it. The warning still surfaces it to a reviewer.
+    for (const pr of rec.provs) pr.subjects.delete("evt:" + p);
+  }
+  const families = new Set(raw.filter((p) => p.endsWith(".*") || p.endsWith(".>")));
+  for (const [pattern, rec] of ctx.events) {
+    if (!plausible(pattern)) continue;
+    const fam = families.has(pattern) ? null : familyOf(pattern, families);
+    mergeInto(fam || pattern, rec);
+    if (fam) {
+      for (const p of rec.provs) {
+        if (p.subjects.has("evt:" + pattern)) {
+          p.subjects.delete("evt:" + pattern);
+          p.subjects.add("evt:" + fam);
+        }
+      }
+    }
+  }
+
+  for (const [pattern, rec] of [...merged.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    const contract = rec.contract;
+    if (!contract || !ctx.repo.exists(contract.ref)) {
+      diagnostics.push({
+        severity: "error",
+        code: CODES.EVENT_CONTRACT,
+        subject: pattern,
+        message: "event pattern '" + pattern + "' has no resolvable canonical contract" + (contract ? ": " + contract.ref : ""),
+        paths: contract ? [contract.ref] : [],
+      });
+      continue;
+    }
+    const resolution = rec.producers.size > 0 ? "resolved" : "unresolved";
+    if (resolution === "unresolved") {
+      diagnostics.push({
+        severity: "warning",
+        code: "AGENTDOC_EVENT_UNRESOLVED",
+        subject: pattern,
+        refs: [...rec.consumers].sort(),
+        message: "event pattern '" + pattern + "' has " + rec.consumers.size + " consumer(s) but no observed producer",
+        paths: [contract.ref],
+      });
+    }
+    events.push({
+      pattern,
+      producers: [...rec.producers].sort(),
+      consumers: [...rec.consumers].sort(),
+      contract,
+      provs: rec.provs,
+      resolution,
+    });
+  }
+
+  const externalDependencies = [...ctx.externals.values()]
+    .sort((a, b) => (a.componentRef + "|" + a.name < b.componentRef + "|" + b.name ? -1 : 1))
+    .map((r) => ({ componentRef: r.componentRef, name: r.name, role: r.role, mechanism: r.mechanism, evidenceClass: r.evidenceClass, provs: r.provs }));
+
+  const capabilities = [...ctx.capabilities.values()]
+    .sort((a, b) => (a.componentRef + "|" + a.name < b.componentRef + "|" + b.name ? -1 : 1))
+    .map((r) => ({ componentRef: r.componentRef, name: r.name, evidenceClass: r.evidenceClass, provs: r.provs }));
+
+  const verification = [...ctx.verification.values()]
+    .sort((a, b) => (a.id < b.id ? -1 : 1))
+    .map((v) => ({
+      id: v.id,
+      componentRefs: [...v.componentRefs].sort(),
+      tier: v.tier,
+      command: v.command,
+      configPaths: [...(v.configPaths || [])].sort(),
+      provs: v.provs,
+    }));
+
+  const journeys = (ctx.sources.journeys || []).map((j) => ({
+    id: j.id,
+    description: j.description,
+    components: j.components,
+    notes: j.notes || null,
+    provs: new Set([prov.add("declared", ctx.journeysPath, "journey-extractor", ["jou:" + j.id])]),
+  }));
+
+  return { events, externalDependencies, capabilities, verification, journeys };
+}
+
+// Every contract file under a configured contract root must be claimed by
+// exactly one API descriptor, and no contract may be claimed twice.
+export function checkContractCoverage(ctx) {
+  const errors = [];
+  const claimed = new Map();
+  for (const api of ctx.sources.entities.filter((e) => e.kind === "API" && e.doc.spec.contract?.ref)) {
+    const cref = api.doc.spec.contract.ref;
+    if (claimed.has(cref)) {
+      errors.push(new AgentDocError(
+        CODES.CONTRACT_SHARED,
+        "contract.ref '" + cref + "' is claimed by two APIs: " + claimed.get(cref) + " and " + api.ref,
+        { path: api.file, ref: api.ref }
+      ));
+    }
+    claimed.set(cref, api.ref);
+  }
+  const defRe = classifyContractDef();
+  for (const rootDir of ctx.cfg.discovery.contractRoots || []) {
+    if (!ctx.repo.isDir(rootDir)) continue;
+    for (const f of ctx.repo.walk(rootDir)) {
+      if (defRe.test(f) && !claimed.has(f)) {
+        errors.push(new AgentDocError(
+          CODES.CONTRACT_UNCLAIMED,
+          "canonical contract definition '" + f + "' is not referenced by any API contract.ref",
+          { path: f }
+        ));
+      }
+    }
+  }
+  return errors;
+}