agent-doc-system 0.0.0-stage → 1.0.0

package/INSTALL_FOR_AGENTS.md

@@ -0,0 +1,60 @@
+# Install AgentDoc — instructions for an AI coding agent
+
+This document has exactly one job: get the `agentdoc` CLI installed and verified
+on the current machine. It is **not** a project workflow. Do not look for a
+project root, do not run `init`, `audit`, `scaffold`, or `check`, do not create
+`.agentdoc/` or `agentdoc/`, and do not modify any software project. The task
+ends when the CLI is installed and verified.
+
+## 1. Inspect the environment
+
+```bash
+uname -a            # OS and architecture
+echo "$SHELL"       # current shell
+node --version      # is Node present, and which major
+npm --version       # is npm present
+command -v git      # is git present (needed to install from GitHub)
+```
+
+## 2. Ensure a supported Node
+
+AgentDoc requires **Node 22 or newer** (22, 24 and 26 are the tested
+baselines). If `node` is missing or older than 22, install or switch to a
+supported release using whatever the machine already has — `nvm`, `fnm`,
+`mise`, `brew`, or the package manager — then re-check `node --version`.
+
+If no Node toolchain exists and none can be installed without a human (for
+example a managed machine), stop and report that prerequisite.
+
+## 3. Install or upgrade the CLI
+
+Canonical install, from the AgentDoc GitHub repository:
+
+```bash
+npm install -g github:lbframe/agent-doc-system
+```
+
+The command is idempotent: run it again to upgrade to the latest `main`.
+If a specific ref is required, append it: `github:lbframe/agent-doc-system#<ref>`.
+
+The package has zero runtime dependencies. If `npm install -g` fails on
+permissions, do **not** use `sudo`; fix the npm global prefix instead
+(`npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to `PATH`),
+or report the blocker.
+
+## 4. Verify the binary resolves
+
+```bash
+command -v agentdoc     # must print a path
+agentdoc --version      # must print a version
+agentdoc doctor         # machine self-check; must exit 0
+```
+
+`agentdoc doctor` reports the Node version, the schema bundle and the compiler
+version, and fails if the installation itself is unhealthy. It never requires a
+project — run it from anywhere.
+
+## 5. Report and stop
+
+Report the installed version and that `doctor` passed. The installation task is
+complete. Do not proceed into any repository, catalog, or migration work.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lbframe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# agentdoc — portable documentation & software-catalog system
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zero runtime dependencies. One Node runtime. AgentDoc compiles a repository
+into one deterministic graph and routes a path or an entity to the minimum
+context needed to change it safely.
+
+It exists to answer one question cheaply and correctly, for an AI coding agent
+or a human reviewer:
+
+> I am about to change *this*. What do I need to know, what must I keep
+> consistent, and which command proves it?
+
+It does that while keeping three kinds of claim apart — what the repository
+*claims*, what can be *derived* from code, and what was *observed* running —
+and surfacing their disagreements as conflicts instead of guessing.
+
+## Install the CLI
+
+The CLI is installed once per machine. Requires Node 22 or newer (22, 24 and
+26 are the tested baselines).
+
+```bash
+npm install -g github:lbframe/agent-doc-system
+
+agentdoc --version
+agentdoc doctor        # machine self-check
+```
+
+Unpinned installs track `main`. For reproducible CI, pin a tag or commit:
+`github:lbframe/agent-doc-system#v1.0.0`.
+
+The install footprint is the CLI only — `bin/`, `core/`, `adapters/`,
+`schemas/`, `templates/`, `evals/`, docs and the agent skill. Nothing is ever
+copied into a project that uses AgentDoc.
+
+### Have an AI agent install it for you
+
+Paste this into a capable coding agent:
+
+```text
+Install AgentDoc on this machine from:
+https://github.com/lbframe/agent-doc-system
+
+Read INSTALL_FOR_AGENTS.md from that repository and follow it completely.
+
+Do not initialize, inspect, migrate, or modify any software project as part of
+this installation task.
+
+When finished, verify the AgentDoc CLI and report the installed version.
+```
+
+[`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md) contains the procedure.
+
+## Use it in a project
+
+From the repository root:
+
+```bash
+cd my-project
+agentdoc doctor --project   # is there a catalog here, and is it healthy
+agentdoc audit              # inventory the repo, classify every fact
+```
+
+Then follow the workflow the audit implies:
+
+| workflow | when | entry point |
+|---|---|---|
+| CREATE | no catalog exists | `agentdoc init`, then `agentdoc scaffold --write` |
+| MIGRATE | established repo, scattered or stale docs | `agentdoc audit`, work the report |
+| VALIDATE | before committing, in CI | `agentdoc validate` → `compile` → `check` |
+| QUERY | before and during a change | `agentdoc query <path-or-ref>` |
+| MAINTAIN | after a change | `agentdoc impact <paths>` |
+
+AgentDoc writes **project data only**: `agentdoc/` (configuration and
+descriptors you own), `docs/` skeleton files, `.agentdoc/graph.json` (the
+compiled artifact), and a CI workflow. The CLI source is never vendored into
+your repository.
+
+The two directories differ in ownership, not just punctuation:
+
+- `agentdoc/` is **authored** — configuration, descriptors and observation
+  sets. Everything in it is a claim you wrote and a reviewer can diff.
+- `.agentdoc/` is **generated** — the compiled graph and other build
+  artifacts. Never edit it by hand; `compile` rewrites it and `check` rejects
+  a stale or edited one.
+
+## Use it with an AI agent
+
+The agent skill is [`skills/agent-doc-system/`](skills/agent-doc-system/SKILL.md).
+Install that directory as a skill in your agent harness. It teaches the agent
+when to use the CLI, the evidence-class model, the working loop, and the
+integrity rules — with deeper material under `skills/agent-doc-system/references/`.
+
+## What it is built on
+
+Most repositories conflate three different kinds of claim, and the confusion
+is the single largest source of wrong agent behaviour:
+
+| what | who says it | how it fails |
+|---|---|---|
+| what the repository **claims** | authored docs, config, manifests | drifts, is aspirational, is not tested |
+| what can be **derived** from code | imports, manifests, contracts | heuristic, incomplete, wrong about intent |
+| what was **observed** in a running system | schedulers, bindings, live APIs | goes stale, disagrees with intent |
+
+A claim carries an evidence class, a confidence, and a pointer to its evidence.
+When two classes disagree about the same fact, the disagreement is **surfaced
+as a conflict**, not reconciled. There is no global precedence order, because
+authority depends on the fact: the committed manifest is authoritative for
+*intent*, the live scheduler is authoritative for *what fires*, and the
+canonical contract is authoritative for the *desired wire surface* while a
+live probe is authoritative for *what is deployed today*.
+
+The default is fail-closed. A fact with no governing authority rule and
+disagreeing evidence is an error, and no gate passes while it stands.
+
+## Documentation
+
+| file | covers |
+|---|---|
+| [`skills/agent-doc-system/SKILL.md`](skills/agent-doc-system/SKILL.md) | how an agent uses the system |
+| [INSTALL_FOR_AGENTS.md](INSTALL_FOR_AGENTS.md) | machine installation, for an AI agent |
+| [docs/SPEC.md](docs/SPEC.md) | the normative specification: entities, graph, determinism |
+| [docs/AUTHORITY.md](docs/AUTHORITY.md) | evidence classes, conflict semantics, elections |
+| [docs/PROVENANCE.md](docs/PROVENANCE.md) | evidence records, pointers, secret handling |
+| [docs/QUERY.md](docs/QUERY.md) | the context router, budgets, freshness refusal |
+| [docs/MIGRATION.md](docs/MIGRATION.md) | CREATE and MIGRATE workflows |
+| [docs/CI.md](docs/CI.md) | the drift gate and its failure modes |
+| [docs/ADAPTERS.md](docs/ADAPTERS.md) | writing an adapter, and what must never live in one |
+| [docs/EVALS.md](docs/EVALS.md) | the routing benchmark and pre-registered thresholds |
+| [docs/COMPARISON-KODA.md](docs/COMPARISON-KODA.md) | measured comparison against the reference corpus |
+
+## Fixtures and the golden corpus
+
+- `fixtures/a-node-ts-postgres` — single Node/TypeScript service, REST, Postgres, GitHub Actions.
+- `fixtures/b-go-multi-service` — multi-service Go repository, protobuf contracts, shared library, resources.
+- `fixtures/c-alt-monorepo` — deliberately *not* `apps/`+`packages/`+`workers/`, mixed runtimes, inconsistent pre-existing docs.
+- `examples/koda` — the profile that represents a large, mature, TypeScript+Go monorepo, including the runtime-observation conflicts that motivated the authority model.
+
+## Development
+
+```bash
+node --test tests/*.test.mjs   # unit, adversarial and mode tests
+node evals/run-all.mjs         # aggregate routing evaluation (gate)
+npm run selfcheck              # agentdoc doctor, from the source checkout
+```
+
+## Licence of the design
+
+The architecture, the fail-closed discipline, the provenance model and the
+warning-acceptance mechanism are extracted from a production catalog system
+that proved them at scale. The namespace, schemas, adapters, CLI and authority
+model here are new and neutral.

package/adapters/cache.mjs

@@ -0,0 +1,27 @@
+// Cache adapter: Redis / in-memory cache client evidence as a derived binding.
+import { Adapter } from "./registry.mjs";
+
+const CACHE_HINT = /(@upstash\/redis|ioredis|redis|go-redis|redis\.go|valkey|memcache|@memcached)/i;
+
+export class CacheAdapter extends Adapter {
+  static adapterName = "cache";
+  constructor() {
+    super({ name: "cache", version: "1.0.0", kind: "source" });
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const evFile = unit.goModule ? unit.root + "/go.mod" : unit.root + "/package.json";
+    if (!repo.exists(evFile)) return {};
+    const text = repo.readText(evFile);
+    if (!CACHE_HINT.test(text)) return {};
+    const pr = prov.add("observed", evFile, "binding-extractor", ["der:" + compRef + ":/bindings"]);
+    const resources = ctx.sources.entities.filter((e) => e.kind === "Resource" && e.doc.spec.type === "cache");
+    if (resources.length === 1) {
+      const client = ctx.clientKeyForResourceType("cache");
+      const attrs = client ? { via: "cache-client", client } : { via: "cache-client" };
+      ctx.addEdge("usesResource", compRef, resources[0].ref, attrs, [pr], "DERIVED");
+      return { bindings: [{ kind: "cache", logicalResourceRef: resources[0].ref, resolution: "resolved", provenanceIds: null, _provs: new Set([pr]) }] };
+    }
+    return { bindings: [{ kind: "cache", resolution: "resolved", provenanceIds: null, _provs: new Set([pr]) }] };
+  }
+}

package/adapters/contract-consumers.mjs

@@ -0,0 +1,56 @@
+// Shared contract-consumer resolution.
+//
+// A cross-component boundary is a contract plus its consumers. Consumers are
+// discovered deterministically: a unit that references the canonical contract
+// file from a source or build-configuration file, other than the provider's own
+// unit, consumes that contract. Documentation mentions are excluded so a doc
+// that quotes a contract path cannot manufacture a dependency edge.
+import path from "node:path";
+
+const CODE_EXT = /\.(ts|tsx|js|jsx|mts|cts|mjs|cjs|go|py|rb|java|kt|rs|ex|exs|cs|php|swift|gradle|proto|graphql|sql)$/;
+const CONFIG_NAMES = new Set([
+  "package.json", "go.mod", "buf.gen.yaml", "buf.yaml", "buf.work.yaml",
+  "codegen.yaml", "codegen.yml", "openapi-ts.config.ts", "openapi-ts.config.js",
+  "oapi-codegen.yaml", "oapi-codegen.yml", "turbo.json", "Makefile", "justfile",
+  "Taskfile.yml", "build.gradle", "build.gradle.kts", "pom.xml",
+]);
+const DOC_EXT = /\.(md|mdx|txt|adoc|rst)$/;
+
+export function contractReferenceSites(repo, unit) {
+  const out = new Map(); // file -> true
+  for (const f of repo.walk(unit.root)) {
+    const base = path.posix.basename(f);
+    if (DOC_EXT.test(f)) continue;
+    if (f.includes("/docs/") || f.startsWith("docs/")) continue;
+    if (!CODE_EXT.test(f) && !CONFIG_NAMES.has(base)) continue;
+    out.set(f, true);
+  }
+  return out;
+}
+
+// Resolve consumers for a contract file. Returns Map<componentRef, string[]>.
+// The per-unit file inventory is built once and cached on the context, so a
+// repository with many contracts does not re-walk every unit per contract.
+export function resolveContractConsumers(ctx, contractRef, providerRef) {
+  if (!ctx.referenceIndex) {
+    const perUnit = new Map();
+    for (const unit of ctx.discovery.eligible) {
+      if (!unit.component) continue;
+      perUnit.set(unit.component.ref, [...contractReferenceSites(ctx.repo, unit).keys()].sort());
+    }
+    ctx.referenceIndex = perUnit;
+  }
+  const out = new Map();
+  for (const [ref, files] of ctx.referenceIndex) {
+    if (ref === providerRef) continue;
+    const hits = files.filter((f) => ctx.repo.readText(f).includes(contractRef));
+    if (hits.length) out.set(ref, hits);
+  }
+  return out;
+}
+
+// A unit that names the contract in its own build config is a stronger signal
+// than a stray mention in source.
+export function isBuildConfig(file) {
+  return CONFIG_NAMES.has(path.posix.basename(file));
+}

package/adapters/database.mjs

@@ -0,0 +1,116 @@
+// Database adapter: migration and schema evidence.
+//
+// Two distinct outcomes, deliberately kept apart:
+//   - an authored logical-database Resource that matches → a resolved binding
+//     and a uses-resource relation;
+//   - no match → a *candidate* fact plus a warning. Migration authority alone
+//     does not establish database ownership, so the system refuses to invent
+//     the edge. This mirrors a real review in the reference project where a
+//     library shipped migrations but explicitly did not own a database.
+import { Adapter } from "./registry.mjs";
+import { firstExistingFile, findMigrationDirs } from "../core/sourcescan.mjs";
+
+const ORM_CONFIG = [
+  "drizzle.config.ts", "drizzle.config.js", "drizzle.config.mjs",
+  "prisma/schema.prisma", "schema.prisma",
+  "knexfile.js", "knexfile.ts", "sequelize.config.js", "ormconfig.json",
+];
+
+export class DatabaseAdapter extends Adapter {
+  static adapterName = "database";
+  constructor() {
+    super({ name: "database", version: "1.0.0", kind: "source" });
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const root = unit.root;
+    const migrationDirs = findMigrationDirs(repo, root);
+    const ormConfig = firstExistingFile(repo, root, ORM_CONFIG);
+    if (!migrationDirs.length && !ormConfig) return {};
+
+    let evidencePath = ormConfig;
+    if (migrationDirs.length) {
+      evidencePath = repo.walk(migrationDirs[0])[0] || migrationDirs[0];
+    }
+    const pr = prov.add("observed", evidencePath, "migration-extractor", ["der:" + compRef + ":/bindings"]);
+
+    // A component that both migrates and opens a connection owns the database.
+    const opensConnection = hasConnectionEvidence(ctx, unit);
+    if (!opensConnection) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "AGENTDOC_RESOURCE_CANDIDATE",
+        subject: compRef,
+        refs: [compRef],
+        message:
+          "migration or schema authority under '" + root + "' has no matching authored logical-database Resource, " +
+          "and no connection-pool evidence: migration authority alone does not establish database ownership",
+        paths: [evidencePath],
+      });
+      ctx.addFact(compRef, "resource.ownership", null, {
+        evidenceClass: "DERIVED", confidence: "candidate", provRecs: [pr],
+        semantics: "a schema exists here, but which component owns the logical database is unresolved",
+      });
+      return { migrationAuthority: evidencePath };
+    }
+
+    const name = compRef.split("/")[1];
+    const target = ctx.sources.byKindName.get("Resource/" + name + "-postgres")
+      || ctx.sources.byKindName.get("Resource/" + name + "-database")
+      || ctx.sources.byKindName.get("Resource/" + name + "-db")
+      || findDatabaseResource(ctx, name);
+    if (!target) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "AGENTDOC_RESOURCE_CANDIDATE",
+        subject: compRef,
+        refs: [compRef],
+        message:
+          "component '" + name + "' has migration and connection authority but no authored logical-database Resource; " +
+          "declare one or record why the database is owned elsewhere",
+        paths: [evidencePath],
+      });
+      ctx.addFact(compRef, "resource.ownership", null, {
+        evidenceClass: "DERIVED", confidence: "candidate", provRecs: [pr],
+        semantics: "this component opens a database connection, but no authored Resource claims ownership",
+      });
+      return { migrationAuthority: evidencePath };
+    }
+    ctx.addFact(compRef, "resource.ownership", target.name, {
+      evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+      semantics: "migration and connection authority in this root resolve to the authored logical database",
+    });
+    // Migrations and a connection string are the same dependency a declared
+    // client matcher would find, so the edge carries the same instance key and
+    // the two routes merge into one fact.
+    const client = ctx.clientKeyForResourceType("logical-database");
+    const attrs = client ? { via: "migrations+connection", client } : { via: "migrations+connection" };
+    ctx.addEdge("usesResource", compRef, target.ref, attrs, [pr], "DERIVED");
+    return {
+      migrationAuthority: evidencePath,
+      bindings: [{ kind: "database", logicalResourceRef: target.ref, resolution: "resolved", provenanceIds: null, _provs: new Set([pr]) }],
+    };
+  }
+}
+
+const POOL_HINT = /(createPool|new Pool|pg\.Pool|psycopg2?\.connect|sql\.Open|mysql\.createConnection|Pool\(|DataSource|prisma\.(datasource|client)|DATABASE_URL|DB_DSN)/;
+
+function hasConnectionEvidence(ctx, unit) {
+  for (const f of ctx.repo.walk(unit.root)) {
+    if (/\.(ts|tsx|js|mjs|go|py|rb|java|kt|rs|ex|cs|php)$/.test(f)) {
+      if (/(^|\/)(tests?|__tests__)\//.test(f)) continue;
+      if (POOL_HINT.test(ctx.repo.readText(f))) return true;
+    }
+  }
+  return false;
+}
+
+// A Resource whose name starts with the component name and whose type is a
+// database. A deterministic naming convention, not a guess: an ambiguous match
+// is left unresolved.
+function findDatabaseResource(ctx, name) {
+  const cands = ctx.sources.entities.filter(
+    (e) => e.kind === "Resource" && e.doc.spec.type === "logical-database" && e.name.startsWith(name)
+  );
+  return cands.length === 1 ? cands[0] : null;
+}

package/adapters/deploy-config.mjs

@@ -0,0 +1,34 @@
+// Deployment-config adapter: platform manifests that make a root deployable.
+// Only the file's existence is treated as evidence; no value from these files
+// is ever reported as deployed state.
+import { Adapter } from "./registry.mjs";
+
+const DEPLOY_FILES = [
+  "fly.toml", "app.yaml", "render.yaml", "railway.json", "vercel.json",
+  "netlify.toml", "heroku.yml", "Procfile", "service.yaml", "k8s/deployment.yaml",
+  "chart/Chart.yaml", "serverless.yml", "serverless.yaml", "ansible.cfg",
+];
+
+export class DeployConfigAdapter extends Adapter {
+  static adapterName = "deploy-config";
+  constructor() {
+    super({ name: "deploy-config", version: "1.0.0", kind: "unit-marker" });
+  }
+  detect(ctx, root) {
+    for (const n of DEPLOY_FILES) {
+      if (ctx.repo.exists(root + "/" + n)) return { path: root + "/" + n, shape: "deployable" };
+    }
+    return null;
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const out = { deployConfigs: [] };
+    for (const n of DEPLOY_FILES) {
+      const p = unit.root + "/" + n;
+      if (!repo.exists(p)) continue;
+      prov.add("observed", p, "deploy-extractor", ["der:" + compRef + ":/artifact"]);
+      out.deployConfigs.push(p);
+    }
+    return out;
+  }
+}

package/adapters/dockerfile.mjs

@@ -0,0 +1,26 @@
+// Dockerfile adapter: a Dockerfile is deployable-artifact evidence.
+import { Adapter } from "./registry.mjs";
+
+export class DockerfileAdapter extends Adapter {
+  static adapterName = "dockerfile";
+  constructor() {
+    super({ name: "dockerfile", version: "1.0.0", kind: "unit-marker" });
+  }
+  detect(ctx, root) {
+    for (const n of ["Dockerfile", "Dockerfile.prod", "Containerfile"]) {
+      if (ctx.repo.exists(root + "/" + n)) return { path: root + "/" + n, shape: "deployable" };
+    }
+    return null;
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const out = { dockerfiles: [] };
+    for (const n of ["Dockerfile", "Dockerfile.prod", "Containerfile"]) {
+      const p = unit.root + "/" + n;
+      if (!repo.exists(p)) continue;
+      prov.add("observed", p, "deploy-extractor", ["der:" + compRef + ":/artifact"]);
+      out.dockerfiles.push(p);
+    }
+    return out;
+  }
+}

package/adapters/events.mjs

@@ -0,0 +1,145 @@
+// Event subject adapter.
+//
+// Discovers event subjects and their producers and consumers from source,
+// filtered by the project's declared event subject prefixes. Two things matter
+// here:
+//
+//   1. No hard-coded project vocabulary. Koda's `koda.` prefix became a
+//      configuration value; without prefixes the extractor falls back to a
+//      conservative three-or-more-segment shape, which is what subject-based
+//      brokers actually use.
+//   2. Producer and consumer roles are evidence, not assumption. A file that
+//      merely mentions a subject is neither.
+import { Adapter } from "./registry.mjs";
+import { sourceFiles as sourceFilesOf } from "../core/sourcescan.mjs";
+
+const SRC_EXT = /\.(ts|tsx|js|jsx|mts|cts|mjs|cjs|go|py|rb|java|kt|rs|ex|exs|cs|php)$/;
+const TEST_PATH = /(^|\/)(tests?|__tests__|spec)\//;
+const TEST_FILE = /\.(test|spec)\./;
+
+// A subject-shaped token: three or more dot-separated lowercase segments, with
+// optional trailing wildcards. Two-segment values are usually scopes, not
+// subjects, and are excluded for exactly that reason.
+// A subject is three or more dot-separated segments: `orders.created.v1`. A
+// declared family is two or more segments plus a wildcard: `orders.created.*`.
+// Both are real and both are indexed. A bare `orders.*` is NOT accepted: a
+// wildcard at the top level is a catch-all, not a subject, and letting it in
+// would fold every subject in the system into one meaningless family.
+const SUBJECT_TOKEN = /["'`]([a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)+(?:[.*>])?|[a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)+\.(?:\*|>))["'`]/g;
+// A named subject constant: its name is what a producer file actually mentions,
+// while the pattern lives in another unit. Resolving the name is what lets a
+// component that publishes "LESSON_PUBLISHED" be credited with producing the
+// subject the shared package defines.
+const SUBJECT_CONST = /\b([A-Z][A-Z0-9_]*_SUBJECT)\b\s*[=:]\s*["'`]([a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+){2,}(?:[.*>])?)["'`]/g;
+// Any identifier bound to a subject literal, in any naming style. A producer
+// file usually references the constant by name; the literal itself lives in the
+// shared unit that defines the vocabulary.
+const SUBJECT_DECL = /\b([A-Za-z_$][\w$]*)\b\s*(?::\s*string\s*)?=\s*["'`]([a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+){2,}(?:[.*>])?)["'`]/g;
+const CONST_REF = /\b([A-Za-z_$][\w$]*)\b/g;
+
+const PUBLISH_HINT = /\b(publish|emit|enqueue|produce|outbox|Publish\(|Emit\()/;
+const CONSUME_HINT = /\b(subscribe|consume|onMessage|handler|WithFilterSubject|FilterSubjects|busloop|subscriber|ProcessBatch|dlq|DLQ|ack|Nak\()/;
+
+export class EventsAdapter extends Adapter {
+  static adapterName = "events";
+  constructor() {
+    super({ name: "events", version: "1.0.0", kind: "source" });
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const prefixes = (ctx.cfg.discovery.eventPatternPrefixes || []).filter(Boolean);
+    const contract = ctx.primaryEventContract();
+    if (!contract) return {};
+    // Constants declared anywhere in the repository, and which of those
+    // declarations this unit can actually see (itself plus what it depends on).
+    const consts = new Map();
+    const collectDecls = (root) => {
+      for (const f of sourceFilesOf(ctx.repo, root)) {
+        const text = ctx.repo.readText(f);
+        for (const m of text.matchAll(SUBJECT_DECL)) consts.set(m[1], m[2]);
+        for (const m of text.matchAll(SUBJECT_CONST)) consts.set(m[1], m[2]);
+      }
+    };
+    collectDecls(unit.root);
+    // A unit can only be credited with a subject it can see: its own sources,
+    // plus those of the units it declares a dependency on, transitively. The
+    // dependency map is built from manifests before extraction, so this does
+    // not depend on adapter execution order.
+    const visible = ctx.transitiveDependencies(compRef);
+    for (const other of ctx.discovery.eligible) {
+      if (other.component && visible.has(other.component.ref) && other.component.ref !== compRef) collectDecls(other.root);
+    }
+    const families = 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);
+      const publish = PUBLISH_HINT.test(text);
+      const consume = CONSUME_HINT.test(text);
+      if (!publish && !consume) continue;
+      const found = new Set();
+      for (const m of text.matchAll(SUBJECT_TOKEN)) {
+        const s = m[1];
+        if (prefixes.length && !prefixes.some((p) => s.startsWith(p))) continue;
+        found.add(s);
+      }
+      for (const m of text.matchAll(CONST_REF)) {
+        const pattern = consts.get(m[1]);
+        if (pattern && pattern !== m[0] && (!prefixes.length || prefixes.some((p) => pattern.startsWith(p)))) found.add(pattern);
+      }
+      for (const s of found) {
+        if (s.endsWith(".*") || s.endsWith(".>")) families.add(s);
+      }
+      for (const s of found) {
+        const pr = prov.add("observed", f, "event-extractor", ["evt:" + s]);
+        if (publish) ctx.addEvent(s, "producer", compRef, pr, contract);
+        if (consume) ctx.addEvent(s, "consumer", compRef, pr, contract);
+      }
+    }
+    // The family set is only needed to fold literals; the fold itself happens in
+    // the index builder, where the contract and the resolution state are known.
+    void families;
+    return {};
+  }
+  // A declared event catalog is a strong, human-maintained statement of which
+  // component subscribes to which subjects. The catalog file is the contract.
+  contracts(ctx) {
+    const out = [];
+    for (const ec of ctx.cfg.discovery.eventContracts || []) {
+      // A contract may be a file, a directory, or a module prefix.
+      const files = ctx.repo.filesWithPrefix(ec.path);
+      if (!files.length) {
+        ctx.errors.push({
+          code: "AGENTDOC_PATH_UNRESOLVED",
+          message: "declared event contract path does not resolve: " + ec.path,
+          path: ec.path,
+        });
+        continue;
+      }
+      const patterns = ec.format === "code" ? harvestFromCode(ctx, ec, files) : Object.keys(safeJson(ctx, ec));
+      // Provenance must name a real file; the contract may be a directory or a
+      // module prefix.
+      const evidenceFile = files.find((f) => SRC_EXT.test(f) && !/\.(test|spec)\./.test(f)) || files[0];
+      const pr = ctx.prov.add("declared", evidenceFile, "event-catalog-extractor", patterns.map((p) => "evt:" + p));
+      for (const p of patterns.sort()) ctx.addEvent(p, "consumer", ec.consumer, pr, { format: ec.format === "code" ? "code" : "declared-catalog", ref: ec.path });
+    }
+    return out;
+  }
+}
+
+function safeJson(ctx, ec) {
+  try {
+    return ctx.repo.readJson(ec.path);
+  } catch {
+    return {};
+  }
+}
+
+function harvestFromCode(ctx, ec, files) {
+  const out = new Set();
+  for (const f of files) {
+    if (!SRC_EXT.test(f)) continue;
+    for (const m of ctx.repo.readText(f).matchAll(SUBJECT_TOKEN)) out.add(m[1]);
+  }
+  return [...out];
+}