@intentius/chant-lexicon-otel 0.81.0

package/dist/topology.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Where telemetry goes, as plain data.
+ *
+ * `collectorTopology()` reads a collector config (declared, or parsed from a
+ * YAML file) and returns its pipelines, its components with their endpoints
+ * and schema pins, and for each exporter the pipelines and signals it
+ * carries. It is the surface a reader such as `chant workspace graph` uses to
+ * say where a member's telemetry is sent, and what a declared telemetry
+ * endpoint link can point at.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+import { type SchemaPin } from "./define.js";
+import { type CollectorConfig, type ComponentKind } from "./model.js";
+export interface TopologyPipeline {
+    /** The id under `service.pipelines`, e.g. `traces` or `traces/backend`. */
+    id: string;
+    /** `traces`, `metrics` or `logs`. */
+    signal: string;
+    receivers: string[];
+    processors: string[];
+    exporters: string[];
+}
+export interface TopologyComponent {
+    /** The collector id, `type` or `type/name`. */
+    id: string;
+    kind: ComponentKind;
+    type: string;
+    name?: string;
+    /** True for a component this package ships; false for a custom one, or one this process has no definition for. */
+    builtin: boolean;
+    /** The schema pin of its definition, when this process has the definition. */
+    schema?: SchemaPin;
+    /** Addresses it listens on or sends to, as the config states them. Empty when the config names none. */
+    endpoints: string[];
+    /** The pipelines that use it. For an extension, empty. */
+    pipelines: string[];
+}
+export interface TopologyExporter {
+    id: string;
+    type: string;
+    endpoints: string[];
+    pipelines: string[];
+    /** The signals that reach it, deduplicated, in pipeline order. */
+    signals: string[];
+}
+export interface CollectorTopology {
+    pipelines: TopologyPipeline[];
+    components: TopologyComponent[];
+    /** The exporters again, grouped for the question "where does this telemetry go". */
+    exporters: TopologyExporter[];
+}
+/** The topology of a collector config. */
+export declare function collectorTopology(config: CollectorConfig): CollectorTopology;
+/** The topology of declared entities, i.e. of the config the serializer would emit for them. */
+export declare function collectorTopologyOf(entities: Iterable<Declarable> | Map<string, Declarable>): CollectorTopology;
+//# sourceMappingURL=topology.d.ts.map

package/dist/topology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../src/topology.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAgD,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAEjH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kHAAkH;IAClH,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,wGAAwG;IACxG,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oFAAoF;IACpF,SAAS,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAeD,0CAA0C;AAC1C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CA4C5E;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,iBAAiB,CAE/G"}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+// The otel lexicon's entity classes and config types are hand-written in
+// src/ and compiled to dist/index.d.ts; this entry re-exports them.
+export * from "../index.js";

package/dist/validate-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+export {};
+//# sourceMappingURL=validate-cli.d.ts.map

package/dist/validate-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-cli.d.ts","sourceRoot":"","sources":["../src/validate-cli.ts"],"names":[],"mappings":""}

package/dist/validate-config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Collector config checks, as plain functions over `CollectorConfig` and over
+ * declared entities.
+ *
+ * The post-synth checks in `lint/post-synth/` are thin wrappers around these,
+ * so the same rules can run anywhere a config exists: on a build's output, on
+ * a composite's generated YAML, or on a collector file parsed by some other
+ * tool.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+import { type CollectorConfig } from "./model.js";
+export type CollectorIssueCode = "OTEL101" | "OTEL102" | "OTEL103" | "OTEL104" | "OTEL105" | "OTEL106" | "OTEL107" | "OTEL108" | "OTEL109";
+export interface CollectorIssue {
+    code: CollectorIssueCode;
+    severity: "error" | "warning";
+    message: string;
+    /** The pipeline id the issue is about, when it is about one. */
+    pipeline?: string;
+    /** The component id the issue is about, when it is about one. */
+    component?: string;
+}
+/** Check a collector config's references and pipeline shape (OTEL101-OTEL106). */
+export declare function validateCollectorConfig(config: CollectorConfig): CollectorIssue[];
+/**
+ * Check declared entities for what only the declaration knows (OTEL107-OTEL109):
+ * each component's own config rules, duplicate ids, and custom components'
+ * schema pins.
+ */
+export declare function validateCollectorEntities(entities: Iterable<Declarable> | Map<string, Declarable>): CollectorIssue[];
+//# sourceMappingURL=validate-config.d.ts.map

