agent-doc-system 0.0.0-stage → 1.1.0

package/adapters/index.mjs

@@ -0,0 +1,56 @@
+// 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";
+import { AnsibleAdapter } from "./ansible.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, AnsibleAdapter,
+]) {
+  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 };

package/adapters/pnpm.mjs

@@ -0,0 +1,42 @@
+// pnpm workspace adapter: contributes workspace member roots so the descriptor
+// globs do not have to know the layout, and records the workspace file as
+// evidence for the repository as a whole.
+import { Adapter } from "./registry.mjs";
+import { parseYamlDocuments } from "../core/yaml.mjs";
+
+export class PnpmAdapter extends Adapter {
+  static adapterName = "pnpm";
+  constructor() {
+    super({ name: "pnpm", version: "1.0.0", kind: "workspace" });
+  }
+  roots(ctx) {
+    const out = [];
+    const ws = "pnpm-workspace.yaml";
+    if (!ctx.repo.exists(ws)) return out;
+    let docs;
+    try {
+      docs = parseYamlDocuments(ctx.repo.readText(ws), ws);
+    } catch {
+      return out;
+    }
+    const globs = (docs[0] && docs[0].doc && docs[0].doc.packages) || [];
+    ctx.repo.readText(ws);
+    for (const g of Array.isArray(globs) ? globs : []) {
+      if (typeof g !== "string" || g.includes("..")) continue;
+      const segs = g.split("/").filter((s) => s.length && s !== "**");
+      const starAt = segs.findIndex((s) => s === "*");
+      if (starAt < 0) continue;
+      const base = segs.slice(0, starAt).join("/");
+      if (!base || !ctx.repo.isDir(base)) continue;
+      // One level of expansion is enough to enumerate members; deeper layouts
+      // are picked up by the descriptor globs.
+      for (const entry of ctx.repo.listDir(base)) {
+        if (!entry.endsWith("/")) continue;
+        const dir = base + "/" + entry.replace(/\/$/, "");
+        if (!ctx.repo.isDir(dir)) continue;
+        if (ctx.repo.exists(dir + "/package.json")) out.push({ root: dir, importable: true, deployable: true });
+      }
+    }
+    return out;
+  }
+}

package/adapters/protobuf.mjs

