@intentius/chant-lexicon-aws 0.124.30 → 0.124.32

package/dist/behaviour-kinds.js

@@ -0,0 +1,114 @@
+/**
+ * What this lexicon's entity types are worth to a behaviour engine (#2382).
+ *
+ * Contributed as rows through the plugin's `behaviourKinds` field; the
+ * vocabulary, the resolution and the prediction are
+ * `packages/core/src/behaviour-kinds.ts`. These rows were a section of one
+ * cross-lexicon table in one lexicon until #2382 moved each substrate's
+ * rows to the lexicon that owns the types — this file can say what
+ * `AWS::EC2::Instance` means because it is the file that defines it.
+ *
+ * A table rather than a heuristic over type names: a heuristic would map
+ * `AWS::EC2::VolumeAttachment` to storage and price a join table.
+ */
+/** Types an engine prices, with the declared property its size is read from. */
+const MAPPED = {
+    "AWS::EC2::Instance": { kind: "compute", sizeProp: "InstanceType", sizeType: "string" },
+    "AWS::EC2::Volume": { kind: "block-store", sizeProp: "Size", sizeType: "number", regionProp: "AvailabilityZone" },
+    "AWS::Lambda::Function": { kind: "serverless", sizeProp: "MemorySize", sizeType: "number" },
+    "AWS::RDS::DBInstance": { kind: "database", sizeProp: "DBInstanceClass", sizeType: "string" },
+    "AWS::RDS::DBCluster": { kind: "database", sizeProp: "DBClusterInstanceClass", sizeType: "string" },
+    "AWS::DynamoDB::Table": { kind: "database", sizeProp: "BillingMode", sizeType: "string" },
+    "AWS::ElastiCache::CacheCluster": { kind: "cache", sizeProp: "CacheNodeType", sizeType: "string" },
+    "AWS::SQS::Queue": { kind: "queue" },
+    "AWS::SNS::Topic": { kind: "queue" },
+    "AWS::S3::Bucket": { kind: "object-store" },
+    "AWS::ElasticLoadBalancingV2::LoadBalancer": { kind: "load-balancer", sizeProp: "Type", sizeType: "string" },
+    "AWS::CloudFront::Distribution": { kind: "cdn" },
+    /** A flat hourly fee for the managed control plane. It does not move with the estate's traffic. */
+    "AWS::EKS::Cluster": { kind: "control-plane" },
+    /**
+     * A set of EC2 instances, and what an EKS estate actually costs. No size:
+     * `InstanceTypes` is a list, and this contract's `size` is one string.
+     */
+    "AWS::EKS::Nodegroup": { kind: "compute" },
+    /** The running thing. Its task definition is the template and carries no rate. */
+    "AWS::ECS::Service": { kind: "compute" },
+};
+/**
+ * Types considered and declared unsendable, each with the reason it carries no
+ * rate. Four of the five families core's contributor guidance names appear
+ * here: a grant is not a resource, a boundary is not a node, a meter chant
+ * cannot read is not a figure, and a template is not an instance.
+ */
+const UNMAPPED = {
+    // ── Grants ───────────────────────────────────────────────────────
+    "AWS::IAM::Role": "a role is a grant, not a resource traffic flows through: no rate, no capacity, no verdict under a lost zone",
+    "AWS::IAM::Policy": "a policy document is a statement about permission; nothing about it saturates or accrues",
+    "AWS::IAM::ManagedPolicy": "a policy document is a statement about permission; nothing about it saturates or accrues",
+    "AWS::IAM::InstanceProfile": "a wrapper that hands a role to an instance; the instance carries the figures",
+    "AWS::S3::BucketPolicy": "a bucket policy is a grant on the bucket beside it, and the bucket carries the figures",
+    "AWS::SQS::QueuePolicy": "a queue policy is a grant on the queue beside it, and the queue carries the figures",
+    "AWS::Lambda::Permission": "a grant letting one service invoke a function; the function carries the figures",
+    // ── Boundaries, and the wiring that puts things inside them ──────
+    "AWS::EC2::VPC": "a network boundary rather than a node: its contribution to a prediction is the zone membership that reaches the engine as containment coverage",
+    "AWS::EC2::Subnet": "a network boundary rather than a node: its contribution to a prediction is the zone membership that reaches the engine as containment coverage",
+    "AWS::EC2::SecurityGroup": "a filter on edges that already exist, not a thing at either end of one",
+    "AWS::EC2::RouteTable": "routing, which decides where an edge goes and is not itself at either end of one",
+    "AWS::EC2::Route": "routing, which decides where an edge goes and is not itself at either end of one",
+    "AWS::EC2::SubnetRouteTableAssociation": "an association between two boundaries; nothing flows through it that does not already flow through them",
+    "AWS::EC2::InternetGateway": "a boundary crossing rather than a resource: no rate of its own and no capacity to saturate",
+    "AWS::EC2::VPCGatewayAttachment": "an attachment between two boundaries, and neither end is priced by it",
+    "AWS::RDS::DBSubnetGroup": "the set of subnets a database may sit in; the database carries the figures",
+    "AWS::ECS::Cluster": "a namespace for services rather than capacity of its own; the services and their nodes carry the figures",
+    // ── Meters chant cannot read ─────────────────────────────────────
+    "AWS::Logs::LogGroup": "priced by the volume ingested into it, which the declaration does not state and no engine can infer from a graph",
+    "AWS::WAFv2::WebACL": "priced by the requests inspected through it, which the declaration does not state",
+    "AWS::EC2::NatGateway": "priced as an hourly rate plus a per-gigabyte meter on everything that crosses it. The declaration states the first and nothing at all about the second, and no engine kind here models a half-known price. A figure covering the hourly half alone would read as the cost of the gateway and be wrong by whatever the traffic did",
+    "AWS::EC2::EIP": "priced only while it is attached to nothing, which is a fact about the running account rather than about the declaration",
+    "AWS::ECR::Repository": "priced by the gigabytes stored in it, which the declaration does not state",
+    "AWS::KMS::Key": "priced per key per month plus a per-request meter the declaration does not state, and neither half is an hourly rate",
+    "AWS::Route53::HostedZone": "priced per zone per month plus a per-query meter the declaration does not state",
+    "AWS::SNS::Subscription": "priced by the notifications delivered through it; the topic is what the graph has an edge to",
+    "AWS::Events::Rule": "priced by the events matched, which is a fact about traffic the declaration does not state",
+    // ── Templates, not instances ─────────────────────────────────────
+    "AWS::ECS::TaskDefinition": "a template a service runs copies of; the service carries the figures, and pricing both would count the estate twice",
+    "AWS::Lambda::EventSourceMapping": "the wiring between a queue and a function, both of which are priced where they are declared",
+    "AWS::ElasticLoadBalancingV2::TargetGroup": "a set of targets behind a load balancer; the load balancer carries the rate",
+    "AWS::ElasticLoadBalancingV2::Listener": "a port on a load balancer; the load balancer carries the rate",
+    "AWS::ElasticLoadBalancingV2::ListenerRule": "a routing rule on a listener, and a rule is not a thing at either end of an edge",
+    // ── Not resources at all ─────────────────────────────────────────
+    "AWS::CloudFormation::Parameter": "a template input, not a thing the account holds. It shapes what is created and is never created itself",
+    "AWS::CloudFormation::Condition": "a template predicate deciding whether something is created; it is never created itself",
+    // ── Meters on a managed agent runtime ────────────────────────────
+    // Bedrock AgentCore is billed per invocation and per token consumed. Neither
+    // is in a declaration, and an hourly rate for an agent that ran twice this
+    // week would be a number with no relationship to the bill.
+    "AWS::BedrockAgentCore::Runtime": "an agent runtime billed per invocation and per token, neither of which the declaration states; there is no hour of existence to price",
+    "AWS::BedrockAgentCore::Gateway": "a front door to an agent runtime, billed by what passes through it rather than by existing",
+    "AWS::BedrockAgentCore::GatewayTarget": "one target behind a gateway; the gateway and the runtime are where the meters are",
+    "AWS::BedrockAgentCore::Memory": "agent memory billed by what is stored and retrieved, which the declaration does not state",
+    "AWS::BedrockAgentCore::WorkloadIdentity": "an identity a runtime acts as; a grant, with no rate and no capacity",
+};
+/**
+ * A CloudFormation **property** type — `AWS::S3::Bucket.VersioningConfiguration`
+ * — recognised by the dot. These are nested blocks of the resource above them
+ * that became entities of their own in the build; there are hundreds, they are
+ * never separately priced, and enumerating them one row at a time would bury
+ * this table's real decisions under boilerplate.
+ */
+function propertyType(type) {
+    return type.includes(".")
+        ? "a CloudFormation property type: a nested block of the resource above it, which became an " +
+            "entity of its own in the build. The resource carries the figures, and pricing the block as " +
+            "well would count part of the estate twice"
+        : undefined;
+}
+/** This lexicon's answer for its own types. */
+export const awsBehaviourKinds = {
+    provider: "aws",
+    prefixes: ["AWS::"],
+    mapped: MAPPED,
+    unmapped: UNMAPPED,
+    unmappedWhen: propertyType,
+};