package/dist/validate-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-config.d.ts","sourceRoot":"","sources":["../src/validate-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,OAAO,EAA0C,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAGvF,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAQD,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,EAAE,CA2HjF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,cAAc,EAAE,CAyDpH"}

package/dist/validate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validate the otel lexicon's own artifacts: every built-in class is in the
+ * registry, every built-in definition carries the collector pin, and every
+ * built-in constructs and serializes.
+ */
+import type { ValidateResult } from "@intentius/chant/codegen/validate";
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+/** Every entity class the package must keep exporting. */
+export declare const REQUIRED_NAMES: string[];
+export declare function validate(): Promise<ValidateResult>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAMvF,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAEvF,0DAA0D;AAC1D,eAAO,MAAM,cAAc,UAqB1B,CAAC;AAEF,wBAAsB,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC,CA2CxD"}

package/dist/yaml.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The collector YAML emitter.
+ *
+ * Its style is the one collector configs are usually written in, and the one
+ * the k8s lexicon's `GkeOtelCollector` wrote by hand before it moved onto this
+ * lexicon:
+ *
+ * - top-level sections in the order receivers, processors, exporters,
+ *   connectors, extensions, service, separated by a blank line;
+ * - two-space indent;
+ * - a list of scalars in flow style (`receivers: [otlp, batch]`), any other
+ *   list in block style with `- ` indented under its key;
+ * - strings plain where YAML reads them back as the same string, double-quoted
+ *   otherwise (`"true"`, `"8080"`, `"a: b"`, `"${env:X}"` inside a flow list).
+ *
+ * The output always parses back to the value it was given.
+ */
+import type { CollectorConfig } from "./model.js";
+/** True when `s` can be written unquoted and still read back as the string `s`. */
+export declare function isPlainSafe(s: string, flow: boolean): boolean;
+export interface EmitOptions {
+    /** Comment lines (without `# `) written above the config. */
+    header?: string[];
+}
+/** Print a collector config as YAML. Empty sections are left out. */
+export declare function emitCollectorYaml(config: CollectorConfig, options?: EmitOptions): string;
+//# sourceMappingURL=yaml.d.ts.map

