agent-doc-system 0.0.0-stage → 1.0.0

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 };

package/adapters/typescript.mjs

@@ -0,0 +1,85 @@
+// TypeScript adapter.
+//
+// Owns tsconfig.json as an importability marker, project references as a build
+// relation source, and the framework route conventions that are genuinely
+// TypeScript-ecosystem facts rather than project conventions.
+import path from "node:path";
+import { Adapter } from "./registry.mjs";
+import { parseYamlDocuments } from "../core/yaml.mjs";
+
+export class TypeScriptAdapter extends Adapter {
+  static adapterName = "typescript";
+  constructor() {
+    super({ name: "typescript", version: "1.0.0", kind: "unit-marker" });
+  }
+  detect(ctx, root) {
+    const p = root + "/tsconfig.json";
+    if (!ctx.repo.exists(p)) return null;
+    return { path: p, shape: "importable" };
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const p = unit.root + "/tsconfig.json";
+    if (!repo.exists(p)) return {};
+    const derived = { languages: new Set(["typescript"]), runtimes: new Set(["node"]) };
+    let ts;
+    try {
+      ts = parseTsconfig(repo, p);
+    } catch {
+      ts = {};
+    }
+    const pr = prov.add("observed", p, "tsconfig-extractor", ["der:" + compRef + ":/languages", "rel:pending"]);
+
+    // Project references: an explicit build-time dependency between units.
+    for (const refPath of (ts.references || [])) {
+      const targetDir = path.posix.normalize(path.posix.join(unit.root, refPath));
+      const target = ctx.unitForRoot(targetDir);
+      if (!target || !target.component) continue;
+      ctx.addEdge("buildDependsOn", compRef, target.component.ref, { via: "tsconfig-references" }, [pr], "DERIVED");
+    }
+    derived.tsconfig = { composite: Boolean(ts.compilerOptions?.composite), references: (ts.references || []).length };
+
+    // Route conventions of the file-based router ecosystem: a route file is a
+    // real HTTP surface and must be visible to the query surface.
+    const routes = [];
+    for (const base of ["src/app", "app", "src/pages", "pages"]) {
+      if (!repo.isDir(unit.root + "/" + base)) continue;
+      for (const f of repo.walk(unit.root + "/" + base)) {
+        const routePath = routeFor(unit.root, base, f);
+        if (!routePath) continue;
+        const rpr = prov.add("observed", f, "route-extractor", ["der:" + compRef + ":/routes"]);
+        routes.push({ path: f, route: routePath, provenanceIds: null, _provs: new Set([rpr]) });
+      }
+    }
+    if (routes.length) {
+      routes.sort((a, b) => (a.route < b.route ? -1 : 1));
+      derived.routes = routes;
+      // Published on the unit so other adapters can resolve a scheduled
+      // trigger to the component that actually serves the route.
+      unit.routes = routes;
+    }
+    return derived;
+  }
+}
+
+function routeFor(root, base, file) {
+  const rel = file.slice((root + "/" + base).length + 1);
+  if (base.endsWith("app")) {
+    if (!rel.endsWith("/route.ts") && !rel.endsWith("/route.tsx") && !rel.endsWith("/route.js")) return null;
+    const segs = rel.split("/").slice(0, -1);
+    if (!segs.length) return "/";
+    return "/" + segs.map((s) => (s.startsWith("(") && s.endsWith(")") ? "" : s.replace(/^\[\.\.\.(.+)\]$/, ":$1*").replace(/^\[(.+)\]$/, ":$1"))).join("/");
+  }
+  if (!rel.startsWith("api/") || !rel.endsWith(".ts")) return null;
+  return "/" + rel.slice(4).replace(/\.ts$/, "");
+}
+
+// tsconfig allows comments and trailing commas; strip them before JSON.parse.
+function parseTsconfig(repo, p) {
+  let text = repo.readText(p);
+  text = text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'\\])\/\/.*$/gm, "$1");
+  text = text.replace(/,(\s*[}\]])/g, "$1");
+  return JSON.parse(text);
+}
+
+export { parseYamlDocuments };

package/adapters/wrangler.mjs

