@intentius/chant 0.102.0 → 0.104.0

package/src/__fixtures__/pr-loop/pr-apply-applied.note.golden.md

@@ -0,0 +1,31 @@
+<!-- chant-pr:prod -->
+### chant apply for `prod`
+
+Applied 2 members. Head `222222222222`, measured from `111111111111`.
+
+| Member | Component | Status | Create | Update | Replace | Delete |
+|---|---|---|---:|---:|---:|---:|
+| `a` | a | applied | 0 | 1 | 0 | 0 |
+| `app` | app | applied, inputs from a moved | 0 | 0 | 0 | 0 |
+
+A member whose inputs moved applied the plan it was approved with. The next run plans it against the new values.
+
+Plan digest: `jcs1-sha256:46bff52773a158dffa5c895b98f8760d601a2f9dc6af7dc235dbf65496f7bf65`
+
+Approved by `github:alice` for this digest.
+
+### Plan summary
+
+2 members: 2 groups, 0 destroys or replacements.
+
+#### Group e84467713bf6: 1 member (outlier), change
+
+```
+~ terraform_data.subnet: input
+```
+
+Members: `a`
+
+#### Group 49648f9475c7: 1 member (outlier), no changes
+
+Members: `app`

package/src/__fixtures__/pr-loop/pr-apply-refused.note.golden.md

@@ -0,0 +1,31 @@
+<!-- chant-pr:prod -->
+### chant apply for `prod`
+
+The apply refused. Head `222222222222`, measured from `111111111111`.
+
+> The plan changed after review, so nothing was applied. approved: jcs1-sha256:0000000000000000000000000000000000000000000000000000000000000063; planned now: jcs1-sha256:46bff52773a158dffa5c895b98f8760d601a2f9dc6af7dc235dbf65496f7bf65. Read the new plan, and if it is right, approve it: chant approve pr-12 pr-apply --plan jcs1-sha256:46bff52773a158dffa5c895b98f8760d601a2f9dc6af7dc235dbf65496f7bf65 --approver <you> --sign; then run the apply again.
+
+| Member | Component | Status | Create | Update | Replace | Delete |
+|---|---|---|---:|---:|---:|---:|
+| `a` | a | planned | 0 | 1 | 0 | 0 |
+| `app` | app | planned | 0 | 0 | 0 | 0 |
+
+Plan digest: `jcs1-sha256:46bff52773a158dffa5c895b98f8760d601a2f9dc6af7dc235dbf65496f7bf65`
+
+An approval stands for `jcs1-sha256:0000000000000000000000000000000000000000000000000000000000000063`, not for this digest: the plan changed since it was approved.
+
+### Plan summary
+
+2 members: 2 groups, 0 destroys or replacements.
+
+#### Group e84467713bf6: 1 member (outlier), change
+
+```
+~ terraform_data.subnet: input
+```
+
+Members: `a`
+
+#### Group 49648f9475c7: 1 member (outlier), no changes
+
+Members: `app`