package/dist/yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAe/C,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAa7D;AAyED,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CAkB5F"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@intentius/chant-lexicon-otel",
+  "version": "0.81.0",
+  "description": "OpenTelemetry Collector lexicon for chant — typed receivers, processors, exporters, extensions and pipelines, serialized to collector YAML",
+  "license": "Apache-2.0",
+  "homepage": "https://intentius.io/chant",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/INTENTIUS/chant.git",
+    "directory": "lexicons/otel"
+  },
+  "bugs": {
+    "url": "https://github.com/INTENTIUS/chant/issues"
+  },
+  "keywords": [
+    "infrastructure-as-code",
+    "iac",
+    "typescript",
+    "opentelemetry",
+    "otel",
+    "collector",
+    "observability",
+    "chant"
+  ],
+  "type": "module",
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": {
+      "development": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./src/*.ts"
+    },
+    "./lint/post-synth": {
+      "development": "./src/lint/post-synth/index.ts",
+      "types": "./dist/lint/post-synth/index.d.ts",
+      "default": "./src/lint/post-synth/index.ts"
+    },
+    "./manifest": "./dist/manifest.json",
+    "./meta": "./dist/meta.json",
+    "./types": "./dist/types/index.d.ts"
+  },
+  "scripts": {
+    "generate": "tsx src/codegen/generate-cli.ts",
+    "bundle": "tsx src/package-cli.ts",
+    "validate": "tsx src/validate-cli.ts",
+    "docs": "tsx src/codegen/docs-cli.ts",
+    "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete"
+  },
+  "dependencies": {
+    "js-yaml": "^4.3.1"
+  },
+  "devDependencies": {
+    "@intentius/chant": "*",
+    "@types/js-yaml": "^4.0.9",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@intentius/chant": "^0.81.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,56 @@
+/**
+ * The built-in entity catalog: every class this package exports, keyed by
+ * class name. It feeds the packaged registry (`dist/meta.json`), LSP
+ * completions and hover, and the docs.
+ */
+
+import type { LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+import { componentEntityType, type ComponentClass } from "./define";
+import * as components from "./components";
+import { PIPELINE_TYPE, SERVICE_TYPE } from "./pipeline";
+
+export interface CatalogEntry {
+  className: string;
+  entityType: string;
+  kind: "receiver" | "processor" | "exporter" | "extension" | "pipeline" | "service";
+  /** The collector type, for components. */
+  type?: string;
+  description: string;
+}
+
+function isComponentClass(v: unknown): v is ComponentClass {
+  return typeof v === "function" && typeof (v as { definition?: unknown }).definition === "object";
+}
+
+export const BUILTIN_CATALOG: CatalogEntry[] = [
+  ...(Object.entries(components) as Array<[string, unknown]>)
+    .filter((e): e is [string, ComponentClass] => isComponentClass(e[1]))
+    .map(([className, cls]) => ({
+      className,
+      entityType: componentEntityType(cls.definition.kind, cls.definition.type),
+      kind: cls.definition.kind,
+      type: cls.definition.type,
+      description: cls.definition.description ?? "",
+    })),
+  {
+    className: "Pipeline",
+    entityType: PIPELINE_TYPE,
+    kind: "pipeline",
+    description: "One pipeline under service.pipelines: receivers, then processors, then exporters, for one signal",
+  },
+  {
+    className: "Service",
+    entityType: SERVICE_TYPE,
+    kind: "service",
+    description: "service.extensions and service.telemetry",
+  },
+];
+
+/** The catalog as a chant lexicon registry, keyed by class name. */
+export function lexiconRegistry(): Record<string, LexiconEntry> {
+  const out: Record<string, LexiconEntry> = {};
+  for (const e of [...BUILTIN_CATALOG].sort((a, b) => a.className.localeCompare(b.className))) {
+    out[e.className] = { resourceType: e.entityType, kind: "resource", lexicon: "otel" };
+  }
+  return out;
+}

package/src/codegen/docs-cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs";
+
+await generateDocs({ verbose: true });

package/src/codegen/docs.ts

@@ -0,0 +1,90 @@
+/**
+ * Documentation generation for the otel lexicon: the generated reference
+ * pages from the core docs pipeline, plus the authored pages in docs/pages/.
+ */
+
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite, type DocsConfig } from "@intentius/chant/codegen/docs";
+
+function serviceFromType(resourceType: string): string {
+  const parts = resourceType.split("::");
+  return parts.length >= 2 ? parts[1] : "OTel";
+}
+
+const overview = `The otel lexicon types [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)
+config: receivers, processors, exporters, extensions and the pipelines that
+connect them. \`chant build\` emits one collector config file, the YAML
+\`otelcol --config\` reads as it is.
+
+\`\`\`ts
+import { OtlpReceiver, BatchProcessor, OtlpExporter, Pipeline } from "@intentius/chant-lexicon-otel";
+
+export const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+export const batch = new BatchProcessor({ timeout: "5s" });
+export const backend = new OtlpExporter({ name: "backend", endpoint: "tempo.observability:4317" });
+
+export const traces = new Pipeline({
+  signal: "traces",
+  receivers: [otlp],
+  processors: [batch],
+  exporters: [backend],
+});
+\`\`\`
+
+The built-in component set is otlp, prometheus, hostmetrics and filelog
+receivers; batch, memory_limiter, resource, attributes, k8sattributes and
+resourcedetection processors; otlp, otlphttp, debug, prometheus and
+googlecloud exporters; and the health_check, pprof and zpages extensions.
+Their config types follow the collector-contrib release named on the
+Custom components page. A component chant doesn't ship is added with
+\`defineComponent\`, and it is serialized and checked the same way as the
+built-ins.
+
+Checks catch a pipeline that uses a component nobody declared (OTEL101), a
+pipeline with no receivers or exporters (OTEL102), a declared component no
+pipeline uses (OTEL103), and a literal credential in source (OTEL002).
+`;
+
+const outputFormat = `The otel lexicon serializes every otel entity in a build into **one
+collector config file** in YAML, the file \`otelcol --config\` reads.
+
+- Sections come out as receivers, processors, exporters, extensions, service,
+  separated by a blank line. Empty sections are left out.
+- A component's id is its collector type, or \`type/name\` when its \`name\` is
+  set. The export name in source never appears in the output.
+- A list of scalars is written in flow style (\`receivers: [otlp]\`), any
+  other list in block style. Strings are plain where YAML reads them back
+  unchanged and double-quoted otherwise.
+- Declared extensions are enabled in declaration order unless a \`Service\`
+  lists \`extensions\`.
+- Each custom component adds a \`# chant:\` comment line above the config
+  naming its schema pin. Built-ins add none.
+- A collector config has no metadata channel, so no ownership marker is
+  stamped.
+`;
+
+export async function generateDocs(opts?: { verbose?: boolean }): Promise<void> {
+  const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+  const config: DocsConfig = {
+    name: "otel",
+    displayName: "OpenTelemetry Collector",
+    description: "Typed OpenTelemetry Collector config: receivers, processors, exporters and pipelines",
+    distDir: join(pkgDir, "dist"),
+    outDir: join(pkgDir, "docs"),
+    basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/otel/",
+    overview,
+    outputFormat,
+    serviceFromType,
+    srcDir: join(pkgDir, "src"),
+    examplesDir: join(pkgDir, "examples"),
+  };
+
+  const result = docsPipeline(config);
+  writeDocsSite(config, result);
+
+  if (opts?.verbose) {
+    console.error(`Generated ${result.pages.size} documentation pages`);
+  }
+}

