@intentius/chant 0.105.0 → 0.106.1

package/src/components/fan-out-record.ts

@@ -30,6 +30,29 @@
 import { dirname } from "node:path";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { readWaveRecords, type WaveRecord } from "../gated-waves";
+import type { ChangeSetDocument } from "../change-set";
+import type { PrMember } from "../pr-loop";
+
+/** What a pull request's apply approved, kept so a re-run can finish it (#3464). */
+export interface PrApplyRecord {
+  /** The gate's op and name: `pr-<n>` and `pr-apply` unless the pipeline names another. */
+  op: string;
+  gate: string;
+  /** The commit the apply ran on. A record from another commit does not carry. */
+  head: string;
+  /** The change-set digest the approval stands for. */
+  digest: string;
+  approvedBy: string[];
+  /** Every member of the approved set, as planned. */
+  members: PrMember[];
+  /** The approved change-set document. Its entries are what a re-planned member is checked against. */
+  changeSet: ChangeSetDocument;
+  /**
+   * The outputs the approved plans read. The members left are planned
+   * against them again, so an unchanged member plans to the same digest.
+   */
+  planOutputs: Record<string, Record<string, unknown>>;
+}
 
 export interface FanOutAttempt {
   digest: string;
@@ -44,11 +67,39 @@ export interface FanOutAttempt {
    * root, choudoufu's wave resume file.
    */
   carried?: Record<string, unknown>;
+  /** A pull request's apply only (#3464). */
+  prApply?: PrApplyRecord;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
 
+const isStringArray = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((v) => typeof v === "string");
+
+/** The `prApply` entry, when it has every field a resume needs. Anything else reads as no entry. */
+function readPrApplyRecord(value: unknown): PrApplyRecord | undefined {
+  if (!isRecord(value)) return undefined;
+  const { op, gate, head, digest, approvedBy, members, changeSet, planOutputs } = value;
+  if (typeof op !== "string" || typeof gate !== "string" || typeof head !== "string" || typeof digest !== "string") return undefined;
+  if (!isStringArray(approvedBy) || !Array.isArray(members) || !members.every(isRecord)) return undefined;
+  if (!isRecord(changeSet) || changeSet.digest !== digest || !Array.isArray(changeSet.members) || !Array.isArray(changeSet.entries)) return undefined;
+  const outputs: Record<string, Record<string, unknown>> = {};
+  if (isRecord(planOutputs)) {
+    for (const [name, v] of Object.entries(planOutputs)) if (isRecord(v)) outputs[name] = v;
+  }
+  return {
+    op,
+    gate,
+    head,
+    digest,
+    approvedBy,
+    members: members as unknown as PrMember[],
+    changeSet: changeSet as unknown as ChangeSetDocument,
+    planOutputs: outputs,
+  };
+}
+
 /** Read an attempt record, or `undefined` when there is none yet. Throws on a file that is not JSON. */
 export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
   if (!existsSync(path)) return undefined;
@@ -58,6 +109,7 @@ export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
     for (const [name, value] of Object.entries(parsed.outputs)) if (isRecord(value)) outputs[name] = value;
   }
   const waves = readWaveRecords(parsed.waves);
+  const prApply = readPrApplyRecord(parsed.prApply);
   return {
     digest: typeof parsed.digest === "string" ? parsed.digest : "",
     completed: Array.isArray(parsed.completed) ? parsed.completed.filter((n): n is string => typeof n === "string") : [],
@@ -65,6 +117,7 @@ export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
     outputs,
     ...(waves.length > 0 ? { waves } : {}),
     ...(isRecord(parsed.carried) && Object.keys(parsed.carried).length > 0 ? { carried: parsed.carried } : {}),
+    ...(prApply ? { prApply } : {}),
   };
 }
 

package/src/components/pr-pipeline.ts

@@ -17,9 +17,23 @@
  *   to `chant/lifecycle`, to record the pending fact when the gate stops it.
  *   One apply runs at a time per environment.
  *
