@intentius/chant 0.101.0 → 0.104.0

package/src/fold-provenance.test.ts

@@ -508,3 +508,143 @@ describe("fold provenance over a real composite build (#2161)", () => {
     expect(verdicts[3].resolution.kind).toBe("edit-declaration");
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────
+// chant #3212 — a registered tag inside a composite factory.
+// ─────────────────────────────────────────────────────────────────────────
+
+const runtimePath = resolve(thisDir, "./runtime");
+const provenancePath = resolve(thisDir, "./provenance");
+
+/**
+ * A SQL-shaped tag, the shape the sql lexicon's `table` takes: it builds one
+ * entity out of its text and reports, per interpolation, which of the entity's
+ * fields that interpolation fed. An interpolated entity is a reference and
+ * feeds nothing the author typed, so it reports no field.
+ */
+const TAGS = `
+  import { createResource } from ${JSON.stringify(runtimePath)};
+  import { setInterpolationFields } from ${JSON.stringify(provenancePath)};
+  const Table = createResource("Test::Table", ${JSON.stringify(LEXICON_NAME)}, {});
+  const CLAUSE = { TABLE: "name", "ENGINE =": "engine", "ORDER BY": "orderBy", TTL: "ttl", COMMENT: "comment" };
+
+  export function table(strings, ...values) {
+    const isEntity = (v) => typeof v === "object" && v !== null && "props" in v;
+    let ddl = strings[0];
+    const fields = values.map((v, i) => {
+      ddl += (isEntity(v) ? v.props.name : String(v)) + strings[i + 1];
+      if (isEntity(v)) return [];
+      const at = (k) => strings[i].lastIndexOf(k);
+      const clause = Object.keys(CLAUSE).sort((a, b) => at(b) - at(a))[0];
+      return at(clause) >= 0 ? [CLAUSE[clause], "ddl"] : ["ddl"];
+    });
+    const m = /CREATE TABLE (\\w+) ENGINE = (\\w+) ORDER BY (\\w+)(?: TTL (.+?))?(?: COMMENT (\\w+))?$/.exec(ddl);
+    if (!m) throw new Error("cannot parse: " + ddl);
+    const props = { name: m[1], engine: m[2], orderBy: m[3], ddl };
+    if (m[4]) props.ttl = m[4];
+    if (m[5]) props.comment = m[5];
+    const entity = new Table(props);
+    setInterpolationFields(entity, fields);
+    return entity;
+  }
+`;
+
+const TAG_COMPOSITES = `
+  import { table } from "./tags";
+  import { Composite } from ${JSON.stringify(compositePath)};
+
+  export const EventsTable = Composite((props) => {
+    const rollupName = \`\${props.name}_daily\`;
+    const events = table\`CREATE TABLE \${props.name} ENGINE = MergeTree ORDER BY ts TTL ts + INTERVAL \${props.ttlDays} DAY\`;
+    const rollup = table\`CREATE TABLE \${rollupName} ENGINE = \${"SummingMergeTree"} ORDER BY ts COMMENT \${events}\`;
+    return { events, rollup };
+  }, "EventsTable");
+`;
+
+const TAG_MAIN = `
+  import { table } from "../tags";
+  import { EventsTable } from "../composites";
+
+  export const audit = table\`CREATE TABLE audit ENGINE = MergeTree ORDER BY ts\`;
+  export const clicks = EventsTable({ name: "clicks", ttlDays: 30 });
+`;
+
+describe("fold provenance through a tagged template in a composite factory (#3212)", () => {
+  let testDir: string;
+  let srcDir: string;
+
+  beforeEach(async () => {
+    const dir = join(repoRoot, ".cache", `chant-3212-${process.pid}-${seq++}`);
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    testDir = await realpath(dir);
+    srcDir = join(testDir, "src");
+    await mkdir(srcDir, { recursive: true });
+    await writeFile(join(testDir, "tags.ts"), TAGS);
+    await writeFile(join(testDir, "composites.ts"), TAG_COMPOSITES);
+    await writeFile(join(srcDir, "main.ts"), TAG_MAIN);
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  const buildIt = () =>
+    build(srcDir, [namesSerializer], undefined, {
+      fold: true,
+      lexicons: [LEXICON_NAME],
+      intrinsics: [{ name: "table", isTag: true }],
+    });
+
+  test("a field fed by ${props.x} is that parameter, a field the text fixes is a literal", async () => {
+    const result = await buildIt();
+    expect(result.errors).toEqual([]);
+    const events = result.foldProvenance.clicksEvents;
+    const rollup = result.foldProvenance.clicksRollup;
+    const at = (parameters: string[]) => ({ kind: "composite-parameter", composite: "EventsTable", instance: "clicks", parameters });
+    const fixed = { kind: "composite-literal", composite: "EventsTable", instance: "clicks" };
+
+    expect(events.fields.name).toEqual(at(["name"]));
+    expect(events.fields.ttl).toEqual(at(["ttlDays"]));
+    expect(events.fields.ddl).toEqual(at(["name", "ttlDays"]));
+    expect(events.fields.engine).toEqual(fixed);
+    expect(events.fields.orderBy).toEqual(fixed);
+
+    // Through a body `const`; an interpolated literal string is fixed; an
+    // interpolated sibling entity is wiring, so it governs nothing.
+    expect(rollup.fields.name).toEqual(at(["name"]));
+    expect(rollup.fields.engine).toEqual(fixed);
+    expect(rollup.fields.comment).toEqual(fixed);
+    expect(rollup.fields.ddl).toEqual(at(["name"]));
+
+    expect(result.foldProvenance.audit.fields.ttl).toBeUndefined();
+    expect(result.foldProvenance.audit.fields.name).toEqual({ kind: "direct" });
+  });
+
+  test("drift on a parameter-fed field proposes the parameter at the call site", async () => {
+    const result = await buildIt();
+    const provenanceOf = (name: string): EntityProvenance | undefined => {
+      const entity = result.entities.get(name);
+      return entity ? getProvenance(entity) : undefined;
+    };
+    const drift = (name: string, path: string, declared: unknown, live: unknown): DeepEntityDrift => {
+      const origin = originOfPath(provenanceOf(name)?.paths, path);
+      return { name, type: "Test::Table", changes: [{ path, kind: "changed", declared, live, ...(origin ? { origin } : {}) }] };
+    };
+
+    const [ttl, engine] = resolveDeepDrift(
+      [
+        drift("clicksEvents", "ttl", "ts + INTERVAL 30 DAY", "ts + INTERVAL 90 DAY"),
+        drift("clicksEvents", "engine", "MergeTree", "ReplacingMergeTree"),
+      ],
+      provenanceOf,
+    );
+
+    expect(ttl.resolution.kind).toBe("propose-parameter");
+    if (ttl.resolution.kind !== "propose-parameter") throw new Error("unreachable");
+    expect(ttl.resolution.parameters).toEqual(["ttlDays"]);
+    expect(ttl.resolution.instance).toBe("clicks");
+    expect(ttl.resolution.sourceFile).toContain("main.ts");
+    expect(engine.resolution.kind).toBe("refuse-fixed");
+  });
+});

package/src/gated-waves-bundle.test.ts

@@ -0,0 +1,62 @@
+/**
+ * The gated-wave primitives bundle small (#3049, ruling #3421).
+ *
+ * terragucci runs a wave per CI job from one bundled file with no TypeScript
+ * toolchain. It calls wave planning, the set digest and the gate names from
+ * `@intentius/chant/gated-waves`, and decides a wave's gate with
+ * `evaluateGate` from `@intentius/chant/op/gate` against the
+ * `chant/lifecycle` ledger. This bundles both 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";
+
+const HEAVY = [/node_modules\/typescript\//, /node_modules\/esbuild\//, /\/src\/fold\//, /\/src\/lint\//, /\/src\/codegen\//];
+
+async function inputsOf(entry: string): Promise<{ inputs: string[]; bytes: number }> {
+  const result = await build({
+    entryPoints: [join(REPO, "packages", "core", "src", entry)],
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    write: false,
+    metafile: true,
+    outdir: "out",
+    logLevel: "silent",
+  });
+  return {
+    inputs: Object.keys(result.metafile.inputs),
+    bytes: result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0),
+  };
+}
+
+describe("the gated-wave bundle", () => {
+  test("wave planning, the set digest and the records hold the change-set digest code and nothing heavier", async () => {
+    const { inputs, bytes } = await inputsOf("gated-waves.ts");
+    for (const pattern of [...HEAVY, /node_modules\/zod\//]) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "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/gated-waves.ts",
+      "packages/core/src/intrinsic.ts",
+      "packages/core/src/lifecycle/plan-digest.ts",
+    ]);
+    expect(bytes).toBeLessThan(24 * 1024);
+  });
+
+  test("the gate decision reaches no TypeScript, esbuild, fold, lint or codegen module", async () => {
+    // It does reach zod, through the workspace identity rules a gate reads
+    // (#3163). That is weight, not a toolchain, and #3421 forbids the toolchain.
+    const { inputs } = await inputsOf("op/gate.ts");
+    for (const pattern of HEAVY) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+  });
+});

package/src/gated-waves.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Gated waves (#3049): the parts with no runner. Wave layering with a canary
+ * list, the set digest, gate names and the attempt record's wave entries.
+ */
+
+import { describe, expect, test } from "vitest";
+import {
+  ProvisionalWaveMemberError,
+  UnknownCanaryError,
+  WaveCycleError,
+  describeChangedWave,
+  layerWaves,
+  readWaveRecords,
+  waveGateName,
+  waveSetDigest,
+  withWaveRecord,
+  type WaveRecord,
+} from "./gated-waves";
+import { changeSetDigest } from "./change-set";
+
+/** net → a, b → app-a (on a), app-b (on b). */
+const ROOTS = [
+  { name: "net" },
+  { name: "a", dependsOn: ["net"] },
+  { name: "b", dependsOn: ["net"] },
+  { name: "app-a", dependsOn: ["a"] },
+  { name: "app-b", dependsOn: ["b"] },
+];
+
+describe("layerWaves", () => {
+  test("dependency order, each wave sorted", () => {
+    expect(layerWaves(ROOTS)).toEqual([["net"], ["a", "b"], ["app-a", "app-b"]]);
+  });
+
+  test("a canary list is wave 1 whatever the graph order, and the rest follow the graph", () => {
+    expect(layerWaves(ROOTS, { canary: ["app-b"] })).toEqual([["app-b"], ["net"], ["a", "b"], ["app-a"]]);
+    expect(layerWaves(ROOTS, { canary: ["b", "net"] })).toEqual([["b", "net"], ["a", "app-b"], ["app-a"]]);
+  });
+
+  test("a dependency outside the set does not hold a node back", () => {
+    expect(layerWaves([{ name: "a", dependsOn: ["net"] }, { name: "app-a", dependsOn: ["a"] }])).toEqual([["a"], ["app-a"]]);
+  });
+
+  test("a canary that is not in the set is refused, unless it is known and just not changing", () => {
+    expect(() => layerWaves(ROOTS, { canary: ["nope"] })).toThrow(UnknownCanaryError);
+    expect(layerWaves(ROOTS.slice(0, 2), { canary: ["app-b"], known: ["app-b"] })).toEqual([["net"], ["a"]]);
+  });
+
+  test("a cycle is refused by name", () => {
+    expect(() => layerWaves([{ name: "x", dependsOn: ["y"] }, { name: "y", dependsOn: ["x"] }])).toThrow(WaveCycleError);
+  });
+});
+
+describe("the set digest", () => {
+  const members = [
+    { member: "net", planDigest: "jcs1-sha256:" + "1".repeat(64) },
+    { member: "a", planDigest: "jcs1-sha256:" + "2".repeat(64) },
+  ];
+
+  test("is the change-set digest of the wave's members", () => {
+    expect(waveSetDigest(members)).toBe(changeSetDigest(members));
+    expect(waveSetDigest(members)).toMatch(/^jcs1-sha256:[0-9a-f]{64}$/);
+  });
+
+  test("does not depend on order and moves when one root's plan does", () => {
+    expect(waveSetDigest([...members].reverse())).toBe(waveSetDigest(members));
+    expect(waveSetDigest([members[0], { member: "a", planDigest: "jcs1-sha256:" + "3".repeat(64) }])).not.toBe(
+      waveSetDigest(members),
+    );
+  });
+
+  test("refuses a wave that names one root twice", () => {
+    expect(() => waveSetDigest([members[0], members[0]])).toThrow(/twice/);
+  });
+
+  test("refuses a wave holding a provisional plan, by name", () => {
+    expect(() => waveSetDigest([members[0], { ...members[1], provisional: true }])).toThrow(ProvisionalWaveMemberError);
+    expect(() => waveSetDigest([members[0], { ...members[1], provisional: true }])).toThrow(/provisional plan: a planned/);
+  });
+});
+
+describe("wave records", () => {
+  const record: WaveRecord = {
+    wave: 2,
+    op: "fan-out",
+    gate: waveGateName("release", 2),
+    components: ["a", "b"],
+    digest: "jcs1-sha256:" + "4".repeat(64),
+    members: [{ member: "a", planDigest: "jcs1-sha256:" + "5".repeat(64) }],
+    status: "gated",
+    approved: "jcs1-sha256:" + "6".repeat(64),
+  };
+
+  test("each wave has its own gate", () => {
+    expect(waveGateName("release", 1)).toBe("release-wave-1");
+    expect(waveGateName("release", 1)).not.toBe(waveGateName("release", 2));
+  });
+
+  test("round-trip through JSON, dropping malformed entries", () => {
+    const read = readWaveRecords(JSON.parse(JSON.stringify([record, { wave: "x" }, null])));
+    expect(read).toEqual([record]);
+    expect(readWaveRecords(undefined)).toEqual([]);
+  });
+
+  test("a later record for the same wave replaces the earlier one", () => {
+    const applied: WaveRecord = { ...record, status: "applied", approvedBy: "ana" };
+    delete applied.approved;
+    expect(withWaveRecord([record], applied)).toEqual([applied]);
+  });
+
+  test("the changed-set refusal names both digests and says nothing applied", () => {
+    const line = describeChangedWave(record);
+    expect(line).toContain(record.approved);
+    expect(line).toContain(record.digest);
+    expect(line).toContain("nothing in it was applied");
+    expect(line).toContain("chant approve fan-out release-wave-2 --plan");
+  });
+});

package/src/gated-waves.ts

@@ -0,0 +1,240 @@
+/**
+ * Gated waves (#3049): one change rolled out across many roots, a wave at a
+ * time, each wave behind its own gate bound to that wave's set digest.
+ *
+ * `chant components fan-out --wave-gate` is the runner. This module holds the
+ * parts that need no runner: how a set of roots is cut into waves, what a
+ * wave's digest is, what its gate is called, and what the attempt record says
+ * about each wave. They are kept apart from the runner because terragucci
+ * calls them from its CI stages as one bundled file with no TypeScript
+ * toolchain (#3421). Everything here imports `./change-set` and nothing else,
+ * and `gated-waves-bundle.test.ts` holds that.
+ *
+ * ## The set digest
+ *
+ * A wave's digest is {@link changeSetDigest} over its members' `{ member,
+ * planDigest }` pairs, the function #3181's change-set document uses. A
+ * terraform-family member is named after its root, so this is the issue's
+ * `jcs1-sha256` over sorted `{ root, planDigest }`, and a wave's digest equals
+ * the change-set digest of the wave's members. Each member's plan digest is
+ * the one a gate on that root alone binds (`terraformPlanDigest`, #2300), so a
+ * one-root wave and a one-root `TerraformApplyOp` approve the same value.
+ *
+ * ## Why a wave is planned when it is reached
+ *
+ * A later wave planned up front reads outputs that do not exist yet. Planned
+ * after the wave before it applied, its digest describes the real upstream
+ * values, which is what an approver of that wave is shown.
+ */
+
+import { changeSetDigest } from "./change-set";
+
+/** A root, or a component, as wave planning sees it: a name and what it reads. */
+export interface WaveNode {
+  name: string;
+  /** Names this node reads from. A name outside the node set is already satisfied. */
+  dependsOn?: readonly string[];
+}
+
+/** Thrown when a canary names something that is not in the set being planned. */
+export class UnknownCanaryError extends Error {
+  constructor(
+    readonly canary: string,
+    known: readonly string[],
+  ) {
+    super(`canary names "${canary}", which is not in this set (known: ${known.join(", ") || "none"})`);
+    this.name = "UnknownCanaryError";
+  }
+}
+
+/** Thrown when the nodes being layered depend on each other in a cycle. */
+export class WaveCycleError extends Error {
+  constructor(readonly members: string[]) {
+    super(`dependency cycle among: ${members.join(", ")}`);
+    this.name = "WaveCycleError";
+  }
+}
+
+export interface LayerWavesOptions {
+  /**
+   * Nodes that form wave 1 whatever the graph says (#3049). Only those in the
+   * set are placed; one outside it has nothing to apply. The rest follow in
+   * dependency order, and a dependency on a canary counts as satisfied by
+   * wave 1.
+   */
+  canary?: readonly string[];
+  /**
+   * Names known to exist outside `nodes`. A canary naming one of them is
+   * left out quietly, since it is real but not part of this change; any
+   * other unknown canary is refused. Defaults to `nodes` alone.
+   */
+  known?: readonly string[];
+}
+
+/**
+ * Cut `nodes` into ordered waves: each node lands after every node it reads
+ * from, and each wave is sorted by name so the same graph always produces the
+ * same waves. With a canary list, those nodes are wave 1.
+ *
+ * A dependency on a name outside `nodes` does not hold a node back. That is
+ * the subset case: the dependency already applied, or is not changing.
+ */
+export function layerWaves(nodes: readonly WaveNode[], options: LayerWavesOptions = {}): string[][] {
+  const names = new Set(nodes.map((n) => n.name));
+  const known = new Set([...names, ...(options.known ?? [])]);
+  for (const canary of options.canary ?? []) {
+    if (!known.has(canary)) throw new UnknownCanaryError(canary, [...known].sort());
+  }
+  const canaries = [...new Set((options.canary ?? []).filter((c) => names.has(c)))].sort();
+
+  const waves: string[][] = canaries.length > 0 ? [canaries] : [];
+  const remaining = new Set([...names].filter((n) => !canaries.includes(n)));
+  const deps = new Map(nodes.map((n) => [n.name, (n.dependsOn ?? []).filter((d) => remaining.has(d))]));
+  while (remaining.size > 0) {
+    const wave = [...remaining].filter((n) => deps.get(n)!.every((d) => !remaining.has(d))).sort();
+    if (wave.length === 0) throw new WaveCycleError([...remaining].sort());
+    for (const n of wave) remaining.delete(n);
+    waves.push(wave);
+  }
+  return waves;
+}
+
+/** One member of a wave: a root (or a component with no plannable step) and its plan digest. */
+export interface WaveMember {
+  member: string;
+  planDigest: string;
+  /** A provisional plan (`ChangeSetMember.provisional`, #3416). A wave refuses it. */
+  provisional?: true;
+}
+
+/** Thrown when a wave's members include a provisional plan, which no gate may bind. */
+export class ProvisionalWaveMemberError extends Error {
+  constructor(readonly members: string[]) {
+    super(
+      `a wave cannot be gated on a provisional plan: ${members.join(", ")} planned before what it reads applied. ` +
+        `Plan it again in its own wave, after its upstream applied`,
+    );
+    this.name = "ProvisionalWaveMemberError";
+  }
+}
+
+/**
+ * A wave's set digest: {@link changeSetDigest} over its members. Order does
+ * not matter, and it moves whenever one member's plan digest does. A wave
+ * naming one member twice has no digest and is refused, and so is a wave
+ * holding a provisional plan (#3416): a gate bound to it would approve
+ * values nobody has yet.
+ */
+export function waveSetDigest(members: readonly WaveMember[]): string {
+  const provisional = members.filter((m) => m.provisional === true).map((m) => m.member);
+  if (provisional.length > 0) throw new ProvisionalWaveMemberError([...new Set(provisional)].sort());
+  return changeSetDigest(members);
+}
+
+/**
+ * The gate a wave waits on: `<gate>-wave-<n>`, under the fan-out's op.
+ *
+ * One gate name per wave keeps each wave's approvals apart. With one name
+ * shared by every wave, wave 2 would find wave 1's approval and report it as
+ * an approval of another plan, which is true and useless. Wave numbers come
+ * from the derivation, not from what is left to run, so wave 3 stays wave 3
+ * on a resumed attempt and its approval still applies.
+ */
+export function waveGateName(gate: string, wave: number): string {
+  return `${gate}-wave-${wave}`;
+}
+
+/** Where a wave got to. */
+export type WaveStatus =
+  /** Planned, and its gate is not approved for this digest. Nothing in it ran. */
+  | "gated"
+  /** Every member applied. */
+  | "applied"
+  /** At least one member failed to plan or to apply. Its dependents are blocked. */
+  | "failed";
+
+/**
+ * One wave, as an attempt record and a run result carry it. The plan report
+ * (#3349) reads these and points at the gate record rather than copying it:
+ * `op` and `gate` name the ledger entry (`_gates/<op>.jsonl` on
+ * `chant/lifecycle`).
+ */
+export interface WaveRecord {
+  /** 1-based, from the derivation. */
+  wave: number;
+  op: string;
+  /** The full gate name, {@link waveGateName}. */
+  gate: string;
+  /** What was planned in this wave on this attempt. */
+  components: string[];
+  /** The set digest the gate was decided against. */
+  digest: string;
+  members: WaveMember[];
+  status: WaveStatus;
+  /** Who approved this digest, once the gate passed. */
+  approvedBy?: string;
+  /** When the gate refused because an approval stands for another digest: that digest. */
+  approved?: string;
+  /** Components that failed to plan or to apply, with why. */
+  failed?: Array<{ component: string; error?: string }>;
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+const strings = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((v): v is string => typeof v === "string") : [];
+
+/**
+ * Read the `waves` array of an attempt record, dropping anything malformed.
+ * A record written before #3049 has none, which reads as no waves.
+ */
+export function readWaveRecords(value: unknown): WaveRecord[] {
+  if (!Array.isArray(value)) return [];
+  const out: WaveRecord[] = [];
+  for (const raw of value) {
+    if (!isObject(raw)) continue;
+    const { wave, op, gate, digest, status } = raw;
+    if (typeof wave !== "number" || typeof op !== "string" || typeof gate !== "string" || typeof digest !== "string") continue;
+    if (status !== "gated" && status !== "applied" && status !== "failed") continue;
+    const members = Array.isArray(raw.members)
+      ? raw.members.filter(
+          (m): m is WaveMember => isObject(m) && typeof m.member === "string" && typeof m.planDigest === "string",
+        )
+      : [];
+    const failed = Array.isArray(raw.failed)
+      ? raw.failed
+          .filter((f): f is { component: string; error?: unknown } => isObject(f) && typeof f.component === "string")
+          .map((f) => ({ component: f.component, ...(typeof f.error === "string" ? { error: f.error } : {}) }))
+      : [];
+    out.push({
+      wave,
+      op,
+      gate,
+      components: strings(raw.components),
+      digest,
+      members: members.map((m) => ({ member: m.member, planDigest: m.planDigest })),
+      status,
+      ...(typeof raw.approvedBy === "string" ? { approvedBy: raw.approvedBy } : {}),
+      ...(typeof raw.approved === "string" ? { approved: raw.approved } : {}),
+      ...(failed.length > 0 ? { failed } : {}),
+    });
+  }
+  return out;
+}
+
+/** Put `record` in `records` in place of any earlier record for the same wave, sorted by wave. */
+export function withWaveRecord(records: readonly WaveRecord[], record: WaveRecord): WaveRecord[] {
+  return [...records.filter((r) => r.wave !== record.wave), record].sort((a, b) => a.wave - b.wave);
+}
+
+/**
+ * The refusal for a wave whose set changed after it was approved: the digest
+ * that was approved, the one planned now, and that nothing in the wave ran.
+ */
+export function describeChangedWave(record: Pick<WaveRecord, "wave" | "op" | "gate" | "digest" | "approved">): string {
+  return (
+    `wave ${record.wave} changed after it was approved, so nothing in it was applied. ` +
+    `approved: ${record.approved ?? "(none)"}; planned now: ${record.digest}. ` +
+    `Read the new plan, then approve it: chant approve ${record.op} ${record.gate} --plan ${record.digest}`
+  );
+}

package/src/graph-ir.test.ts

@@ -287,3 +287,86 @@ describe("entity-declared references and stacks", () => {
     expect(ir.nodes.find((n) => n.id === "app/vpc")!.attrs).not.toHaveProperty("stack");
   });
 });
+
+describe("whole declarables held in an entity's fields (#3257)", () => {
+  /** An entity shaped like the sql lexicon's: props non-enumerable, `dependsOn` enumerable. */
+  function holder(dependsOn: unknown[], extra: object = {}) {
+    const e = decl({ lexicon: "sql", entityType: "ClickHouse::Table", ...extra });
+    Object.defineProperty(e, "dependsOn", { value: dependsOn, enumerable: true });
+    return e;
+  }
+
+  test("draws an edge to each node named directly in an enumerable array", () => {
+    const db = decl({ lexicon: "sql", entityType: "ClickHouse::Database" });
+    const target = holder([db]);
+    const events = holder([db]);
+    const mv = holder([db, target, events]);
+    const entities = new Map<string, Declarable>([
+      ["analytics", db],
+      ["dailyActive", target],
+      ["events", events],
+      ["dailyActiveMv", mv],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    const dep = (from: string, to: string) => ({ from, to, kind: "ref", viaAttr: "dependsOn" });
+    expect(ir.edges).toEqual([
+      dep("dailyActive", "analytics"),
+      dep("dailyActiveMv", "analytics"),
+      dep("dailyActiveMv", "dailyActive"),
+      dep("dailyActiveMv", "events"),
+      dep("events", "analytics"),
+    ]);
+  });
+
+  test("does not walk into the referenced node, and projects it as a $ref", () => {
+    const db = decl({ lexicon: "sql", entityType: "ClickHouse::Database", props: { name: "analytics" } });
+    const events = holder([db]);
+    const entities = new Map<string, Declarable>([
+      ["analytics", db],
+      ["events", events],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.nodes.find((n) => n.id === "events")!.attrs.dependsOn).toEqual([{ $ref: "analytics" }]);
+  });
+
+  test("an AttrRef and the whole node to the same target collapse to one edge", () => {
+    const db = decl({ lexicon: "sql", entityType: "ClickHouse::Database" });
+    const events = decl({ lexicon: "sql", entityType: "ClickHouse::Table" });
+    const mv = holder([events, new AttrRef(events, "user_id")]);
+    const entities = new Map<string, Declarable>([
+      ["analytics", db],
+      ["events", events],
+      ["mv", mv],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.edges).toEqual([{ from: "mv", to: "events", kind: "ref", viaAttr: "dependsOn" }]);
+  });
+
+  test("ignores a self reference, and still descends into an inlined property-kind resource", () => {
+    const self: Declarable = holder([]);
+    (self as unknown as { dependsOn: unknown[] }).dependsOn.push(self);
+    const vpc = decl({ lexicon: "aws", entityType: "Vpc" });
+    const inline = decl({
+      lexicon: "aws",
+      entityType: "Listener_Action",
+      kind: "property",
+      props: { vpc: new AttrRef(vpc, "Id") },
+    });
+    const lb = decl({ lexicon: "aws", entityType: "Lb", props: { actions: [inline] } });
+    const entities = new Map<string, Declarable>([
+      ["self", self],
+      ["vpc", vpc],
+      ["lb", lb],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.edges).toEqual([{ from: "lb", to: "vpc", kind: "ref", viaAttr: "actions" }]);
+  });
+});