package/src/codegen/generate-cli.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for `npm run generate` in lexicon-otel.
+ */
+import { generate, writeGeneratedFiles } from "./generate";
+
+const result = await generate({ verbose: true });
+writeGeneratedFiles(result);

package/src/codegen/generate.ts

@@ -0,0 +1,50 @@
+/**
+ * The otel lexicon's "generation" step.
+ *
+ * There is no upstream schema to fetch: the collector defines each
+ * component's config as a Go struct, and publishes no machine-readable schema
+ * for the set as a whole. The built-in types are written by hand against the
+ * collector release named in `COLLECTOR_PIN` (src/define.ts), and this step
+ * derives the registry from them, so the packaged `dist/meta.json` can never
+ * disagree with the classes the package exports.
+ */
+
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { mkdirSync, writeFileSync } from "fs";
+import type { GenerateResult } from "@intentius/chant/codegen/generate";
+import { BUILTIN_CATALOG, lexiconRegistry } from "../catalog";
+
+export type { GenerateResult };
+
+/** The packaged types entry re-exports the compiled declarations, which carry every config type. */
+const TYPES_DTS = `// The otel lexicon's entity classes and config types are hand-written in
+// src/ and compiled to dist/index.d.ts; this entry re-exports them.
+export * from "../index";
+`;
+
+export async function generate(opts?: { verbose?: boolean; force?: boolean }): Promise<GenerateResult> {
+  const registry = lexiconRegistry();
+  const lexiconJSON = `${JSON.stringify(registry, null, 2)}\n`;
+  const components = BUILTIN_CATALOG.filter((c) => c.type !== undefined).length;
+  if (opts?.verbose) {
+    console.error(`otel: ${components} built-in components, plus Pipeline and Service (${BUILTIN_CATALOG.length} entities)`);
+  }
+  return {
+    lexiconJSON,
+    typesDTS: TYPES_DTS,
+    indexTS: "",
+    resources: BUILTIN_CATALOG.length,
+    properties: 0,
+    enums: 0,
+    warnings: [],
+  };
+}
+
+/** Write the registry to src/generated/lexicon-otel.json, for tools that read it from there. */
+export function writeGeneratedFiles(result: GenerateResult): void {
+  const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+  const dir = join(pkgDir, "src", "generated");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "lexicon-otel.json"), result.lexiconJSON);
+}

