agent-doc-system 0.0.0-stage → 1.1.0

package/core/yaml.mjs

@@ -0,0 +1,477 @@
+// Strict YAML 1.2 *subset* parser with zero dependencies.
+//
+// Supported: multi-document streams, block mappings, block sequences, plain /
+// single-quoted / double-quoted scalars, flow sequences and mappings of
+// scalars, literal (|) and folded (>) block scalars, comments, and the YAML
+// 1.2 core scalar resolution (null/bool/int/float/string).
+//
+// Deliberately unsupported and rejected with a dedicated code: anchors,
+// aliases, custom tags, merge keys, environment interpolation, complex keys,
+// and any nesting the compiler would have to guess at. Authored sources are
+// machine-generated templates plus human review; ambiguity is a defect, not a
+// feature. See SPEC.md "Source dialect".
+import { AgentDocError, CODES } from "./codes.mjs";
+
+const BANNED = [
+  { re: /(?:^|[\s\[])&[A-Za-z0-9_-]+/, code: CODES.YAML_ANCHOR, what: "anchors" },
+  { re: /(?:^|[\s\[])\*[A-Za-z0-9_-]+/, code: CODES.YAML_ALIAS, what: "aliases" },
+  { re: /(?:^|[\s[])!(?:<[^>]*>|![^\s]*|[A-Za-z][A-Za-z0-9_:.\/-]*)/, code: CODES.YAML_TAG, what: "custom tags" },
+  { re: /^\s*<<\s*:/, code: CODES.YAML_MERGE_KEY, what: "merge keys" },
+  { re: /\$\{[A-Za-z_][A-Za-z0-9_]*\}/, code: CODES.YAML_ENV, what: "environment interpolation" },
+];
+
+function scanBanned(text, path) {
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*(#|---|\.\.\.)/.test(line) && !/^(---|...)/.test(line.trim())) continue;
+    for (const b of BANNED) {
+      if (b.re.test(line)) {
+        throw new AgentDocError(b.code, "YAML " + b.what + " are forbidden in agentdoc sources", {
+          path,
+          line: i + 1,
+        });
+      }
+    }
+  }
+}
+
+function makeLine(raw, lineNo) {
+  const l = { raw, lineNo, indent: 0, content: "", blank: false, _c: null };
+  l.indent = /^[ \t]*/.exec(raw)[0].length;
+  if (/^\t/.test(raw)) {
+    throw new AgentDocError(CODES.YAML_PARSE, "tab character used for indentation", { line: lineNo });
+  }
+  const t = raw.trim();
+  l.blank = t === "" || t.startsWith("#");
+  return l;
+}
+
+function stripComment(raw) {
+  let q = null;
+  for (let i = 0; i < raw.length; i++) {
+    const c = raw[i];
+    if (q) {
+      if (c === "\\" && q === '"') { i++; continue; }
+      if (c === q) q = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { q = c; continue; }
+    if (c === "#" && (i === 0 || /\s/.test(raw[i - 1]))) return raw.slice(0, i);
+  }
+  return raw;
+}
+
+function content(l) {
+  if (l._c === null) l._c = stripComment(l.raw).replace(/\s+$/, "");
+  return l._c;
+}
+
+const isSeqEntry = (s) => s === "-" || /^-(\s)/.test(s);
+
+function splitKey(s) {
+  // Returns {key, rest} for `key: value` / `key:` / `"key": value`, else null.
+  if (s === "") return null;
+  if (s[0] === '"' || s[0] === "'") {
+    const q = s[0];
+    let i = 1;
+    while (i < s.length) {
+      if (s[i] === "\\" && q === '"') { i += 2; continue; }
+      if (s[i] === q) {
+        if (q === "'" && s[i + 1] === "'") { i += 2; continue; }
+        break;
+      }
+      i++;
+    }
+    if (i >= s.length) return null;
+    const key = unquote(s.slice(0, i + 1));
+    const after = s.slice(i + 1);
+    if (!after.startsWith(":")) return null;
+    return { key, rest: after.slice(1).replace(/^[ \t]+/, "").replace(/\s+$/, "") };
+  }
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "[" || c === "{") depth++;
+    else if (c === "]" || c === "}") depth--;
+    else if (c === ":" && depth === 0) {
+      const nxt = s[i + 1];
+      if (nxt === undefined || nxt === " " || nxt === "\t") {
+        return { key: s.slice(0, i).replace(/\s+$/, ""), rest: s.slice(i + 1).replace(/^[ \t]+/, "").replace(/\s+$/, "") };
+      }
+    }
+  }
+  return null;
+}
+
+function unquote(tok) {
+  const q = tok[0];
+  const body = tok.slice(1, -1);
+  if (q === "'") return body.replace(/''/g, "'");
+  let out = "";
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (c !== "\\") { out += c; continue; }
+    const n = body[++i];
+    if (n === "n") out += "\n";
+    else if (n === "t") out += "\t";
+    else if (n === "r") out += "\r";
+    else if (n === "0") out += "\0";
+    else if (n === '"') out += '"';
+    else if (n === "\\") out += "\\";
+    else if (n === "/") out += "/";
+    else if (n === "u") { out += String.fromCharCode(parseInt(body.slice(i + 1, i + 5), 16)); i += 4; }
+    else throw new AgentDocError(CODES.YAML_UNSUPPORTED, "unsupported escape sequence \\" + n);
+  }
+  return out;
+}
+
+const INT_RE = /^[-+]?[0-9]+$/;
+const OCT_RE = /^0o[0-7]+$/;
+const HEX_RE = /^0x[0-9a-fA-F]+$/;
+const FLOAT_RE = /^[-+]?(?:[0-9]+\.[0-9]*|\.[0-9]+|[0-9]+)(?:[eE][-+]?[0-9]+)?$/;
+
+function resolvePlain(s) {
+  if (s === "" || s === "null" || s === "~" || s === "Null" || s === "NULL") return null;
+  if (s === "true" || s === "True" || s === "TRUE") return true;
+  if (s === "false" || s === "False" || s === "FALSE") return false;
+  if (INT_RE.test(s)) {
+    const n = Number(s);
+    if (!Number.isSafeInteger(n)) throw new AgentDocError(CODES.YAML_UNSUPPORTED, "integer out of safe range: " + s);
+    return n;
+  }
+  if (OCT_RE.test(s)) return parseInt(s.slice(2), 8);
+  if (HEX_RE.test(s)) return parseInt(s.slice(2), 16);
+  if (FLOAT_RE.test(s) && /[.eE]/.test(s)) return Number(s);
+  if (s === ".inf" || s === ".Inf") return Infinity;
+  if (s === "-.inf" || s === "-.Inf") return -Infinity;
+  if (s === ".nan" || s === ".NaN") return NaN;
+  return s;
+}
+
+function scalar(tok, lineNo) {
+  const t = tok.trim();
+  if (t === "") return null;
+  if (t[0] === '"' || t[0] === "'") {
+    if (t.length < 2 || t[t.length - 1] !== t[0]) {
+      throw new AgentDocError(CODES.YAML_PARSE, "unterminated quoted scalar", { line: lineNo });
+    }
+    return unquote(t);
+  }
+  if (t[0] === "[" || t[0] === "{") return flow(t, lineNo);
+  if (t[0] === "&" || t[0] === "*" || t[0] === "!") {
+    throw new AgentDocError(CODES.YAML_UNSUPPORTED, "anchors, aliases and tags are not supported", { line: lineNo });
+  }
+  return resolvePlain(t);
+}
+
+// Flow collections of scalars (and nested flow collections).
+function flow(text, lineNo) {
+  let i = 0;
+  const err = (m) => { throw new AgentDocError(CODES.YAML_PARSE, "flow collection: " + m, { line: lineNo }); };
+  const ws = () => { while (i < text.length && /\s/.test(text[i])) i++; };
+  let valueStart = 0;
+  function value() {
+    ws();
+    const c = text[i];
+    if (c === "[") return seqFlow();
+    if (c === "{") return mapFlow();
+    valueStart = i;
+    return scalarToken();
+  }
+  function scalarToken() {
+    ws();
+    if (text[i] === '"' || text[i] === "'") {
+      valueStart = i;
+      const q = text[i++];
+      let out = "";
+      while (i < text.length) {
+        if (q === '"' && text[i] === "\\") { out += text[i] + text[i + 1]; i += 2; continue; }
+        if (text[i] === q) {
+          if (q === "'" && text[i + 1] === "'") { out += "'"; i += 2; continue; }
+          i++;
+          return unquote(q + out + q);
+        }
+        out += text[i++];
+      }
+      err("unterminated quoted scalar");
+    }
+    // Scan a plain scalar in flow context. It ends at a bracket, at a colon, or
+    // at a comma that is a separator; see isSeqSeparator.
+    while (i < text.length) {
+      const c = text[i];
+      if (c === "]" || c === "}") break;
+      if (c === ":") break;
+      if (c === ",") {
+        const save = i;
+        if (isSeqSeparator()) { i = save; break; }
+        i++;
+        continue;
+      }
+      i++;
+    }
+    const t = text.slice(valueStart, i).replace(/\s+$/, "");
+    return resolvePlain(t);
+  }
+  function seqFlow() {
+    i++; // [
+    const out = [];
+    ws();
+    if (text[i] === "]") { i++; return out; }
+    for (;;) {
+      out.push(value());
+      ws();
+      if (isSeqSeparator()) { i++; continue; }
+      if (text[i] === "]") { i++; return out; }
+      err("expected , or ]");
+    }
+  }
+  function mapFlow() {
+    i++; // {
+    const out = {};
+    ws();
+    if (text[i] === "}") { i++; return out; }
+    for (;;) {
+      ws();
+      valueStart = i;
+      const k = scalarKey();
+      ws();
+      if (text[i] !== ":") err("expected : in flow mapping");
+      i++;
+      const v = value();
+      if (Object.prototype.hasOwnProperty.call(out, k)) {
+        throw new AgentDocError(CODES.YAML_DUP_KEY, "duplicate mapping key " + JSON.stringify(k), { line: lineNo });
+      }
+      out[k] = v;
+      ws();
+      if (isSeqSeparator()) { i++; continue; }
+      if (text[i] === "}") { i++; return out; }
+      err("expected , or }");
+    }
+  }
+  // A flow-mapping key is a plain or quoted scalar ending at a colon. Keys are
+  // never allowed to swallow a comma, so this is the strict form.
+  function scalarKey() {
+    if (text[i] === '"' || text[i] === "'") {
+      const q = text[i++];
+      let out = "";
+      while (i < text.length) {
+        if (text[i] === "\\" && q === '"') { out += text[i] + text[i + 1]; i += 2; continue; }
+        if (text[i] === q) {
+          if (q === "'" && text[i + 1] === "'") { out += "'"; i += 2; continue; }
+          i++;
+          return unquote(q + out + q);
+        }
+        out += text[i++];
+      }
+      err("unterminated quoted key");
+    }
+    const start = i;
+    while (i < text.length && !":,]}".includes(text[i])) i++;
+    const t = text.slice(start, i).replace(/\s+$/, "");
+    if (t.includes(": ")) err("quoted keys are required in flow mappings");
+    return resolvePlain(t);
+  }
+
+  // A comma inside a flow collection is a separator only when what follows
+  // looks like the next element. Real OpenAPI documents contain flow mappings
+  // whose plain-scalar values contain commas — `{ description: Body is
+  // unreadable, invalid, or wrong. }` — and the YAML ecosystem parses them, so
+  // refusing them would reject valid-in-practice contracts. The rule below is
+  // deterministic and matches that behaviour: a comma separates when the
+  // remainder is a closing bracket, a new key (`ident:`), or the previous token
+  // carried no internal whitespace.
+  function isSeqSeparator() {
+    if (text[i] !== ",") return false;
+    const rest = text.slice(i + 1);
+    if (/^\s*[}\]]/.test(rest)) return true;
+    if (/^\s*[\[{]/.test(rest)) return true;
+    if (/^\s*[^,:{}\[\]"']+\s*:/.test(rest)) return true;
+    const prev = text.slice(valueStart, i);
+    return prev.length > 0 && !/\s/.test(prev);
+  }
+  const v = value();
+  ws();
+  if (i !== text.length) err("trailing content after flow collection");
+  return v;
+}
+
+class Reader {
+  constructor(lines, path) {
+    this.ls = lines;
+    this.path = path;
+  }
+  skip() {
+    while (this.i < this.ls.length && this.ls[this.i].blank) this.i++;
+  }
+  peek() {
+    this.skip();
+    return this.i < this.ls.length ? this.ls[this.i] : null;
+  }
+  node(indent) {
+    const l = this.peek();
+    if (!l || l.indent < indent) return null;
+    if (isSeqEntry(content(l).slice(l.indent))) return this.seq(l.indent);
+    return this.map(l.indent);
+  }
+  map(indent) {
+    const out = {};
+    for (;;) {
+      const l = this.peek();
+      if (!l || l.indent < indent) break;
+      const s = content(l).slice(l.indent);
+      if (isSeqEntry(s)) {
+        throw new AgentDocError(CODES.YAML_PARSE, "sequence entry where a mapping key was expected", {
+          path: this.path, line: l.lineNo,
+        });
+      }
+      if (l.indent > indent) {
+        throw new AgentDocError(CODES.YAML_PARSE, "unexpected indentation", { path: this.path, line: l.lineNo });
+      }
+      const kv = splitKey(s);
+      if (!kv) {
+        throw new AgentDocError(CODES.YAML_PARSE, "expected 'key: value', got " + JSON.stringify(s.slice(0, 40)), {
+          path: this.path, line: l.lineNo,
+        });
+      }
+      if (Object.prototype.hasOwnProperty.call(out, kv.key)) {
+        throw new AgentDocError(CODES.YAML_DUP_KEY, "duplicate mapping key " + JSON.stringify(kv.key), {
+          path: this.path, line: l.lineNo,
+        });
+      }
+      this.i++;
+      out[kv.key] = this.value(l, kv.rest, indent);
+    }
+    return out;
+  }
+  seq(indent) {
+    const out = [];
+    for (;;) {
+      const l = this.peek();
+      if (!l || l.indent < indent) break;
+      const s = content(l).slice(l.indent);
+      if (!isSeqEntry(s)) {
+        if (l.indent > indent) {
+          throw new AgentDocError(CODES.YAML_PARSE, "unexpected indentation in sequence", { path: this.path, line: l.lineNo });
+        }
+        break;
+      }
+      const rest = s.slice(1).replace(/^[ \t]+/, "");
+      if (rest === "") {
+        this.i++;
+        out.push(this.node(indent + 1));
+        continue;
+      }
+      const dashOffset = l.indent + (s.length - rest.length);
+      if (splitKey(rest)) {
+        // Inline mapping opened by the dash: re-anchor it at the text column so
+        // continuation lines line up naturally.
+        this.ls[this.i] = { raw: " ".repeat(dashOffset) + rest, lineNo: l.lineNo, indent: dashOffset, blank: false, _c: null };
+        out.push(this.map(dashOffset));
+      } else {
+        this.i++;
+        out.push(this.scalarValue(l, rest, indent));
+      }
+    }
+    return out;
+  }
+  value(l, rest, indent) {
+    if (rest === "") return this.node(indent + 1);
+    if (rest[0] === "|" || rest[0] === ">") return this.blockScalar(l, rest, indent);
+    return scalar(rest, l.lineNo);
+  }
+  scalarValue(l, rest, indent) {
+    if (rest[0] === "|" || rest[0] === ">") return this.blockScalar(l, rest, indent);
+    return scalar(rest, l.lineNo);
+  }
+  blockScalar(l, head, indent) {
+    const m = /^([|>])([-+]?)([0-9]*)([-+]?)\s*$/.exec(head);
+    if (!m) {
+      throw new AgentDocError(CODES.YAML_UNSUPPORTED, "unsupported block scalar header " + JSON.stringify(head), {
+        path: this.path, line: l.lineNo,
+      });
+    }
+    const folded = m[1] === ">";
+    const chomp = m[2] || m[4] || "";
+    const explicit = m[3] ? Number(m[3]) : 0;
+    const body = [];
+    let blockIndent = explicit ? indent + explicit : -1;
+    while (this.i < this.ls.length) {
+      const n = this.ls[this.i];
+      const t = n.raw.trim();
+      if (t === "" && n.indent === 0) { body.push(""); this.i++; continue; }
+      if (n.indent <= indent) break;
+      if (blockIndent < 0) blockIndent = n.indent;
+      body.push(n.raw.slice(blockIndent));
+      this.i++;
+    }
+    while (body.length && body[body.length - 1] === "") body.pop();
+    let text;
+    if (folded) {
+      const parts = [];
+      let cur = "";
+      for (const b of body) {
+        if (b === "") { parts.push(cur); cur = ""; continue; }
+        cur = cur === "" ? b : cur + " " + b;
+      }
+      parts.push(cur);
+      text = parts.join("\n");
+    } else {
+      text = body.join("\n");
+    }
+    if (chomp !== "-") text += "\n";
+    return text;
+  }
+}
+
+// Parse a multi-document YAML stream. Returns [{doc, line}] with 1-based line
+// numbers of each document root. Catalog sources must be mappings; a reader of
+// third-party files whose root is a list (an Ansible playbook or task file)
+// opts in with `allowSequenceRoot`.
+export function parseYamlDocuments(src, path, { allowSequenceRoot = false } = {}) {
+  if (typeof src !== "string") throw new AgentDocError(CODES.UTF8, "expected text for " + path, { path });
+  if (src.charCodeAt(0) === 0xfeff) src = src.slice(1);
+  scanBanned(src, path);
+  const all = src.split("\n").map((raw, i) => makeLine(raw.replace(/\r$/, ""), i + 1));
+  const out = [];
+  let start = 0;
+  const bounds = [];
+  for (let i = 0; i < all.length; i++) {
+    const t = all[i].raw;
+    if (/^---(\s|$)/.test(t)) { bounds.push({ kind: "start", i }); }
+    else if (/^\.\.\.(\s|$)/.test(t)) { bounds.push({ kind: "end", i }); }
+  }
+  const segs = [];
+  let from = 0;
+  for (const b of bounds) {
+    if (b.kind === "start") { if (b.i > from) segs.push([from, b.i]); from = b.i + 1; }
+    else { segs.push([from, b.i]); from = b.i + 1; }
+  }
+  segs.push([from, all.length]);
+  for (const [a, b] of segs) {
+    const lines = all.slice(a, b);
+    const r = new Reader(lines, path);
+    r.i = 0;
+    const first = r.peek();
+    if (!first) continue;
+    const rootLine = first.lineNo;
+    const value = r.node(first.indent);
+    if (r.peek()) {
+      throw new AgentDocError(CODES.YAML_PARSE, "unparsed trailing content", { path, line: r.peek().lineNo });
+    }
+    if (value === null) continue;
+    if (typeof value !== "object" || (Array.isArray(value) && !allowSequenceRoot)) {
+      throw new AgentDocError(CODES.YAML_NON_MAP_ROOT, "document root must be a mapping", { path, line: rootLine });
+    }
+    out.push({ doc: value, line: rootLine });
+  }
+  return out;
+}
+
+export function parseYamlOne(src, path) {
+  const docs = parseYamlDocuments(src, path);
+  if (docs.length !== 1) {
+    throw new AgentDocError(CODES.YAML_PARSE, "expected exactly one YAML document in " + path, { path });
+  }
+  return docs[0].doc;
+}

package/docs/ADAPTERS.md

@@ -0,0 +1,207 @@
+# ADAPTERS
+
+An adapter knows one technology's vocabulary. It does not know your repository.
+
+## The contract
+
+```js
+class MyAdapter extends Adapter {
+  static adapterName = "my-technology";
+
+  constructor() { super({ name: "my-technology", version: "1.0.0", kind: "unit-marker" }); }
+
+  // Unit-marker adapters: does this directory host a unit of my kind?
+  detect(ctx, root) { return { path: root + "/manifest.toml", shape: "deployable" }; }
+
+  // Contribute workspace member roots the descriptor globs cannot know about.
+  roots(ctx) { return [{ root: "modules/a", importable: true }]; }
+
+  // Per-unit extraction. Return plain data; the pipeline merges it.
+  extract(ctx, unit) { return { languages: new Set(["mylang"]), bindings: [...] }; }
+
+  // Contract indexing. Runs once, after every unit is known.
+  contracts(ctx) { ctx.addContract({ apiRef, ref, operations: [...] }); }
+  }
+}
+```
+
+Available on `ctx`:
+
+| member | purpose |
+|---|---|
+| `repo` | tracked repository access (`readText`, `exists`, `isDir`, `walk`, `git`, `diffPaths`) |
+| `cfg` | the parsed configuration |
+| `refs` | `refFor`, `kindOfRef`, `isValidRef` for this repository's namespace |
+| `prov.add(class, path, extractor, subjects)` | create a provenance record |
+| `diagnostics.push({ severity, code, message, ... })` | a warning or an error |
+| `addFact(subject, key, value, { evidenceClass, confidence, provRecs, semantics, observed, review })` | record a claim |
+| `addEdge(type, sourceRef, targetRef, attributes, provRecs, evidenceClass)` | propose a relation |
+| `addEvent(pattern, role, componentRef, provRec, contract)` | an event subject |
+| `addExternal / addCapability` | indexes |
+| `addVerification({ id, componentRefs, tier, command, configPaths, provRecs })` | a component-scoped check |
+| `addGate({ id, tier, command, configPaths, provRecs })` | a repository-scoped check |
+| `transitiveDependencies(ref)` | manifest-declared dependencies, order-independent |
+| `productionDependencies(ref)` | production dependency names, for client-of-resource rules |
+| `deferSecondPass(fn)` | run after every unit is known |
+| `requirements` | declared normative requirements (`subject`, `key`, `value`, `source`, `satisfiedBy`, `expects`) an adapter may derive the implementation side of |
+| `unitByPkgName`, `unitByGoModule` | cross-unit resolution built before extraction |
+| `errors.push({ code, message })` | a hard error, collected rather than thrown |
+
+## The three rules
+
+### 1. An adapter may not know the repository
+
+No folder names, no project names, no domain vocabulary, no provider names, no
+event prefixes, no organisation. A `koda.` subject prefix is configuration
+(`discovery.eventPatternPrefixes`), not code. A `dist/` directory is a generated
+directory, not a component.
+
+If you catch yourself writing a project name in an adapter, the fact belongs in
+`agentdoc.config.yaml`.
+
+### 2. An adapter may not assert
+
+An adapter extracts. It does not decide. If your extractor can produce two
+answers, it must produce **neither** and a diagnostic:
+
+```js
+if (matches.length > 1) {
+  ctx.diagnostics.push({ severity: "warning", code: "AGENTDOC_BINDING_AMBIGUOUS", ... });
+  return;                       // not: pick matches[0]
+}
+```
+
+A candidate that is the only candidate is still a candidate, and candidates are
+never elected. Migration authority is not database ownership. A folder that
+looks like a service is not a service.
+
+### 3. Every fact needs evidence
+
+Anything an adapter adds carries provenance records it created itself. If you
+cannot name the file a fact came from, you cannot add the fact.
+
+## Shipped adapters
+
+| adapter | recognises | contributes |
+|---|---|---|
+| `generic` | — | health-route literals, a single-port fact |
+| `node` | `package.json` | importability, npm dependency edges, script tiers |
+| `pnpm` | `pnpm-workspace.yaml` | workspace member roots |
+| `turborepo` | `turbo.json` (nearest ancestor) | per-package task commands |
+| `typescript` | `tsconfig.json` | language, project references, file-router routes |
+| `go` | `go.mod`, `go.work` | module roots, module graph, `go test`/`go vet` |
+| `openapi` | `*.openapi.y[a]ml` | operation inventory, deterministic consumers |
+| `protobuf` / `graphql` | contract files | method/type inventory, consumers |
+| `oidc` | discovery-path literals | OIDC client consumers |
+| `github-actions` | repository-root `.github/workflows` (not a unit marker; a nested one is ignored, as GitHub ignores it) | component-scoped checks and repository gates |
+| `dockerfile` | `Dockerfile`, `Containerfile` | deployable evidence |
+| `deploy-config` | `fly.toml`, `Procfile`, … | deployable evidence |
+| `wrangler` | `wrangler.toml/json` | bindings, crons, service bindings, trigger targets |
+| `database` | migrations, ORM config, pool evidence | logical-database ownership, or a candidate |
+| `object-store` | bucket literals | logical-dataset edges, or an ambiguity |
+| `cache` | cache client evidence | cache bindings |
+| `events` | subject literals, declared constants, event-contract files | producers, consumers, reserved subjects |
+| `ansible` | playbooks (YAML lists of plays) | deployable evidence, installed paths and managed services, the DERIVED side of provisioning requirements |
+
+`generic` is always on. Everything else is opt-in through `adapters: [...]`, and
+an unknown name is `AGENTDOC_CONFIG`, not a silent no-op.
+
+### `ansible`
+
+Reads playbooks under a unit root and follows what they reach — plays,
+`roles:`, `include_role`/`import_role`, `include_tasks`/`import_tasks`,
+`import_playbook`, `block`/`rescue`/`always` — inside the repository only.
+Nothing is executed and no Jinja is evaluated.
+
+| it derives | from |
+|---|---|
+| an installed path | `copy`/`template`/`get_url`/`git`/`synchronize` `dest`, `unarchive` `dest`/`creates`, `pip` `virtualenv`, `file` with `state: directory\|touch\|link\|hard`, `lineinfile`/`blockinfile` with `create: true`, a command's literal `creates` |
+| a managed service | `systemd`, `systemd_service`, `service` `name` |
+
+The inventory lands on the component as `derived.provisioning`. For a normative
+requirement on that component with `satisfiedBy: [ansible]` and an `expects`
+(`installs: <path>` or `service: <name>`), it adds a `DERIVED` fact on the
+requirement key:
+
+| value | confidence | when |
+|---|---|---|
+| `provided` | deterministic | a reachable task without `when` installs the path (or a path below it), or manages the service |
+| `provided` | candidate | the only matching task is conditional (`when`, `rescue`, a conditional role or include) |
+| `absent` | deterministic | no reachable task matches **and** every reachable task is transparent |
+| `absent` | candidate | no task matches, but something opaque was reached |
+
+**What it cannot see, and therefore never rules out:** a command
+(`shell`/`command`/`script`/`raw`) without a literal `creates`; a module it does
+not model (`apt`, `dnf`, `package`, collections, …); a templated path or a
+`loop`; a role, include or imported playbook that is not in the repository or is
+templated; a file that does not parse. Any of these makes an absence a
+candidate, which is never elected — the requirement stays
+`AGENTDOC_REQUIREMENT_UNVERIFIED` and the diagnostic names what was opaque.
+Inventory files, `group_vars`/`host_vars` and variables are not read.
+
+`asyncapi` is a contract **type** (declared on an API descriptor, validated by
+the contract layer), not an adapter — there is no `asyncapi` entry in
+`adapters: [...]`.
+
+## Enabling
+
+Adapters only cost what they read. Start with what the repository demonstrably
+uses; add more when the audit says a fact is missing. Enabling every adapter is
+not free and not always right: `events` with no `eventPatternPrefixes` falls back
+to a conservative three-segment subject shape, which is right for subject-based
+brokers and wrong for a repository that uses dotted identifiers for something
+else entirely.
+
+## Determinism
+
+An adapter is a pure function of the checkout and the configuration.
+
+- Sort everything. `Set` iteration order is insertion order, which depends on
+  the order files were read.
+- Never read a clock, an environment variable outside the repository, a random
+  value, or an absolute path. The determinism guard scans the graph's structure
+  for exactly these, and compilation fails if one appears.
+- Do not depend on execution order. `transitiveDependencies` and
+  `unitByPkgName` are computed from manifests before extraction; use them rather
+  than reading `ctx.edges`.
+- Bump `version` when behaviour changes. It is part of the graph input hash, so
+  an upgrade invalidates every graph — which is correct, because the graph
+  changes.
+
+## Testing an adapter
+
+1. Build a fixture with the smallest repository the adapter must recognise, plus
+   one ambiguity it must refuse.
+2. Assert the exact diagnostics and error codes, not message text.
+3. Assert that two compiles produce identical bytes.
+4. Assert the provenance: every added record names a real file and a real hash.
+
+The adversarial suite (`tests/adversarial.test.mjs`) is the model: inject a
+defect, assert the right code.
+
+## What the core still knows
+
+The engine's *layout* knowledge is empty: no folder name, no provider, no domain
+vocabulary. It does, however, know the shape of a manifest filename in three
+places, and those are the honest exceptions worth naming:
+
+- `core/compile.mjs` builds a manifest pre-pass over `package.json`, `go.mod`
+  and `go.work`, so `unitByPkgName`, `unitByGoModule` and
+  `transitiveDependencies` are available to every adapter regardless of
+  execution order.
+- `core/impact.mjs` classifies a changed file by consulting the compiled graph —
+  its contracts, its provenance paths, its extractor identities — rather than a
+  hand-written list of technology filenames. A list would silently under-report
+  for every repository that is not Node-and-Go.
+- `core/discover.mjs` has a default list of directories that are never units
+  (`agentdoc`, `docs`, `scripts`, `.github`), overridable through
+  `discovery.notUnitRoots`.
+
+Each is a place a future change should push outward, not a licence to add more.
+
+## Adding one to a project
+
+Adapters live in the compiler, not in the project, precisely so a project cannot
+extend the fact model into something unreviewable. If your technology is not
+covered, the honest options are to describe the boundary with a canonical
+contract and a `reviewedOverride`, or to contribute an adapter upstream.