package/dist/caller-identity.d.ts

@@ -29,11 +29,9 @@
  * while `aws sts get-caller-identity` answered with a principal. An expired
  * SSO session is `no-credentials` naming `aws sso login --profile <p>`.
  *
- * The native read transport still signs with environment keys only
- * (`resolveCredentials` in ./api/sigv4.ts; #3958). So a profile-sourced row says
- * what the CLI, and anything shelling out to it, would act as; it does not
- * yet say what `describeResources` signs with. The `source` column names the
- * profile, so the difference is visible.
+ * The native read transport walks the same chain (`transportCredentials`,
+ * #3958), so a profile-sourced row also says what `describeResources` signs
+ * with.
  *
  * Against an endpoint override the chain is not walked: the emulator call is
  * unsigned whatever resolves, and a whoami against Floci should not start an

package/dist/caller-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"caller-identity.d.ts","sourceRoot":"","sources":["../src/caller-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAA0B,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AA+B7F,2FAA2F;AAC3F,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAuEtG"}
+{"version":3,"file":"caller-identity.d.ts","sourceRoot":"","sources":["../src/caller-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAA0B,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AA+B7F,2FAA2F;AAC3F,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAuEtG"}

package/dist/caller-identity.js

@@ -0,0 +1,146 @@
+/**
+ * Who chant would act as in AWS — the lexicon half of `chant lifecycle whoami`
+ * (chant #1982).
+ *
+ * `sts:GetCallerIdentity` on the same transport every read uses, so the answer
+ * cannot describe a target the read does not reach: the endpoint override, the
+ * region and the signing decision are resolved by `read-client.ts` once, for
+ * both. That parity is the point of the command — a whoami that reports real
+ * AWS while `describeResources` reads Floci is worse than none — and a test
+ * pins it.
+ *
+ * ## What the region actually is
+ *
+ * The native read transport takes its region from the stack being observed
+ * (`stacks[].region`, #1261) and falls back to `us-east-1` inside `serviceUrl`.
+ * It does NOT read `AWS_REGION`. So that is what is reported, including the
+ * awkward case: an operator whose shell exports `AWS_REGION=eu-west-1` and
+ * whose project declares no stack region is reading us-east-1, and has had no
+ * way to find that out short of a wrong answer. `source` names it.
+ *
+ * ## Credentials
+ *
+ * Resolved the way the AWS CLI resolves them (#3954), by
+ * `./api/credential-chain.ts`: environment keys, then the profile
+ * `AWS_PROFILE` names (or `default`) from the shared config and credentials
+ * files, through static keys, `role_arn`, SSO sessions and
+ * `credential_process`. Before #3954 only the environment keys were read, so
+ * `AWS_PROFILE=dev` on an SSO session answered "no identity is configured"
+ * while `aws sts get-caller-identity` answered with a principal. An expired
+ * SSO session is `no-credentials` naming `aws sso login --profile <p>`.
+ *
+ * The native read transport walks the same chain (`transportCredentials`,
+ * #3958), so a profile-sourced row also says what `describeResources` signs
+ * with.
+ *
+ * Against an endpoint override the chain is not walked: the emulator call is
+ * unsigned whatever resolves, and a whoami against Floci should not start an
+ * SSO refresh or a `credential_process`.
+ *
+ * No credential value is ever returned. The identity is the principal ARN the
+ * service itself answers with, and the scope is an account and a region.
+ */
+import { AwsReadError, getCallerIdentity, resolveEndpointOverride, serviceUrl, } from "./api/read-client.js";
+import { resolveCredentialChain } from "./api/credential-chain.js";
+/** The region the read transport falls back to when no stack declares one. */
+const DEFAULT_REGION = "us-east-1";
+/** True when the failure says the call was refused rather than broken. */
+function isAuthFailure(err) {
+    if (err.status === 401 || err.status === 403)
+        return true;
+    return /credential|token|expired|AccessDenied|not authorized|Unauthorized|InvalidClientTokenId|SignatureDoesNotMatch/i.test(`${err.code ?? ""} ${err.message}`);
+}
+/** Where the region came from, said plainly enough to act on. */
+function regionSource(declared, env) {
+    if (declared)
+        return `stacks[].region`;
+    const ambient = env.AWS_REGION ?? env.AWS_DEFAULT_REGION;
+    if (ambient && ambient !== DEFAULT_REGION) {
+        return `chant default (no stacks[].region; AWS_REGION=${ambient} is not read by this transport)`;
+    }
+    return "chant default (no stacks[].region)";
+}
+/** The environment-key label, used against an endpoint override where the chain is not walked. */
+function envCredentialLabel(env) {
+    if (!env.AWS_ACCESS_KEY_ID || !env.AWS_SECRET_ACCESS_KEY)
+        return undefined;
+    return env.AWS_SESSION_TOKEN
+        ? "env AWS_ACCESS_KEY_ID + AWS_SESSION_TOKEN"
+        : "env AWS_ACCESS_KEY_ID";
+}
+/**
+ * The AWS `describeIdentity`. Returns the STS principal and the account+region
+ * scope, or a typed refusal — never a guessed identity and never an empty one.
+ */
+export async function describeIdentity(options) {
+    const client = {
+        ...options.client,
+        ...(options.region ? { region: options.region } : {}),
+    };
+    const env = client.env ?? process.env;
+    const override = resolveEndpointOverride("sts", client.endpoint, env);
+    // The region the transport resolves, not the one an operator might assume:
+    // `serviceUrl` defaults it, so this is the host the read is actually sent to.
+    const region = client.region ?? DEFAULT_REGION;
+    const endpoint = serviceUrl("sts", override, client.region);
+    // Against an emulator the call is unsigned by design (Floci verifies no
+    // signature), so an absent credential is not yet a refusal — the emulator
+    // answers with the identity it models — and the chain is not walked.
+    let credential;
+    if (override) {
+        credential = envCredentialLabel(env);
+    }
+    else if (client.credentials) {
+        credential = "credentials injected by the caller";
+    }
+    else {
+        const chain = await resolveCredentialChain({
+            env,
+            ...options.chain,
+            sts: { ...(client.http ? { http: client.http } : {}), ...options.chain?.sts, env },
+        });
+        if ("unresolved" in chain)
+            return { unresolved: chain.unresolved };
+        credential = chain.resolved.source;
+        client.credentials = chain.resolved.credentials;
+    }
+    let identity;
+    try {
+        identity = await getCallerIdentity(client);
+    }
+    catch (err) {
+        if (err instanceof AwsReadError) {
+            return {
+                unresolved: {
+                    reason: isAuthFailure(err) ? "no-credentials" : "read-failed",
+                    detail: `sts:GetCallerIdentity against ${endpoint} failed: ${err.code ? `${err.code}: ` : ""}${err.message}`,
+                },
+            };
+        }
+        return {
+            unresolved: {
+                reason: "read-failed",
+                detail: `sts:GetCallerIdentity against ${endpoint} failed: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    if (!identity.arn) {
+        return {
+            unresolved: {
+                reason: "read-failed",
+                detail: `sts:GetCallerIdentity against ${endpoint} answered without an Arn`,
+            },
+        };
+    }
+    const sources = [
+        credential ?? "unsigned (endpoint override)",
+        regionSource(client.region, env),
+        ...(override ? [`endpoint override ${override}`] : []),
+    ];
+    return {
+        identity: identity.arn,
+        scope: identity.account ? `${identity.account} ${region}` : region,
+        source: sources.join("; "),
+        endpoint,
+    };
+}

package/dist/codegen/docs-cli.js

@@ -0,0 +1,2 @@
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });

package/dist/codegen/docs.js

@@ -0,0 +1,120 @@
+/**
+ * AWS CloudFormation documentation generator.
+ *
+ * Calls the core docsPipeline with AWS-specific config:
+ * service grouping, resource type URLs, and overview content.
+ *
+ * writeDocsSite puts the pages in the main docs site under
+ * docs/src/content/docs/lexicons/aws/ (chant #3993).
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+const __dirname_ = dirname(fileURLToPath(import.meta.url));
+const pkgDir = join(__dirname_, "..", "..");
+/**
+ * Extract the AWS service name from a CloudFormation resource type.
+ * e.g. "AWS::S3::Bucket" → "S3", "AWS::Lambda::Function" → "Lambda"
+ */
+function serviceFromType(resourceType) {
+    const parts = resourceType.split("::");
+    return parts.length >= 2 ? parts[1] : "Other";
+}
+const overview = `The **AWS CloudFormation** lexicon provides full support for defining AWS infrastructure using chant's declarative TypeScript syntax. Resources are serialized to CloudFormation JSON templates.
+
+This lexicon is generated from the official [CloudFormation Resource Provider Schemas](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-resource-specification.html) and includes coverage for all publicly available resource types.
+
+Install it with:
+
+\`\`\`bash
+npm install --save-dev @intentius/chant-lexicon-aws
+\`\`\``;
+const outputFormat = `The AWS lexicon serializes resources into **CloudFormation JSON templates**.
+
+## Building
+
+Run \`chant build\` to produce a CloudFormation template from your declarations:
+
+\`\`\`bash
+chant build
+# Writes dist/template.json
+\`\`\`
+
+The generated template includes:
+
+- \`AWSTemplateFormatVersion\` header
+- \`Parameters\` section (if any parameters are declared)
+- \`Resources\` section with typed resource definitions
+- \`Outputs\` section for exported values
+- Full support for intrinsic functions (\`Fn::Sub\`, \`Ref\`, \`Fn::GetAtt\`, etc.)
+
+## Deploying
+
+The output is standard CloudFormation JSON. Deploy with any CF-compatible tool:
+
+\`\`\`bash
+# AWS CLI
+aws cloudformation deploy \\
+  --template-file dist/template.json \\
+  --stack-name my-stack \\
+  --capabilities CAPABILITY_IAM
+
+# Rain (faster, with diff preview)
+rain deploy dist/template.json my-stack
+
+# SAM CLI (if using serverless transforms)
+sam deploy --template-file dist/template.json --stack-name my-stack
+\`\`\`
+
+## Compatibility
+
+The output is compatible with:
+- AWS CloudFormation service (direct deployment)
+- AWS SAM CLI
+- AWS CDK (as an escape hatch via \`CfnInclude\`)
+- Rain and other CloudFormation tooling
+- Any tool that accepts CloudFormation JSON templates`;
+/**
+ * Generate the AWS lexicon's documentation pages.
+ */
+export async function generateDocs(options) {
+    const log = options?.verbose
+        ? (msg) => console.error(msg)
+        : (_msg) => { };
+    const distDir = join(pkgDir, "dist");
+    const srcDir = join(pkgDir, "src");
+    const outDir = join(pkgDir, "docs");
+    const config = {
+        name: "aws",
+        basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/aws/",
+        displayName: "AWS CloudFormation",
+        description: "AWS CloudFormation lexicon for chant — resource types, intrinsics, and lint rules",
+        distDir,
+        outDir,
+        srcDir,
+        overview,
+        outputFormat,
+        serviceFromType,
+        // "intrinsics" is no longer suppressed (chant #1067) — the reference
+        // table at that slug is now generated from the plugin's own
+        // `intrinsics()` registration (docsPipeline's generateIntrinsics, same
+        // mechanism azure/helm already use), so its "Folds?" column can never
+        // drift from the registration the way #1062's foldability matrix
+        // depends on. The hand-written usage guide with full worked examples
+        // moves to a separate "intrinsics-guide" page in docs/pages/ — content
+        // unchanged, just no longer sharing a slug with generated data.
+        // `rules` is NOT suppressed: the hand-written `lint-rules` page in docs/pages/
+        // explains 26 of the lexicon's 50 rules in depth, and the whole WAW032+
+        // hardening pass had no entry there at all (#1312). The generated table is
+        // the complete, always-current list, so both ship: a hand-written overview
+        // beside a generated reference. Duplicating 24 descriptions into the prose
+        // page would just create a third copy to drift.
+        suppressPages: ["pseudo-parameters"],
+        examplesDir: join(pkgDir, "examples"),
+    };
+    log("Generating AWS documentation...");
+    const result = docsPipeline(config);
+    log(`Writing docs pages for ${outDir}`);
+    writeDocsSite(config, result);
+    console.error(`Docs generated: ${result.stats.resources} resources, ${result.stats.services} services, ${result.stats.rules} rules`);
+}

package/dist/codegen/enum-overlay.js

@@ -0,0 +1,162 @@
+/**
+ * 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" };
+/** The curated entries, in file order. */
+export function enumOverlayEntries() {
+    return overlayDocument.entries;
+}
+/** Entries grouped by CloudFormation type name. */
+export function enumOverlayByType(entries = enumOverlayEntries()) {
+    const byType = new Map();
+    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) {
+    if (!pointer.startsWith("/")) {
+        throw new Error(`enum overlay pointer must start with "/": ${pointer}`);
+    }
+    return pointer.split("/").slice(1);
+}
+function resolvePointer(doc, pointer) {
+    let node = doc;
+    for (const segment of pointerSegments(pointer)) {
+        if (typeof node !== "object" || node === null || Array.isArray(node))
+            return undefined;
+        node = node[segment];
+        if (node === undefined)
+            return undefined;
+    }
+    if (typeof node !== "object" || node === null || Array.isArray(node))
+        return undefined;
+    return node;
+}
+/**
+ * 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, data, entries, opts = {}) {
+    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);
+    const applications = [];
+    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,
+            });
+            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 ?? (doc.definitions = {}));
+        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, seenTypes, strict) {
+    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) {
+    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.`,
+    }));
+}