@@ -0,0 +1,35 @@
+// Protobuf adapter: .proto files as canonical contracts, with the service and
+// method inventory an agent needs and deterministic consumer resolution.
+import { Adapter } from "./registry.mjs";
+import { resolveContractConsumers, isBuildConfig } from "./contract-consumers.mjs";
+
+export class ProtobufAdapter extends Adapter {
+  static adapterName = "protobuf";
+  constructor() {
+    super({ name: "protobuf", 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 === "protobuf")) {
+      const ref = api.doc.spec.contract.ref;
+      const text = ctx.repo.readText(ref);
+      const methods = [];
+      const packages = [];
+      for (const m of text.matchAll(/^\s*package\s+([A-Za-z0-9_.]+)\s*;/gm)) packages.push(m[1]);
+      for (const m of text.matchAll(/service\s+([A-Za-z0-9_]+)\s*\{([\s\S]*?)\n\}/g)) {
+        for (const r of m[2].matchAll(/rpc\s+([A-Za-z0-9_]+)\s*\(\s*(stream\s+)?([A-Za-z0-9_.]+)/g)) {
+          methods.push({ service: m[1], method: r[1], request: r[3], streaming: Boolean(r[2]) });
+        }
+      }
+      methods.sort((a, b) => ((a.service + a.method) < (b.service + b.method) ? -1 : 1));
+      ctx.addContract({ apiRef: api.ref, ref, services: [...new Set(text.match(/service\s+([A-Za-z0-9_]+)/g) || [])].length, methods, packages: [...new Set(packages)].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/registry.mjs

@@ -0,0 +1,27 @@
+// Adapter contract.
+//
+// An adapter knows one technology's vocabulary: how to recognise a unit root,
+// how to read its manifest, and which deterministic facts it can extract. It
+// must NOT know about the repository's folder layout, its domain names, its
+// event names or its providers. Everything project-specific arrives through
+// agentdoc.config.yaml.
+//
+// Two phases per unit:
+//   detect(repo, root)      -> does this root host a unit of my kind?
+//   extract(ctx, unit)      -> deterministic facts + provenance
+//
+// Adapters are pure: same checkout, same facts, same order.
+export class Adapter {
+  constructor({ name, version = "1.0.0", kind = "generic" }) {
+    this.name = name;
+    this.version = version;
+    this.kind = kind; // generic | unit-marker | manifest | source | contract | ci
+  }
+  // Unit-marker adapters answer: does `root` contain a unit I recognise?
+  // Returning a marker path is what makes the root eligible.
+  detect(ctx, root) { return null; }
+  // Manifest/source adapters contribute facts for an already-eligible unit.
+  extract(ctx, unit) {}
+  // Contract adapters validate and index contract files listed by config.
+  contracts(ctx) { return []; }
+}

package/adapters/resource-client.mjs

@@ -0,0 +1,61 @@
+// Client-of-resource resolution.
+//
+// A component that depends on a declared external service also *uses* the
+// resource that service fronts, when exactly one authored Resource of the
+// declared type exists. A message-bus client binds to the event bus; a cache
+// client to the cache.
+//
+// The mapping is declared in configuration rather than inferred, because
+// "this npm package talks to our bus" is a fact about the project, not about
+// the package. When more than one Resource of the type exists the fact is left
+// unresolved: an ambiguous match must never become an edge.
+
+const POOL_HINT = /(createPool|new Pool|pg\.Pool|pgxpool|sql\.Open|mysql\.createConnection|Pool\(|DataSource|prisma\.(datasource|client)|DATABASE_URL|DB_DSN|redis|minio|Client\()/;
+
+export function resolveClientResources(ctx, unit, compRef, provRec) {
+  const declared = ctx.externalMatchers().filter((x) => x.resourceType);
+  if (!declared.length) return [];
+  // The rule is "this unit depends on this service", so it is tested against
+  // the unit's production dependency names, not against its source text.
+  const deps = ctx.productionDependencies(compRef);
+  if (!deps.length) return [];
+  const out = [];
+  for (const x of declared) {
+    if (!deps.some((d) => x.re.test(d))) continue;
+    const cands = ctx.sources.entities.filter(
+      (e) => e.kind === "Resource" && e.doc.spec.type === x.resourceType
+    );
+    if (cands.length !== 1) {
+      if (cands.length > 1) {
+        ctx.diagnostics.push({
+          severity: "warning",
+          code: "AGENTDOC_BINDING_AMBIGUOUS",
+          subject: compRef,
+          refs: [compRef],
+          message:
+            "component '" + compRef + "' depends on " + x.name + " and there are " + cands.length +
+            " authored Resources of type " + x.resourceType + "; the binding is left unresolved",
+          paths: [],
+        });
+      }
+      continue;
+    }
+    const target = cands[0];
+    // The matcher name is *data* — which declared client produced the edge — not
+    // a derivation route. Encoding it in `via` would put it outside the relation's
+    // identity, so a component depending on two matchers of the same Resource type
+    // would merge into one edge and the graph would state the dependency once
+    // instead of twice. `via` names the mechanism; `client` names the instance.
+    ctx.addEdge("usesResource", compRef, target.ref, { via: "declared-client", client: x.name }, [provRec], "DERIVED");
+    ctx.addFact(compRef, "resource.ownership", target.name, {
+      evidenceClass: "DERIVED",
+      confidence: "deterministic",
+      provRecs: [provRec],
+      semantics: "the component depends on " + x.name + ", declared as a client of the " + x.resourceType + " Resource",
+    });
+    out.push(target.ref);
+  }
+  return out;
+}
+
+export { POOL_HINT };

package/adapters/turborepo.mjs

@@ -0,0 +1,135 @@
+// Turborepo adapter: records task-graph driven verification commands and the
+// pipeline they belong to. Turborepo knows how to run a task for one package
+// and how to filter by dependency graph, which makes it the most precise
+// verification answer available for a monorepo unit.
+import { Adapter } from "./registry.mjs";
+import { parseYamlDocuments } from "../core/yaml.mjs";
+
+// Whether a declared task is a check is decided by `taskTier` alone, not by a
+// second, narrower pattern. Two lists meant two places to disagree: a task that
+// `TIERS` recognised — `e2e`, `playwright`, `drift:detect`, `generate:types` —
+// was silently dropped because this filter had never heard of it, and the
+// "untiered task" diagnostic could not fire for it either, since it sits after
+// the filter. A verification entry that vanishes without a word is worse than
+// one that is visibly untiered.
+
+export class TurborepoAdapter extends Adapter {
+  static adapterName = "turborepo";
+  constructor() {
+    super({ name: "turborepo", version: "1.0.0", kind: "ci" });
+  }
+  detect(ctx, root) {
+    const p = root + "/turbo.json";
+    if (!ctx.repo.exists(p)) return null;
+    return { path: p, shape: "importable" };
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const p = nearestTurboConfig(repo, unit.root);
+    if (!p) return {};
+    let doc;
+    try {
+      doc = JSON.parse(repo.readText(p));
+    } catch {
+      return {};
+    }
+    // Every declared task is considered; `taskTier` decides which are checks.
+    // Filtering by a second pattern first is what silently dropped the tasks
+    // that pattern had never heard of.
+    const tasks = Object.keys(doc.tasks || doc.pipeline || {}).sort();
+    if (!tasks.length) return {};
+    const pr = prov.add("observed", p, "taskgraph-extractor", tasks.map((t) => "ver:tg:" + compRef + ":" + t));
+    const pkgName = unit.pkgName;
+    const scripts = Object.keys((unit.pkg || {}).scripts || {});
+    const emitted = [];
+    for (const t of tasks) {
+      // A task-graph command is only real if this unit actually declares the
+      // task. `turbo run test --filter=./apps/notifications` is not a command
+      // when that package has no `test` script, and emitting it would put an
+      // unrunnable command in front of an agent as if it were the answer.
+      if (!scripts.includes(t)) continue;
+      const tier = taskTier(t);
+      if (!tier) {
+        // A task with no tier is usually an ordinary package script (`dev`,
+        // `docs`, `release`) and not a missing verification entry, so it is
+        // dropped silently. A task that *looks* like a check but cannot be
+        // tiered is a gap worth reporting, and this is the only place that can
+        // tell the two apart.
+        // A check task with no tier would otherwise vanish with no trace, and a
+        // verification entry that is silently missing is worse than one that is
+        // visibly untiered: nothing is left to notice the gap.
+        ctx.diagnostics.push({
+          severity: "warning",
+          code: "AGENTDOC_VERIFICATION_UNTIERED",
+          subject: compRef,
+          refs: [compRef, p],
+          message:
+            "check task '" + t + "' has no recognisable tier and was not recorded as a verification entry. " +
+            "Name the task test/lint/typecheck/build/e2e/integration/contract, or extend the adapter.",
+        });
+        continue;
+      }
+      const filter = pkgName ? " --filter=" + pkgName : " --filter=./" + unit.root;
+      ctx.addVerification({
+        id: "tg:" + compRef + ":" + t,
+        componentRefs: [compRef],
+        tier,
+        command: "turbo run " + t + filter,
+        configPaths: [p],
+        provRecs: [pr],
+      });
+      emitted.push(t);
+    }
+    for (const t of tasks) if (!emitted.includes(t)) pr.subjects.delete("ver:tg:" + compRef + ":" + t);
+    return {};
+  }
+  contracts() {
+    return [];
+  }
+}
+
+// The tier is derived from the whole task name, never from a fragment of it. A
+// mis-tiered check is worse than an absent one: it is copied into a change set
+// as though it proved something it does not, and an agent will run the cheap
+// thing and believe the expensive thing was covered.
+// A watch task is an interactive session, not a check. Recording `test:watch`
+// as a runnable verification command hands an agent a process that never exits.
+const NOT_A_CHECK = /(^|[:_-])(watch|dev|serve|start|preview)([:_-]|$)/;
+
+const TIERS = [
+  // Order matters: the most specific reading of a name wins. `e2e-lite` is an
+  // integration suite that happens to contain "e2e", so it must be read before
+  // the e2e row rather than after it.
+  [/(^|[:_-])e2e-lite([:_-]|$)/, "integration"],
+  [/(^|[:_-])(e2e|playwright|cypress|acceptance)([:_-]|$)/, "e2e"],
+  [/(^|[:_-])(contract|openapi|drift|schema)([:_-]|$)/, "contract"],
+  [/(^|[:_-])(integration|itest|e2e-lite)([:_-]|$)/, "integration"],
+  [/(^|[:_-])(lint|typecheck|check-types|type-check|golangci|vet|fmt|format|audit)([:_-]|$)/, "static"],
+  [/(^|[:_-])(unit|jest|vitest|mocha)([:_-]|$)/, "unit"],
+  [/(^|[:_-])(build|compile|generate|bundle)([:_-]|$)/, "build"],
+  // A bare `test`/`tests`/`verify`/`check` is a unit test by convention. A
+  // repository that disagrees should name the tier, as above. This row is last
+  // on purpose: `check:prettier` and `verify:lint` are formatting and lint
+  // checks wearing a `check` prefix, and reading them as unit tests would put a
+  // trivial command in front of an agent as if it covered behaviour.
+  [/(^|[:_-])(test|tests|verify|check)([:_-]|$)/, "unit"],
+];
+function taskTier(t) {
+  if (NOT_A_CHECK.test(t)) return null;
+  for (const [re, tier] of TIERS) if (re.test(t)) return tier;
+  return null;
+}
+
+// A task graph normally lives at the workspace root, not in each package.
+function nearestTurboConfig(repo, root) {
+  let dir = root;
+  for (let i = 0; i < 12; i++) {
+    const p = dir ? dir + "/turbo.json" : "turbo.json";
+    if (repo.exists(p)) return p;
+    if (!dir) break;
+    dir = dir.split("/").slice(0, -1).join("/");
+  }
+  return null;
+}
+
+export { parseYamlDocuments };