@intentius/chant-lexicon-aws 0.124.31 → 0.124.32

package/dist/spec/fetch.js

@@ -0,0 +1,193 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { fetchWithCache, extractFromZip, clearCacheFile } from "@intentius/chant/codegen/fetch";
+import { RELEASE_GATE_ENV } from "@intentius/chant/codegen/validate";
+import { ACCEPT_ENV, AWS_SPEC_PIN, specContentDigest } from "./pin.js";
+/** Per-attempt download timeout for a multi-megabyte archive. */
+const ARCHIVE_ATTEMPT_TIMEOUT_MS = 120000;
+const SCHEMA_ZIP_URL = "https://schema.cloudformation.us-east-1.amazonaws.com/CloudformationSchema.zip";
+const CACHE_DIR = join(homedir(), ".chant");
+const CACHE_FILE = join(CACHE_DIR, "CloudformationSchema.zip");
+/**
+ * The pinned-spec store (chant #1511): assets on one dedicated GitHub release,
+ * named by content digest, in a public repo — so nothing binary ever enters
+ * git history, and the download needs no auth anywhere (CI included).
+ *
+ * Why a store at all: `prepack` regenerates from upstream, and the registry
+ * serves a single mutable "latest" artifact — on 2026-08-05 four distinct
+ * contents were observed in one day, two *contradicting* each other about the
+ * same resources, so the surface gate compared artifacts built from whichever
+ * variant that fetch happened to hit. Publishing aws was a retry lottery
+ * (v0.41.1 and v0.41.2 both stranded it). The accepted content itself is the
+ * only deterministic input; the accept uploads it, every build downloads it
+ * by digest and verifies before trusting it.
+ */
+const SPEC_PIN_RELEASE_TAG = "aws-spec-pin";
+const SPEC_PIN_REPO = "INTENTIUS/chant";
+/** Verified-by-digest local copies of pin assets, so repeat builds skip the download. Content-addressed: no TTL, never invalidated. */
+const PIN_CACHE_DIR = join(CACHE_DIR, "spec-pin");
+/** `<first 12 digest hex>.zip` — the asset (and local cache) name for a pin. */
+export function pinAssetName(pin = AWS_SPEC_PIN) {
+    return `${pin.digest.replace(/^sha256:/, "").slice(0, 12)}.zip`;
+}
+/** Public, unauthenticated download URL for a pin's asset. */
+export function pinAssetUrl(pin = AWS_SPEC_PIN) {
+    return `https://github.com/${SPEC_PIN_REPO}/releases/download/${SPEC_PIN_RELEASE_TAG}/${pinAssetName(pin)}`;
+}
+const downloadPinAsset = async (url) => {
+    try {
+        const res = await fetch(url, { redirect: "follow" });
+        if (!res.ok)
+            return undefined;
+        return Buffer.from(await res.arrayBuffer());
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Load and verify the pinned spec: the local verified cache first, then the
+ * release asset. Returns undefined when neither is available (offline and
+ * cold, or the accept never uploaded) — the caller falls back to the live
+ * fetch and the pin's existing advisory drift report. Content that does not
+ * digest to the pin throws: a tampered or half-uploaded asset must never
+ * silently pass as the accepted spec, wherever it came from.
+ */
+export async function loadPinnedSchemas(options = {}) {
+    const pin = options.pin ?? AWS_SPEC_PIN;
+    const cacheDir = options.cacheDir ?? PIN_CACHE_DIR;
+    const cachePath = join(cacheDir, pinAssetName(pin));
+    const verify = async (zipData, source) => {
+        const schemas = await extractRawSchemas(zipData);
+        const digest = specContentDigest(schemas);
+        if (digest !== pin.digest) {
+            throw new Error(`pinned spec from ${source} extracts to ${digest}, but the pin declares ${pin.digest} — ` +
+                `refusing to build from it. Re-run the accept (${ACCEPT_ENV}=1 npm run generate) to ` +
+                `upload the content the pin actually names.`);
+        }
+        return schemas;
+    };
+    if (existsSync(cachePath)) {
+        return verify(readFileSync(cachePath), cachePath);
+    }
+    const url = pinAssetUrl(pin);
+    const zipData = await (options.download ?? downloadPinAsset)(url);
+    if (zipData === undefined)
+        return undefined;
+    const schemas = await verify(zipData, url);
+    // Cache only after verification, so the cache can never hold a bad copy.
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(cachePath, zipData);
+    return schemas;
+}
+/**
+ * The accept flow's upload half: push the just-accepted zip to the pin
+ * release via `gh` (dev-machine path — publishes never upload). Creates the
+ * rolling `aws-spec-pin` release on first use. Assets are content-addressed
+ * and never overwritten. A missing/unauthenticated `gh` degrades to printing
+ * the exact command to run by hand — the accept still completes, and the pin
+ * block still prints.
+ */
+async function uploadPinAsset(zipData, digest) {
+    const pin = { ...AWS_SPEC_PIN, digest };
+    mkdirSync(PIN_CACHE_DIR, { recursive: true });
+    const localPath = join(PIN_CACHE_DIR, pinAssetName(pin));
+    writeFileSync(localPath, zipData);
+    const run = promisify(execFile);
+    try {
+        try {
+            await run("gh", ["release", "view", SPEC_PIN_RELEASE_TAG, "--repo", SPEC_PIN_REPO]);
+        }
+        catch {
+            await run("gh", [
+                "release", "create", SPEC_PIN_RELEASE_TAG,
+                "--repo", SPEC_PIN_REPO,
+                "--title", "aws spec pin assets",
+                "--notes", "Content-addressed CloudFormation registry archives, one per accepted spec pin (chant #1511). Uploaded by the accept flow; downloaded and digest-verified by every build. Not a chant release.",
+            ]);
+        }
+        await run("gh", ["release", "upload", SPEC_PIN_RELEASE_TAG, localPath, "--repo", SPEC_PIN_REPO]);
+        console.error(`Accepted spec uploaded: ${pinAssetUrl(pin)}`);
+    }
+    catch (err) {
+        console.error(`Could not upload the accepted spec via gh (${err instanceof Error ? err.message.split("\n")[0] : String(err)}).\n` +
+            `Upload it yourself before merging the pin:\n` +
+            `  gh release upload ${SPEC_PIN_RELEASE_TAG} ${localPath} --repo ${SPEC_PIN_REPO}`);
+    }
+}
+/**
+ * Fetch the CloudFormation Registry schema zip and extract per-resource JSON schemas.
+ * Returns a Map keyed by typeName (e.g. "AWS::S3::Bucket") to raw JSON bytes.
+ *
+ * chant #1511 — the pinned release asset is the primary source: when it
+ * resolves and digest-verifies, generation uses the content a human accepted
+ * rather than whatever upstream variant this fetch happens to hit, so every
+ * build (CI, prepack, publish) is deterministic. The live fetch remains for:
+ * `force`, the accept flow (`CHANT_ACCEPT_AWS_SPEC=1`, which must sample
+ * upstream — and bypasses the 24h cache for the same reason), and when the
+ * asset is unreachable. The live path keeps its 24h local cache.
+ *
+ * chant #1481 — the fallback is what made two workflows disagree about one
+ * commit. The live archive is served from CloudFront and two fetches seconds
+ * apart can get different variants; under the release gate, building from
+ * it would ship a surface nobody reviewed on a retry lottery, so the gate
+ * refuses instead. Anywhere else the fallback stays, but says so, because a
+ * silent fallback is indistinguishable from the pinned path in a CI log.
+ */
+export async function fetchSchemaZip(force = false, options = {}) {
+    const env = options.env ?? process.env;
+    const accepting = !!env[ACCEPT_ENV];
+    if (!force && !accepting) {
+        const pinned = await loadPinnedSchemas({ download: options.download, cacheDir: options.pinCacheDir });
+        if (pinned)
+            return pinned;
+        if (env[RELEASE_GATE_ENV] === "1") {
+            throw new Error(`${RELEASE_GATE_ENV}=1 and the pinned spec asset could not be loaded (${pinAssetUrl()}) — ` +
+                `refusing to build a release from the live CloudFormation archive, which is not the content ` +
+                `the pin was reviewed against. Check the asset exists on the ${SPEC_PIN_RELEASE_TAG} release ` +
+                `(the accept flow uploads it: ${ACCEPT_ENV}=1 npm run generate).`);
+        }
+        console.error(`pinned spec asset unavailable (${pinAssetUrl()}); falling back to the live CloudFormation archive`);
+    }
+    const zipData = await fetchWithCache({ url: SCHEMA_ZIP_URL, cacheFile: CACHE_FILE, attemptTimeoutMs: ARCHIVE_ATTEMPT_TIMEOUT_MS }, force || accepting);
+    const schemas = await extractRawSchemas(zipData);
+    if (accepting) {
+        await uploadPinAsset(zipData, specContentDigest(schemas));
+    }
+    return schemas;
+}
+/**
+ * Extract raw JSON schema bytes from the zip, keyed by typeName.
+ */
+async function extractRawSchemas(zipData) {
+    const files = await extractFromZip(zipData, (name) => name.endsWith(".json"));
+    const schemas = new Map();
+    for (const [_name, data] of files) {
+        try {
+            const text = data.toString("utf-8");
+            const partial = JSON.parse(text);
+            if (!partial.typeName)
+                continue;
+            schemas.set(partial.typeName, data);
+        }
+        catch {
+            // Skip files that can't be parsed
+        }
+    }
+    return schemas;
+}
+/**
+ * Get the cache file path (for testing)
+ */
+export function getCachePath() {
+    return CACHE_FILE;
+}
+/**
+ * Clear the cache (for testing)
+ */
+export function clearCache() {
+    clearCacheFile(CACHE_FILE);
+}

package/dist/spec/parse.js

@@ -0,0 +1,259 @@
+/**
+ * CloudFormation Registry JSON Schema parser.
+ *
+ * Parses each CFNSchema into typed structures suitable for code generation:
+ * resources with properties and attributes, property types from definitions,
+ * and enum types from string enum definitions.
+ */
+import { resolvePropertyType as coreResolvePropertyType, extractConstraints as coreExtractConstraints, constraintsIsEmpty as coreConstraintsIsEmpty, isEnumDefinition as coreIsEnumDefinition, } from "@intentius/chant/codegen/json-schema";
+import { boundPropertyTypes } from "@intentius/chant/codegen/bound-property-types";
+/**
+ * Maximum nesting depth of generated property-type interfaces. Bounds the
+ * shipped `.d.ts` size: property types reachable from a resource's top-level
+ * properties within this depth stay typed; deeper ones are loosened to
+ * `Record<string, unknown>`. Set high enough that the shapes composites consume
+ * (which reach a few levels into CFN config) remain typed. (#440)
+ */
+const MAX_PROPERTY_TYPE_DEPTH = 3;
+/**
+ * Prose signals that a property description is describing a deprecation.
+ * A hit is a guess, not a reading — see `ParsedResource.inferredDeprecations`.
+ */
+const DEPRECATION_RE = /\bdeprecated\b|\blegacy\b|no longer (available|recommended|used|supported)|is not recommended|has been discontinued/i;
+/**
+ * Parse a CloudFormation Registry JSON Schema into typed structures.
+ */
+export function parseCFNSchema(data) {
+    const schema = JSON.parse(typeof data === "string" ? data : data.toString("utf-8"));
+    const requiredSet = new Set(schema.required ?? []);
+    const shortName = cfnShortName(schema.typeName);
+    // Parse top-level properties
+    const props = [];
+    if (schema.properties) {
+        for (const [name, prop] of Object.entries(schema.properties)) {
+            const tsType = resolvePropertyType(prop, schema);
+            props.push({
+                name,
+                tsType,
+                required: requiredSet.has(name),
+                description: prop.description,
+                enum: prop.enum,
+                constraints: extractConstraints(prop),
+            });
+        }
+    }
+    // Parse readOnlyProperties as attributes
+    // Deduplicate — some upstream schemas (e.g. aws-s3files-filesystem) list the same
+    // property twice in readOnlyProperties, which would produce duplicate class members.
+    const attrs = [];
+    const seenAttrs = new Set();
+    for (const path of schema.readOnlyProperties ?? []) {
+        const attrName = stripPointerPath(path, schema);
+        // Flatten nested paths: "Endpoint/Address" → attr name "Endpoint.Address"
+        const cfnAttr = attrName.replace(/\//g, ".");
+        if (seenAttrs.has(cfnAttr))
+            continue;
+        seenAttrs.add(cfnAttr);
+        let tsType = "string";
+        // For top-level attrs, look up type from properties
+        if (!cfnAttr.includes(".") && schema.properties?.[cfnAttr]) {
+            tsType = resolvePropertyType(schema.properties[cfnAttr], schema);
+        }
+        // For nested attrs, type is always string (CF GetAtt returns strings for leaf values)
+        attrs.push({ name: cfnAttr, tsType });
+    }
+    // Parse definitions into property types and enums
+    const propertyTypes = [];
+    const enums = [];
+    if (schema.definitions) {
+        for (const [defName, def] of Object.entries(schema.definitions)) {
+            if (isEnumDefinition(def)) {
+                enums.push({
+                    name: `${shortName}_${defName}`,
+                    values: def.enum,
+                });
+                continue;
+            }
+            if (def.properties) {
+                const defRequired = new Set(def.required ?? []);
+                const defProps = [];
+                for (const [propName, prop] of Object.entries(def.properties)) {
+                    const tsType = resolvePropertyType(prop, schema);
+                    defProps.push({
+                        name: propName,
+                        tsType,
+                        required: defRequired.has(propName),
+                        description: prop.description,
+                        enum: prop.enum,
+                        constraints: extractConstraints(prop),
+                    });
+                }
+                propertyTypes.push({
+                    name: `${shortName}_${defName}`,
+                    specType: defName,
+                    properties: defProps,
+                });
+            }
+        }
+    }
+    // --- Deprecated properties: declared upstream, plus description-mined ---
+    // The declared half is what the Registry schema states. The mined half is a
+    // regex over English prose and is recorded separately (#1701): a description
+    // can mention the deprecation of a sibling property, of an enum value, or of
+    // something the property merely configures.
+    const deprecatedSet = new Set(stripPointerPaths(schema.deprecatedProperties ?? [], schema));
+    const inferredDeprecations = [];
+    // Mine top-level property descriptions
+    if (schema.properties) {
+        for (const [name, prop] of Object.entries(schema.properties)) {
+            if (!prop.description || !DEPRECATION_RE.test(prop.description))
+                continue;
+            // A hit upstream already declares adds nothing, and is not an inference.
+            if (deprecatedSet.has(name))
+                continue;
+            deprecatedSet.add(name);
+            inferredDeprecations.push(name);
+        }
+    }
+    // --- Tagging ---
+    let tagging;
+    if (schema.tagging && schema.tagging.taggable) {
+        tagging = {
+            taggable: true,
+            tagOnCreate: schema.tagging.tagOnCreate ?? false,
+            tagUpdatable: schema.tagging.tagUpdatable ?? false,
+        };
+    }
+    // --- Replacement strategy ---
+    let replacementStrategy;
+    if (schema.replacementStrategy === "delete_then_create" || schema.replacementStrategy === "create_then_delete") {
+        replacementStrategy = schema.replacementStrategy;
+    }
+    // Bound the emitted property types to keep the shipped declaration small while
+    // preserving the shapes composites and shallow authoring rely on (#440).
+    const boundedPropertyTypes = boundPropertyTypes(shortName, props, propertyTypes, new Set(enums.map((e) => e.name)), { maxDepth: MAX_PROPERTY_TYPE_DEPTH });
+    return {
+        resource: {
+            typeName: schema.typeName,
+            properties: props,
+            attributes: attrs,
+            createOnly: stripPointerPaths(schema.createOnlyProperties ?? [], schema),
+            writeOnly: stripPointerPaths(schema.writeOnlyProperties ?? [], schema),
+            primaryIdentifier: stripPointerPaths(schema.primaryIdentifier ?? [], schema),
+            deprecatedProperties: [...deprecatedSet],
+            inferredDeprecations,
+            conditionalCreateOnly: stripPointerPaths(schema.conditionalCreateOnlyProperties ?? [], schema),
+            ...(replacementStrategy && { replacementStrategy }),
+            ...(tagging && { tagging }),
+        },
+        propertyTypes: boundedPropertyTypes,
+        enums,
+    };
+}
+// --- Type resolution (delegated to core) ---
+function resolvePropertyType(prop, schema) {
+    const shortName = cfnShortName(schema.typeName);
+    return coreResolvePropertyType(prop, schema, (defName) => `${shortName}_${defName}`);
+}
+function extractConstraints(prop) {
+    return coreExtractConstraints(prop);
+}
+export const constraintsIsEmpty = coreConstraintsIsEmpty;
+function isEnumDefinition(def) {
+    return coreIsEnumDefinition(def);
+}
+/**
+ * Extract short resource name: "AWS::S3::Bucket" → "Bucket"
+ */
+export function cfnShortName(typeName) {
+    const parts = typeName.split("::");
+    return parts.length >= 3 ? parts[2] : typeName;
+}
+/**
+ * Extract service name: "AWS::S3::Bucket" → "S3"
+ */
+export function cfnServiceName(typeName) {
+    const parts = typeName.split("::");
+    return parts.length >= 2 ? parts[1] : typeName;
+}
+/** Bound on the `$ref` walk that resolves a definition-scoped pointer. */
+const MAX_DEFINITION_PATH_DEPTH = 6;
+/** The definition a `#/definitions/Name` ref names, or undefined for anything else. */
+function refDefinitionName(ref) {
+    const prefix = "#/definitions/";
+    return ref?.startsWith(prefix) ? ref.slice(prefix.length) : undefined;
+}
+function pushProperties(queue, path, properties) {
+    for (const [name, prop] of Object.entries(properties))
+        queue.push({ path: [...path, name], node: prop });
+}
+/**
+ * The property path that reaches `defName`, searched breadth-first from the
+ * top-level properties so the shortest one wins. Undefined when nothing
+ * declared reaches the definition; the pointer is then left as the Registry
+ * wrote it rather than naming a key no template has.
+ */
+function definitionPropertyPath(defName, schema) {
+    const defs = schema.definitions ?? {};
+    const expanded = new Set();
+    const queue = [];
+    pushProperties(queue, [], schema.properties ?? {});
+    while (queue.length > 0) {
+        const { path, node } = queue.shift();
+        if (path.length > MAX_DEFINITION_PATH_DEPTH)
+            continue;
+        const ref = refDefinitionName(node.$ref);
+        if (ref === defName)
+            return path.join("/");
+        if (ref !== undefined) {
+            // Shortest path wins, so a definition already reached needs no second visit.
+            if (expanded.has(ref))
+                continue;
+            expanded.add(ref);
+            const def = defs[ref];
+            if (def?.properties)
+                pushProperties(queue, path, def.properties);
+            continue;
+        }
+        if (node.items) {
+            queue.push({ path: [...path, "*"], node: node.items });
+            continue;
+        }
+        if (node.properties)
+            pushProperties(queue, path, node.properties);
+    }
+    return undefined;
+}
+/**
+ * Flatten a CloudFormation Registry JSON pointer to the property path a
+ * template expresses, `/`-joined.
+ *
+ * Three shapes occur upstream. `/properties/BucketName` is the plain one.
+ * A pointer can re-enter the `properties` keyword mid-path
+ * (`/properties/DistributionConfig/properties/S3Origin`), which a template
+ * never writes. And a pointer can be scoped to a shared definition
+ * (`/definitions/ContinuousDeploymentPolicyConfig/properties/Type`), which a
+ * template expresses only through whichever property carries that definition.
+ *
+ * Array positions stay as `*`. `readOnlyProperties` attribute names are
+ * generated from this output, so dropping the wildcard would rename them.
+ */
+export function stripPointerPath(path, schema) {
+    if (!path.startsWith("/"))
+        return path;
+    const segments = path.split("/").filter((s) => s.length > 0);
+    if (segments[0] === "definitions") {
+        const prefix = segments[1] && schema ? definitionPropertyPath(segments[1], schema) : undefined;
+        if (prefix === undefined)
+            return path;
+        return [prefix, ...segments.slice(2).filter((s) => s !== "properties")].join("/");
+    }
+    if (segments[0] !== "properties")
+        return path;
+    return segments.slice(1).filter((s) => s !== "properties").join("/");
+}
+function stripPointerPaths(paths, schema) {
+    if (paths.length === 0)
+        return [];
+    return paths.map((p) => stripPointerPath(p, schema));
+}

package/dist/spec/pin.js

@@ -0,0 +1,185 @@
+/**
+ * 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 = new Set(pinnedTypes);
+/**
+ * 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 = {
+    digest: "sha256:398259716cca4a83d8ffc719fb214caf3ed6239c6be775e6d21952ce7ad8dae4",
+    resources: 1856,
+    accepted: "2026-10-19",
+};
+/** 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) {
+    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")}`;
+}
+/** Compare a freshly fetched archive against a pin. `null` when it matches. */
+export function specDrift(schemas, pinnedNames, pin = AWS_SPEC_PIN) {
+    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, pin = AWS_SPEC_PIN, options = {}) {
+    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, options = {}) {
+    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) => 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.
+    // chant #1473 — the pin reports, it does not gate.
+    //
+    // Refusing here made every aws PR hostage to CloudFormation: the archive
+    // gains and edits types through the day, and `generate` runs on every CI
+    // job, so an unrelated change goes red the moment upstream moves. Both the
+    // 0.39.0 and 0.40.1 releases died this way, and a PR *accepting* the drift
+    // was itself refused by a newer drift that arrived while its CI queued.
+    //
+    // Enforcement lives where the consequence is: core's
+    // `validateLexiconArtifacts` compares the generated API against the reviewed
+    // `surface.snapshot.json` and, armed by CHANT_RELEASE_GATE, refuses to
+    // publish a surface nobody reviewed. A new or removed type always shows up
+    // there, so nothing is lost by reporting rather than throwing here — while a
+    // description edit, which changes the digest and no declaration, stops
+    // costing a red build.
+    warn(driftMessage(drift, pin, { fatal: drift.added.length > 0 || drift.removed.length > 0 }));
+}