package/src/__fixtures__/pr-loop/pr-plan.golden.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json",
+  "contract": 1,
+  "stage": "plan",
+  "pr": 12,
+  "env": "prod",
+  "base": "1111111111111111111111111111111111111111",
+  "head": "2222222222222222222222222222222222222222",
+  "op": "pr-12",
+  "gate": "pr-apply",
+  "digest": "jcs1-sha256:46bff52773a158dffa5c895b98f8760d601a2f9dc6af7dc235dbf65496f7bf65",
+  "status": "planned",
+  "approval": {
+    "status": "pending"
+  },
+  "selection": {
+    "changed": [
+      "a"
+    ],
+    "dependents": [
+      "app"
+    ],
+    "unclaimed": [],
+    "indeterminate": [],
+    "waves": [
+      [
+        "a"
+      ],
+      [
+        "app"
+      ]
+    ]
+  },
+  "members": [
+    {
+      "member": "a",
+      "component": "a",
+      "planDigest": "jcs1-sha256:0000000000000000000000000000000000000000000000000000000000000001",
+      "status": "planned",
+      "counts": {
+        "create": 0,
+        "update": 1,
+        "replace": 0,
+        "delete": 0
+      }
+    },
+    {
+      "member": "app",
+      "component": "app",
+      "planDigest": "jcs1-sha256:0000000000000000000000000000000000000000000000000000000000000002",
+      "status": "planned",
+      "counts": {
+        "create": 0,
+        "update": 0,
+        "replace": 0,
+        "delete": 0
+      }
+    }
+  ],
+  "changeSet": {
+    "$schema": "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json",
+    "contract": 1,
+    "digest": "jcs1-sha256:46bff52773a158dffa5c895b98f8760d601a2f9dc6af7dc235dbf65496f7bf65",
+    "members": [
+      {
+        "member": "a",
+        "lexicon": "terraform",
+        "planner": "tofu",
+        "status": "planned",
+        "planDigest": "jcs1-sha256:0000000000000000000000000000000000000000000000000000000000000001",
+        "holes": []
+      },
+      {
+        "member": "app",
+        "lexicon": "terraform",
+        "planner": "tofu",
+        "status": "planned",
+        "planDigest": "jcs1-sha256:0000000000000000000000000000000000000000000000000000000000000002",
+        "holes": []
+      }
+    ],
+    "entries": [
+      {
+        "member": "a",
+        "lexicon": "terraform",
+        "planner": "tofu",
+        "address": "terraform_data.subnet",
+        "type": "terraform_data",
+        "action": "update",
+        "attributes": [
+          {
+            "path": "input",
+            "before": "v1",
+            "after": "v2"
+          }
+        ]
+      }
+    ],
+    "summary": {
+      "members": 2,
+      "entries": 1,
+      "actions": {
+        "create": 0,
+        "update": 1,
+        "replace": 0,
+        "delete": 0,
+        "read": 0,
+        "no-op": 0,
+        "forget": 0
+      },
+      "types": {
+        "terraform_data": {
+          "update": 1
+        }
+      },
+      "byMember": {
+        "a": {
+          "update": 1
+        }
+      },
+      "deletes": [],
+      "replacements": [],
+      "failed": [],
+      "holes": 0
+    }
+  }
+}

package/src/__fixtures__/pr-loop/pr-plan.note.golden.md

@@ -0,0 +1,37 @@
+<!-- chant-pr:prod -->
+### chant plan for `prod`
+
+Planned 2 members. Head `222222222222`, measured from `111111111111`.
+
+| Member | Component | Status | Create | Update | Replace | Delete |
+|---|---|---|---:|---:|---:|---:|
+| `a` | a | planned | 0 | 1 | 0 | 0 |
+| `app` | app | planned | 0 | 0 | 0 | 0 |
+
+Plan digest: `jcs1-sha256:46bff52773a158dffa5c895b98f8760d601a2f9dc6af7dc235dbf65496f7bf65`
+
+Not approved yet.
+
+A reviewer who approved this pull request approves the plan with:
+
+```
+chant approve pr-12 pr-apply --plan jcs1-sha256:46bff52773a158dffa5c895b98f8760d601a2f9dc6af7dc235dbf65496f7bf65 --approver github:<your-login> --sign
+```
+
+It applies on merge if the plan is still this one. If it moved, the apply refuses and names both digests.
+
+### Plan summary
+
+2 members: 2 groups, 0 destroys or replacements.
+
+#### Group e84467713bf6: 1 member (outlier), change
+
+```
+~ terraform_data.subnet: input
+```
+
+Members: `a`
+
+#### Group 49648f9475c7: 1 member (outlier), no changes
+
+Members: `app`

package/src/audit/core.test.ts

@@ -128,6 +128,21 @@ describe("auditFiles", () => {
     expect(findings.map((f) => f.file).sort()).toEqual(["a.yml", "b.yml"]);
   });
 
