@intentius/chant 0.39.0 → 0.41.1

package/src/cli/handlers/graph.test.ts

@@ -85,8 +85,15 @@ vi.mock("../../config", async () => {
     loadChantConfigUpward: (...a: unknown[]) => loadChantConfigUpwardMock(...a),
   };
 });
+const buildMock = vi.fn();
 vi.mock("../../build", () => ({
-  build: () => Promise.resolve({ errors: [] }),
+  // Forwards its arguments so a test can assert what the live path passed —
+  // `buildParams` in particular (#1483), the same reason `discover` above
+  // forwards for #1359.
+  build: (...a: unknown[]) => {
+    buildMock(...a);
+    return Promise.resolve({ errors: [] });
+  },
   partitionByLexicon: () => ({}),
   computeStackGraph: () => ({}),
 }));
@@ -136,6 +143,7 @@ describe("runGraph", () => {
     // Default: no components — the single-stack --live path most tests exercise.
     discoverComponentsMock.mockResolvedValue({ components: new Map(), sourceFiles: [], errors: [] });
     observeMock.mockReset();
+    buildMock.mockReset();
     loadPluginsMock.mockReset();
     resolveLexMock.mockReset();
     loadChantConfigMock.mockReset();
@@ -480,6 +488,48 @@ describe("runGraph", () => {
   });
 
   describe("live graph (--live)", () => {
+    // #1483 — the live path builds the source to learn which entities to
+    // observe, and did so on default parameters while the declared overlay
+    // resolved the caller's. For a project whose parameters choose *which
+    // resources exist* — a tier, a size, a profile — that observed one estate
+    // and compared it against another, so every resource the real parameter
+    // declares read as absent and every resource the default declares read as
+    // pending. A confidently wrong overlay, not an empty one.
+    describe("build-time parameters reach the observed build (#1483)", () => {
+      const liveWithTier = async (param?: string[]) => {
+        loadChantConfigUpwardMock.mockResolvedValue({
+          config: { buildParams: { tier: { type: "string", enum: ["light", "prod"], default: "light" } } },
+        });
+        resolveLexMock.mockResolvedValue(["aws"]);
+        loadPluginsMock.mockResolvedValue([
+          { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
+        ]);
+        observeMock.mockResolvedValue({ observations: [], errors: [], warnings: [] });
+        return runGraph({
+          args: makeArgs({ format: "ir", live: true, env: "prod", ...(param ? { param } : {}) }),
+          plugins: [],
+          serializers: [],
+        });
+      };
+
+      const paramsOf = (call: unknown[]) =>
+        (call[3] as { buildParams?: Array<{ name: string; value: unknown }> } | undefined)?.buildParams;
+
+      test("--param reaches the build the observation is scoped from", async () => {
+        expect(await liveWithTier(["tier=prod"])).toBe(0);
+        expect(paramsOf(buildMock.mock.calls[0]!)).toContainEqual(
+          expect.objectContaining({ name: "tier", value: "prod" }),
+        );
+      });
+
+      test("a declared default reaches it too, rather than nothing at all", async () => {
+        expect(await liveWithTier()).toBe(0);
+        expect(paramsOf(buildMock.mock.calls[0]!)).toContainEqual(
+          expect.objectContaining({ name: "tier", value: "light" }),
+        );
+      });
+    });
+
     // Regression: `graph` is not `requiresPlugins`, so `ctx.plugins` is empty. The
     // live path must load the project's plugins itself — otherwise it wrongly
     // reports "No lexicons implement describeResources" and observes nothing.

package/src/cli/handlers/graph.ts

@@ -144,7 +144,22 @@ async function runGraphLive(
 
   // Build to get each lexicon's entity names + output (the scope
   // describeResources needs), mirroring `chant lifecycle snapshot`.
-  const buildResult = await build(resolve(args.src ?? config.sourceDir ?? "."), plugins.map((p) => p.serializer));
+  //
+  // With the same build params the source graph resolves (#1483). Without
+  // them this build ran on defaults while the declared overlay below ran on
+  // the caller's, so a project whose parameters choose *which resources
+  // exist* — a tier, a size, a profile — observed one estate and compared it
+  // against another. Every resource the real parameter declares read as
+  // absent and every resource the default declares read as pending, which is
+  // a confidently wrong overlay rather than an empty one.
+  const liveBuildParams = await graphBuildParams(ctx, projectPath);
+  if (!liveBuildParams) return 1;
+  const buildResult = await build(
+    resolve(args.src ?? config.sourceDir ?? "."),
+    plugins.map((p) => p.serializer),
+    undefined,
+    { buildParams: liveBuildParams },
+  );
   if (buildResult.errors.length > 0) {
     console.error(formatError({ message: "Build failed — fix errors before graphing live state" }));
     return 1;

package/src/cli/handlers/lifecycle.ts

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { commandBuildParams } from "../build-params-cli";
 import { build } from "../../build";
 import { takeSnapshot } from "../../lifecycle/snapshot";
 import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, pushLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
@@ -101,6 +102,10 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
   // Validate environment against config
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath);
+  // This invocation's parameters, so the declared side of the comparison is the estate
+  // the caller asked for rather than the parameter defaults (#1483).
+  const declaredParams = await commandBuildParams(config.buildParams, args);
+  if (!declaredParams) return 1;
   const declaredEnvNames = environmentNames(config.environments);
   if (declaredEnvNames && !declaredEnvNames.includes(environment)) {
     console.error(formatError({
@@ -146,7 +151,7 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
   const built: Array<{ target: (typeof targets)[number]; buildResult: Awaited<ReturnType<typeof build>> }> = [];
   for (const target of targets) {
     const label = target.stack ? `stack "${target.stack}"` : "project";
-    const buildResult = await build(target.root, targetSerializers);
+    const buildResult = await build(target.root, targetSerializers, undefined, { buildParams: declaredParams });
     if (buildResult.errors.length > 0) {
       console.error(formatError({ message: `Build failed for ${label} — fix errors before taking a snapshot` }));
       anyHardError = true;
@@ -326,6 +331,10 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
 
   // Fetch previous snapshots once (all stacks share the orphan branch).
   const { config } = await loadChantConfig(resolve("."));
+  // This invocation's parameters, so the declared side of the comparison is the estate
+  // the caller asked for rather than the parameter defaults (#1483).
+  const declaredParams = await commandBuildParams(config.buildParams, args);
+  if (!declaredParams) return 1;
   await fetchLifecycle();
 
   // One target per stack (single-stack projects: exactly one), each built from
@@ -355,7 +364,7 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
 
   try {
     for (const target of targets) {
-      const buildResult = await build(target.root, targetSerializers);
+      const buildResult = await build(target.root, targetSerializers, undefined, { buildParams: declaredParams });
       if (buildResult.errors.length > 0) {
         const label = target.stack ? `stack "${target.stack}"` : "project";
         console.error(formatError({ message: `Build failed for ${label} — fix errors before diffing` }));
@@ -1021,7 +1030,13 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
     : serializers;
 
   const { config } = await loadChantConfig(resolve("."));
-  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers);
+  // This invocation's parameters, so the declared side of the comparison is the estate
+  // the caller asked for rather than the parameter defaults (#1483).
+  const declaredParams = await commandBuildParams(config.buildParams, args);
+  if (!declaredParams) return 1;
+  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers, undefined, {
+    buildParams: declaredParams,
+  });
   if (buildResult.errors.length > 0) {
     console.error(formatError({ message: "Build failed — fix errors before planning" }));
     return 1;

package/src/codegen/naming.test.ts

@@ -0,0 +1,129 @@
+import { describe, test, expect } from "vitest";
+import { NamingStrategy, reservedNamesFromSnapshot, type NamingConfig, type NamingInput } from "./naming";
+
+/**
+ * chant #1459 — a published TypeScript name belongs to the type that published
+ * it, so an unrelated upstream addition or removal cannot rename a resource
+ * whose own schema never moved.
+ */
+
+const config: NamingConfig = {
+  priorityNames: {},
+  priorityAliases: {},
+  priorityPropertyAliases: {},
+  serviceAbbreviations: {},
+  shortName: (t) => t.split("::").pop() ?? t,
+  serviceName: (t) => t.split("::")[1] ?? "",
+};
+
+function name(types: string[], over: Partial<NamingConfig> = {}): Map<string, string | undefined> {
+  const inputs: NamingInput[] = types.map((typeName) => ({ typeName, propertyTypes: [] }));
+  const strategy = new NamingStrategy(inputs, { ...config, ...over });
+  return new Map(types.map((t) => [t, strategy.resolve(t)]));
+}
+
+describe("reservedNamesFromSnapshot", () => {
+  test("inverts the snapshot into spec type → published name", () => {
+    expect(
+      reservedNamesFromSnapshot({
+        entries: { MacieSession: { kind: "resource", resourceType: "AWS::Macie::Session" } },
+      }),
+    ).toEqual({ "AWS::Macie::Session": "MacieSession" });
+  });
+
+  test("reserves resources only, not property types", () => {
+    // Property names derive from their owning resource (phase 5), so pinning
+    // the resource pins them; reserving them separately would freeze aliases
+    // that are meant to follow their parent.
+    const reserved = reservedNamesFromSnapshot({
+      entries: {
+        Bucket: { kind: "resource", resourceType: "AWS::S3::Bucket" },
+        Bucket_Rule: { kind: "property", resourceType: "AWS::S3::Bucket.Rule" },
+      },
+    });
+    expect(reserved).toEqual({ "AWS::S3::Bucket": "Bucket" });
+  });
+
+  test("ignores entries with no resourceType, and a missing snapshot", () => {
+    expect(reservedNamesFromSnapshot({ entries: { Broken: { kind: "resource" } } })).toEqual({});
+    expect(reservedNamesFromSnapshot(undefined)).toEqual({});
+    expect(reservedNamesFromSnapshot({})).toEqual({});
+  });
+
+  test("first writer wins when one spec type is listed under two names", () => {
+    const reserved = reservedNamesFromSnapshot({
+      entries: {
+        Alpha: { kind: "resource", resourceType: "AWS::X::Y" },
+        Beta: { kind: "resource", resourceType: "AWS::X::Y" },
+      },
+    });
+    expect(reserved).toEqual({ "AWS::X::Y": "Alpha" });
+  });
+});
+
+describe("reserved names survive their neighbours changing", () => {
+  test("a competitor disappearing does not hand its short name over", () => {
+    // The real case: AWS::Athena::Session and AWS::SSM::Session were removed
+    // upstream, which silently renamed AWS::Macie::Session from MacieSession
+    // to Session — breaking a resource AWS had not touched.
+    const withCompetitor = name(["AWS::Macie::Session", "AWS::Athena::Session"]);
+    expect(withCompetitor.get("AWS::Macie::Session")).toBe("MacieSession");
+
+    const afterRemoval = name(["AWS::Macie::Session"], {
+      reservedNames: { "AWS::Macie::Session": "MacieSession" },
+    });
+    expect(afterRemoval.get("AWS::Macie::Session")).toBe("MacieSession");
+  });
+
+  test("without reservation, the same removal renames it — the bug", () => {
+    const afterRemoval = name(["AWS::Macie::Session"]);
+    expect(afterRemoval.get("AWS::Macie::Session")).toBe("Session");
+  });
+
+  test("a newcomer colliding gets qualified instead of displacing the incumbent", () => {
+    // AWS::QuickSight::Space appearing renamed AWS::SageMaker::Space from
+    // Space to SageMakerSpace. The newcomer should absorb the qualification.
+    const names = name(["AWS::SageMaker::Space", "AWS::QuickSight::Space"], {
+      reservedNames: { "AWS::SageMaker::Space": "Space" },
+    });
+    expect(names.get("AWS::SageMaker::Space")).toBe("Space");
+    expect(names.get("AWS::QuickSight::Space")).toBe("QuickSightSpace");
+  });
+
+  test("order of the input does not decide the outcome", () => {
+    const reservedNames = { "AWS::SageMaker::Space": "Space" };
+    const forward = name(["AWS::SageMaker::Space", "AWS::QuickSight::Space"], { reservedNames });
+    const reverse = name(["AWS::QuickSight::Space", "AWS::SageMaker::Space"], { reservedNames });
+    expect(forward.get("AWS::SageMaker::Space")).toBe(reverse.get("AWS::SageMaker::Space"));
+    expect(forward.get("AWS::QuickSight::Space")).toBe(reverse.get("AWS::QuickSight::Space"));
+  });
+});
+
+describe("reservation boundaries", () => {
+  test("an explicit priority name still outranks history", () => {
+    const names = name(["AWS::Macie::Session"], {
+      priorityNames: { "AWS::Macie::Session": "PinnedName" },
+      reservedNames: { "AWS::Macie::Session": "MacieSession" },
+    });
+    expect(names.get("AWS::Macie::Session")).toBe("PinnedName");
+  });
+
+  test("a reservation for a type no longer in the input releases the name", () => {
+    // AWS::CodeArtifact::Package was genuinely removed, so Package is free for
+    // whoever legitimately claims it next.
+    const names = name(["AWS::Panorama::Package"], {
+      reservedNames: { "AWS::CodeArtifact::Package": "Package" },
+    });
+    expect(names.get("AWS::Panorama::Package")).toBe("Package");
+  });
+
+  test("a brand-new resource with no reservation is unaffected", () => {
+    const names = name(["AWS::MSK::Channel"], { reservedNames: { "AWS::Macie::Session": "MacieSession" } });
+    expect(names.get("AWS::MSK::Channel")).toBe("Channel");
+  });
+
+  test("no reservations at all reproduces the previous behaviour exactly", () => {
+    const types = ["AWS::Macie::Session", "AWS::Athena::Session", "AWS::MSK::Channel"];
+    expect(name(types, { reservedNames: {} })).toEqual(name(types));
+  });
+});

package/src/codegen/naming.ts

@@ -1,12 +1,32 @@
 /**
  * Collision-free naming strategy for TypeScript class names.
  *
- * 5-phase algorithm:
+ * 6-phase algorithm:
  * 1. Priority names (backward compatibility)
+ * 1a. Reserved names — names this lexicon has already published (chant #1459)
  * 2. Priority aliases (additional short names)
  * 3. Short names (last segment of type)
  * 4. Collision resolution (service-prefixed)
  * 5. Property type aliases (globally unique defs)
+ *
+ * ## Why phase 1a exists
+ *
+ * Phases 3 and 4 assign a short name to whoever asks first and service-qualify
+ * everyone after. Membership of that contest is the whole input set, so a
+ * resource's name was a function of its NEIGHBOURS: removing
+ * `AWS::Athena::Session` upstream freed `Session`, and `AWS::Macie::Session`
+ * silently changed from `MacieSession` to `Session` — a breaking rename for a
+ * resource whose schema had not moved. Adding a resource does the same in
+ * reverse: `AWS::QuickSight::Space` appearing renamed `AWS::SageMaker::Space`
+ * from `Space` to `SageMakerSpace`.
+ *
+ * Worse, it is reversible. These are read-only registry types that come and go,
+ * so a name could flip back on the next upgrade and break consumers again.
+ *
+ * Reserved names invert the bias: a name that has already shipped belongs to
+ * the type that shipped it, and a newcomer colliding with it gets qualified
+ * instead. A published name then changes only when its own type disappears,
+ * which is a genuine breaking change rather than an incidental one.
  */
 
 /**
@@ -35,6 +55,40 @@ export interface NamingConfig {
   shortName: (typeName: string) => string;
   /** Extract the service name from a type name (e.g. "Vendor::Service::Resource" → "Service"). */
   serviceName: (typeName: string) => string;
+  /**
+   * chant #1459 — spec type name → the TypeScript name this lexicon has
+   * already published for it, normally read from the committed
+   * `surface.snapshot.json` via {@link reservedNamesFromSnapshot}.
+   *
+   * Claimed before short names are contested, so a shipped name is not taken
+   * away from its owner by an unrelated upstream change. Omit for a lexicon
+   * with no published surface yet; an entry for a type that is no longer in
+   * the input is ignored, so a removed type frees its name for reuse.
+   */
+  reservedNames?: Record<string, string>;
+}
+
+/**
+ * The names a lexicon has already published, read from a committed surface
+ * snapshot (chant #1459).
+ *
+ * The snapshot is keyed by TypeScript name with the spec type inside, which is
+ * exactly the mapping phase 1a needs, inverted. Only `resource` entries are
+ * reserved: property-type names are derived from their owning resource's name
+ * (phase 5), so pinning the resource pins them, and reserving them separately
+ * would freeze aliases that are meant to follow their parent.
+ */
+export function reservedNamesFromSnapshot(
+  snapshot: { entries?: Record<string, { kind?: string; resourceType?: string }> } | undefined,
+): Record<string, string> {
+  const reserved: Record<string, string> = {};
+  for (const [tsName, entry] of Object.entries(snapshot?.entries ?? {})) {
+    if (entry.kind !== "resource" || !entry.resourceType) continue;
+    // First writer wins: a snapshot that somehow lists one spec type under two
+    // names keeps the earlier, rather than silently preferring iteration order.
+    reserved[entry.resourceType] ??= tsName;
+  }
+  return reserved;
 }
 
 export class NamingStrategy {
@@ -58,6 +112,23 @@ export class NamingStrategy {
       }
     }
 
+    // Phase 1a: claim previously-published names (chant #1459).
+    //
+    // After priority names, which are explicit hand-pinned decisions and still
+    // win, and before any short name is contested. A reserved name whose type
+    // is gone from the input is simply never reached, so its name is released
+    // for whoever legitimately claims it next.
+    for (const t of typeNames) {
+      if (this.assigned.has(t)) continue;
+      const published = config.reservedNames?.[t];
+      // `usedNames` guards the case where a priority name already took it —
+      // an explicit pin outranks history.
+      if (published && !this.usedNames.has(published)) {
+        this.assigned.set(t, published);
+        this.usedNames.add(published);
+      }
+    }
+
     // Phase 1b: assign priority aliases
     for (const t of typeNames) {
       const extras = config.priorityAliases[t];

package/src/codegen/validate.test.ts

@@ -84,3 +84,89 @@ describe("validateLexiconArtifacts", () => {
     rmSync(dir, { recursive: true, force: true });
   });
 });
+
+/**
+ * chant #1473 — the release gate. `prepack` regenerates from an upstream that
+ * moves, so what must match the reviewed baseline is the API that comes out,
+ * not the archive that went in.
+ */
+describe("surface snapshot gate (#1473)", () => {
+  const LEXICON = JSON.stringify({
+    Bucket: { resourceType: "AWS::S3::Bucket", kind: "resource", lexicon: "aws" },
+  });
+  const DTS = "export declare class Bucket {}\n";
+
+  function fixture(opts: { snapshot?: string } = {}): string {
+    const dir = makeTempDir();
+    const genDir = join(dir, "src", "generated");
+    mkdirSync(genDir, { recursive: true });
+    writeFileSync(join(genDir, "lexicon-test.json"), LEXICON);
+    writeFileSync(join(genDir, "index.d.ts"), DTS);
+    if (opts.snapshot !== undefined) writeFileSync(join(dir, "surface.snapshot.json"), opts.snapshot);
+    return dir;
+  }
+
+  const run = (basePath: string, checkSurfaceSnapshot: boolean, armed = true) =>
+    validateLexiconArtifacts({
+      lexiconJsonFilename: "lexicon-test.json",
+      requiredNames: [],
+      basePath,
+      checkSurfaceSnapshot,
+      env: armed ? { CHANT_RELEASE_GATE: "1" } : {},
+    });
+
+  /** The snapshot a matching build would have produced. */
+  async function matchingSnapshot(): Promise<string> {
+    const { extractSurface, serializeSnapshot } = await import("./surface-snapshot");
+    return serializeSnapshot(extractSurface(LEXICON, DTS));
+  }
+
+  test("passes when the generated API matches the snapshot", async () => {
+    const result = await run(fixture({ snapshot: await matchingSnapshot() }), true);
+    const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
+    expect(check?.ok).toBe(true);
+  });
+
+  test("fails when the generated API differs, and says how to accept it", async () => {
+    const stale = JSON.stringify({
+      schemaVersion: 1,
+      generatedAt: "2026-01-01T00:00:00.000Z",
+      entries: { Queue: { kind: "resource", resourceType: "AWS::SQS::Queue", attrs: [], props: [] } },
+    });
+    const result = await run(fixture({ snapshot: stale }), true);
+    const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
+    expect(check?.ok).toBe(false);
+    expect(check?.error).toContain("--update-snapshot");
+    expect(result.success).toBe(false);
+  });
+
+  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.
+    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();
+  });
+
+  test("does not run outside a release, even for a lexicon that opted in", async () => {
+    // `validate` runs on every PR. Upstream can move the surface at any time,
+    // so a hard check here would turn unrelated PRs red — the same trap the
+    // spec pin fell into. Drift between releases is the upgrade job's business.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await run(fixture({ snapshot: stale }), true, false);
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+    expect(result.success).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);
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+  });
+
+  test("an unreadable snapshot fails rather than passing silently", async () => {
+    const result = await run(fixture({ snapshot: "{ not json" }), true);
+    const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
+    expect(check?.ok).toBe(false);
+  });
+});

package/src/codegen/validate.ts

@@ -8,6 +8,7 @@
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import { computeCoverage, checkThresholds, type CoverageThresholds } from "./coverage";
+import { extractSurface, diffSurface, parseSnapshot, formatDelta } from "./surface-snapshot";
 
 export interface ValidateCheck {
   name: string;
@@ -20,6 +21,12 @@ export interface ValidateResult {
   checks: ValidateCheck[];
 }
 
+/**
+ * Set by the publish workflow to arm the release-time surface gate
+ * (chant #1473). Absent in ordinary CI, where upstream drift is expected.
+ */
+export const RELEASE_GATE_ENV = "CHANT_RELEASE_GATE";
+
 export interface LexiconValidationConfig {
   /** Filename of the lexicon JSON (e.g. "lexicon-mydom.json") */
   lexiconJsonFilename: string;
@@ -35,6 +42,32 @@ export interface LexiconValidationConfig {
   requiredNamesMatchSubstring?: boolean;
   /** Base path of the lexicon package */
   basePath: string;
+  /**
+   * chant #1473 — this lexicon's release is gated on the generated API
+   * matching the committed `surface.snapshot.json`.
+   *
+   * Two conditions, both required. The lexicon opts in here, AND
+   * {@link RELEASE_GATE_ENV} is set — which the publish workflow does and
+   * ordinary CI does not.
+   *
+   * The env half is not caution, it is correctness. `validate` runs on every
+   * PR, and the upstream a lexicon generates from can move at any time: the
+   * CloudFormation archive republishes schemas several times a day, and some
+   * of those edits do change the surface. A hard surface check on every PR
+   * would turn any unrelated change red the moment upstream moved, which is
+   * the same trap the spec pin fell into one level down. Drift between
+   * releases is expected and is what the scheduled lexicon-upgrade job exists
+   * to report (#1423).
+   *
+   * 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).
+   */
+  checkSurfaceSnapshot?: boolean;
+  /** 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) */
   generatedDir?: string;
   /** Coverage thresholds (optional) */
@@ -148,6 +181,47 @@ export async function validateLexiconArtifacts(config: LexiconValidationConfig):
     }
   }
 
+  // Check: the generated API matches the reviewed one (chant #1473).
+  //
+  // This is the gate that makes a release trustworthy. `prepack` regenerates
+  // from upstream, and for aws that upstream republishes schemas several times
+  // a day, so the input can differ from the one whose delta a human accepted.
+  // What must not differ is the API that ships. Comparing the just-generated
+  // artifacts against the committed `surface.snapshot.json` says exactly that,
+  // and says nothing about byte churn that changed no declaration.
+  //
+  // 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.
+  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)) {
+    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;
+      checks.push(
+        moved === 0
+          ? { name: "surface-matches-snapshot", ok: true }
+          : {
+              name: "surface-matches-snapshot",
+              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). ` +
+                `Accept it deliberately with \`chant dev surface-diff <lexicon> --update-snapshot --bump\`, ` +
+                `never as a side effect of a release.\n${formatDelta(delta)}`,
+            },
+      );
+    } catch (err) {
+      checks.push({
+        name: "surface-matches-snapshot",
+        ok: false,
+        error: `Failed to compare against surface.snapshot.json: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  }
+
   return {
     success: checks.every((c) => c.ok),
     checks,

package/src/components/deploy-units.test.ts

@@ -0,0 +1,42 @@
+import { describe, test, expect } from "vitest";
+import { deployUnits } from "./deploy-units";
+import type { Phase } from "./component";
+
+const phase = (name: string, steps: Phase["steps"]): Phase => ({ phase: name, steps });
+
+describe("deployUnits (#1495 piece 1)", () => {
+  test("resolves a cfn-deploy step to its stack, keyed to the aws observer", () => {
+    const deploy = [phase("Apply", [{ kind: "cfn-deploy", stack: "cc-canonical", template: "t.json" }])];
+    expect(deployUnits(deploy)).toEqual([{ unit: "cc-canonical", lexicon: "aws" }]);
+  });
+
+  test("resolves kubectl-apply and helm-upgrade units once their steps exist", () => {
+    const deploy = [
+      phase("Apply", [
+        { kind: "kubectl-apply", stack: "kubemicrovm-ops" },
+        { kind: "helm-upgrade", release: "operator" },
+      ]),
+    ];
+    expect(deployUnits(deploy)).toEqual([
+      { unit: "kubemicrovm-ops", lexicon: "k8s" },
+      { unit: "operator", lexicon: "helm" },
+    ]);
+  });
+
+  test("walks nested phases, dedupes per lexicon, and skips unitless steps", () => {
+    const deploy = [
+      phase("Outer", [
+        phase("Inner", [{ kind: "cfn-deploy", stack: "web" }]) as never,
+        { kind: "cfn-deploy", stack: "web" },
+        { kind: "shell", cmd: "echo", reason: "no capability yet" },
+        { kind: "cfn-deploy" }, // no stack named — contributes nothing
+      ]),
+    ];
+    expect(deployUnits(deploy)).toEqual([{ unit: "web", lexicon: "aws" }]);
+  });
+
+  test("an unlisted kind contributes no unit — the registry is the rule", () => {
+    const deploy = [phase("Apply", [{ kind: "gcloud-deploy", stack: "x" }])];
+    expect(deployUnits(deploy)).toEqual([]);
+  });
+});