@intentius/chant 0.100.0 → 0.102.0

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(",");
+}

package/src/workspace/__fixtures__/studio-template-84c8b21.json

@@ -2,7 +2,7 @@
  "$comment": "The studio kit's app template, arugula-salad/studio 84c8b21 template/, which is chud's template at jhgaylor/chud 43afcf1 with the chud CLI steps taken out of its prose and delivery/package.json. The fixture for chant workspace upgrade's chud-lexicon-exit migration (INTENTIUS/chant#2737). Data only: nothing here is imported or run by chant's tests, and delivery/ names @intentius/chud-runtime, which chant never installs.",
  "source": "https://github.com/arugula-salad/studio/tree/84c8b21/template",
  "files": {
-  ".github/workflows/ci.yml": "name: ci\n\non:\n  push:\n    branches:\n      - main\n  pull_request: {}\n\npermissions:\n  contents: read\n\nconcurrency:\n  group: ci-${{ github.ref }}\n  cancel-in-progress: '${{ github.event_name == ''pull_request'' }}'\n\njobs:\n  ci:\n    runs-on: ubuntu-latest\n    timeout-minutes: 20\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      - name: Setup Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: '22.x'\n          cache: npm\n          cache-dependency-path: delivery/package-lock.json\n      - name: Read access to @intentius/chud-runtime\n        env:\n          CHUD_RUNTIME_TOKEN: '${{ secrets.CHUD_RUNTIME_TOKEN }}'\n          CHUD_RUNTIME_DEPLOY_KEY: '${{ secrets.CHUD_RUNTIME_DEPLOY_KEY }}'\n        run: |\n          if [ -n \"$CHUD_RUNTIME_TOKEN\" ]; then\n            git config --global url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf ssh://git@github.com/\n            git config --global --add url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf git@github.com:\n          elif [ -n \"$CHUD_RUNTIME_DEPLOY_KEY\" ]; then\n            mkdir -p ~/.ssh && chmod 700 ~/.ssh\n            printf '%s\\n' \"$CHUD_RUNTIME_DEPLOY_KEY\" > ~/.ssh/id_ed25519 && chmod 600 ~/.ssh/id_ed25519\n            echo \"github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl\" >> ~/.ssh/known_hosts\n          else\n            echo \"neither CHUD_RUNTIME_TOKEN nor CHUD_RUNTIME_DEPLOY_KEY is set: a private @intentius/chud-runtime will not install\"\n          fi\n      - name: Install\n        run: npm ci\n        working-directory: delivery\n      - name: Workflow YAML is built from ci/ci.ts\n        run: npm run ci:check\n        working-directory: delivery\n      - name: chant workspace check\n        run: npx chant workspace check\n        working-directory: delivery\n      - name: chant build\n        run: npx chant build -o \"$RUNNER_TEMP/chant-build.out\"\n        working-directory: delivery\n      - name: chant lint\n        run: npx chant lint\n        working-directory: delivery\n      - name: App tests and approved contract checks\n        run: npm run check\n        working-directory: delivery\n",
+  ".github/workflows/ci.yml": "name: ci\n\non:\n  push:\n    branches:\n      - main\n  pull_request: {}\n\npermissions:\n  contents: read\n\nconcurrency:\n  group: ci-${{ github.ref }}\n  cancel-in-progress: '${{ github.event_name == ''pull_request'' }}'\n\njobs:\n  ci:\n    runs-on: ubuntu-latest\n    timeout-minutes: 20\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v7\n      - name: Setup Node.js\n        uses: actions/setup-node@v7\n        with:\n          node-version: '22.x'\n          cache: npm\n          cache-dependency-path: delivery/package-lock.json\n      - name: Read access to @intentius/chud-runtime\n        env:\n          CHUD_RUNTIME_TOKEN: '${{ secrets.CHUD_RUNTIME_TOKEN }}'\n          CHUD_RUNTIME_DEPLOY_KEY: '${{ secrets.CHUD_RUNTIME_DEPLOY_KEY }}'\n        run: |\n          if [ -n \"$CHUD_RUNTIME_TOKEN\" ]; then\n            git config --global url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf ssh://git@github.com/\n            git config --global --add url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf git@github.com:\n          elif [ -n \"$CHUD_RUNTIME_DEPLOY_KEY\" ]; then\n            mkdir -p ~/.ssh && chmod 700 ~/.ssh\n            printf '%s\\n' \"$CHUD_RUNTIME_DEPLOY_KEY\" > ~/.ssh/id_ed25519 && chmod 600 ~/.ssh/id_ed25519\n            echo \"github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl\" >> ~/.ssh/known_hosts\n          else\n            echo \"neither CHUD_RUNTIME_TOKEN nor CHUD_RUNTIME_DEPLOY_KEY is set: a private @intentius/chud-runtime will not install\"\n          fi\n      - name: Install\n        run: npm ci\n        working-directory: delivery\n      - name: Workflow YAML is built from ci/ci.ts\n        run: npm run ci:check\n        working-directory: delivery\n      - name: chant workspace check\n        run: npx chant workspace check\n        working-directory: delivery\n      - name: chant build\n        run: npx chant build -o \"$RUNNER_TEMP/chant-build.out\"\n        working-directory: delivery\n      - name: chant lint\n        run: npx chant lint\n        working-directory: delivery\n      - name: App tests and approved contract checks\n        run: npm run check\n        working-directory: delivery\n",
   ".gitignore": "node_modules/\n.chud/\n.data/\n.hud/\n# chant build output (the Ops as op.json)\ndist/\n",
   "CLAUDE.md": "# {{chant:name}}: notes for agents\n\nThis repo is a chant workspace made from the studio kit's template\n(`chant init --from <studio>/template`, then the kit's `box/setup-app.mjs`).\nIt holds everything about {{chant:name}}: the app, the contracts it must\nmeet, the decisions made about it, the agents that build it, and the Ops that\nship it. `chant.workspace.json` declares its members, and chant finds\neverything through them.\n\nYou are probably running as hud's agent in the app's page: the app's own\nserver (its `dev` script, `node --watch`) behind hud's proxy. Your working\ndirectory is this one (the workspace root), and your job is to build the app\nin `app/`. See `app/CLAUDE.md`. Decisions and work items are chant records:\nwrite them with `chant workspace records`, and hud shows them.\n\n## Where things are\n\n| Member | Directory | What it holds |\n|---|---|---|\n| app | `app/` | The product. Edited live while its `dev` script runs. |\n| delivery | `delivery/` | The chant project: `chant.config.ts` (this repo's settings as `buildParams`: ports and how to run the app), `ops/` (the release, rollback, upgrade and dispatch Ops), `deploy/` (the app as a chant component and the sites it ships to), `agents/team.ts` (the agents that build the app, as fountain specs), `decisions/` (the decision points and the ship gate's Cedar policy), `ci/ci.ts` (this repo's CI), `.chant/` (the write-scope policy and the contract-sizing lint rules), and `node_modules/`. |\n| design | `design/` | chud's records, written by the design app: `contracts/` (and `contracts/checks/`), `drivers/`, `evidence/`, `sessions/`, `context/`, `proposals/`. Also the design app's overrides and the screen specs in `screens/`. |\n| design-client | `design-client/` | A placeholder for a vendored design client. Nothing here yet. |\n\n`work/` at the root holds the units of work: chant work items\n(`W-NNN-<slug>.md`, `work.kind.mjs` and `work.schema.json` beside them), one\nper agent run or piece of manual work, with chud's fields under `x-chud`.\nchud writes them through `chant workspace records new|amend`; list them with\n`chant workspace records --kind work/work.kind.mjs`.\n\n`decisions/` at the root holds the decision records: chant decision records\n(`decision.kind.mjs` and `decision.schema.json` beside them define the\nformat), the template's `ref-001`, `ref-002` and `chud-001`, and the\n`chud-NNN` records the design app writes. Each cites the issue in\n`chud.decisions.issue` (`delivery/chant.config.ts`) as its source, or\n`chud-001`'s when none is set. List the\ncurrent ones with\n`chant workspace records --kind decisions/decision.kind.mjs --current`.\n\nA decision pins the files it rests on by path and hash: an `evidence` entry\n`{ title, path, sha256, as_of }`, `path` from the workspace root and inside a\nmember (such as `design/screens/home.json`), and `sha256` the hash of the\nfile's bytes, which `chant workspace records pin <path>` prints. What it\ngoverns goes in `constrains` as `member:<name>` or `path:<path>`. `chant\nworkspace records` reports each pin as `pinned`, `drifted` (the file changed\nsince), `missing` or `stale` (a superseding decision pins the file at the\nsame hash, and the file has not changed since). A drifted pin means the file\nmoved away from what was decided: say so, and do not re-pin it yourself. The\ndesign app pins a file by name (`POST /api/decisions` with `{ title, path }`\nin `evidence` hashes it) and re-pins with `PUT /api/decisions/<id>`.\n\nEvidence (`design/evidence/<sha256>.json`) and design sessions\n(`design/sessions/S-NNNN.json`) are chant record kinds too, declared on the\ndesign member in `chant.workspace.json` (`design/evidence/evidence.kind.mjs`,\n`design/sessions/session.kind.mjs`). Read them with\n`chant workspace records --json`, which reads every declared kind. An\nevidence record's id is the sha256 of its bytes; a file whose name is not\nthat hash carries `asset-drift` and is not evidence. A closed session is\nsealed, and an edit to it is `session-seal-mismatch`. Only the design app and\nthe Ops' Check phases write these files, and each write is read back through\nchant before it is committed. Never write or edit one by hand, and never\nrename one.\n\n- Records keep their core fields in YAML front matter (or JSON), validated\n  against the schemas in\n  `delivery/node_modules/@intentius/chud-runtime/schemas/`. Extra fields must\n  start with `x-`.\n- `delivery/node_modules/@intentius/chud-runtime` is the machinery (the design\n  app, the Op steps). It is a versioned dependency: never edit it. Upgrade it\n  with the upgrade Op (`npm run upgrade` in `delivery/`), which stops at a\n  gate for a person.\n- `.chud/`: local state (hud data, staged releases, the local site). Never\n  edit it, and never commit it.\n\nEvery path chud records (a unit's scope, a protected path, a record's `file`)\nis relative to this directory, the git top-level.\n\n## Rules\n\n- Contracts and decisions are written by the design app. Read the ones that\n  touch your work and do not undo them. Never edit `design/contracts/`,\n  `decisions/`, `work/`, `design/evidence/`, `design/drivers/`,\n  `design/context/`, `design/sessions/`, `delivery/decisions/`,\n  `delivery/.chant/`, `delivery/chant.config.ts` or `chant.workspace.json`\n  (or the paths `chud.protectedPaths` in `delivery/chant.config.ts` adds)\n  from the app's page. This is enforced: an agent run's changes there are thrown\n  away, and a release refuses to plan while a commit that changes them lacks\n  the design app's `Chud-Author: design-app` trailer.\n- Never commit, tag or push. Committing, planning and shipping happen in the\n  design app, through the release Op and its gate.\n\n## Why a line is the way it is\n\nThe design app's commits for a unit of work carry trailers that tie the\ncommit to that unit: `Chud-Unit: W-NNN`, `Chud-Contract: C-NNN` (or\n`Chud-Driver: D-NNN` for a split) and one `Chud-Evidence: <sha256>` per\nevidence record the unit cites, beside `Chud-Author: design-app`.\n`decisions/decision.kind.mjs` exports `commitJoins`, which joins a commit\nto its unit from the work item whose `x-chud.result.commit` is the commit\n(chant 0.86's `list` on the hook's context), and from those trailers for the\nunit's other commits, so\n\n```sh\nchant workspace graph --intent app/server.js --json\n```\n\nlists the commits that touched the file (a `path:start-end` region narrows\nit to lines), each joined to the unit that made it (`work/W-NNN-<slug>.md`),\nthe contract it served and the evidence it cited, with the decisions whose\n`constrains` cover the file and what they pin, and the work items whose\nwindow a commit fell in (`worked`). Read it before changing code\na decision governs. The template pins chant 0.86, which has all of this.\nchant marks a commit inside a decision's window `decided-by-window`, and the\nkind adds `plugin:chud:contract-moved` for a unit commit whose contract's\ncriteria differ from those the first unit under that decision served: the\ncontract moved with no decision. Record a decision before you change what a\ncontract asks for.\n",
   "README.md": "# {{chant:name}}\n\nA chant workspace made from the studio kit's template\n([arugula-salad/studio](https://github.com/arugula-salad/studio) `template/`),\nwhich is chant's reference workspace with an app, a delivery project and\nrecords laid onto it. It started as chud's template (jhgaylor/chud 43afcf1)\nand moved into the kit when chud began to retire (arugula-salad/studio#37).\nThe app is built with hud in the page, and releases ship through chant Ops.\n\n```sh\nchant init --from <studio checkout>/template --param name=\"{{chant:name}}\" [--param issue=owner/repo#1] <dir>\nnode <studio checkout>/box/setup-app.mjs <dir>   # free ports, npm install in delivery/, git init, the first commit\ncd <dir>/app && npm run dev                      # the app, restarted on every change (node --watch)\n```\n\nA studio box does both steps in `box/provision-template.sh` and runs the\napp's `dev` script behind hud's proxy. No chud command runs.\n\n[`chant.workspace.json`](chant.workspace.json) declares the members, and\n`chant workspace ls` lists them. The release Op finds everything through them.\n\n| Member | Directory | Kind | What it is |\n|---|---|---|---|\n| app | [`app/`](app) | `other` | the product: a Node HTTP server with SQLite migrations and its own tests |\n| delivery | [`delivery/`](delivery) | `chant` | the chant project, which still runs on chud's runtime package (`@intentius/chud-runtime`) and the chud lexicon until they are split out of chud (INTENTIUS/chant#2713): the release, rollback, upgrade and dispatch Ops, the sites releases ship to, the agents that build the app, the decision points, the write-scope policy and this repo's CI |\n| design-client | [`design-client/`](design-client) | `other`, role `design-app` | a placeholder for a vendored design client (chant's reference workspace, #2524 D18) |\n| design | [`design/`](design) | `other` | the design data: chud's records (contracts, drivers, evidence, sessions, context, proposals), the screen specs, and the design app's overrides |\n\nThe root also holds [`decisions/`](decisions), the decision records. They\nare chant decision records, the format of chant's `docs/design/decisions/`\n(the kind file and schema are beside them): `ref-001` and `ref-002` from\nchant's reference workspace, `chud-001`, and the `chud-NNN` records the design\napp writes as the team decides. Each cites the issue this app's design is\ntracked in (`chud.decisions.issue` in `delivery/chant.config.ts`, the\ntemplate's optional `issue` parameter) as its source, or without one the\nsource of `chud-001`:\n\n```sh\nchant workspace records --kind decisions/decision.kind.mjs --current\n```\n\n[`work/`](work) holds the units of work: every agent run and piece of\nmanual work is a chant work item (`W-NNN-<slug>.md`, chant's work kind with\nchud's fields under `x-chud`), written by chud through `chant workspace\nrecords new` and `records amend`. Both kinds are declared in\n`chant.workspace.json` `records`:\n\n```sh\nchant workspace records --kind work/work.kind.mjs\n```\n\n`.chant/workspace.lock.json`, written by `chant init --from`, records the\ntemplate's lineage: where it came from, at which commit, and the parameters\nit was made with.\n\n## Everyday commands\n\nIn `delivery/`:\n\n```sh\nnpm run release      # chant run release --on chud: check, plan, stop at the ship gate\nchant approve release ship --plan <digest>\nnpm run release      # ship it\nnpm run rollback\nnpm run upgrade      # move to a newer @intentius/chud-runtime, through its gate\nnpm run check        # the app's tests and every approved contract's check (CI runs this)\nnpm run lint         # chant lint agents, with the contract-sizing rules\n```\n\nAt the root:\n\n```sh\nchant workspace check\nchant workspace build\nchant workspace lint\n```\n\n`CLAUDE.md` is the map for agents, and `design/CLAUDE.md` has the rules for\nthe records.\n",

package/src/workspace/agent-cli.ts

@@ -0,0 +1,138 @@
+/**
+ * `chant workspace agent [<name>] [--json]` (#2524 D20, #2548, ws-067): what
+ * an agent session reloads from, read from the repository alone.
+ *
+ * A session is declared in the declaration's `agents` list and bound to one
+ * member. This prints the session, its member, its write scope (the files
+ * and the record kinds, with their verbs, it may write) and the spec: the
+ * `spec` block `chant workspace records --current --json` prints (#2546). An
+ * agent that resumes needs nothing else: no memory of an earlier run, no
+ * state outside the checkout.
+ *
+ * The session and its scope come from the declaration at base, as the
+ * write paths and `check --changes` read them; the spec from the working
+ * tree, which is what the agent works on. Without a name, the session
+ * `CHANT_AGENT` names.
+ */
+
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, WRITE_VERBS, type WriteVerb } from "./declaration";
+import type { ReasonCode } from "./reason-codes";
+import { declaredKindFiles, queryDeclaredRecords, type SpecView } from "./records-cli";
+import { AGENT_ENV, resolveWriter, scopeOf, scopeSource, WriteScopeError } from "./write-scope";
+
+/** The version of the `agent` document this chant writes. */
+export const AGENT_CONTRACT_VERSION = 1;
+
+export const AGENT_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/agent/v1/agent.schema.json";
+
+/** Why the session can't be printed. Closed. */
+export const AGENT_ERROR_CODES = [...WORKSPACE_ERROR_CODES, "agent-unknown"] as const satisfies readonly ReasonCode[];
+export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[number];
+
+/** A record kind in the session's reach, with the verbs it may write it with. */
+export interface AgentKindScope {
+  /** The kind file from the workspace root, as the declaration names it. */
+  path: string;
+  /** The kind file's recordKind.name, or null when it can't be loaded. */
+  kind: string | null;
+  /** The name the declaration gives it, or null. */
+  name: string | null;
+  /** The member that declares it, or null for the workspace's own. */
+  member: string | null;
+  /** Empty when writeScope.agent.records leaves the kind out. */
+  verbs: WriteVerb[];
+}
+
+interface Head {
+  $schema: string;
+  contract: number;
+  chant: string;
+}
+
+export type AgentDocument =
+  | (Head & {
+      workspace: { name: string; root: string; scopeFrom: "base" | "working-tree" };
+      agent: { name: string; member: { name: string; dir: string; kind: string }; principals: string[] };
+      scope: {
+        /** The one member whose files the session writes. */
+        members: string[];
+        /** Every declared kind in reach: the workspace's own and the member's. */
+        records: AgentKindScope[];
+        /** The paths writeScope.agent.protected keeps the session from writing, with the JSON keys each still allows (#3146). */
+        protected: { path: string; except: string[] }[];
+      };
+      /** The spec, as records --current --json prints it. */
+      spec: SpecView;
+      /** The reads that rebuild the session's context. */
+      reload: string[];
+    })
+  | (Head & { error: { code: AgentErrorCode; message: string } });
+
+/** The session `name` names, as {@link AgentDocument} prints it. Never throws a read or scope error. */
+export async function agentSession(q: { cwd: string; name: string }): Promise<AgentDocument> {
+  const head: Head = { $schema: AGENT_OUTPUT_SCHEMA_ID, contract: AGENT_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    const source = scopeSource(q.cwd);
+    if (source.declaration === null || source.from === null) {
+      throw new WorkspaceReadError("declaration-missing", "no chant.workspace.json or .jsonc between this directory and the git root, so no agent session is declared");
+    }
+    const decl = source.declaration;
+    const writer = resolveWriter(decl, source.policy, { agent: q.name }, source.classes);
+    const agent = writer.agent!;
+    const member = decl.members.find((m) => m.name === agent.member)!;
+    const scope = scopeOf(decl, writer)!;
+    const rules = scope.records;
+    // The spec query, over every declared kind in the working tree.
+    const set = await queryDeclaredRecords(declaredKindFiles(q.cwd), { cwd: q.cwd, current: true });
+    const loadedName = new Map(set.kinds.map((k) => [k.declared.path, "error" in k ? null : k.kind.name]));
+    const records: AgentKindScope[] = [...decl.records, ...member.records].map((d) => {
+      const kind = loadedName.get(d.path) ?? null;
+      const names = [kind, d.name].filter((n): n is string => n !== null);
+      const verbs = rules === null ? [...WRITE_VERBS] : WRITE_VERBS.filter((v) => names.some((n) => (rules[n] ?? []).includes(v)));
+      return { path: d.path, kind, name: d.name, member: d.member, verbs };
+    });
+    return {
+      ...head,
+      workspace: { name: decl.name, root: source.root ?? ".", scopeFrom: source.from },
+      agent: { name: agent.name, member: { name: member.name, dir: member.dir, kind: member.kind }, principals: agent.principals },
+      scope: { members: [member.name], records, protected: scope.protected.map((p) => ({ path: p.path, except: [...p.except] })) },
+      spec: set.spec ?? { kinds: [], records: [] },
+      reload: [`chant workspace agent ${agent.name} --json`, "chant workspace records --current --json"],
+    };
+  } catch (err) {
+    if (err instanceof WorkspaceReadError || err instanceof WriteScopeError) {
+      return { ...head, error: { code: err.code as AgentErrorCode, message: err instanceof WorkspaceReadError ? err.describe() : err.message } };
+    }
+    throw err;
+  }
+}
+
+const USAGE = "chant workspace agent [<name>] [--json]";
+
+/** `chant workspace agent`: exit 0 when the session was printed, 1 otherwise. */
+export async function runWorkspaceAgent(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const name = args.extraPositional ?? (process.env[AGENT_ENV] || undefined);
+  if (!name) {
+    console.error(formatError({ message: `name the agent session, or set ${AGENT_ENV}`, hint: USAGE }));
+    return 1;
+  }
+  const doc = await agentSession({ cwd: process.cwd(), name });
+  if (args.json || args.format === "json") console.log(JSON.stringify(doc, null, 2));
+  if ("error" in doc) {
+    if (!args.json && args.format !== "json") console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    return 1;
+  }
+  if (args.json || args.format === "json") return 0;
+  const out: string[] = [];
+  out.push(`agent     ${doc.agent.name}, bound to member ${doc.agent.member.name} (${doc.agent.member.dir}), scope read from ${doc.workspace.scopeFrom}`);
+  for (const r of doc.scope.records) out.push(`records   ${r.name ?? r.kind ?? r.path} (${r.path}): ${r.verbs.length > 0 ? r.verbs.join(", ") : "not writable"}`);
+  for (const p of doc.scope.protected) out.push(`protected ${p.path}${p.except.length > 0 ? ` (except ${p.except.join(", ")})` : ""}`);
+  out.push(`spec      ${doc.spec.records.length} current records of ${doc.spec.kinds.length} spec kinds`);
+  for (const r of doc.spec.records) out.push(`          ${r.kind}/${r.id ?? "?"} ${r.state ?? ""} ${r.path}`);
+  out.push(`reload    ${doc.reload.join("; ")}`);
+  console.log(out.join("\n"));
+  return 0;
+}