@intentius/chant-lexicon-aws 0.58.0 → 0.60.0

package/src/codegen/enum-overlay.test.ts

@@ -0,0 +1,298 @@
+import { describe, test, expect } from "vitest";
+import {
+  applyEnumOverlay,
+  assertOverlayCoverage,
+  enumOverlayByType,
+  enumOverlayEntries,
+  redundantOverlayWarnings,
+  type EnumOverlayEntry,
+} from "./enum-overlay";
+import { generate } from "./generate";
+
+const entry = (over: Partial<EnumOverlayEntry> = {}): EnumOverlayEntry => ({
+  type: "AWS::Test::Resource",
+  pointer: "/properties/Mode",
+  enumName: "Mode",
+  note: "test",
+  source: { kind: "docs", url: "https://example.invalid" },
+  reviewed: "2026-09-06",
+  values: ["fast", "slow"],
+  ...over,
+});
+
+const schema = (extra: Record<string, unknown> = {}) =>
+  JSON.stringify({
+    typeName: "AWS::Test::Resource",
+    properties: { Mode: { type: "string" }, Name: { type: "string" } },
+    additionalProperties: false,
+    ...extra,
+  });
+
+describe("applyEnumOverlay", () => {
+  test("narrows a bare string property to a named enum definition", () => {
+    const { data, applications } = applyEnumOverlay("AWS::Test::Resource", schema(), [entry()], {
+      strict: true,
+    });
+
+    expect(applications).toEqual([{ entry: entry(), outcome: "applied" }]);
+    const doc = JSON.parse(data as string);
+    expect(doc.definitions.Mode).toEqual({ type: "string", enum: ["fast", "slow"] });
+    expect(doc.properties.Mode.$ref).toBe("#/definitions/Mode");
+    // The enum stays on the property too, because that is what the lexicon
+    // registry's propertyConstraints are read from.
+    expect(doc.properties.Mode.enum).toEqual(["fast", "slow"]);
+    expect(doc.properties.Name).toEqual({ type: "string" });
+  });
+
+  test("reaches a property inside a definition", () => {
+    const nested = JSON.stringify({
+      typeName: "AWS::Test::Resource",
+      properties: { Disk: { $ref: "#/definitions/Ebs" } },
+      definitions: { Ebs: { type: "object", properties: { VolumeType: { type: "string" } } } },
+    });
+
+    const { data } = applyEnumOverlay(
+      "AWS::Test::Resource",
+      nested,
+      [entry({ pointer: "/definitions/Ebs/properties/VolumeType", enumName: "VolumeType", values: ["gp2", "gp3"] })],
+      { strict: true },
+    );
+
+    const doc = JSON.parse(data as string);
+    expect(doc.definitions.VolumeType).toEqual({ type: "string", enum: ["gp2", "gp3"] });
+    expect(doc.definitions.Ebs.properties.VolumeType.$ref).toBe("#/definitions/VolumeType");
+  });
+
+  test("the spec wins where it already declares allowed values", () => {
+    const withEnum = schema({
+      properties: { Mode: { type: "string", enum: ["fast", "slow", "medium"] } },
+    });
+
+    const { data, applications } = applyEnumOverlay("AWS::Test::Resource", withEnum, [entry()], {
+      strict: true,
+    });
+
+    expect(applications[0].outcome).toBe("redundant");
+    expect(applications[0].upstreamValues).toEqual(["fast", "slow", "medium"]);
+    // Untouched: no definition minted, no $ref, upstream values intact.
+    expect(data).toBe(withEnum);
+    const doc = JSON.parse(data as string);
+    expect(doc.definitions).toBeUndefined();
+    expect(doc.properties.Mode.$ref).toBeUndefined();
+    expect(doc.properties.Mode.enum).toEqual(["fast", "slow", "medium"]);
+  });
+
+  test("a redundant entry produces a warning naming the entry", () => {
+    const withEnum = schema({ properties: { Mode: { type: "string", enum: ["fast"] } } });
+    const { applications } = applyEnumOverlay("AWS::Test::Resource", withEnum, [entry()], {
+      strict: true,
+    });
+
+    const warnings = redundantOverlayWarnings(applications);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].file).toBe("AWS::Test::Resource/properties/Mode");
+    expect(warnings[0].error).toContain("redundant");
+  });
+
+  test("a strict run fails loudly on a property the schema does not declare", () => {
+    expect(() =>
+      applyEnumOverlay("AWS::Test::Resource", schema(), [entry({ pointer: "/properties/Gone" })], {
+        strict: true,
+      }),
+    ).toThrow(/AWS::Test::Resource\/properties\/Gone names a property the schema does not declare/);
+  });
+
+  test("a fixture run records the same case as absent instead of failing", () => {
+    const { applications } = applyEnumOverlay(
+      "AWS::Test::Resource",
+      schema(),
+      [entry({ pointer: "/properties/Gone" })],
+      { strict: false },
+    );
+    expect(applications[0].outcome).toBe("absent");
+  });
+
+  test("fails when the enum name would shadow an existing definition", () => {
+    const withDef = schema({ definitions: { Mode: { type: "object", properties: {} } } });
+    expect(() =>
+      applyEnumOverlay("AWS::Test::Resource", withDef, [entry()], { strict: true }),
+    ).toThrow(/already declares/);
+  });
+
+  test("fails when the target property already refers to a definition", () => {
+    const withRef = schema({
+      properties: { Mode: { $ref: "#/definitions/Other" } },
+      definitions: { Other: { type: "string" } },
+    });
+    expect(() =>
+      applyEnumOverlay("AWS::Test::Resource", withRef, [entry()], { strict: true }),
+    ).toThrow(/already refers to/);
+  });
+
+  test("leaves a schema with no entries untouched", () => {
+    const original = schema();
+    const { data, applications } = applyEnumOverlay("AWS::Other::Thing", original, []);
+    expect(data).toBe(original);
+    expect(applications).toEqual([]);
+  });
+});
+
+describe("assertOverlayCoverage", () => {
+  test("a strict run fails on an entry whose type never appeared", () => {
+    expect(() => assertOverlayCoverage([entry()], new Set(["AWS::S3::Bucket"]), true)).toThrow(
+      /AWS::Test::Resource/,
+    );
+  });
+
+  test("a fixture run tolerates it", () => {
+    expect(() => assertOverlayCoverage([entry()], new Set(["AWS::S3::Bucket"]), false)).not.toThrow();
+  });
+
+  test("passes when every type was seen", () => {
+    expect(() =>
+      assertOverlayCoverage([entry()], new Set(["AWS::Test::Resource"]), true),
+    ).not.toThrow();
+  });
+});
+
+describe("the shipped overlay", () => {
+  const entries = enumOverlayEntries();
+
+  test("is non-empty and grouped by type without loss", () => {
+    expect(entries.length).toBeGreaterThan(0);
+    const grouped = [...enumOverlayByType(entries).values()].reduce((n, l) => n + l.length, 0);
+    expect(grouped).toBe(entries.length);
+  });
+
+  test("addresses each property at most once", () => {
+    const keys = entries.map((e) => `${e.type}${e.pointer}`);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  test("every entry is well formed", () => {
+    for (const e of entries) {
+      expect(e.type, `${e.type} is a CloudFormation type name`).toMatch(/^[A-Za-z0-9]+(::[A-Za-z0-9]+){2}$/);
+      expect(e.pointer, `${e.type}${e.pointer} is a properties pointer`).toMatch(
+        /^\/(properties\/[A-Za-z0-9]+|definitions\/[A-Za-z0-9]+\/properties\/[A-Za-z0-9]+)$/,
+      );
+      expect(e.enumName, `${e.type}${e.pointer} names its definition`).toMatch(/^[A-Za-z0-9]+$/);
+      expect(e.reviewed, `${e.type}${e.pointer} records when it was read`).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+      expect(e.note.length, `${e.type}${e.pointer} says why it is here`).toBeGreaterThan(0);
+      if (e.source.kind === "botocore") {
+        expect(e.source.service).toBeTruthy();
+        expect(e.source.apiVersion).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+        expect(e.source.shape).toBeTruthy();
+      } else {
+        expect(e.source.url).toMatch(/^https:\/\//);
+      }
+    }
+  });
+
+  test("every value list is non-empty, unique and sorted", () => {
+    for (const e of entries) {
+      const where = `${e.type}${e.pointer}`;
+      expect(e.values.length, where).toBeGreaterThan(0);
+      expect(new Set(e.values).size, where).toBe(e.values.length);
+      expect(e.values, where).toEqual([...e.values].sort());
+    }
+  });
+
+  test("covers the headline property from chant #1497", () => {
+    const ec2 = entries.find(
+      (e) => e.type === "AWS::EC2::Instance" && e.pointer === "/properties/InstanceType",
+    );
+    expect(ec2).toBeDefined();
+    expect(ec2!.values).toContain("t3.micro");
+  });
+
+  test("carries every value the repo's own examples and composites already write", () => {
+    const written: Array<[string, string, string]> = [
+      ["AWS::Lambda::Function", "/properties/Runtime", "nodejs20.x"],
+      ["AWS::Lambda::Function", "/properties/Runtime", "nodejs18.x"],
+      ["AWS::Lambda::Function", "/properties/Runtime", "python3.12"],
+      ["AWS::EC2::Instance", "/properties/InstanceType", "t3.micro"],
+      ["AWS::ElasticLoadBalancingV2::TargetGroup", "/properties/Protocol", "HTTP"],
+      ["AWS::ElasticLoadBalancingV2::TargetGroup", "/properties/Protocol", "HTTPS"],
+      ["AWS::ElasticLoadBalancingV2::TargetGroup", "/properties/Protocol", "TCP"],
+      ["AWS::ElasticLoadBalancingV2::TargetGroup", "/properties/TargetType", "ip"],
+      ["AWS::ElasticLoadBalancingV2::LoadBalancer", "/properties/Scheme", "internet-facing"],
+      ["AWS::SNS::Subscription", "/properties/Protocol", "lambda"],
+      ["AWS::DynamoDB::Table", "/properties/BillingMode", "PAY_PER_REQUEST"],
+      ["AWS::DynamoDB::Table", "/definitions/AttributeDefinition/properties/AttributeType", "S"],
+      ["AWS::DynamoDB::Table", "/definitions/AttributeDefinition/properties/AttributeType", "N"],
+      ["AWS::DynamoDB::Table", "/definitions/KeySchema/properties/KeyType", "HASH"],
+      ["AWS::DynamoDB::Table", "/definitions/KeySchema/properties/KeyType", "RANGE"],
+      ["AWS::DynamoDB::Table", "/definitions/Projection/properties/ProjectionType", "ALL"],
+      ["AWS::DynamoDB::Table", "/definitions/Projection/properties/ProjectionType", "INCLUDE"],
+      ["AWS::DynamoDB::Table", "/definitions/StreamSpecification/properties/StreamViewType", "NEW_AND_OLD_IMAGES"],
+      ["AWS::DynamoDB::Table", "/definitions/StreamSpecification/properties/StreamViewType", "KEYS_ONLY"],
+      ["AWS::RDS::DBInstance", "/properties/Engine", "postgres"],
+      ["AWS::RDS::DBCluster", "/properties/Engine", "aurora-postgresql"],
+      ["AWS::ApplicationAutoScaling::ScalableTarget", "/properties/ServiceNamespace", "ecs"],
+      ["AWS::ApplicationAutoScaling::ScalableTarget", "/properties/ServiceNamespace", "dynamodb"],
+      ["AWS::ApplicationAutoScaling::ScalableTarget", "/properties/ScalableDimension", "ecs:service:DesiredCount"],
+      [
+        "AWS::ApplicationAutoScaling::ScalableTarget",
+        "/properties/ScalableDimension",
+        "dynamodb:table:ReadCapacityUnits",
+      ],
+    ];
+
+    for (const [type, pointer, value] of written) {
+      const e = entries.find((x) => x.type === type && x.pointer === pointer);
+      expect(e, `${type}${pointer} is in the overlay`).toBeDefined();
+      expect(e!.values, `${type}${pointer} accepts ${value}`).toContain(value);
+    }
+  });
+});
+
+describe("the overlay through the generation pipeline", () => {
+  test("a bare property comes out as a named union in the .d.ts", async () => {
+    const schemas = new Map<string, Buffer>([
+      [
+        "AWS::ElasticLoadBalancingV2::LoadBalancer",
+        Buffer.from(
+          JSON.stringify({
+            typeName: "AWS::ElasticLoadBalancingV2::LoadBalancer",
+            properties: { Name: { type: "string" }, Scheme: { type: "string" } },
+            additionalProperties: false,
+          }),
+        ),
+      ],
+    ]);
+
+    const result = await generate({ schemaSource: schemas });
+
+    expect(result.typesDTS).toContain(
+      'export type LoadBalancer_Scheme = "internal" | "internet-facing";',
+    );
+    expect(result.typesDTS).toContain("Scheme?: LoadBalancer_Scheme;");
+
+    const lexicon = JSON.parse(result.lexiconJSON);
+    expect(lexicon["LoadBalancer"].propertyConstraints.Scheme.enum).toEqual([
+      "internal",
+      "internet-facing",
+    ]);
+  });
+
+  test("a spec-declared enum survives the pipeline unchanged", async () => {
+    const schemas = new Map<string, Buffer>([
+      [
+        "AWS::ElasticLoadBalancingV2::LoadBalancer",
+        Buffer.from(
+          JSON.stringify({
+            typeName: "AWS::ElasticLoadBalancingV2::LoadBalancer",
+            properties: { Scheme: { type: "string", enum: ["internal"] } },
+            additionalProperties: false,
+          }),
+        ),
+      ],
+    ]);
+
+    const result = await generate({ schemaSource: schemas });
+
+    expect(result.typesDTS).toContain('Scheme?: "internal";');
+    expect(result.typesDTS).not.toContain("export type LoadBalancer_Scheme");
+    expect(result.warnings.some((w) => w.error.includes("redundant"))).toBe(true);
+  });
+});

package/src/codegen/enum-overlay.ts

@@ -0,0 +1,245 @@
+/**
+ * Curated enum overlay (chant #1497).
+ *
+ * The CloudFormation Registry spec declares `enum` on some properties and not
+ * on others, and the split does not follow how often a property is written:
+ * `AWS::SageMaker::NotebookInstance.InstanceType` is a union while
+ * `AWS::EC2::Instance.InstanceType` is a bare `string`. Where the spec is
+ * silent the generated type stops teaching the API, and a wrong value survives
+ * `tsc` and `chant build` to fail at deploy.
+ *
+ * This overlay is a checked-in list of `(CFN type, JSON pointer, values)`
+ * entries merged into the raw schema before parsing, so a curated enum reaches
+ * the generated `.d.ts` and the lexicon registry by exactly the path a spec
+ * enum reaches them. Nothing here is fetched at build time: the values live in
+ * `enum-overlay.json` beside this file, each with the source it was read from
+ * and the date it was read, so `scripts/refresh-enum-overlay.ts` can diff them
+ * later.
+ *
+ * Precedence: the overlay only fills gaps. An entry whose target already
+ * declares `enum` (from the Registry spec or from a cfn-lint patch) leaves the
+ * spec alone and reports itself as redundant. Upstream is refreshed on every
+ * `generate`, so it is the source that keeps tracking AWS; a hand list allowed
+ * to win would rot invisibly and would make the generated type depend on which
+ * of two sources happened to be newer. Reporting the overlap instead surfaces
+ * the entry for retirement the moment upstream catches up.
+ *
+ * An entry that matches nothing is an error, not a shrug: a renamed or removed
+ * property means the curated values are being applied to a property that no
+ * longer exists, and silence there is how an overlay goes stale.
+ */
+
+import overlayDocument from "./enum-overlay.json" with { type: "json" };
+
+/** Where an entry's values were read from, and enough detail to read them again. */
+export type EnumOverlaySource =
+  | {
+      kind: "botocore";
+      /** Directory under `botocore/data`, e.g. `elbv2`. */
+      service: string;
+      /** API version directory, e.g. `2015-12-01`. */
+      apiVersion: string;
+      /** Shape name carrying the `enum`, e.g. `ProtocolEnum`. */
+      shape: string;
+    }
+  | {
+      kind: "docs";
+      /** Page the values were transcribed from. */
+      url: string;
+    };
+
+/** One curated enum. */
+export interface EnumOverlayEntry {
+  /** CloudFormation type name, e.g. `AWS::EC2::Instance`. */
+  type: string;
+  /**
+   * JSON pointer to the property inside that type's Registry schema, either
+   * `/properties/<Name>` or `/definitions/<Def>/properties/<Name>`.
+   */
+  pointer: string;
+  /**
+   * Name for the `definitions` entry this creates. The generator turns it into
+   * an exported type named `<class>_<enumName>`, e.g. `Function_Runtime`.
+   */
+  enumName: string;
+  /** Why this property earned a place in the first curated set. */
+  note: string;
+  source: EnumOverlaySource;
+  /** ISO date the values were last read from `source`. */
+  reviewed: string;
+  values: string[];
+}
+
+/** What happened to one entry during a generation run. */
+export interface EnumOverlayApplication {
+  entry: EnumOverlayEntry;
+  /**
+   * `applied` narrowed the property; `redundant` left an upstream enum in
+   * place; `absent` means the schema in hand does not declare the property,
+   * which only a non-strict (fixture) run tolerates.
+   */
+  outcome: "applied" | "redundant" | "absent";
+  /** For `redundant`, the values upstream already declared. */
+  upstreamValues?: string[];
+}
+
+/** The curated entries, in file order. */
+export function enumOverlayEntries(): EnumOverlayEntry[] {
+  return overlayDocument.entries as EnumOverlayEntry[];
+}
+
+/** Entries grouped by CloudFormation type name. */
+export function enumOverlayByType(
+  entries: EnumOverlayEntry[] = enumOverlayEntries(),
+): Map<string, EnumOverlayEntry[]> {
+  const byType = new Map<string, EnumOverlayEntry[]>();
+  for (const entry of entries) {
+    const list = byType.get(entry.type);
+    if (list) list.push(entry);
+    else byType.set(entry.type, [entry]);
+  }
+  return byType;
+}
+
+/** A pointer segment that is not a plain object key is not addressable. */
+function pointerSegments(pointer: string): string[] {
+  if (!pointer.startsWith("/")) {
+    throw new Error(`enum overlay pointer must start with "/": ${pointer}`);
+  }
+  return pointer.split("/").slice(1);
+}
+
+type SchemaNode = Record<string, unknown>;
+
+function resolvePointer(doc: SchemaNode, pointer: string): SchemaNode | undefined {
+  let node: unknown = doc;
+  for (const segment of pointerSegments(pointer)) {
+    if (typeof node !== "object" || node === null || Array.isArray(node)) return undefined;
+    node = (node as SchemaNode)[segment];
+    if (node === undefined) return undefined;
+  }
+  if (typeof node !== "object" || node === null || Array.isArray(node)) return undefined;
+  return node as SchemaNode;
+}
+
+/**
+ * Apply the entries for one CloudFormation type to its raw schema bytes.
+ *
+ * Returns the (possibly rewritten) schema and one {@link EnumOverlayApplication}
+ * per entry. Throws when an entry cannot be honoured, which is always a
+ * curation bug rather than a spec quirk.
+ *
+ * `strict` is on for a run over the real schema zip and off for a run over the
+ * trimmed fixtures under `src/testdata/schemas`, which legitimately drop
+ * properties the overlay names. Only a strict run treats a missing property as
+ * an error.
+ */
+export function applyEnumOverlay(
+  typeName: string,
+  data: Buffer | string,
+  entries: EnumOverlayEntry[],
+  opts: { strict?: boolean } = {},
+): { data: Buffer | string; applications: EnumOverlayApplication[] } {
+  if (entries.length === 0) return { data, applications: [] };
+  const strict = opts.strict ?? false;
+
+  const text = typeof data === "string" ? data : data.toString("utf-8");
+  const doc = JSON.parse(text) as SchemaNode;
+  const applications: EnumOverlayApplication[] = [];
+  let changed = false;
+
+  for (const entry of entries) {
+    const where = `${entry.type}${entry.pointer}`;
+
+    const target = resolvePointer(doc, entry.pointer);
+    if (!target) {
+      if (!strict) {
+        applications.push({ entry, outcome: "absent" });
+        continue;
+      }
+      throw new Error(
+        `enum overlay entry ${where} names a property the schema does not declare. ` +
+          `Either the property was renamed upstream or the entry is stale; fix or drop it in ` +
+          `src/codegen/enum-overlay.json.`,
+      );
+    }
+
+    if (Array.isArray(target.enum) && target.enum.length > 0) {
+      applications.push({
+        entry,
+        outcome: "redundant",
+        upstreamValues: target.enum as string[],
+      });
+      continue;
+    }
+
+    if (typeof target.$ref === "string") {
+      throw new Error(
+        `enum overlay entry ${where} targets a property that already refers to ` +
+          `${target.$ref}; the overlay cannot own its type.`,
+      );
+    }
+
+    const definitions = (doc.definitions ??= {}) as SchemaNode;
+    if (entry.enumName in definitions) {
+      throw new Error(
+        `enum overlay entry ${where} would define ${entry.type}.${entry.enumName}, ` +
+          `which the schema already declares. Pick a different enumName.`,
+      );
+    }
+
+    // The definition gives the generator a name to export; the `enum` left on
+    // the property is what `extractConstraints` copies into the lexicon
+    // registry, where the LSP and the docs build read it.
+    definitions[entry.enumName] = { type: "string", enum: [...entry.values] };
+    target.$ref = `#/definitions/${entry.enumName}`;
+    target.enum = [...entry.values];
+    changed = true;
+    applications.push({ entry, outcome: "applied" });
+  }
+
+  if (!changed) return { data, applications };
+  const rewritten = JSON.stringify(doc);
+  return {
+    data: typeof data === "string" ? rewritten : Buffer.from(rewritten),
+    applications,
+  };
+}
+
+/**
+ * Fail on any entry the run never reached.
+ *
+ * `strict` is on for a run over the real schema zip and off for a run over a
+ * fixture subset, where most types are legitimately absent. A missing type in
+ * a full run means the resource left the Registry and the entry is dead.
+ */
+export function assertOverlayCoverage(
+  entries: EnumOverlayEntry[],
+  seenTypes: Set<string>,
+  strict: boolean,
+): void {
+  if (!strict) return;
+  const missing = entries.filter((e) => !seenTypes.has(e.type));
+  if (missing.length === 0) return;
+  const names = [...new Set(missing.map((e) => e.type))].sort().join(", ");
+  throw new Error(
+    `enum overlay names ${missing.length} entr${missing.length === 1 ? "y" : "ies"} on ` +
+      `type(s) the spec does not contain: ${names}. Drop them from ` +
+      `src/codegen/enum-overlay.json or fix the type name.`,
+  );
+}
+
+/** One warning line per entry upstream has caught up with. */
+export function redundantOverlayWarnings(
+  applications: EnumOverlayApplication[],
+): Array<{ file: string; error: string }> {
+  return applications
+    .filter((a) => a.outcome === "redundant")
+    .map((a) => ({
+      file: `${a.entry.type}${a.entry.pointer}`,
+      error:
+        `enum overlay entry is redundant: the spec already declares ` +
+        `${(a.upstreamValues ?? []).length} allowed value(s) here, and the spec wins. ` +
+        `Retire the entry from src/codegen/enum-overlay.json.`,
+    }));
+}

package/src/codegen/generate.ts

@@ -18,6 +18,15 @@ import { assertPinnedSpec } from "../spec/pin";
 import { parseCFNSchema, cfnShortName, type SchemaParseResult } from "../spec/parse";
 import { fetchCfnLintPatches, applyPatches } from "./patches";
 import { fetchCfnLintExtensions, loadExtensionSchemas, type ExtensionConstraint } from "./extensions";
+import {
+  applyEnumOverlay,
+  assertOverlayCoverage,
+  enumOverlayByType,
+  enumOverlayEntries,
+  redundantOverlayWarnings,
+  type EnumOverlayApplication,
+  type EnumOverlayEntry,
+} from "./enum-overlay";
 import { samResources } from "./sam";
 import { fallbackResources } from "./fallback";
 import { NamingStrategy, publishedNames, propertyTypeName, extractDefName } from "./naming";
@@ -35,6 +44,18 @@ export type { GenerateOptions, GenerateResult };
 let awsConstraints = new Map<string, ExtensionConstraint[]>();
 /** chant #1459 — spec type → already-published TS name, reset per `generate()` call. */
 let awsReservedNames: Record<string, string> = {};
+/**
+ * Curated enum overlay state (chant #1497), reset per `generate()` call.
+ *
+ * The overlay runs in `parseSchema` rather than `augmentSchemas` on purpose:
+ * `augmentSchemas` is skipped for a caller-supplied schema set because it
+ * fetches, and the overlay fetches nothing. Running it per schema keeps a
+ * fixture-driven run and a real run on the same code path.
+ */
+let awsOverlay: Map<string, EnumOverlayEntry[]> = new Map();
+let awsOverlayApplications: EnumOverlayApplication[] = [];
+let awsOverlaySeenTypes = new Set<string>();
+let awsOverlayStrict = false;
 
 const awsPipelineConfig: GeneratePipelineConfig<SchemaParseResult> = {
   fetchSchemas: async (opts) => {
@@ -46,8 +67,12 @@ const awsPipelineConfig: GeneratePipelineConfig<SchemaParseResult> = {
     return schemas;
   },
 
-  parseSchema: (_typeName, data) => {
-    const result = parseCFNSchema(data);
+  parseSchema: (typeName, data) => {
+    awsOverlaySeenTypes.add(typeName);
+    const entries = awsOverlay.get(typeName) ?? [];
+    const overlaid = applyEnumOverlay(typeName, data, entries, { strict: awsOverlayStrict });
+    awsOverlayApplications.push(...overlaid.applications);
+    const result = parseCFNSchema(overlaid.data);
     if (!result.resource.typeName) return null;
     return result;
   },
@@ -110,6 +135,13 @@ const awsPipelineConfig: GeneratePipelineConfig<SchemaParseResult> = {
     // Re-filter extension constraints now that we have the full type set
     // (augmentSchemas loaded them before parsing, so we already have them)
 
+    // A curated enum that reached nothing is a stale entry (chant #1497), and
+    // the only place it can be noticed is here, once every schema has been seen.
+    assertOverlayCoverage(enumOverlayEntries(), awsOverlaySeenTypes, awsOverlayStrict);
+    const applied = awsOverlayApplications.filter((a) => a.outcome === "applied").length;
+    log(`Applied ${applied} curated enum overlay entries`);
+    warnings.push(...redundantOverlayWarnings(awsOverlayApplications));
+
     log(`Total: ${results.length} resource schemas`);
     return { results, warnings };
   },
@@ -139,6 +171,12 @@ const awsPipelineConfig: GeneratePipelineConfig<SchemaParseResult> = {
 export async function generate(opts: GenerateOptions = {}): Promise<GenerateResult> {
   // Reset shared state
   awsConstraints = new Map();
+  awsOverlay = enumOverlayByType();
+  awsOverlayApplications = [];
+  awsOverlaySeenTypes = new Set();
+  // A fixture set is a trimmed subset, so an entry it never reaches is
+  // expected; a run over the real zip has no such excuse.
+  awsOverlayStrict = !opts.schemaSource;
   // chant #1459 — names already published keep pointing at the types that
   // published them. Skipped for a caller-supplied schema set, exactly as
   // `augmentSchemas` is (see the pipeline's `opts.schemaSource` guard): a

package/src/components/safety.test.ts

@@ -42,10 +42,10 @@ describe("rollback-previous (#557)", () => {
   });
 
   it("rolls an ECS service back via the executor for the {service, cluster} shape (#990)", async () => {
-    // The ecs-fargate preset / ALB-ECS pilot (and loomster's loom-frontend)
-    // compose rollback-previous with an ECS service, NOT a snapshot id. This
-    // used to reach the snapshot path and throw "Cannot read properties of
-    // undefined (reading 'includes')" on the absent snapshotId.
+    // The ecs-fargate preset / ALB-ECS pilot compose rollback-previous with an
+    // ECS service, NOT a snapshot id. This used to reach the snapshot path and
+    // throw "Cannot read properties of undefined (reading 'includes')" on the
+    // absent snapshotId.
     const mock = createMockCloudExecutor();
     const out = await createRollbackPreviousCapability(mock.executor).run(ctx, {
       service: "loom-frontend-svc",

package/src/components/safety.ts

@@ -54,8 +54,8 @@ export interface RollbackPreviousSnapshotInput {
 }
 
 /** Roll an ECS service back to its previously recorded task definition — the
- * shape the `ecs-fargate` preset and the ALB/ECS pilot compose (e.g. loomster's
- * `loom-frontend`). */
+ * shape the `ecs-fargate` preset and the ALB/ECS pilot compose for an
+ * ALB-fronted frontend service. */
 export interface RollbackPreviousEcsInput {
   /** ECS service name. */
   service: string;