agent-doc-system 0.0.0-stage → 1.1.0

package/core/authority/engine.mjs

@@ -0,0 +1,266 @@
+// Authority rules and conflict resolution.
+//
+// There is deliberately NO global precedence order. Authority depends on the
+// fact: an OpenAPI file may be authoritative for the desired wire contract
+// while a runtime observation is authoritative for what is deployed right now,
+// and source code is authoritative for the behaviour shipped by a commit.
+//
+// A fact with an authority rule gets an election. A fact with NO matching rule
+// and disagreeing evidence stays UNRESOLVED and raises a conflict. That is the
+// fail-closed default: silence is not a resolution.
+import { AgentDocError, CODES } from "../codes.mjs";
+import { EVIDENCE_CLASSES, CONFIDENCE } from "./classes.mjs";
+import { isNormative } from "../normative.mjs";
+
+export class AuthorityEngine {
+  constructor(rules) {
+    this.rules = (rules || []).map((r) => {
+      let re;
+      try {
+        re = new RegExp(r.keyPattern, "u");
+      } catch {
+        throw new AgentDocError(CODES.CONFIG, "authority rule " + r.id + " has an invalid keyPattern: " + r.keyPattern);
+      }
+      for (const c of r.elect) {
+        if (!EVIDENCE_CLASSES.includes(c) || c === "UNRESOLVED") {
+          throw new AgentDocError(CODES.CONFIG, "authority rule " + r.id + " cannot elect " + c);
+        }
+      }
+      return { ...r, re };
+    });
+    for (let i = 0; i < this.rules.length; i++) {
+      for (let j = i + 1; j < this.rules.length; j++) {
+        if (this.rules[i].id === this.rules[j].id) {
+          throw new AgentDocError(CODES.CONFIG, "duplicate authority rule id " + this.rules[i].id);
+        }
+      }
+    }
+  }
+  // Returns the most specific matching rule (longest pattern wins) or null.
+  ruleFor(subject, key) {
+    const target = subject + " " + key;
+    let best = null;
+    for (const r of this.rules) {
+      if (!r.re.test(target)) continue;
+      if (!best || r.keyPattern.length > best.keyPattern.length) best = r;
+    }
+    return best;
+  }
+}
+
+// Group assertions by (subject, key) and elect at most one per group.
+//
+// Election basis, in the order it is attempted — and each basis is only
+// reachable when a rule explicitly allows it:
+//   reviewed-override  an explicit human interpretation exists
+//   authority-rule     the rule's elect list contains exactly one class present
+//   superset           the elected value strictly contains the others
+//   recency            the newest runtime observation, and only if the rule says so
+//   none               fail closed
+export function resolveAssertions(assertions, authority) {
+  const groups = new Map();
+  for (const a of assertions) {
+    // An assertion a later observation supersedes stays in the graph as
+    // history but does not compete here: it cannot win an election and cannot
+    // anchor a conflict.
+    if (a.status === "superseded") continue;
+    const gk = a.subject + "\u0000" + a.key;
+    if (!groups.has(gk)) groups.set(gk, []);
+    groups.get(gk).push(a);
+  }
+
+  const conflicts = [];
+  const elections = [];
+
+  for (const [gk, list] of [...groups.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    const [subject, key] = gk.split("\u0000");
+    const distinct = distinctValues(list);
+
+    // A normative requirement is a claim about what the implementation must
+    // do, so it can only be corroborated, never elected on its own word. With
+    // no implementation evidence beside it, it stays unresolved: the gap the
+    // migration must surface.
+    const normative = list.some(isNormative);
+    if (normative && list.every((a) => isNormative(a) || a.confidence === "candidate")) {
+      // A heuristic candidate is not evidence either way: it stays a candidate,
+      // and the requirement stays unverified.
+      for (const a of list) a.status = isNormative(a) ? "unresolved" : "candidate";
+      continue;
+    }
+
+    if (distinct.length === 1) {
+      // Agreement across evidence classes is corroboration, not a conflict —
+      // but a lone heuristic candidate is not agreement with anything. It stays
+      // UNRESOLVED and never becomes an elected fact.
+      const allCandidate = list.every((a) => a.confidence === "candidate");
+      for (const a of list) a.status = allCandidate ? "candidate" : "elected";
+      const rule = authority.ruleFor(subject, key);
+      elections.push({ subject, key, ruleId: rule ? rule.id : "agreement", basis: "authority-rule", elected: list[0] });
+      if (allCandidate) {
+        conflicts.push({
+          subject,
+          key,
+          kind: "ambiguity",
+          status: "unresolved",
+          assertionIds: list.map((a) => a.id).sort(),
+          election: {
+            elected: null,
+            basis: "none",
+            ruleId: rule ? rule.id : "no-rule",
+            rationale: "only heuristic candidates exist for '" + key + "'; deterministic discovery cannot resolve it",
+            reviewWhen: rule ? rule.reviewWhen : null,
+            contradicted: [],
+          },
+        });
+      }
+      continue;
+    }
+
+    const rule = authority.ruleFor(subject, key);
+    const candidates = list.filter((a) => a.confidence !== "candidate");
+    const candidateOnly = list.length !== candidates.length;
+
+    // `reviewWhen` travels with the election so a consumer can report when this
+    // decision must be re-examined. A null here means "no rule governs it", which
+    // is a real state — and one that must never be rendered as if a condition
+    // existed.
+    const election = {
+      elected: null,
+      basis: "none",
+      ruleId: rule ? rule.id : "no-rule",
+      rationale: null,
+      reviewWhen: rule ? rule.reviewWhen : null,
+      contradicted: [],
+    };
+    let status = "unresolved";
+
+    // 0. A normative requirement and the implementation disagree. No rule may
+    //    settle that: electing the implementation waives the specification,
+    //    electing the requirement hides the missing implementation. Only a
+    //    change to one of them resolves it.
+    if (normative) {
+      election.rationale =
+        "a normative requirement disagrees with the implementation evidence; no authority rule may settle it — " +
+        "change the implementation, or change the specification and re-review its section";
+    }
+
+    // 1. reviewed override wins outright, but the divergence is still recorded.
+    const reviewed = candidates.filter((a) => a.evidenceClass === "REVIEWED_OVERRIDE");
+    if (!normative && rule && rule.elect.length === 1 && rule.elect[0] === "REVIEWED_OVERRIDE" && reviewed.length === 1) {
+      election.elected = reviewed[0];
+      election.basis = "reviewed-override";
+      election.rationale = rule.rationale;
+      status = "accepted";
+    }
+
+    // 2. authority rule with a single elected class present among candidates.
+    if (!normative && !election.elected && rule) {
+      const allowed = rule.elect.filter((c) => candidates.some((a) => a.evidenceClass === c));
+      if (allowed.length === 1) {
+        const winners = candidates.filter((a) => a.evidenceClass === allowed[0]);
+        if (winners.length === 1) {
+          election.elected = winners[0];
+          election.basis = "authority-rule";
+          election.rationale = rule.rationale;
+          status = "resolved";
+        } else if (winners.length > 1) {
+          election.rationale = "multiple same-class assertions disagree; no election";
+        }
+      } else if (allowed.length > 1) {
+        election.rationale = "authority rule " + rule.id + " elects several classes that are all present; no deterministic election";
+      }
+    }
+
+    // 3. superset: one candidate's value contains every other candidate's value.
+    if (!normative && !election.elected && candidates.length > 1) {
+      const sup = candidates.find((c) => candidates.every((o) => o === c || containsValue(c.value, o.value)));
+      if (sup) {
+        election.elected = sup;
+        election.basis = "superset";
+        election.rationale = "one observed value strictly contains the others";
+        status = "resolved";
+      }
+    }
+
+    // 4. recency: only when the rule names recency and the winner is a runtime fact.
+    if (!normative && !election.elected && rule && rule.elect.includes("OBSERVED_RUNTIME")) {
+      const runtime = candidates.filter((a) => a.evidenceClass === "OBSERVED_RUNTIME");
+      const dated = runtime.filter((a) => a.observed && a.observed.at);
+      if (dated.length > 1) {
+        const newest = dated.sort((a, b) => (a.observed.at < b.observed.at ? -1 : 1)).pop();
+        election.elected = newest;
+        election.basis = "recency";
+        election.rationale = "newest runtime observation, per authority rule " + rule.id;
+        status = "resolved";
+      }
+    }
+
+    if (!election.elected) {
+      election.rationale = election.rationale || (
+        rule
+          ? "authority rule " + rule.id + " does not resolve this disagreement"
+          : "no authority rule governs '" + key + "' for " + subject + "; fail closed"
+      );
+    }
+
+    for (const a of list) {
+      if (a === election.elected) a.status = "elected";
+      else if (a.confidence === "candidate") a.status = "candidate";
+      else a.status = "contradicted";
+    }
+    election.contradicted = list.filter((a) => a !== election.elected && a.confidence !== "candidate").map((a) => a.id);
+
+    const kind = classifyConflict(list, election, candidateOnly);
+    conflicts.push({
+      subject,
+      key,
+      kind,
+      status,
+      assertionIds: list.map((a) => a.id).sort(),
+      election,
+    });
+    elections.push({ subject, key, ruleId: election.ruleId, basis: election.basis, elected: election.elected });
+  }
+
+  return { conflicts, elections };
+}
+
+function classifyConflict(list, election, candidateOnly) {
+  const classes = new Set(list.map((a) => a.evidenceClass));
+  if (election.basis === "reviewed-override") return "reviewed-divergence";
+  // An observation that declares itself superseded no longer competes: a newer
+  // capture of the same authority system replaces it outright.
+  if (list.some((a) => a.observed && a.observed.supersedes)) return "supersession";
+  if (classes.has("OBSERVED_RUNTIME") && classes.has("AUTHORED")) return "contradiction";
+  if (classes.has("OBSERVED_RUNTIME") && classes.size === 1) return "staleness";
+  if (candidateOnly) return "ambiguity";
+  if (classes.size > 1) return "contradiction";
+  return "ambiguity";
+}
+
+export function distinctValues(list) {
+  const seen = new Map();
+  for (const a of list) {
+    const k = stable(a.value);
+    if (!seen.has(k)) seen.set(k, a.value);
+  }
+  return [...seen.values()];
+}
+
+function containsValue(big, small) {
+  if (Array.isArray(big) && Array.isArray(small)) {
+    return small.every((s) => big.some((b) => stable(b) === stable(s))) && big.length > small.length;
+  }
+  return false;
+}
+
+export function stable(v) {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return "[" + v.map(stable).join(",") + "]";
+  return "{" + Object.keys(v).sort().map((k) => JSON.stringify(k) + ":" + stable(v[k])).join(",") + "}";
+}
+
+export function assertConfidence(c) {
+  if (!CONFIDENCE.includes(c)) throw new Error("unknown confidence " + c);
+  return c;
+}

package/core/authority/facts.mjs

@@ -0,0 +1,41 @@
+// Fact model.
+//
+// A "fact" is a claim about one (subject, key) pair. Multiple facts may exist
+// for the same pair when different evidence classes disagree — that is a
+// conflict, and it is surfaced, never reconciled silently.
+//
+// Well-known keys are namespaced by domain so an authority rule can be written
+// per fact-kind rather than per project. See SPEC.md "Fact keys".
+export const FACT_KEYS = Object.freeze({
+  // what a scheduler actually runs
+  "schedule.cron": "the cron expression a platform scheduler evaluates for this component's job",
+  // what a binding actually points at
+  "binding.kind": "the kind of platform resource a declared binding resolves to",
+  "binding.target": "the concrete instance a declared binding resolves to",
+  // what an external API actually accepts
+  "contract.supports": "capabilities an external contract actually accepts",
+  "contract.version": "the deployed version of a contract",
+  // component shape
+  "component.deployable": "whether the component ships as an independently deployable artifact",
+  "component.importable": "whether the component ships as an independently importable library",
+  "component.runtime": "the runtime the deployed artifact executes on",
+  "component.language": "the implementation language of the component",
+  // governance
+  "placement.system": "the system a component is placed in",
+  "placement.domain": "the domain a component or system is placed in",
+  "resource.ownership": "which component owns a logical resource",
+  "schedule.enabled": "whether a scheduled job is enabled in the scheduler",
+  "schedule.target": "the endpoint a scheduled job invokes",
+});
+
+export function isKnownFactKey(key) {
+  return Object.prototype.hasOwnProperty.call(FACT_KEYS, key);
+}
+
+export function knownFactKeys() {
+  return Object.keys(FACT_KEYS);
+}
+
+export function assertFactKeyShape(key) {
+  return typeof key === "string" && /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/.test(key) && key.length <= 80;
+}

package/core/codes.mjs

@@ -0,0 +1,126 @@
+// Stable diagnostic/error codes. Every failure the compiler or a gate can
+// produce is named here so tests, CI and the skill can match on identity
+// rather than on human-readable message text.
+export const CODES = {
+  // source & schema
+  UTF8: "AGENTDOC_UTF8",
+  YAML_PARSE: "AGENTDOC_YAML_PARSE",
+  YAML_DUP_KEY: "AGENTDOC_YAML_DUP_KEY",
+  YAML_ANCHOR: "AGENTDOC_YAML_ANCHOR",
+  YAML_ALIAS: "AGENTDOC_YAML_ALIAS",
+  YAML_TAG: "AGENTDOC_YAML_TAG",
+  YAML_MERGE_KEY: "AGENTDOC_YAML_MERGE_KEY",
+  YAML_ENV: "AGENTDOC_YAML_ENV",
+  YAML_UNSUPPORTED: "AGENTDOC_YAML_UNSUPPORTED",
+  YAML_NON_MAP_ROOT: "AGENTDOC_YAML_NON_MAP_ROOT",
+  SCHEMA: "AGENTDOC_SCHEMA",
+  UNKNOWN_FIELD: "AGENTDOC_UNKNOWN_FIELD",
+  PROHIBITED_FIELD: "AGENTDOC_PROHIBITED_FIELD",
+  API_VERSION: "AGENTDOC_API_VERSION",
+  KIND: "AGENTDOC_KIND",
+  LOCATION: "AGENTDOC_LOCATION",
+  CONFIG: "AGENTDOC_CONFIG",
+  GLOB: "AGENTDOC_GLOB",
+  PATH_ESCAPE: "AGENTDOC_PATH_ESCAPE",
+  PATH_UNRESOLVED: "AGENTDOC_PATH_UNRESOLVED",
+  SECRET: "AGENTDOC_SECRET",
+
+  // identity & references
+  NAME_INVALID: "AGENTDOC_NAME_INVALID",
+  REF_INVALID: "AGENTDOC_REF_INVALID",
+  REF_UNRESOLVED: "AGENTDOC_REF_UNRESOLVED",
+  DUPLICATE_IDENTITY: "AGENTDOC_DUPLICATE_IDENTITY",
+
+  // discovery coverage
+  COVERAGE_ZERO: "AGENTDOC_COVERAGE_ZERO",
+  COVERAGE_MULTI: "AGENTDOC_COVERAGE_MULTI",
+  COMPONENT_UNCORROBORATED: "AGENTDOC_COMPONENT_UNCORROBORATED",
+  EVENT_CONTRACT: "AGENTDOC_EVENT_CONTRACT",
+  ARTIFACT_TYPE: "AGENTDOC_ARTIFACT_TYPE",
+
+  // contracts
+  CONTRACT_FORM: "AGENTDOC_CONTRACT_FORM",
+  CONTRACT_SYNTAX: "AGENTDOC_CONTRACT_SYNTAX",
+  CONTRACT_UNCLAIMED: "AGENTDOC_CONTRACT_UNCLAIMED",
+  CONTRACT_SHARED: "AGENTDOC_CONTRACT_SHARED",
+  OIDC_DISCOVERY: "AGENTDOC_OIDC_DISCOVERY",
+
+  // relations
+  RELATION_KIND: "AGENTDOC_RELATION_KIND",
+  RELATION_UNRESOLVED: "AGENTDOC_RELATION_UNRESOLVED",
+  RELATION_AUTHORED: "AGENTDOC_RELATION_AUTHORED",
+  RELATION_MISSING_INVERSE: "AGENTDOC_RELATION_MISSING_INVERSE",
+  RELATION_CONTRACT_DUP: "AGENTDOC_RELATION_CONTRACT_DUP",
+
+  // authority / conflicts
+  CONFLICT_UNRESOLVED: "AGENTDOC_CONFLICT_UNRESOLVED",
+  OBSERVATION_STALE: "AGENTDOC_OBSERVATION_STALE",
+  ELECTION_STALE: "AGENTDOC_ELECTION_STALE",
+  UNRESOLVED_FACT: "AGENTDOC_UNRESOLVED_FACT",
+
+  // normative requirements
+  NORMATIVE_UNCOVERED: "AGENTDOC_NORMATIVE_UNCOVERED",
+  NORMATIVE_SOURCE_STALE: "AGENTDOC_NORMATIVE_SOURCE_STALE",
+  REQUIREMENT_UNVERIFIED: "AGENTDOC_REQUIREMENT_UNVERIFIED",
+
+  // provenance & determinism
+  PROVENANCE: "AGENTDOC_PROVENANCE",
+  NONDETERMINISTIC: "AGENTDOC_NONDETERMINISTIC",
+  GRAPH_SCHEMA: "AGENTDOC_GRAPH_SCHEMA",
+
+  // artifacts & gates
+  STALE_GRAPH: "AGENTDOC_STALE_GRAPH",
+  GRAPH_FRESHNESS: "AGENTDOC_GRAPH_FRESHNESS",
+  GRAPH_MISSING: "AGENTDOC_GRAPH_MISSING",
+  COMPILER_MISMATCH: "AGENTDOC_COMPILER_MISMATCH",
+  DIRTY_SOURCE: "AGENTDOC_DIRTY_SOURCE",
+  WARNING_ACCEPTANCE: "AGENTDOC_WARNING_ACCEPTANCE",
+  OVERRIDE_STALE: "AGENTDOC_OVERRIDE_STALE",
+  JOURNEY: "AGENTDOC_JOURNEY",
+};
+
+// Warning codes that a reviewer may explicitly accept. Anything outside this
+// list is unacceptable: acceptance must never downgrade a hard error.
+export const ACCEPTABLE_WARNING_CODES = Object.freeze([
+  "AGENTDOC_EVENT_UNRESOLVED",
+  "AGENTDOC_RESOURCE_CANDIDATE",
+  "AGENTDOC_SERVICE_BINDING_UNRESOLVED",
+  "AGENTDOC_SCHEDULE_UNRESOLVED",
+  "AGENTDOC_BINDING_AMBIGUOUS",
+  "AGENTDOC_CONFLICT_REVIEWED",
+  "AGENTDOC_OBSERVATION_SUPERSEDED",
+  "AGENTDOC_EXTERNAL_DEPENDENCY_UNCLASSIFIED",
+  "AGENTDOC_DOC_ORPHANED",
+  "AGENTDOC_VERIFICATION_UNTIERED",
+  "AGENTDOC_NORMATIVE_UNCOVERED",
+  "AGENTDOC_REQUIREMENT_UNVERIFIED",
+]);
+
+export class AgentDocError extends Error {
+  constructor(code, message, opts = {}) {
+    super(message);
+    this.name = "AgentDocError";
+    this.code = code;
+    this.path = opts.path;
+    this.ref = opts.ref;
+    this.line = opts.line;
+  }
+  format() {
+    const where = [this.path, this.line ? "line " + this.line : null, this.ref].filter(Boolean).join(" ");
+    return this.code + (where ? " [" + where + "]" : "") + ": " + this.message;
+  }
+}
+
+// Run fn, pushing any AgentDocError into errors and returning undefined.
+// A non-AgentDocError is a compiler defect and is rethrown.
+export function collect(fn, errors) {
+  try {
+    return fn();
+  } catch (e) {
+    if (e instanceof AgentDocError) {
+      errors.push(e);
+      return undefined;
+    }
+    throw e;
+  }
+}