agent-doc-system 0.0.0-stage → 1.0.0

package/adapters/generic.mjs

@@ -0,0 +1,86 @@
+// Generic adapter: language- and toolchain-agnostic facts only.
+//
+// Nothing here knows a language, a package manager, a provider or a folder
+// name. It contributes the two things any repository can be said to have:
+// conventional documentation (handled in core/derive.mjs) and health contract
+// route literals found in source.
+import { Adapter } from "./registry.mjs";
+import { resolveClientResources } from "./resource-client.mjs";
+import { sourceFiles } from "../core/sourcescan.mjs";
+
+// Conservative: a health route is an absolute string literal that looks like a
+// liveness or readiness endpoint. Anything more specific belongs to a
+// framework adapter.
+const HEALTH_LITERAL = /["'`](\/(?:healthz|health|livez|readyz|ready|ping|status))["'`]/;
+
+export class GenericAdapter extends Adapter {
+  static adapterName = "generic";
+  constructor() {
+    super({ name: "generic", version: "1.0.0", kind: "source" });
+  }
+
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const derived = { healthContracts: [] };
+    const seen = new Set();
+    const ports = new Set();
+    const portFiles = new Map();
+    const allSrc = sourceFiles(repo, unit.root, { test: false });
+    for (const f of allSrc) {
+      const text = repo.readText(f);
+      const pm = /ListenAndServe\(\s*":(\d{2,5})"|\bPORT\s*=\s*"?(\d{2,5})"?|\bport:\s*(\d{2,5})\b/.exec(text);
+      if (pm) {
+        const p = pm[1] || pm[2] || pm[3];
+        ports.add(p);
+        if (!portFiles.has(p)) portFiles.set(p, f);
+      }
+      const m = HEALTH_LITERAL.exec(text);
+      if (!m) continue;
+      const route = m[1];
+      if (seen.has(route)) continue;
+      seen.add(route);
+      const pr = prov.add("observed", f, "health-extractor", ["der:" + compRef + ":/healthContracts"]);
+      derived.healthContracts.push({ path: f, route, semantics: "liveness", provenanceIds: null, _provs: new Set([pr]) });
+    }
+    if (derived.healthContracts.length > 1) derived.healthContracts.sort((a, b) => (a.route < b.route ? -1 : 1));
+    // A port is only a fact when the source states exactly one. Two literals
+    // mean the component binds more than one, and a single number would be a
+    // confident half-truth.
+    // Declared external services front Resources; resolve those bindings.
+    // Provenance must name a file that exists. The dependency evidence is the
+    // manifest when there is one, and otherwise the unit's descriptor.
+    const manifest = ["package.json", "go.mod", "Cargo.toml", "pyproject.toml", "pom.xml"]
+      .map((n) => unit.root + "/" + n)
+      .find((p) => repo.exists(p)) || ctx.componentEntity().file;
+    const clientProv = prov.add("observed", manifest, "client-resolver", ["rel:pending", "der:" + compRef + ":/bindings"]);
+    resolveClientResources(ctx, unit, compRef, clientProv);
+
+    // Capability detectors are declared, not hard-coded: a manifest cannot tell
+    // you a component can use a browser API, but a source literal can.
+    for (const cap of (ctx.cfg.discovery.capabilities || [])) {
+      let re;
+      try {
+        re = new RegExp(cap.match);
+      } catch {
+        continue;
+      }
+      for (const f of allSrc) {
+        if (!re.test(repo.readText(f))) continue;
+        const cpr = prov.add("observed", f, "capability-extractor", ["cap:" + compRef + "|" + cap.name]);
+        ctx.addCapability(compRef, cap.name, cpr, "DERIVED");
+        break;
+      }
+    }
+
+    if (ports.size === 1) {
+      const p = [...ports][0];
+      const pr = prov.add("observed", portFiles.get(p) || ctx.componentEntity().file, "port-extractor", ["der:" + compRef + ":/port"]);
+      derived.port = Number(p);
+      ctx.addFact(compRef, "component.port", Number(p), {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "the single TCP port the source binds a listener to",
+      });
+    }
+    return derived;
+  }
+}

package/adapters/github-actions.mjs

@@ -0,0 +1,106 @@
+// GitHub Actions adapter.
+//
+// CI is a verification authority: a workflow that names a component's paths is
+// the check that must be run for that component. Recording the mapping means
+// an agent changing a component is told which gate covers it, instead of
+// guessing or running everything.
+import { Adapter } from "./registry.mjs";
+import { parseYamlDocuments } from "../core/yaml.mjs";
+
+export class GitHubActionsAdapter extends Adapter {
+  static adapterName = "github-actions";
+  constructor() {
+    super({ name: "github-actions", version: "1.0.0", kind: "ci" });
+  }
+  detect(ctx, root) {
+    const p = root + "/.github/workflows";
+    if (!ctx.repo.isDir(p)) return null;
+    return { path: p, shape: "importable" };
+  }
+  contracts(ctx) {
+    const dir = ".github/workflows";
+    if (!ctx.repo.isDir(dir)) return [];
+    const out = [];
+    const files = ctx.repo.walk(dir).filter((f) => /\.ya?ml$/.test(f)).sort();
+    const units = ctx.discovery.eligible.filter((u) => u.component);
+    for (const f of files) {
+      let text = "";
+      try {
+        text = ctx.repo.readText(f);
+      } catch {
+        continue;
+      }
+      let doc = null;
+      try {
+        doc = parseYamlDocuments(text, f)[0]?.doc;
+      } catch {
+        doc = null;
+      }
+      const steps = [];
+      if (doc && doc.jobs) {
+        for (const [jobName, job] of Object.entries(doc.jobs)) {
+          for (const step of (job && job.steps) || []) {
+            const run = [step.run, step.uses].filter(Boolean).join(" ");
+            if (!run) continue;
+            steps.push({ job: jobName, run: String(run) });
+          }
+        }
+      }
+      const covered = new Set();
+      for (const u of units) {
+        if (text.includes(u.root + "/") || (u.pkgName && text.includes(u.pkgName))) covered.add(u.component.ref);
+      }
+      const pr = ctx.prov.add("observed", f, "ci-extractor", []);
+      const subjects = [];
+      steps.forEach((s, i) => {
+        if (!/[a-z0-9]/i.test(s.run)) return;
+        const command = s.run.trim().slice(0, 600);
+        // A step that installs dependencies or checks out code is not a check.
+        // Recording it as one would bury the commands that actually gate.
+        const tier = ciTier(command);
+        if (!tier) return;
+        const id = "ci:" + f.replace(/[^A-Za-z0-9]+/g, "-") + ":" + s.job + ":" + i;
+        if (covered.size) {
+          ctx.addVerification({
+            id,
+            componentRefs: [...covered].sort(),
+            tier,
+            command,
+            configPaths: [f],
+            provRecs: [pr],
+          });
+          subjects.push("ver:" + id);
+        } else {
+          // A gate that names no component is repository-wide: it applies to
+          // everything, so it is recorded once as a gate rather than
+          // duplicated onto every component.
+          // The graph id must not itself start with the provenance prefix, or
+          // the subject key becomes ambiguous. "repo-gate:" is unambiguous.
+          const gid = "repo-gate:" + f.replace(/[^A-Za-z0-9]+/g, "-") + ":" + s.job + ":" + i;
+          ctx.addGate({ id: gid, tier: ciTier(command), command, configPaths: [f], provRecs: [pr] });
+          subjects.push("gate:" + gid);
+        }
+      });
+      for (const s of subjects) pr.subjects.add(s);
+      void steps;
+      void covered;
+    }
+    return out;
+  }
+}
+
+// Returns null for a step that is not a check. Install, checkout, cache and
+// upload steps gate nothing and would only add noise to a routing surface.
+const NOT_A_CHECK = /^\s*(?:-\s*)?(?:uses:\s*actions\/(?:checkout|cache|upload|download|setup-|artifact)|run:\s*(?:\w*\s*)?(?:pnpm|npm|yarn|bun)\s+(?:i|install|ci)\b)/i;
+
+function ciTier(run) {
+  if (NOT_A_CHECK.test(run.trim())) return null;
+  if (/^uses:/.test(run.trim()) && !/check|lint|test|build|audit|scan/i.test(run)) return null;
+  if (/e2e|playwright|cypress/.test(run)) return "e2e";
+  if (/contract|openapi|api:check|drift|catalog/.test(run)) return "contract";
+  if (/integration/.test(run)) return "integration";
+  if (/lint|typecheck|type-check|golangci|vet/.test(run)) return "static";
+  if (/\btest\b|pytest|vitest|jest|go test/.test(run)) return "unit";
+  if (/\bbuild\b|tsc|compile/.test(run)) return "build";
+  return null;
+}

package/adapters/go.mjs

@@ -0,0 +1,91 @@
+// Go adapter: go.mod / go.work as unit markers, module graph as build
+// relations, and the go toolchain's own verification commands.
+import { Adapter } from "./registry.mjs";
+
+export class GoAdapter extends Adapter {
+  static adapterName = "go";
+  constructor() {
+    super({ name: "go", version: "1.0.0", kind: "unit-marker" });
+  }
+  roots(ctx) {
+    const out = [];
+    const ws = "go.work";
+    if (!ctx.repo.exists(ws)) return out;
+    const text = ctx.repo.readText(ws);
+    const block = /use\s*\(([^)]*)\)/s.exec(text);
+    const candidates = block
+      ? block[1].split("\n").map((l) => l.replace(/\/\/.*$/, "").trim()).filter(Boolean)
+      : [...text.matchAll(/^\s*use\s+(\S+)/gm)].map((m) => m[1]);
+    for (const raw of candidates) {
+      const d = raw.replace(/^\.\//, "").replace(/\/$/, "");
+      if (!d || d.startsWith("//") || d.includes("..")) continue;
+      if (!ctx.repo.isDir(d)) continue;
+      if (!ctx.repo.exists(d + "/go.mod")) continue;
+      out.push({ root: d, deployable: ctx.repo.isDir(d + "/cmd"), importable: !ctx.repo.isDir(d + "/cmd") });
+    }
+    return out;
+  }
+  detect(ctx, root) {
+    const p = root + "/go.mod";
+    if (!ctx.repo.exists(p)) return null;
+    return { path: p, shape: ctx.repo.isDir(root + "/cmd") ? "deployable" : "importable" };
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const p = unit.root + "/go.mod";
+    if (!repo.exists(p)) return {};
+    const derived = { languages: new Set(["go"]), runtimes: new Set(["go"]) };
+    const text = repo.readText(p);
+    const pr = prov.add("observed", p, "gomod-extractor", ["der:" + compRef + ":/runtimes", "der:" + compRef + ":/languages"]);
+
+    for (const m of text.matchAll(/^\s*(?:require\s+)?([a-z0-9.]+\.[a-z0-9./-]+)\s+v[0-9]/gm)) {
+      const mod = m[1];
+      const target = ctx.unitByGoModule.get(mod);
+      if (target && target.component && target.component.ref !== compRef) {
+        ctx.addEdge("buildDependsOn", compRef, target.component.ref, { via: "go-module" }, [pr], "DERIVED");
+      } else {
+        for (const x of ctx.externalMatchers()) {
+          if (!x.re.test(mod)) continue;
+          ctx.addExternal(compRef, x.name, x.mechanism, x.role, pr, "DERIVED");
+        }
+      }
+    }
+    // Workspace members depended on by import alone. A Go workspace member can
+    // have no require line at all, so the import graph is the only evidence.
+    for (const importPath of ctx.importIndex.goPathsByUnit.get(unit) || []) {
+      for (const [mod, target] of ctx.unitByGoModule) {
+        if (target === unit || !target.component) continue;
+        if (importPath !== mod && importPath.startsWith(mod + "/")) {
+          ctx.addEdge("buildDependsOn", compRef, target.component.ref, { via: "go-import" }, [pr], "DERIVED");
+        }
+      }
+    }
+
+    const hasTests = repo.walk(unit.root).some((f) => /_test\.go$/.test(f));
+    ctx.addVerification({
+      id: compRef + ":go-test",
+      componentRefs: [compRef],
+      tier: "unit",
+      command: "go test ./...",
+      configPaths: [p],
+      provRecs: [pr],
+    });
+    ctx.addVerification({
+      id: compRef + ":go-vet",
+      componentRefs: [compRef],
+      tier: "static",
+      command: "go vet ./...",
+      configPaths: [p],
+      provRecs: [pr],
+    });
+    if (hasTests) derived.hasTests = true;
+    derived.goModule = unit.goModule;
+    return derived;
+  }
+}
+
+export function goExternalName(mod) {
+  const parts = mod.split("/");
+  const tail = parts[parts.length - 1].replace(/\.v\d+$/, "");
+  return (tail || parts[0]).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "go-module";
+}

package/adapters/graphql.mjs

@@ -0,0 +1,28 @@
+// GraphQL adapter: SDL as the canonical contract plus deterministic consumer
+// resolution.
+import { Adapter } from "./registry.mjs";
+import { resolveContractConsumers, isBuildConfig } from "./contract-consumers.mjs";
+
+export class GraphQLAdapter extends Adapter {
+  static adapterName = "graphql";
+  constructor() {
+    super({ name: "graphql", version: "1.0.0", kind: "contract" });
+  }
+  contracts(ctx) {
+    const out = [];
+    for (const api of ctx.sources.entities.filter((e) => e.kind === "API" && ["graphql", "graphql-sdl"].includes(e.doc.spec.type))) {
+      const ref = api.doc.spec.contract.ref;
+      const text = ctx.repo.readText(ref);
+      const types = [...text.matchAll(/^\s*(?:type|interface|input|enum|scalar|union)\s+([A-Za-z_][A-Za-z0-9_]*)/gm)].map((m) => m[1]);
+      const queries = [...text.matchAll(/^\s*(?:extend\s+)?type\s+Query\s*\{([\s\S]*?)\n\}/gm)]
+        .flatMap((m) => [...m[1].matchAll(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*[(:]/gm)].map((x) => x[1]));
+      ctx.addContract({ apiRef: api.ref, ref, types: [...new Set(types)].sort(), queries: [...new Set(queries)].sort() });
+      const consumers = resolveContractConsumers(ctx, ref, api.doc.spec.provider);
+      for (const [consumerRef, files] of consumers) {
+        const provs = files.map((f) => ctx.prov.add(isBuildConfig(f) ? "validated" : "observed", f, "api-contract-extractor", ["rel:pending"]));
+        ctx.addEdge("consumesApi", consumerRef, api.ref, { via: files.some(isBuildConfig) ? "codegen" : "source-reference" }, provs, "DERIVED");
+      }
+    }
+    return out;
+  }
+}

package/adapters/index.mjs

@@ -0,0 +1,55 @@
+// Adapter registry. Adapters are looked up by name and instantiated once.
+// An unknown adapter name is a configuration error, never a silent no-op: a
+// project that thinks it has protobuf discovery must not lose it quietly.
+import { AgentDocError, CODES } from "../core/codes.mjs";
+import { GenericAdapter } from "./generic.mjs";
+import { NodeAdapter } from "./node.mjs";
+import { PnpmAdapter } from "./pnpm.mjs";
+import { TurborepoAdapter } from "./turborepo.mjs";
+import { TypeScriptAdapter } from "./typescript.mjs";
+import { GoAdapter } from "./go.mjs";
+import { OpenApiAdapter } from "./openapi.mjs";
+import { ProtobufAdapter } from "./protobuf.mjs";
+import { GraphQLAdapter } from "./graphql.mjs";
+import { OidcAdapter } from "./oidc.mjs";
+import { GitHubActionsAdapter } from "./github-actions.mjs";
+import { DockerfileAdapter } from "./dockerfile.mjs";
+import { WranglerAdapter } from "./wrangler.mjs";
+import { DatabaseAdapter } from "./database.mjs";
+import { EventsAdapter } from "./events.mjs";
+import { DeployConfigAdapter } from "./deploy-config.mjs";
+import { ObjectStoreAdapter } from "./object-store.mjs";
+import { CacheAdapter } from "./cache.mjs";
+
+const REGISTRY = new Map();
+for (const C of [
+  GenericAdapter, NodeAdapter, PnpmAdapter, TurborepoAdapter, TypeScriptAdapter,
+  GoAdapter, OpenApiAdapter, ProtobufAdapter, GraphQLAdapter, OidcAdapter,
+  GitHubActionsAdapter, DockerfileAdapter, WranglerAdapter, DatabaseAdapter,
+  EventsAdapter, DeployConfigAdapter, ObjectStoreAdapter, CacheAdapter,
+]) {
+  REGISTRY.set(C.prototype.constructor.adapterName, new C());
+}
+
+export function adapterNames() {
+  return [...REGISTRY.keys()].sort();
+}
+
+export function loadAdapters(names) {
+  // The generic adapter is always on: documentation conventions and health
+  // contract detection are language-agnostic and cost nothing.
+  const out = [REGISTRY.get("generic")];
+  for (const n of names || []) {
+    const a = REGISTRY.get(n);
+    if (!a) {
+      throw new AgentDocError(
+        CODES.CONFIG,
+        "unknown adapter '" + n + "'; available adapters: " + adapterNames().join(", ")
+      );
+    }
+    if (out.includes(a)) continue;
+    out.push(a);
+  }
+  // Deterministic order, independent of how the config listed them.
+  return out.slice().sort((x, y) => (x.name < y.name ? -1 : x.name > y.name ? 1 : 0));
+}

package/adapters/node.mjs

@@ -0,0 +1,118 @@
+// Node adapter: package.json as the unit marker and manifest authority.
+import { Adapter } from "./registry.mjs";
+
+// A script name maps to a verification tier. Deliberately conservative and
+// project-neutral: a script that does not look like a check is not a check.
+const TIERS = [
+  [/^(test|tests)$|^test:unit$|^test:unit:/, "unit"],
+  [/^test:integration$|^test:integration:/, "integration"],
+  [/^test:contract$|^test:contract:/, "contract"],
+  [/^test:e2e$|^test:e2e:/, "e2e"],
+  [/^test:browser$/, "unit"],
+  [/^(lint|typecheck|check-types|type-check)$/, "static"],
+  [/^(build|compile)$/, "build"],
+];
+const IGNORED_SCRIPT = /^(dev|start|serve|watch|preview|clean|postinstall|preinstall|prepare|format|format:fix)$/;
+
+export class NodeAdapter extends Adapter {
+  static adapterName = "node";
+  constructor() {
+    super({ name: "node", version: "1.0.0", kind: "unit-marker" });
+  }
+  detect(ctx, root) {
+    const p = root + "/package.json";
+    if (!ctx.repo.exists(p)) return null;
+    let pkg;
+    try {
+      pkg = ctx.repo.readJson(p);
+    } catch {
+      return null; // malformed manifest is not authority
+    }
+    const importable = Boolean(pkg.exports || pkg.main || pkg.bin || pkg.types);
+    return { path: p, shape: importable ? "both" : "deployable" };
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const root = unit.root;
+    const manifestPath = root + "/package.json";
+    if (!repo.exists(manifestPath)) return {};
+    const derived = { languages: new Set(["javascript"]), runtimes: new Set(["node"]) };
+    const pkg = unit.pkg || repo.readJson(manifestPath);
+
+    const pr = prov.add("observed", manifestPath, "manifest-extractor", [
+      "der:" + compRef + ":/runtimes", "der:" + compRef + ":/languages", "der:" + compRef + ":/artifact",
+    ]);
+    const prodDeps = new Set([...Object.keys(pkg.dependencies || {}), ...Object.keys(pkg.optionalDependencies || {})]);
+    const devDeps = new Set(Object.keys(pkg.devDependencies || {}));
+
+    // Only declared external services are classified. A package in a manifest
+    // is a build fact, not an architectural dependency, and recording six
+    // hundred of them would make the index useless.
+    for (const d of [...prodDeps].sort()) {
+      for (const x of ctx.externalMatchers()) {
+        if (!x.re.test(d)) continue;
+        ctx.addExternal(compRef, x.name, x.mechanism, x.role, pr, "DERIVED");
+      }
+    }
+
+    // Workspace resolution: a dependency naming another discovered unit is a
+    // build relation, not an external dependency.
+    for (const d of [...prodDeps, ...devDeps].sort()) {
+      const target = ctx.unitByPkgName.get(d);
+      if (!target || !target.component) continue;
+      const isProd = prodDeps.has(d);
+      ctx.addEdge(isProd ? "buildDependsOn" : "testDependsOn", compRef, target.component.ref,
+        { via: "npm-manifest", package: d }, [pr], "DERIVED");
+    }
+
+    // Source imports are stronger evidence than the manifest, and catch
+    // subpath imports the manifest cannot express.
+    const sibling = new Map();
+    for (const spec of ctx.unitImports.keys()) {
+      const parts = spec.split("/");
+      const base = spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+      const target = ctx.unitByPkgName.get(base);
+      if (!target || !target.component || target.component.ref === compRef) continue;
+      if (prodDeps.has(base)) continue;
+      if (!sibling.has(target)) sibling.set(target, new Set());
+      for (const f of ctx.unitImports.get(spec)) sibling.get(target).add(f);
+    }
+    for (const [target, files] of [...sibling.entries()].sort((a, b) => (a[0].root < b[0].root ? -1 : 1))) {
+      const provs = [...files].sort().map((f) => prov.add("observed", f, "import-extractor", ["rel:pending"]));
+      // The import names the same package the manifest route names, so it
+      // carries the same instance key. Without it, a dependency found by both
+      // routes shipped as two edges — the manifest one saying `package`, the
+      // import one not — which measures adapter overlap rather than architecture.
+      const pkgName = target.pkgName;
+      const attrs = pkgName ? { via: "source-import", package: pkgName } : { via: "source-import" };
+      ctx.addEdge(devDeps.has(pkgName) ? "testDependsOn" : "buildDependsOn",
+        compRef, target.component.ref, attrs, provs, "DERIVED");
+    }
+
+    for (const [name, cmd] of Object.entries(pkg.scripts || {}).sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+      if (IGNORED_SCRIPT.test(name)) continue;
+      const tier = TIERS.find(([re]) => re.test(name));
+      if (!tier) continue;
+      const vpr = prov.add("observed", manifestPath, "verification-extractor", ["ver:" + compRef + ":" + name]);
+      ctx.addVerification({
+        id: compRef + ":" + name,
+        componentRefs: [compRef],
+        tier: tier[1],
+        command: String(cmd).trim(),
+        configPaths: [manifestPath],
+        provRecs: [vpr],
+      });
+    }
+    return derived;
+  }
+}
+
+// Normalise a package name into a graph-safe external dependency name.
+export function externalName(d) {
+  const n = d
+    .replace(/^@[^/]+\//, "")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+  return /^[a-z0-9]/.test(n) ? n.slice(0, 60) : "pkg-" + n.replace(/[^a-z0-9]/g, "").slice(0, 50);
+}

package/adapters/object-store.mjs

@@ -0,0 +1,64 @@
+// Object-store adapter: bucket bindings and literal bucket names.
+//
+// A bucket literal in a component's source is deterministic evidence that the
+// component touches that store. It is only turned into a resource relation when
+// exactly one authored logical-dataset Resource matches — an ambiguous literal
+// is left unresolved rather than guessed at.
+import { Adapter } from "./registry.mjs";
+
+const SRC_EXT = /\.(ts|tsx|js|jsx|mts|cts|go|py|rb|java|kt|rs)$/;
+const TEST_PATH = /(^|\/)(tests?|__tests__|spec)\//;
+const TEST_FILE = /\.(test|spec)\./;
+const BUCKET_LITERAL = /["'`]([a-z][a-z0-9-]{4,60})["'`]/g;
+const STORE_HINT = /(@aws-sdk\/client-s3|minio|google\.cloud\.storage|\bS3\b|bucket|Bucket|BlobService|createBucket)/i;
+
+export class ObjectStoreAdapter extends Adapter {
+  static adapterName = "object-store";
+  constructor() {
+    super({ name: "object-store", version: "1.0.0", kind: "source" });
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const datasets = ctx.sources.entities.filter((e) => e.kind === "Resource" && e.doc.spec.type === "logical-dataset");
+    if (!datasets.length) return {};
+    const usesStore = ctx.unitImports && [...ctx.unitImports.keys()].some((k) => /s3|minio|storage|blob/i.test(k));
+    const bindings = [];
+    const claimed = new Set();
+    for (const f of repo.walk(unit.root)) {
+      if (!SRC_EXT.test(f)) continue;
+      if (TEST_PATH.test(f) || TEST_FILE.test(f)) continue;
+      const text = repo.readText(f);
+      if (!STORE_HINT.test(text)) continue;
+      for (const m of text.matchAll(BUCKET_LITERAL)) {
+        const lit = m[1];
+        const matches = datasets.filter((d) => lit.includes(token(d.name)) || d.name.includes(token(lit)));
+        if (matches.length !== 1) {
+          if (matches.length > 1) {
+            ctx.diagnostics.push({
+              severity: "warning",
+              code: "AGENTDOC_BINDING_AMBIGUOUS",
+              subject: compRef,
+              refs: [compRef],
+              message: "bucket literal '" + lit + "' in " + f + " matches " + matches.length + " authored logical-dataset Resources; left unresolved",
+              paths: [f],
+            });
+          }
+          continue;
+        }
+        if (claimed.has(matches[0].ref)) continue;
+        claimed.add(matches[0].ref);
+        const pr = prov.add("observed", f, "binding-extractor", ["der:" + compRef + ":/bindings", "rel:pending"]);
+        bindings.push({ kind: "object-store", logicalResourceRef: matches[0].ref, locator: { bucket: lit }, resolution: "resolved", provenanceIds: null, _provs: new Set([pr]) });
+        const client = ctx.clientKeyForResourceType("logical-dataset");
+        const attrs = client ? { via: "bucket-literal", client } : { via: "bucket-literal" };
+        ctx.addEdge("usesResource", compRef, matches[0].ref, attrs, [pr], "DERIVED");
+      }
+    }
+    if (!usesStore && !bindings.length) return {};
+    return bindings.length ? { bindings } : { objectStoreClientOnly: true };
+  }
+}
+
+function token(name) {
+  return name.split("-")[0];
+}

package/adapters/oidc.mjs

@@ -0,0 +1,56 @@
+// OIDC adapter.
+//
+// The canonical authority for an OIDC surface is the published standard plus
+// the provider's discovery document, both of which live outside the repository
+// (EXTERNAL_STANDARD). What the repository can establish is narrower and is
+// recorded as such: which units implement a client against the declared
+// discovery path, and the fact that the provider exposes that path.
+//
+// A discovery document fetched from a live deployment is an OBSERVED_RUNTIME
+// fact and belongs in an ObservationSet, not here.
+import { Adapter } from "./registry.mjs";
+import { sourceFiles } from "../core/sourcescan.mjs";
+
+// A component is an OIDC client when it both names the discovery surface and
+// shows the shape of a token request. One of the two alone is not enough: a
+// comment mentioning /oidc/token, or a bare import of an OAuth helper in a
+// component that never calls the identity provider, would both produce a false
+// edge, and a false edge is worse than a missing one.
+const DISCOVERY_HINT = /(\.well-known\/openid-configuration|jwks_uri|token_endpoint|\/oidc\/token|oauth2?\/token)/i;
+// Both naming conventions: the wire names (snake_case, as in JSON) and the
+// field names a typed client uses (camelCase, as in Go and TypeScript).
+const TOKEN_REQUEST_HINT = /(grant_?type|client_?id|client_?secret|jwks|authoriz|id_?token|access_?token|userinfo|refresh_?token)/i;
+
+export class OidcAdapter extends Adapter {
+  static adapterName = "oidc";
+  constructor() {
+    super({ name: "oidc", version: "1.0.0", kind: "contract" });
+  }
+  contracts(ctx) {
+    const out = [];
+    for (const api of ctx.sources.entities.filter((e) => e.kind === "API" && e.doc.spec.type === "oidc")) {
+      const discoveryPath = api.doc.spec.contract.discoveryPath;
+      const providerFile = api.file;
+      const providerRef = api.doc.spec.provider;
+      const hosts = new Map();
+      for (const unit of ctx.discovery.eligible) {
+        if (!unit.component) continue;
+        for (const f of sourceFiles(ctx.repo, unit.root, { test: false })) {
+          const text = ctx.repo.readText(f);
+          const namesDiscovery = text.includes(discoveryPath) || DISCOVERY_HINT.test(text);
+          if (namesDiscovery && TOKEN_REQUEST_HINT.test(text)) {
+            hosts.set(unit.component.ref, f);
+            break;
+          }
+        }
+      }
+      hosts.delete(providerRef);
+      for (const [ref, file] of [...hosts.entries()].sort()) {
+        const pr = ctx.prov.add("validated", file, "oidc-extractor", ["rel:pending"]);
+        ctx.addEdge("consumesApi", ref, api.ref, { via: "oidc-client" }, [pr], "DERIVED");
+      }
+      ctx.addContract({ apiRef: api.ref, ref: providerFile, standard: api.doc.spec.contract.standard, discoveryPath, consumers: [...hosts.keys()].sort() });
+    }
+    return out;
+  }
+}

package/adapters/openapi.mjs

@@ -0,0 +1,50 @@
+// OpenAPI adapter.
+//
+// The catalog points at the canonical contract; it never duplicates it. What
+// the adapter adds is (a) the operation inventory an agent needs to find a
+// handler without reading the whole spec, and (b) deterministic consumer
+// resolution from the contract reference.
+import { Adapter } from "./registry.mjs";
+import { resolveContractConsumers, isBuildConfig } from "./contract-consumers.mjs";
+import { parseYamlDocuments } from "../core/yaml.mjs";
+import { parse as parseToml } from "../core/toml.mjs";
+
+const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+
+export class OpenApiAdapter extends Adapter {
+  static adapterName = "openapi";
+  constructor() {
+    super({ name: "openapi", version: "1.0.0", kind: "contract" });
+  }
+  contracts(ctx) {
+    const out = [];
+    for (const api of ctx.sources.entities.filter((e) => e.kind === "API" && e.doc.spec.type === "openapi")) {
+      const ref = api.doc.spec.contract.ref;
+      let doc = null;
+      try {
+        doc = parseYamlDocuments(ctx.repo.readText(ref), ref)[0]?.doc || JSON.parse(ctx.repo.readText(ref, { track: false }));
+      } catch {
+        continue;
+      }
+      const operations = [];
+      for (const [route, item] of Object.entries((doc && doc.paths) || {})) {
+        for (const m of METHODS) {
+          if (item && typeof item === "object" && item[m]) {
+            operations.push({ method: m.toUpperCase(), route, operationId: item[m].operationId || null });
+          }
+        }
+      }
+      operations.sort((a, b) => (a.route + a.method < b.route + b.method ? -1 : 1));
+      ctx.addContract({ apiRef: api.ref, ref, operations, title: doc?.info?.title || null });
+
+      const consumers = resolveContractConsumers(ctx, ref, api.doc.spec.provider);
+      for (const [ref2, files] of consumers) {
+        const provs = files.map((f) => ctx.prov.add(isBuildConfig(f) ? "validated" : "observed", f, "api-contract-extractor", ["rel:pending"]));
+        ctx.addEdge("consumesApi", ref2, api.ref, { via: files.some(isBuildConfig) ? "codegen" : "source-reference" }, provs, "DERIVED");
+      }
+    }
+    return out;
+  }
+}
+
+export { parseToml };