package/src/codegen/package.ts

@@ -0,0 +1,41 @@
+/**
+ * otel lexicon packaging, delegating to core's packagePipeline.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  packagePipeline,
+  collectSkills,
+  type PackageOptions,
+  type PackageResult,
+} from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+import { otelSkills } from "../skill-defs";
+
+export type { PackageOptions, PackageResult };
+
+// src/codegen/package.ts -> src/
+const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export async function packageLexicon(opts: PackageOptions = {}): Promise<PackageResult> {
+  const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+  return packagePipeline(
+    {
+      generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+      buildManifest: () => ({
+        name: "otel",
+        version: pkgJson.version ?? "0.0.1",
+        chantVersion: ">=0.1.0",
+        namespace: "OTel",
+        intrinsics: [],
+        pseudoParameters: {},
+      }),
+      srcDir,
+      collectSkills: () => collectSkills(otelSkills()),
+      version: pkgJson.version ?? "0.0.1",
+    },
+    opts,
+  );
+}

package/src/collector.ts

@@ -0,0 +1,147 @@
+/**
+ * Declared entities -> `CollectorConfig` -> YAML.
+ *
+ * The serializer runs this over a build's entities, and a composite in another
+ * lexicon (the k8s `GkeOtelCollector`, which puts the YAML in a ConfigMap)
+ * runs it over the entities it creates. Both get the same config and the same
+ * text.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { definitionFor, isOTelComponent, type OTelComponent } from "./define";
+import { SECTION_OF, type CollectorConfig, type PipelineConfig } from "./model";
+import { isPipelineEntity, isServiceEntity, type ComponentRef, type PipelineEntity, type ServiceEntity } from "./pipeline";
+import { emitCollectorYaml } from "./yaml";
+
+export interface BuiltCollector {
+  config: CollectorConfig;
+  /** One line per custom component naming its schema pin. Becomes the YAML's `# chant:` header. */
+  header: string[];
+  /** Non-fatal problems, e.g. two components declaring the same id. */
+  warnings: string[];
+  components: OTelComponent[];
+  pipelines: PipelineEntity[];
+  service?: ServiceEntity;
+}
+
+function entityList(entities: Iterable<Declarable> | Map<string, Declarable>): Declarable[] {
+  return entities instanceof Map ? [...entities.values()] : [...entities];
+}
+
+/** A config value with component entities turned into ids and `undefined` keys dropped. */
+function plain(value: unknown): unknown {
+  if (value === undefined) return undefined;
+  if (isOTelComponent(value)) return value.componentId;
+  if (Array.isArray(value)) return value.map(plain);
+  if (typeof value === "object" && value !== null) {
+    const toJSON = (value as { toJSON?: () => unknown }).toJSON;
+    if (typeof toJSON === "function") return plain(toJSON.call(value));
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (v !== undefined) out[k] = plain(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** A component's config, as it appears under its id: its props without `name`. */
+export function componentConfig(component: OTelComponent): Record<string, unknown> {
+  const { name: _name, ...rest } = (component.props ?? {}) as Record<string, unknown>;
+  return plain(rest) as Record<string, unknown>;
+}
+
+function refId(ref: ComponentRef<never> | unknown): string {
+  if (isOTelComponent(ref)) return ref.componentId;
+  return String(ref);
+}
+
+/** Build the collector config for a set of declared entities. Non-otel entities are ignored. */
+export function buildCollectorConfig(entities: Iterable<Declarable> | Map<string, Declarable>): BuiltCollector {
+  const all = entityList(entities).filter((e) => e && e.lexicon === "otel");
+  const warnings: string[] = [];
+  const components: OTelComponent[] = [];
+  const byId = new Map<string, OTelComponent>();
+  const pipelines: PipelineEntity[] = [];
+  let service: ServiceEntity | undefined;
+
+  const addComponent = (c: OTelComponent) => {
+    const key = `${c.componentKind}:${c.componentId}`;
+    const existing = byId.get(key);
+    if (existing === c) return;
+    if (existing) {
+      warnings.push(`otel: two ${c.componentKind}s declare the id "${c.componentId}"; the first one is emitted`);
+      return;
+    }
+    byId.set(key, c);
+    components.push(c);
+  };
+
+  for (const e of all) {
+    if (isOTelComponent(e)) addComponent(e);
+    else if (isPipelineEntity(e)) pipelines.push(e);
+    else if (isServiceEntity(e)) {
+      if (service) warnings.push("otel: more than one Service is declared; the first one is used");
+      else service = e;
+    }
+  }
+
+  // A component a pipeline or the service references by entity is part of the
+  // config even when the caller didn't list it: it carries its own config.
+  for (const p of pipelines) {
+    for (const ref of [...(p.props.receivers ?? []), ...(p.props.processors ?? []), ...(p.props.exporters ?? [])]) {
+      if (isOTelComponent(ref)) addComponent(ref);
+    }
+  }
+  for (const ref of service?.props.extensions ?? []) {
+    if (isOTelComponent(ref)) addComponent(ref);
+  }
+
+  const config: CollectorConfig = {};
+  for (const c of components) {
+    const section = SECTION_OF[c.componentKind];
+    const bucket = (config[section] ??= {});
+    bucket[c.componentId] = componentConfig(c);
+  }
+
+  const pipelineMap: Record<string, PipelineConfig> = {};
+  for (const p of pipelines) {
+    if (p.pipelineId in pipelineMap) {
+      warnings.push(`otel: two pipelines declare the id "${p.pipelineId}"; the first one is emitted`);
+      continue;
+    }
+    const entry: PipelineConfig = { receivers: (p.props.receivers ?? []).map(refId) };
+    const processors = (p.props.processors ?? []).map(refId);
+    if (processors.length > 0) entry.processors = processors;
+    entry.exporters = (p.props.exporters ?? []).map(refId);
+    pipelineMap[p.pipelineId] = entry;
+  }
+
+  const extensions = service?.props.extensions
+    ? service.props.extensions.map(refId)
+    : components.filter((c) => c.componentKind === "extension").map((c) => c.componentId);
+
+  if (pipelines.length > 0 || extensions.length > 0 || service?.props.telemetry) {
+    config.service = {};
+    if (extensions.length > 0) config.service.extensions = extensions;
+    if (service?.props.telemetry) config.service.telemetry = plain(service.props.telemetry) as Record<string, unknown>;
+    if (pipelines.length > 0) config.service.pipelines = pipelineMap;
+  }
+
+  const header: string[] = [];
+  for (const c of components) {
+    const def = definitionFor(c.entityType);
+    if (!def || def.builtin) continue;
+    const pin = def.pin;
+    const digest = pin?.digest ? ` ${pin.digest}` : "";
+    header.push(`chant: ${c.componentKind} ${c.componentId} schema ${pin?.source ?? "(unpinned)"}@${pin?.version ?? "(unpinned)"}${digest}`);
+  }
+
+  return { config, header, warnings, components, pipelines, service };
+}
+
+/** Collector YAML for a set of declared entities, exactly as the serializer emits it. */
+export function collectorYaml(entities: Iterable<Declarable> | Map<string, Declarable>): string {
+  const built = buildCollectorConfig(entities);
+  return emitCollectorYaml(built.config, { header: built.header });
+}