+  test("skips an auditOptIn check unless enabledRules names it (#3190)", async () => {
+    const optIn: PostSynthCheck = {
+      id: "OPT001",
+      description: "opt-in",
+      auditOptIn: true,
+      check: () => [{ checkId: "OPT001", severity: "warning", message: "hit" }],
+    };
+    const input = [{ path: "a.yml", content: "x", lexicon: "github" }];
+    const run = (enabledRules?: ReadonlySet<string>) =>
+      auditFiles(input, { checksProvider: async () => [optIn], enabledRules });
+    expect(await run()).toEqual([]);
+    expect(await run(new Set(["OTHER"]))).toEqual([]);
+    expect((await run(new Set(["OPT001"]))).map((f) => f.checkId)).toEqual(["OPT001"]);
+  });
+
   test("accepts a lexicon name outside the built-in set (open AuditLexicon)", async () => {
     const fake: PostSynthCheck = {
       id: "CUSTOM001",

package/src/audit/core.ts

@@ -231,7 +231,13 @@ export interface SuppressionStats {
  */
 export async function auditFiles(
   inputs: AuditInput[],
-  opts: { checksProvider?: ChecksProvider; entitiesProvider?: EntitiesProvider; suppressionStats?: SuppressionStats } = {},
+  opts: {
+    checksProvider?: ChecksProvider;
+    entitiesProvider?: EntitiesProvider;
+    suppressionStats?: SuppressionStats;
+    /** Check ids the project enabled with `lint.rules`; a check marked `auditOptIn` runs only when listed here (#3190). */
+    enabledRules?: ReadonlySet<string>;
+  } = {},
 ): Promise<AuditFinding[]> {
   const provider = opts.checksProvider ?? defaultChecksProvider;
   const entitiesProvider = opts.entitiesProvider ?? defaultEntitiesProvider;
@@ -246,7 +252,7 @@ export async function auditFiles(
   }
 
   for (const [lexicon, files] of byLexicon) {
-    const checks = await provider(lexicon);
+    const checks = (await provider(lexicon)).filter((c) => !c.auditOptIn || opts.enabledRules?.has(c.id));
     if (checks.length === 0) continue;
     const parseEntities = await entitiesProvider(lexicon);
     findings.push(...(await auditLexicon(lexicon, files, checks, parseEntities, opts.suppressionStats)));

package/src/audit/discover.test.ts

@@ -126,6 +126,17 @@ describe("discoverByDetection (unified, detectTemplate-driven)", () => {
       expect(found.some((i) => i.path.includes(".terraform"))).toBe(false);
     });
 
+    test("terragrunt.hcl and root.hcl join the terraform bundle, and a unit's source path does not make a module of its target (#3417)", () => {
+      const files = [
+        { path: "live/app/terragrunt.hcl", content: 'terraform {\n  source = "../../modules/app"\n}\n' },
+        { path: "root.hcl", content: "remote_state {\n}\n" },
+        { path: "modules/app/main.tf", content: 'resource "x" "y" {}\n' },
+      ];
+      const found = classifyFiles(files, [terraform], { baseDir: "/repo" });
+      expect(targets(found)).toEqual(["terraform:.", "terraform:live/app", "terraform:modules/app"]);
+      expect(found.find((i) => i.path === "live/app")!.content).toContain("# file: terragrunt.hcl");
+    });
+
     test("without the terraform plugin, .tf files are classified into nothing (skipped, same as an unloaded helm)", () => {
       const found = discoverByDetection(fixture("audit-terraform"), []);
       expect(found).toEqual([]);

package/src/audit/discover.ts

@@ -151,7 +151,9 @@ function isDockerfileName(name: string): boolean {
 }
 
 function isTerraformFileName(name: string): boolean {
-  return /\.tf$/i.test(name);
+  // `terragrunt.hcl` and `root.hcl` ride in the terraform bundle (#3417): the
+  // terraform lexicon reads them into Terragrunt entities, apart from modules.
+  return /\.tf$/i.test(name) || name === "terragrunt.hcl" || name === "root.hcl";
 }
 
 /**
@@ -470,7 +472,10 @@ function calledAsLocalModule(byDir: Map<string, Record<string, string>>): Set<st
   const called = new Set<string>();
   for (const [dir, bundle] of byDir) {
     const targets = new Set<string>();
-    for (const source of Object.values(bundle)) {
+    for (const [name, source] of Object.entries(bundle)) {
+      // A Terragrunt unit's `terraform { source = "../modules/x" }` is not a
+      // `module` call: the directory it names stays a root of its own (#3417).
+      if (name === "terragrunt.hcl" || name === "root.hcl") continue;
       for (const match of source.matchAll(LOCAL_MODULE_SOURCE)) {
         const target = resolveRepoDir(dir, match[1]);
         if (target === undefined || target === dir || !byDir.has(target)) continue;

package/src/change-set-bundle.test.ts

@@ -0,0 +1,57 @@
+/**
+ * The change-set modules bundle small (#3181, ruling #3421).
+ *
+ * terragucci runs its stages in customer CI as one bundled file with no
+ * TypeScript toolchain. So `@intentius/chant/change-set`, the grouped plan
+ * summary at `@intentius/chant/plan-summary` (#3188) and the terraform
+ * lexicon's `change-set` subpath must not reach `typescript`, esbuild, zod or
+ * chant's fold, lint and codegen modules. This bundles the three entry points
+ * the way terragucci would and reads esbuild's own list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+/** What the three bundles may hold together at most. They are about 40 KB today (9 KB change-set, 21 KB plan-summary, 10 KB terraform). */
+const BUDGET_BYTES = 64 * 1024;
+
+const FORBIDDEN = [/node_modules\/typescript\//, /node_modules\/esbuild\//, /node_modules\/zod\//, /\/src\/fold\//, /\/src\/lint\//, /\/src\/codegen\//];
+
+describe("the change-set bundle", () => {
+  test("holds the document, the adapters, the summary and the digest, and nothing heavier", async () => {
+    const result = await build({
+      entryPoints: [
+        join(REPO, "packages", "core", "src", "change-set.ts"),
+        join(REPO, "packages", "core", "src", "plan-summary.ts"),
+        join(REPO, "lexicons", "terraform", "src", "change-set.ts"),
+      ],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    for (const pattern of FORBIDDEN) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    // The whole graph: the three entry points, the terraform plan digest, and core's digest code.
+    expect(inputs.map((i) => i.replace(/^.*?(packages|lexicons)\//, "$1/")).sort()).toEqual([
+      "lexicons/terraform/src/change-set.ts",
+      "lexicons/terraform/src/plan-digest.ts",
+      "packages/core/src/change-set.ts",
+      "packages/core/src/content-digest.ts",
+      "packages/core/src/declarable.ts",
+      "packages/core/src/effect-receipt.ts",
+      "packages/core/src/intrinsic.ts",
+      "packages/core/src/lifecycle/plan-digest.ts",
+      "packages/core/src/plan-summary.ts",
+    ]);
+    const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+    expect(bytes).toBeLessThan(BUDGET_BYTES);
+  });
+});

package/src/change-set.test.ts

@@ -0,0 +1,215 @@
+/**
+ * The change-set document (#3181): its schema, the lifecycle and reconcile
+ * adapters, and the digest.
+ *
+ * `__fixtures__/change-set/lifecycle-plan.floci.json` is real `chant
+ * lifecycle plan dev --owned --json` output: `lifecycle-v1.ts.txt` deployed as
+ * CloudFormation stack `dev` to floci 1.5.34 and snapshotted, then
+ * `lifecycle-v2.ts.txt` planned. It has a create and no-ops; the aws lexicon
+ * reads stack resources, so out-of-band drift does not reach it as an
+ * update. The update, delete, effect and hole mappings are pinned on typed
+ * entries below.
+ *
+ * `warden.plan.json` is the reconcile change set chant's own
+ * `diffCollection` produces for a warden's teams cycle: one create, one
+ * update and one owned delete. github-warden prints its plan as text today,
+ * so this is the shape it would write.
+ *
+ * Goldens regenerate with `UPDATE_GOLDEN=1`.
+ */
+
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  CHANGE_SET_SCHEMA_ID,
+  changeSetDigest,
+  composeChangeSet,
+  lifecyclePlanPart,
+  reconcilePlanPart,
+  verifyChangeSetDigest,
+  type ChangeSetPart,
+} from "./change-set";
+import { computePlanDigest } from "./lifecycle/plan-digest";
+import type { ChangeSet as LifecycleChangeSet } from "./lifecycle/change-set";
+import { diffCollection, diffFields, type ChangeSet as ReconcileChangeSet, type ChangeSetEntry as ReconcileEntry } from "./reconcile";
+import { contract, REPO, validSchema } from "./workspace/__fixtures__/contract-repo";
+import schema from "./workspace/change-set.schema.json";
+
+const DIR = join(import.meta.dirname, "__fixtures__", "change-set");
+const TF_DIR = join(REPO, "lexicons", "terraform", "src", "__fixtures__", "change-set");
+const read = (dir: string, name: string): unknown => JSON.parse(readFileSync(join(dir, name), "utf-8"));
+
+function golden(name: string, value: unknown): void {
+  const path = join(DIR, name);
+  const text = JSON.stringify(value, null, 2) + "\n";
+  if (process.env.UPDATE_GOLDEN) writeFileSync(path, text);
+  expect(text).toBe(readFileSync(path, "utf-8"));
+}
+
+const { expectValid, validate } = contract(schema);
+
+/** A warden's teams cycle, planned by the reconcile primitives it is built on. */
+function wardenPlan(): ReconcileChangeSet {
+  type Team = { privacy: string; description: string };
+  const desired = new Map<string, Team>([
+    ["platform", { privacy: "closed", description: "Platform team" }],
+    ["release", { privacy: "secret", description: "Release managers" }],
+  ]);
+  const live = new Map<string, Team>([
+    ["platform", { privacy: "secret", description: "Platform team" }],
+    ["contractors", { privacy: "closed", description: "Old contractors" }],
+  ]);
+  const entries: ReconcileEntry[] = [];
+  diffCollection({
+    resourceType: "team",
+    desired,
+    live,
+    compareFields: (d, l) => diffFields(d, l),
+    opts: { isOwned: () => true },
+    out: entries,
+  });
+  return { org: "acme", entries, managedCount: live.size };
+}
+
+describe("the change-set schema", () => {
+  test("is a valid draft 2020-12 document at the read contract's version", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(CHANGE_SET_SCHEMA_ID);
+    expect(schema.properties.contract).toEqual({ const: 1 });
+  });
+
+  test("every golden document in both fixture directories validates", () => {
+    const docs = [
+      ...readdirSync(DIR).filter((f) => f.endsWith(".change-set.golden.json")).map((f) => read(DIR, f)),
+      ...readdirSync(TF_DIR).filter((f) => f.endsWith(".change-set.golden.json")).map((f) => read(TF_DIR, f)),
+      ...readdirSync(TF_DIR).filter((f) => f.endsWith(".part.golden.json")).map((f) => composeChangeSet([read(TF_DIR, f) as ChangeSetPart])),
+    ];
+    expect(docs.length).toBeGreaterThanOrEqual(5);
+    for (const doc of docs) expectValid(doc);
+  });
+
+  test("refuses an unknown action, a missing digest and a malformed plan digest", () => {
+    const doc = composeChangeSet([lifecyclePlanPart({ member: "delivery", plan: read(DIR, "lifecycle-plan.floci.json") as LifecycleChangeSet })]);
+    expect(validate({ ...doc, entries: [{ ...doc.entries[0], action: "teleport" }] })).toBe(false);
+    const { digest: _d, ...noDigest } = doc;
+    expect(validate(noDigest)).toBe(false);
+    expect(validate({ ...doc, members: [{ ...doc.members[0], planDigest: "sha256:abc" }] })).toBe(false);
+  });
+});
+
+describe("lifecyclePlanPart", () => {
+  test("a real lifecycle plan against floci matches its golden", () => {
+    const plan = read(DIR, "lifecycle-plan.floci.json") as LifecycleChangeSet;
+    const part = lifecyclePlanPart({ member: "delivery", plan });
+    expect(part.member.planDigest).toBe(computePlanDigest("lifecycle-plan", plan));
+    expect(part.entries.map((e) => [e.address, e.action])).toEqual([
+      ["alerts", "no-op"], ["dlq", "create"], ["events", "no-op"], ["jobs", "no-op"],
+    ]);
+    golden("lifecycle.change-set.golden.json", composeChangeSet([part]));
+  });
+
+  test("update, replace, delete, effect, holes, and what is left out", () => {
+    const plan: LifecycleChangeSet = {
+      env: "prod",
+      entries: [
+        { name: "web", type: "Deployment", lexicon: "k8s", action: "update", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned", deltas: [{ path: "replicas", oldValue: 2, newValue: 3 }], disruption: "rolling" },
+        { name: "db", type: "AWS::RDS::DBInstance", lexicon: "aws", action: "update", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned", deltas: [{ path: "Engine", oldValue: "mysql", newValue: "postgres" }], disruption: "destroy", disruptionBecause: ["Engine"] },
+        { name: "old", type: "AWS::SQS::Queue", lexicon: "aws", action: "delete", evidence: { declared: false, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
+        { name: "notify-receipt", type: "Receipt", lexicon: "aws", action: "effect", effect: "notify", effectReason: "receipt-absent", evidence: { declared: true, inSnapshot: false, live: false, observed: true }, ownership: "owned" },
+        { name: "cache", type: "AWS::ElastiCache::CacheCluster", lexicon: "aws", action: "unobserved", unobservedReason: "read-failed", evidence: { declared: true, inSnapshot: false, live: false, observed: false }, ownership: "unknown" },
+        { name: "stray", lexicon: "aws", action: "adopt", evidence: { declared: false, inSnapshot: false, live: true, observed: true }, ownership: "unknown" },
+        { name: "web-abc12", lexicon: "k8s", action: "runtime", runtimeOwner: "web", evidence: { declared: false, inSnapshot: false, live: true, observed: true }, ownership: "unknown" },
+      ],
+    };
+    const { member, entries } = lifecyclePlanPart({ member: "delivery", plan });
+    expect(entries.map((e) => [e.address, e.action, e.disruption ?? null])).toEqual([
+      ["web", "update", "rolling"],
+      ["db", "replace", "destroy"],
+      ["old", "delete", "destroy"],
+      ["notify-receipt", "create", null],
+    ]);
+    expect(entries[1].attributes).toEqual([{ path: "Engine", before: "mysql", after: "postgres", forcesReplacement: true }]);
+    expect(member.holes).toEqual([{ address: "cache", type: "AWS::ElastiCache::CacheCluster", reason: "read-failed" }]);
+    expect(member.lexicon).toBe("chant");
+    const doc = composeChangeSet([{ member, entries }]);
+    expectValid(doc);
+    expect(doc.summary.holes).toBe(1);
+    expect(doc.summary.replacements).toEqual([{ member: "delivery", address: "db", type: "AWS::RDS::DBInstance", disruption: "destroy" }]);
+  });
+});
+
+describe("reconcilePlanPart", () => {
+  test("a warden's teams cycle, as chant's reconcile primitives plan it", () => {
+    const plan = wardenPlan();
+    golden("warden.plan.json", plan);
+    const part = reconcilePlanPart({ member: "warden", plan: read(DIR, "warden.plan.json") as ReconcileChangeSet });
+    expect(part.entries.map((e) => [e.address, e.action, e.disruption ?? null])).toEqual([
+      ["team.contractors", "delete", "destroy"],
+      ["team.platform", "update", "unknown"],
+      ["team.release", "create", null],
+    ]);
+    expect(part.entries[1].attributes).toEqual([{ path: "privacy", before: "secret", after: "closed" }]);
+    golden("warden.change-set.golden.json", composeChangeSet([part]));
+  });
+
+  test("the plan digest ignores the managed counts and the order of change sets", () => {
+    const a = wardenPlan();
+    const b: ReconcileChangeSet = { org: "beta", entries: [] };
+    const one = reconcilePlanPart({ member: "w", plan: [a, b] }).member.planDigest;
+    expect(reconcilePlanPart({ member: "w", plan: [b, { ...a, managedCount: 99 }] }).member.planDigest).toBe(one);
+    expect(reconcilePlanPart({ member: "w", plan: [b, { ...a, entries: a.entries.slice(1) }] }).member.planDigest).not.toBe(one);
+  });
+});
+
+describe("the digest", () => {
+  const lifecycle = () => lifecyclePlanPart({ member: "delivery", plan: read(DIR, "lifecycle-plan.floci.json") as LifecycleChangeSet });
+  const warden = () => reconcilePlanPart({ member: "warden", plan: wardenPlan() });
+  const tofu = () => read(TF_DIR, "tofu.part.golden.json") as ChangeSetPart;
+
+  test("is the set digest over { member, planDigest }, whatever order the parts come in", () => {
+    const doc = composeChangeSet([lifecycle(), warden(), tofu()]);
+    expect(composeChangeSet([tofu(), warden(), lifecycle()])).toEqual(doc);
+    const pairs = doc.members.map((m) => ({ member: m.member, planDigest: m.planDigest }));
+    expect(doc.digest).toBe(computePlanDigest("change-set", pairs));
+    expect(doc.digest).toMatch(/^jcs1-sha256:[0-9a-f]{64}$/);
+    expect(verifyChangeSetDigest(doc)).toBe(true);
+    expect(verifyChangeSetDigest({ ...doc, digest: changeSetDigest(doc.members.slice(1)) })).toBe(false);
+  });
+
+  test("moves when one member's plan moves, and only then", () => {
+    const base = composeChangeSet([lifecycle(), warden()]).digest;
+    expect(composeChangeSet([lifecycle(), warden()], { chant: "9.9.9" }).digest).toBe(base);
+    const moved = wardenPlan();
+    moved.entries[0] = { ...moved.entries[0], after: { privacy: "closed", description: "Release engineers" } };
+    expect(composeChangeSet([lifecycle(), reconcilePlanPart({ member: "warden", plan: moved })]).digest).not.toBe(base);
+    // A wave is a subset of members: its digest is the same function over them.
+    expect(changeSetDigest([lifecycle().member])).toBe(composeChangeSet([lifecycle()]).digest);
+  });
+
+  test("leaves provisional members out, so approving the document never covers them", () => {
+    const provisional = tofu();
+    provisional.member = { ...provisional.member, provisional: true };
+    const doc = composeChangeSet([lifecycle(), warden(), provisional]);
+    expect(doc.members.find((m) => m.provisional)?.member).toBe(provisional.member.member);
+    expect(doc.digest).toBe(composeChangeSet([lifecycle(), warden()]).digest);
+    expect(verifyChangeSetDigest(doc)).toBe(true);
+    expectValid(doc);
+  });
+
+  test("refuses two parts for one member, and an entry naming another member", () => {
+    expect(() => composeChangeSet([warden(), warden()])).toThrow(/names member warden twice/);
+    const stray = warden();
+    stray.entries[0] = { ...stray.entries[0], member: "other" };
+    expect(() => composeChangeSet([stray])).toThrow(/names member other, inside member warden/);
+  });
+
+  test("the summary counts per action, type and member, and names every delete and replacement", () => {
+    const doc = composeChangeSet([lifecycle(), warden(), tofu()]);
+    expect(doc.summary.actions).toEqual({ create: 4, update: 3, replace: 1, delete: 2, read: 0, "no-op": 4, forget: 0 });
+    expect(doc.summary.byMember.warden).toEqual({ create: 1, update: 1, delete: 1 });
+    expect(doc.summary.types.terraform_data).toEqual({ create: 2, update: 2, replace: 1, delete: 1, "no-op": 1 });
+    expect(doc.summary.deletes.map((d) => `${d.member}:${d.address}`)).toEqual(["estate:terraform_data.old", "warden:team.contractors"]);
+    expect(doc.summary.replacements.map((d) => `${d.member}:${d.address}`)).toEqual(["estate:terraform_data.worker"]);
+  });
+});