agent-doc-system 0.0.0-stage → 1.1.0

package/core/jsonschema.mjs

@@ -0,0 +1,298 @@
+// Zero-dependency JSON Schema validator (2020-12 subset).
+//
+// Supported keywords — exactly what the agentdoc schemas use:
+//   $ref (local bundle ids and #/$defs/... pointers), $defs, type, const, enum,
+//   required, properties, additionalProperties, patternProperties, items,
+//   prefixItems, minItems, maxItems, uniqueItems, minLength, maxLength,
+//   pattern, minimum, maximum, allOf, anyOf, oneOf, not, if/then/else,
+//   propertyNames, minProperties, format (annotation only).
+//
+// Anything else in a schema is a hard authoring error, so a schema can never
+// silently validate less than it appears to. See SPEC.md "Schema dialect".
+import { AgentDocError, CODES } from "./codes.mjs";
+
+export const SUPPORTED_KEYWORDS = Object.freeze(new Set([
+  "$schema", "$id", "$defs", "$ref", "title", "description", "examples", "default", "deprecated",
+  "type", "const", "enum", "required", "properties", "additionalProperties", "patternProperties",
+  "items", "prefixItems", "minItems", "maxItems", "uniqueItems", "minLength", "maxLength",
+  "pattern", "minimum", "maximum", "allOf", "anyOf", "oneOf", "not", "if", "then", "else",
+  "propertyNames", "minProperties", "$comment",
+]));
+
+function typeOf(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  if (Number.isInteger(v)) return "integer";
+  return typeof v;
+}
+
+function typeMatches(v, t) {
+  const a = typeOf(v);
+  if (t === "number") return a === "number" || a === "integer";
+  if (t === "integer") return a === "integer";
+  return a === t;
+}
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeOf(a) !== typeOf(b)) {
+    if (!(typeof a === "number" && typeof b === "number")) return false;
+  }
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((x, i) => deepEqual(x, b[i]));
+  }
+  if (a && typeof a === "object") {
+    if (!b || typeof b !== "object" || Array.isArray(b)) return false;
+    const ka = Object.keys(a).sort();
+    const kb = Object.keys(b).sort();
+    if (ka.length !== kb.length || ka.some((k, i) => k !== kb[i])) return false;
+    return ka.every((k) => deepEqual(a[k], b[k]));
+  }
+  return false;
+}
+
+export class SchemaBundle {
+  constructor(schemas) {
+    this.byId = new Map();
+    for (const s of schemas) this.byId.set(s.$id, s);
+  }
+  static fromMap(map) {
+    return new SchemaBundle([...map.values()]);
+  }
+  get(id) {
+    const s = this.byId.get(id);
+    if (!s) throw new AgentDocError(CODES.SCHEMA, "schema not found in bundle: " + id);
+    return s;
+  }
+  // Resolve a cross-schema $ref. Schemas may refer to a sibling by bare file
+  // name ("common.json#/$defs/x"); both that alias and the fully qualified id
+  // are accepted, so a bundle can be registered under either.
+  //
+  // Returns the target *and* the document it was found in. The document matters:
+  // a node reached through `common.json#/$defs/metadata` contains its own local
+  // `#/$defs/name` pointers, which must resolve against common rather than
+  // against whichever schema happened to lead here.
+  resolve(baseId, ref) {
+    const [file, pointer] = splitRef(ref);
+    const candidates = [];
+    if (file) {
+      if (this.byId.has(file)) candidates.push(file);
+      if (baseId) candidates.push(relativeTo(baseId, file));
+      for (const id of this.byId.keys()) {
+        if (id === file || id.endsWith("/" + file)) candidates.push(id);
+      }
+    } else if (baseId) {
+      candidates.push(baseId);
+    }
+    for (const c of candidates) {
+      if (!this.byId.has(c)) continue;
+      let target = this.byId.get(c);
+      if (pointer) {
+        for (const part of pointer.split("/").filter(Boolean)) {
+          target = target[unescapePointer(part)];
+        }
+      }
+      if (target !== undefined) return { node: target, document: this.byId.get(c) };
+    }
+    throw new AgentDocError(CODES.SCHEMA, "cannot resolve $ref " + ref + " from " + baseId);
+  }
+  validator(schemaOrId) {
+    const root = typeof schemaOrId === "string" ? this.get(schemaOrId) : schemaOrId;
+    return new Validator(this, root);
+  }
+}
+
+export class Validator {
+  constructor(bundle, root) {
+    this.bundle = bundle;
+    this.root = root;
+  }
+  // Returns null when valid, else an array of {instancePath, keyword, message}.
+  validate(value) {
+    const errs = [];
+    this.#check(this.root, value, "", errs, this.root);
+    return errs.length ? errs : null;
+  }
+
+  // A `#/...` pointer resolves against the *document* that contains it, and that
+  // document changes as a cross-file `$ref` is followed. Two bugs live here and
+  // both failed silently, because dereferencing to `undefined` means "no
+  // constraint" rather than an error:
+  //
+  //  1. Resolving against the referring subschema rather than its document looks
+  //     up `#/$defs/E` inside `{"$ref": "#/$defs/E"}` and yields undefined, so any
+  //     schema using `$ref` for an enum inside `items` validated anything at all.
+  //  2. Resolving against `this.root` always is wrong in the other direction:
+  //     after following `common.json#/$defs/metadata`, the local `#/$defs/name`
+  //     inside *common* must resolve against common, not against the original
+  //     root. That made every component descriptor fail to validate.
+  //
+  // `doc` therefore tracks the current base document, and `#` alone means the
+  // current document's root.
+  // Resolve `schema` to a node, and report which document that node's own local
+  // `#/...` pointers must be resolved against. Threading the document explicitly
+  // is what makes nested cross-file references work: without it, a
+  // `#/$defs/repoPath` written inside `common.json` was looked up in whichever
+  // schema happened to lead there, and dereferencing to `undefined` means "no
+  // constraint" rather than an error — a silent soundness hole.
+  #resolve(schema, doc = this.root, seen = new Set()) {
+    let s = schema;
+    let base = doc;
+    while (s && typeof s.$ref === "string") {
+      const id = s.$ref;
+      const tag = (base && base.$id) + "|" + id;
+      if (seen.has(tag)) throw new AgentDocError(CODES.SCHEMA, "cyclic $ref: " + id);
+      seen.add(tag);
+      if (id.startsWith("#")) {
+        if (id === "#") { s = base; continue; }
+        if (!id.startsWith("#/")) throw new AgentDocError(CODES.SCHEMA, "unsupported $ref " + id);
+        s = pointerGet(base, id.slice(2).split("/").map(unescapePointer));
+        if (s === undefined) {
+          throw new AgentDocError(CODES.SCHEMA, "cannot resolve local $ref " + id + " against " + base.$id);
+        }
+      } else {
+        const found = this.bundle.resolve(base.$id, id);
+        s = found.node;
+        base = found.document;
+      }
+    }
+    return { node: s, document: base };
+  }
+
+  #check(rawSchema, value, ip, errs, doc = this.root) {
+    const resolved = this.#resolve(rawSchema, doc);
+    const schema = resolved.node;
+    const base = resolved.document;
+    if (schema === true || schema === undefined) return;
+    if (schema === false) {
+      errs.push({ instancePath: ip || "/", keyword: "false", message: "schema forbids any value" });
+      return;
+    }
+    const add = (keyword, message) => errs.push({ instancePath: ip || "/", keyword, message });
+
+    if (schema.type !== undefined) {
+      const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+      if (!types.some((t) => typeMatches(value, t))) {
+        add("type", "must be " + types.join("|") + " (got " + typeOf(value) + ")");
+        return;
+      }
+    }
+    if (schema.const !== undefined && !deepEqual(value, schema.const)) {
+      add("const", "must equal " + JSON.stringify(schema.const));
+    }
+    if (schema.enum !== undefined && !schema.enum.some((e) => deepEqual(value, e))) {
+      add("enum", "must be one of " + JSON.stringify(schema.enum));
+    }
+
+    const t = typeOf(value);
+    if (t === "string") {
+      if (schema.minLength !== undefined && [...value].length < schema.minLength) add("minLength", "shorter than " + schema.minLength);
+      if (schema.maxLength !== undefined && [...value].length > schema.maxLength) add("maxLength", "longer than " + schema.maxLength);
+      if (schema.pattern !== undefined && !new RegExp(schema.pattern, "u").test(value)) {
+        add("pattern", "does not match " + schema.pattern);
+      }
+    }
+    if (t === "number" || t === "integer") {
+      if (schema.minimum !== undefined && value < schema.minimum) add("minimum", "below minimum " + schema.minimum);
+      if (schema.maximum !== undefined && value > schema.maximum) add("maximum", "above maximum " + schema.maximum);
+    }
+    if (t === "array") {
+      if (schema.minItems !== undefined && value.length < schema.minItems) add("minItems", "fewer than " + schema.minItems + " items");
+      if (schema.maxItems !== undefined && value.length > schema.maxItems) add("maxItems", "more than " + schema.maxItems + " items");
+      if (schema.uniqueItems === true) {
+        for (let i = 0; i < value.length; i++) {
+          for (let j = i + 1; j < value.length; j++) {
+            if (deepEqual(value[i], value[j])) add("uniqueItems", "duplicate item at index " + j);
+          }
+        }
+      }
+      const prefix = schema.prefixItems || [];
+      for (let i = 0; i < value.length; i++) {
+        if (i < prefix.length) this.#check(prefix[i], value[i], ip + "/" + i, errs, base);
+        else if (schema.items !== undefined) this.#check(schema.items, value[i], ip + "/" + i, errs, base);
+      }
+    }
+    if (t === "object") {
+      const keys = Object.keys(value);
+      if (schema.minProperties !== undefined && keys.length < schema.minProperties) add("minProperties", "fewer than " + schema.minProperties + " properties");
+      for (const r of schema.required || []) {
+        if (!Object.prototype.hasOwnProperty.call(value, r)) add("required", "missing required property " + JSON.stringify(r));
+      }
+      const props = schema.properties || {};
+      const patterns = Object.entries(schema.patternProperties || {});
+      for (const k of keys) {
+        const escaped = k.replace(/~/g, "~0").replace(/\//g, "~1");
+        const childIp = ip + "/" + escaped;
+        let covered = false;
+        if (Object.prototype.hasOwnProperty.call(props, k)) {
+          covered = true;
+          this.#check(props[k], value[k], childIp, errs, base);
+        }
+        for (const [re, sub] of patterns) {
+          if (new RegExp(re, "u").test(k)) {
+            covered = true;
+            this.#check(sub, value[k], childIp, errs, base);
+          }
+        }
+        if (!covered) {
+          if (schema.additionalProperties === false) {
+            errs.push({ instancePath: childIp, keyword: "additionalProperties", message: "unknown property " + JSON.stringify(k) });
+          } else if (schema.additionalProperties !== undefined) {
+            this.#check(schema.additionalProperties, value[k], childIp, errs, base);
+          }
+        }
+        if (schema.propertyNames !== undefined) this.#check(schema.propertyNames, k, childIp, errs, base);
+      }
+    }
+
+    for (const sub of schema.allOf || []) this.#check(sub, value, ip, errs, base);
+    if (schema.anyOf) {
+      const ok = schema.anyOf.some((s) => this.#sub(value, s, base));
+      if (!ok) add("anyOf", "does not match any allowed variant");
+    }
+    if (schema.oneOf) {
+      const n = schema.oneOf.filter((s) => this.#sub(value, s, base)).length;
+      if (n !== 1) add("oneOf", "must match exactly one variant (matched " + n + ")");
+    }
+    if (schema.not !== undefined && this.#sub(value, schema.not, base)) add("not", "matches a forbidden shape");
+    if (schema.if !== undefined) {
+      if (this.#sub(value, schema.if, base)) this.#check(schema.then, value, ip, errs, base);
+      else if (schema.else !== undefined) this.#check(schema.else, value, ip, errs, base);
+    }
+  }
+
+  #sub(value, schema, doc = this.root) {
+    const errs = [];
+    this.#check(schema, value, "", errs, doc);
+    return errs.length === 0;
+  }
+}
+
+function unescapePointer(s) {
+  return s.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function pointerGet(root, parts) {
+  let cur = root;
+  for (const p of parts) {
+    if (cur === undefined || cur === null) return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+function relativeTo(baseId, ref) {
+  const base = baseId || "";
+  const cut = base.lastIndexOf("/");
+  return cut >= 0 ? base.slice(0, cut + 1) + ref : ref;
+}
+
+function splitRef(ref) {
+  const at = ref.indexOf("#");
+  return at < 0 ? [ref, null] : [ref.slice(0, at), ref.slice(at + 1)];
+}
+
+export function formatErrors(errs, limit = 8) {
+  return errs.slice(0, limit).map((e) => (e.instancePath || "/") + " " + e.message).join("; ");
+}

package/core/normative.mjs

@@ -0,0 +1,171 @@
+// Normative requirement coverage.
+//
+// A normative document (a specification, a technical profile) states what the
+// implementation must do. Routing it to a component is not reviewing it: the
+// incident behind this module was a migration that linked every specification,
+// passed every gate, and still never noticed that a "must be reproduced on the
+// production host" had no implementation at all.
+//
+// This module does not read prose for meaning. It does two deterministic
+// things:
+//
+//   - it cuts every configured normative document into sections and pins each
+//     one by content hash, so "which parts of the specification were reviewed"
+//     becomes a question with an exact answer;
+//   - it requires every section to be accounted for, either by a structured
+//     requirement (a fact the authority engine can compare against evidence)
+//     or by an explicit, reviewed attestation that it carries no
+//     implementation obligation.
+//
+// Deciding *what* a section obliges is a human act. Making sure that act
+// happened, and is re-done when the section changes, is the machine's.
+import { AgentDocError, CODES } from "./codes.mjs";
+import { expandGlob, sha256Hex } from "./fsx.mjs";
+import { CONFIG_PATH } from "./descriptors.mjs";
+
+export const REQUIREMENT_KEY_PREFIX = "requirement.";
+export const NORMATIVE_SEMANTICS_PREFIX = "normative: ";
+
+// Sections are the level-2 headings of a Markdown document. Level 1 is the
+// document title; deeper levels belong to the section that contains them, so a
+// reviewer attests a unit that is large enough to carry one obligation and
+// small enough to be re-reviewed when it changes. Headings inside fenced code
+// blocks are not headings.
+export function splitSections(text) {
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  const sections = [];
+  const slugs = new Map();
+  let cur = null;
+  let fence = null;
+  for (const line of lines) {
+    const f = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+    if (f) {
+      if (!fence) fence = f[1][0];
+      else if (f[1][0] === fence) fence = null;
+    }
+    const h = !fence && /^##(?!#)\s+(.+?)\s*#*\s*$/.exec(line);
+    if (h) {
+      if (cur) sections.push(cur);
+      const base = slugify(h[1]);
+      // Duplicate headings get the same suffixes a Markdown renderer gives
+      // their anchors, so a citation can be the link a reader would follow.
+      const n = slugs.get(base) || 0;
+      slugs.set(base, n + 1);
+      cur = { section: n ? base + "-" + n : base, heading: h[1], lines: [line] };
+      continue;
+    }
+    if (/^#(?!#)\s/.test(line) && !fence) {
+      if (cur) sections.push(cur);
+      cur = null;
+      continue;
+    }
+    if (cur) cur.lines.push(line);
+  }
+  if (cur) sections.push(cur);
+  return sections.map((s) => {
+    // Trailing blank lines are layout, not content: appending a section must
+    // not invalidate the review of the one before it.
+    while (s.lines.length > 1 && s.lines[s.lines.length - 1].trim() === "") s.lines.pop();
+    const body = s.lines.join("\n") + "\n";
+    return { section: s.section, heading: s.heading, sha256: sha256Hex(Buffer.from(body, "utf8")) };
+  });
+}
+
+export function slugify(heading) {
+  return String(heading)
+    .trim()
+    .toLowerCase()
+    .replace(/[`*_~[\]()]/g, "")
+    .replace(/[^\p{L}\p{N}\s-]/gu, "")
+    .replace(/\s/g, "-");
+}
+
+// Every configured normative document, cut into sections. Reading through the
+// repository handle keeps these files in the compile's input hash, so a change
+// to a specification makes the committed graph stale like any other input.
+export function loadNormativeDocuments(repo, cfg) {
+  const globs = (cfg.docs && cfg.docs.normative) || [];
+  const paths = new Set();
+  for (const g of globs) for (const p of expandGlob(repo, g)) paths.add(p);
+  const docs = [];
+  for (const p of [...paths].sort()) {
+    if (!/\.(md|mdx)$/.test(p)) continue;
+    docs.push({ path: p, sections: splitSections(repo.readText(p)) });
+  }
+  return docs;
+}
+
+// A citation of one section: a requirement's `source`, or a coverage
+// attestation. Both must name a section that exists *now*, with the digest it
+// had when someone reviewed it.
+export function verifyCitation(docs, cite, where, ref) {
+  const doc = docs.find((d) => d.path === cite.path);
+  if (!doc) {
+    throw new AgentDocError(
+      CODES.CONFIG,
+      "cites " + cite.path + ", which is not a configured normative document (docs.normative)",
+      { path: where, ref }
+    );
+  }
+  const s = doc.sections.find((x) => x.section === cite.section);
+  if (!s) {
+    throw new AgentDocError(
+      CODES.NORMATIVE_SOURCE_STALE,
+      "cited section " + cite.path + "#" + cite.section + " no longer exists — re-review what replaced it",
+      { path: where, ref }
+    );
+  }
+  if (s.sha256 !== cite.sha256) {
+    throw new AgentDocError(
+      CODES.NORMATIVE_SOURCE_STALE,
+      "cited section " + cite.path + "#" + cite.section + " changed since it was reviewed — " +
+        "re-review it before updating the digest to " + s.sha256,
+      { path: where, ref }
+    );
+  }
+  return s;
+}
+
+// Coverage: which sections are cited by a requirement, which are attested, and
+// which nobody has looked at. Returned rather than pushed so the audit can show
+// the same table the gate enforces.
+export function normativeCoverage(docs, requirements, attestations, errors) {
+  const coveredBy = new Map();
+  const mark = (path, section, by) => {
+    const k = path + "#" + section;
+    if (!coveredBy.has(k)) coveredBy.set(k, []);
+    coveredBy.get(k).push(by);
+  };
+  for (const r of requirements) {
+    mark(r.source.path, r.source.section, "requirement:" + r.subject + " " + r.key);
+  }
+  const seen = new Set();
+  for (const a of attestations) {
+    const k = a.path + "#" + a.section;
+    try {
+      if (seen.has(k)) throw new AgentDocError(CODES.CONFIG, "duplicate normativeCoverage entry for " + k, { path: CONFIG_PATH });
+      seen.add(k);
+      verifyCitation(docs, a, CONFIG_PATH, null);
+      mark(a.path, a.section, "attestation:" + a.disposition);
+    } catch (e) {
+      if (!(e instanceof AgentDocError)) throw e;
+      errors.push(e);
+    }
+  }
+  const sections = [];
+  for (const d of docs) {
+    for (const s of d.sections) {
+      const by = (coveredBy.get(d.path + "#" + s.section) || []).sort();
+      sections.push({ path: d.path, section: s.section, heading: s.heading, sha256: s.sha256, coveredBy: by });
+    }
+  }
+  return { sections, uncovered: sections.filter((s) => !s.coveredBy.length) };
+}
+
+export function isRequirementKey(key) {
+  return typeof key === "string" && key.startsWith(REQUIREMENT_KEY_PREFIX);
+}
+
+export function isNormative(assertion) {
+  return typeof assertion.semantics === "string" && assertion.semantics.startsWith(NORMATIVE_SEMANTICS_PREFIX);
+}

package/core/observations.mjs

@@ -0,0 +1,129 @@
+// Observation ingestion.
+//
+// An ObservationSet is a committed, secret-free record of what an external
+// system actually said at a known time. Ingesting it produces
+// OBSERVED_RUNTIME assertions. It can never overwrite an authored fact: it is
+// added to the same (subject, key) group and the authority engine decides what
+// happens. Freshness is evaluated at gate time (check/query), never at compile
+// time, so a compile stays a pure function of the checkout.
+import { CODES, AgentDocError } from "./codes.mjs";
+
+export function ingestObservations(ctx) {
+  const out = [];
+  const { sets } = ctx.observations;
+  const byName = new Map();
+  for (const s of sets) {
+    if (byName.has(s.meta.name)) {
+      throw new AgentDocError(
+        CODES.DUPLICATE_IDENTITY,
+        "duplicate observation set name '" + s.meta.name + "' (also in " + byName.get(s.meta.name).file + ")",
+        { path: s.file }
+      );
+    }
+    byName.set(s.meta.name, s);
+  }
+  for (const s of sets) {
+    const m = s.meta;
+    if (m.supersedes && !byName.has(m.supersedes)) {
+      throw new AgentDocError(
+        CODES.REF_UNRESOLVED,
+        "observation set '" + m.name + "' supersedes unknown set '" + m.supersedes + "'",
+        { path: s.file }
+      );
+    }
+    const bundleProv = ctx.prov.add(
+      "runtime",
+      m.evidenceBundle,
+      "observation:" + m.collector.replace(/\s+/g, "-").toLowerCase(),
+      ["obs:" + m.name],
+      { jsonPointer: "/facts" }
+    );
+    const observed = {
+      at: m.capturedAt,
+      environment: m.environment,
+      sourceSystem: m.sourceSystem,
+      collector: m.collector,
+      evidenceBundle: m.evidenceBundle,
+      retrievalMethod: m.collector,
+      supersedes: m.supersedes || null,
+    };
+    const facts = [];
+    for (const f of s.facts) {
+      const fact = ctx.facts.add({
+        subject: f.subject,
+        key: f.key,
+        value: f.value,
+        evidenceClass: "OBSERVED_RUNTIME",
+        confidence: "direct",
+        provRecs: [bundleProv],
+        semantics: f.semantics,
+        observed,
+        source: s.file,
+      });
+      facts.push({
+        id: f.id,
+        subject: f.subject,
+        key: f.key,
+        value: f.value,
+        semantics: f.semantics,
+        assertionId: fact.id,
+        observedRefs: [...(f.observedRefs || [])].sort(),
+      });
+    }
+    out.push({
+      id: m.name,
+      name: m.name,
+      description: m.description,
+      environment: m.environment,
+      sourceSystem: m.sourceSystem,
+      collector: m.collector,
+      capturedAt: m.capturedAt,
+      maxAgeDays: m.maxAgeDays,
+      evidenceBundle: m.evidenceBundle,
+      supersedes: m.supersedes || null,
+      facts,
+      provenanceIds: null,
+      provs: new Set([bundleProv]),
+    });
+  }
+  out.sort((a, b) => (a.id < b.id ? -1 : 1));
+  return out;
+}
+
+// Freshness of an observation is a time-dependent judgement and therefore lives
+// outside the compiled graph. `now` is injected so tests and CI are hermetic.
+export function observationFreshness(observations, now = new Date()) {
+  const out = [];
+  // A superseded set is history, not a promise of freshness — its maxAgeDays
+  // no longer gates, or every superseding observation would immediately make
+  // the one it replaced a permanent staleness failure.
+  const supersededIds = new Set((observations || []).map((o) => o.supersedes).filter(Boolean));
+  for (const o of observations || []) {
+    if (supersededIds.has(o.id)) continue;
+    const captured = Date.parse(o.capturedAt);
+    const ageDays = Math.floor((now.getTime() - captured) / 86400000);
+    out.push({
+      id: o.id,
+      environment: o.environment,
+      capturedAt: o.capturedAt,
+      ageDays,
+      maxAgeDays: o.maxAgeDays,
+      stale: !Number.isFinite(ageDays) || ageDays > o.maxAgeDays,
+    });
+  }
+  return out.sort((a, b) => (a.id < b.id ? -1 : 1));
+}
+
+export function stalenessDiagnostics(freshness) {
+  return freshness
+    .filter((f) => f.stale)
+    .map((f) => ({
+      severity: "error",
+      code: CODES.OBSERVATION_STALE,
+      subject: f.id,
+      message:
+        "observation set '" + f.id + "' (" + f.environment + ") was captured " + f.capturedAt +
+        " and exceeds its declared maxAgeDays of " + f.maxAgeDays + " — re-observe the source system or restate the fact",
+      paths: [],
+    }));
+}

package/core/provenance.mjs

@@ -0,0 +1,83 @@
+// Provenance registry.
+//
+// Every fact that reaches the compiled graph is backed by a record carrying the
+// evidence path, extractor identity, content hash, and RFC 6901 subject
+// pointers into the graph. Provenance classes:
+//   declared   — the file states the fact outright (authored descriptor, config)
+//   observed   — the file shows the fact (manifest, source file, config)
+//   validated  — two independent files agree (a generated client + the contract)
+//   runtime    — read from an external system via a recorded collector
+//   standard   — the canonical authority is a published standard
+import { sha256Hex } from "./fsx.mjs";
+
+// Extractor identities appear in the graph and are matched by tooling, so they
+// are normalised to a slug. "discovery:pnpm" and "pnpm" must not be two
+// different extractors.
+export function slugExtractor(name) {
+  const s = String(name).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return s || "unknown";
+}
+
+// `reviewed` is the provenance class for a human interpretation recorded in
+// configuration. It was previously filed as `declared`, which mapped to
+// AUTHORED — the strongest class in the model — so a reviewed override merged
+// with a derived edge and was relabelled AUTHORED, silently promoting a human
+// judgement to the top of the hierarchy. The authority model elects classes per
+// fact; a provenance class must not decide that on its own.
+export const CLASSES = Object.freeze(["declared", "observed", "validated", "runtime", "standard", "reviewed"]);
+
+export class ProvRegistry {
+  constructor(repo) {
+    this.repo = repo;
+    this.records = [];
+  }
+  // subjects are symbolic keys ("rel:pending", "ent:<ref>", "evt:<pattern>")
+  // resolved to graph pointers after assembly. Callers add "pending" first and
+  // rebind later; see bindPending in graph.mjs.
+  add(cls, path, extractorName, subjects, location, extractorVersion = "1.0.0") {
+    if (!CLASSES.includes(cls)) throw new Error("unknown provenance class " + cls);
+    const name = slugExtractor(extractorName);
+    const buf = this.repo.readBytes(path);
+    const rec = {
+      cls,
+      path,
+      extractor: { name, version: extractorVersion },
+      subjects: new Set(subjects.filter(Boolean)),
+      hash: "sha256:" + sha256Hex(buf),
+      location,
+    };
+    this.records.push(rec);
+    return rec;
+  }
+  // Canonical order: path, extractor, first subject. IDs are positional, so the
+  // numbering is a pure function of the input set.
+  finalize(resolve) {
+    const sorted = [...this.records].sort((a, b) => {
+      const ka = a.path + "|" + a.extractor.name + "|" + [...a.subjects].sort()[0];
+      const kb = b.path + "|" + b.extractor.name + "|" + [...b.subjects].sort()[0];
+      return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+    const list = sorted.map((r, i) => {
+      const subjects = [...r.subjects].map(resolve).sort();
+      const out = {
+        id: "p-" + String(i + 1).padStart(4, "0"),
+        class: r.cls,
+        path: r.path,
+        extractor: { name: r.extractor.name, version: r.extractor.version },
+        contentHash: r.hash,
+        subjects,
+      };
+      if (r.location) out.location = r.location;
+      return out;
+    });
+    const idOf = new Map(sorted.map((r, i) => [r, "p-" + String(i + 1).padStart(4, "0")]));
+    return { list, idOf };
+  }
+}
+
+// Collect the distinct extractor identities for the compiler stamp.
+export function extractorSet(prov) {
+  const m = new Map();
+  for (const r of prov.records) m.set(r.extractor.name, r.extractor.version);
+  return [...m.entries()].sort().map(([name, version]) => ({ name, version }));
+}