agent-doc-system 0.0.0-stage → 1.0.0

package/core/query.mjs

@@ -0,0 +1,384 @@
+// Context router.
+//
+// The job is routing, not documentation concatenation. Given a source path or
+// an entity ref, return the smallest set of facts an agent needs to work
+// safely on that subject — and refuse to answer from a stale graph.
+//
+// Everything returned is budgeted: relations, interfaces, resources, journeys
+// and verification entries are all capped, with the overflow reported rather
+// than silently dropped, so an agent can see that it is seeing a slice.
+import { AgentDocError, CODES } from "./codes.mjs";
+import { assertNoSecretsInText } from "./secrets.mjs";
+
+const DEFAULT_BUDGET = {
+  relations: 40,
+  events: 20,
+  externals: 15,
+  capabilities: 10,
+  verification: 12,
+  journeys: 10,
+  conflicts: 20,
+  assertions: 25,
+  provenance: 20,
+  contracts: 10,
+};
+
+export class ContextIndex {
+  constructor(graph) {
+    this.graph = graph;
+    this.byRef = new Map(graph.entities.map((e) => [e.ref, e]));
+    this.byPath = new Map();
+    for (const e of graph.entities) {
+      const sp = e.derived && e.derived.sourcePath;
+      if (!sp) continue;
+      this.byPath.set(sp, e);
+      // Longest path first so a nested path resolves to its own component
+      // rather than to a parent.
+    }
+    // Documentation and constraint files a descriptor links resolve to their
+    // component, even when they live outside the source root. Following a
+    // stale document to the code it describes is exactly the migration case.
+    this.byDoc = new Map();
+    for (const e of graph.entities) {
+      const ctxPaths = [
+        ...(((e.entity.spec || {}).context || {}).docs || []),
+        ...(((e.entity.spec || {}).context || {}).constraints || []),
+        ...(((e.entity.spec || {}).context || {}).runbooks || []),
+        ...(e.derived || {}).docs || [],
+        ...(e.derived || {}).constraints || [],
+        ...(e.derived || {}).runbooks || [],
+      ];
+      for (const p of ctxPaths) if (!this.byDoc.has(p)) this.byDoc.set(p, e);
+    }
+    this.paths = [...this.byPath.keys()].sort((a, b) => b.length - a.length);
+    this.relationsByRef = new Map();
+    for (const r of graph.relations) {
+      if (!this.relationsByRef.has(r.sourceRef)) this.relationsByRef.set(r.sourceRef, []);
+      if (!this.relationsByRef.has(r.targetRef)) this.relationsByRef.set(r.targetRef, []);
+      this.relationsByRef.get(r.sourceRef).push(r);
+      this.relationsByRef.get(r.targetRef).push(r);
+    }
+  }
+
+  // A contract file resolves to the API entity that claims it, so "change this
+  // endpoint" routes to the boundary rather than to nothing.
+  contractFor(needle) {
+    const norm = needle.replace(/^\.\//, "").replace(/\/+$/, "");
+    let best = null;
+    for (const c of (this.graph.contracts || [])) {
+      if (norm === c.ref || norm.startsWith(c.ref)) {
+        if (!best || c.ref.length > best.ref.length) best = c;
+      }
+    }
+    return best;
+  }
+  resolve(needle) {
+    if (this.byRef.has(needle)) return this.byRef.get(needle);
+    const norm = needle.replace(/^\.\//, "").replace(/\/+$/, "");
+    if (this.byDoc.has(norm)) return this.byDoc.get(norm);
+    if (this.byPath.has(norm)) return this.byPath.get(norm);
+    for (const p of this.paths) {
+      if (norm === p || norm.startsWith(p + "/")) return this.byPath.get(p);
+    }
+    for (const p of this.paths) {
+      if (needle.startsWith(p + "/")) return this.byPath.get(p);
+    }
+    if (this.byDoc.has(needle)) return this.byDoc.get(needle);
+    const c = this.contractFor(needle);
+    return c ? this.byRef.get(c.apiRef) || null : null;
+  }
+}
+
+function contractsOf(graph) {
+  return graph.contracts || [];
+}
+
+export function queryContext(graph, needle, opts = {}) {
+  const budget = { ...DEFAULT_BUDGET, ...(opts.budget || {}) };
+  const idx = new ContextIndex(graph);
+  const entity = idx.resolve(needle);
+  if (!entity) {
+    throw new AgentDocError(
+      CODES.REF_UNRESOLVED,
+      "no entity resolves for '" + needle + "' — run `agentdoc audit` to see what the catalog knows about this repository"
+    );
+  }
+  const ref = entity.ref;
+  const g = graph;
+  const take = (arr, n) => ({ items: arr.slice(0, n), total: arr.length, truncated: arr.length > n });
+
+  const relations = idx.relationsByRef.get(ref) || [];
+  const neighbourRefs = new Set();
+  for (const r of relations) neighbourRefs.add(r.targetRef);
+
+  const placement = relations
+    .filter((r) => (r.type === "partOf" || r.type === "hasPart") && (r.sourceRef === ref || r.targetRef === ref))
+    .map((r) => (r.sourceRef === ref ? r.targetRef : r.sourceRef));
+  const systems = [...new Set(placement.filter((p) => p.startsWith("system:")))];
+  const domains = [...new Set(placement.filter((p) => p.startsWith("domain:")))];
+
+  // For a component these are the APIs it serves; for an API entity the subject
+  // *is* the provided surface.
+  const providedApis = entity.kind === "API"
+    ? [ref]
+    : g.relations.filter((r) => r.type === "providesApi" && r.sourceRef === ref).map((r) => r.targetRef);
+  const consumedApis = g.relations.filter((r) => r.type === "consumesApi" && r.sourceRef === ref).map((r) => r.targetRef);
+  // When the subject IS an API, the interesting question is who consumes it.
+  const apiConsumers = entity.kind === "API"
+    ? g.relations.filter((r) => r.type === "consumesApi" && r.targetRef === ref).map((r) => r.sourceRef)
+    : [];
+
+  const providerOf = (apiRef) => {
+    const r = g.relations.find((x) => x.type === "apiProvidedBy" && x.sourceRef === apiRef);
+    return r ? r.targetRef : null;
+  };
+  const apiProvider = entity.kind === "API" ? providerOf(ref) : null;
+
+  const apiRefs = new Set([...providedApis, ...consumedApis]);
+  const srcPath = (entity.derived && entity.derived.sourcePath) || null;
+  const events = g.interfaces.events.filter(
+    (e) =>
+      e.producers.includes(ref) ||
+      e.consumers.includes(ref) ||
+      // A contract library that ships the subject catalog owns those subjects,
+      // even when another component is the one that subscribes to them.
+      (srcPath && e.contract && e.contract.ref.startsWith(srcPath + "/"))
+  );
+  const externals = g.externalDependencies.filter((e) => e.componentRef === ref);
+  const capabilities = g.capabilities.filter((e) => e.componentRef === ref);
+  // For a contract subject, the checks that matter are the provider's and the
+  // consumers': changing an endpoint is proved by running their suites.
+  const verificationScope = entity.kind === "API"
+    ? [ref, ...apiConsumers, ...(apiProvider ? [apiProvider] : [])]
+    : [ref];
+  const verification = g.verification.filter((e) => e.componentRefs.some((r) => verificationScope.includes(r)));
+  const journeys = g.journeys.filter((j) => j.components.includes(ref));
+  const contracts = g.contracts.filter((c) => c.apiRef && apiRefs.has(c.apiRef));
+  const conflicts = g.conflicts.filter((c) => c.subject === ref);
+  const assertions = g.assertions.filter((a) => a.subject === ref);
+  const resources = g.relations
+    .filter((r) => r.type === "usesResource" && r.sourceRef === ref)
+    .map((r) => r.targetRef);
+  const affectedByResources = g.relations
+    .filter((r) => r.type === "usesResource" && r.targetRef === ref)
+    .map((r) => r.sourceRef);
+
+  const provIds = new Set();
+  const collect = (obj) => {
+    for (const id of obj.provenanceIds || []) provIds.add(id);
+  };
+  collect(entity);
+  relations.forEach(collect);
+  events.forEach(collect);
+  externals.forEach(collect);
+  verification.forEach(collect);
+  journeys.forEach(collect);
+  contracts.forEach(collect);
+  conflicts.forEach(collect);
+  assertions.forEach(collect);
+  const provenance = g.provenance.filter((p) => provIds.has(p.id));
+
+  const journeyPeers = new Set();
+  for (const j of journeys) for (const c of j.components) if (c !== ref) journeyPeers.add(c);
+
+  const neighbourSummaries = [...neighbourRefs]
+    .filter((r) => r !== ref)
+    .sort()
+    .map((r) => {
+      const e = idx.byRef.get(r);
+      return e ? { ref: r, kind: e.kind, name: e.name, description: e.entity.metadata.description } : { ref: r };
+    });
+
+  const out = {
+    query: { needle, resolved: ref, namespace: ref.split("/")[0].split(":")[1] },
+    entity: {
+      ref,
+      kind: entity.kind,
+      name: entity.name,
+      description: entity.entity.metadata.description,
+      spec: entity.entity.spec || {},
+      sourcePaths: entity.sourcePaths,
+      derived: entity.derived || {},
+    },
+    placement: { systems, domains },
+    relations: take(
+      relations.map((r) => ({
+        type: r.type,
+        direction: r.sourceRef === ref ? "out" : "in",
+        other: r.sourceRef === ref ? r.targetRef : r.sourceRef,
+        evidenceClass: r.evidenceClass,
+        attributes: Object.keys(r.attributes || {}).length ? r.attributes : undefined,
+        provenanceIds: r.provenanceIds,
+      })),
+      budget.relations
+    ),
+    neighbours: neighbourSummaries,
+    apis: {
+      provided: providedApis.map((a) => ({ api: a, contract: contractRef(g, a) })),
+      consumed: consumedApis.map((a) => ({ api: a, provider: providerOf(a), contract: contractRef(g, a) })),
+      provider: apiProvider,
+      consumers: [...new Set(apiConsumers)].sort(),
+      contract: entity.kind === "API" ? contractRef(g, ref) : null,
+    },
+    events: take(
+      events.map((e) => ({ pattern: e.pattern, producers: e.producers, consumers: e.consumers, resolution: e.resolution, contract: e.contract })),
+      budget.events
+    ),
+    resources: { used: resources, usedBy: affectedByResources },
+    externalDependencies: take(
+      externals.map((e) => ({ name: e.name, role: e.role, mechanism: e.mechanism, evidenceClass: e.evidenceClass })),
+      budget.externals
+    ),
+    capabilities: take(capabilities.map((c) => ({ name: c.name, evidenceClass: c.evidenceClass })), budget.capabilities),
+    constraints: {
+      docs: (entity.derived && entity.derived.docs) || [],
+      constraints: (entity.derived && entity.derived.constraints) || [],
+      runbooks: (entity.derived && entity.derived.runbooks) || [],
+    },
+    verification: take(
+      verification.map((v) => ({ id: v.id, tier: v.tier, command: v.command, configPaths: v.configPaths })),
+      budget.verification
+    ),
+    journeys: take(
+      journeys.map((j) => ({ id: j.id, description: j.description, components: j.components })),
+      budget.journeys
+    ),
+    // A journey is a claim that these components act together. Touching one of
+    // them means the others are in scope, and naming them is cheaper for the
+    // agent than rediscovering the coupling.
+    journeyPeers: [...journeyPeers].sort(),
+    contracts: take(contracts, budget.contracts),
+    authority: {
+      conflicts: take(
+        conflicts.map((c) => ({
+          id: c.id, key: c.key, kind: c.kind, status: c.status,
+          detail: c.detail, election: c.election,
+          assertions: c.assertionIds.map((id) => {
+            const a = g.assertions.find((x) => x.id === id);
+            return a ? { id: a.id, evidenceClass: a.evidenceClass, confidence: a.confidence, value: a.value, status: a.status, semantics: a.semantics, observed: a.observed } : { id };
+          }),
+        })),
+        budget.conflicts
+      ),
+      assertions: take(
+        assertions.map((a) => ({
+          id: a.id, key: a.key, value: a.value, evidenceClass: a.evidenceClass,
+          confidence: a.confidence, status: a.status, semantics: a.semantics,
+        })),
+        budget.assertions
+      ),
+      observations: g.observations
+        .filter((o) => o.facts.some((f) => f.subject === ref))
+        .map((o) => ({
+          id: o.id, environment: o.environment, sourceSystem: o.sourceSystem,
+          collector: o.collector, capturedAt: o.capturedAt, maxAgeDays: o.maxAgeDays,
+          evidenceBundle: o.evidenceBundle,
+          facts: o.facts.filter((f) => f.subject === ref),
+        })),
+    },
+    provenance: take(provenance.map((p) => ({ id: p.id, class: p.class, path: p.path, extractor: p.extractor.name, contentHash: p.contentHash })), budget.provenance),
+    globalGates: g.gates.map((x) => ({ id: x.id, tier: x.tier, command: x.command })),
+    // Everything a reviewer committed to re-examining, in one place. A review
+    // condition nobody can see is a review condition nobody performs.
+    reviewCommitments: [
+      ...g.conflicts
+        .filter((c) => c.status !== "unresolved")
+        .map((c) => ({
+          kind: c.kind, subject: c.subject, key: c.key, status: c.status,
+          basis: c.election.basis, ruleId: c.election.ruleId,
+          // The governing authority rule's own re-examination condition. When
+          // there is no rule the fact stayed unresolved, and `null` says exactly
+          // that — it is not a missing value to be papered over with a pointer
+          // to a record that was never written.
+          reviewWhen: c.election.reviewWhen ?? null,
+        })),
+      ...g.diagnostics
+        .filter((d) => d.acceptance)
+        .map((d) => ({
+          kind: d.code, subject: d.subject || null, status: "accepted",
+          classification: d.acceptance.classification,
+          reason: d.acceptance.reason, reviewWhen: d.acceptance.reviewWhen,
+        })),
+      ...g.assertions
+        .filter((a) => a.review)
+        .map((a) => ({
+          kind: "reviewed-override", subject: a.subject, key: a.key, status: a.status,
+          reason: a.review.reason, reviewWhen: a.review.reviewWhen,
+        })),
+    ],
+  };
+  // Truncation is reported for every capped section, including the nested ones
+  // inside `authority`. A silently shortened conflict list is the most damaging
+  // cut this command could make.
+  out.truncated = [];
+  for (const [k, v] of Object.entries(out)) {
+    if (v && typeof v === "object" && v.truncated) out.truncated.push(k);
+    if (k === "authority" && v) {
+      for (const [ak, av] of Object.entries(v)) {
+        if (av && typeof av === "object" && av.truncated) out.truncated.push("authority." + ak);
+      }
+    }
+  }
+  assertNoSecretsInText(JSON.stringify(out), "query result");
+  return out;
+}
+
+function contractRef(graph, apiRef) {
+  const e = graph.entities.find((x) => x.ref === apiRef);
+  return e ? e.entity.spec.contract : null;
+}
+
+// Compact markdown rendering for a prompt or a human. Same routing, less tokens.
+export function renderContext(ctx) {
+  const L = [];
+  const e = ctx.entity;
+  L.push("# " + e.ref + " (" + e.kind + ")");
+  L.push(e.description);
+  if (e.derived.sourcePath) L.push("- source: " + e.derived.sourcePath);
+  if (e.derived.runtimes?.length) L.push("- runtimes: " + e.derived.runtimes.join(", "));
+  if (e.derived.languages?.length) L.push("- languages: " + e.derived.languages.join(", "));
+  if (ctx.placement.systems.length) L.push("- system: " + ctx.placement.systems.join(", "));
+  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.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.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(", "));
+  if (ctx.constraints.constraints.length) L.push("- CONSTRAINTS: " + ctx.constraints.constraints.join(", "));
+  if (ctx.constraints.docs.length) L.push("- docs: " + ctx.constraints.docs.join(", "));
+  if (ctx.constraints.runbooks.length) L.push("- runbooks: " + ctx.constraints.runbooks.join(", "));
+  if (ctx.verification.items.length) {
+    L.push("- verify:");
+    for (const v of ctx.verification.items) L.push("  - [" + v.tier + "] " + v.command);
+  }
+  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) {
+      L.push("  - " + c.key + " [" + c.kind + "/" + c.status + "] " + (c.detail || ""));
+      for (const a of c.assertions) L.push("    - " + a.evidenceClass + "/" + a.confidence + ": " + JSON.stringify(a.value));
+    }
+  }
+  if (ctx.reviewCommitments.length) {
+    L.push("- REVIEW COMMITMENTS (re-check when the condition is met):");
+    for (const r of ctx.reviewCommitments) {
+      // An absent condition is stated as absent. Printing a pointer to a record
+      // that does not exist is worse than printing nothing: it looks actionable
+      // and is not.
+      const when = r.reviewWhen
+        ? r.reviewWhen
+        : "NO REVIEW CONDITION RECORDED — " + r.kind + " " + (r.subject || "") + " " + (r.key || "") +
+          " is settled with none; re-examine it now";
+      L.push("  - " + (r.subject || "repository") + " " + (r.key || r.kind) + ": " + when);
+    }
+  }
+  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 + ")");
+  }
+  const neighbours = ctx.neighbours.filter((n) => n.ref !== e.ref);
+  if (neighbours.length) L.push("- neighbours: " + neighbours.map((n) => n.ref).join(", "));
+  return L.join("\n");
+}

