feat(aws): export the MicroVM service limits MicrovmApp enforces

lexicons/aws/src/composites/index.ts

@@ -32,7 +32,7 @@ export { Ec2InstanceRole } from "./ec2-instance-role";
 export type { Ec2InstanceRoleProps } from "./ec2-instance-role";
 export { MinimalVpc } from "./minimal-vpc";
 export type { MinimalVpcProps } from "./minimal-vpc";
-export { MicrovmApp } from "./microvm-app";
-export type { MicrovmAppProps, MicrovmAppResult, MicrovmAppBuildConnectorProps } from "./microvm-app";
+export { MicrovmApp, MICROVM_LIMITS } from "./microvm-app";
+export type { MicrovmAppProps, MicrovmAppResult, MicrovmAppBuildConnectorProps, MicrovmMemoryMiB } from "./microvm-app";
 export { AgentCoreAgent } from "./agentcore-agent";
 export type { AgentCoreAgentProps, AgentCoreAgentResult } from "./agentcore-agent";

lexicons/aws/src/composites/microvm-app.test.ts

@@ -3,7 +3,7 @@ import { expandComposite } from "@intentius/chant";
 import { AttrRef } from "@intentius/chant/attrref";
 import { resolveAttrRefs } from "@intentius/chant/discovery/resolve";
 import { awsSerializer } from "../serializer";
-import { MicrovmApp } from "./microvm-app";
+import { MicrovmApp, MICROVM_LIMITS } from "./microvm-app";
 
 const baseProps = {
   name: "worker-image",
@@ -232,3 +232,41 @@ describe("MicrovmApp", () => {
     });
   });
 });
+
+describe("MICROVM_LIMITS", () => {
+  // The composite validates against these; a consumer driving the same service
+  // through a different control plane needs the same numbers, and copying them
+  // is how two sources of truth start (#1374).
+  test("is reachable from the package root", async () => {
+    const root = await import("../index");
+    expect(root.MICROVM_LIMITS).toBe(MICROVM_LIMITS);
+  });
+
+  test("is what the composite actually enforces", () => {
+    // Not a restatement of the constants — a probe through the public API, so
+    // the two cannot drift apart while both look right.
+    expect(() => MicrovmApp({ ...baseProps, memoryMiB: 3072 as never })).toThrow(
+      new RegExp(MICROVM_LIMITS.memoryMiB.join(", ")),
+    );
+    expect(() => MicrovmApp({ ...baseProps, name: "no spaces allowed" })).toThrow(/name must match/);
+    expect(() =>
+      MicrovmApp({ ...baseProps, name: "x".repeat(MICROVM_LIMITS.maxNameLength + 1) }),
+    ).toThrow(/≤64 chars/);
+    expect(() =>
+      MicrovmApp({ ...baseProps, environment: { AWS_REGION: "us-east-1" } }),
+    ).toThrow(/AWS_REGION/);
+  });
+
+  test("names every limit the composite checks", () => {
+    // A limit enforced and not named here is one a consumer cannot see.
+    expect(Object.keys(MICROVM_LIMITS).sort()).toEqual([
+      "connectorSubnets",
+      "maxEgressConnectors",
+      "maxEnvironmentVariables",
+      "maxNameLength",
+      "memoryMiB",
+      "namePattern",
+      "reservedEnvironmentKeys",
+    ]);
+  });
+});

lexicons/aws/src/composites/microvm-app.ts

@@ -47,17 +47,38 @@ import { Sub } from "../intrinsics";
 const MICROVM_SERVICE_PRINCIPAL = "lambda.amazonaws.com";
 const CONNECTOR_MANAGED_RESOURCE_OPERATOR = "network-connectors.lambda.amazonaws.com";
 
-/** Documented baseline memory tiers (MiB) — the CFN schema types it as an open int, but the service accepts only these five; vCPU auto-scales with the tier. */
-const VALID_MEMORY_MIB = [512, 1024, 2048, 4096, 8192] as const;
-type MicrovmMemoryMiB = (typeof VALID_MEMORY_MIB)[number];
-
-const NAME_PATTERN = /^[a-zA-Z0-9-_]+$/;
-const MAX_NAME_LENGTH = 64;
-const RESERVED_ENV_KEYS = new Set(["AWS_REGION"]);
-const MAX_ENVIRONMENT_VARIABLES = 50;
-const MAX_EGRESS_CONNECTORS = 10;
-const MIN_CONNECTOR_SUBNETS = 1;
-const MAX_CONNECTOR_SUBNETS = 16;
+/**
+ * The Lambda MicroVMs service's real limits, verified against the upstream
+ * `ran-isenberg/lambda-microvm-cdk-python` construct and the AWS docs.
+ *
+ * Exported because a consumer driving the same service through a different
+ * control plane needs the same numbers, and copying them is how two sources of
+ * truth start (#1374). The CFN schema types most of these as open ints and
+ * strings, so nothing but this object knows them.
+ */
+export const MICROVM_LIMITS = {
+  /** Documented baseline memory tiers (MiB). The schema says int; the service accepts five values. vCPU auto-scales with the tier. */
+  memoryMiB: [512, 1024, 2048, 4096, 8192],
+  namePattern: /^[a-zA-Z0-9-_]+$/,
+  maxNameLength: 64,
+  /** Set by the service on every MicroVM; supplying it is rejected. */
+  reservedEnvironmentKeys: ["AWS_REGION"],
+  maxEnvironmentVariables: 50,
+  maxEgressConnectors: 10,
+  connectorSubnets: { min: 1, max: 16 },
+} as const;
+
+/** One of the five memory tiers {@link MICROVM_LIMITS} names. */
+export type MicrovmMemoryMiB = (typeof MICROVM_LIMITS.memoryMiB)[number];
+
+const VALID_MEMORY_MIB = MICROVM_LIMITS.memoryMiB;
+const NAME_PATTERN = MICROVM_LIMITS.namePattern;
+const MAX_NAME_LENGTH = MICROVM_LIMITS.maxNameLength;
+const RESERVED_ENV_KEYS = new Set<string>(MICROVM_LIMITS.reservedEnvironmentKeys);
+const MAX_ENVIRONMENT_VARIABLES = MICROVM_LIMITS.maxEnvironmentVariables;
+const MAX_EGRESS_CONNECTORS = MICROVM_LIMITS.maxEgressConnectors;
+const MIN_CONNECTOR_SUBNETS = MICROVM_LIMITS.connectorSubnets.min;
+const MAX_CONNECTOR_SUBNETS = MICROVM_LIMITS.connectorSubnets.max;
 
 /**
  * `sts:AssumeRole` + `sts:TagSession` trust for `lambda.amazonaws.com` — the

lexicons/aws/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";