@intentius/chant 0.8.2 → 0.10.0

package/src/graph-lens.test.ts

@@ -0,0 +1,80 @@
+import { describe, test, expect } from "vitest";
+import { parseLens, applyLens } from "./graph-lens";
+import type { GraphIR } from "./graph-ir";
+
+// vpc <- subnet <- cluster (gcp), cluster <- pod (k8s). A linear dependency
+// chain crossing two lexicons.
+const ir: GraphIR = {
+  nodes: [
+    { id: "vpc", kind: "Vpc", lexicon: "gcp", attrs: {} },
+    { id: "subnet", kind: "Subnet", lexicon: "gcp", attrs: {} },
+    { id: "cluster", kind: "GkeCluster", lexicon: "gcp", attrs: {} },
+    { id: "pod", kind: "Pod", lexicon: "k8s", attrs: {} },
+  ],
+  edges: [
+    { from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" },
+    { from: "cluster", to: "subnet", kind: "ref", viaAttr: "subnetwork" },
+    { from: "pod", to: "cluster", kind: "ref", viaAttr: "cluster" },
+  ],
+  groups: { byLexicon: { gcp: ["cluster", "subnet", "vpc"], k8s: ["pod"] } },
+};
+
+describe("parseLens", () => {
+  test("parses kind:target", () => {
+    expect(parseLens("lexicon:gcp")).toMatchObject({ kind: "lexicon", target: "gcp" });
+  });
+  test("blast defaults to both directions", () => {
+    expect(parseLens("blast:cluster")).toMatchObject({ up: true, down: true });
+  });
+  test("blast honours --up / --down", () => {
+    expect(parseLens("blast:cluster", { up: true })).toMatchObject({ up: true, down: false });
+  });
+  test("rejects malformed and unknown lenses", () => {
+    expect(() => parseLens("gcp")).toThrow();
+    expect(() => parseLens("bogus:x")).toThrow();
+  });
+});
+
+describe("applyLens", () => {
+  test("lexicon: keeps only that lexicon's nodes and internal edges", () => {
+    const out = applyLens(ir, parseLens("lexicon:gcp"));
+    expect(out.nodes.map((n) => n.id).sort()).toEqual(["cluster", "subnet", "vpc"]);
+    // cross-lexicon pod→cluster edge dropped; gcp-internal edges kept
+    expect(out.edges.map((e) => `${e.from}->${e.to}`).sort()).toEqual([
+      "cluster->subnet",
+      "subnet->vpc",
+    ]);
+    expect(out.groups.byLexicon).toEqual({ gcp: ["cluster", "subnet", "vpc"] });
+  });
+
+  test("lexicon: count matches the byLexicon partition", () => {
+    const out = applyLens(ir, parseLens("lexicon:gcp"));
+    expect(out.nodes.length).toBe(ir.groups.byLexicon!.gcp.length);
+  });
+
+  test("blast --up returns the producer chain above a node", () => {
+    const out = applyLens(ir, parseLens("blast:cluster", { up: true }));
+    expect(out.nodes.map((n) => n.id).sort()).toEqual(["cluster", "subnet", "vpc"]);
+  });
+
+  test("blast --down returns the dependents below a node", () => {
+    const out = applyLens(ir, parseLens("blast:cluster", { down: true }));
+    expect(out.nodes.map((n) => n.id).sort()).toEqual(["cluster", "pod"]);
+  });
+
+  test("blast both returns the whole connected chain", () => {
+    const out = applyLens(ir, parseLens("blast:cluster"));
+    expect(out.nodes.map((n) => n.id).sort()).toEqual(["cluster", "pod", "subnet", "vpc"]);
+  });
+
+  test("blast on a leaf returns just its chain", () => {
+    const out = applyLens(ir, parseLens("blast:vpc", { up: true }));
+    expect(out.nodes.map((n) => n.id)).toEqual(["vpc"]); // vpc depends on nothing
+    expect(out.edges).toEqual([]);
+  });
+
+  test("throws when the target matches nothing", () => {
+    expect(() => applyLens(ir, parseLens("lexicon:aws"))).toThrow();
+    expect(() => applyLens(ir, parseLens("blast:ghost"))).toThrow();
+  });
+});

package/src/graph-lens.ts

@@ -0,0 +1,127 @@
+import type { GraphIR, IRNode, IREdge } from "./graph-ir";
+
+/**
+ * Lenses — focus the graph IR on a slice without touching the source. Pure
+ * IR → IR filters, composable with detail tiers (apply a lens, then view the
+ * result at any `--detail`). See issue #495 / epic #492.
+ *
+ * - `lexicon:<name>` — only nodes in a lexicon
+ * - `stack:<name>`   — only one stack's nodes (stacks map to lexicon partitions today)
+ * - `blast:<nodeId>` — the transitive neighbourhood of a node: what it depends
+ *   on (`--up`), what depends on it (`--down`), or both (default)
+ *
+ * Every lens drops edges that would dangle and rebuilds group metadata from the
+ * surviving nodes, so the result is always a self-consistent graph.
+ */
+export interface LensSpec {
+  kind: "lexicon" | "stack" | "blast";
+  target: string;
+  /** blast: include upstream producers (what the node depends on). */
+  up: boolean;
+  /** blast: include downstream dependents (what depends on the node). */
+  down: boolean;
+}
+
+const KINDS = new Set(["lexicon", "stack", "blast"]);
+
+/** Parse a `--lens` spec. Throws a descriptive Error on a malformed spec. */
+export function parseLens(spec: string, opts: { up?: boolean; down?: boolean } = {}): LensSpec {
+  const colon = spec.indexOf(":");
+  if (colon <= 0 || colon === spec.length - 1) {
+    throw new Error(`Invalid --lens "${spec}". Expected <kind>:<target>, e.g. lexicon:gcp or blast:vpc.`);
+  }
+  const kind = spec.slice(0, colon);
+  const target = spec.slice(colon + 1);
+  if (!KINDS.has(kind)) {
+    throw new Error(`Unknown lens "${kind}". Expected one of: ${[...KINDS].join(", ")}.`);
+  }
+  // For blast, default to both directions when neither flag is given.
+  const both = !opts.up && !opts.down;
+  return {
+    kind: kind as LensSpec["kind"],
+    target,
+    up: opts.up ?? both,
+    down: opts.down ?? both,
+  };
+}
+
+/** Apply a lens to the IR. Throws a descriptive Error when the target matches nothing. */
+export function applyLens(ir: GraphIR, lens: LensSpec): GraphIR {
+  const keep =
+    lens.kind === "blast" ? blastSet(ir, lens) : partitionSet(ir, lens);
+  return subgraph(ir, keep);
+}
+
+/** Node ids for a lexicon/stack lens. */
+function partitionSet(ir: GraphIR, lens: LensSpec): Set<string> {
+  if (lens.kind === "stack") {
+    const members = ir.groups.byStack?.[lens.target] ?? ir.groups.byLexicon?.[lens.target];
+    if (members && members.length) return new Set(members);
+    // Fall through to a direct scan if groups are absent.
+  }
+  const keep = new Set<string>();
+  for (const n of ir.nodes) if (n.lexicon === lens.target) keep.add(n.id);
+  if (keep.size === 0) {
+    throw new Error(`No nodes match lens ${lens.kind}:${lens.target}.`);
+  }
+  return keep;
+}
+
+/** Node ids in the transitive neighbourhood of a node. */
+function blastSet(ir: GraphIR, lens: LensSpec): Set<string> {
+  if (!ir.nodes.some((n) => n.id === lens.target)) {
+    throw new Error(`No node "${lens.target}" for lens blast:${lens.target}.`);
+  }
+  const out = new Map<string, string[]>(); // from -> [to]  (depends-on)
+  const inc = new Map<string, string[]>(); // to -> [from]  (depended-on-by)
+  const push = (m: Map<string, string[]>, k: string, v: string): void => {
+    const arr = m.get(k);
+    if (arr) arr.push(v);
+    else m.set(k, [v]);
+  };
+  for (const e of ir.edges) {
+    push(out, e.from, e.to);
+    push(inc, e.to, e.from);
+  }
+  const keep = new Set<string>([lens.target]);
+  if (lens.up) walk(lens.target, out, keep);
+  if (lens.down) walk(lens.target, inc, keep);
+  return keep;
+}
+
+function walk(start: string, adj: Map<string, string[]>, keep: Set<string>): void {
+  const stack = [start];
+  while (stack.length) {
+    const cur = stack.pop()!;
+    for (const next of adj.get(cur) ?? []) {
+      if (!keep.has(next)) {
+        keep.add(next);
+        stack.push(next);
+      }
+    }
+  }
+}
+
+/** Restrict the IR to a node set: keep internal edges, rebuild groups. */
+function subgraph(ir: GraphIR, keep: Set<string>): GraphIR {
+  const nodes: IRNode[] = ir.nodes.filter((n) => keep.has(n.id));
+  const edges: IREdge[] = ir.edges.filter((e) => keep.has(e.from) && keep.has(e.to));
+
+  const byLexicon: Record<string, string[]> = {};
+  const byComposite: Record<string, string[]> = {};
+  for (const n of nodes) {
+    (byLexicon[n.lexicon] ??= []).push(n.id);
+    if (n.compositeInstance) (byComposite[n.compositeInstance] ??= []).push(n.id);
+  }
+  const groups: GraphIR["groups"] = {};
+  if (Object.keys(byLexicon).length) groups.byLexicon = sortGroups(byLexicon);
+  if (Object.keys(byComposite).length) groups.byComposite = sortGroups(byComposite);
+
+  return { nodes, edges, groups };
+}
+
+function sortGroups(rec: Record<string, string[]>): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const k of Object.keys(rec).sort()) out[k] = rec[k].sort();
+  return out;
+}

