@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/registry/targets/zip.ts

@@ -0,0 +1,287 @@
+/**
+ * The zip of an attested module archive (chant#4605, terragucci#1299 ruling
+ * A). Artifactory takes a module only as a zip and Nexus recommends one, so
+ * their targets upload the same files the bucket registry's `.tar.gz`
+ * carries, at the same paths with the same modes, repacked as a zip. Nothing
+ * is added to or dropped from the module.
+ *
+ * The repack is deterministic: entries keep the tarball's order and mtimes,
+ * so one archive always gives the same zip bytes. The zip's archive comment
+ * carries the attested content digest and the revision
+ * (`chant-module content=sha256:<hex> revision=<sha>`), which is how a
+ * target's `held` tells, from the zip a host gives back, which attested
+ * archive it was made from. A zip with no such comment (one uploaded by
+ * hand) is judged by its own digest, so it never passes for the release's.
+ *
+ * No zip64: an archive past 4 GiB or 65535 entries is refused, far above
+ * either host's limit (Nexus takes 100 MB per module).
+ */
+import { deflateRawSync, gunzipSync, inflateRawSync } from "node:zlib";
+import { PublishTargetError } from "@intentius/chant/lifecycle/release-publish";
+
+/** One entry of a module tarball. */
+export interface ModuleArchiveEntry {
+  path: string;
+  type: "file" | "dir";
+  mode: number;
+  /** Seconds since the epoch. */
+  mtime: number;
+  data: Buffer;
+}
+
+const field = (b: Buffer, at: number, len: number): string => {
+  const raw = b.subarray(at, at + len);
+  const end = raw.indexOf(0);
+  return raw.subarray(0, end < 0 ? raw.length : end).toString("utf-8");
+};
+const octal = (b: Buffer, at: number, len: number): number => parseInt(field(b, at, len).trim() || "0", 8);
+
+function paxRecords(data: Buffer): Record<string, string> {
+  const out: Record<string, string> = {};
+  let at = 0;
+  while (at < data.length) {
+    const space = data.indexOf(0x20, at);
+    if (space < 0) break;
+    const len = parseInt(data.subarray(at, space).toString("utf-8"), 10);
+    if (!Number.isFinite(len) || len <= 0) break;
+    const record = data.subarray(space + 1, at + len - 1).toString("utf-8");
+    const eq = record.indexOf("=");
+    if (eq > 0) out[record.slice(0, eq)] = record.slice(eq + 1);
+    at += len;
+  }
+  return out;
+}
+
+const invalid = (message: string) => new PublishTargetError("publish-archive-invalid", message, "Publish the .tar.gz the bucket registry serves, with the module's files at its root.");
+
+/**
+ * The entries of a module's gzip tarball (ustar, pax and GNU long names), with
+ * `./` cut from each path. A link or a device in the archive is refused: a
+ * zip of the module could not carry it as the tarball does.
+ */
+export function moduleArchiveEntries(archive: Uint8Array): ModuleArchiveEntry[] {
+  let tar: Buffer;
+  try {
+    tar = gunzipSync(archive);
+  } catch {
+    throw invalid("the module archive is not a gzip tarball");
+  }
+  const out: ModuleArchiveEntry[] = [];
+  let at = 0;
+  let pax: Record<string, string> = {};
+  let longName: string | undefined;
+  while (at + 512 <= tar.length) {
+    const header = tar.subarray(at, at + 512);
+    if (header.every((b) => b === 0)) break;
+    const size = octal(header, 124, 12);
+    const flag = String.fromCharCode(header[156] || 0x30);
+    const data = tar.subarray(at + 512, at + 512 + size);
+    at += 512 + Math.ceil(size / 512) * 512;
+    if (flag === "x") {
+      pax = paxRecords(data);
+      continue;
+    }
+    if (flag === "L") {
+      longName = field(data, 0, data.length);
+      continue;
+    }
+    if (flag === "g") continue;
+    const prefix = field(header, 345, 155);
+    const raw = pax.path ?? longName ?? (prefix ? `${prefix}/${field(header, 0, 100)}` : field(header, 0, 100));
+    const mtime = pax.mtime ? Math.floor(Number(pax.mtime)) : octal(header, 136, 12);
+    pax = {};
+    longName = undefined;
+    const path = raw.replace(/^(\.\/)+/, "").replace(/\/+$/, "");
+    if (!path || path === ".") continue;
+    if (path.startsWith("/") || path.split("/").includes("..")) throw invalid(`the module archive holds ${raw}, outside its root`);
+    const type = flag === "0" || flag === "\0" || flag === "7" ? "file" : flag === "5" ? "dir" : undefined;
+    if (!type) throw invalid(`the module archive holds ${path}, which is not a regular file or a directory; a zip of the module cannot carry it`);
+    out.push({ path, type, mode: octal(header, 100, 8) & 0o7777, mtime, data: type === "file" ? Buffer.from(data) : Buffer.alloc(0) });
+  }
+  return out;
+}
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+/** The CRC-32 a zip entry carries. */
+export function crc32(data: Uint8Array): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < data.length; i++) c = CRC_TABLE[(c ^ data[i]!) & 0xff]! ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** MS-DOS date and time, as a zip entry keeps them, in UTC and clamped to 1980. */
+function dosTime(seconds: number): { time: number; date: number } {
+  const d = new Date(Math.max(seconds * 1000, Date.UTC(1980, 0, 1)));
+  return {
+    time: (d.getUTCHours() << 11) | (d.getUTCMinutes() << 5) | Math.floor(d.getUTCSeconds() / 2),
+    date: ((d.getUTCFullYear() - 1980) << 9) | ((d.getUTCMonth() + 1) << 5) | d.getUTCDate(),
+  };
+}
+
+/** The archive comment that names the attested archive a zip was made from. */
+export const ZIP_COMMENT_PREFIX = "chant-module";
+
+export const moduleZipComment = (content: string, revision?: string): string => `${ZIP_COMMENT_PREFIX} content=${content}${revision ? ` revision=${revision}` : ""}`;
+
+/** The content and revision a zip's archive comment names, when it is one {@link moduleZipComment} wrote. */
+export function readModuleZipComment(comment: string): { content: string; revision?: string } | undefined {
+  if (!comment.startsWith(`${ZIP_COMMENT_PREFIX} `)) return undefined;
+  const content = /(?:^| )content=(sha256:[0-9a-f]{64})(?: |$)/.exec(comment)?.[1];
+  if (!content) return undefined;
+  const revision = /(?:^| )revision=([^ ]+)(?: |$)/.exec(comment)?.[1];
+  return { content, ...(revision ? { revision } : {}) };
+}
+
+/** A zip of the given entries, with `comment` as its archive comment. Files are deflated. */
+export function zipOf(entries: readonly ModuleArchiveEntry[], comment = ""): Buffer {
+  if (entries.length > 0xffff) throw invalid(`the module archive holds ${entries.length} entries; a zip without zip64 holds 65535`);
+  const locals: Buffer[] = [];
+  const centrals: Buffer[] = [];
+  let offset = 0;
+  for (const e of entries) {
+    const name = Buffer.from(e.type === "dir" ? `${e.path}/` : e.path, "utf-8");
+    const data = e.type === "file" ? e.data : Buffer.alloc(0);
+    const packed = e.type === "file" ? deflateRawSync(data, { level: 9 }) : Buffer.alloc(0);
+    const method = e.type === "file" ? 8 : 0;
+    const crc = crc32(data);
+    const { time, date } = dosTime(e.mtime);
+    if (packed.length > 0xfffffffe || data.length > 0xfffffffe || offset > 0xfffffffe) throw invalid("the module archive is past 4 GiB; a zip without zip64 holds less");
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0800, 6);
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(date, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(packed.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    locals.push(local, name, packed);
+
+    const unixMode = (e.type === "dir" ? 0o040000 : 0o100000) | (e.mode & 0o7777 || (e.type === "dir" ? 0o755 : 0o644));
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE((3 << 8) | 20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0x0800, 8);
+    central.writeUInt16LE(method, 10);
+    central.writeUInt16LE(time, 12);
+    central.writeUInt16LE(date, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(packed.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    central.writeUInt32LE(((unixMode << 16) | (e.type === "dir" ? 0x10 : 0)) >>> 0, 38);
+    central.writeUInt32LE(offset, 42);
+    centrals.push(central, name);
+    offset += local.length + name.length + packed.length;
+  }
+  const cd = Buffer.concat(centrals);
+  const note = Buffer.from(comment, "utf-8");
+  if (note.length > 0xffff) throw invalid("the zip comment is longer than a zip carries");
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(cd.length, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(note.length, 20);
+  return Buffer.concat([...locals, cd, end, note]);
+}
+
+/**
+ * The zip a hosted target uploads for an attested archive: its entries,
+ * repacked, with the content digest and revision in the archive comment.
+ */
+export function moduleZip(archive: Uint8Array, content: string, revision?: string): Buffer {
+  return zipOf(moduleArchiveEntries(archive), moduleZipComment(content, revision));
+}
+
+/** A zip read back: its archive comment and its entries' paths, modes and bytes. */
+export interface ReadZip {
+  comment: string;
+  entries: { path: string; dir: boolean; mode: number; data: Buffer }[];
+}
+
+/** Reads a zip's central directory and entries. Throws on bytes that are not a zip. */
+export function readZip(bytes: Uint8Array): ReadZip {
+  const b = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let end = -1;
+  for (let i = b.length - 22; i >= Math.max(0, b.length - 22 - 0xffff); i--) {
+    if (b.readUInt32LE(i) === 0x06054b50) {
+      end = i;
+      break;
+    }
+  }
+  if (end < 0) throw new Error("not a zip archive: no end of central directory");
+  const count = b.readUInt16LE(end + 10);
+  const cdOffset = b.readUInt32LE(end + 16);
+  const comment = b.subarray(end + 22, end + 22 + b.readUInt16LE(end + 20)).toString("utf-8");
+  const entries: ReadZip["entries"] = [];
+  let at = cdOffset;
+  for (let n = 0; n < count; n++) {
+    if (b.readUInt32LE(at) !== 0x02014b50) throw new Error("not a zip archive: a bad central directory entry");
+    const method = b.readUInt16LE(at + 10);
+    const csize = b.readUInt32LE(at + 20);
+    const nameLen = b.readUInt16LE(at + 28);
+    const extraLen = b.readUInt16LE(at + 30);
+    const commentLen = b.readUInt16LE(at + 32);
+    const external = b.readUInt32LE(at + 38);
+    const local = b.readUInt32LE(at + 42);
+    const name = b.subarray(at + 46, at + 46 + nameLen).toString("utf-8");
+    at += 46 + nameLen + extraLen + commentLen;
+    if (b.readUInt32LE(local) !== 0x04034b50) throw new Error(`not a zip archive: no local header for ${name}`);
+    const start = local + 30 + b.readUInt16LE(local + 26) + b.readUInt16LE(local + 28);
+    const packed = b.subarray(start, start + csize);
+    const data = method === 0 ? Buffer.from(packed) : method === 8 ? inflateRawSync(packed) : undefined;
+    if (!data) throw new Error(`${name}: zip method ${method} is not read here`);
+    const dir = name.endsWith("/");
+    entries.push({ path: dir ? name.slice(0, -1) : name, dir, mode: (external >>> 16) & 0o7777, data });
+  }
+  return { comment, entries };
+}
+
+const isGzip = (b: Uint8Array) => b.length >= 2 && b[0] === 0x1f && b[1] === 0x8b;
+const isZip = (b: Uint8Array) => b.length >= 4 && b[0] === 0x50 && b[1] === 0x4b;
+
+/**
+ * The content a module archive a host gave back carries, as `held` reports
+ * it: the attested digest a chant zip's comment names; for a gzip tarball,
+ * the digest of its uncompressed bytes, as the bucket registry keeps it; for
+ * any other bytes, their own digest.
+ */
+export function heldContentOf(bytes: Uint8Array, digest: (b: Uint8Array) => string): { content: string; revision?: string } {
+  if (isZip(bytes)) {
+    try {
+      const named = readModuleZipComment(readZip(bytes).comment);
+      if (named) return named;
+    } catch {
+      // Not a zip after all: judged by its own digest below.
+    }
+  } else if (isGzip(bytes)) {
+    try {
+      return { content: digest(gunzipSync(bytes)) };
+    } catch {
+      // A broken gzip: judged by its own digest below.
+    }
+  }
+  return { content: digest(bytes) };
+}

package/src/registry/writer.ts

@@ -0,0 +1,155 @@
+/**
+ * The module registry protocol, written as files a bucket, a directory or a
+ * Pages site holds (https://opentofu.org/docs/internals/module-registry-protocol/):
+ *
+ *   .well-known/terraform.json                  {"modules.v1": "/v1/modules/"}
+ *   v1/modules/<ns>/<name>/<system>/versions     every version, oldest first
+ *   v1/modules/<ns>/<name>/<system>/<v>/download {"location": ...}
+ *   v1/modules/<ns>/<name>/<system>/<v>/<name>-<v>.tar.gz   a tarball download
+ *   v1/modules/<ns>/<name>/<system>/<v>/release.json        the commit and content digest
+ *
+ * The download answer the two CLIs need is a 200 with the JSON body and an
+ * `X-Terraform-Get` header naming the same location (terragucci#1287).
+ * Terraform reads only the header (hashicorp/terraform
+ * internal/registry/client.go:237-250 at v1.14.9 and v1.15.8). OpenTofu reads
+ * the body's `location` first and the header when it is empty
+ * (opentofu/opentofu internal/registry/client.go:205-237 at v1.12.5 and
+ * v1.13.1). A stored file carries no header, so the stored `download` file is
+ * the body, and whatever serves it (`downloadAnswer`, the loopback handler in
+ * ./serve, an edge function) adds the header from that body.
+ *
+ * The writer takes the store it writes to, so the bucket clients stay with
+ * whoever owns them (chant#4554 moves terragucci's into core).
+ */
+// The errors module alone, never the object-store index: its clients import Node built-ins, and the
+// edge function (./edge) reaches this file for the download answer (chant#4589).
+import { isStoreConflict, type StoreCondition } from "@intentius/chant/object-store/errors";
+import { DISCOVERY, MODULES_V1, keyFor, type RegistryAddress } from "./address";
+import { compareSemver, formatSemver, parseSemver, type Semver } from "./semver";
+
+/** The header Terraform takes a module's location from. */
+export const DOWNLOAD_HEADER = "X-Terraform-Get";
+
+/** The files a registry is written to: a bucket client, a directory, or a test's map. */
+export interface RegistryWriteStore {
+  /** Writes one object. With `when`, the write must fail with a conflict when the condition no longer holds. */
+  put(key: string, body: string | Buffer, contentType?: string, when?: StoreCondition): Promise<unknown>;
+  /** One object's body and version tag, or `{}` when there is none. */
+  read(key: string): Promise<{ body?: string; etag?: string }>;
+}
+
+/** The service discovery document. */
+export const discoveryDoc = (): string => `${JSON.stringify({ "modules.v1": MODULES_V1 })}\n`;
+
+/** The protocol's versions answer, oldest first, duplicates and non-versions dropped. */
+export function versionsDoc(versions: string[]): string {
+  // Dedupe after formatting, so "v1.0.0" and "1.0.0" are one version.
+  const parsed = versions.map((v) => parseSemver(v)).filter((v): v is Semver => !!v);
+  const sorted = [...new Set(parsed.sort(compareSemver).map(formatSemver))];
+  return `${JSON.stringify({ modules: [{ versions: sorted.map((version) => ({ version })) }] }, null, 2)}\n`;
+}
+
+/** The versions a versions answer lists, or none when it is missing or not the protocol's JSON. */
+export function readVersions(text: string | undefined): string[] {
+  if (!text) return [];
+  try {
+    const doc = JSON.parse(text) as { modules?: { versions?: { version?: unknown }[] }[] };
+    return (doc.modules?.[0]?.versions ?? []).map((v) => v.version).filter((v): v is string => typeof v === "string");
+  } catch {
+    return [];
+  }
+}
+
+/** A version's download answer body: the JSON OpenTofu reads. */
+export function downloadDoc(location: string): string {
+  return `${JSON.stringify({ location })}\n`;
+}
+
+/** The location a download body names, or undefined when it names none. */
+export function downloadLocation(body: string | undefined): string | undefined {
+  if (!body) return undefined;
+  try {
+    const location = (JSON.parse(body) as { location?: unknown }).location;
+    return typeof location === "string" && location ? location : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** A download answer as a server sends it. */
+export interface DownloadAnswer {
+  status: 200;
+  headers: Record<string, string>;
+  body: string;
+}
+
+/**
+ * The download answer both CLIs install from: status 200, the JSON body with
+ * `location`, and `X-Terraform-Get` naming the same location.
+ */
+export function downloadAnswer(location: string): DownloadAnswer {
+  return { status: 200, headers: { "content-type": "application/json", [DOWNLOAD_HEADER]: location }, body: downloadDoc(location) };
+}
+
+/** The headers a stored download body is served with, or undefined when the body names no location. */
+export function downloadHeaders(body: string | undefined): Record<string, string> | undefined {
+  const location = downloadLocation(body);
+  return location ? downloadAnswer(location).headers : undefined;
+}
+
+/** True for a `.../v1/modules/<ns>/<name>/<system>/<version>/download` path, with or without a leading prefix. */
+export const isDownloadPath = (path: string): boolean => /(^|\/)v1\/modules\/[^/]+\/[^/]+\/[^/]+\/[^/]+\/download$/.test(path.split("?")[0]!);
+
+/** What the registry keeps beside a version, so the next publish knows what it holds. */
+export interface ReleaseMeta {
+  module: string;
+  version: string;
+  revision: string;
+  content: string;
+  location: string;
+}
+
+/** The registry's files for one version, written in this order: the version is listed last, once all it points at is there. */
+export interface VersionFiles {
+  tarball?: { key: string; body: Buffer };
+  download: { key: string; body: string };
+  meta: { key: string; body: string };
+}
+
+export interface WriteVersionOptions {
+  /** The registry's prefix in its store. */
+  prefix?: string;
+  /**
+   * Whether an error from `put` is a lost conditional write, to be retried.
+   * By default chant's `StoreConflict`, or any error named `StoreConflict`
+   * (a store from another package with a class of its own).
+   */
+  isConflict?: (e: unknown) => boolean;
+  /** Conditional retries on the versions file before the conflict is thrown. Default 3. */
+  retries?: number;
+}
+
+/** Writes one version: discovery when it differs, the tarball, the download answer, release.json, then the versions list. */
+export async function writeVersion(store: RegistryWriteStore, addr: RegistryAddress, version: Semver, files: VersionFiles, options: WriteVersionOptions = {}): Promise<void> {
+  const discovery = discoveryDoc();
+  const discoKey = keyFor(options.prefix, DISCOVERY);
+  const disco = await store.read(discoKey);
+  if (disco.body !== discovery) await store.put(discoKey, discovery, "application/json");
+  if (files.tarball) await store.put(files.tarball.key, files.tarball.body, "application/gzip");
+  await store.put(files.download.key, files.download.body, "application/json");
+  await store.put(files.meta.key, files.meta.body, "application/json");
+  const key = keyFor(options.prefix, `${addr.path}/versions`);
+  const isConflict = options.isConflict ?? isStoreConflict;
+  const retries = options.retries ?? 3;
+  // Read, add, write only over the copy read: two publishes at once cannot drop each other's version.
+  for (let attempt = 0; ; attempt++) {
+    const held = await store.read(key);
+    const when: StoreCondition | undefined = held.body === undefined ? { ifNoneMatch: "*" } : held.etag ? { ifMatch: held.etag } : undefined;
+    try {
+      await store.put(key, versionsDoc([...readVersions(held.body), formatSemver(version)]), "application/json", when);
+      return;
+    } catch (e) {
+      if (!isConflict(e) || attempt >= retries) throw e;
+    }
+  }
+}

package/src/report.test.ts

@@ -8,9 +8,13 @@
 import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { contract } from "../../../packages/core/src/workspace/__fixtures__/contract-repo";
 import { describe, expect, test } from "vitest";
+import { verifyChangeSetDigest } from "@intentius/chant/change-set";
 import { addToIndex, atmosOutputReads, atmosStackReads, dirStore, estateOfDir, httpStore, moduleEstates, runFactsFromEnv, slicePlan, terraformReport, topModule, writeReport } from "./report";
 import { parseReportArgs } from "./commands";
+import { generateReportFixture } from "./__fixtures__/report/generate";
+import { readdirSync } from "node:fs";
 
 const rc = (address: string, module: string, type: string, name: string, actions: string[], change: Record<string, unknown>) => ({
   address, module_address: module, mode: "managed", type, name, provider_name: "registry.terraform.io/hashicorp/aws", change: { actions, ...change },
@@ -287,7 +291,7 @@ describe("writing", () => {
     const store = dirStore(dir);
     const plan = terraformReport({ ...base, stage: "tf-plan" });
     const apply = terraformReport({ ...base, stage: "tf-apply", applied: AFTER, finished: "2026-10-24T10:05:00Z" });
-    expect(await writeReport(store, plan)).toEqual([`${RUN.project}/2026/10/abc123/tf-plan/report.json`, `${RUN.project}/index.json`, "index.json"]);
+    expect(await writeReport(store, plan)).toEqual([`${RUN.project}/2026/10/abc123/tf-plan/report.json`, `${RUN.project}/2026/10/abc123/tf-plan/change-set.json`, `${RUN.project}/index.json`, "index.json"]);
     await writeReport(store, apply);
     await writeReport(store, apply);
     const project = JSON.parse(readFileSync(join(dir, RUN.project, "index.json"), "utf8"));
@@ -322,6 +326,83 @@ describe("writing", () => {
   });
 });
 
+const SCHEMA_PATH = join(import.meta.dirname, "..", "..", "..", "packages", "core", "src", "workspace", "change-set.schema.json");
+const { validate: validateChangeSet } = contract(JSON.parse(readFileSync(SCHEMA_PATH, "utf8")));
+const FIXTURE_DIR = join(import.meta.dirname, "__fixtures__", "report");
+
+/** The change set must validate against chant's schema and be the document the report's digest names. */
+function expectChangeSet(doc: any, report: any): void {
+  expect(validateChangeSet(doc), JSON.stringify(validateChangeSet.errors, null, 2)).toBe(true);
+  expect(verifyChangeSetDigest(doc)).toBe(true);
+  expect(report.change_set).toBe(doc.digest);
+}
+
+describe("change-set.json beside the report", () => {
+  const apply = { ...base, stage: "tf-apply" as const, applied: AFTER, finished: "2026-10-24T10:05:00Z" };
+
+  test.each([["tf-plan", { ...base, stage: "tf-plan" as const }], ["tf-apply", apply]])("%s: the document validates and its digest is the report's", (_stage, input) => {
+    const r = terraformReport(input);
+    expectChangeSet(r.changeSet, r.report);
+  });
+
+  test("--out writes it next to report.json for both stages", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "tf-report-cs-"));
+    const store = dirStore(dir);
+    for (const input of [{ ...base, stage: "tf-plan" as const }, apply]) {
+      const r = terraformReport(input);
+      await writeReport(store, r);
+      const at = join(dir, RUN.project, r.path);
+      expect(readdirSync(at).sort()).toEqual(["change-set.json", "report.json"]);
+      expectChangeSet(JSON.parse(readFileSync(join(at, "change-set.json"), "utf8")), JSON.parse(readFileSync(join(at, "report.json"), "utf8")));
+    }
+  });
+
+  test("--to puts it next to report.json for both stages", async () => {
+    const objects = new Map<string, string>();
+    const fake = (async (url: string, init?: RequestInit) => {
+      if (init?.method === "PUT") {
+        objects.set(url, String(init.body));
+        return new Response("", { status: 200 });
+      }
+      return objects.has(url) ? new Response(objects.get(url)!) : new Response("", { status: 404 });
+    }) as unknown as typeof fetch;
+    const store = httpStore("http://floci:4566/demo-reports/demo", fake);
+    for (const input of [{ ...base, stage: "tf-plan" as const }, apply]) {
+      const r = terraformReport(input);
+      await writeReport(store, r);
+      const at = `http://floci:4566/demo-reports/demo/${encodeURIComponent("forgejo:3000").replace(/%3A/g, "%3A")}/admin/demo-terragrunt-choudoufu/${r.path}`;
+      expectChangeSet(JSON.parse(objects.get(`${at}/change-set.json`)!), JSON.parse(objects.get(`${at}/report.json`)!));
+    }
+  });
+});
+
+describe("the report fixture behold renders", () => {
+  const read = (name: string): any => JSON.parse(readFileSync(join(FIXTURE_DIR, name), "utf8"));
+
+  test("is what the generator writes now; regenerate with `npx tsx lexicons/terraform/src/__fixtures__/report/generate.ts`", async () => {
+    const files = await generateReportFixture();
+    expect(Object.keys(files).sort()).toEqual(["tf-apply/change-set.json", "tf-apply/report.json", "tf-plan/change-set.json", "tf-plan/report.json"]);
+    for (const [name, body] of Object.entries(files)) expect(readFileSync(join(FIXTURE_DIR, name), "utf8"), `${name} is stale`).toBe(body);
+  });
+
+  test("both stages validate, and each digest is its report's", () => {
+    for (const stage of ["tf-plan", "tf-apply"]) expectChangeSet(read(`${stage}/change-set.json`), read(`${stage}/report.json`));
+  });
+
+  test("three members, two composed reads", () => {
+    const plan = read("tf-plan/report.json");
+    expect(read("tf-plan/change-set.json").members.map((m: any) => m.member)).toEqual(["estates/app", "estates/edge", "estates/network"]);
+    const reads = plan.roots.flatMap((r: any) => r.reads ?? []);
+    expect(reads.filter((r: any) => r.composed === true).length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("an attribute unknown at plan has its value after the apply", () => {
+    const attr = (stage: string) => read(`${stage}/report.json`).roots.find((r: any) => r.path === "estates/network").changes.find((c: any) => c.address === "aws_subnet.new").attributes.find((a: any) => a.path === "id");
+    expect(attr("tf-plan")).toEqual({ path: "id", unknown: true });
+    expect(attr("tf-apply")).toEqual({ path: "id", after: "subnet-0a1b" });
+  });
+});
+
 describe("the run's facts and the verb's flags", () => {
   test("a Forgejo environment names the project as terragucci does", () => {
     const f = runFactsFromEnv({ GITHUB_REPOSITORY: "admin/demo", GITHUB_SERVER_URL: "http://forgejo:3000", GITHUB_SHA: "deadbeef", GITHUB_RUN_ID: "9", FORGEJO_ACTIONS: "true" }, { pullRequest: "12" });