package/core/relations.mjs

@@ -0,0 +1,286 @@
+// Relation materialisation.
+//
+// No relation is ever authored. Placement comes from authored placement fields,
+// provider edges from the API descriptor, everything else from deterministic
+// extractors or bounded reviewed overrides. Inversions are generated, the kind
+// pair is validated, and duplicates merge their provenance instead of forking
+// the graph.
+import { CODES, AgentDocError } from "./codes.mjs";
+import { PROV_TO_EVIDENCE } from "./authority/classes.mjs";
+
+export const INVERSE = Object.freeze({
+  partOf: "hasPart",
+  hasPart: "partOf",
+  providesApi: "apiProvidedBy",
+  apiProvidedBy: "providesApi",
+  consumesApi: "apiConsumedBy",
+  apiConsumedBy: "consumesApi",
+  buildDependsOn: "buildDependencyOf",
+  buildDependencyOf: "buildDependsOn",
+  testDependsOn: "testDependencyOf",
+  testDependencyOf: "testDependsOn",
+  runtimeCalls: "runtimeCalledBy",
+  runtimeCalledBy: "runtimeCalls",
+  usesResource: "resourceUsedBy",
+  resourceUsedBy: "usesResource",
+  schedules: "scheduledBy",
+  scheduledBy: "schedules",
+});
+
+export const KIND_PAIRS = Object.freeze({
+  partOf: { Component: ["System", "Domain"], System: ["Domain"], Resource: ["System"] },
+  hasPart: { System: ["Component", "Resource"], Domain: ["Component", "System"] },
+  providesApi: { Component: ["API"] },
+  apiProvidedBy: { API: ["Component"] },
+  consumesApi: { Component: ["API"] },
+  apiConsumedBy: { API: ["Component"] },
+  buildDependsOn: { Component: ["Component"] },
+  buildDependencyOf: { Component: ["Component"] },
+  testDependsOn: { Component: ["Component"] },
+  testDependencyOf: { Component: ["Component"] },
+  runtimeCalls: { Component: ["Component"] },
+  runtimeCalledBy: { Component: ["Component"] },
+  usesResource: { Component: ["Resource"] },
+  resourceUsedBy: { Resource: ["Component"] },
+  schedules: { Component: ["Component"] },
+  scheduledBy: { Component: ["Component"] },
+});
+
+// A closed whitelist of attribute keys per relation type. An unknown key is a
+// compiler error, so the graph cannot accumulate unvalidated payload — and a
+// new relation type cannot silently start carrying arbitrary data.
+export const ATTRIBUTE_KEYS = Object.freeze({
+  partOf: [], hasPart: [],
+  providesApi: [], apiProvidedBy: [],
+  consumesApi: ["via"], apiConsumedBy: ["via"],
+  buildDependsOn: ["via", "package"], buildDependencyOf: ["via", "package"],
+  testDependsOn: ["via", "package"], testDependencyOf: ["via", "package"],
+  runtimeCalls: ["transport", "contractRef", "deliverySemantics"],
+  runtimeCalledBy: ["transport", "contractRef", "deliverySemantics"],
+  usesResource: ["via", "client"], resourceUsedBy: ["via", "client"],
+  schedules: ["via", "route"], scheduledBy: ["via", "route"],
+});
+
+// Attributes that record *how* an edge was found, not what the edge is.
+// `via` is the derivation route ("npm-manifest", "source-import",
+// "reviewed-override"). It must not take part in a relation's identity: if it
+// did, the single fact "accounts consumes the OCR admin API" would appear once
+// per adapter that noticed it, and a repository's edge count would measure
+// adapter overlap rather than architecture. `package` and `route` are the
+// opposite case — they name the specific instance, so two of them are two real
+// edges and are kept apart deliberately.
+const DERIVATION_ATTRS = new Set(["via"]);
+
+// The identity of a relation: what it asserts, ignoring how it was found.
+export function relationIdentity(e) {
+  const attrs = {};
+  for (const k of Object.keys(e.attributes || {}).sort()) {
+    if (!DERIVATION_ATTRS.has(k)) attrs[k] = e.attributes[k];
+  }
+  return e.type + "|" + e.sourceRef + "|" + e.targetRef + "|" + canonicalAttrs(attrs);
+}
+
+export function canonicalAttrs(attrs) {
+  return Object.keys(attrs || {}).sort().map((k) => k + "=" + JSON.stringify(attrs[k])).join("|");
+}
+
+export function buildRelations(ctx) {
+  const { entities, byRef } = ctx.sources;
+  const { refs } = ctx;
+  const errors = [];
+  const forward = [];
+
+  const add = (type, sourceRef, targetRef, attributes, provRecs, evidenceClass) => {
+    forward.push({
+      type,
+      sourceRef,
+      targetRef,
+      attributes: attributes || {},
+      provs: new Set(provRecs.filter(Boolean)),
+      evidenceClass: evidenceClass || evidenceOf(provRecs),
+    });
+  };
+
+  // placement
+  for (const e of entities) {
+    const spec = e.doc.spec || {};
+    const p = () => ctx.prov.add("declared", e.file, "descriptor-reader", ["rel:pending"]);
+    if (e.kind === "Component") {
+      if (spec.system) add("partOf", e.ref, refs.refFor("System", spec.system), {}, [p()], "AUTHORED");
+      else if (spec.domain) add("partOf", e.ref, refs.refFor("Domain", spec.domain), {}, [p()], "AUTHORED");
+    } else if (e.kind === "System" && spec.domain) {
+      add("partOf", e.ref, refs.refFor("Domain", spec.domain), {}, [p()], "AUTHORED");
+    } else if (e.kind === "Resource" && spec.system) {
+      add("partOf", e.ref, refs.refFor("System", spec.system), {}, [p()], "AUTHORED");
+    }
+  }
+
+  // provider edges
+  for (const e of entities.filter((x) => x.kind === "API")) {
+    add("providesApi", e.doc.spec.provider, e.ref, {}, [ctx.prov.add("declared", e.file, "api-contract-extractor", ["rel:pending"])], "AUTHORED");
+  }
+
+  // extractor edges
+  for (const e of ctx.edges) add(e.type, e.sourceRef, e.targetRef, e.attributes, [...e.provs], e.evidenceClass);
+
+  // reviewed overrides
+  for (const e of ctx.overrideEdges) add(e.type, e.sourceRef, e.targetRef, e.attributes, [...e.provs], "REVIEWED_OVERRIDE");
+
+  // An API contract owns the boundary: a runtime call that duplicates the
+  // canonical contract is a modelling error, not a second fact.
+  const apiProviderOf = new Map();
+  const contractOf = new Map();
+  for (const e of entities.filter((x) => x.kind === "API")) {
+    apiProviderOf.set(e.ref, e.doc.spec.provider);
+    if (e.doc.spec.contract?.ref) contractOf.set(e.ref, e.doc.spec.contract.ref);
+  }
+  const consumed = new Map();
+  for (const e of forward) {
+    if (e.type !== "consumesApi") continue;
+    if (!consumed.has(e.sourceRef)) consumed.set(e.sourceRef, new Set());
+    consumed.get(e.sourceRef).add(e.targetRef);
+  }
+  const filtered = forward.filter((e) => {
+    if (e.type !== "runtimeCalls") return true;
+    for (const apiRef of consumed.get(e.sourceRef) || []) {
+      if (apiProviderOf.get(apiRef) !== e.targetRef) continue;
+      if (contractOf.get(apiRef) && contractOf.get(apiRef) === e.attributes?.contractRef) {
+        errors.push(new AgentDocError(
+          CODES.RELATION_CONTRACT_DUP,
+          "runtime call " + e.sourceRef + " -> " + e.targetRef + " duplicates canonical API contract " + contractOf.get(apiRef),
+          { ref: e.sourceRef }
+        ));
+        return false;
+      }
+    }
+    return true;
+  });
+
+  const all = [];
+  for (const e of filtered) {
+    all.push(e);
+    const inv = INVERSE[e.type];
+    if (!inv) {
+      errors.push(new AgentDocError(CODES.RELATION_KIND, "unknown relation type '" + e.type + "'", { ref: e.sourceRef }));
+      continue;
+    }
+    all.push({ type: inv, sourceRef: e.targetRef, targetRef: e.sourceRef, attributes: e.attributes, provs: e.provs, evidenceClass: e.evidenceClass });
+  }
+
+  const kindOf = (ref) => refs.kindOfRef(ref);
+  for (const e of all) {
+    const sk = kindOf(e.sourceRef);
+    const tk = kindOf(e.targetRef);
+    if (!sk || !tk || !byRef.has(e.sourceRef) || !byRef.has(e.targetRef)) {
+      errors.push(new AgentDocError(
+        CODES.RELATION_UNRESOLVED,
+        "relation endpoint does not resolve to a real entity: " + e.sourceRef + " -> " + e.targetRef
+      ));
+      continue;
+    }
+    const allowed = KIND_PAIRS[e.type]?.[sk] || [];
+    if (!allowed.includes(tk)) {
+      errors.push(new AgentDocError(CODES.RELATION_KIND, "invalid kind pair for " + e.type + ": " + sk + " -> " + tk, { ref: e.sourceRef }));
+    }
+    const allowedAttrs = ATTRIBUTE_KEYS[e.type];
+    if (!allowedAttrs) {
+      errors.push(new AgentDocError(CODES.RELATION_KIND, "unknown relation type '" + e.type + "'", { ref: e.sourceRef }));
+    } else {
+      const attrKeys = Object.keys(e.attributes || {});
+      for (const k of attrKeys) {
+        if (!allowedAttrs.includes(k)) {
+          errors.push(new AgentDocError(
+            CODES.RELATION_KIND,
+            "relation " + e.type + " does not allow attribute '" + k + "' (allowed: " + allowedAttrs.join(", ") + ")",
+            { ref: e.sourceRef }
+          ));
+        }
+      }
+      if (e.type === "runtimeCalls" || e.type === "runtimeCalledBy") {
+        const a = e.attributes || {};
+        if (!["http", "service-binding", "signed-http", "grpc", "queue", "in-process"].includes(a.transport)) {
+          errors.push(new AgentDocError(CODES.RELATION_KIND, e.type + " requires a known transport", { ref: e.sourceRef }));
+        }
+        if (!a.contractRef) {
+          errors.push(new AgentDocError(CODES.RELATION_KIND, e.type + " requires contractRef", { ref: e.sourceRef }));
+        }
+      }
+    }
+  }
+
+  const seen = new Map();
+  const out = [];
+  const vias = new Map();
+  for (const e of all) {
+    const key = relationIdentity(e);
+    if (seen.has(key)) {
+      const prev = seen.get(key);
+      for (const p of e.provs) prev.provs.add(p);
+      // A corroborated edge keeps the label its evidence supports, recomputed
+      // from the merged provenance rather than promoted by a fixed order.
+      prev.evidenceClass = evidenceOf([...prev.provs]);
+      // Every derivation route that found it, so merging never discards the
+      // fact that a second, independent adapter agreed.
+      const v = vias.get(key);
+      if (v && e.attributes && e.attributes.via) v.add(e.attributes.via);
+      continue;
+    }
+    const canon = {};
+    for (const k of Object.keys(e.attributes || {}).sort()) canon[k] = e.attributes[k];
+    e.attributes = canon;
+    if (canon.via !== undefined) {
+      vias.set(key, new Set([canon.via]));
+      delete e.attributes.via;
+    }
+    seen.set(key, e);
+    out.push(e);
+  }
+  // Re-attach the sorted derivation routes.
+  for (const e of out) {
+    const key = relationIdentity(e);
+    const v = vias.get(key);
+    if (v) {
+      const canon = {};
+      canon.via = [...v].sort();
+      for (const k of Object.keys(e.attributes).sort()) canon[k] = e.attributes[k];
+      e.attributes = canon;
+    }
+  }
+  out.sort((a, b) => {
+    const ka = relationIdentity(a);
+    const kb = relationIdentity(b);
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+
+  const keys = new Set(out.map(relationIdentity));
+  for (const e of out) {
+    const invKey = relationIdentity({ type: INVERSE[e.type], sourceRef: e.targetRef, targetRef: e.sourceRef, attributes: e.attributes });
+    if (!keys.has(invKey)) {
+      errors.push(new AgentDocError(CODES.RELATION_MISSING_INVERSE, "missing inverse for " + e.type + " " + e.sourceRef + " -> " + e.targetRef));
+    }
+  }
+  return { relations: out, errors };
+}
+
+// The label on a relation records which classes back it.
+//
+// It does NOT pick a winner by strength. A precedence list here is a global
+// precedence order hiding in a helper — the exact thing the authority model
+// forbids — and it was actively wrong: a reviewed override corroborated by a
+// source reference was relabelled AUTHORED, so the same fact read as a weaker,
+// purely-authored claim on the relation while its assertion read
+// REVIEWED_OVERRIDE. The graph contradicted itself about its own highest-
+// authority input.
+//
+// So: when the evidence agrees there is one class and it is reported. When it
+// disagrees, this elects nothing. REVIEWED_OVERRIDE is reported when a human
+// interpretation is among the classes, because that is not an election between
+// competing claims — it records that someone reviewed this specific edge — and
+// suppressing it would hide the review. The full class set is always recoverable
+// from the provenance records.
+function evidenceOf(provRecs) {
+  const classes = new Set((provRecs || []).map((p) => p && p.cls).filter(Boolean).map((c) => PROV_TO_EVIDENCE[c]).filter(Boolean));
+  if (classes.size <= 1) return classes.size === 1 ? [...classes][0] : "DERIVED";
+  if (classes.has("REVIEWED_OVERRIDE")) return "REVIEWED_OVERRIDE";
+  return "DERIVED";
+}