@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/lineage-versions.ts

@@ -0,0 +1,348 @@
+/**
+ * `chant workspace versions [<dir>] [--template <id>] [--json]` (#2551, D9,
+ * requirement T9).
+ *
+ * Reports, for a family of workspaces, which template version and which chant
+ * and lexicon versions each one is on. A family is the set of workspaces made
+ * from the same template: each lineage scope belongs to the family of its
+ * template id. The command finds every `.chant/workspace.lock.json` under
+ * `<dir>` (the working directory by default), so pointing it at a directory of
+ * checkouts compares them all. Without `--available` nothing is fetched and no
+ * code runs: it reads lock files and `package.json` files only.
+ *
+ * With `--available`, each family whose template is a git source also lists
+ * the template's version tags (`git ls-remote --tags`, catalogued in
+ * `test/egress-catalogue.ts`), and each member says how many are newer than
+ * the version its lock sits at. That is the list `chant workspace upgrade
+ * --to <tag>` chooses from.
+ *
+ * Per D9 the word "drift" keeps its existing meanings, so a workspace on an
+ * older version than the newest one in its family is reported as `behind`.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { TemplateTags } from "./lineage-hash-index";
+import { LockError, LOCK_FILE, readLock, type LineageSource } from "./lineage-lock";
+import { lineageProvenance } from "./lineage-provenance";
+import { compareVersions, formatVersion, parseVersion } from "./lineage-version";
+
+/** How deep under `<dir>` a lock is looked for. */
+export const MAX_DEPTH = 8;
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", ".chant"]);
+
+export interface ScopeVersion {
+  scope: string;
+  kind: "template" | "vendor";
+  template: string;
+  ref: string | null;
+  /** The version the ref names, or null when it names none (a branch, a commit). */
+  version: string | null;
+  commit: string | null;
+  migrations: number;
+  /** `files` or `lineage` when adopt-lineage recorded the lineage (#2551), otherwise null. */
+  adoption: "files" | "lineage" | null;
+  /** D5's level: `adopted` once the policy at base admits the adopted range, `unattested` otherwise. */
+  provenance: "adopted" | "unattested";
+  /** Where the template is fetched from: the source type, and for git the URL as the lock records it. */
+  source: { type: LineageSource["type"]; url?: string };
+}
+
+export interface PluginVersion {
+  name: string;
+  /** The range `package.json` declares. */
+  declared: string;
+  /** The version installed where the workspace resolves it, or null when it is not installed. */
+  installed: string | null;
+}
+
+export interface WorkspaceVersions {
+  /** Relative to `<dir>`, `.` for `<dir>` itself. */
+  path: string;
+  scopes: ScopeVersion[];
+  plugins: PluginVersion[];
+  /** Set when the lock could not be read; the workspace then has no scopes. */
+  error?: string;
+}
+
+export interface FamilyMember {
+  path: string;
+  scope: string;
+  ref: string | null;
+  version: string | null;
+  /** Older than the newest version in the family. */
+  behind: boolean;
+  /** With `--available`: how many of the template's version tags are newer than this member's version, or null when unknown. */
+  newer?: number | null;
+}
+
+export interface AvailableVersions {
+  /** The template's version tags, oldest first, narrowed by `--tags`. */
+  tags: string[];
+  /** The newest of them, or null when there are none. */
+  newest: string | null;
+  /** Why the tags could not be listed (not a git template, or the fetch failed). */
+  error?: string;
+}
+
+export interface Family {
+  template: string;
+  /** The newest version any member is on, or null when no member's ref is a version. */
+  newest: string | null;
+  members: FamilyMember[];
+  /** With `--available`: the template's own version tags. */
+  available?: AvailableVersions;
+}
+
+export interface VersionsReport {
+  root: string;
+  workspaces: WorkspaceVersions[];
+  families: Family[];
+  /** chant and lexicon packages that members of one family have at different installed versions. */
+  pluginSpread: Array<{ template: string; name: string; versions: Record<string, string[]> }>;
+}
+
+/** Every directory under `dir` that holds a lineage lock, nearest first. */
+export function findLocks(dir: string, depth = MAX_DEPTH): string[] {
+  const found: string[] = [];
+  const walk = (at: string, level: number): void => {
+    if (existsSync(join(at, LOCK_FILE))) found.push(at);
+    if (level >= depth) return;
+    let names: string[];
+    try {
+      names = readdirSync(at);
+    } catch {
+      return;
+    }
+    for (const name of names.sort()) {
+      if (SKIP_DIRS.has(name) || (name.startsWith(".") && name !== ".")) continue;
+      const child = join(at, name);
+      try {
+        if (!statSync(child).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      walk(child, level + 1);
+    }
+  };
+  walk(dir, 0);
+  return found;
+}
+
+function isPlugin(name: string): boolean {
+  return name === "@intentius/chant" || name.startsWith("@intentius/chant-lexicon-");
+}
+
+/** The version of `pkg` that node would resolve from `dir`: the nearest `node_modules/<pkg>` going up. */
+function installedVersion(pkg: string, dir: string): string | null {
+  let at = dir;
+  for (;;) {
+    const manifest = join(at, "node_modules", pkg, "package.json");
+    if (existsSync(manifest)) {
+      try {
+        return (JSON.parse(readFileSync(manifest, "utf-8")) as { version?: string }).version ?? null;
+      } catch {
+        return null;
+      }
+    }
+    const up = dirname(at);
+    if (up === at) return null;
+    at = up;
+  }
+}
+
+/** chant and its lexicons, as the workspace's `package.json` declares them. */
+export function pluginVersions(dir: string): PluginVersion[] {
+  const manifest = join(dir, "package.json");
+  if (!existsSync(manifest)) return [];
+  let json: { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+  try {
+    json = JSON.parse(readFileSync(manifest, "utf-8"));
+  } catch {
+    return [];
+  }
+  const declared = { ...(json.devDependencies ?? {}), ...(json.dependencies ?? {}) };
+  return Object.keys(declared)
+    .filter(isPlugin)
+    .sort()
+    .map((name) => ({ name, declared: declared[name], installed: installedVersion(name, dir) }));
+}
+
+export interface VersionsOptions {
+  /** Only this template's family. */
+  template?: string;
+  /** List each git template's version tags. */
+  available?: boolean;
+  /** Narrow those tags with a glob, such as `kit-v*`. */
+  tags?: string;
+  /** Lists a template's version tags; replaced in tests. */
+  listTags?: (url: string, member: string | undefined, pattern?: string) => string[];
+}
+
+/** The default lister: `git ls-remote --tags` through ./lineage-hash-index.ts. */
+function remoteTags(url: string, member: string | undefined, pattern?: string): string[] {
+  const tags = new TemplateTags(url, member, url);
+  try {
+    return tags.listTags(pattern).map((t) => t.tag);
+  } finally {
+    tags.dispose();
+  }
+}
+
+/** Build the report for every workspace under `dir`, narrowed to one template's family when `template` is given. */
+export function workspaceVersions(dir: string, templateOrOptions?: string | VersionsOptions): VersionsReport {
+  const options: VersionsOptions = typeof templateOrOptions === "string" ? { template: templateOrOptions } : (templateOrOptions ?? {});
+  const template = options.template;
+  const root = resolve(dir);
+  const workspaces: WorkspaceVersions[] = [];
+  for (const at of findLocks(root)) {
+    const path = relative(root, at).split(sep).join("/") || ".";
+    let scopes: ScopeVersion[] = [];
+    let error: string | undefined;
+    try {
+      const lock = readLock(at)!;
+      scopes = Object.entries(lock.scopes).map(([scope, l]) => {
+        const v = parseVersion(l.ref);
+        return {
+          scope,
+          kind: l.kind,
+          template: l.template,
+          ref: l.ref ?? null,
+          version: v ? formatVersion(v) : null,
+          commit: l.address?.commit ?? null,
+          migrations: l.migrations.length,
+          adoption: l.adoption?.by ?? null,
+          provenance: lineageProvenance(at, l)?.level ?? "unattested",
+          source: l.source.type === "git" ? { type: "git", url: l.source.url.startsWith(".") ? resolve(at, l.source.url) : l.source.url } : { type: l.source.type },
+        };
+      });
+    } catch (err) {
+      if (!(err instanceof LockError)) throw err;
+      error = err.message;
+    }
+    if (template !== undefined && !error && !scopes.some((s) => s.template === template)) continue;
+    workspaces.push({ path, scopes, plugins: pluginVersions(at), ...(error ? { error } : {}) });
+  }
+
+  const byTemplate = new Map<string, FamilyMember[]>();
+  for (const w of workspaces) {
+    for (const s of w.scopes) {
+      if (template !== undefined && s.template !== template) continue;
+      const list = byTemplate.get(s.template) ?? [];
+      list.push({ path: w.path, scope: s.scope, ref: s.ref, version: s.version, behind: false });
+      byTemplate.set(s.template, list);
+    }
+  }
+  const families: Family[] = [];
+  const pluginSpread: VersionsReport["pluginSpread"] = [];
+  for (const [id, members] of [...byTemplate.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const versions = members.map((m) => (m.version ? parseVersion(m.version)! : null)).filter((v) => v !== null);
+    const newest = versions.length > 0 ? versions.reduce((a, b) => (compareVersions(a, b) >= 0 ? a : b)) : null;
+    for (const m of members) {
+      m.behind = newest !== null && m.version !== null && compareVersions(parseVersion(m.version)!, newest) < 0;
+    }
+    const family: Family = { template: id, newest: newest ? formatVersion(newest) : null, members };
+    if (options.available) family.available = available(id, workspaces, members, options);
+    families.push(family);
+
+    const paths = new Set(members.map((m) => m.path));
+    const seen = new Map<string, Record<string, string[]>>();
+    for (const w of workspaces.filter((w) => paths.has(w.path))) {
+      for (const p of w.plugins) {
+        const v = p.installed ?? `not installed (${p.declared})`;
+        const entry = seen.get(p.name) ?? {};
+        (entry[v] ??= []).push(w.path);
+        seen.set(p.name, entry);
+      }
+    }
+    for (const [name, spread] of [...seen.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      if (Object.keys(spread).length > 1) pluginSpread.push({ template: id, name, versions: spread });
+    }
+  }
+  return { root, workspaces, families, pluginSpread };
+}
+
+/** The version tags of a family's template, and how far behind them each member is. */
+function available(id: string, workspaces: WorkspaceVersions[], members: FamilyMember[], options: VersionsOptions): AvailableVersions {
+  const scope = workspaces.flatMap((w) => w.scopes).find((s) => s.template === id);
+  if (!scope || scope.source.type !== "git" || !scope.source.url) {
+    for (const m of members) m.newer = null;
+    return { tags: [], newest: null, error: `a ${scope?.source.type ?? "unknown"} source has no version tags to list` };
+  }
+  const member = id.includes("#") ? id.slice(id.lastIndexOf("#") + 1) : undefined;
+  let tags: string[];
+  try {
+    tags = (options.listTags ?? remoteTags)(scope.source.url, member, options.tags);
+  } catch (err) {
+    for (const m of members) m.newer = null;
+    return { tags: [], newest: null, error: err instanceof Error ? err.message : String(err) };
+  }
+  const versions = tags.map((t) => parseVersion(t)).filter((v) => v !== null);
+  for (const m of members) {
+    const v = m.version ? parseVersion(m.version) : null;
+    m.newer = v ? versions.filter((t) => compareVersions(t, v) > 0).length : null;
+  }
+  return { tags, newest: tags.length > 0 ? tags[tags.length - 1] : null };
+}
+
+/** The report as terminal lines. */
+export function describeVersions(report: VersionsReport): string[] {
+  const lines: string[] = [];
+  for (const w of report.workspaces) {
+    lines.push(w.path);
+    if (w.error) lines.push(`  unreadable: ${w.error}`);
+    for (const s of w.scopes) {
+      const at = s.commit ? ` (${s.commit.slice(0, 12)})` : "";
+      const adopted = s.adoption === "files" && s.provenance !== "adopted" ? ", adopted range not yet at base" : s.adoption === "lineage" ? ", moved from a directory lineage" : "";
+      lines.push(`  ${s.scope}  ${s.template}@${s.ref ?? "(no ref)"}${at}  ${s.provenance}${adopted}${s.migrations > 0 ? `, ${s.migrations} migration(s)` : ""}`);
+    }
+    if (w.plugins.length > 0) {
+      lines.push(`  plugins: ${w.plugins.map((p) => `${p.name} ${p.installed ?? `not installed (${p.declared})`}`).join(", ")}`);
+    }
+  }
+  for (const f of report.families) {
+    const behind = f.members.filter((m) => m.behind);
+    lines.push(
+      `family ${f.template}: ${f.members.length} scope(s), newest ${f.newest ?? "(no versions)"}${behind.length > 0 ? `; behind: ${behind.map((m) => `${m.path}${m.scope === "." ? "" : `/${m.scope}`} (${m.ref})`).join(", ")}` : ""}`,
+    );
+    if (f.available) {
+      if (f.available.error) lines.push(`  available: unknown (${f.available.error})`);
+      else {
+        lines.push(`  available: ${f.available.tags.length} version tag(s), newest ${f.available.newest ?? "(none)"}`);
+        for (const m of f.members) {
+          if (m.newer === undefined || m.newer === null) continue;
+          lines.push(`  ${m.path}${m.scope === "." ? "" : `/${m.scope}`} at ${m.ref}: ${m.newer === 0 ? "on the newest" : `${m.newer} newer`}`);
+        }
+      }
+    }
+    for (const s of report.pluginSpread.filter((p) => p.template === f.template)) {
+      lines.push(`  ${s.name} differs: ${Object.entries(s.versions).map(([v, paths]) => `${v} in ${paths.join(", ")}`).join("; ")}`);
+    }
+  }
+  if (report.workspaces.length === 0) lines.push(`no ${LOCK_FILE} under ${report.root}`);
+  return lines;
+}
+
+export async function runWorkspaceVersions(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (args.extraPositional2) {
+    console.error(formatError({ message: `unexpected argument: ${args.extraPositional2}`, hint: "chant workspace versions [<dir>] [--template <id>] [--available [--tags <glob>]] [--json]" }));
+    return 1;
+  }
+  const dir = resolve(args.extraPositional ?? ".");
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+    console.error(formatError({ message: `${dir} is not a directory` }));
+    return 1;
+  }
+  const report = workspaceVersions(dir, {
+    template: args.template,
+    available: args.available,
+    tags: args.tags,
+  });
+  if (args.json) console.log(JSON.stringify(report, null, 2));
+  else console.log(describeVersions(report).join("\n"));
+  return 0;
+}

package/src/workspace/links.test.ts

@@ -321,8 +321,8 @@ describe("the declaration's link fields", () => {
     expect(d.members[0].outputs).toEqual(["One", "Two"]);
     expect(d.members[1].outputs).toBeNull();
     expect(d.members[1].links).toEqual([
-      { member: "a", output: "One", kind: null, pointer: "/members/1/links/0" },
-      { member: "a", output: "Two", kind: "output", pointer: "/members/1/links/1" },
+      { member: "a", output: "One", kind: null, protocol: null, pointer: "/members/1/links/0" },
+      { member: "a", output: "Two", kind: "output", protocol: null, pointer: "/members/1/links/1" },
     ]);
   });
 
@@ -335,6 +335,125 @@ describe("the declaration's link fields", () => {
   });
 });
 
+describe("telemetry links (#2558)", () => {
+  const collector = {
+    member: "ops",
+    pipelines: [
+      { id: "traces", signal: "traces", receivers: ["otlp"], processors: [], exporters: ["otlphttp/backend"] },
+      { id: "metrics", signal: "metrics", receivers: ["custom"], processors: [], exporters: ["otlphttp/backend"] },
+    ],
+    components: [
+      { id: "otlp", kind: "receiver", type: "otlp", endpoints: ["0.0.0.0:4318"], protocols: ["http/protobuf", "http/json"], pipelines: ["traces"] },
+      { id: "custom", kind: "receiver", type: "custom", endpoints: [], protocols: [], pipelines: ["metrics"] },
+      { id: "otlphttp/backend", kind: "exporter", type: "otlphttp", endpoints: ["https://b"], protocols: ["http/protobuf"], pipelines: ["traces", "metrics"] },
+    ],
+    exporters: [{ id: "otlphttp/backend", type: "otlphttp", endpoints: ["https://b"], pipelines: ["traces", "metrics"], signals: ["traces", "metrics"] }],
+  };
+  const decl = (link: Record<string, unknown>) =>
+    parseDeclaration(
+      declaration([
+        { name: "ops", dir: "ops", kind: "chant" },
+        { name: "web", dir: "web", kind: "chant" },
+        { name: "docs", dir: "docs", kind: "other", because: "prose" },
+        { name: "app", dir: "app", kind: "other", because: "x", links: [{ kind: "telemetry", ...link }] },
+      ]),
+      "chant.workspace.json",
+    );
+  const targets = (collectors: (typeof collector)[], composed = ["ops", "web"]) => ({
+    collectors: new Map(collectors.map((c) => [c.member, c])),
+    composed: new Set(composed),
+  });
+  const rowFor = (link: Record<string, unknown>, t?: ReturnType<typeof targets>) => resolveLinks(decl(link), new Map(), t)[0] as Extract<LinkTableRow, { producer: string }>;
+
+  test("resolves to a pipeline of the producer's collector, and says it is a pipeline", () => {
+    const row = rowFor({ member: "ops", output: "traces" }, targets([collector]));
+    expect(row).toMatchObject({ kind: "telemetry", status: "resolved", reason: null, target: "pipeline", output: "traces", producer: "ops" });
+  });
+
+  test("resolves to an exporter when no pipeline has the name", () => {
+    expect(rowFor({ member: "ops", output: "otlphttp/backend" }, targets([collector]))).toMatchObject({ status: "resolved", target: "exporter" });
+  });
+
+  test("is missing when the collector has no such pipeline or exporter, and lists what it has", () => {
+    const row = rowFor({ member: "ops", output: "logs" }, targets([collector]));
+    expect(row.status).toBe("missing");
+    expect(row.reason).toBe("ops's collector has no pipeline or exporter logs; pipelines: traces, metrics; exporters: otlphttp/backend");
+    expect(row.target).toBeUndefined();
+  });
+
+  test("is missing when a composed producer declares no collector, and unresolved when it was not composed", () => {
+    expect(rowFor({ member: "web", output: "traces" }, targets([collector]))).toMatchObject({ status: "missing", reason: expect.stringContaining("web declares no collector") });
+    expect(rowFor({ member: "docs", output: "traces" }, targets([collector]))).toMatchObject({ status: "unresolved", reason: expect.stringContaining("docs was not composed") });
+  });
+
+  test("checks the protocol against a pipeline's receivers", () => {
+    expect(rowFor({ member: "ops", output: "traces", protocol: "http/protobuf" }, targets([collector]))).toMatchObject({ status: "resolved", protocol: "http/protobuf" });
+    const bad = rowFor({ member: "ops", output: "traces", protocol: "grpc" }, targets([collector]));
+    expect(bad).toMatchObject({ status: "invalid", target: "pipeline" });
+    expect(bad.reason).toBe("the receivers of pipeline traces speak http/protobuf, http/json, and the link sends grpc");
+  });
+
+  test("checks the protocol against an exporter's own", () => {
+    expect(rowFor({ member: "ops", output: "otlphttp/backend", protocol: "http/protobuf" }, targets([collector])).status).toBe("resolved");
+    expect(rowFor({ member: "ops", output: "otlphttp/backend", protocol: "grpc" }, targets([collector])).status).toBe("invalid");
+  });
+
+  test("leaves the link unresolved when the target's definitions state no protocols", () => {
+    const row = rowFor({ member: "ops", output: "metrics", protocol: "grpc" }, targets([collector]));
+    expect(row).toMatchObject({ status: "unresolved", reason: "the receivers of pipeline metrics state no protocols, so grpc could not be confirmed" });
+  });
+
+  test("a link with no protocol checks presence only", () => {
+    expect(rowFor({ member: "ops", output: "metrics" }, targets([collector])).status).toBe("resolved");
+  });
+
+  test("without collectors, as in chant workspace check, a telemetry link is kept unresolved", () => {
+    const row = rowFor({ member: "ops", output: "traces" });
+    expect(row).toMatchObject({ status: "unresolved", reason: expect.stringContaining("read by chant workspace graph") });
+  });
+
+  test("a protocol on a link that isn't a telemetry link is invalid", () => {
+    const d = parseDeclaration(
+      declaration([{ name: "ops", dir: "ops", kind: "chant" }, { name: "app", dir: "app", kind: "other", because: "x", links: [{ member: "ops", output: "Url", protocol: "grpc" }] }]),
+      "chant.workspace.json",
+    );
+    const row = resolveLinks(d, new Map())[0] as Extract<LinkTableRow, { producer: string }>;
+    expect(row).toMatchObject({ status: "invalid", reason: "protocol applies to telemetry links; this link has kind output" });
+  });
+
+  test("graphLinks resolves a telemetry link from the composed collectors, and drops the pointer", () => {
+    const rows = graphLinks(decl({ member: "ops", output: "traces", protocol: "http/protobuf" }), { composed: ["ops", "web"], collectors: [collector], exports: [], imports: [] });
+    expect(rows).toEqual([
+      expect.objectContaining({ consumer: "app", producer: "ops", output: "traces", kind: "telemetry", status: "resolved", protocol: "http/protobuf", target: "pipeline" }),
+    ]);
+    expect("pointer" in rows[0]!).toBe(false);
+  });
+
+  test("the declaration refuses an unknown protocol, and reads a telemetry link's protocol", () => {
+    expect(() => decl({ member: "ops", output: "traces", protocol: "carrier-pigeon" })).toThrow(WorkspaceReadError);
+    expect(decl({ member: "ops", output: "traces", protocol: "grpc" }).members[3]!.links[0]).toMatchObject({ kind: "telemetry", protocol: "grpc" });
+  });
+
+  test("WSP098 flags a protocol on a link of another kind, and WSP092 accepts telemetry", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([
+        { name: "ops", dir: "ops", kind: "chant" },
+        { name: "app", dir: "app", kind: "other", because: "x", links: [{ member: "ops", output: "Url", protocol: "grpc" }, { member: "ops", output: "traces", kind: "telemetry", protocol: "grpc" }] },
+      ]),
+      "ops/chant.config.ts": "export default {};\n",
+      "app/README.md": "",
+    });
+    const report = await runDeclarationChecks(root);
+    const ids = report.diagnostics.map((d) => d.ruleId);
+    expect(ids).toContain("WSP098");
+    expect(ids).not.toContain("WSP092");
+    expect(report.diagnostics.find((d) => d.ruleId === "WSP098")!.message).toContain("states protocol grpc");
+    expect(report.diagnostics.filter((d) => d.ruleId === "WSP098")).toHaveLength(1);
+    // The telemetry link is kept unresolved here: check reads source.
+    expect(report.diagnostics.find((d) => d.ruleId === "WSP094")!.message).toContain("read by chant workspace graph");
+  });
+});
+
 describe("the chant repository's own declaration (#2557)", () => {
   test("has no link finding", async () => {
     const report = await runDeclarationChecks(resolve(import.meta.dirname, "../../../.."));

package/src/workspace/links.ts

@@ -16,7 +16,7 @@
  * is promoted.
  *
  * Every row says how it was found (`declared` or `inferred:joinKey`), where it
- * resolved (`source`; `check --live` comes later) and its status. A link that
+ * resolved (`source`, or `live` for the rows of `check --live`, #2549) and its status. A link that
  * can't be resolved is kept, with the reason.
  *
  * {@link resolveLinks} takes the members' handles as plain data, so the same
@@ -29,11 +29,23 @@
 import { joinKey, joinLabel, type JoinLabel } from "../join-key";
 import type { Declaration, LinkDeclaration, Member } from "./declaration";
 import type { KindRegistry, MemberKind } from "./kinds";
+import type { MemberCollector } from "./compose-graph";
 
-/** The link kinds chant knows. Closed: a link of any other kind fails closed. */
-export const LINK_KINDS = ["output"] as const;
+/**
+ * The link kinds chant knows. Closed: a link of any other kind fails closed.
+ * `output` reads a named output of the producer. `telemetry` (#2558, D22)
+ * sends the consumer's telemetry to a pipeline or exporter of the producer's
+ * collector.
+ */
+export const LINK_KINDS = ["output", "telemetry"] as const;
 export const DEFAULT_LINK_KIND = "output";
 
+/** The kind a link has when it names a collector target (#2558). */
+export const TELEMETRY_LINK_KIND = "telemetry";
+
+/** The OTLP protocols a telemetry link may state, as `OTEL_EXPORTER_OTLP_PROTOCOL` names them. */
+export const TELEMETRY_PROTOCOLS = ["grpc", "http/protobuf", "http/json"] as const;
+
 /** How a row was found: written down, or inferred by the named rule. */
 export type LinkOrigin = "declared" | "inferred:joinKey";
 
@@ -65,7 +77,7 @@ interface RowBase {
   consumer: string;
   kind: string;
   origin: LinkOrigin;
-  resolves: "source";
+  resolves: "source" | "live";
   /** Why the row is not `resolved`, or null. */
   reason: string | null;
 }
@@ -84,6 +96,21 @@ export interface LinkRow extends RowBase {
   to?: string;
   /** The declared link's JSON Pointer in the declaration. */
   pointer?: string;
+  /** A telemetry link: the OTLP protocol it states (#2558). */
+  protocol?: string;
+  /** A telemetry link that found its target: what `output` named, a `pipeline` or an `exporter` of the producer's collector. */
+  target?: "pipeline" | "exporter";
+}
+
+/**
+ * What a telemetry link reads from the producers (#2558): each composed
+ * member's collector, as `chant workspace graph` lists it, and which members
+ * were composed. `chant workspace check` reads source and runs no member, so
+ * it passes none and a telemetry link stays unresolved there.
+ */
+export interface TelemetryTargets {
+  collectors: ReadonlyMap<string, MemberCollector>;
+  composed: ReadonlySet<string>;
 }
 
 /** A parameter that joins outputs of two or more producers (or two outputs of one). */
@@ -145,7 +172,7 @@ function nearNames(name: string, outputs: JoinHandle[]): string[] {
  * missing from it is unresolved. Declared rows come first, in declaration
  * order; inferred and ambiguous rows follow, sorted by consumer and parameter.
  */
-export function resolveLinks(declaration: Declaration, handles: ReadonlyMap<string, MemberHandles>): LinkTableRow[] {
+export function resolveLinks(declaration: Declaration, handles: ReadonlyMap<string, MemberHandles>, telemetry?: TelemetryTargets): LinkTableRow[] {
   const rows: LinkTableRow[] = [];
   const declaredTargets = new Map<string, Set<string>>();
 
@@ -164,6 +191,7 @@ export function resolveLinks(declaration: Declaration, handles: ReadonlyMap<stri
         status: "resolved",
         reason: null,
         pointer: link.pointer,
+        ...(link.protocol ? { protocol: link.protocol } : {}),
       };
       rows.push(row);
       const targetProblem = linkTargetProblem(declaration, consumer, link);
@@ -178,6 +206,15 @@ export function resolveLinks(declaration: Declaration, handles: ReadonlyMap<stri
         row.reason = `the link kind ${kind} is not one chant knows; known link kinds: ${LINK_KINDS.join(", ")}`;
         continue;
       }
+      if (kind === TELEMETRY_LINK_KIND) {
+        resolveTelemetryLink(row, telemetry);
+        continue;
+      }
+      if (link.protocol) {
+        row.status = "invalid";
+        row.reason = `protocol applies to telemetry links; this link has kind ${kind}`;
+        continue;
+      }
       const producer = handles.get(link.member);
       const found = producer?.outputs.find((o) => o.name === link.output);
       if (found) {
@@ -260,6 +297,54 @@ export function resolveLinks(declaration: Declaration, handles: ReadonlyMap<stri
   return [...rows, ...inferred];
 }
 
+/**
+ * Resolve a telemetry link against the producer's collector (#2558): the
+ * target exists (presence), and when the link states a protocol, the target
+ * speaks it. A pipeline speaks what its receivers speak; an exporter speaks
+ * what its definition says. A target whose protocols the collector's
+ * definitions don't state leaves the link unresolved rather than failed.
+ */
+function resolveTelemetryLink(row: LinkRow, telemetry: TelemetryTargets | undefined): void {
+  if (!telemetry) {
+    row.status = "unresolved";
+    row.reason = `the collector of ${row.producer} is read by chant workspace graph; chant workspace check reads source and runs no member`;
+    return;
+  }
+  const collector = telemetry.collectors.get(row.producer);
+  if (!collector) {
+    if (!telemetry.composed.has(row.producer)) {
+      row.status = "unresolved";
+      row.reason = `the collector of ${row.producer} was not read: ${row.producer} was not composed`;
+    } else {
+      row.status = "missing";
+      row.reason = `${row.producer} declares no collector: its build reports no collector pipelines or components`;
+    }
+    return;
+  }
+  const pipeline = collector.pipelines.find((p) => p.id === row.output);
+  const exporter = pipeline ? undefined : collector.exporters.find((e) => e.id === row.output);
+  if (!pipeline && !exporter) {
+    row.status = "missing";
+    row.reason =
+      `${row.producer}'s collector has no pipeline or exporter ${row.output}` +
+      `; pipelines: ${collector.pipelines.map((p) => p.id).join(", ") || "none"}` +
+      `; exporters: ${collector.exporters.map((e) => e.id).join(", ") || "none"}`;
+    return;
+  }
+  row.target = pipeline ? "pipeline" : "exporter";
+  if (!row.protocol) return;
+  const ids = pipeline ? pipeline.receivers : [exporter!.id];
+  const speaks = [...new Set(collector.components.filter((c) => ids.includes(c.id)).flatMap((c) => c.protocols))];
+  const what = pipeline ? `the receivers of pipeline ${row.output}` : `exporter ${row.output}`;
+  if (speaks.length === 0) {
+    row.status = "unresolved";
+    row.reason = `${what} state no protocols, so ${row.protocol} could not be confirmed`;
+  } else if (!speaks.includes(row.protocol)) {
+    row.status = "invalid";
+    row.reason = `${what} speak ${speaks.join(", ")}, and the link sends ${row.protocol}`;
+  }
+}
+
 // ── Where the handles come from ──────────────────────────────────────────────
 
 /**
@@ -282,6 +367,8 @@ export function kindHandles(m: Member, kind: MemberKind): MemberHandles | undefi
 export interface ComposedHandles {
   /** Members whose IR was composed. */
   composed: readonly string[];
+  /** The collectors those members report (#2558); a telemetry link resolves against them. */
+  collectors?: readonly MemberCollector[];
   exports: readonly { member: string; name: string; node?: string }[];
   imports: readonly { member: string; name: string; node: string }[];
 }
@@ -322,7 +409,11 @@ export function graphLinks(declaration: Declaration, graph: ComposedHandles, kin
     const listed = kindHandles(m, kind);
     if (listed) handles.set(m.name, listed);
   }
-  return resolveLinks(declaration, handles).map((row) => {
+  const telemetry: TelemetryTargets = {
+    collectors: new Map((graph.collectors ?? []).map((c) => [c.member, c])),
+    composed: new Set(graph.composed),
+  };
+  return resolveLinks(declaration, handles, telemetry).map((row) => {
     if (row.status === "ambiguous" || row.origin !== "declared") return row;
     // The declaration's pointer means nothing to a graph reader.
     const { pointer: _pointer, ...rest } = row;