@intentius/chant-lexicon-terraform 0.124.52 → 0.124.54

package/src/report.ts

@@ -30,9 +30,14 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { changeSetDigest, composeChangeSet, type ChangeSetAction, type ChangeSetAttribute, type ChangeSetEntry, type ChangeSetPlanner } from "@intentius/chant/change-set";
+import { changeSetDigest, composeChangeSet, type ChangeSetAction, type ChangeSetDocument, type ChangeSetAttribute, type ChangeSetEntry, type ChangeSetPlanner } from "@intentius/chant/change-set";
 import { groupChangeSet } from "@intentius/chant/plan-summary";
 import { plannerForBinary, terraformChangeSetPart } from "./change-set";
+import { moduleChanges, stripModule, topModule } from "./compose/module-address";
+import { stateResources } from "./applied-state";
+import { isJsonConfigFile, jsonLiveBlocks, listConfigFiles } from "./hcl/files";
+
+export { topModule } from "./compose/module-address";
 
 type Json = Record<string, unknown>;
 const isObject = (v: unknown): v is Json => v !== null && typeof v === "object" && !Array.isArray(v);
@@ -139,40 +144,15 @@ export interface IndexRow {
 // Slicing the composed plan into one plan per module.
 // ---------------------------------------------------------------------------
 
-const TOP_MODULE = /^module\.([^.[\]]+)(?:\[(?:"(?:[^"\\]|\\.)*"|\d+)\])?(?:\.|$)/;
-
-/** The top-level module an address or module address is in, or undefined for the composed root's own. */
-export function topModule(address: string): string | undefined {
-  return TOP_MODULE.exec(address)?.[1];
-}
-
-/** `address` with its leading `module.<m>` (and index) taken off. */
-function unprefix(address: string): string {
-  const m = TOP_MODULE.exec(address);
-  return m ? address.slice(m[0].length) : address;
-}
-
 /** The plan's `resource_changes` that belong to module `m` (undefined: the root's own), each with the module taken off its address. */
 export function slicePlan(plan: unknown, m: string | undefined): Json {
   const p = isObject(plan) ? plan : {};
-  const list = Array.isArray(p.resource_changes) ? p.resource_changes : [];
-  const mine = list.filter((r) => isObject(r) && topModule(String(r.module_address ?? r.address ?? "")) === m);
-  const resource_changes = mine.map((r) => {
-    const rc = r as Json;
-    const out: Json = { ...rc, address: unprefix(String(rc.address)) };
-    if (typeof rc.previous_address === "string") out.previous_address = unprefix(rc.previous_address);
-    if (typeof rc.module_address === "string") {
-      const rest = unprefix(rc.module_address);
-      if (rest === "" || rest === rc.module_address) delete out.module_address;
-      else out.module_address = rest;
-    }
-    return out;
-  });
-  return { ...(p.errored === true ? { errored: true } : {}), resource_changes };
+  return { ...(p.errored === true ? { errored: true } : {}), resource_changes: moduleChanges(p.resource_changes, m) };
 }
 
 // ---------------------------------------------------------------------------
-// Applied values: the state after the apply gives the values the plan left unknown.
+// Applied values: the state after the apply gives the values the plan left unknown,
+// read through `./applied-state`, as the composed estate run reads them.
 // ---------------------------------------------------------------------------
 
 /** Whether a sensitivity map marks anything under it `true`. */
@@ -183,25 +163,6 @@ function marks(v: unknown): boolean {
   return false;
 }
 
-/** Every resource of a `show -json` state, by address. A deposed object is left out. */
-function stateResources(show: unknown): Map<string, { values: Json; sensitive: Json }> {
-  const out = new Map<string, { values: Json; sensitive: Json }>();
-  const walk = (mod: unknown): void => {
-    if (!isObject(mod)) return;
-    for (const r of Array.isArray(mod.resources) ? mod.resources : []) {
-      if (!isObject(r) || typeof r.address !== "string" || r.deposed_key !== undefined) continue;
-      out.set(r.address, { values: isObject(r.values) ? r.values : {}, sensitive: isObject(r.sensitive_values) ? r.sensitive_values : {} });
-    }
-    for (const c of Array.isArray(mod.child_modules) ? mod.child_modules : []) walk(c);
-  };
-  const root = isObject(show) ? show : {};
-  // A plan's `prior_state` is the state; a `show -json` of state has `values` itself.
-  const state = isObject(root.prior_state) ? root.prior_state : root;
-  const values = isObject(state.values) ? state.values : {};
-  walk(values.root_module);
-  return out;
-}
-
 /** Each unknown attribute given the value the state holds. One the state lacks stays unknown; a sensitive one stays `sensitive`. */
 function resolveUnknowns(attributes: ChangeSetAttribute[], res: { values: Json; sensitive: Json } | undefined): ChangeSetAttribute[] {
   if (!res || !attributes.some((a) => a.unknown)) return attributes;
@@ -230,15 +191,27 @@ export interface ReportRead {
   composed: true;
 }
 
-/** The estate named by the first `live { estate = "..." }` block in a directory's `.tf` files, or undefined. */
-export function estateOfDir(dir: string): string | undefined {
+/**
+ * The estate named by the first `live { estate = "..." }` block in a
+ * directory's configuration files, in filename order, or undefined. A `live`
+ * block takes effect only under choudoufu, so the files are the ones
+ * choudoufu reads (`.tf`, `.tf.json`, `.tofu` and `.tofu.json`, chant#4457)
+ * unless `binary` names another. A JSON-syntax file's `live` block is the one
+ * nested in its `terraform` block (chant#4504).
+ */
+export function estateOfDir(dir: string, binary = "choudoufu"): string | undefined {
   let files: string[];
   try {
-    files = readdirSync(dir).filter((f) => f.endsWith(".tf")).sort();
+    files = listConfigFiles(dir, binary);
   } catch {
     return undefined;
   }
   for (const f of files) {
+    if (isJsonConfigFile(f)) {
+      const estate = jsonLiveBlocks(readFileSync(join(dir, f), "utf8")).map((b) => b.estate).find((e): e is string => typeof e === "string" && e !== "");
+      if (estate) return estate;
+      continue;
+    }
     const text = readFileSync(join(dir, f), "utf8").replace(/^\s*(#|\/\/).*$/gm, "");
     const live = /\blive\s*\{/.exec(text);
     if (!live) continue;
@@ -309,7 +282,7 @@ function unknownOutputsOf(plan: Json, u: string): Set<string> {
       const data = parts[0] === "data";
       const [type, rname, attr] = data ? [parts[1], parts[2], parts[3]] : [parts[0], parts[1], parts[2]];
       if (!type || !rname) continue;
-      const unprefixed = (c: Json): string => unprefix(String(c.address)).replace(/\[[^\]]*\]$/, "");
+      const unprefixed = (c: Json): string => stripModule(String(c.address)).replace(/\[[^\]]*\]$/, "");
       for (const c of changes) {
         if (unprefixed(c) !== `${data ? "data." : ""}${type}.${rname}`) continue;
         const after = isObject(c.change) ? c.change.after_unknown : undefined;
@@ -494,6 +467,8 @@ function rawChanges(plan: Json): Map<string, RawChange> {
 
 export interface TerraformReport {
   report: Json;
+  /** The change set whose digest `report.change_set` names: what behold reads beside the report. */
+  changeSet: ChangeSetDocument;
   /** The run's directory, relative to the project's own index: `yyyy/mm/<commit>/<stage>`. */
   path: string;
   row: IndexRow;
@@ -680,7 +655,7 @@ export function terraformReport(input: TerraformReportInput): TerraformReport {
     ...(run.pull_request_url ? { pull_request_url: run.pull_request_url } : {}),
     ...(run.job_url ? { job_url: run.job_url } : {}),
   };
-  return { report, path, row };
+  return { report, changeSet: doc, path, row };
 }
 
 // ---------------------------------------------------------------------------
@@ -716,7 +691,8 @@ export interface ReportStore {
 }
 
 /**
- * Write the run's `report.json` and add its row to the project's index
+ * Write the run's `report.json` and `change-set.json` (the document whose
+ * digest the report names, as `chant change-set` writes it), and add its row to the project's index
  * (`<project>/index.json`, paths relative to it) and to the prefix's
  * (`index.json`, paths starting at the project), the two places terragucci
  * writes. Returns the keys written.
@@ -729,6 +705,7 @@ export async function writeReport(store: ReportStore, r: TerraformReport): Promi
     keys.push(key);
   };
   await put(`${project}/${r.path}/report.json`, r.report);
+  await put(`${project}/${r.path}/change-set.json`, r.changeSet);
   for (const [key, path] of [[`${project}/index.json`, r.path], ["index.json", `${project}/${r.path}`]] as const) {
     await put(key, addToIndex(await store.read(key), { ...r.row, path }));
   }

package/src/signal-only-root.test.ts

@@ -0,0 +1,72 @@
+/**
+ * A `signalOnly` root (#4484, C5 of #4477). The dns member declares the azure
+ * estate's root only so an azure change brings dns into the change. Change
+ * detection counts it; the build and the live reads leave it out, so dns's
+ * graph draws only dns's own root and dns's live reads never list azure.
+ */
+
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { terraformConfigSchema, ownRoots } from "./config";
+import { terraformPlugin } from "./plugin";
+import { liveRootNames } from "./describe-resources";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+const TERRAFORM: { binary: "choudoufu"; roots: Record<string, { dir: string; signalOnly?: boolean }> } = {
+  binary: "choudoufu",
+  roots: {
+    dns: { dir: "estate" },
+    azure: { dir: "../azure", signalOnly: true },
+  },
+};
+
+/** A workspace slice: `dns/` (the chant member, with its own root under `estate/`) beside `azure/`. */
+function estate(): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-signal-only-")));
+  scratch.push(root);
+  const files: Record<string, string> = {
+    "dns/chant.config.json": JSON.stringify({ lexicons: ["terraform"], terraform: TERRAFORM }),
+    "dns/estate/main.tf": 'resource "null_resource" "zone" {}\n',
+    "dns/estate/estate.chdf.hcl": 'estate = "dns"\n',
+    "azure/main.tf": 'resource "null_resource" "vnet" {}\n',
+    "azure/estate.chdf.hcl": 'estate = "azure"\n',
+  };
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return join(root, "dns");
+}
+
+describe("a signalOnly root (#4484)", () => {
+  test("the config schema takes the marker", () => {
+    expect(terraformConfigSchema.safeParse(TERRAFORM).success).toBe(true);
+    expect(Object.keys(ownRoots(TERRAFORM.roots))).toEqual(["dns"]);
+  });
+
+  test("the build draws only dns's own root, so the azure estate is not drawn under dns", async () => {
+    const dns = estate();
+    const { entities } = await terraformPlugin.buildRoots!({ projectRoot: dns, config: { terraform: TERRAFORM }, entities: new Map() });
+    const keys = [...entities.keys()];
+    expect(keys.length).toBeGreaterThan(0);
+    expect(keys.every((k) => k.startsWith("dns/"))).toBe(true);
+    expect(keys.some((k) => k.startsWith("azure/"))).toBe(false);
+  });
+
+  test("the live reads list dns's root and not the azure estate", async () => {
+    const dns = estate();
+    expect(await liveRootNames(dns)).toEqual([{ root: "dns", estate: "dns" }]);
+  });
+
+  test("an azure change still brings dns into the change", async () => {
+    const dns = estate();
+    const touched = await terraformPlugin.changedUnits!({ projectRoot: dns, config: { terraform: TERRAFORM }, changedFiles: ["../azure/main.tf"] });
+    expect(touched).toEqual(["azure"]);
+  });
+});

package/src/skills/chant-terraform.md

@@ -33,7 +33,7 @@ export default {
 
 ## What a build produces
 
-Every block of every configured root becomes one entity, keyed `<root>/<address>`: `terraform { }` -> `Terraform::Terraform`, `provider "x" {}` -> `Terraform::Provider`, `resource "x" "y" {}` -> `Terraform::Resource`, `data "x" "y" {}` -> `Terraform::Data`, `module "x" {}` -> `Terraform::Module`, `variable "x" {}` -> `Terraform::Variable`, `output "x" {}` -> `Terraform::Output`, `locals {}` -> `Terraform::Locals`. Each carries `props.address`, `props.body` (the block, verbatim), `props.file` and `props.root`. A root whose `dir` doesn't exist, or whose HCL the parser refuses, warns and contributes no entities — the rest of the build is unaffected.
+Every block of every configured root becomes one entity, keyed `<root>/<address>`: `terraform { }` -> `Terraform::Terraform`, `provider "x" {}` -> `Terraform::Provider`, `resource "x" "y" {}` -> `Terraform::Resource`, `data "x" "y" {}` -> `Terraform::Data`, `module "x" {}` -> `Terraform::Module`, `variable "x" {}` -> `Terraform::Variable`, `output "x" {}` -> `Terraform::Output`, `locals {}` -> `Terraform::Locals`, `moved {}` -> `Terraform::Moved`, `import {}` -> `Terraform::Import`, `removed {}` -> `Terraform::Removed`, `check "x" {}` -> `Terraform::Check`. Each carries `props.address`, `props.body` (the block, verbatim), `props.file` and `props.root`. A root whose `dir` doesn't exist, or whose HCL the parser refuses, warns and contributes no entities — the rest of the build is unaffected.
 
 ## The one thing to check before anything else
 

package/src/state/azure-blob.ts

@@ -0,0 +1,223 @@
+/**
+ * Azure Blob Storage for an azurerm backend's state, over its REST API with
+ * `fetch` and `node:crypto`: a blob's properties and metadata, its text, a
+ * write (under a lease when one holds it), a snapshot, a delete, and the
+ * blob lease the backend locks a state with.
+ *
+ * Requests are signed with Shared Key for an account key, carry a SAS as it
+ * is, or carry a storage token the job's OIDC identity is traded for at Entra
+ * ID (a client assertion, the way the azurerm backend does it).
+ *
+ * Lifted from terragucci's `report/azure-blob.ts` (c493e0e), without SAS
+ * links, version reads and version listing.
+ */
+import { createHmac } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { defaultFetch, encodePath, StoreError, xmlText, type StoreFetch } from "./object-store";
+
+/** The REST version every request names. */
+export const AZURE_VERSION = "2021-08-06";
+
+/** Entra ID's public cloud. */
+export const AZURE_AUTHORITY = "https://login.microsoftonline.com";
+
+const STORAGE_SCOPE = "https://storage.azure.com/.default";
+
+export interface AzureLocation {
+  account: string;
+  container: string;
+  /** The account's blob endpoint, no trailing slash: https://<account>.blob.core.windows.net, or an emulator's http://host:10000/<account>. */
+  endpoint: string;
+}
+
+/** The job's federated identity: an Entra app or managed identity that trusts the forge's token. */
+export interface AzureOidc {
+  tenantId: string;
+  clientId: string;
+  tokenFile: string;
+  /** Entra ID's address, https://host, no path. */
+  authority: string;
+}
+
+export type AzureTarget = AzureLocation & ({ accountKey: string } | { oidc: AzureOidc } | { sas: string });
+
+/** A blob's properties, as a HEAD answers them: never its body. */
+export interface BlobHead {
+  exists: boolean;
+  etag?: string;
+  /** x-ms-lease-state: `leased` while a lease holds it. */
+  leaseState?: string;
+  /** Its metadata, by name without the x-ms-meta- prefix. */
+  metadata: Record<string, string>;
+}
+
+const hmac64 = (key: string, s: string): string => createHmac("sha256", Buffer.from(key, "base64")).update(s, "utf8").digest("base64");
+
+/** The headers whose values Shared Key signs by position, in order. */
+const SIGNED = ["content-encoding", "content-language", "content-length", "content-md5", "content-type", "date", "if-modified-since", "if-match", "if-none-match", "if-unmodified-since", "range"];
+
+/** The Shared Key Authorization header for a request. */
+export function sharedKey(account: string, accountKey: string, method: string, rawUrl: string, headers: Record<string, string>): string {
+  const url = new URL(rawUrl);
+  const h = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+  const fixed = SIGNED.map((n) => (n === "content-length" && h[n] === "0" ? "" : (h[n] ?? "")));
+  const ms = Object.keys(h).filter((n) => n.startsWith("x-ms-")).sort().map((n) => `${n}:${h[n]!.trim()}\n`).join("");
+  const params = new Map<string, string[]>();
+  for (const [k, v] of url.searchParams) params.set(k.toLowerCase(), [...(params.get(k.toLowerCase()) ?? []), v]);
+  const query = [...params.keys()].sort().map((k) => `\n${k}:${params.get(k)!.sort().join(",")}`).join("");
+  const toSign = [method, ...fixed].join("\n") + "\n" + ms + `/${account}${url.pathname}` + query;
+  return `SharedKey ${account}:${hmac64(accountKey, toSign)}`;
+}
+
+/** Entra ID's error, or the start of the body. */
+const why = (text: string): string => {
+  try {
+    const j = JSON.parse(text) as { error?: string; error_description?: string };
+    if (j.error) return [j.error, j.error_description?.split("\r\n")[0]].filter(Boolean).join(": ");
+  } catch {
+    // Not JSON: Blob Storage answers in XML.
+  }
+  return [xmlText(text, "Code"), xmlText(text, "Message")?.split("\n")[0]].filter(Boolean).join(": ") || text.slice(0, 300);
+};
+
+export class AzureBlobClient {
+  private token?: Promise<{ token: string; expires: number }>;
+
+  constructor(readonly target: AzureTarget, private readonly fetchFn: StoreFetch = defaultFetch, private readonly readToken: (file: string) => string = (f) => readFileSync(f, "utf-8")) {}
+
+  private where(key: string): string {
+    return `az://${this.target.account}/${this.target.container}/${key}`;
+  }
+
+  private blobUrl(key: string, query = ""): string {
+    const t = this.target;
+    const q = [query, "sas" in t ? t.sas.replace(/^\?/, "") : ""].filter(Boolean).join("&");
+    return `${t.endpoint}/${t.container}/${encodePath(key)}${q ? `?${q}` : ""}`;
+  }
+
+  /** The storage token for the OIDC identity: once per client, again a minute before it expires. */
+  private async bearer(o: AzureOidc): Promise<string> {
+    const fetchToken = async (): Promise<{ token: string; expires: number }> => {
+      let assertion: string;
+      try {
+        assertion = this.readToken(o.tokenFile).trim();
+      } catch (e) {
+        throw new StoreError(`cannot read the OIDC token in ${o.tokenFile}: ${(e as Error).message}`);
+      }
+      if (!assertion) throw new StoreError(`the OIDC token file ${o.tokenFile} is empty`);
+      const body = new URLSearchParams({
+        client_id: o.clientId,
+        scope: STORAGE_SCOPE,
+        grant_type: "client_credentials",
+        client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+        client_assertion: assertion,
+      }).toString();
+      const res = await this.fetchFn(`${o.authority}/${o.tenantId}/oauth2/v2.0/token`, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body });
+      const text = await res.text();
+      if (!res.ok) throw new StoreError(`Entra ID refused the OIDC token for client ${o.clientId}: ${res.status} ${why(text)}`);
+      let j: { access_token?: string; expires_in?: number | string } = {};
+      try {
+        j = JSON.parse(text) as typeof j;
+      } catch {
+        // Reported below as no token.
+      }
+      if (!j.access_token) throw new StoreError(`Entra ID answered client ${o.clientId} without a token`);
+      return { token: j.access_token, expires: Date.now() + Number(j.expires_in ?? 3600) * 1000 };
+    };
+    const again = (): Promise<{ token: string; expires: number }> =>
+      (this.token = fetchToken().catch((e: unknown) => {
+        this.token = undefined;
+        throw e;
+      }));
+    let held = await (this.token ?? again());
+    if (held.expires - Date.now() < 60_000) held = await again();
+    return held.token;
+  }
+
+  /** The headers for one request, signed or with the bearer token. */
+  private async headers(method: string, url: string, extra: Record<string, string>): Promise<Record<string, string>> {
+    const h: Record<string, string> = { "x-ms-date": new Date().toUTCString(), "x-ms-version": AZURE_VERSION, ...extra };
+    const t = this.target;
+    if ("accountKey" in t) return { ...h, authorization: sharedKey(t.account, t.accountKey, method, url, h) };
+    if ("sas" in t) return h;
+    return { ...h, authorization: `Bearer ${await this.bearer(t.oidc)}` };
+  }
+
+  async get(key: string): Promise<string | undefined> {
+    const url = this.blobUrl(key);
+    const res = await this.fetchFn(url, { method: "GET", headers: await this.headers("GET", url, {}) });
+    if (res.status === 404) return undefined;
+    if (!res.ok) throw new StoreError(`GET ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+    return res.text();
+  }
+
+  /** A blob's properties and metadata, from a HEAD. */
+  async head(key: string): Promise<BlobHead> {
+    const url = this.blobUrl(key);
+    const res = await this.fetchFn(url, { method: "HEAD", headers: await this.headers("HEAD", url, {}) });
+    if (res.status === 404) return { exists: false, metadata: {} };
+    if (!res.ok) throw new StoreError(`HEAD ${this.where(key)}: ${res.status}`);
+    const get = (n: string): string | undefined => res.headers?.get(n) ?? undefined;
+    const metadata: Record<string, string> = {};
+    const all = res.headers as unknown as { forEach?: (fn: (v: string, k: string) => void) => void } | undefined;
+    all?.forEach?.((v, k) => {
+      if (k.toLowerCase().startsWith("x-ms-meta-")) metadata[k.toLowerCase().slice("x-ms-meta-".length)] = v;
+    });
+    const etag = get("etag");
+    const leaseState = get("x-ms-lease-state");
+    return { exists: true, ...(etag ? { etag } : {}), ...(leaseState ? { leaseState } : {}), metadata };
+  }
+
+  /** Take a snapshot of a blob: its id, the time Azure gives it. */
+  async snapshot(key: string): Promise<string> {
+    const url = this.blobUrl(key, "comp=snapshot");
+    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, { "content-length": "0" }) });
+    if (!res.ok) throw new StoreError(`snapshot of ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+    const id = res.headers?.get("x-ms-snapshot");
+    if (!id) throw new StoreError(`snapshot of ${this.where(key)}: Azure answered without x-ms-snapshot`);
+    return id;
+  }
+
+  /** Write a block blob with metadata, under a lease when one holds it; with `ifNoneMatch`, only when there is none (false when one was there). */
+  async putBlob(key: string, body: string, contentType: string, options: { leaseId?: string; metadata?: Record<string, string>; ifNoneMatch?: boolean } = {}): Promise<boolean> {
+    const url = this.blobUrl(key);
+    const meta = Object.fromEntries(Object.entries(options.metadata ?? {}).map(([k, v]) => [`x-ms-meta-${k}`, v]));
+    const extra: Record<string, string> = {
+      "x-ms-blob-type": "BlockBlob",
+      "content-type": contentType,
+      "content-length": String(Buffer.byteLength(body)),
+      ...meta,
+      ...(options.leaseId ? { "x-ms-lease-id": options.leaseId } : {}),
+      ...(options.ifNoneMatch ? { "if-none-match": "*" } : {}),
+    };
+    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, extra), body });
+    if (options.ifNoneMatch && (res.status === 409 || res.status === 412)) return false;
+    if (!res.ok) throw new StoreError(`PUT ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+    return true;
+  }
+
+  /** Delete a blob. One that is not there is deleted already. */
+  async remove(key: string): Promise<void> {
+    const url = this.blobUrl(key);
+    const res = await this.fetchFn(url, { method: "DELETE", headers: await this.headers("DELETE", url, {}) });
+    if (!res.ok && res.status !== 404) throw new StoreError(`DELETE ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+  }
+
+  /** A blob lease: acquire one that never expires with the id given (false when one holds it), or release it. */
+  async lease(key: string, action: "acquire" | "release", id: string): Promise<boolean> {
+    const url = this.blobUrl(key, "comp=lease");
+    const extra: Record<string, string> = { "x-ms-lease-action": action, "content-length": "0", ...(action === "acquire" ? { "x-ms-lease-duration": "-1", "x-ms-proposed-lease-id": id } : { "x-ms-lease-id": id }) };
+    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, extra) });
+    if (action === "acquire" && res.status === 409) return false;
+    if (!res.ok) throw new StoreError(`${action} the lease of ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+    return true;
+  }
+
+  /** Set a blob's metadata, all of it, under its lease when one holds it. */
+  async setMetadata(key: string, metadata: Record<string, string>, leaseId?: string): Promise<void> {
+    const url = this.blobUrl(key, "comp=metadata");
+    const extra = { "content-length": "0", ...Object.fromEntries(Object.entries(metadata).map(([k, v]) => [`x-ms-meta-${k}`, v])), ...(leaseId ? { "x-ms-lease-id": leaseId } : {}) };
+    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, extra) });
+    if (!res.ok) throw new StoreError(`set the metadata of ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+  }
+}

package/src/state/backend-verdict.test.ts

@@ -0,0 +1,187 @@
+/**
+ * One backend verdict for compose and state (chant#4478). The composition's
+ * `backend` fallback (#4438) and the state refusals (#4437) both come from
+ * `lockRefusal(readBackend(...))`, so the same root gets the same answer from
+ * each, before init (the code and flags) and after (what init recorded,
+ * compared with the code).
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { compositionFor, type CompositionInput } from "../compose";
+import { rootState } from "../compose/hcl";
+import type { TerraformConfig } from "../config";
+import { LOCKABLE_BACKENDS, LOCKS, cliBackendConfig, declaredBackend, isRefused, lockRefusal, readBackend, stateObject } from "./backend";
+
+const made: string[] = [];
+afterAll(() => {
+  for (const d of made) rmSync(d, { recursive: true, force: true });
+});
+
+function project(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-4478-"));
+  made.push(dir);
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, path)), { recursive: true });
+    writeFileSync(join(dir, path), text);
+  }
+  return dir;
+}
+
+const EMPTY = 'resource "terraform_data" "x" {}\n';
+const tf = (name: string): DriverComponent => ({ name, dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: name }] }] });
+const record = (type: string, config: Record<string, unknown>): string => JSON.stringify({ version: 3, backend: { type, config, hash: 1 } });
+
+/** Credentials for every lockable backend, so a lockable root resolves to a state rather than a credentials refusal. */
+const CREDS: NodeJS.ProcessEnv = { AWS_ACCESS_KEY_ID: "AK", AWS_SECRET_ACCESS_KEY: "SK", GOOGLE_OAUTH_ACCESS_TOKEN: "t", ARM_ACCESS_KEY: Buffer.from("k").toString("base64") };
+
+interface Case {
+  name: string;
+  /** Root `c`'s files, beside the plain roots `a` and `b`. */
+  files: Record<string, string>;
+  env?: NodeJS.ProcessEnv;
+  terraform?: Partial<TerraformConfig>;
+  /** The refusal kind both sides give, or undefined when chant locks it. */
+  refused?: string;
+}
+
+const s3 = (body: string): string => `terraform {\n  backend "s3" {\n    bucket = "b"\n    key    = "c.tfstate"\n${body}  }\n}\n`;
+
+const CASES: Case[] = [
+  { name: "s3 with use_lockfile = true in the code", files: { "main.tf": s3("    use_lockfile = true\n") } },
+  { name: "s3 with no lock file", files: { "main.tf": s3("") }, refused: "no-lockfile" },
+  { name: "s3 whose use_lockfile = true reaches init only through TF_CLI_ARGS_init", files: { "main.tf": s3("") }, env: { TF_CLI_ARGS_init: "-input=false -backend-config=use_lockfile=true" } },
+  { name: "s3 whose use_lockfile = true is in backendConfig", files: { "main.tf": s3("") }, terraform: { roots: { a: { dir: "roots/a" }, b: { dir: "roots/b" }, c: { dir: "roots/c", backendConfig: { use_lockfile: "true" } } } } },
+  { name: "gcs", files: { "main.tf": 'terraform {\n  backend "gcs" {\n    bucket = "b"\n    prefix = "c"\n  }\n}\n' } },
+  { name: "azurerm", files: { "main.tf": 'terraform {\n  backend "azurerm" {\n    storage_account_name = "acct"\n    container_name = "tfstate"\n    key = "c.tfstate"\n  }\n}\n' } },
+  { name: "local, declared", files: { "main.tf": 'terraform {\n  backend "local" {}\n}\n' } },
+  { name: "local, by declaring nothing", files: { "main.tf": EMPTY } },
+  { name: "a cloud block", files: { "main.tf": 'terraform {\n  cloud {\n    organization = "o"\n  }\n}\n' }, refused: "cloud" },
+  { name: "a cloud block in a .tofu file of a tofu root", files: { "main.tofu": 'terraform {\n  cloud {\n    organization = "o"\n  }\n}\n' }, terraform: { binary: "tofu" }, refused: "cloud" },
+  { name: "another backend", files: { "main.tf": 'terraform {\n  backend "consul" {\n    path = "c"\n  }\n}\n' }, refused: "backend" },
+  {
+    name: "s3 whose use_lockfile = true is only in a backend-config file (chant#4459)",
+    files: { "main.tf": s3(""), "backend.hcl": "# the lock\nuse_lockfile = true\n" },
+    terraform: { roots: { a: { dir: "roots/a" }, b: { dir: "roots/b" }, c: { dir: "roots/c", backendConfigFiles: ["backend.hcl"] } } },
+  },
+  {
+    name: "init recorded another bucket than the code names",
+    files: { "main.tf": s3("    use_lockfile = true\n"), ".terraform/terraform.tfstate": record("s3", { bucket: "elsewhere", key: "c.tfstate", use_lockfile: true }) },
+    refused: "disagree",
+  },
+  {
+    name: "init recorded s3 and the code now names gcs",
+    files: { "main.tf": 'terraform {\n  backend "gcs" {\n    bucket = "b"\n  }\n}\n', ".terraform/terraform.tfstate": record("s3", { bucket: "b", key: "k", use_lockfile: true }) },
+    refused: "disagree",
+  },
+  {
+    name: "init recorded what the code names, plus defaults the code leaves out",
+    files: { "main.tf": s3("    use_lockfile = true\n"), ".terraform/terraform.tfstate": record("s3", { bucket: "b", key: "c.tfstate", use_lockfile: true, region: "us-east-1", workspace_key_prefix: null }) },
+  },
+];
+
+function both(c: Case): { fallback?: string; state: ReturnType<typeof stateObject> } {
+  const dir = project({ "roots/a/main.tf": EMPTY, "roots/b/main.tf": EMPTY, ...Object.fromEntries(Object.entries(c.files).map(([f, t]) => [`roots/c/${f}`, t])) });
+  const env = { ...CREDS, ...c.env };
+  const terraform: TerraformConfig = { roots: { a: { dir: "roots/a" }, b: { dir: "roots/b" }, c: { dir: "roots/c" } }, compose: { enabled: true }, ...c.terraform } as TerraformConfig;
+  const input: CompositionInput = { projectRoot: dir, components: [tf("a"), tf("b"), tf("c")], env, terraform };
+  const fallback = compositionFor(input).fallbacks.find((f) => f.member === "c" && f.kind === "backend")?.reason;
+  const state = stateObject(join(dir, "roots/c"), env, undefined, terraform.binary, {
+    ...(terraform.roots.c?.backendConfig ? { backendConfig: terraform.roots.c.backendConfig } : {}),
+    ...(terraform.roots.c?.backendConfigFiles ? { backendConfigFiles: terraform.roots.c.backendConfigFiles } : {}),
+  });
+  return { ...(fallback ? { fallback } : {}), state };
+}
+
+describe("compose and state give one verdict per root (chant#4478)", () => {
+  for (const c of CASES) {
+    test(c.name, () => {
+      const { fallback, state } = both(c);
+      if (c.refused === undefined) {
+        expect(fallback).toBeUndefined();
+        expect(isRefused(state)).toBe(false);
+        return;
+      }
+      expect(state).toMatchObject({ refused: c.refused });
+      expect(fallback).toBe(`\`c\`: ${isRefused(state) ? state.reason : ""}`);
+    });
+  }
+
+  test("a disagreement names both sides", () => {
+    const { state } = both(CASES.find((c) => c.name.startsWith("init recorded another bucket"))!);
+    expect(isRefused(state) && state.reason).toContain('bucket = "b" in the code and flags, bucket = "elsewhere" in what init recorded');
+  });
+
+  test("a disagreement over a secret names the key, not its values", () => {
+    const dir = project({ "main.tf": 'terraform {\n  backend "s3" {\n    bucket = "b"\n    key = "k"\n    use_lockfile = true\n    secret_key = "one"\n  }\n}\n' });
+    const reading = readBackend(dir, { recorded: { type: "s3", config: { bucket: "b", key: "k", use_lockfile: true, secret_key: "two" } } });
+    expect(reading.disagreement).toContain("secret_key (value hidden)");
+    expect(reading.disagreement).not.toContain("one");
+    expect(reading.disagreement).not.toContain("two");
+  });
+});
+
+describe("the parts of the verdict", () => {
+  test("the lockable list is the one LOCKS spells", () => {
+    expect(LOCKABLE_BACKENDS).toEqual(["s3", "gcs", "azurerm", "local"]);
+    expect(LOCKS).toBe("chant locks and writes s3 (with use_lockfile = true), gcs, azurerm and local states");
+    for (const type of LOCKABLE_BACKENDS) expect(lockRefusal({ backend: { type, config: { use_lockfile: true } } })).toBeUndefined();
+  });
+
+  test("TF_CLI_ARGS and TF_CLI_ARGS_init -backend-config flags, pairs and files, later over earlier", () => {
+    expect(cliBackendConfig({ TF_CLI_ARGS: "-backend-config=region=eu-west-1 -backend-config backend.hcl", TF_CLI_ARGS_init: '-backend-config="region=us-east-2" --backend-config=use_lockfile=true' })).toMatchObject({
+      pairs: { region: "us-east-2", use_lockfile: "true" },
+      files: ["backend.hcl"],
+    });
+  });
+
+  test("the declared backend: code, then TF_CLI_ARGS*, then backendConfig", () => {
+    const dir = project({ "main.tf": 'terraform {\n  backend "s3" {\n    bucket = "b"\n    key = "k"\n    assume_role {\n      role_arn = "nested"\n    }\n  }\n}\n' });
+    expect(declaredBackend(dir, { env: { TF_CLI_ARGS_init: "-backend-config=key=from-env" }, backendConfig: { use_lockfile: "true" } })).toEqual({
+      type: "s3",
+      config: { bucket: "b", key: "from-env", use_lockfile: true },
+    });
+  });
+
+  test("the declared backend in Terraform's JSON syntax", () => {
+    const dir = project({ "main.tf.json": JSON.stringify({ terraform: { backend: { s3: { bucket: "b", key: "k", use_lockfile: true } } } }) });
+    expect(declaredBackend(dir)).toEqual({ type: "s3", config: { bucket: "b", key: "k", use_lockfile: true } });
+  });
+});
+
+describe("compose's state address comes from the same verdict (chant#4478 round 2)", () => {
+  const S3_NO_KEY = 'terraform {\n  backend "s3" {\n    bucket = "b"\n    use_lockfile = true\n  }\n}\n';
+  const reader = 'data "terraform_remote_state" "a" {\n  backend = "s3"\n  config = {\n    bucket = "b"\n    key    = "a.tfstate"\n  }\n}\n\nresource "terraform_data" "x" {\n  input = data.terraform_remote_state.a.outputs.id\n}\n';
+
+  test("a key only TF_CLI_ARGS_init gives is the root's state address, as stateObject reads it", () => {
+    const dir = project({ "main.tf": S3_NO_KEY });
+    const env = { ...CREDS, TF_CLI_ARGS_init: "-backend-config=key=from-init-args.tfstate" };
+    expect(rootState(dir, "app", { env, recorded: null }).own).toEqual({ bucket: "b", key: "from-init-args.tfstate" });
+    expect(stateObject(dir, env, undefined)).toMatchObject({ backend: "s3", bucket: "b", key: "from-init-args.tfstate" });
+    expect(rootState(dir, "app", { env: {}, recorded: null }).own).toBeUndefined();
+  });
+
+  test("a key TF_CLI_ARGS gives is overridden by TF_CLI_ARGS_init, as init applies them", () => {
+    const dir = project({ "main.tf": S3_NO_KEY });
+    const env = { TF_CLI_ARGS: "-backend-config=key=first.tfstate", TF_CLI_ARGS_init: "-backend-config=key=second.tfstate" };
+    expect(rootState(dir, "app", { env, recorded: null }).own).toEqual({ bucket: "b", key: "second.tfstate" });
+  });
+
+  test("after init, the recorded configuration names the state", () => {
+    const dir = project({ "main.tf": S3_NO_KEY, ".terraform/terraform.tfstate": record("s3", { bucket: "b", key: "recorded.tfstate", use_lockfile: true, region: null }) });
+    expect(rootState(dir, "app", { env: {} }).own).toEqual({ bucket: "b", key: "recorded.tfstate" });
+  });
+
+  test("a composition lines a read up with a member whose key comes only from TF_CLI_ARGS_init", () => {
+    const dir = project({ "roots/a/main.tf": S3_NO_KEY, "roots/b/main.tf": S3_NO_KEY + reader });
+    const c = compositionFor({
+      projectRoot: dir,
+      env: { TF_CLI_ARGS_init: "-backend-config=key=a.tfstate" },
+      components: [tf("a"), tf("b")],
+      terraform: { roots: { a: { dir: "roots/a" }, b: { dir: "roots/b" } }, compose: { enabled: true } },
+    });
+    expect(c.reads.get("b")).toEqual([{ via: "remote-state", upstream: "a", name: "a" }]);
+  });
+});