@intentius/chant-lexicon-aws 0.37.2 → 0.40.0

package/src/import/generator.ts

@@ -1,3 +1,4 @@
+import { loadLexiconRegistry } from "@intentius/chant/codegen/registry";
 import { createRequire } from "module";
 import type { TemplateIR, ResourceIR, ParameterIR } from "@intentius/chant/import/parser";
 const require = createRequire(import.meta.url);
@@ -14,10 +15,10 @@ export class CFGenerator implements TypeScriptGenerator {
   private allClassNames: Set<string>;
 
   constructor() {
-    // Build reverse lookup from dist/meta.json: resourceType → className
-    const metaPath = join(import.meta.dirname, "../../dist/meta.json");
-    const meta: Record<string, { resourceType: string; kind: string }> =
-      require(metaPath);
+    // Reverse lookup from the generated registry: resourceType → className.
+    // Loaded through core so a missing registry says what to run rather than
+    // "Cannot find module .../dist/meta.json" (#1367).
+    const meta = loadLexiconRegistry(join(import.meta.dirname, "../.."), "aws");
     this.typeToClass = new Map();
     this.allClassNames = new Set();
     for (const [className, entry] of Object.entries(meta)) {

package/src/index.ts

@@ -112,7 +112,7 @@ export {
   EfsWithAccessPoint,
   Ec2InstanceRole, MinimalVpc,
   SolrFargateService,
-  MicrovmApp,
+  MicrovmApp, MICROVM_LIMITS,
   AgentCoreAgent,
 } from "./composites/index";
 export type {
@@ -122,7 +122,7 @@ export type {
   EfsWithAccessPointProps,
   Ec2InstanceRoleProps, MinimalVpcProps,
   SolrFargateServiceProps,
-  MicrovmAppProps, MicrovmAppResult, MicrovmAppBuildConnectorProps,
+  MicrovmAppProps, MicrovmAppResult, MicrovmAppBuildConnectorProps, MicrovmMemoryMiB,
   AgentCoreAgentProps, AgentCoreAgentResult,
 } from "./composites/index";
 

package/src/lifecycle-integration.test.ts

@@ -239,6 +239,7 @@ describe("aws lifecycle integration (#163)", () => {
 // The shared conformance suite (#1089).
 describeObservationConformance({
   lexicon: "aws",
+  ownershipChannel: awsPlugin.ownershipChannel,
   scenarios: [
     {
       name: "a stack read that fails on credentials",
@@ -286,5 +287,29 @@ describeObservationConformance({
         });
       },
     },
+    {
+      // aws declares a marker channel on the deep read and on live export, but
+      // not here: describe-stack-resources returns no tags, so the filter has
+      // nothing to filter on. The suite holds it to that — an `owned` verdict
+      // from this path would be a claim the transport cannot support (#1348).
+      name: "an owned read on a path with no marker channel",
+      declared: ["MyBucket"],
+      expectPresent: ["MyBucket"],
+      owned: true,
+      run: () => {
+        stubCfn((action) =>
+          action === "DescribeStackResources"
+            ? { text: stackResourcesXml([{ logicalId: "MyBucket", type: "AWS::S3::Bucket", physicalId: "my-bucket" }]) }
+            : { text: stackOutputsXml() },
+        );
+        return awsPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["MyBucket"],
+          entities: new Map(),
+          owned: true,
+        });
+      },
+    },
   ],
 });

package/src/op/activities/floci.test.ts

@@ -13,7 +13,7 @@ import {
 describe("flociRunCommand (#704)", () => {
   test("minimal — defaults name/port/image, no docker socket", () => {
     expect(flociRunCommand({})).toBe(
-      "docker run -d --rm --name chant-floci -p 4566:4566 floci/floci:latest",
+      "docker run -d --rm --name chant-floci -p 4566:4566 floci/floci:1.5.34",
     );
   });
 
@@ -60,7 +60,7 @@ describe("flociHealthUrl / flociEnv (#704)", () => {
 describe("FLOCI_SPEC / FLOCI_EMULATOR — the aws plugin's emulator capability (#920)", () => {
   test("spec pins the Floci container identity the shared lifecycle boots", () => {
     expect(FLOCI_SPEC.name).toBe("chant-floci");
-    expect(FLOCI_SPEC.image).toBe("floci/floci:latest");
+    expect(FLOCI_SPEC.image).toBe("floci/floci:1.5.34");
     expect(FLOCI_SPEC.containerPort).toBe(4566);
     expect(FLOCI_SPEC.healthPath).toBe("/_localstack/health");
   });

package/src/op/activities/floci.ts

@@ -2,7 +2,11 @@ import { emulatorLifecycle, type EmulatorSpec, type EmulatorCapability } from "@
 
 const DEFAULT_NAME = "chant-floci";
 const DEFAULT_PORT = 4566;
-const DEFAULT_IMAGE = "floci/floci:latest";
+// Pinned, not `:latest` (#1345). An image that moves underneath a passing
+// local suite is the drift a pin exists to stop, and the freshness check in
+// core reports how far behind this is rather than bumping it — the tag moves
+// when a consuming test needs the newer emulator (#808).
+const DEFAULT_IMAGE = "floci/floci:1.5.34";
 const DEFAULT_REGION = "us-east-1";
 const DEFAULT_READY_SERVICE = "cloudformation";
 const DOCKER_SOCK = ["-v", "/var/run/docker.sock:/var/run/docker.sock"] as const;
@@ -55,6 +59,7 @@ const flociSpecFor = (readyService: string): EmulatorSpec => ({
   containerPort: DEFAULT_PORT,
   healthPath: "/_localstack/health",
   ready: (body) => isFlociReady(body, readyService),
+  upstream: { repo: "floci-io/floci" },
 });
 
 /** The Floci emulator spec — the aws plugin's `emulator` capability (#920). */

package/src/plugin.ts

@@ -35,6 +35,7 @@ import { CFGenerator } from "./import/generator";
 import { parseStackTemplate } from "./import/live-export";
 import { awsCompletions } from "./lsp/completions";
 import { awsHover } from "./lsp/hover";
+import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
 
 /** Re-exported from ./stack-errors so the long-standing import path (and its
  * tests) keep working now that the deep reader shares the classifier. */
@@ -51,6 +52,9 @@ let warnedOwnership = false;
 
 export const awsPlugin: LexiconPlugin = {
   name: "aws",
+  // The thin read is sourced from describe-stack-resources, which returns no
+  // tags — so `owned` on that path can only answer `unknown`, and does (#1348).
+  ownershipChannel: { keys: AWS_TAG_OWNERSHIP_KEYS, reads: ["observeResourcesDeep", "exportResources"] },
   serializer: awsSerializer,
   // Local emulator (#920): Floci + the AWS env that redirects the SDK / observe.
   emulator: FLOCI_EMULATOR,

package/src/reference-catalog.test.ts

@@ -72,3 +72,31 @@ describe("awsReferenceCatalog — golden 3-tier VPC", () => {
     expect(groups.privA).toEqual(expect.arrayContaining(["svc", "rds"]));
   });
 });
+
+describe("an instance is in a VPC (#1432 follow-up)", () => {
+  // Subnet, security group and route table all had an "in VPC" rule. The
+  // instance did not, so the one kind every estate question is about reached
+  // its VPC only through its subnet — two hops, which a one-hop `<-` cannot
+  // cross. `describe-instances` returns VpcId directly; nothing had to be
+  // inferred.
+  const nodes = [
+    { id: "vpc-1", kind: "AWS::EC2::VPC", lexicon: "aws", physicalId: "vpc-1", attrs: { VpcId: "vpc-1" } },
+    { id: "vpc-2", kind: "AWS::EC2::VPC", lexicon: "aws", physicalId: "vpc-2", attrs: { VpcId: "vpc-2" } },
+    { id: "web", kind: "AWS::EC2::Instance", lexicon: "aws", physicalId: "i-1", attrs: { VpcId: "vpc-1", SubnetId: "sub-1" } },
+  ];
+
+  it("reaches its VPC in one hop", () => {
+    const { containmentEdges } = reconstructEdges(nodes, awsReferenceCatalog);
+    expect(containmentEdges).toContainEqual({ from: "web", to: "vpc-1", kind: "ref", viaAttr: "VpcId" });
+  });
+
+  it("leaves an empty VPC reached by nothing — the question being asked", () => {
+    const { containmentEdges } = reconstructEdges(nodes, awsReferenceCatalog);
+    expect(containmentEdges.some((e) => e.to === "vpc-2")).toBe(false);
+  });
+
+  it("does not draw it — the VPC stays a boundary", () => {
+    const { edges } = reconstructEdges(nodes, awsReferenceCatalog);
+    expect(edges.some((e) => e.to === "vpc-1")).toBe(false);
+  });
+});

package/src/reference-catalog.ts

@@ -35,6 +35,13 @@ export const awsReferenceCatalog: ReferenceCatalog = {
     { from: "AWS::EC2::SecurityGroup", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
     { from: "AWS::EC2::RouteTable", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
     { from: "AWS::EC2::Instance", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet", viaAttr: "SubnetId" },
+    // An instance is in a VPC, and `describe-instances` says so directly. The
+    // other three kinds that sit in a VPC — subnet, security group, route table
+    // — all had this rule; the instance did not, so the estate's own topology
+    // was missing its most-asked-about member. Nothing derived it either: the
+    // instance reached its VPC only through its subnet, two hops, which a
+    // one-hop `<-` cannot cross.
+    { from: "AWS::EC2::Instance", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
     { from: "AWS::EC2::NatGateway", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
     { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "AvailabilityZones[].SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
     { from: "AWS::ElasticLoadBalancingV2::TargetGroup", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },

package/src/spec/pin.test.ts

@@ -0,0 +1,248 @@
+import { describe, test, expect } from "vitest";
+import {
+  AWS_SPEC_PIN,
+  PINNED_TYPE_NAMES,
+  ACCEPT_ENV,
+  specContentDigest,
+  specDrift,
+  driftMessage,
+  assertPinnedSpec,
+} from "./pin";
+
+const schema = (typeName: string, extra = "") =>
+  Buffer.from(JSON.stringify({ typeName, description: extra }));
+
+const archive = (...names: string[]): Map<string, Buffer> =>
+  new Map(names.map((n) => [n, schema(n)]));
+
+const pinFor = (schemas: Map<string, Buffer>) => ({
+  digest: specContentDigest(schemas),
+  resources: schemas.size,
+  accepted: "2026-01-01",
+});
+
+describe("specContentDigest (#1390)", () => {
+  test("is stable across map insertion order", () => {
+    // The zip's file order is not something to depend on.
+    const a = archive("AWS::A::One", "AWS::B::Two");
+    const b = new Map([...a.entries()].reverse());
+    expect(specContentDigest(a)).toBe(specContentDigest(b));
+  });
+
+  test("changes when a schema's bytes change", () => {
+    const before = archive("AWS::A::One");
+    const after = new Map([["AWS::A::One", schema("AWS::A::One", "now documented")]]);
+    expect(specContentDigest(after)).not.toBe(specContentDigest(before));
+  });
+
+  test("changes when a type is added", () => {
+    expect(specContentDigest(archive("AWS::A::One", "AWS::B::Two"))).not.toBe(
+      specContentDigest(archive("AWS::A::One")),
+    );
+  });
+
+  test("changes when a type is removed", () => {
+    expect(specContentDigest(archive("AWS::A::One"))).not.toBe(
+      specContentDigest(archive("AWS::A::One", "AWS::B::Two")),
+    );
+  });
+
+  test("an empty archive still digests", () => {
+    expect(specContentDigest(new Map())).toMatch(/^sha256:[0-9a-f]{64}$/);
+  });
+});
+
+describe("specDrift", () => {
+  const pinned = archive("AWS::A::One", "AWS::B::Two");
+  const pin = pinFor(pinned);
+  const names = new Set(pinned.keys());
+
+  test("null when the content matches", () => {
+    expect(specDrift(pinned, names, pin)).toBeNull();
+  });
+
+  test("names what was added", () => {
+    const drifted = archive("AWS::A::One", "AWS::B::Two", "AWS::C::Three");
+    expect(specDrift(drifted, names, pin)?.added).toEqual(["AWS::C::Three"]);
+  });
+
+  test("names what was removed", () => {
+    expect(specDrift(archive("AWS::A::One"), names, pin)?.removed).toEqual(["AWS::B::Two"]);
+  });
+
+  test("a changed schema drifts with no added or removed types", () => {
+    const changed = new Map(pinned);
+    changed.set("AWS::A::One", schema("AWS::A::One", "changed"));
+    const drift = specDrift(changed, names, pin);
+    expect(drift).not.toBeNull();
+    expect(drift!.added).toEqual([]);
+    expect(drift!.removed).toEqual([]);
+    expect(drift!.resources).toBe(pin.resources);
+  });
+
+  test("without a name set it still reports the count", () => {
+    const drift = specDrift(archive("AWS::A::One"), undefined, pin);
+    expect(drift?.resources).toBe(1);
+    expect(drift?.added).toEqual([]);
+  });
+});
+
+describe("driftMessage", () => {
+  const pinned = archive("AWS::A::One", "AWS::B::Two");
+  const pin = pinFor(pinned);
+  const names = new Set(pinned.keys());
+
+  test("states the count delta, not just that a digest differs", () => {
+    const drift = specDrift(archive("AWS::A::One", "AWS::B::Two", "AWS::C::Three"), names, pin)!;
+    expect(driftMessage(drift, pin)).toContain("+1 against the pin");
+  });
+
+  test("says so when only content changed", () => {
+    const changed = new Map(pinned);
+    changed.set("AWS::A::One", schema("AWS::A::One", "changed"));
+    expect(driftMessage(specDrift(changed, names, pin)!, pin)).toContain("unchanged in count");
+  });
+
+  test("prints the block to paste into the pin", () => {
+    const drift = specDrift(archive("AWS::A::One"), names, pin)!;
+    const message = driftMessage(drift, pin);
+    expect(message).toContain(`digest: "${drift.digest}"`);
+    expect(message).toContain("resources: 1,");
+  });
+
+  test("truncates a long list rather than printing hundreds of names", () => {
+    const many = archive("AWS::A::One", "AWS::B::Two", ...Array.from({ length: 9 }, (_, i) => `AWS::N::T${i}`));
+    expect(driftMessage(specDrift(many, names, pin)!, pin)).toContain("+4 more");
+  });
+});
+
+describe("assertPinnedSpec", () => {
+  const pinned = archive("AWS::A::One");
+  const pin = pinFor(pinned);
+  const names = new Set(pinned.keys());
+
+  test("passes when the archive matches", () => {
+    expect(() => assertPinnedSpec(pinned, { pin, pinnedNames: names, env: {} })).not.toThrow();
+  });
+
+  test("refuses a drifted archive — generation does not proceed", () => {
+    expect(() => assertPinnedSpec(archive("AWS::A::One", "AWS::B::Two"), { pin, pinnedNames: names, env: {} }))
+      .toThrow(/upstream CloudFormation schema has moved/);
+  });
+
+  test("the accept env proceeds and reports instead", () => {
+    const warnings: string[] = [];
+    expect(() =>
+      assertPinnedSpec(archive("AWS::A::One", "AWS::B::Two"), {
+        pin,
+        pinnedNames: names,
+        env: { [ACCEPT_ENV]: "1" },
+        warn: (m) => warnings.push(m),
+      }),
+    ).not.toThrow();
+    expect(warnings[0]).toContain("AWS::B::Two");
+  });
+});
+
+describe("the committed pin", () => {
+  test("records as many type names as it claims resources", () => {
+    // A pin bumped without regenerating the name list would make every future
+    // drift message wrong about what was added.
+    expect(PINNED_TYPE_NAMES.size).toBe(AWS_SPEC_PIN.resources);
+  });
+
+  test("is a sha256 and an ISO date", () => {
+    expect(AWS_SPEC_PIN.digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+    expect(AWS_SPEC_PIN.accepted).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+
+  test("holds real CloudFormation type names", () => {
+    expect(PINNED_TYPE_NAMES.has("AWS::S3::Bucket")).toBe(true);
+    expect(PINNED_TYPE_NAMES.has("AWS::IAM::Role")).toBe(true);
+  });
+});
+
+/**
+ * chant #1473 — byte churn is a warning, a moved resource set is still a
+ * refusal. The aws lexicon became unpublishable because upstream republishes
+ * schemas several times a day and any digest mismatch was fatal.
+ */
+describe("byte churn vs a moved resource set (#1473)", () => {
+  const pinned = archive("AWS::S3::Bucket", "AWS::IAM::Role");
+  const pin = pinFor(pinned);
+  const names = new Set(pinned.keys());
+
+  function capture(schemas: Map<string, Buffer>) {
+    const warnings: string[] = [];
+    let threw: Error | undefined;
+    try {
+      assertPinnedSpec(schemas, { pin, pinnedNames: names, env: {}, warn: (m) => warnings.push(m) });
+    } catch (err) {
+      threw = err as Error;
+    }
+    return { warnings, threw };
+  }
+
+  test("same type set, different bytes — warns and proceeds", () => {
+    // AWS editing a description in place. Three digests were observed in one
+    // day this way, all with an unchanged resource count.
+    const edited = new Map(pinned);
+    edited.set("AWS::S3::Bucket", schema("AWS::S3::Bucket", "reworded"));
+
+    const { warnings, threw } = capture(edited);
+    expect(threw).toBeUndefined();
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("resource set is unchanged");
+    expect(warnings[0]).toContain("surface.snapshot.json");
+  });
+
+  test("a type removed — still refuses", () => {
+    const { threw } = capture(archive("AWS::S3::Bucket"));
+    expect(threw?.message).toContain("Generation refuses");
+    expect(threw?.message).toContain("removed");
+  });
+
+  test("a type added — still refuses", () => {
+    const { threw } = capture(archive("AWS::S3::Bucket", "AWS::IAM::Role", "AWS::SQS::Queue"));
+    expect(threw?.message).toContain("Generation refuses");
+    expect(threw?.message).toContain("added");
+  });
+
+  test("an unchanged archive neither warns nor throws", () => {
+    const { warnings, threw } = capture(new Map(pinned));
+    expect(threw).toBeUndefined();
+    expect(warnings).toEqual([]);
+  });
+
+  test("with no previous type set to compare, a mismatch stays fatal", () => {
+    // `specDrift` reports empty added/removed when it cannot compare, which
+    // would otherwise read as "no type moved" and downgrade every mismatch.
+    const edited = new Map(pinned);
+    edited.set("AWS::S3::Bucket", schema("AWS::S3::Bucket", "reworded"));
+
+    expect(() =>
+      assertPinnedSpec(edited, { pin, pinnedNames: new Set(), env: {}, warn: () => {} }),
+    ).toThrow(/Generation refuses/);
+  });
+
+  test("the accept env still short-circuits both cases", () => {
+    const warnings: string[] = [];
+    assertPinnedSpec(archive("AWS::S3::Bucket"), {
+      pin,
+      pinnedNames: names,
+      env: { [ACCEPT_ENV]: "1" },
+      warn: (m) => warnings.push(m),
+    });
+    expect(warnings[0]).toContain(ACCEPT_ENV);
+  });
+
+  test("the non-fatal message still prints a pastable pin block", () => {
+    const edited = new Map(pinned);
+    edited.set("AWS::IAM::Role", schema("AWS::IAM::Role", "reworded"));
+    const { warnings } = capture(edited);
+    expect(warnings[0]).toContain('  digest: "sha256:');
+    expect(warnings[0]).toContain("  resources: 2,");
+    // The one-off escape hatch is meaningless when nothing is being refused.
+    expect(warnings[0]).not.toContain(ACCEPT_ENV);
+  });
+});

package/src/spec/pin.ts

@@ -0,0 +1,247 @@
+/**
+ * Content pin for the CloudFormation Registry schema (#1390).
+ *
+ * cfn-lint is pinned to a git tag (`PINNED_VERSIONS.cfnLint`). The registry
+ * schema could not be: it is a single "latest" artifact with no version in the
+ * path, republished constantly —
+ *
+ *     $ curl -sI .../CloudformationSchema.zip
+ *     Last-Modified: Mon, 03 Aug 2026 01:29:20 GMT
+ *
+ * — so `npm run --prefix lexicons/aws prepack`, which CI runs on every build and
+ * any local codegen or docs task triggers, resolved to whatever CloudFormation
+ * shipped that morning. During the #1312 docs work a docs-only branch twice
+ * picked up a resource-count move with nothing in the commit explaining it. The
+ * count was only the visible symptom; the same regeneration rewrites generated
+ * types and the resource registry.
+ *
+ * Since there is no version to pin, the pin is over content. Specifically over
+ * the **extracted schemas**, not the zip: AWS repackaging the archive changes
+ * its `ETag` and its bytes while the schemas are identical, and a pin that fires
+ * on that would be noise. Sorted `typeName` → `sha256(schema)`, hashed in order,
+ * moves exactly when a schema does.
+ *
+ * Advisory is not enough here, unlike the emulator image pins (#808). An
+ * emulator that drifts fails a test you can see; a spec that drifts silently
+ * rewrites committed artifacts in a branch about something else. So a mismatch
+ * refuses, and accepting is a deliberate act that lands as its own commit.
+ */
+
+import { createHash } from "crypto";
+import pinnedTypes from "./pinned-types.json" with { type: "json" };
+
+/**
+ * The resource types the pinned archive contained.
+ *
+ * Committed beside the digest so accepting a new spec is reviewable as a diff:
+ * the PR that moves the pin shows exactly which types AWS added or removed,
+ * rather than one opaque hash replacing another. The generated artifacts cannot
+ * play that role — `src/generated/` is not committed.
+ */
+export const PINNED_TYPE_NAMES: ReadonlySet<string> = new Set(pinnedTypes as string[]);
+
+export interface SpecPin {
+  /** `sha256:…` over the sorted typeName → schema content. */
+  readonly digest: string;
+  /** How many resource types the pinned archive contained. */
+  readonly resources: number;
+  /** ISO date the pin was accepted, so a diff reads as a decision. */
+  readonly accepted: string;
+}
+
+/**
+ * The accepted upstream spec.
+ *
+ * To move it: run generation, read the refusal, confirm the delta is one you
+ * want, and paste the printed pin here in its own commit.
+ */
+export const AWS_SPEC_PIN: SpecPin = {
+  digest: "sha256:f2a0f4f2c0685116fa928a01d889b2aa2a03e4f02cd3257b124cbb184f7e533b",
+  resources: 1650,
+  accepted: "2026-08-04",
+};
+
+/** Env var that accepts whatever upstream currently serves, printing the new pin. */
+export const ACCEPT_ENV = "CHANT_ACCEPT_AWS_SPEC";
+
+/**
+ * Digest the extracted schemas. Stable against repackaging; changes when any
+ * schema's bytes change, or when a type is added or removed.
+ */
+export function specContentDigest(schemas: ReadonlyMap<string, Buffer>): string {
+  const hash = createHash("sha256");
+  for (const typeName of [...schemas.keys()].sort()) {
+    hash.update(typeName);
+    hash.update(createHash("sha256").update(schemas.get(typeName)!).digest());
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+/** What moved between the pinned archive and the one just fetched. */
+export interface SpecDrift {
+  digest: string;
+  resources: number;
+  added: string[];
+  removed: string[];
+}
+
+/** Compare a freshly fetched archive against a pin. `null` when it matches. */
+export function specDrift(
+  schemas: ReadonlyMap<string, Buffer>,
+  pinnedNames: ReadonlySet<string> | undefined,
+  pin: SpecPin = AWS_SPEC_PIN,
+): SpecDrift | null {
+  const digest = specContentDigest(schemas);
+  if (digest === pin.digest) return null;
+
+  const names = new Set(schemas.keys());
+  return {
+    digest,
+    resources: names.size,
+    // Type names are only known when a caller supplies the previous set;
+    // without it the count delta still tells a reader the shape of the change.
+    added: pinnedNames ? [...names].filter((n) => !pinnedNames.has(n)).sort() : [],
+    removed: pinnedNames ? [...pinnedNames].filter((n) => !names.has(n)).sort() : [],
+  };
+}
+
+/** The refusal a mismatch produces, or the acceptance notice under {@link ACCEPT_ENV}. */
+export function driftMessage(
+  drift: SpecDrift,
+  pin: SpecPin = AWS_SPEC_PIN,
+  options: { fatal?: boolean } = {},
+): string {
+  const fatal = options.fatal ?? true;
+  const delta = drift.resources - pin.resources;
+  const countLine =
+    delta === 0
+      ? `${drift.resources} resource types, unchanged in count`
+      : `${drift.resources} resource types, ${delta > 0 ? "+" : ""}${delta} against the pin`;
+
+  const lines = [
+    "The upstream CloudFormation schema has moved since the pinned one.",
+    "",
+    `  pinned    ${pin.digest}  (${pin.resources} resources, accepted ${pin.accepted})`,
+    `  upstream  ${drift.digest}  (${countLine})`,
+  ];
+
+  if (drift.added.length > 0) {
+    lines.push(`  added     ${drift.added.slice(0, 5).join(", ")}${drift.added.length > 5 ? ` (+${drift.added.length - 5} more)` : ""}`);
+  }
+  if (drift.removed.length > 0) {
+    lines.push(`  removed   ${drift.removed.slice(0, 5).join(", ")}${drift.removed.length > 5 ? ` (+${drift.removed.length - 5} more)` : ""}`);
+  }
+
+  if (fatal) {
+    lines.push(
+      "",
+      "Generation refuses rather than regenerating against a spec nobody chose:",
+      "a docs or codegen task on an unrelated branch would otherwise rewrite the",
+      "generated types and resource registry with no commit saying why.",
+    );
+  } else {
+    // chant #1473 — the type set is identical, so this is upstream editing
+    // schemas in place, not a spec swap. Generation continues; whether it
+    // changed anything visible is decided by the surface snapshot.
+    lines.push(
+      "",
+      "The resource set is unchanged, so this is upstream editing schemas in",
+      "place rather than a different spec. Generation continues — whether it",
+      "changed the published API is decided by surface.snapshot.json, which is",
+      "checked against the generated artifacts before anything is packed.",
+    );
+  }
+
+  lines.push(
+    "",
+    "To refresh the pin, confirm the delta is one you want and update",
+    "lexicons/aws/src/spec/pin.ts, in its own commit:",
+    "",
+    `  digest: "${drift.digest}",`,
+    `  resources: ${drift.resources},`,
+    `  accepted: "<today>",`,
+  );
+
+  if (fatal) {
+    lines.push("", `Or re-run with ${ACCEPT_ENV}=1 to proceed this once and print the same block.`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Refuse a fetched archive whose RESOURCE SET does not match the pin.
+ *
+ * Under {@link ACCEPT_ENV} it warns with the same detail instead, so the
+ * accept-then-paste loop is one command rather than two.
+ *
+ * ## Why byte drift alone is a warning (chant #1473)
+ *
+ * This originally threw on any digest mismatch, which made the aws lexicon
+ * unpublishable. `prepack` runs `generate`, `generate` fetches from upstream,
+ * and CloudFormation republishes individual schemas several times a day: three
+ * distinct digests were observed on 2026-08-03 alone, all with an unchanged
+ * count of 1650, and two fetches two hours apart differed in 4 of 1650 files.
+ * `chant-v0.39.0` published 13 packages and failed on aws for exactly this,
+ * with a pin ~18 hours old.
+ *
+ * A pin that goes stale by itself within hours cannot gate a release: it does
+ * not distinguish "someone regenerated against a spec nobody chose" from
+ * "AWS edited a description this afternoon".
+ *
+ * So the two cases are separated:
+ *
+ *  - **The resource set moved** (a type added or removed) — still a refusal.
+ *    That always changes the published API, and it is the case #1390 was filed
+ *    about.
+ *  - **Only bytes moved**, with an identical type set — a warning. Whether it
+ *    matters is decided downstream by the surface gate in core's
+ *    `validateLexiconArtifacts`, which compares the generated API against the
+ *    committed `surface.snapshot.json`. That gate is exact: a byte change that
+ *    alters the emitted surface fails the build, and one that does not is
+ *    correctly ignored.
+ *
+ * The guarantee is unchanged in substance — nothing ships whose surface was
+ * not reviewed — and it is now enforced against the thing that actually
+ * matters rather than against an archive that is not stable enough to pin.
+ */
+export function assertPinnedSpec(
+  schemas: ReadonlyMap<string, Buffer>,
+  options: {
+    pin?: SpecPin;
+    /** Defaults to {@link PINNED_TYPE_NAMES}; overridden in tests. */
+    pinnedNames?: ReadonlySet<string>;
+    env?: NodeJS.ProcessEnv;
+    warn?: (message: string) => void;
+  } = {},
+): void {
+  const pin = options.pin ?? AWS_SPEC_PIN;
+  const pinnedNames = options.pinnedNames ?? PINNED_TYPE_NAMES;
+  const drift = specDrift(schemas, pinnedNames, pin);
+  if (!drift) return;
+
+  const env = options.env ?? process.env;
+  const warn = options.warn ?? ((m: string) => console.error(m));
+
+  if (env[ACCEPT_ENV]) {
+    warn(driftMessage(drift, pin));
+    return;
+  }
+
+  // chant #1473 — an identical type set with different bytes is upstream
+  // churn, not an unchosen spec. Reported so a stale pin stays visible, but
+  // not fatal; the surface gate decides whether it changed anything.
+  //
+  // Guarded on actually HAVING a previous type set: `specDrift` reports empty
+  // added/removed when it has nothing to compare against, which would
+  // otherwise read as "no type moved" and downgrade every mismatch.
+  const typeSetKnown = pinnedNames !== undefined && pinnedNames.size > 0;
+  const typeSetMoved = drift.added.length > 0 || drift.removed.length > 0;
+
+  if (typeSetKnown && !typeSetMoved) {
+    warn(driftMessage(drift, pin, { fatal: false }));
+    return;
+  }
+
+  throw new Error(driftMessage(drift, pin));
+}