@intentius/chant 0.100.0 → 0.101.0

package/src/content-digest.test.ts

@@ -104,13 +104,13 @@ describe("other hashes use contentDigest over canonicalJson (#2514)", () => {
   test("a plan digest", () => {
     const subject = { b: 1, a: [true, null] };
     expect(computePlanDigest("lifecycle-diff", subject)).toBe(
-      contentDigest(canonicalJson({ kind: "lifecycle-diff", subject })),
+      `jcs1-${contentDigest(canonicalJson({ kind: "lifecycle-diff", subject }))}`,
     );
   });
 
   test("a plan digest orders keys by code unit, not by locale", () => {
     // localeCompare puts "a" before "B"; canonicalJson puts "B" first.
-    expect(computePlanDigest("k", { a: 1, B: 2 })).toBe(contentDigest('{"kind":"k","subject":{"B":2,"a":1}}'));
+    expect(computePlanDigest("k", { a: 1, B: 2 })).toBe(`jcs1-${contentDigest('{"kind":"k","subject":{"B":2,"a":1}}')}`);
   });
 
   test("a props hash, which drops what JSON cannot hold instead of throwing", () => {

package/src/lexicon.ts

@@ -3,7 +3,7 @@ import type { Declarable } from "./declarable";
 import type { LintRule } from "./lint/rule";
 import type { RuleSpec } from "./lint/declarative";
 import type { PostSynthCheck } from "./lint/post-synth";
-import type { TemplateParser, TemplateIR } from "./import/parser";
+import type { TemplateParser, TemplateIR, ParseContext } from "./import/parser";
 import type { TypeScriptGenerator } from "./import/generator";
 import type { EmbeddedContentImporter } from "./import/embedded";
 import type { AgentConfigImporter } from "./agents/importer";
@@ -1259,6 +1259,22 @@ export interface LexiconPlugin {
    */
   buildRoots?(ctx: BuildRootContext): Promise<BuildRootContribution>;
 
+  /**
+   * Facts about the whole read that this lexicon's entities imply, for the
+   * graph IR's `meta` bag (#2559). The otel lexicon answers
+   * `{ collector: <topology> }`, which `chant workspace graph` lifts into its
+   * `collectors` section, so core carries the shape of the answer and never
+   * imports the lexicon that computes it.
+   *
+   * Called by `chant graph --format ir` with the discovered entities of the
+   * project, after the plugins are loaded. Return `undefined` or an empty
+   * object when the project declares nothing this lexicon reports; the IR is
+   * then unchanged. Keys must be unique to the lexicon (two lexicons writing
+   * one key is a conflict the graph refuses). Omit for lexicons with nothing
+   * to report.
+   */
+  graphMeta?(entities: ReadonlyMap<string, Declarable>): Record<string, unknown> | undefined;
+
   // LSP
   /** Provide completions for LSP */
   completionProvider?(ctx: CompletionContext): CompletionItem[];
@@ -1989,6 +2005,14 @@ export interface ResourceSelector {
 export type ExportedTemplate = TemplateIR & {
   /** Phantom marker — never present at runtime. */
   readonly __fidelity?: "full-config";
+  /**
+   * The same export parsed again with a {@link ParseContext}, from the
+   * objects already read: no second read of the live target. An exporter
+   * that maps through its import parser offers this so `chant import --from`
+   * can hand embedded content to the lexicon that owns it, as file import
+   * does (#2995). Without it, embedded content is kept as written.
+   */
+  readonly reparse?: (context: ParseContext) => TemplateIR;
 };
 
 /**

package/src/lifecycle/gate-ledger.test.ts

@@ -298,6 +298,20 @@ describe("latestResolutionForPlan (#2300)", () => {
     expect(found.mismatched).toBeUndefined();
   });
 
+  // #2547: plan digests carry a version prefix now. An approval written under
+  // the bare prefix is still an approval of the same plan.
+  test("a resolution recorded under the bare sha256: prefix answers the same plan's jcs1 digest", () => {
+    const found = latestResolutionForPlan([resolution({ planDigest: PLAN_A })], "approve-live-apply", EPOCH, `jcs1-${PLAN_A}`);
+    expect(found.resolution?.resolvedBy).toBe("alex");
+    expect(found.mismatched).toBeUndefined();
+  });
+
+  test("the prefix never makes a different plan match", () => {
+    const found = latestResolutionForPlan([resolution({ planDigest: PLAN_B })], "approve-live-apply", EPOCH, `jcs1-${PLAN_A}`);
+    expect(found.resolution).toBeUndefined();
+    expect(found.mismatched?.planDigest).toBe(PLAN_B);
+  });
+
   test("a resolution for another plan does not, and comes back named", () => {
     const found = latestResolutionForPlan([resolution({ planDigest: PLAN_B })], "approve-live-apply", EPOCH, PLAN_A);
     expect(found.resolution).toBeUndefined();

package/src/lifecycle/gate-ledger.ts

@@ -41,6 +41,7 @@
  * (absent on the resolution lines written before #2119, which is why
  * `"resolution"` is the default reading).
  */
+import { samePlanDigest } from "./plan-digest";
 import { sortedJsonReplacer } from "../utils";
 import { currentGateOrigin, type GateOrigin } from "./gate-origin";
 import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../op/gate-approval";
@@ -513,7 +514,7 @@ export function latestResolutionForPlan(
     if (new Date(r.timestamp).getTime() < since) continue;
     const newest = (best: GateResolutionRecord | undefined) =>
       !best || new Date(r.timestamp).getTime() >= new Date(best.timestamp).getTime();
-    if (r.planDigest === planDigest) {
+    if (samePlanDigest(r.planDigest, planDigest)) {
       if (newest(matched)) matched = r;
     } else if (newest(mismatched)) {
       mismatched = r;

package/src/lifecycle/plan-digest.test.ts

@@ -1,5 +1,7 @@
 import { describe, test, expect } from "vitest";
-import { computePlanDigest, isPlanDigest, describePlanDigest } from "./plan-digest";
+import { canonicalJson } from "../effect-receipt";
+import { contentDigest } from "../content-digest";
+import { computePlanDigest, isPlanDigest, describePlanDigest, samePlanDigest, PLAN_DIGEST_PREFIX } from "./plan-digest";
 
 describe("computePlanDigest", () => {
   test("the same change set digests the same, whatever order its keys arrived in", () => {
@@ -23,19 +25,68 @@ describe("computePlanDigest", () => {
     );
   });
 
-  test("it is a sha256 digest, in the shape isPlanDigest accepts", () => {
+  test("it is a versioned jcs1-sha256 digest, in the shape isPlanDigest accepts", () => {
     const digest = computePlanDigest("terraform-plan", {});
-    expect(digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+    expect(digest).toMatch(/^jcs1-sha256:[0-9a-f]{64}$/);
+    expect(digest.startsWith(PLAN_DIGEST_PREFIX)).toBe(true);
     expect(isPlanDigest(digest)).toBe(true);
   });
+
+  test("it hashes the same bytes the bare sha256: digest of chant before #2547 did", () => {
+    const subject = { b: [1, { y: 2, x: 1 }], a: "\u00e9" };
+    const legacy = contentDigest(canonicalJson({ kind: "k", subject }));
+    expect(computePlanDigest("k", subject)).toBe(`jcs1-${legacy}`);
+  });
+});
+
+describe("the canonical form is RFC 8785", () => {
+  test("it sorts keys by UTF-16 code unit, as RFC 8785 section 3.2.3 does", () => {
+    // The RFC's own example: these keys in this order.
+    const keys = ["\r", "1", "\u0080", "\u00f6", "\u20ac", "\ud83d\ude00", "\ufb33"];
+    const reversed = [...keys].reverse();
+    const value = Object.fromEntries(reversed.map((k) => [k, reversed.indexOf(k)]));
+    // Written out by hand because Object.keys puts "1" first, whatever order a key was added in.
+    expect(canonicalJson(value)).toBe(`{${keys.map((k) => `${JSON.stringify(k)}:${reversed.indexOf(k)}`).join(",")}}`);
+  });
+
+  test("it writes numbers as ECMAScript does, which is what RFC 8785 section 3.2.2 specifies", () => {
+    expect(canonicalJson([1e21, 1e-7, 0.000001, -0, 4.5, 333333333.33333329])).toBe("[1e+21,1e-7,0.000001,0,4.5,333333333.3333333]");
+  });
+});
+
+describe("samePlanDigest", () => {
+  const hex = "a".repeat(64);
+  test("a digest recorded under the bare prefix is the same plan as the jcs1 one", () => {
+    expect(samePlanDigest(`sha256:${hex}`, `jcs1-sha256:${hex}`)).toBe(true);
+    expect(samePlanDigest(`jcs1-sha256:${hex}`, `sha256:${hex}`)).toBe(true);
+    expect(samePlanDigest(`sha256:${hex}`, `sha256:${hex}`)).toBe(true);
+  });
+
+  test("a different hash is a different plan, in either prefix", () => {
+    expect(samePlanDigest(`sha256:${hex}`, `jcs1-sha256:${"b".repeat(64)}`)).toBe(false);
+  });
+
+  test("a value that is not a plan digest matches only itself", () => {
+    expect(samePlanDigest("anything", "anything")).toBe(true);
+    expect(samePlanDigest("anything", `sha256:${hex}`)).toBe(false);
+    expect(samePlanDigest(undefined, `sha256:${hex}`)).toBe(false);
+    expect(samePlanDigest(undefined, undefined)).toBe(true);
+  });
 });
 
 describe("isPlanDigest", () => {
+  test("accepts both prefixes, since gates recorded before #2547 carry the bare one", () => {
+    expect(isPlanDigest(`sha256:${"a".repeat(64)}`)).toBe(true);
+    expect(isPlanDigest(`jcs1-sha256:${"a".repeat(64)}`)).toBe(true);
+  });
+
   test("refuses everything a copy-paste or a path could be", () => {
     expect(isPlanDigest("chant.tfplan")).toBe(false);
     expect(isPlanDigest(`sha256:${"a".repeat(63)}`)).toBe(false);
     expect(isPlanDigest("a".repeat(64))).toBe(false);
     expect(isPlanDigest(`sha256:${"A".repeat(64)}`)).toBe(false);
+    expect(isPlanDigest(`jcs2-sha256:${"a".repeat(64)}`)).toBe(false);
+    expect(isPlanDigest(`jcs1-sha256:${"a".repeat(63)}`)).toBe(false);
     expect(isPlanDigest(undefined)).toBe(false);
     expect(isPlanDigest(12)).toBe(false);
   });

package/src/lifecycle/plan-digest.ts

@@ -39,11 +39,22 @@
 import { canonicalJson } from "../effect-receipt";
 import { contentDigest } from "../content-digest";
 
-/** The hash a plan digest is taken with, and the prefix every digest carries. */
+/** The hash a plan digest is taken with. */
 export const PLAN_DIGEST_ALGORITHM = "sha256";
 
-/** Shape of a well-formed digest: `sha256:` and 64 lowercase hex characters. */
-const PLAN_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/**
+ * The version prefix a plan digest is written with since #2547: `jcs1` names
+ * the input form (the RFC 8785 canonical JSON of `{ kind, subject }`, see
+ * `canonicalJson` in ../effect-receipt.ts) and `sha256` the hash. A later
+ * input form gets a new prefix, so a digest always says how it was made.
+ */
+export const PLAN_DIGEST_PREFIX = "jcs1-sha256:";
+
+/** The bare prefix every digest written before #2547 carries. Still read, never written for a plan. */
+export const LEGACY_PLAN_DIGEST_PREFIX = "sha256:";
+
+/** Shape of a well-formed digest: either prefix, then 64 lowercase hex characters. */
+const PLAN_DIGEST_PATTERN = /^(?:jcs1-)?sha256:([0-9a-f]{64})$/;
 
 /**
  * Hash a plan's change set into a stable identity.
@@ -60,21 +71,40 @@ const PLAN_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
  * versions, does not change the answer. It is the caller's job to
  * hand in a projection that already excludes the volatile fields this
  * module's doc comment lists.
+ *
+ * The result is `jcs1-sha256:<hex>` (#2547). Before that it was
+ * `sha256:<hex>` over the same bytes, so the hex is unchanged and
+ * {@link samePlanDigest} treats the two spellings as one digest: a gate
+ * recorded under the old prefix still matches the plan it was approved for.
  */
 export function computePlanDigest(kind: string, subject: unknown): string {
-  return contentDigest(canonicalJson({ kind, subject }));
+  return PLAN_DIGEST_PREFIX + contentDigest(canonicalJson({ kind, subject })).slice(LEGACY_PLAN_DIGEST_PREFIX.length);
 }
 
 /**
- * Whether `raw` is a digest this code produced. Used at the `chant approve
- * --plan` boundary, so a typo, a truncated copy-paste or a plan *file* path
- * is refused before it is written into an immutable resolution that would
- * then never match anything.
+ * Whether `raw` is a digest this code produced, in either prefix. Used at the
+ * `chant approve --plan` boundary, so a typo, a truncated copy-paste or a plan
+ * *file* path is refused before it is written into an immutable resolution
+ * that would then never match anything.
  */
 export function isPlanDigest(raw: unknown): raw is string {
   return typeof raw === "string" && PLAN_DIGEST_PATTERN.test(raw);
 }
 
+/**
+ * Whether two recorded or computed plan digests name the same plan. Two
+ * well-formed plan digests are the same when their hex is, whichever prefix
+ * each carries (read both, write new, #2547). Anything else, such as a
+ * release plan's own digest, is the same only when the strings are equal.
+ */
+export function samePlanDigest(a: string | undefined, b: string | undefined): boolean {
+  if (a === b) return true;
+  if (a === undefined || b === undefined) return false;
+  const x = PLAN_DIGEST_PATTERN.exec(a);
+  const y = PLAN_DIGEST_PATTERN.exec(b);
+  return x !== null && y !== null && x[1] === y[1];
+}
+
 /**
  * A digest as it reads in a message, and the one place that decides how an
  * absent one reads. Records written before #2300 carry no digest at all, and

package/src/op/activities/activity-contracts.ts

@@ -153,6 +153,7 @@ export const proposeWorkspaceUpgradeContract = activityContract(
     base: z.string().optional(),
     remote: z.string().optional(),
     allowCode: z.boolean().optional(),
+    source: z.string().optional(),
     cwd: z.string().optional(),
   }),
   z.object({

package/src/op/activities/propose-upgrade.ts

@@ -45,6 +45,8 @@ export interface ProposeWorkspaceUpgradeArgs {
   remote?: string;
   /** Run code migrations. Default false. */
   allowCode?: boolean;
+  /** `<repo>[#<member>]`: move the scope to this template through its bridge migration (#2551). Needs `to`. */
+  source?: string;
   /** The directory holding the lineage lock. Default: the working directory. */
   cwd?: string;
   /** Replaces the git and gh child processes. For tests. */
@@ -91,8 +93,8 @@ export function proposalMarker(scope: string): string {
 
 function body(staged: StagedUpgrade, lines: string[]): string {
   return [
-    proposalMarker(staged.scope),
-    `## Template upgrade: \`${staged.scope}\``,
+    proposalMarker(staged.gate),
+    `## Template upgrade: \`${staged.gate}\``,
     "",
     `\`${staged.template}\` from \`${staged.from ?? "(no ref)"}\` to \`${staged.to ?? "(no ref)"}\`.`,
     "",
@@ -131,12 +133,13 @@ export async function proposeWorkspaceUpgrade(args: ProposeWorkspaceUpgradeArgs)
     scope: args.scope,
     to: args.to,
     allowCode: args.allowCode,
+    ...(args.source !== undefined ? { source: args.source } : {}),
     ...(args._runChant ? { runChant: args._runChant } : {}),
   });
   try {
     const lines = describeStaged(staged);
     const result: ProposeWorkspaceUpgradeResult = {
-      scope: staged.scope,
+      scope: staged.gate,
       mode,
       changed: staged.changed,
       proposed: false,
@@ -150,7 +153,7 @@ export async function proposeWorkspaceUpgrade(args: ProposeWorkspaceUpgradeArgs)
     };
     if (!result.changed || !result.checksOk || mode === "report") return result;
 
-    const branch = args.branch ?? proposalBranch(staged.scope);
+    const branch = args.branch ?? proposalBranch(staged.gate);
     const remoteDefault = await defaultBranch(run, staged.repo, remote);
     const base = args.base ?? remoteDefault;
     let current: string | null = null;
@@ -168,7 +171,7 @@ export async function proposeWorkspaceUpgrade(args: ProposeWorkspaceUpgradeArgs)
       throw new Error(`proposeWorkspaceUpgrade: cannot tell the default branch of "${remote}"; pass base`);
     }
 
-    const title = `chore(upgrade): ${staged.template} ${staged.to ?? ""} (${staged.scope})`.replace(/\s+/g, " ").replace(" )", ")");
+    const title = `chore(upgrade): ${staged.template} ${staged.to ?? ""} (${staged.gate})`.replace(/\s+/g, " ").replace(" )", ")");
     result.commit = commitStagedUpgrade(staged, branch, `${title}\n\nPatch digest: ${staged.digest}\n`);
     result.branch = branch;
     result.proposed = true;

package/src/op/gate-approval.test.ts

@@ -107,6 +107,23 @@ describe("gate approval — quorum (#2508)", () => {
     expect(port.appended).toHaveLength(0);
   });
 
+  // #2547: a gate still pending, and an approval given, under the bare sha256: prefix
+  // keep working once the run computes the same plan's digest as jcs1-sha256:.
+  test("a pending gate and an approval recorded under the bare prefix match the jcs1 digest of the same plan", async () => {
+    const jcs = `jcs1-${PLAN_A}`;
+    const block: ResolvedGateApproval = { quorum: { count: 1 }, mode: "log-only" };
+    const run = async (resolutions: GateResolutionRecord[]) => {
+      const port = memoryGateLedgerPort({ resolutions, pending: [{ ...PENDING, approval: block }] });
+      return { port, check: await evaluateGate(port, { op: "release", gate: "ship", planDigest: jcs, approval: block, now: NOW }) };
+    };
+    const approved = await run([approval({ resolvedBy: "alex", timestamp: "2026-09-01T01:00:00.000Z" })]);
+    expect(approved.check.satisfied).toBe(true);
+    // A standing fact is not rewritten just because the prefix moved.
+    const waiting = await run([]);
+    expect(waiting.check.satisfied).toBe(false);
+    expect(waiting.port.appended).toHaveLength(0);
+  });
+
   test("an approval older than the standing pending fact does not count", async () => {
     const { check } = await decide(
       [approval({ resolvedBy: "alex", timestamp: "2026-08-31T00:00:00.000Z" })],

package/src/op/gate.ts

@@ -44,7 +44,7 @@ import {
   type PendingGateInput,
   type PendingGateRecord,
 } from "../lifecycle/gate-ledger";
-import { describePlanDigest } from "../lifecycle/plan-digest";
+import { describePlanDigest, samePlanDigest } from "../lifecycle/plan-digest";
 import { isModelAuthored } from "../lifecycle/gate-origin";
 import { sortedJsonReplacer } from "../utils";
 import type { GateApprover, ResolvedGateApproval } from "./gate-approval";
@@ -325,7 +325,7 @@ export function tallyGateApprovals(
   let mismatched: GateResolutionRecord | undefined;
   for (const r of records) {
     if (r.gate !== gate || at(r) < since) continue;
-    if (planDigest !== undefined && r.planDigest !== planDigest) {
+    if (planDigest !== undefined && !samePlanDigest(r.planDigest, planDigest)) {
       if (!mismatched || at(r) >= at(mismatched)) mismatched = r;
       continue;
     }
@@ -447,7 +447,7 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   // under another policy version or another context would have `chant
   // approve` evaluate the policy against something this run no longer has.
   if (
-    standing && !isPendingGateExpired(standing, now) && standing.planDigest === input.planDigest &&
+    standing && !isPendingGateExpired(standing, now) && samePlanDigest(standing.planDigest, input.planDigest) &&
     sameApproval(standing.approval, input.approval)
   ) {
     return { satisfied: false, pending: standing, recorded: false, ...asMismatch };

package/src/op/index.ts

@@ -71,7 +71,7 @@ export type {
   GatePolicyEvaluator, GatePolicyRef, GatePolicyRequest, GateQuorum, ResolvedGateApproval,
 } from "./gate-approval";
 export {
-  computePlanDigest, isPlanDigest, describePlanDigest, PLAN_DIGEST_ALGORITHM,
+  computePlanDigest, isPlanDigest, describePlanDigest, samePlanDigest, PLAN_DIGEST_ALGORITHM, PLAN_DIGEST_PREFIX,
 } from "../lifecycle/plan-digest";
 export { gateName, usesDeprecatedGateKey, DEPRECATED_GATE_KEY_WARNING } from "./gate-name";
 export type { GateNamed } from "./gate-name";

package/src/serializer.ts

@@ -1,6 +1,7 @@
 import type { Declarable } from "./declarable";
 import type { LexiconOutput } from "./lexicon-output";
 import type { OwnershipMarker } from "./ownership";
+import type { TelemetryAttribution } from "./telemetry-attribution";
 
 /**
  * Build-time context passed to a serializer. Optional — serializers that don't
@@ -32,6 +33,14 @@ export interface SerializeContext {
    * safe default.
    */
   receipts?: ReadonlyMap<string, Declarable>;
+
+  /**
+   * Telemetry attribution (#2558, D22): the facts a workload lexicon stamps
+   * as resource attributes. Set only inside a workspace, or when the project
+   * opts in with `telemetry.attribution: true`; a serializer that ignores it,
+   * and every serializer at level 0, is unchanged. See `./telemetry-attribution.ts`.
+   */
+  telemetry?: TelemetryAttribution;
 }
 
 /**

package/src/telemetry-attribution.test.ts

@@ -0,0 +1,91 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { mergeResourceAttributes, resolveTelemetryAttribution, TELEMETRY_ATTRIBUTES, telemetryEnvironment } from "./telemetry-attribution";
+
+const scratch = mkdtempSync(join(tmpdir(), "chant-2558-"));
+afterAll(() => rmSync(scratch, { recursive: true, force: true }));
+
+let n = 0;
+/** A directory tree under the scratch directory, files keyed by relative path. */
+function tree(files: Record<string, string>): string {
+  const root = join(scratch, `t${n++}`);
+  // The git root ends the search for a declaration, as in a real checkout.
+  mkdirSync(join(root, ".git"), { recursive: true });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(join(root, path, ".."), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const declaration = JSON.stringify({
+  name: "acme",
+  schema: 1,
+  members: [
+    { name: "delivery", dir: "delivery", kind: "chant" },
+    { name: "docs", dir: "docs", kind: "other", because: "prose" },
+  ],
+});
+
+describe("resolveTelemetryAttribution", () => {
+  test("is nothing for a project with no workspace declaration above it", async () => {
+    const root = tree({ "app/chant.config.ts": "export default {};\n" });
+    expect(await resolveTelemetryAttribution(join(root, "app"), {}, "prod")).toBeUndefined();
+  });
+
+  test("is on for a project that opts in outside a workspace, with no workspace or member", async () => {
+    const root = tree({ "app/chant.config.ts": "export default {};\n" });
+    expect(await resolveTelemetryAttribution(join(root, "app"), { telemetry: { attribution: true } }, "prod")).toEqual({ environment: "prod" });
+    expect(await resolveTelemetryAttribution(join(root, "app"), { telemetry: { attribution: true } })).toEqual({});
+  });
+
+  test("names the workspace and the member inside a workspace", async () => {
+    const root = tree({ "chant.workspace.json": declaration, "delivery/chant.config.ts": "export default {};\n", "delivery/src/a.ts": "" });
+    expect(await resolveTelemetryAttribution(join(root, "delivery"), {})).toEqual({ workspace: "acme", member: "delivery" });
+    expect(await resolveTelemetryAttribution(join(root, "delivery", "src"), {}, "staging")).toEqual({ workspace: "acme", member: "delivery", environment: "staging" });
+  });
+
+  test("names no member for a directory no member owns", async () => {
+    const root = tree({ "chant.workspace.json": declaration, "scripts/x.ts": "" });
+    expect(await resolveTelemetryAttribution(join(root, "scripts"), {})).toEqual({ workspace: "acme" });
+  });
+
+  test("telemetry.attribution false turns it off inside a workspace", async () => {
+    const root = tree({ "chant.workspace.json": declaration, "delivery/x.ts": "" });
+    expect(await resolveTelemetryAttribution(join(root, "delivery"), { telemetry: { attribution: false } })).toBeUndefined();
+  });
+
+  test("a declaration that can't be read stamps the workspace-free attributes and does not throw", async () => {
+    const root = tree({ "chant.workspace.json": "{ not json", "delivery/x.ts": "" });
+    expect(await resolveTelemetryAttribution(join(root, "delivery"), {}, "prod")).toEqual({ environment: "prod" });
+  });
+});
+
+describe("telemetryEnvironment", () => {
+  test("lists the attributes in the table's order, percent-encoding values", () => {
+    const env = telemetryEnvironment({ workspace: "acme", member: "delivery", environment: "pr 12" }, { service: "api", decl: "apiService", version: "sha256:ab" });
+    expect(env).toEqual({
+      OTEL_SERVICE_NAME: "api",
+      OTEL_RESOURCE_ATTRIBUTES: "chant.workspace=acme,chant.member=delivery,chant.decl=apiService,deployment.environment.name=pr%2012,service.version=sha256%3Aab",
+    });
+  });
+
+  test("leaves out what it doesn't know", () => {
+    expect(telemetryEnvironment({}, { service: "api", decl: "api" }).OTEL_RESOURCE_ATTRIBUTES).toBe("chant.decl=api");
+  });
+
+  test("the table names every attribute the environment can carry, and marks release-time ones", () => {
+    const keys = TELEMETRY_ATTRIBUTES.map((a) => a.key);
+    expect(keys).toEqual(["service.name", "service.version", "deployment.environment.name", "vcs.ref.head.revision", "chant.workspace", "chant.member", "chant.decl"]);
+    expect(TELEMETRY_ATTRIBUTES.filter((a) => !a.stampedAtBuild).map((a) => a.key)).toEqual(["service.version", "vcs.ref.head.revision"]);
+  });
+});
+
+describe("mergeResourceAttributes", () => {
+  test("keeps keys already set and appends the rest", () => {
+    expect(mergeResourceAttributes("a=1,chant.member=mine", "chant.workspace=w,chant.member=m")).toBe("a=1,chant.member=mine,chant.workspace=w");
+    expect(mergeResourceAttributes("", "a=1")).toBe("a=1");
+  });
+});

package/src/telemetry-attribution.ts

@@ -0,0 +1,145 @@
+/**
+ * Telemetry attribution (#2558, #2524 D22, ws-060).
+ *
+ * A workload's spans carry resource attributes that name the declaration and
+ * the release that produced them, so a reader (hud, behold) can join a span
+ * back to a member, a release and a node of `chant workspace graph`. They use
+ * OpenTelemetry semantic conventions where those exist and a `chant.*`
+ * namespace for the rest ({@link TELEMETRY_ATTRIBUTES}).
+ *
+ * A lexicon that declares workloads stamps them as environment variables
+ * (`OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES`, which every OTel SDK
+ * reads) when it builds inside a workspace. The build resolves the facts once
+ * ({@link resolveTelemetryAttribution}) and hands them to each serializer on
+ * `SerializeContext.telemetry`, and {@link telemetryEnvironment} turns them
+ * into the variables for one workload.
+ *
+ * Level 0 is untouched: a project with no `chant.workspace.json` above it,
+ * and no `telemetry.attribution: true` in its config, resolves to nothing and
+ * its output is the same bytes as before. The workspace declaration reader is
+ * imported only once a declaration has been found (#2525 rule 5, pinned by
+ * #2526's goldens), and this module's name keeps it off the workspace-module
+ * list.
+ */
+
+import { relative, resolve, sep } from "node:path";
+import { findWorkspaceRoot } from "./project-root";
+
+/** What a build knows about where it runs, for the attributes it can stamp. */
+export interface TelemetryAttribution {
+  /** The declaration's `name`, when the project is inside a workspace. */
+  workspace?: string;
+  /** The member that owns the project, when it is inside a workspace and a member owns it. */
+  member?: string;
+  /** The environment the build is for (`--env`, or the config's `ownership.env`), when it has one. */
+  environment?: string;
+}
+
+/** One attribute of the table in D22, as data, so docs and tests read the same list. */
+export interface TelemetryAttributeSpec {
+  key: string;
+  /** Where the value comes from. */
+  source: string;
+  /** What a reader joins it to. */
+  joinsTo: string;
+  /** Whether a lexicon's build stamps it. The rest are set by the release step, which knows them. */
+  stampedAtBuild: boolean;
+}
+
+export const TELEMETRY_ATTRIBUTES: readonly TelemetryAttributeSpec[] = [
+  { key: "service.name", source: "the declaration's name", joinsTo: "the service", stampedAtBuild: true },
+  { key: "service.version", source: "the release's artifact digest", joinsTo: "the member's release ledger", stampedAtBuild: false },
+  { key: "deployment.environment.name", source: "the environment", joinsTo: "the ledger's environment", stampedAtBuild: true },
+  { key: "vcs.ref.head.revision", source: "the git SHA", joinsTo: "the workspace revision (D15)", stampedAtBuild: false },
+  { key: "chant.workspace", source: "the workspace declaration's `name`", joinsTo: "the workspace", stampedAtBuild: true },
+  { key: "chant.member", source: "the member name", joinsTo: "the member", stampedAtBuild: true },
+  { key: "chant.decl", source: "the declaration id", joinsTo: "the node in `chant workspace graph`", stampedAtBuild: true },
+];
+
+/** The config's opt-in or opt-out, `telemetry.attribution`. */
+function configured(config: Record<string, unknown> | undefined): boolean | undefined {
+  const telemetry = config?.telemetry;
+  if (typeof telemetry !== "object" || telemetry === null) return undefined;
+  const value = (telemetry as { attribution?: unknown }).attribution;
+  return typeof value === "boolean" ? value : undefined;
+}
+
+/**
+ * What a build at `projectDir` stamps, or `undefined` for nothing.
+ *
+ * Inside a workspace attribution is on, and `telemetry.attribution: false`
+ * turns it off. Outside one it is off, and `telemetry.attribution: true`
+ * turns it on, with the attributes that need no workspace (`chant.workspace`
+ * and `chant.member` are then absent).
+ *
+ * A declaration that can't be read stamps the workspace-free attributes only:
+ * `chant workspace check` is where a broken declaration is reported, and a
+ * build must not fail on it.
+ */
+export async function resolveTelemetryAttribution(
+  projectDir: string,
+  config: Record<string, unknown> | undefined,
+  environment?: string,
+): Promise<TelemetryAttribution | undefined> {
+  const setting = configured(config);
+  if (setting === false) return undefined;
+  const found = findWorkspaceRoot(projectDir);
+  if (!found && setting !== true) return undefined;
+  const out: TelemetryAttribution = {};
+  if (found) {
+    // Only now does workspace code load.
+    try {
+      const { readDeclaration, resolveGroups, ownerOf } = await import("./workspace/declaration");
+      const { workingTree } = await import("./workspace/tree");
+      const tree = workingTree(found.dir);
+      const declaration = readDeclaration(tree);
+      out.workspace = declaration.name;
+      const rel = relative(found.dir, resolve(projectDir));
+      const owner = ownerOf(declaration, resolveGroups(declaration, tree), rel === "" ? "" : rel.split(sep).join("/"));
+      if (owner && "member" in owner) out.member = owner.member.name;
+    } catch {
+      // Left to `chant workspace check`.
+    }
+  }
+  if (environment) out.environment = environment;
+  return out;
+}
+
+/** What a workload adds to the attributes: its own identity. */
+export interface TelemetryWorkload {
+  /** `service.name`: the workload's name in the declaration. */
+  service: string;
+  /** `chant.decl`: the declaration id, the graph node id inside the member. */
+  decl: string;
+  /** `service.version`, when the build knows the artifact digest (an image pinned by digest). */
+  version?: string;
+}
+
+/** The environment variables that carry one workload's attributes. Keys the build can't fill are left out. */
+export function telemetryEnvironment(attribution: TelemetryAttribution, workload: TelemetryWorkload): { OTEL_SERVICE_NAME: string; OTEL_RESOURCE_ATTRIBUTES: string } {
+  const pairs: [string, string | undefined][] = [
+    ["chant.workspace", attribution.workspace],
+    ["chant.member", attribution.member],
+    ["chant.decl", workload.decl],
+    ["deployment.environment.name", attribution.environment],
+    ["service.version", workload.version],
+  ];
+  return {
+    OTEL_SERVICE_NAME: workload.service,
+    OTEL_RESOURCE_ATTRIBUTES: pairs
+      .filter((p): p is [string, string] => p[1] !== undefined && p[1] !== "")
+      .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+      .join(","),
+  };
+}
+
+/**
+ * Add `extra` to a resource-attributes string a project already set. A key the
+ * project set keeps its value, so a team's own `chant.member` is never
+ * overwritten; a key it didn't set is appended.
+ */
+export function mergeResourceAttributes(existing: string, extra: string): string {
+  const have = new Set(existing.split(",").map((kv) => kv.split("=")[0]!.trim()).filter(Boolean));
+  const added = extra.split(",").filter((kv) => kv !== "" && !have.has(kv.split("=")[0]!));
+  return [existing, ...added].filter((s) => s !== "").join(",");
+}