@@ -0,0 +1,206 @@
+// Wrangler adapter (Cloudflare Workers / Pages).
+//
+// This adapter is where the most expensive lesson of the reference project
+// lives. A committed deployment manifest is a *declared* schedule and a
+// *declared* binding set. It is DERIVED evidence about what the repository
+// intends, and nothing more. If a live scheduler disagrees — an hourly trigger
+// with hour-3 gating where the manifest says "daily" — the disagreement has to
+// reach the graph as a conflict, which only happens if the manifest claim is
+// emitted as a fact on the same key the observation uses. So: no manifest value
+// is ever reported as deployed truth.
+import { Adapter } from "./registry.mjs";
+import { parse as parseToml } from "../core/toml.mjs";
+import { sourceFiles } from "../core/sourcescan.mjs";
+
+const MANIFESTS = ["wrangler.toml", "wrangler.json", "wrangler.jsonc"];
+
+export class WranglerAdapter extends Adapter {
+  static adapterName = "wrangler";
+  constructor() {
+    super({ name: "wrangler", version: "1.0.0", kind: "unit-marker" });
+  }
+  detect(ctx, root) {
+    for (const n of MANIFESTS) {
+      if (ctx.repo.exists(root + "/" + n)) return { path: root + "/" + n, shape: "deployable" };
+    }
+    return null;
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const file = MANIFESTS.map((n) => unit.root + "/" + n).find((p) => repo.exists(p));
+    if (!file) return {};
+    let toml;
+    try {
+      toml = file.endsWith(".toml") ? parseToml(repo.readText(file), file) : stripJsonc(repo.readText(file));
+    } catch {
+      return {};
+    }
+    const derived = { runtimes: new Set(["cloudflare-workers"]) };
+    if (toml.name) unit.platformName = String(toml.name);
+    const pr = prov.add("observed", file, "platform-manifest-extractor", ["der:" + compRef + ":/runtimes", "der:" + compRef + ":/bindings"]);
+
+    const bindings = [];
+    // The manifest makes ONE claim about the binding set, so the graph records
+    // one fact. Emitting a fact per binding would make a manifest that declares
+    // two bindings look like a contradiction against a runtime that reports one.
+    const bindingKinds = new Set();
+    const bindingNames = new Set();
+    const pushBinding = (kind, locator) => {
+      bindingKinds.add(kind);
+      if (locator && locator.binding) bindingNames.add(locator.binding);
+      bindings.push({ kind, locator, resolution: "resolved", provenanceIds: null, _provs: new Set([pr]) });
+    };
+    for (const kv of toml.kv_namespaces || []) pushBinding("kv", { binding: String(kv.binding || "") });
+    for (const d1 of toml.d1_databases || []) pushBinding("d1", { binding: String(d1.binding || "") });
+    for (const r2 of toml.r2_buckets || []) pushBinding("r2", { binding: String(r2.binding || "") });
+    for (const dofs of toml.durable_objects?.bindings || []) pushBinding("durable-object", { binding: String(dofs.name || "") });
+    for (const em of toml.send_email || []) pushBinding("email-routing", { binding: String(em.name || em.binding || "") });
+    for (const q of toml.queues?.producers || []) pushBinding("queue-producer", { binding: String(q.binding || "") });
+    for (const q of toml.queues?.consumers || []) pushBinding("queue-consumer", { binding: String(q.queue || q.binding || "") });
+    if (bindings.length) derived.bindings = bindings;
+
+    // Service bindings: a platform-level runtime call. Resolved in a second
+    // pass once every unit's platform name is known.
+    const pending = [];
+    for (const svc of toml.services || []) {
+      pushBinding("service-binding", { binding: String(svc.binding || ""), service: String(svc.service || "") });
+      pending.push({ binding: String(svc.binding || ""), service: String(svc.service || "") });
+    }
+    if (pending.length) {
+      derived.serviceBindings = pending;
+      ctx.deferSecondPass((pass) => {
+        for (const sb of pending) {
+          const target = pass.byPlatformName.get(sb.service);
+          if (target && target.component) {
+            const epr = prov.add("observed", file, "service-binding-extractor", ["rel:pending"]);
+            ctx.addEdge("runtimeCalls", compRef, target.component.ref,
+              { transport: "service-binding", contractRef: file }, [epr], "DERIVED");
+          } else {
+            ctx.diagnostics.push({
+              severity: "warning",
+              code: "AGENTDOC_SERVICE_BINDING_UNRESOLVED",
+              subject: compRef,
+              refs: [compRef],
+              message: "service binding '" + sb.service + "' declared in " + file + " does not match any discovered component",
+              paths: [file],
+            });
+          }
+        }
+      });
+    }
+
+    if (bindingNames.size) {
+      ctx.addFact(compRef, "binding.declared", [...bindingNames].sort(), {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "the binding names the committed manifest declares for this component",
+      });
+    }
+    if (bindingKinds.size) {
+      ctx.addFact(compRef, "binding.kind", [...bindingKinds].sort(), {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "the kinds of platform binding the committed manifest declares for this component",
+      });
+    }
+
+    // Scheduled triggers. Emitted as a DERIVED fact on schedule.cron, which is
+    // the same key a scheduler observation uses, so the two can be compared.
+    const crons = ((toml.triggers && toml.triggers.crons) || []).map(String).sort();
+    if (crons.length) {
+      derived.schedules = crons;
+      ctx.addFact(compRef, "schedule.cron", crons.join(","), {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "cron expressions the committed deployment manifest declares for this component",
+      });
+      ctx.addFact(compRef, "schedule.enabled", true, {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "the manifest declares a trigger, i.e. the job is intended to be enabled",
+      });
+    }
+
+    // Job handlers: a cron URL variable names the endpoint a trigger calls.
+    // Again one claim, not one per variable.
+    const vars = toml.vars || {};
+    const declaredTargets = [];
+    for (const [varName, url] of Object.entries(vars)) {
+      if (typeof url !== "string") continue;
+      const m = /^https?:\/\/[^/]+(\/[^\s]*)$/.exec(url);
+      if (!m) continue;
+      declaredTargets.push({ var: varName, route: m[1] });
+    }
+    if (declaredTargets.length) {
+      derived.scheduleTargets = declaredTargets.slice().sort((a, b) => (a.route < b.route ? -1 : 1));
+      ctx.addFact(compRef, "schedule.target", [...new Set(declaredTargets.map((t) => t.route))].sort(), {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "endpoints the committed manifest points scheduled triggers at",
+      });
+      // A schedule that points at a route this repository implements is a
+      // `schedules` relation. Without it, "who does this trigger call?" has no
+      // answer and an agent debugging a missed job has nothing to follow.
+      for (const t of declaredTargets) {
+        ctx.deferSecondPass(() => {
+          const owner = findRouteOwner(ctx, t.route, compRef);
+          if (owner) {
+            const rpr = prov.add("observed", file, "schedule-extractor", ["rel:pending"]);
+            const tpr = prov.add("observed", owner.file, "schedule-extractor", ["rel:pending"]);
+            ctx.addEdge("schedules", compRef, owner.ref, { via: "declared-trigger-target", route: t.route }, [rpr, tpr], "DERIVED");
+          } else {
+            ctx.diagnostics.push({
+              severity: "warning",
+              code: "AGENTDOC_SCHEDULE_UNRESOLVED",
+              subject: compRef,
+              refs: [compRef],
+              message: "scheduled trigger target '" + t.route + "' declared in " + file + " does not resolve to a route in any discovered component",
+              paths: [file],
+            });
+          }
+        });
+      }
+    }
+    return derived;
+  }
+}
+
+// Resolve an absolute route path to the component that *serves* it.
+//
+// A route literal appears in more places than the component that owns it: every
+// generated OpenAPI client embeds the path it calls. So candidates are ranked
+// rather than counted, and only an unambiguous winner is used:
+//
+//   2  a file-based route whose path is this route
+//   1  a route literal in hand-written source
+//   0  a route literal in generated client code
+//
+// A tie at the top score is a genuine ambiguity and yields no relation.
+function findRouteOwner(ctx, route, selfRef) {
+  const generated = (ctx.cfg.discovery.generatedClientPatterns || ["/gen/", ".gen.", "/generated/", "/generated/"]).map(
+    (p) => new RegExp(escapeRe(p))
+  );
+  const isGenerated = (f) => generated.some((re) => re.test(f));
+  const candidates = [];
+  for (const unit of ctx.discovery.eligible) {
+    if (!unit.component || unit.component.ref === selfRef) continue;
+    const viaPath = (unit.routes || []).find((r) => r.route === route);
+    if (viaPath) { candidates.push({ ref: unit.component.ref, file: viaPath.path, score: 2 }); continue; }
+    for (const f of sourceFiles(ctx.repo, unit.root, { test: false })) {
+      const text = ctx.repo.readText(f);
+      if (!text.includes(route)) continue;
+      if (!new RegExp("[\"'\`]" + escapeRe(route) + "[\"'\`]").test(text)) continue;
+      candidates.push({ ref: unit.component.ref, file: f, score: isGenerated(f) ? 0 : 1 });
+      break;
+    }
+  }
+  if (!candidates.length) return null;
+  const best = Math.max(...candidates.map((c) => c.score));
+  const winners = candidates.filter((c) => c.score === best);
+  const distinct = new Set(winners.map((c) => c.ref));
+  if (distinct.size !== 1) return null;
+  return winners[0];
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function stripJsonc(text) {
+  return JSON.parse(text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'\\])\/\/.*$/gm, "$1").replace(/,(\s*[}\]])/g, "$1"));
+}