@intentius/chant-lexicon-k8s 0.95.1 → 0.97.0

package/dist/lint/post-synth/otel-placement-helpers.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Where each OpenTelemetry Collector config in a k8s build runs: the join
+ * WK8601, WK8602 and WK8603 read (chant #2899).
+ *
+ * The collector config is a YAML string inside a ConfigMap, and whether it
+ * runs once per node or as N replicas lives on another document, the workload
+ * that mounts it. A config is joined to its workload in this order:
+ *
+ * 1. The workload's `otel.chant.dev/config` annotation, written by
+ *    `OtelCollector` and `OtelCollectorGateway`, naming the ConfigMap whose
+ *    `config.yaml` it runs.
+ * 2. Otherwise the ConfigMaps the pod spec mounts as volumes (how
+ *    `GkeOtelCollector` and hand-written manifests link them), keeping only
+ *    data keys that parse as a collector config (a `service.pipelines` map).
+ *    When a container passes `--config=<path>`, only keys named by those
+ *    paths count.
+ *
+ * Anything this can't resolve (a ConfigMap or workload outside the build, a
+ * replica count that isn't a number) is left out, so the checks stay silent
+ * rather than guess. Like every bundle-join check they see one build root at
+ * a time (chant #1939).
+ *
+ * The annotation keys are repeated here rather than imported from the
+ * composites, whose module pulls in the otel lexicon; a test pins them to
+ * `OTEL_COLLECTOR_ANNOTATIONS`.
+ */
+import { type K8sManifest } from "./k8s-helpers.js";
+export declare const PLACEMENT_ANNOTATIONS: {
+    readonly role: "otel.chant.dev/role";
+    readonly workload: "otel.chant.dev/workload";
+    readonly config: "otel.chant.dev/config";
+    readonly gateways: "otel.chant.dev/gateways";
+};
+/** The part of a collector config the placement checks read. */
+export interface CollectorConfigShape {
+    receivers?: Record<string, unknown>;
+    processors?: Record<string, unknown>;
+    exporters?: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+    service: {
+        extensions?: unknown;
+        pipelines: Record<string, {
+            receivers?: unknown;
+            processors?: unknown;
+            exporters?: unknown;
+        }>;
+    };
+}
+/** One collector config and the workload that runs it. */
+export interface CollectorPlacement {
+    workload: K8sManifest;
+    kind: "DaemonSet" | "Deployment" | "StatefulSet";
+    name: string;
+    namespace: string;
+    /**
+     * How many copies run at most: `spec.replicas` (1 when unset), raised to a
+     * HorizontalPodAutoscaler's `maxReplicas` when one targets the workload.
+     * Undefined for a DaemonSet, or when the count isn't a number.
+     */
+    replicas: number | undefined;
+    configMap: string;
+    key: string;
+    config: CollectorConfigShape;
+}
+/** Parse a ConfigMap value as a collector config, or undefined when it isn't one. */
+export declare function parseCollectorConfig(text: unknown): CollectorConfigShape | undefined;
+/** The `type` of a component id: `tail_sampling/errors` is `tail_sampling`. */
+export declare function componentType(id: string): string;
+/** The pipelines of one signal (`traces`, `traces/sampled`, ...) as [id, pipeline] pairs. */
+export declare function pipelinesOf(config: CollectorConfigShape, signal: string): Array<[string, {
+    receivers: string[];
+    processors: string[];
+    exporters: string[];
+}]>;
+/** Every pipeline, whatever its signal. */
+export declare function allPipelines(config: CollectorConfigShape): Array<[string, {
+    receivers: string[];
+    processors: string[];
+    exporters: string[];
+}]>;
+/** Processor ids of `type` that a traces pipeline runs. */
+export declare function tracePipelineProcessors(config: CollectorConfigShape, type: string): string[];
+/** Join every collector config in the build to the workload that runs it. */
+export declare function collectorPlacements(manifests: K8sManifest[]): CollectorPlacement[];
+/** How a placement is described in a message: `DaemonSet observability/otel-agent`. */
+export declare function describePlacement(p: CollectorPlacement): string;
+/** A Service that selects a workload's pods. */
+export interface SelectingService {
+    name: string;
+    namespace: string;
+    headless: boolean;
+}
+/** The Services in a workload's namespace whose selector matches its pod template labels. */
+export declare function servicesSelecting(manifests: K8sManifest[], workload: K8sManifest): SelectingService[];
+/**
+ * The Service a hostname names, as `name.namespace`, when it has the shape of
+ * cluster DNS: `name`, `name.ns`, `name.ns.svc` or `name.ns.svc.<domain>`.
+ * A bare `name` resolves in the caller's namespace.
+ */
+export declare function serviceOfHost(host: string, callerNamespace: string): string | undefined;
+/** The host of an exporter endpoint: `host:port`, `scheme://host:port/path` or `dns:///host:port`. */
+export declare function hostOfEndpoint(endpoint: unknown): string | undefined;
+//# sourceMappingURL=otel-placement-helpers.d.ts.map

package/dist/lint/post-synth/otel-placement-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-placement-helpers.d.ts","sourceRoot":"","sources":["../../../src/lint/post-synth/otel-placement-helpers.ts"],"names":[],"mappings":"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"}

package/dist/lint/post-synth/wk8601.d.ts

@@ -0,0 +1,17 @@
+/**
+ * WK8601: `tail_sampling` in a collector that runs once per node
+ *
+ * A DaemonSet collector sees the spans produced on its own node. A trace
+ * whose services run on several nodes arrives in pieces, one piece per
+ * agent, and `tail_sampling` decides on each piece alone: an error span on
+ * node A doesn't keep the rest of the trace on node B, and latency policies
+ * measure a fragment. Nothing fails; the sampled traces are just incomplete.
+ * Tail sampling belongs on a gateway that receives whole traces (see WK8602
+ * for the multi-replica gateway case).
+ *
+ * Reads the collector config from the ConfigMap the DaemonSet runs, joined
+ * through `otel-placement-helpers.ts`. One build root at a time (chant #1939).
+ */
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+export declare const wk8601: PostSynthCheck;
+//# sourceMappingURL=wk8601.d.ts.map

package/dist/lint/post-synth/wk8601.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wk8601.d.ts","sourceRoot":"","sources":["../../../src/lint/post-synth/wk8601.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAyC,MAAM,kCAAkC,CAAC;AAI9G,eAAO,MAAM,MAAM,EAAE,cAwBpB,CAAC"}

package/dist/lint/post-synth/wk8602.d.ts

@@ -0,0 +1,23 @@
+/**
+ * WK8602: `tail_sampling` on a multi-replica gateway that collectors reach
+ * without trace-aware load balancing
+ *
+ * Tail sampling needs every span of a trace in the same process. Behind a
+ * ClusterIP Service, connections are spread across the gateway replicas with
+ * no regard for trace ids, so the spans of one trace land on different
+ * replicas and each samples a fragment. The fix is a `loadbalancing`
+ * exporter in front, routing by `traceID` to the replicas themselves (the
+ * `k8s` resolver on any Service that selects them, or the `dns` resolver on
+ * a headless one). A single-replica gateway passes.
+ *
+ * The check fires on evidence, not on absence: another collector in the
+ * build whose traces pipeline exports to one of the gateway's Services
+ * through `otlp`/`otlphttp`, through a `loadbalancing` exporter routed by
+ * something other than `traceID`, or through the `dns` resolver on a
+ * ClusterIP Service (one virtual IP, so one backend per connection). When
+ * the senders live in another build root, or are applications talking to
+ * the gateway directly, it stays silent (chant #1939).
+ */
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+export declare const wk8602: PostSynthCheck;
+//# sourceMappingURL=wk8602.d.ts.map

package/dist/lint/post-synth/wk8602.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wk8602.d.ts","sourceRoot":"","sources":["../../../src/lint/post-synth/wk8602.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAyC,MAAM,kCAAkC,CAAC;AAsE9G,eAAO,MAAM,MAAM,EAAE,cAyCpB,CAAC"}

package/dist/lint/post-synth/wk8603.d.ts

@@ -0,0 +1,19 @@
+/**
+ * WK8603: `k8s_cluster` receiver in a collector that runs more than one copy
+ * without a leader elector
+ *
+ * The `k8s_cluster` receiver reports cluster-level metrics and entity events
+ * (nodes, deployments, pods, resource quotas) by watching the API server.
+ * Every copy of the collector reports every object, so in a DaemonSet the
+ * cluster is reported once per node, and in a Deployment once per replica:
+ * duplicated series and N watches against the API server. Run it in a
+ * single-replica Deployment, or set the receiver's `k8s_leader_elector` to a
+ * `k8s_leader_elector` extension enabled in `service.extensions` (both ship in
+ * otelcol-contrib and otelcol-k8s at the pinned v0.130.0), so only the
+ * leader collects.
+ *
+ * One build root at a time (chant #1939).
+ */
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+export declare const wk8603: PostSynthCheck;
+//# sourceMappingURL=wk8603.d.ts.map

package/dist/lint/post-synth/wk8603.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wk8603.d.ts","sourceRoot":"","sources":["../../../src/lint/post-synth/wk8603.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAyC,MAAM,kCAAkC,CAAC;AAiB9G,eAAO,MAAM,MAAM,EAAE,cA+BpB,CAAC"}

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "k8s",
-  "version": "0.95.1",
+  "version": "0.97.0",
   "chantVersion": ">=0.1.0",
   "namespace": "K8s",
   "intrinsics": [],

package/dist/okf/index.md

@@ -280,3 +280,6 @@ okf_version: '0.2'
 * [WK8503](/rules/WK8503.md) - Workload consumes a Secret nothing in the output produces — produce it (Secret, ExternalSecret, InfisicalSecret, Certificate) or declare its provenance with...
 * [WK8504](/rules/WK8504.md) - committed-encrypted secret declaration does not resolve — the declared file is missing, is not the named Secret, or is not encrypted
 * [WK8505](/rules/WK8505.md) - committed-encrypted secret with no Flux decryption wiring — add decryption: 'sops' to the FluxAppFor reconciling the path that carries it. Sees one build roo...
+* [WK8601](/rules/WK8601.md) - OpenTelemetry Collector runs tail_sampling as a per-node DaemonSet; each agent sees only its node's spans, so decisions are made on partial traces. Sees one...
+* [WK8602](/rules/WK8602.md) - OpenTelemetry Collector gateway runs tail_sampling on more than one replica, but collectors send it traces without a loadbalancing exporter routed by traceID...
+* [WK8603](/rules/WK8603.md) - OpenTelemetry Collector runs the k8s_cluster receiver in a DaemonSet or multi-replica workload without a k8s_leader_elector; every copy reports every cluster...

package/dist/okf/rules/WK8601.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: WK8601
+description: 'OpenTelemetry Collector runs tail_sampling as a per-node DaemonSet; each agent sees only its node''s spans, so decisions are made on partial traces. Sees one build root at a time (chant #1939).'
+id: WK8601
+severity: error
+category: post-synth
+lexicon: k8s
+docs: https://intentius.io/chant/lexicons/k8s/rules/
+---
+OpenTelemetry Collector runs tail_sampling as a per-node DaemonSet; each agent sees only its node's spans, so decisions are made on partial traces. Sees one build root at a time (chant #1939).
+
+## Applies to
+
+- [DaemonSet](/types/DaemonSet.md)

package/dist/okf/rules/WK8602.md

@@ -0,0 +1,16 @@
+---
+type: post-synth-check
+title: WK8602
+description: 'OpenTelemetry Collector gateway runs tail_sampling on more than one replica, but collectors send it traces without a loadbalancing exporter routed by traceID. Sees one build root at a time (chant #...'
+id: WK8602
+severity: error
+category: post-synth
+lexicon: k8s
+docs: https://intentius.io/chant/lexicons/k8s/rules/
+---
+OpenTelemetry Collector gateway runs tail_sampling on more than one replica, but collectors send it traces without a loadbalancing exporter routed by traceID. Sees one build root at a time (chant #1939).
+
+## Applies to
+
+- [DaemonSet](/types/DaemonSet.md)
+- [Service](/types/Service.md)

package/dist/okf/rules/WK8603.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: WK8603
+description: OpenTelemetry Collector runs the k8s_cluster receiver in a DaemonSet or multi-replica workload without a k8s_leader_elector; every copy reports every cluster object. Sees one build root at a time (...
+id: WK8603
+severity: error
+category: post-synth
+lexicon: k8s
+docs: https://intentius.io/chant/lexicons/k8s/rules/
+---
+OpenTelemetry Collector runs the k8s_cluster receiver in a DaemonSet or multi-replica workload without a k8s_leader_elector; every copy reports every cluster object. Sees one build root at a time (chant #1939).
+
+## Applies to
+
+- [DaemonSet](/types/DaemonSet.md)

package/dist/okf/types/DaemonSet.md

@@ -17,3 +17,6 @@ resource_type: K8s::Apps::DaemonSet
 
 - [WK8002](/rules/WK8002.md): Latest Image Tag
 - [WK8003](/rules/WK8003.md): Missing Resource Limits
+- [WK8601](/rules/WK8601.md): OpenTelemetry Collector runs tail_sampling as a per-node DaemonSet; each agent sees only its node's spans, so decisions are made on partial traces. Sees one build root at a time (chant #1939).
+- [WK8602](/rules/WK8602.md): OpenTelemetry Collector gateway runs tail_sampling on more than one replica, but collectors send it traces without a loadbalancing exporter routed by traceID. Sees one build root at a time (chant #1939).
+- [WK8603](/rules/WK8603.md): OpenTelemetry Collector runs the k8s_cluster receiver in a DaemonSet or multi-replica workload without a k8s_leader_elector; every copy reports every cluster object. Sees one build root at a time (chant #1939).

package/dist/okf/types/Service.md

@@ -18,3 +18,4 @@ resource_type: K8s::Core::Service
 - [WK8104](/rules/WK8104.md): Ports should be named — named ports improve Service and NetworkPolicy configuration
 - [WK8301](/rules/WK8301.md): Probes required — containers should have livenessProbe and readinessProbe
 - [WK8305](/rules/WK8305.md): Ingress port not matching Service — backend port must match a declared Service port
+- [WK8602](/rules/WK8602.md): OpenTelemetry Collector gateway runs tail_sampling on more than one replica, but collectors send it traces without a loadbalancing exporter routed by traceID. Sees one build root at a time (chant #1939).

package/dist/rules/otel-placement-helpers.ts

@@ -0,0 +1,277 @@
+/**
+ * Where each OpenTelemetry Collector config in a k8s build runs: the join
+ * WK8601, WK8602 and WK8603 read (chant #2899).
+ *
+ * The collector config is a YAML string inside a ConfigMap, and whether it
+ * runs once per node or as N replicas lives on another document, the workload
+ * that mounts it. A config is joined to its workload in this order:
+ *
+ * 1. The workload's `otel.chant.dev/config` annotation, written by
+ *    `OtelCollector` and `OtelCollectorGateway`, naming the ConfigMap whose
+ *    `config.yaml` it runs.
+ * 2. Otherwise the ConfigMaps the pod spec mounts as volumes (how
+ *    `GkeOtelCollector` and hand-written manifests link them), keeping only
+ *    data keys that parse as a collector config (a `service.pipelines` map).
+ *    When a container passes `--config=<path>`, only keys named by those
+ *    paths count.
+ *
+ * Anything this can't resolve (a ConfigMap or workload outside the build, a
+ * replica count that isn't a number) is left out, so the checks stay silent
+ * rather than guess. Like every bundle-join check they see one build root at
+ * a time (chant #1939).
+ *
+ * The annotation keys are repeated here rather than imported from the
+ * composites, whose module pulls in the otel lexicon; a test pins them to
+ * `OTEL_COLLECTOR_ANNOTATIONS`.
+ */
+
+import { load } from "js-yaml";
+import { extractContainers, extractPodSpec, type K8sManifest } from "./k8s-helpers";
+
+export const PLACEMENT_ANNOTATIONS = {
+  role: "otel.chant.dev/role",
+  workload: "otel.chant.dev/workload",
+  config: "otel.chant.dev/config",
+  gateways: "otel.chant.dev/gateways",
+} as const;
+
+/** The part of a collector config the placement checks read. */
+export interface CollectorConfigShape {
+  receivers?: Record<string, unknown>;
+  processors?: Record<string, unknown>;
+  exporters?: Record<string, unknown>;
+  extensions?: Record<string, unknown>;
+  service: {
+    extensions?: unknown;
+    pipelines: Record<string, { receivers?: unknown; processors?: unknown; exporters?: unknown }>;
+  };
+}
+
+/** One collector config and the workload that runs it. */
+export interface CollectorPlacement {
+  workload: K8sManifest;
+  kind: "DaemonSet" | "Deployment" | "StatefulSet";
+  name: string;
+  namespace: string;
+  /**
+   * How many copies run at most: `spec.replicas` (1 when unset), raised to a
+   * HorizontalPodAutoscaler's `maxReplicas` when one targets the workload.
+   * Undefined for a DaemonSet, or when the count isn't a number.
+   */
+  replicas: number | undefined;
+  configMap: string;
+  key: string;
+  config: CollectorConfigShape;
+}
+
+const PLACED_KINDS = new Set(["DaemonSet", "Deployment", "StatefulSet"]);
+
+function ns(m: K8sManifest): string {
+  const n = m.metadata?.namespace;
+  return typeof n === "string" && n.length > 0 ? n : "default";
+}
+
+function annotations(m: K8sManifest): Record<string, unknown> {
+  const a = (m.metadata as { annotations?: unknown } | undefined)?.annotations;
+  return a && typeof a === "object" ? (a as Record<string, unknown>) : {};
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Parse a ConfigMap value as a collector config, or undefined when it isn't one. */
+export function parseCollectorConfig(text: unknown): CollectorConfigShape | undefined {
+  if (typeof text !== "string") return undefined;
+  let value: unknown;
+  try {
+    value = load(text);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(value) || !isRecord(value.service) || !isRecord(value.service.pipelines)) return undefined;
+  return value as unknown as CollectorConfigShape;
+}
+
+/** The `type` of a component id: `tail_sampling/errors` is `tail_sampling`. */
+export function componentType(id: string): string {
+  const slash = id.indexOf("/");
+  return slash === -1 ? id : id.slice(0, slash);
+}
+
+function stringList(v: unknown): string[] {
+  return Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+}
+
+/** The pipelines of one signal (`traces`, `traces/sampled`, ...) as [id, pipeline] pairs. */
+export function pipelinesOf(config: CollectorConfigShape, signal: string): Array<[string, { receivers: string[]; processors: string[]; exporters: string[] }]> {
+  const out: Array<[string, { receivers: string[]; processors: string[]; exporters: string[] }]> = [];
+  for (const [id, p] of Object.entries(config.service.pipelines)) {
+    if (componentType(id) !== signal || !isRecord(p)) continue;
+    out.push([id, { receivers: stringList(p.receivers), processors: stringList(p.processors), exporters: stringList(p.exporters) }]);
+  }
+  return out;
+}
+
+/** Every pipeline, whatever its signal. */
+export function allPipelines(config: CollectorConfigShape): Array<[string, { receivers: string[]; processors: string[]; exporters: string[] }]> {
+  return ["traces", "metrics", "logs"].flatMap((s) => pipelinesOf(config, s));
+}
+
+/** Processor ids of `type` that a traces pipeline runs. */
+export function tracePipelineProcessors(config: CollectorConfigShape, type: string): string[] {
+  const out = new Set<string>();
+  for (const [, p] of pipelinesOf(config, "traces")) {
+    for (const id of p.processors) if (componentType(id) === type) out.add(id);
+  }
+  return [...out];
+}
+
+/** The ConfigMap file names a workload's containers pass with `--config`. */
+function configArgNames(workload: K8sManifest): string[] {
+  const names: string[] = [];
+  for (const c of extractContainers(workload)) {
+    const argv = [...stringList(c.command), ...stringList(c.args)];
+    for (let i = 0; i < argv.length; i++) {
+      let path: string | undefined;
+      if (argv[i].startsWith("--config=")) path = argv[i].slice("--config=".length);
+      else if (argv[i] === "--config") path = argv[i + 1];
+      if (!path) continue;
+      // `--config=env:...`, `--config=yaml:...` and URLs are not files.
+      if (/^[a-z]+:/.test(path)) continue;
+      names.push(path.slice(path.lastIndexOf("/") + 1));
+    }
+  }
+  return names;
+}
+
+/** ConfigMap names mounted by a workload's pod spec, directly or through a projected volume. */
+function mountedConfigMaps(workload: K8sManifest): string[] {
+  const pod = extractPodSpec(workload);
+  const out: string[] = [];
+  for (const v of Array.isArray(pod?.volumes) ? pod.volumes : []) {
+    if (!isRecord(v)) continue;
+    const cm = isRecord(v.configMap) ? v.configMap.name : undefined;
+    if (typeof cm === "string") out.push(cm);
+    const sources = isRecord(v.projected) && Array.isArray(v.projected.sources) ? v.projected.sources : [];
+    for (const s of sources) {
+      const name = isRecord(s) && isRecord(s.configMap) ? s.configMap.name : undefined;
+      if (typeof name === "string") out.push(name);
+    }
+  }
+  return out;
+}
+
+/** The max replica count an HPA allows for kind/name in a namespace, if one targets it. */
+function hpaMax(manifests: K8sManifest[], kind: string, name: string, namespace: string): number | undefined {
+  let max: number | undefined;
+  for (const m of manifests) {
+    if (m.kind !== "HorizontalPodAutoscaler" || ns(m) !== namespace) continue;
+    const target = isRecord(m.spec?.scaleTargetRef) ? m.spec.scaleTargetRef : undefined;
+    if (!target || target.kind !== kind || target.name !== name) continue;
+    const n = m.spec?.maxReplicas;
+    if (typeof n === "number") max = Math.max(max ?? 0, n);
+  }
+  return max;
+}
+
+/** Join every collector config in the build to the workload that runs it. */
+export function collectorPlacements(manifests: K8sManifest[]): CollectorPlacement[] {
+  const configMaps = new Map<string, K8sManifest>();
+  for (const m of manifests) {
+    if (m.kind === "ConfigMap" && typeof m.metadata?.name === "string") configMaps.set(`${ns(m)}/${m.metadata.name}`, m);
+  }
+
+  const out: CollectorPlacement[] = [];
+  for (const workload of manifests) {
+    if (!workload.kind || !PLACED_KINDS.has(workload.kind)) continue;
+    const name = workload.metadata?.name;
+    if (typeof name !== "string") continue;
+    const namespace = ns(workload);
+    const kind = workload.kind as CollectorPlacement["kind"];
+
+    let replicas: number | undefined;
+    if (kind !== "DaemonSet") {
+      const r = workload.spec?.replicas;
+      const base = r === undefined || r === null ? 1 : typeof r === "number" ? r : undefined;
+      const hpa = hpaMax(manifests, kind, name, namespace);
+      replicas = base === undefined ? undefined : Math.max(base, hpa ?? 0);
+    }
+
+    const annotated = annotations(workload)[PLACEMENT_ANNOTATIONS.config];
+    const candidates: Array<{ configMap: string; keys?: string[] }> =
+      typeof annotated === "string"
+        ? [{ configMap: annotated, keys: ["config.yaml"] }]
+        : mountedConfigMaps(workload).map((configMap) => ({ configMap }));
+    const argNames = configArgNames(workload);
+
+    for (const { configMap, keys } of candidates) {
+      const cm = configMaps.get(`${namespace}/${configMap}`);
+      if (!cm || !isRecord(cm.data)) continue;
+      const parsed: Array<[string, CollectorConfigShape]> = [];
+      for (const [key, text] of Object.entries(cm.data)) {
+        if (keys && !keys.includes(key)) continue;
+        const config = parseCollectorConfig(text);
+        if (config) parsed.push([key, config]);
+      }
+      const named = parsed.filter(([key]) => argNames.includes(key));
+      for (const [key, config] of named.length > 0 ? named : parsed) {
+        out.push({ workload, kind, name, namespace, replicas, configMap, key, config });
+      }
+    }
+  }
+  return out;
+}
+
+/** How a placement is described in a message: `DaemonSet observability/otel-agent`. */
+export function describePlacement(p: CollectorPlacement): string {
+  return `${p.kind} ${p.namespace}/${p.name}`;
+}
+
+// ── Services and exporters (WK8602) ─────────────────────────────────
+
+/** A Service that selects a workload's pods. */
+export interface SelectingService {
+  name: string;
+  namespace: string;
+  headless: boolean;
+}
+
+/** The Services in a workload's namespace whose selector matches its pod template labels. */
+export function servicesSelecting(manifests: K8sManifest[], workload: K8sManifest): SelectingService[] {
+  const template = isRecord(workload.spec?.template) ? workload.spec.template : undefined;
+  const labels = isRecord(template?.metadata) && isRecord(template.metadata.labels) ? template.metadata.labels : {};
+  const out: SelectingService[] = [];
+  for (const m of manifests) {
+    if (m.kind !== "Service" || ns(m) !== ns(workload) || typeof m.metadata?.name !== "string") continue;
+    const selector = isRecord(m.spec?.selector) ? m.spec.selector : undefined;
+    if (!selector || Object.keys(selector).length === 0) continue;
+    if (!Object.entries(selector).every(([k, v]) => labels[k] === v)) continue;
+    out.push({ name: m.metadata.name, namespace: ns(m), headless: m.spec?.clusterIP === "None" });
+  }
+  return out;
+}
+
+/**
+ * The Service a hostname names, as `name.namespace`, when it has the shape of
+ * cluster DNS: `name`, `name.ns`, `name.ns.svc` or `name.ns.svc.<domain>`.
+ * A bare `name` resolves in the caller's namespace.
+ */
+export function serviceOfHost(host: string, callerNamespace: string): string | undefined {
+  const parts = host.split(".");
+  if (parts.some((p) => p.length === 0)) return undefined;
+  if (parts.length === 1) return `${parts[0]}.${callerNamespace}`;
+  if (parts.length === 2) return `${parts[0]}.${parts[1]}`;
+  if (parts[2] === "svc") return `${parts[0]}.${parts[1]}`;
+  return undefined;
+}
+
+/** The host of an exporter endpoint: `host:port`, `scheme://host:port/path` or `dns:///host:port`. */
+export function hostOfEndpoint(endpoint: unknown): string | undefined {
+  if (typeof endpoint !== "string" || endpoint.length === 0) return undefined;
+  let rest = endpoint.replace(/^[a-z][a-z0-9+.-]*:\/\/\/?/i, "");
+  rest = rest.split("/")[0];
+  if (rest.startsWith("[")) return undefined;
+  const colon = rest.lastIndexOf(":");
+  return colon === -1 ? rest : rest.slice(0, colon);
+}

package/dist/rules/wk8601.ts

@@ -0,0 +1,44 @@
+/**
+ * WK8601: `tail_sampling` in a collector that runs once per node
+ *
+ * A DaemonSet collector sees the spans produced on its own node. A trace
+ * whose services run on several nodes arrives in pieces, one piece per
+ * agent, and `tail_sampling` decides on each piece alone: an error span on
+ * node A doesn't keep the rest of the trace on node B, and latency policies
+ * measure a fragment. Nothing fails; the sampled traces are just incomplete.
+ * Tail sampling belongs on a gateway that receives whole traces (see WK8602
+ * for the multi-replica gateway case).
+ *
+ * Reads the collector config from the ConfigMap the DaemonSet runs, joined
+ * through `otel-placement-helpers.ts`. One build root at a time (chant #1939).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { docsToManifests } from "./k8s-helpers";
+import { collectorPlacements, describePlacement, tracePipelineProcessors } from "./otel-placement-helpers";
+
+export const wk8601: PostSynthCheck = {
+  id: "WK8601",
+  description:
+    "OpenTelemetry Collector runs tail_sampling as a per-node DaemonSet; each agent sees only its node's spans, so decisions are made on partial traces. Sees one build root at a time (chant #1939).",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const p of collectorPlacements(docsToManifests(ctx))) {
+      if (p.kind !== "DaemonSet") continue;
+      const ids = tracePipelineProcessors(p.config, "tail_sampling");
+      if (ids.length === 0) continue;
+      diagnostics.push({
+        checkId: "WK8601",
+        severity: "warning",
+        message:
+          `${describePlacement(p)} runs ${ids.join(", ")} (ConfigMap ${p.configMap}, ${p.key}) on every node. ` +
+          `Each agent sees only its own node's spans, so sampling decisions are made on partial traces. ` +
+          `Move tail sampling to a gateway (OtelCollectorGateway) and send traces to it through a loadbalancing exporter routed by traceID.`,
+        entity: p.name,
+        lexicon: "k8s",
+      });
+    }
+    return diagnostics;
+  },
+};