+ * The apply job passes `--resume` (#3543) with a record path outside the
+ * report directory, and each forge keeps that file in its CI cache under a
+ * key that names the environment, the member and the pushed commit
+ * (`prApplyRecordKey`). A re-run of a failed apply job restores it and
+ * finishes the approved set under the same approval; the record itself is
+ * checked against the pull request's gate, the commit, the selection and
+ * the ledger before it counts (`pr-apply --resume`, #3464).
+ *
  * Measuring the push from the commit it replaced works for merge commits,
  * squash merges and rebase merges alike, and every job measures from the
  * merge base of that commit and its own head (`resolveMergeBase`).
+ *
+ * In a workspace member (#3465) both commands run in the member's directory
+ * and pass `--member <name>`, so the member's gate (`pr-<number>-<member>`),
+ * note and statuses stay apart from every other member's on the same pull
+ * request. They still measure the whole change: a file outside the member
+ * that one of its units reaches selects that unit.
  */
 
 import type { ForgeKind } from "../pr-forge";
@@ -28,6 +42,31 @@ import { PR_APPLY_GATE } from "../pr-loop";
 /** Where both jobs write their reports, kept as a CI artifact. */
 export const PR_LOOP_REPORT_DIR = ".chant/pr";
 
+/**
+ * The attempt record the apply job resumes from (#3543), relative to the
+ * directory the job runs in. It sits outside `PR_LOOP_REPORT_DIR`, so the
+ * report artifact never carries it: it holds the outputs the members read.
+ */
+export const PR_APPLY_RECORD = ".chant/pr-resume/pr-apply.json";
+
+/**
+ * The image the pull-request pipeline runs in when the caller sets none. The
+ * full `node` image has git, which both jobs measure the change with;
+ * `PR_LOOP_SETUP` adds OpenTofu on top of it. A caller who sets `image`
+ * brings both and gets no setup lines.
+ */
+export const PR_LOOP_IMAGE = "node:22";
+
+/** Installs OpenTofu into `PR_LOOP_IMAGE`. */
+export const PR_LOOP_SETUP = [
+  "command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)",
+];
+
+/** The setup lines for a pipeline running in `image`: the install when it is the default image, none otherwise. */
+export function prLoopSetup(image: string): string[] {
+  return image === PR_LOOP_IMAGE ? PR_LOOP_SETUP : [];
+}
+
 /** The `prLoop` generator option (`ComponentPipelineOptions.prLoop`). */
 export interface PrLoopPipelineOptions {
   /** The gate the apply waits on. Default `pr-apply`. */
@@ -58,12 +97,21 @@ export interface PrLoopJob {
    * variables on GitLab.
    */
   env: Record<string, string>;
+  /** Shell lines to run before the command, to settle values the forge may leave unusable. */
+  setup?: string[];
 }
 
-/** The two jobs for `forge`. */
-export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelineOptions = {}): PrLoopJob[] {
+/**
+ * The two jobs for `forge`. `member` is the workspace member the pipeline is
+ * generated for; the commands then run in its directory, so `--output` is
+ * relative to it.
+ */
+export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelineOptions = {}, member?: string): PrLoopJob[] {
   const gate = options.gate ?? PR_APPLY_GATE;
-  const common = ["--env", env, "--gate", gate, "--output", PR_LOOP_REPORT_DIR, "--forge", forge];
+  const common = [
+    "--env", env, "--gate", gate, "--output", PR_LOOP_REPORT_DIR, "--forge", forge,
+    ...(member ? ["--member", member] : []),
+  ];
   const github = forge !== "gitlab";
   const token: Record<string, string> = github ? { GITHUB_TOKEN: "${{ github.token }}" } : {};
   return [
@@ -79,13 +127,48 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
       command: [
         "chant", "components", "pr-apply", "--base", '"$BASE_SHA"', ...common,
         ...(options.requireReview === false ? [] : ["--require-review"]),
+        "--resume", PR_APPLY_RECORD,
       ].join(" "),
       env: github ? { BASE_SHA: "${{ github.event.before }}", ...token } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA" },
+      ...(github ? {} : { setup: [gitlabBaseFallback(options.branch)] }),
     },
   ];
 }
 
-/** The concurrency group (GitHub, Forgejo) or resource group (GitLab) that keeps one apply at a time per environment. */
-export function prApplyGroup(env: string): string {
-  return `chant-apply-${env}`;
+/**
+ * The concurrency group (GitHub, Forgejo) or resource group (GitLab) that
+ * keeps one apply at a time per environment, and per member in a workspace.
+ */
+export function prApplyGroup(env: string, member?: string): string {
+  return member ? `chant-apply-${member}-${env}` : `chant-apply-${env}`;
+}
+
+/**
+ * The cache key the apply job keeps its attempt record under (#3543), with
+ * `commit` the forge's expression for the pushed commit. A push of another
+ * commit never restores a record, and the environment and member keep each
+ * pipeline's record apart. The pull request and the gate digest are not in
+ * the key, since neither is known before the job runs; `pr-apply --resume`
+ * refuses a record made for another pull request, gate or digest.
+ */
+export function prApplyRecordKey(env: string, commit: string, member?: string): string {
+  return `${prApplyGroup(env, member)}-${commit}`;
+}
+
+/**
+ * GitLab sets `CI_COMMIT_BEFORE_SHA` to forty zeros on a branch's first push.
+ * The line replaces it with the merge request's diff base when the pipeline
+ * has one, and otherwise with the merge base of the target branch and the
+ * pushed commit, or the pushed commit's parent when that is the commit itself.
+ */
+export function gitlabBaseFallback(branch?: string): string {
+  const target = branch ? JSON.stringify(branch) : "$CI_DEFAULT_BRANCH";
+  return (
+    'if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then ' +
+    'BASE_SHA="${CI_MERGE_REQUEST_DIFF_BASE_SHA:-}"; ' +
+    'if [ -z "$BASE_SHA" ]; then ' +
+    `git fetch origin ${target} && BASE_SHA="$(git merge-base FETCH_HEAD "$CI_COMMIT_SHA")"; ` +
+    'if [ "$BASE_SHA" = "$CI_COMMIT_SHA" ]; then BASE_SHA="$(git rev-parse "$CI_COMMIT_SHA^")"; fi; ' +
+    "fi; fi; export BASE_SHA"
+  );
 }

package/src/components/pr-run.test.ts

@@ -12,8 +12,21 @@ import { describe, expect, test } from "vitest";
 import { CapabilityRegistry, type DeployContext } from "./capability";
 import { memoryGateLedgerPort } from "../op/gate";
 import { planFanOut } from "./fan-out";
-import { applyPrSet, approvalOf, approversWithoutReview, decidePrGate, planPrSet, readOnlyLedger } from "./pr-run";
-import { changeSetDigest } from "../change-set";
+import {
+  applyPrSet,
+  approvalOf,
+  approversWithoutReview,
+  decidePrGate,
+  planCoveredBy,
+  planPrSet,
+  prReport,
+  readOnlyLedger,
+  resumePrSet,
+  type PrPlanSet,
+} from "./pr-run";
+import { changeSetDigest, composeChangeSet, type ChangeSetEntry, type ChangeSetPart } from "../change-set";
+import type { PrApplyRecord } from "./fan-out-record";
+import type { FanOutPlan } from "./fan-out";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { DriverComponent } from "./driver";
 
@@ -66,7 +79,17 @@ function world() {
         changeSet: {
           member: { member: input.root, lexicon: "terraform", planner: "tofu", status: "planned", planDigest, holes: [] },
           entries: changes
-            ? [{ member: input.root, lexicon: "terraform", planner: "tofu", address: "terraform_data.x", type: "terraform_data", action: "update", attributes: [] }]
+            ? [
+                {
+                  member: input.root,
+                  lexicon: "terraform",
+                  planner: "tofu",
+                  address: "terraform_data.x",
+                  type: "terraform_data",
+                  action: "update",
+                  attributes: [{ path: "version", before: "v1", after: w.versions[input.root] }],
+                },
+              ]
             : [],
         },
       };
@@ -203,3 +226,277 @@ describe("applyPrSet", () => {
     expect(members.find((m) => m.member === "a")?.error).toBe("a failed");
   });
 });
+
+/** The record a first attempt leaves (`pr-apply --resume`), from the set it applied. */
+function recordOf(set: PrPlanSet, approvedBy = "github:alice"): PrApplyRecord {
+  return {
+    op: "pr-12",
+    gate: "pr-apply",
+    head: "2".repeat(40),
+    digest: set.doc.digest,
+    approvedBy: [approvedBy],
+    members: set.members,
+    changeSet: set.doc,
+    planOutputs: set.outputs,
+  };
+}
+
+/** Plan and apply once, with `failing` failing to apply. */
+async function firstAttempt(w: ReturnType<typeof world>, plan: FanOutPlan, failing: string[]) {
+  for (const f of failing) w.failing.add(f);
+  const set = await planPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod" });
+  const first = await applyPrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", set });
+  for (const f of failing) w.failing.delete(f);
+  return { set, first, record: recordOf(set) };
+}
+
+describe("resuming an apply that failed partway (#3464)", () => {
+  test("plans and applies only what did not apply, and the set keeps the approved digest", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net", "dns"] });
+    const { set, first, record } = await firstAttempt(w, plan, ["a"]);
+    expect(first.status).toBe("failed");
+    expect(first.run.completed).toEqual(["b", "dns", "net"]);
+
+    w.planned.length = 0;
+    w.applied.length = 0;
+    const resumed = await resumePrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", record, completed: first.run.completed });
+    if (!resumed.ok) throw new Error(resumed.reasons.join("; "));
+
+    expect(resumed.plan.order).toEqual(["a", "app"]);
+    // Planned against the outputs the approved plans read, so each member plans as it did.
+    expect(w.planned).toEqual([
+      { root: "a", vars: { cidr: "10.0.0.0/16" } },
+      { root: "app", vars: { subnet: "a-v1" } },
+    ]);
+    expect(resumed.set.doc.digest).toBe(set.doc.digest);
+    expect(resumed.fresh.members.map((m) => m.planDigest)).toEqual(
+      set.members.filter((m) => m.member === "a" || m.member === "app").map((m) => m.planDigest),
+    );
+
+    // The gate is decided against the digest that was approved, and it still stands.
+    const ledger = memoryGateLedgerPort({ resolutions: [approval(set.doc.digest)] });
+    const check = await decidePrGate(ledger, { op: "pr-12", gate: "pr-apply", digest: resumed.set.doc.digest, now: NOW });
+    expect(check.satisfied).toBe(true);
+    expect(ledger.appended).toEqual([]);
+
+    const second = await applyPrSet({
+      components: ESTATE,
+      plan: resumed.plan,
+      registry: w.registry,
+      env: "prod",
+      set: resumed.set,
+      resumed: { completed: first.run.completed, outputs: {} },
+    });
+    expect(second.status).toBe("applied");
+    expect(w.applied).toEqual(["a", "app"]);
+    expect(w.fromPlan.a).toBe(true);
+    expect(Object.fromEntries(second.members.map((m) => [m.member, m.status]))).toEqual({
+      a: "applied",
+      app: "applied",
+      b: "applied",
+      dns: "applied",
+      net: "applied",
+    });
+  });
+
+  test("the resumed report carries the approved digest and names what the earlier attempt applied", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net", "dns"] });
+    const { set, first, record } = await firstAttempt(w, plan, ["a"]);
+    const resumed = await resumePrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", record, completed: first.run.completed });
+    if (!resumed.ok) throw new Error(resumed.reasons.join("; "));
+    const second = await applyPrSet({
+      components: ESTATE,
+      plan: resumed.plan,
+      registry: w.registry,
+      env: "prod",
+      set: resumed.set,
+      resumed: { completed: first.run.completed, outputs: {} },
+    });
+    const report = prReport({
+      stage: "apply",
+      pr: 12,
+      env: "prod",
+      base: "1".repeat(40),
+      head: "2".repeat(40),
+      op: "pr-12",
+      gate: "pr-apply",
+      plan,
+      signal: { changed: ["net", "dns"], unclaimed: [] } as never,
+      set: resumed.set,
+      approval: { status: "approved", approvedBy: ["github:alice"] },
+      status: second.status,
+      members: second.members,
+      resumed: first.run.completed,
+    });
+    expect(report.digest).toBe(set.doc.digest);
+    expect(report.changeSet).toBe(set.doc);
+    expect(report.resumed).toEqual({ applied: ["b", "dns", "net"] });
+  });
+
+  test("a dependent whose dependency applied in the earlier attempt applies its approved plan and says its inputs moved", async () => {
+    const w = world();
+    w.versions.a = "v2";
+    const plan = planFanOut({ components: ESTATE, changed: ["a"] });
+    const { first, record } = await firstAttempt(w, plan, ["app"]);
+    expect(first.run.completed).toEqual(["a"]);
+    const outputs = { a: first.run.componentOutputs.a };
+    expect(outputs.a).toEqual({ id: "a-v2" });
+
+    w.planned.length = 0;
+    const resumed = await resumePrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", record, completed: ["a"] });
+    if (!resumed.ok) throw new Error(resumed.reasons.join("; "));
+    // app is planned against the value it was approved with, not the one a wrote since.
+    expect(w.planned).toEqual([{ root: "app", vars: { subnet: "a-v1" } }]);
+
+    const second = await applyPrSet({
+      components: ESTATE,
+      plan: resumed.plan,
+      registry: w.registry,
+      env: "prod",
+      set: resumed.set,
+      resumed: { completed: ["a"], outputs },
+    });
+    expect(second.members.map((m) => [m.member, m.status, m.inputsMoved])).toEqual([
+      ["a", "applied", undefined],
+      ["app", "applied", ["a"]],
+    ]);
+  });
+
+  test("a member left over whose plan moved is not covered, and says why", async () => {
+    const w = world();
+    w.versions.a = "v2";
+    const plan = planFanOut({ components: ESTATE, changed: ["net", "a"] });
+    const { first, record } = await firstAttempt(w, plan, ["a"]);
+    expect(first.run.completed).toEqual(["b", "net"]);
+
+    w.versions.a = "v3";
+    const resumed = await resumePrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", record, completed: first.run.completed });
+    expect(resumed.ok).toBe(false);
+    if (resumed.ok) return;
+    expect(resumed.reasons).toEqual(["a now writes terraform_data.x.version to a different value than the approved plan"]);
+  });
+
+  test("a member left over that fails to plan is not covered", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { first, record } = await firstAttempt(w, plan, ["a"]);
+    w.planFailing.add("a");
+    const resumed = await resumePrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", record, completed: first.run.completed });
+    expect(resumed.ok).toBe(false);
+    if (resumed.ok) return;
+    expect(resumed.reasons[0]).toMatch(/^a failed to plan/);
+  });
+
+  test("a record whose change set is not the one its digest names does not resume (#3543)", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { set, first, record } = await firstAttempt(w, plan, ["a"]);
+    const other = { ...set.doc, digest: "jcs1-sha256:" + "0".repeat(64) };
+    for (const forged of [
+      { ...record, changeSet: other },
+      { ...record, digest: other.digest, changeSet: other },
+      { ...record, changeSet: { ...set.doc, members: set.doc.members.map((m) => (m.member === "a" ? { ...m, planDigest: "jcs1-sha256:" + "1".repeat(64) } : m)) } },
+    ]) {
+      w.planned.length = 0;
+      const resumed = await resumePrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", record: forged, completed: first.run.completed });
+      expect(resumed.ok).toBe(false);
+      if (resumed.ok) return;
+      expect(resumed.reasons[0]).toMatch(/^the record's change set is not the one its digest/);
+      expect(w.planned).toEqual([]);
+    }
+  });
+
+  test("with every component applied, nothing is left to plan or apply", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["dns"] });
+    const { first, record } = await firstAttempt(w, plan, []);
+    expect(first.status).toBe("applied");
+    w.planned.length = 0;
+    const resumed = await resumePrSet({ components: ESTATE, plan, registry: w.registry, env: "prod", record, completed: first.run.completed });
+    if (!resumed.ok) throw new Error(resumed.reasons.join("; "));
+    expect(resumed.plan.order).toEqual([]);
+    expect(w.planned).toEqual([]);
+  });
+});
+
+describe("planCoveredBy", () => {
+  const entry = (address: string, action: ChangeSetEntry["action"], attributes: ChangeSetEntry["attributes"] = [], extra: Partial<ChangeSetEntry> = {}): ChangeSetEntry => ({
+    member: "net",
+    lexicon: "terraform",
+    planner: "tofu",
+    address,
+    type: address.split(".")[0],
+    action,
+    attributes,
+    ...extra,
+  });
+  const doc = (digest: string, entries: ChangeSetEntry[], extra: Partial<ChangeSetPart["member"]> = {}) =>
+    composeChangeSet([
+      {
+        member: { member: "net", lexicon: "terraform", planner: "tofu", status: "planned", planDigest: `jcs1-sha256:${digest.repeat(64)}`, holes: [], ...extra },
+        entries,
+      },
+    ]);
+
+  const approved = doc("1", [
+    entry("aws_vpc.main", "update", [{ path: "tags", before: { a: "1" }, after: { a: "2" } }]),
+    entry("aws_subnet.a", "create", [{ path: "vpc_id", unknown: true }, { path: "cidr_block", after: "10.0.1.0/24" }]),
+    entry("aws_instance.web", "replace", [{ path: "ami", before: "ami-1", after: "ami-2", forcesReplacement: true }]),
+    entry("aws_db_instance.db", "update", [{ path: "password", sensitive: true }]),
+  ]);
+
+  test("the same plan digest is covered", () => {
+    expect(planCoveredBy(approved, doc("1", []), "net")).toBeUndefined();
+  });
+
+  test("what is left of the approved changes is covered", () => {
+    // The VPC applied, the subnet's vpc_id is known now, and the instance's
+    // old object was destroyed before the create failed.
+    const left = doc("2", [
+      entry("aws_vpc.main", "no-op"),
+      entry("aws_subnet.a", "create", [{ path: "vpc_id", after: "vpc-123" }, { path: "cidr_block", after: "10.0.1.0/24" }]),
+      entry("aws_instance.web", "create", [{ path: "ami", after: "ami-2" }, { path: "instance_type", after: "t3.micro" }]),
+      entry("aws_db_instance.db", "update", [{ path: "password", sensitive: true }]),
+    ]);
+    expect(planCoveredBy(approved, left, "net")).toBeUndefined();
+  });
+
+  test("a create-before-destroy replace left with its deposed object to delete is covered", () => {
+    const left = doc("2", [entry("aws_instance.web", "delete", [], { deposed: "00abc" })]);
+    expect(planCoveredBy(approved, left, "net")).toBeUndefined();
+  });
+
+  test("a change the approved plan did not make is not covered", () => {
+    expect(planCoveredBy(approved, doc("2", [entry("aws_s3_bucket.logs", "create")]), "net")).toBe(
+      "net now plans to create aws_s3_bucket.logs, which the approved plan did not",
+    );
+    expect(planCoveredBy(approved, doc("2", [entry("aws_vpc.main", "delete")]), "net")).toBe(
+      "net now plans to delete aws_vpc.main, where the approved plan would update it",
+    );
+    expect(planCoveredBy(approved, doc("2", [entry("aws_vpc.main", "update", [{ path: "tags", before: { a: "1" }, after: { a: "3" } }])]), "net")).toBe(
+      "net now writes aws_vpc.main.tags to a different value than the approved plan",
+    );
+    expect(planCoveredBy(approved, doc("2", [entry("aws_vpc.main", "update", [{ path: "cidr_block", before: "a", after: "b" }])]), "net")).toBe(
+      "net now writes aws_vpc.main.cidr_block, which the approved plan did not",
+    );
+  });
+
+  test("a sensitive value is covered only where the approved plan wrote it as sensitive", () => {
+    expect(planCoveredBy(approved, doc("2", [entry("aws_vpc.main", "update", [{ path: "tags", sensitive: true }])]), "net")).toMatch(/as sensitive/);
+    expect(planCoveredBy(approved, doc("2", [entry("aws_db_instance.db", "update", [{ path: "password", after: "x" }])]), "net")).toMatch(/wrote as sensitive/);
+  });
+
+  test("a hole the approved plan did not have is not covered", () => {
+    const left = doc("2", [], { holes: [{ address: "data.aws_ami.latest", reason: "unknown" }] });
+    expect(planCoveredBy(approved, left, "net")).toMatch(/cannot read data.aws_ami.latest/);
+  });
+
+  test("a member the approved set did not have is not covered", () => {
+    const other = composeChangeSet([
+      { member: { member: "edge", lexicon: "terraform", planner: "tofu", status: "planned", planDigest: `jcs1-sha256:${"3".repeat(64)}`, holes: [] }, entries: [] },
+    ]);
+    expect(planCoveredBy(approved, other, "edge")).toBe("edge was not in the approved plan");
+  });
+});