@intentius/chant 0.44.14 → 0.46.0

package/src/codegen/surface-snapshot.ts

@@ -72,8 +72,8 @@ export interface RemovedEntry {
   entry: SurfaceEntry;
 }
 
-export interface ChangedEntry {
-  name: string;
+/** Structural differences between two versions of one entry. */
+export interface EntryChanges {
   /** New resourceType (breaking). */
   resourceTypeChanged?: { before: string; after: string };
   /** kind changed from resource to property or vice-versa (breaking). */
@@ -96,14 +96,40 @@ export interface ChangedEntry {
   taggableChanged?: { before?: boolean; after?: boolean };
 }
 
+export interface ChangedEntry extends EntryChanges {
+  name: string;
+}
+
+/**
+ * An entry whose TS export name changed while its kind and resourceType
+ * stayed the same (#1460). Paired from one removal and one addition.
+ */
+export interface RenamedEntry {
+  /** TS export name in the baseline. */
+  from: string;
+  /** TS export name in the fresh surface. */
+  to: string;
+  /** The entry as it now appears. */
+  entry: SurfaceEntry;
+  /** Structural differences between the two, when any. */
+  changes?: EntryChanges;
+}
+
 export interface SurfaceDelta {
   added: AddedEntry[];
   changed: ChangedEntry[];
   removed: RemovedEntry[];
+  /**
+   * Removals and additions paired by kind + resourceType. A rename still
+   * breaks the old import, so it counts as breaking; it is reported apart
+   * from removals so a reader can tell the two kinds of break apart.
+   */
+  renamed: RenamedEntry[];
   /**
    * Rolled-up severity. "none" means no surface changes at all.
    * "additive" means only new resources / new optional props / new attrs.
-   * "breaking" means any removal or change that could break existing consumers.
+   * "breaking" means any removal, rename, or change that could break
+   * existing consumers.
    */
   severity: ChangeSeverity;
 }
@@ -314,9 +340,9 @@ export function extractPropsFromDts(dts: string): Map<string, string[]> {
  *   - taggable: false→true or undefined→true → additive
  */
 export function diffSurface(baseline: SurfaceSnapshot, fresh: SurfaceSnapshot): SurfaceDelta {
-  const added: AddedEntry[] = [];
   const changed: ChangedEntry[] = [];
-  const removed: RemovedEntry[] = [];
+  let added: AddedEntry[] = [];
+  let removed: RemovedEntry[] = [];
 
   const baseNames = new Set(Object.keys(baseline.entries));
   const freshNames = new Set(Object.keys(fresh.entries));
@@ -335,119 +361,253 @@ export function diffSurface(baseline: SurfaceSnapshot, fresh: SurfaceSnapshot):
     }
   }
 
+  // Renamed (#1460): a removal and an addition that carry the same
+  // resourceType and kind are one entry under a new TS name. Pair them
+  // before classifying so the report shows what upstream actually did.
+  const renamed: RenamedEntry[] = [];
+  const paired = pairRenames(removed, added);
+  for (const { from, to } of paired) {
+    const entry: RenamedEntry = { from: from.name, to: to.name, entry: to.entry };
+    const changes = diffEntries(from.entry, to.entry);
+    if (changes) entry.changes = changes;
+    renamed.push(entry);
+  }
+  if (paired.length > 0) {
+    const fromNames = new Set(paired.map((p) => p.from.name));
+    const toNames = new Set(paired.map((p) => p.to.name));
+    removed = removed.filter((r) => !fromNames.has(r.name));
+    added = added.filter((a) => !toNames.has(a.name));
+  }
+  renamed.sort((a, b) => a.from.localeCompare(b.from));
+
   // Changed
   for (const name of baseNames) {
     if (!freshNames.has(name)) continue;
+    const changes = diffEntries(baseline.entries[name], fresh.entries[name]);
+    if (changes) changed.push({ name, ...changes });
+  }
 
-    const before = baseline.entries[name];
-    const after = fresh.entries[name];
+  // Severity
+  let severity: ChangeSeverity = "none";
 
-    const change: ChangedEntry = { name };
-    let hasChange = false;
+  if (added.length > 0) {
+    severity = "additive";
+  }
 
-    if (before.resourceType !== after.resourceType) {
-      change.resourceTypeChanged = { before: before.resourceType, after: after.resourceType };
-      hasChange = true;
-    }
+  // Additive-only changes in the changed[] set
+  const hasAdditiveChanges = changed.some(isAdditiveChange);
 
-    if (before.kind !== after.kind) {
-      change.kindChanged = { before: before.kind, after: after.kind };
-      hasChange = true;
-    }
+  if (hasAdditiveChanges && severity === "none") {
+    severity = "additive";
+  }
 
-    // Props diff (only meaningful for resource entries)
-    const beforeProps = new Map(
-      (before.props ?? []).map((p) => {
-        const [nm, req] = splitProp(p);
-        return [nm, req === "true"];
-      }),
-    );
-    const afterProps = new Map(
-      (after.props ?? []).map((p) => {
-        const [nm, req] = splitProp(p);
-        return [nm, req === "true"];
-      }),
-    );
+  // A rename is still breaking for the consumer: the old import no longer
+  // resolves, whether the entry is a resource or a property type. It is
+  // reported separately so the reader can tell a rename from a deletion.
+  const hasBreaking =
+    removed.length > 0 ||
+    renamed.length > 0 ||
+    changed.some(isBreakingChange);
 
-    const removedProps = [...beforeProps.keys()].filter((k) => !afterProps.has(k));
-    const addedProps = [...afterProps.keys()].filter((k) => !beforeProps.has(k));
-    const nowRequired = [...beforeProps.keys()].filter(
-      (k) => afterProps.has(k) && !beforeProps.get(k) && afterProps.get(k),
-    );
-    const nowOptional = [...beforeProps.keys()].filter(
-      (k) => afterProps.has(k) && beforeProps.get(k) && !afterProps.get(k),
-    );
+  if (hasBreaking) severity = "breaking";
 
-    if (removedProps.length > 0) { change.removedProps = removedProps.sort(); hasChange = true; }
-    if (addedProps.length > 0) { change.addedProps = addedProps.sort(); hasChange = true; }
-    if (nowRequired.length > 0) { change.nowRequired = nowRequired.sort(); hasChange = true; }
-    if (nowOptional.length > 0) { change.nowOptional = nowOptional.sort(); hasChange = true; }
-
-    // Attrs diff
-    const beforeAttrs = new Set(before.attrs ?? []);
-    const afterAttrs = new Set(after.attrs ?? []);
-    const removedAttrs = [...beforeAttrs].filter((a) => !afterAttrs.has(a));
-    const addedAttrs = [...afterAttrs].filter((a) => !beforeAttrs.has(a));
-    if (removedAttrs.length > 0) { change.removedAttrs = removedAttrs.sort(); hasChange = true; }
-    if (addedAttrs.length > 0) { change.addedAttrs = addedAttrs.sort(); hasChange = true; }
-
-    // createOnly diff
-    const beforeCO = JSON.stringify((before.createOnly ?? []).sort());
-    const afterCO = JSON.stringify((after.createOnly ?? []).sort());
-    if (beforeCO !== afterCO) {
-      change.createOnlyChanged = {
-        before: before.createOnly ?? [],
-        after: after.createOnly ?? [],
-      };
-      hasChange = true;
-    }
+  return { added, changed, removed, renamed, severity };
+}
 
-    // taggable diff
-    if (before.taggable !== after.taggable) {
-      change.taggableChanged = { before: before.taggable, after: after.taggable };
-      hasChange = true;
-    }
+/**
+ * Diff two entries that are (or are taken to be) the same thing. Returns
+ * `null` when nothing differs.
+ */
+function diffEntries(before: SurfaceEntry, after: SurfaceEntry): EntryChanges | null {
+  const change: EntryChanges = {};
+  let hasChange = false;
 
-    if (hasChange) changed.push(change);
+  if (before.resourceType !== after.resourceType) {
+    change.resourceTypeChanged = { before: before.resourceType, after: after.resourceType };
+    hasChange = true;
   }
 
-  // Severity
-  let severity: ChangeSeverity = "none";
+  if (before.kind !== after.kind) {
+    change.kindChanged = { before: before.kind, after: after.kind };
+    hasChange = true;
+  }
 
-  if (added.length > 0) {
-    severity = "additive";
+  // Props diff (only meaningful for resource entries)
+  const beforeProps = new Map(
+    (before.props ?? []).map((p) => {
+      const [nm, req] = splitProp(p);
+      return [nm, req === "true"];
+    }),
+  );
+  const afterProps = new Map(
+    (after.props ?? []).map((p) => {
+      const [nm, req] = splitProp(p);
+      return [nm, req === "true"];
+    }),
+  );
+
+  const removedProps = [...beforeProps.keys()].filter((k) => !afterProps.has(k));
+  const addedProps = [...afterProps.keys()].filter((k) => !beforeProps.has(k));
+  const nowRequired = [...beforeProps.keys()].filter(
+    (k) => afterProps.has(k) && !beforeProps.get(k) && afterProps.get(k),
+  );
+  const nowOptional = [...beforeProps.keys()].filter(
+    (k) => afterProps.has(k) && beforeProps.get(k) && !afterProps.get(k),
+  );
+
+  if (removedProps.length > 0) { change.removedProps = removedProps.sort(); hasChange = true; }
+  if (addedProps.length > 0) { change.addedProps = addedProps.sort(); hasChange = true; }
+  if (nowRequired.length > 0) { change.nowRequired = nowRequired.sort(); hasChange = true; }
+  if (nowOptional.length > 0) { change.nowOptional = nowOptional.sort(); hasChange = true; }
+
+  // Attrs diff
+  const beforeAttrs = new Set(before.attrs ?? []);
+  const afterAttrs = new Set(after.attrs ?? []);
+  const removedAttrs = [...beforeAttrs].filter((a) => !afterAttrs.has(a));
+  const addedAttrs = [...afterAttrs].filter((a) => !beforeAttrs.has(a));
+  if (removedAttrs.length > 0) { change.removedAttrs = removedAttrs.sort(); hasChange = true; }
+  if (addedAttrs.length > 0) { change.addedAttrs = addedAttrs.sort(); hasChange = true; }
+
+  // createOnly diff
+  const beforeCO = JSON.stringify((before.createOnly ?? []).sort());
+  const afterCO = JSON.stringify((after.createOnly ?? []).sort());
+  if (beforeCO !== afterCO) {
+    change.createOnlyChanged = {
+      before: before.createOnly ?? [],
+      after: after.createOnly ?? [],
+    };
+    hasChange = true;
   }
 
-  // Additive-only changes in the changed[] set
-  const hasAdditiveChanges = changed.some((c) =>
+  // taggable diff
+  if (before.taggable !== after.taggable) {
+    change.taggableChanged = { before: before.taggable, after: after.taggable };
+    hasChange = true;
+  }
+
+  return hasChange ? change : null;
+}
+
+function isAdditiveChange(c: EntryChanges): boolean {
+  return (
     (c.addedProps?.length ?? 0) > 0 ||
     (c.nowOptional?.length ?? 0) > 0 ||
     (c.addedAttrs?.length ?? 0) > 0 ||
     // gaining tagging is additive
-    (c.taggableChanged !== undefined && c.taggableChanged.after === true && c.taggableChanged.before !== true),
+    (c.taggableChanged !== undefined && c.taggableChanged.after === true && c.taggableChanged.before !== true)
+  );
+}
+
+function isBreakingChange(c: EntryChanges): boolean {
+  return (
+    c.resourceTypeChanged !== undefined ||
+    c.kindChanged !== undefined ||
+    (c.removedProps?.length ?? 0) > 0 ||
+    (c.nowRequired?.length ?? 0) > 0 ||
+    (c.removedAttrs?.length ?? 0) > 0 ||
+    c.createOnlyChanged !== undefined ||
+    // losing taggable is breaking
+    (c.taggableChanged !== undefined && c.taggableChanged.before === true && c.taggableChanged.after !== true)
   );
+}
 
-  if (hasAdditiveChanges && severity === "none") {
-    severity = "additive";
+// ── Rename pairing ───────────────────────────────────────────────────
+
+interface RenamePair {
+  from: RemovedEntry;
+  to: AddedEntry;
+}
+
+/**
+ * Pair removed and added entries that share a kind and resourceType.
+ *
+ * One removal and one addition under a resourceType pair directly. When a
+ * resourceType has several of each (property types of one renamed parent
+ * resource, for instance), pairs are chosen greedily by name similarity and
+ * whatever is left over stays a plain removal or addition. Entries with an
+ * empty resourceType are never paired; there is nothing to key them on.
+ */
+function pairRenames(removed: RemovedEntry[], added: AddedEntry[]): RenamePair[] {
+  const key = (e: SurfaceEntry): string => `${e.kind} ${e.resourceType}`;
+
+  const addedByKey = new Map<string, AddedEntry[]>();
+  for (const a of added) {
+    if (!a.entry.resourceType) continue;
+    const k = key(a.entry);
+    const bucket = addedByKey.get(k);
+    if (bucket) bucket.push(a);
+    else addedByKey.set(k, [a]);
   }
 
-  const hasBreaking =
-    removed.length > 0 ||
-    changed.some(
-      (c) =>
-        c.resourceTypeChanged !== undefined ||
-        c.kindChanged !== undefined ||
-        (c.removedProps?.length ?? 0) > 0 ||
-        (c.nowRequired?.length ?? 0) > 0 ||
-        (c.removedAttrs?.length ?? 0) > 0 ||
-        (c.createOnlyChanged !== undefined) ||
-        // losing taggable is breaking
-        (c.taggableChanged !== undefined && c.taggableChanged.before === true && c.taggableChanged.after !== true),
+  const removedByKey = new Map<string, RemovedEntry[]>();
+  for (const r of removed) {
+    if (!r.entry.resourceType) continue;
+    const k = key(r.entry);
+    if (!addedByKey.has(k)) continue;
+    const bucket = removedByKey.get(k);
+    if (bucket) bucket.push(r);
+    else removedByKey.set(k, [r]);
+  }
+
+  const pairs: RenamePair[] = [];
+  for (const [k, olds] of removedByKey) {
+    const news = addedByKey.get(k) ?? [];
+    if (olds.length === 1 && news.length === 1) {
+      pairs.push({ from: olds[0], to: news[0] });
+      continue;
+    }
+
+    // Ambiguous: rank every (old, new) combination by similarity and take
+    // the best remaining pair until one side runs out.
+    const candidates: Array<{ from: RemovedEntry; to: AddedEntry; score: number }> = [];
+    for (const from of olds) {
+      for (const to of news) {
+        candidates.push({ from, to, score: nameSimilarity(from.name, to.name) });
+      }
+    }
+    candidates.sort((a, b) =>
+      b.score - a.score ||
+      a.from.name.localeCompare(b.from.name) ||
+      a.to.name.localeCompare(b.to.name),
     );
+    const usedOld = new Set<string>();
+    const usedNew = new Set<string>();
+    for (const cand of candidates) {
+      if (usedOld.has(cand.from.name) || usedNew.has(cand.to.name)) continue;
+      usedOld.add(cand.from.name);
+      usedNew.add(cand.to.name);
+      pairs.push({ from: cand.from, to: cand.to });
+      if (usedOld.size === olds.length || usedNew.size === news.length) break;
+    }
+  }
 
-  if (hasBreaking) severity = "breaking";
+  return pairs;
+}
 
-  return { added, changed, removed, severity };
+/**
+ * Dice similarity over character bigrams, in [0, 1]. Enough to tell
+ * `Space` apart from `Space_Tag` when pairing the property types of a
+ * renamed parent; nothing heavier is needed.
+ */
+function nameSimilarity(a: string, b: string): number {
+  if (a === b) return 1;
+  if (a.length < 2 || b.length < 2) return 0;
+  const bigrams = (s: string): Map<string, number> => {
+    const m = new Map<string, number>();
+    for (let i = 0; i < s.length - 1; i++) {
+      const bg = s.slice(i, i + 2);
+      m.set(bg, (m.get(bg) ?? 0) + 1);
+    }
+    return m;
+  };
+  const ba = bigrams(a);
+  const bb = bigrams(b);
+  let overlap = 0;
+  for (const [bg, n] of ba) {
+    const m = bb.get(bg);
+    if (m) overlap += Math.min(n, m);
+  }
+  return (2 * overlap) / (a.length - 1 + b.length - 1);
 }
 
 // ── Serialization ────────────────────────────────────────────────────
@@ -489,42 +649,19 @@ export function formatDelta(delta: SurfaceDelta): string {
     }
   }
 
+  if (delta.renamed.length > 0) {
+    lines.push(`Renamed (${delta.renamed.length}):`);
+    for (const r of delta.renamed) {
+      lines.push(`  ~ ${r.from} -> ${r.to} [${r.entry.kind}] (${r.entry.resourceType})`);
+      if (r.changes) lines.push(...formatChanges(r.changes));
+    }
+  }
+
   if (delta.changed.length > 0) {
     lines.push(`Changed (${delta.changed.length}):`);
     for (const c of delta.changed) {
       lines.push(`  ~ ${c.name}`);
-      if (c.resourceTypeChanged) {
-        lines.push(`      resourceType: ${c.resourceTypeChanged.before} -> ${c.resourceTypeChanged.after}`);
-      }
-      if (c.kindChanged) {
-        lines.push(`      kind: ${c.kindChanged.before} -> ${c.kindChanged.after}`);
-      }
-      if (c.removedProps?.length) {
-        lines.push(`      removed props: ${c.removedProps.join(", ")}`);
-      }
-      if (c.nowRequired?.length) {
-        lines.push(`      now required: ${c.nowRequired.join(", ")}`);
-      }
-      if (c.addedProps?.length) {
-        lines.push(`      added props: ${c.addedProps.join(", ")}`);
-      }
-      if (c.nowOptional?.length) {
-        lines.push(`      now optional: ${c.nowOptional.join(", ")}`);
-      }
-      if (c.removedAttrs?.length) {
-        lines.push(`      removed attrs: ${c.removedAttrs.join(", ")}`);
-      }
-      if (c.addedAttrs?.length) {
-        lines.push(`      added attrs: ${c.addedAttrs.join(", ")}`);
-      }
-      if (c.createOnlyChanged) {
-        const before = c.createOnlyChanged.before.join(", ") || "(none)";
-        const after = c.createOnlyChanged.after.join(", ") || "(none)";
-        lines.push(`      createOnly: [${before}] -> [${after}]`);
-      }
-      if (c.taggableChanged) {
-        lines.push(`      taggable: ${c.taggableChanged.before ?? "(unset)"} -> ${c.taggableChanged.after ?? "(unset)"}`);
-      }
+      lines.push(...formatChanges(c));
     }
   }
 
@@ -538,6 +675,44 @@ export function formatDelta(delta: SurfaceDelta): string {
   return lines.join("\n");
 }
 
+/** Indented detail lines for one entry's structural changes. */
+function formatChanges(c: EntryChanges): string[] {
+  const lines: string[] = [];
+  if (c.resourceTypeChanged) {
+    lines.push(`      resourceType: ${c.resourceTypeChanged.before} -> ${c.resourceTypeChanged.after}`);
+  }
+  if (c.kindChanged) {
+    lines.push(`      kind: ${c.kindChanged.before} -> ${c.kindChanged.after}`);
+  }
+  if (c.removedProps?.length) {
+    lines.push(`      removed props: ${c.removedProps.join(", ")}`);
+  }
+  if (c.nowRequired?.length) {
+    lines.push(`      now required: ${c.nowRequired.join(", ")}`);
+  }
+  if (c.addedProps?.length) {
+    lines.push(`      added props: ${c.addedProps.join(", ")}`);
+  }
+  if (c.nowOptional?.length) {
+    lines.push(`      now optional: ${c.nowOptional.join(", ")}`);
+  }
+  if (c.removedAttrs?.length) {
+    lines.push(`      removed attrs: ${c.removedAttrs.join(", ")}`);
+  }
+  if (c.addedAttrs?.length) {
+    lines.push(`      added attrs: ${c.addedAttrs.join(", ")}`);
+  }
+  if (c.createOnlyChanged) {
+    const before = c.createOnlyChanged.before.join(", ") || "(none)";
+    const after = c.createOnlyChanged.after.join(", ") || "(none)";
+    lines.push(`      createOnly: [${before}] -> [${after}]`);
+  }
+  if (c.taggableChanged) {
+    lines.push(`      taggable: ${c.taggableChanged.before ?? "(unset)"} -> ${c.taggableChanged.after ?? "(unset)"}`);
+  }
+  return lines;
+}
+
 // ── Helpers ──────────────────────────────────────────────────────────
 
 function splitProp(encoded: string): [string, string] {

package/src/codegen/validate.test.ts

@@ -106,7 +106,7 @@ describe("surface snapshot gate (#1473)", () => {
     return dir;
   }
 
-  const run = (basePath: string, checkSurfaceSnapshot: boolean, armed = true) =>
+  const run = (basePath: string, checkSurfaceSnapshot: boolean | "always", armed = true) =>
     validateLexiconArtifacts({
       lexiconJsonFilename: "lexicon-test.json",
       requiredNames: [],
@@ -141,8 +141,8 @@ describe("surface snapshot gate (#1473)", () => {
   });
 
   test("is off unless the lexicon opts in", async () => {
-    // k8s and azure are adrift from their own baselines (#1475); switching
-    // this on globally would block their releases.
+    // A lexicon with no baseline of its own, or one that generates from a
+    // moving upstream it has not pinned, must not be gated by default.
     const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
     const result = await run(fixture({ snapshot: stale }), false);
     expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
@@ -158,6 +158,19 @@ describe("surface snapshot gate (#1473)", () => {
     expect(result.success).toBe(true);
   });
 
+  test("\"always\" runs outside a release — a pinned upstream cannot move on its own (#1475)", async () => {
+    // k8s and azure generate from immutable refs, so drift on a PR can only
+    // come from this repo and is exactly what should fail the build.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await run(fixture({ snapshot: stale }), "always", false);
+    const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
+    expect(check?.ok).toBe(false);
+    expect(result.success).toBe(false);
+
+    const ok = await run(fixture({ snapshot: await matchingSnapshot() }), "always", false);
+    expect(ok.checks.find((c) => c.name === "surface-matches-snapshot")?.ok).toBe(true);
+  });
+
   test("is skipped for a lexicon with no committed snapshot", async () => {
     // A new lexicon before its first baseline must still be able to build.
     const result = await run(fixture(), true);
@@ -169,4 +182,37 @@ describe("surface snapshot gate (#1473)", () => {
     const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
     expect(check?.ok).toBe(false);
   });
+
+  test("an update run skips the staleness check it is about to fix (#1825)", async () => {
+    // `--update-snapshot` sets CHANT_SNAPSHOT_UPDATE for its validate run.
+    // Without this, an "always" gate deadlocks the documented re-baseline flow:
+    // validate fails on the stale snapshot, and the update writes only after a
+    // green validate.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await validateLexiconArtifacts({
+      lexiconJsonFilename: "lexicon-test.json",
+      requiredNames: [],
+      basePath: fixture({ snapshot: stale }),
+      checkSurfaceSnapshot: "always",
+      env: { CHANT_SNAPSHOT_UPDATE: "1" },
+    });
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+    expect(result.success).toBe(true);
+  });
+
+  test("an update run is exempt from the staleness check and nothing else", async () => {
+    // A failing check other than surface-matches-snapshot must still refuse
+    // the run, so a broken generate cannot be baselined.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await validateLexiconArtifacts({
+      lexiconJsonFilename: "lexicon-test.json",
+      requiredNames: ["NotThere"],
+      basePath: fixture({ snapshot: stale }),
+      checkSurfaceSnapshot: "always",
+      env: { CHANT_SNAPSHOT_UPDATE: "1" },
+    });
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+    expect(result.checks.find((c) => c.name === "required-names")?.ok).toBe(false);
+    expect(result.success).toBe(false);
+  });
 });

package/src/codegen/validate.ts

@@ -27,6 +27,17 @@ export interface ValidateResult {
  */
 export const RELEASE_GATE_ENV = "CHANT_RELEASE_GATE";
 
+/**
+ * Set by `chant dev surface-diff --update-snapshot` for the validate run it
+ * performs before rewriting the baseline (chant #1825). When set to "1", the
+ * `surface-matches-snapshot` check is skipped. That check fails on exactly the
+ * staleness the update run exists to fix, and with an `"always"` gate (#1475)
+ * the two would deadlock: validate cannot pass until the snapshot is updated,
+ * and the snapshot cannot be updated until validate passes. Every other check
+ * still runs, so a broken generate cannot be baselined.
+ */
+export const SNAPSHOT_UPDATE_ENV = "CHANT_SNAPSHOT_UPDATE";
+
 export interface LexiconValidationConfig {
   /** Filename of the lexicon JSON (e.g. "lexicon-mydom.json") */
   lexiconJsonFilename: string;
@@ -62,10 +73,18 @@ export interface LexiconValidationConfig {
    * What must never happen is *publishing* a surface nobody reviewed. That is
    * a release-time property, so it is checked at release time.
    *
-   * Opt-in per lexicon because k8s and azure are currently adrift from their
-   * own baselines (393 and 483 entries, #1475).
+   * `"always"` drops the env half (#1475). It is for a lexicon whose upstream
+   * is pinned to an immutable ref — k8s generates from a kubernetes release
+   * tag plus vendored CRDs, azure from a commit sha of the
+   * resource-manager-schemas repo — so a fresh `generate` on a PR is
+   * deterministic and the only way the surface can move is a change in this
+   * repo. For those, drift on a PR is exactly the thing to fail on: the CRD
+   * batches #1319/#1320/#1321 left the k8s baseline 393 entries behind, and
+   * the #1144 pin left azure 483 behind, because nothing compared the two
+   * until a release was attempted. Never use `"always"` for a lexicon that
+   * fetches a moving upstream.
    */
-  checkSurfaceSnapshot?: boolean;
+  checkSurfaceSnapshot?: boolean | "always";
   /** Environment to read {@link RELEASE_GATE_ENV} from. Defaults to `process.env`; overridden in tests. */
   env?: NodeJS.ProcessEnv;
   /** Path to the generated directory (defaults to basePath/src/generated) */
@@ -193,13 +212,23 @@ export async function validateLexiconArtifacts(config: LexiconValidationConfig):
   // Runs on the artifacts already on disk — no second generation — and is
   // skipped for a lexicon with no committed snapshot, which is the case for a
   // new lexicon before its first baseline.
+  //
+  // A re-baseline run (`chant dev surface-diff --update-snapshot`) sets
+  // {@link SNAPSHOT_UPDATE_ENV} and is exempt: the check would fail on the
+  // stale snapshot that run is about to rewrite, deadlocking the documented
+  // update flow against an `"always"` gate (#1825). Only this check is exempt —
+  // every other check above still gates the run.
   const snapshotPath = join(config.basePath, "surface.snapshot.json");
-  const releaseGate = config.checkSurfaceSnapshot && (config.env ?? process.env)[RELEASE_GATE_ENV] === "1";
-  if (releaseGate && lexiconData && existsSync(snapshotPath) && existsSync(dtsPath)) {
+  const env = config.env ?? process.env;
+  const surfaceGate =
+    (config.checkSurfaceSnapshot === "always" ||
+      (config.checkSurfaceSnapshot === true && env[RELEASE_GATE_ENV] === "1")) &&
+    env[SNAPSHOT_UPDATE_ENV] !== "1";
+  if (surfaceGate && lexiconData && existsSync(snapshotPath) && existsSync(dtsPath)) {
     try {
       const fresh = extractSurface(readFileSync(lexiconPath, "utf-8"), readFileSync(dtsPath, "utf-8"));
       const delta = diffSurface(parseSnapshot(readFileSync(snapshotPath, "utf-8")), fresh);
-      const moved = delta.added.length + delta.removed.length + delta.changed.length;
+      const moved = delta.added.length + delta.removed.length + delta.renamed.length + delta.changed.length;
       checks.push(
         moved === 0
           ? { name: "surface-matches-snapshot", ok: true }
@@ -208,7 +237,7 @@ export async function validateLexiconArtifacts(config: LexiconValidationConfig):
               ok: false,
               error:
                 `The generated API differs from the reviewed surface.snapshot.json ` +
-                `(${delta.added.length} added, ${delta.removed.length} removed, ${delta.changed.length} changed). ` +
+                `(${delta.added.length} added, ${delta.removed.length} removed, ${delta.renamed.length} renamed, ${delta.changed.length} changed). ` +
                 `Accept it deliberately with \`chant dev surface-diff <lexicon> --update-snapshot --bump\`, ` +
                 `never as a side effect of a release.\n${formatDelta(delta)}`,
             },

package/src/components/auto-release.ts

@@ -42,7 +42,7 @@ import type { DriverStepRecord } from "./driver";
  * `extract-config-bom` likewise *describes* an artifact rather than promoting
  * one. Those must not trigger a release record (#665) — a release means "we
  * promoted this by digest to a location", not "we hashed some bytes". The
- * driver's own `findPublishOutput` stays looser (uri/digest/key) because it
+ * driver's own `collectComponentOutputs` stays looser (uri/digest/key) because it
  * only feeds `@<component>.publish.*` wiring, where a false positive is harmless.
  */
 function isPromotedArtifact(output: unknown): output is { uri: string; digest?: string } {