package/src/graph-mermaid.test.ts

@@ -0,0 +1,61 @@
+import { describe, test, expect } from "vitest";
+import { toMermaid } from "./graph-mermaid";
+import type { GraphIR } from "./graph-ir";
+
+const ir: GraphIR = {
+  nodes: [
+    { id: "vpc", kind: "Vpc", lexicon: "gcp", attrs: {} },
+    { id: "subnet", kind: "Subnet", lexicon: "gcp", attrs: {} },
+    { id: "ns", kind: "Namespace", lexicon: "k8s", attrs: {} },
+  ],
+  edges: [
+    { from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" },
+    { from: "ns", to: "subnet", kind: "ref", viaAttr: "subnet", toAttr: "selfLink" },
+  ],
+  groups: { byLexicon: { gcp: ["subnet", "vpc"], k8s: ["ns"] } },
+};
+
+describe("toMermaid", () => {
+  test("renders a flowchart with lexicon subgraphs, nodes, and labelled edges", () => {
+    const out = toMermaid(ir);
+    expect(out).toContain("flowchart TD");
+    expect(out).toContain('subgraph lex_gcp["gcp"]');
+    expect(out).toContain('subgraph lex_k8s["k8s"]');
+    // node label = name + kind on two lines
+    expect(out).toContain('vpc["vpc<br/>Vpc"]');
+    // edge with consumer-property label
+    expect(out).toContain("subnet -->|\"network\"| vpc");
+    // T3 edge shows consumer → producer attribute
+    expect(out).toContain('ns -->|"subnet → selfLink"| subnet');
+  });
+
+  test("is deterministic", () => {
+    expect(toMermaid(ir)).toEqual(toMermaid(ir));
+  });
+
+  test("sanitizes ids that aren't Mermaid-safe but keeps the human label", () => {
+    const dirty: GraphIR = {
+      nodes: [
+        { id: "east/db-0", kind: "StatefulSet", lexicon: "k8s", attrs: {} },
+        { id: "east/db-1", kind: "StatefulSet", lexicon: "k8s", attrs: {} },
+      ],
+      edges: [{ from: "east/db-1", to: "east/db-0", kind: "ref" }],
+      groups: {},
+    };
+    const out = toMermaid(dirty);
+    // ids are sanitized and unique
+    expect(out).toContain('east_db_0["east/db-0<br/>StatefulSet"]');
+    expect(out).toContain('east_db_1["east/db-1<br/>StatefulSet"]');
+    expect(out).toContain("east_db_1 --> east_db_0");
+  });
+
+  test("places ungrouped nodes at the top level", () => {
+    const out = toMermaid({
+      nodes: [{ id: "loner", kind: "Thing", lexicon: "x", attrs: {} }],
+      edges: [],
+      groups: {},
+    });
+    expect(out).toContain('loner["loner<br/>Thing"]');
+    expect(out).not.toContain("subgraph");
+  });
+});

package/src/graph-mermaid.ts

@@ -0,0 +1,85 @@
+import type { GraphIR, IRNode, IREdge } from "./graph-ir";
+
+/**
+ * Render the graph IR as a Mermaid `flowchart`. Mermaid is the zero-install
+ * default — it renders in GitHub, docs, and browsers with no native dependency,
+ * so `chant graph --format mermaid` gives a diagram out of the box without the
+ * standalone painter. Lower fidelity than a custom painter, but portable.
+ *
+ * Consumes whatever IR it is given, so it honours `--detail` and `--lens` for
+ * free (those are IR → IR transforms). See issue #496 / epic #492.
+ *
+ * Known limits: Mermaid owns layout, so there is little control over node
+ * placement, and very large graphs get hard to read — that is the trade-off for
+ * zero-install portability. Reach for the graphviz/custom-painter path (#497,
+ * pinhole) when fidelity matters.
+ */
+export function toMermaid(ir: GraphIR): string {
+  const ids = new Map<string, string>(); // logical name -> mermaid-safe id
+  for (const n of ir.nodes) safeId(n.id, ids);
+
+  const lines: string[] = ["flowchart TD"];
+
+  // Cluster by lexicon when grouping is available; nodes outside any group fall
+  // through to the top level. byLexicon is sorted, so output is deterministic.
+  const byLexicon = ir.groups.byLexicon;
+  const grouped = new Set<string>();
+  if (byLexicon) {
+    for (const [lexicon, members] of Object.entries(byLexicon)) {
+      lines.push(`  subgraph ${safeId(`lex_${lexicon}`, ids)}[${quote(lexicon)}]`);
+      for (const id of members) {
+        const node = ir.nodes.find((n) => n.id === id);
+        if (!node) continue;
+        grouped.add(id);
+        lines.push(`    ${nodeLine(node, ids)}`);
+      }
+      lines.push("  end");
+    }
+  }
+  for (const node of ir.nodes) {
+    if (grouped.has(node.id)) continue;
+    lines.push(`  ${nodeLine(node, ids)}`);
+  }
+
+  for (const e of ir.edges) {
+    lines.push(`  ${edgeLine(e, ids)}`);
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+function nodeLine(node: IRNode, ids: Map<string, string>): string {
+  const id = safeId(node.id, ids);
+  const parts = [node.id];
+  if (node.kind && node.kind !== node.id) parts.push(node.kind);
+  return `${id}[${quote(parts.join("\n"))}]`;
+}
+
+function edgeLine(e: IREdge, ids: Map<string, string>): string {
+  const from = safeId(e.from, ids);
+  const to = safeId(e.to, ids);
+  const label = [e.viaAttr, e.toAttr].filter(Boolean).join(" → ");
+  return label ? `${from} -->|${quote(label)}| ${to}` : `${from} --> ${to}`;
+}
+
+/** Map an arbitrary logical name to a stable, unique Mermaid-safe node id. */
+function safeId(raw: string, ids: Map<string, string>): string {
+  const existing = ids.get(raw);
+  if (existing) return existing;
+  let base = raw.replace(/[^A-Za-z0-9_]/g, "_");
+  if (base === "" || /^[0-9]/.test(base)) base = `n_${base}`;
+  const taken = new Set(ids.values());
+  let candidate = base;
+  let i = 1;
+  while (taken.has(candidate)) candidate = `${base}_${i++}`;
+  ids.set(raw, candidate);
+  return candidate;
+}
+
+/** Quote a Mermaid label, escaping markup and turning newlines into <br/>. */
+function quote(text: string): string {
+  const esc = (s: string): string =>
+    s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const body = text.split("\n").map(esc).join("<br/>");
+  return `"${body}"`;
+}

package/src/index.ts

@@ -25,6 +25,12 @@ export * from "./discovery/graph";
 export * from "./discovery/index";
 export * from "./discovery/cache";
 export * from "./build";
+export * from "./graph-ir";
+export * from "./graph-detail";
+export * from "./graph-mermaid";
+export * from "./graph-dot";
+export * from "./graph-layout";
+export * from "./graph-lens";
 export * from "./detectLexicon";
 export * from "./lint/parser";
 export * from "./lint/rule";

package/src/provenance.ts

@@ -15,8 +15,15 @@ const PROVENANCE = Symbol.for("chant.provenance");
 export interface EntityProvenance {
   /** Absolute path of the source file that declared (or exported) the entity. */
   sourceFile?: string;
-  /** The composite that expanded this entity, when it came from one. */
+  /** The composite (type) that expanded this entity, when it came from one. */
   composite?: string;
+  /**
+   * The composite *instance* this entity belongs to — the export name of the
+   * top-level composite, shared by every member it expanded to. Distinguishes
+   * two instances of the same composite type, which `composite` cannot. Used to
+   * collapse a composite to a single node at coarse diagram detail levels (#494).
+   */
+  compositeInstance?: string;
 }
 
 /**
@@ -30,6 +37,7 @@ export function setProvenance(entity: object, prov: EntityProvenance): void {
   if (existing) {
     existing.sourceFile ??= prov.sourceFile;
     existing.composite ??= prov.composite;
+    existing.compositeInstance ??= prov.compositeInstance;
     return;
   }
   Object.defineProperty(entity, PROVENANCE, {

package/src/reconcile.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Tests for the provider-agnostic reconcile primitive.
+ *
+ * Pure unit tests over the generic primitives — no provider types, no I/O.
+ */
+
+import { describe, expect, test } from "vitest";
+import {
+  deepEqual,
+  diffFields,
+  diffCollection,
+  summarizeChangeSet,
+  renderChangeSet,
+  resolveRenames,
+  removalDeltaCap,
+  runGuardrailChecks,
+} from "./reconcile";
+import type { ChangeSet, ChangeSetEntry, DiffOptions, GuardrailCheck } from "./reconcile";
+
+const noOpts: DiffOptions = {};
+
+// ---------------------------------------------------------------------------
+// deepEqual / diffFields
+// ---------------------------------------------------------------------------
+
+describe("deepEqual", () => {
+  test("compares primitives and nested structures", () => {
+    expect(deepEqual(1, 1)).toBe(true);
+    expect(deepEqual("a", "b")).toBe(false);
+    expect(deepEqual({ a: [1, 2] }, { a: [1, 2] })).toBe(true);
+    expect(deepEqual({ a: 1 }, { a: 2 })).toBe(false);
+    expect(deepEqual(null, undefined)).toBe(false);
+  });
+});
+
+describe("diffFields", () => {
+  test("compares every key of desired when no key list is given", () => {
+    expect(diffFields({ a: 1, b: 2 }, { a: 1, b: 9 })).toEqual([{ field: "b", before: 9, after: 2 }]);
+  });
+
+  test("compares only listed keys present in desired", () => {
+    expect(diffFields({ a: 1, b: 2 }, { a: 9, b: 9 }, ["a"])).toEqual([{ field: "a", before: 9, after: 1 }]);
+  });
+
+  test("ignores listed keys absent from desired (selective-by-omission)", () => {
+    expect(diffFields({ a: 1 }, { a: 1, b: 2 }, ["a", "b"])).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// diffCollection
+// ---------------------------------------------------------------------------
+
+interface D {
+  name: string;
+  v?: number;
+}
+interface L {
+  name: string;
+  v?: number;
+}
+
+function runCollection(desired: D[], live: L[], opts: DiffOptions = noOpts): ChangeSetEntry[] {
+  const out: ChangeSetEntry[] = [];
+  diffCollection<D, L>({
+    resourceType: "thing",
+    keyPrefix: "p/",
+    desired: new Map(desired.map((d) => [d.name, d])),
+    live: new Map(live.map((l) => [l.name, l])),
+    compareFields: (d, l) => (d.v !== l.v ? [{ field: "v", before: l.v, after: d.v }] : []),
+    opts,
+    out,
+  });
+  return out;
+}
+
+describe("diffCollection", () => {
+  test("creates entries for desired-not-live (with key prefix)", () => {
+    const out = runCollection([{ name: "a", v: 1 }], []);
+    expect(out).toEqual([{ kind: "create", resourceType: "thing", key: "p/a", after: { name: "a", v: 1 } }]);
+  });
+
+  test("updates when compareFields reports differences", () => {
+    const out = runCollection([{ name: "a", v: 2 }], [{ name: "a", v: 1 }]);
+    expect(out[0]!.kind).toBe("update");
+    expect(out[0]!.fields).toEqual([{ field: "v", before: 1, after: 2 }]);
+  });
+
+  test("emits no entry when live matches desired", () => {
+    expect(runCollection([{ name: "a", v: 1 }], [{ name: "a", v: 1 }])).toEqual([]);
+  });
+
+  test("only deletes live-not-desired when ownership-gated", () => {
+    const live = [
+      { name: "a", v: 1 },
+      { name: "stray", v: 9 },
+    ];
+    expect(runCollection([{ name: "a", v: 1 }], live)).toEqual([]); // no predicate
+    const owned = runCollection([{ name: "a", v: 1 }], live, { isOwned: (_t, k) => k === "p/stray" });
+    expect(owned).toEqual([
+      { kind: "delete", resourceType: "thing", key: "p/stray", before: { name: "stray", v: 9 } },
+    ]);
+  });
+
+  test("honours createAfter / updateAfter mappers", () => {
+    const out: ChangeSetEntry[] = [];
+    diffCollection<D, L>({
+      resourceType: "thing",
+      desired: new Map([["a", { name: "a", v: 5 }]]),
+      live: new Map(),
+      compareFields: () => [],
+      createAfter: (key, d) => ({ normalized: key, v: d.v }),
+      opts: noOpts,
+      out,
+    });
+    expect(out[0]!.after).toEqual({ normalized: "a", v: 5 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// summarize / render
+// ---------------------------------------------------------------------------
+
+describe("summarizeChangeSet / renderChangeSet", () => {
+  const cs: ChangeSet = {
+    org: "acme",
+    entries: [
+      { kind: "create", resourceType: "thing", key: "a" },
+      { kind: "update", resourceType: "thing", key: "b", fields: [{ field: "v", before: 1, after: 2 }] },
+      { kind: "delete", resourceType: "thing", key: "c" },
+    ],
+  };
+
+  test("counts entries by kind", () => {
+    expect(summarizeChangeSet(cs)).toEqual({ create: 1, update: 1, delete: 1 });
+  });
+
+  test("renders a readable plan with the scope id and field changes", () => {
+    const out = renderChangeSet(cs);
+    expect(out).toContain("Plan for acme: 1 to create, 1 to update, 1 to delete");
+    expect(out).toContain("[thing] b");
+    expect(out).toContain("v: 1 → 2");
+  });
+
+  test("renders 'No changes.' for an empty set", () => {
+    expect(renderChangeSet({ org: "acme", entries: [] })).toContain("No changes.");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Guardrail framework
+// ---------------------------------------------------------------------------
+
+describe("resolveRenames", () => {
+  test("collapses delete(previously)+create(key) into one update", () => {
+    const cs: ChangeSet = {
+      org: "acme",
+      entries: [
+        { kind: "delete", resourceType: "team", key: "old", before: { slug: "old" } },
+        { kind: "create", resourceType: "team", key: "new", after: { previously: "old" } },
+      ],
+    };
+    const resolved = resolveRenames(cs);
+    expect(resolved.entries.some((e) => e.kind === "delete")).toBe(false);
+    const update = resolved.entries.find((e) => e.kind === "update")!;
+    expect(update.key).toBe("new");
+    expect(update.before).toEqual({ slug: "old" });
+  });
+
+  test("is a no-op without a matching previously alias", () => {
+    const cs: ChangeSet = { org: "acme", entries: [{ kind: "delete", resourceType: "team", key: "old" }] };
+    expect(resolveRenames(cs)).toBe(cs);
+  });
+});
+
+describe("removalDeltaCap", () => {
+  test("trips when deletes exceed the fraction of pre-existing entries", () => {
+    const cs: ChangeSet = {
+      org: "acme",
+      entries: Array.from({ length: 4 }, (_, i) => ({
+        kind: "delete" as const,
+        resourceType: "x",
+        key: `k${i}`,
+      })),
+    };
+    expect(removalDeltaCap(cs)!.guardrail).toBe("removalDeltaCap");
+  });
+
+  test("excludes creates from the denominator and passes under the cap", () => {
+    const cs: ChangeSet = {
+      org: "acme",
+      entries: [
+        { kind: "delete", resourceType: "x", key: "d" },
+        { kind: "update", resourceType: "x", key: "u1" },
+        { kind: "update", resourceType: "x", key: "u2" },
+        { kind: "update", resourceType: "x", key: "u3" },
+        { kind: "create", resourceType: "x", key: "c" },
+      ],
+    };
+    expect(removalDeltaCap(cs)).toBeNull(); // 1/4 = 25%, not > 25%
+  });
+});
+
+describe("runGuardrailChecks", () => {
+  test("resolves renames once and aggregates failing checks", () => {
+    const cs: ChangeSet = {
+      org: "acme",
+      entries: [
+        { kind: "delete", resourceType: "x", key: "a" },
+        { kind: "delete", resourceType: "x", key: "b" },
+      ],
+    };
+    const failing: GuardrailCheck = (resolved) => removalDeltaCap(resolved);
+    const passing: GuardrailCheck = () => null;
+    const result = runGuardrailChecks(cs, [failing, passing]);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.diagnostics).toHaveLength(1);
+  });
+
+  test("returns ok when every check passes", () => {
+    const cs: ChangeSet = { org: "acme", entries: [{ kind: "create", resourceType: "x", key: "a" }] };
+    expect(runGuardrailChecks(cs, [() => null])).toEqual({ ok: true });
+  });
+});