@intentius/chant-lexicon-aws 0.18.11 → 0.18.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.18.11",
+  "version": "0.18.13",
   "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -80,6 +80,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.18.11"
+    "@intentius/chant": "^0.18.13",
+    "typescript": "^5.9.3"
   }
 }

package/src/composites/agentcore-agent.test.ts

@@ -0,0 +1,188 @@
+import { describe, test, expect } from "vitest";
+import { expandComposite } from "@intentius/chant";
+import { AttrRef } from "@intentius/chant/attrref";
+// resolveAttrRefs stamps logical names onto AttrRefs before serialization —
+// normally the discover→resolve→serialize pipeline (`chant build`) does this;
+// reaching into core directly here mirrors nested-stack-integration.test.ts's
+// precedent for aws-lexicon integration-style tests.
+import { resolveAttrRefs } from "../../../../packages/core/src/discovery/resolve";
+import { AgentCoreAgent } from "./agentcore-agent";
+import { awsSerializer } from "../serializer";
+
+const baseProps = {
+  name: "support-agent",
+  containerUri: "123456789012.dkr.ecr.us-east-1.amazonaws.com/support-agent:latest",
+};
+
+describe("AgentCoreAgent", () => {
+  test("returns all 8 members", () => {
+    const instance = AgentCoreAgent(baseProps);
+    expect(Object.keys(instance.members)).toEqual([
+      "role", "gatewayRole", "runtime", "endpoint", "memory",
+      "workloadIdentity", "gateway", "gatewayTarget",
+    ]);
+  });
+
+  test("expandComposite produces correct logical names", () => {
+    const expanded = expandComposite("agent", AgentCoreAgent(baseProps));
+    expect(expanded.has("agentRole")).toBe(true);
+    expect(expanded.has("agentGatewayRole")).toBe(true);
+    expect(expanded.has("agentRuntime")).toBe(true);
+    expect(expanded.has("agentEndpoint")).toBe(true);
+    expect(expanded.has("agentMemory")).toBe(true);
+    expect(expanded.has("agentWorkloadIdentity")).toBe(true);
+    expect(expanded.has("agentGateway")).toBe(true);
+    expect(expanded.has("agentGatewayTarget")).toBe(true);
+    expect(expanded.size).toBe(8);
+  });
+
+  test("role and gatewayRole trust bedrock-agentcore.amazonaws.com", () => {
+    const instance = AgentCoreAgent(baseProps);
+    const roleProps = (instance.role as any).props;
+    const gatewayRoleProps = (instance.gatewayRole as any).props;
+    expect(roleProps.AssumeRolePolicyDocument.Statement[0].Principal.Service).toBe(
+      "bedrock-agentcore.amazonaws.com",
+    );
+    expect(gatewayRoleProps.AssumeRolePolicyDocument.Statement[0].Principal.Service).toBe(
+      "bedrock-agentcore.amazonaws.com",
+    );
+  });
+
+  test("kebab-case name is sanitized for Runtime/RuntimeEndpoint/Memory (no hyphens)", () => {
+    const instance = AgentCoreAgent(baseProps);
+    const runtimeProps = (instance.runtime as any).props;
+    const endpointProps = (instance.endpoint as any).props;
+    const memoryProps = (instance.memory as any).props;
+    expect(runtimeProps.AgentRuntimeName).toBe("support_agent");
+    expect(runtimeProps.AgentRuntimeName).toMatch(/^[a-zA-Z][a-zA-Z0-9_]{0,47}$/);
+    expect(endpointProps.Name).toBe("DEFAULT");
+    expect(memoryProps.Name).toBe("support_agentMemory");
+    expect(memoryProps.Name).toMatch(/^[a-zA-Z][a-zA-Z0-9_]{0,47}$/);
+  });
+
+  test("Gateway/GatewayTarget/WorkloadIdentity keep the raw kebab-case name (hyphens allowed)", () => {
+    const instance = AgentCoreAgent(baseProps);
+    const gatewayProps = (instance.gateway as any).props;
+    const targetProps = (instance.gatewayTarget as any).props;
+    const identityProps = (instance.workloadIdentity as any).props;
+    expect(gatewayProps.Name).toBe("support-agent-gateway");
+    expect(targetProps.Name).toBe("support-agent-target");
+    expect(identityProps.Name).toBe("support-agent-identity");
+  });
+
+  test("Runtime wires RoleArn, ContainerUri, and defaults to MCP/PUBLIC", () => {
+    const instance = AgentCoreAgent(baseProps);
+    const runtimeProps = (instance.runtime as any).props;
+    expect(runtimeProps.RoleArn).toBeInstanceOf(AttrRef);
+    expect(runtimeProps.ProtocolConfiguration).toBe("MCP");
+    const artifactProps = (runtimeProps.AgentRuntimeArtifact as any).props;
+    const containerProps = (artifactProps.ContainerConfiguration as any).props;
+    expect(containerProps.ContainerUri).toBe(baseProps.containerUri);
+    const networkProps = (runtimeProps.NetworkConfiguration as any).props;
+    expect(networkProps.NetworkMode).toBe("PUBLIC");
+    expect(networkProps.NetworkModeConfig).toBeUndefined();
+  });
+
+  test("VPC network mode wires NetworkModeConfig from vpcSubnetIds/vpcSecurityGroupIds", () => {
+    const instance = AgentCoreAgent({
+      ...baseProps,
+      networkMode: "VPC",
+      vpcSubnetIds: ["subnet-1", "subnet-2"],
+      vpcSecurityGroupIds: ["sg-1"],
+    });
+    const runtimeProps = (instance.runtime as any).props;
+    const networkProps = (runtimeProps.NetworkConfiguration as any).props;
+    expect(networkProps.NetworkMode).toBe("VPC");
+    const vpcConfigProps = (networkProps.NetworkModeConfig as any).props;
+    expect(vpcConfigProps.Subnets).toEqual(["subnet-1", "subnet-2"]);
+    expect(vpcConfigProps.SecurityGroups).toEqual(["sg-1"]);
+  });
+
+  test("throws when networkMode is VPC without subnets/security groups", () => {
+    expect(() => AgentCoreAgent({ ...baseProps, networkMode: "VPC" })).toThrow(
+      "AgentCoreAgent requires vpcSubnetIds and vpcSecurityGroupIds when networkMode is \"VPC\"",
+    );
+  });
+
+  test("throws when memoryEventExpiryDays is out of CFN bounds (3-365)", () => {
+    expect(() => AgentCoreAgent({ ...baseProps, memoryEventExpiryDays: 1 })).toThrow(
+      "AgentCoreAgent memoryEventExpiryDays must be between 3 and 365",
+    );
+    expect(() => AgentCoreAgent({ ...baseProps, memoryEventExpiryDays: 400 })).toThrow(
+      "AgentCoreAgent memoryEventExpiryDays must be between 3 and 365",
+    );
+  });
+
+  test("RuntimeEndpoint references runtime.AgentRuntimeId", () => {
+    const instance = AgentCoreAgent(baseProps);
+    const endpointProps = (instance.endpoint as any).props;
+    expect(endpointProps.AgentRuntimeId).toBeInstanceOf(AttrRef);
+  });
+
+  test("Memory defaults EventExpiryDuration and MemoryExecutionRoleArn", () => {
+    const instance = AgentCoreAgent(baseProps);
+    const memoryProps = (instance.memory as any).props;
+    expect(memoryProps.EventExpiryDuration).toBe(30);
+    expect(memoryProps.MemoryExecutionRoleArn).toBeInstanceOf(AttrRef);
+  });
+
+  test("GatewayTarget defaults to routing back at the agent's own Runtime", () => {
+    const instance = AgentCoreAgent(baseProps);
+    const targetProps = (instance.gatewayTarget as any).props;
+    expect(targetProps.GatewayIdentifier).toBeInstanceOf(AttrRef);
+    const runtimeArnRef = targetProps.TargetConfiguration.Http.AgentcoreRuntime.Arn;
+    expect(runtimeArnRef).toBeInstanceOf(AttrRef);
+  });
+
+  test("Gateway defaults to AWS_IAM authorizer, override is respected", () => {
+    const instance = AgentCoreAgent(baseProps);
+    const gatewayProps = (instance.gateway as any).props;
+    expect(gatewayProps.AuthorizerType).toBe("AWS_IAM");
+
+    const custom = AgentCoreAgent({ ...baseProps, gatewayAuthorizerType: "NONE" });
+    const customGatewayProps = (custom.gateway as any).props;
+    expect(customGatewayProps.AuthorizerType).toBe("NONE");
+  });
+
+  test("ManagedPolicyArns and Policies pass through to the runtime role", () => {
+    const arn = "arn:aws:iam::aws:policy/AmazonBedrockFullAccess";
+    const instance = AgentCoreAgent({ ...baseProps, ManagedPolicyArns: [arn] });
+    const roleProps = (instance.role as any).props;
+    expect(roleProps.ManagedPolicyArns).toContain(arn);
+  });
+
+  test("per-member defaults are applied (e.g. custom endpoint description)", () => {
+    const instance = AgentCoreAgent({
+      ...baseProps,
+      defaults: { endpoint: { Description: "prod alias" } },
+    });
+    const endpointProps = (instance.endpoint as any).props;
+    expect(endpointProps.Description).toBe("prod alias");
+  });
+
+  test("serializes to a valid CloudFormation template with the expected resource types", () => {
+    const expanded = expandComposite("agent", AgentCoreAgent(baseProps));
+    resolveAttrRefs(expanded);
+    const output = awsSerializer.serialize(expanded);
+    const template = JSON.parse(output);
+
+    expect(template.AWSTemplateFormatVersion).toBe("2010-09-09");
+    expect(template.Resources.agentRole.Type).toBe("AWS::IAM::Role");
+    expect(template.Resources.agentGatewayRole.Type).toBe("AWS::IAM::Role");
+    expect(template.Resources.agentRuntime.Type).toBe("AWS::BedrockAgentCore::Runtime");
+    expect(template.Resources.agentEndpoint.Type).toBe("AWS::BedrockAgentCore::RuntimeEndpoint");
+    expect(template.Resources.agentMemory.Type).toBe("AWS::BedrockAgentCore::Memory");
+    expect(template.Resources.agentWorkloadIdentity.Type).toBe("AWS::BedrockAgentCore::WorkloadIdentity");
+    expect(template.Resources.agentGateway.Type).toBe("AWS::BedrockAgentCore::Gateway");
+    expect(template.Resources.agentGatewayTarget.Type).toBe("AWS::BedrockAgentCore::GatewayTarget");
+
+    // Cross-references resolved to CFN intrinsics, not left as live objects.
+    expect(template.Resources.agentRuntime.Properties.RoleArn).toEqual({ "Fn::GetAtt": ["agentRole", "Arn"] });
+    expect(template.Resources.agentEndpoint.Properties.AgentRuntimeId).toEqual({
+      "Fn::GetAtt": ["agentRuntime", "AgentRuntimeId"],
+    });
+    expect(template.Resources.agentGatewayTarget.Properties.TargetConfiguration).toEqual({
+      Http: { AgentcoreRuntime: { Arn: { "Fn::GetAtt": ["agentRuntime", "AgentRuntimeArn"] } } },
+    });
+  });
+});

package/src/composites/agentcore-agent.ts

@@ -0,0 +1,195 @@
+import { Composite, mergeDefaults } from "@intentius/chant";
+import {
+  Role,
+  Role_Policy,
+  Runtime,
+  Runtime_AgentRuntimeArtifact,
+  Runtime_ContainerConfiguration,
+  Runtime_NetworkConfiguration,
+  Runtime_VpcConfig,
+  RuntimeEndpoint,
+  Memory,
+  BedrockAgentCoreGateway,
+  GatewayTarget,
+  WorkloadIdentity,
+} from "../generated";
+import { agentCoreTrustPolicy } from "./agentcore-trust-policy";
+
+/**
+ * AgentCore's `Runtime`/`RuntimeEndpoint`/`Memory` `Name`/`AgentRuntimeName`
+ * fields are all bound to the CFN registry pattern
+ * `^[a-zA-Z][a-zA-Z0-9_]{0,47}$` (spot-checked against the CloudFormation
+ * schema for #882 — no hyphens, unlike chant's usual kebab-case component
+ * names). `Gateway`/`GatewayTarget`/`WorkloadIdentity` names accept hyphens,
+ * so only the Runtime family needs sanitizing. Non-identifier characters
+ * become `_`, and a leading digit/underscore gets an `A` prefix so the result
+ * always starts with a letter.
+ */
+function toRuntimeIdentifier(name: string): string {
+  const cleaned = name.replace(/[^a-zA-Z0-9_]/g, "_");
+  const identifier = /^[a-zA-Z]/.test(cleaned) ? cleaned : `A${cleaned}`;
+  return identifier.slice(0, 48);
+}
+
+export interface AgentCoreAgentProps {
+  /**
+   * Base name for the agent's resources. `toRuntimeIdentifier(name)` derives
+   * the Runtime/RuntimeEndpoint/Memory names; Gateway/GatewayTarget/
+   * WorkloadIdentity use `name` as-is (hyphens are valid there).
+   */
+  name: string;
+  /** ECR image URI the Runtime runs, e.g. `"123456789012.dkr.ecr.us-east-1.amazonaws.com/agent:latest"`. */
+  containerUri: string;
+  /** Runtime network mode. Default: "PUBLIC". */
+  networkMode?: "PUBLIC" | "VPC";
+  /** Subnets for the Runtime's ENIs. Required when `networkMode` is "VPC". */
+  vpcSubnetIds?: string[];
+  /** Security groups for the Runtime's ENIs. Required when `networkMode` is "VPC". */
+  vpcSecurityGroupIds?: string[];
+  /** Protocol the Runtime serves. Mirrors the generated `Runtime_ProtocolConfiguration` CFN enum. Default: "MCP". */
+  protocolConfiguration?: "A2A" | "AGUI" | "HTTP" | "MCP";
+  /** Environment variables passed to the Runtime container. */
+  environmentVariables?: Record<string, string>;
+  /** RuntimeEndpoint name — the alias a version-promotion capability would repoint (deferred, see #882). Default: "DEFAULT". */
+  endpointName?: string;
+  /** Memory event retention, in days. CFN bounds: 3-365. Default: 30. */
+  memoryEventExpiryDays?: number;
+  /** Gateway authorizer. Mirrors the generated `BedrockAgentCoreGateway_AuthorizerType` CFN enum. Default: "AWS_IAM". */
+  gatewayAuthorizerType?: "CUSTOM_JWT" | "AWS_IAM" | "NONE" | "AUTHENTICATE_ONLY";
+  /** Allow-listed OAuth2 return URLs for the standalone `WorkloadIdentity` resource. */
+  allowedResourceOauth2ReturnUrls?: string[];
+  /** Extra managed policy ARNs merged onto the auto-created Runtime/Memory execution role. */
+  ManagedPolicyArns?: string[];
+  /** Inline policies attached to the auto-created Runtime/Memory execution role. */
+  Policies?: InstanceType<typeof Role_Policy>[];
+  defaults?: {
+    role?: Partial<ConstructorParameters<typeof Role>[0]>;
+    gatewayRole?: Partial<ConstructorParameters<typeof Role>[0]>;
+    runtime?: Partial<ConstructorParameters<typeof Runtime>[0]>;
+    endpoint?: Partial<ConstructorParameters<typeof RuntimeEndpoint>[0]>;
+    memory?: Partial<ConstructorParameters<typeof Memory>[0]>;
+    gateway?: Partial<ConstructorParameters<typeof BedrockAgentCoreGateway>[0]>;
+    gatewayTarget?: Partial<ConstructorParameters<typeof GatewayTarget>[0]>;
+    workloadIdentity?: Partial<ConstructorParameters<typeof WorkloadIdentity>[0]>;
+  };
+}
+
+export type AgentCoreAgentResult = {
+  role: InstanceType<typeof Role>;
+  gatewayRole: InstanceType<typeof Role>;
+  runtime: InstanceType<typeof Runtime>;
+  endpoint: InstanceType<typeof RuntimeEndpoint>;
+  memory: InstanceType<typeof Memory>;
+  workloadIdentity: InstanceType<typeof WorkloadIdentity>;
+  gateway: InstanceType<typeof BedrockAgentCoreGateway>;
+  gatewayTarget: InstanceType<typeof GatewayTarget>;
+};
+
+/**
+ * A Bedrock AgentCore agent as one CloudFormation-serializable bundle — the
+ * composite/base path from #882: `Runtime` + `RuntimeEndpoint` + `Memory` +
+ * `Gateway`/`GatewayTarget` + `WorkloadIdentity` + IAM, deployable with
+ * `cfn-deploy` + `wait-for-stack` and no bespoke verb.
+ *
+ * `WorkloadIdentityDetails` on both `Runtime` and `BedrockAgentCoreGateway`
+ * is CFN `readOnly` — AWS provisions a workload identity per resource
+ * automatically, and neither accepts one as an input. The `WorkloadIdentity`
+ * resource this composite creates is therefore standalone (not cross-wired
+ * to `runtime`/`gateway`), included because #882 calls for it — it exists
+ * for workflows (e.g. a future credential-provider capability) that need an
+ * explicit workload identity of their own.
+ *
+ * The `agentcore-deploy` version-promotion capability that would repoint
+ * `endpoint`'s `TargetVersion`/`LiveVersion` is deferred (GA-gated, #882) —
+ * this composite only wires the CloudFormation shape it would eventually
+ * apply against.
+ */
+export const AgentCoreAgent = Composite<AgentCoreAgentProps, AgentCoreAgentResult>((props) => {
+  const { defaults } = props;
+  const networkMode = props.networkMode ?? "PUBLIC";
+  if (networkMode === "VPC" && (!props.vpcSubnetIds?.length || !props.vpcSecurityGroupIds?.length)) {
+    throw new Error("AgentCoreAgent requires vpcSubnetIds and vpcSecurityGroupIds when networkMode is \"VPC\"");
+  }
+  const memoryEventExpiryDays = props.memoryEventExpiryDays ?? 30;
+  if (memoryEventExpiryDays < 3 || memoryEventExpiryDays > 365) {
+    throw new Error("AgentCoreAgent memoryEventExpiryDays must be between 3 and 365");
+  }
+
+  const runtimeName = toRuntimeIdentifier(props.name);
+
+  // Runtime + Memory share one execution role — both are AgentCore-hosted
+  // and assume the same service principal (see agentcore-trust-policy.ts).
+  const role = new Role(mergeDefaults({
+    AssumeRolePolicyDocument: agentCoreTrustPolicy,
+    ManagedPolicyArns: props.ManagedPolicyArns,
+    Policies: props.Policies,
+  }, defaults?.role));
+
+  // Gateway assumes its own role to invoke targets (e.g. this agent's own
+  // Runtime endpoint) — kept separate from the Runtime/Memory role so its
+  // permissions don't have to grow with the agent's own execution needs.
+  const gatewayRole = new Role(mergeDefaults({
+    AssumeRolePolicyDocument: agentCoreTrustPolicy,
+  }, defaults?.gatewayRole));
+
+  const networkConfiguration = new Runtime_NetworkConfiguration({
+    NetworkMode: networkMode,
+    NetworkModeConfig: networkMode === "VPC"
+      ? new Runtime_VpcConfig({
+        SecurityGroups: props.vpcSecurityGroupIds,
+        Subnets: props.vpcSubnetIds,
+      })
+      : undefined,
+  });
+
+  const runtime = new Runtime(mergeDefaults({
+    AgentRuntimeName: runtimeName,
+    AgentRuntimeArtifact: new Runtime_AgentRuntimeArtifact({
+      ContainerConfiguration: new Runtime_ContainerConfiguration({
+        ContainerUri: props.containerUri,
+      }),
+    }),
+    RoleArn: role.Arn,
+    NetworkConfiguration: networkConfiguration,
+    ProtocolConfiguration: props.protocolConfiguration ?? "MCP",
+    EnvironmentVariables: props.environmentVariables,
+  }, defaults?.runtime));
+
+  const endpoint = new RuntimeEndpoint(mergeDefaults({
+    AgentRuntimeId: runtime.AgentRuntimeId,
+    Name: toRuntimeIdentifier(props.endpointName ?? "DEFAULT"),
+  }, defaults?.endpoint));
+
+  const memory = new Memory(mergeDefaults({
+    Name: `${runtimeName}Memory`.slice(0, 48),
+    EventExpiryDuration: memoryEventExpiryDays,
+    MemoryExecutionRoleArn: role.Arn,
+  }, defaults?.memory));
+
+  const workloadIdentity = new WorkloadIdentity(mergeDefaults({
+    Name: `${props.name}-identity`,
+    AllowedResourceOauth2ReturnUrls: props.allowedResourceOauth2ReturnUrls,
+  }, defaults?.workloadIdentity));
+
+  const gateway = new BedrockAgentCoreGateway(mergeDefaults({
+    Name: `${props.name}-gateway`,
+    AuthorizerType: props.gatewayAuthorizerType ?? "AWS_IAM",
+    RoleArn: gatewayRole.Arn,
+  }, defaults?.gateway));
+
+  // Default target: route the gateway's MCP tools straight back to this
+  // agent's own Runtime endpoint (the shape Gateway's HTTP/AgentcoreRuntime
+  // target configuration exists for). Override `defaults.gatewayTarget` to
+  // point at a Lambda/OpenAPI/other target instead.
+  const gatewayTarget = new GatewayTarget(mergeDefaults({
+    GatewayIdentifier: gateway.GatewayIdentifier,
+    Name: `${props.name}-target`,
+    TargetConfiguration: {
+      Http: {
+        AgentcoreRuntime: { Arn: runtime.AgentRuntimeArn },
+      },
+    },
+  }, defaults?.gatewayTarget));
+
+  return { role, gatewayRole, runtime, endpoint, memory, workloadIdentity, gateway, gatewayTarget };
+}, "AgentCoreAgent");

package/src/composites/agentcore-trust-policy.ts

@@ -0,0 +1,13 @@
+// The service principal Bedrock AgentCore assumes to run a Runtime and to
+// invoke Gateway targets. Same shape as ecs-trust-policy.ts/lambdaTrustPolicy
+// in lambda-function.ts, one principal shared by both AgentCore-hosted roles.
+export const agentCoreTrustPolicy = {
+  Version: "2012-10-17" as const,
+  Statement: [
+    {
+      Effect: "Allow" as const,
+      Principal: { Service: "bedrock-agentcore.amazonaws.com" },
+      Action: "sts:AssumeRole",
+    },
+  ],
+};

package/src/composites/index.ts

@@ -32,3 +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 { AgentCoreAgent } from "./agentcore-agent";
+export type { AgentCoreAgentProps, AgentCoreAgentResult } from "./agentcore-agent";

package/src/composites/microvm-app.test.ts

@@ -0,0 +1,234 @@
+import { describe, test, expect } from "vitest";
+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";
+
+const baseProps = {
+  name: "worker-image",
+  description: "Worker MicroVM image",
+  codeArtifactUri: "s3://microvm-artifacts/worker/context.zip",
+  codeArtifactObjectArn: "arn:aws:s3:::microvm-artifacts/worker/context.zip",
+  baseImage: "al2023-1",
+  baseImageVersion: "0",
+};
+
+describe("MicrovmApp", () => {
+  test("returns buildRole, executionRole, and image members (no connector)", () => {
+    const instance = MicrovmApp(baseProps);
+    expect(instance.buildRole).toBeDefined();
+    expect(instance.executionRole).toBeDefined();
+    expect(instance.image).toBeDefined();
+    expect(instance.connector).toBeUndefined();
+    expect(instance.connectorSecurityGroup).toBeUndefined();
+    expect(instance.connectorOperatorRole).toBeUndefined();
+    expect(Object.keys(instance.members)).toEqual(["buildRole", "executionRole", "image"]);
+  });
+
+  test("image.BuildRoleArn references buildRole.Arn via AttrRef", () => {
+    const instance = MicrovmApp(baseProps);
+    const imageProps = (instance.image as any).props;
+    expect(imageProps.BuildRoleArn).toBeInstanceOf(AttrRef);
+  });
+
+  test("defaults: memory 2048MiB, ARM_64, empty os capabilities, logging enabled", () => {
+    const instance = MicrovmApp(baseProps);
+    const imageProps = (instance.image as any).props;
+    expect(imageProps.Resources[0].props.MinimumMemoryInMiB).toBe(2048);
+    expect(imageProps.CpuConfigurations[0].props.Architecture).toBe("ARM_64");
+    expect(imageProps.AdditionalOsCapabilities).toEqual([]);
+    expect(imageProps.EgressNetworkConnectors).toEqual([]);
+    expect(imageProps.Logging.props.CloudWatch.props.LogGroup).toBe("/aws/lambda/microvms/worker-image");
+  });
+
+  test("disableLogging emits Logging.Disabled", () => {
+    const instance = MicrovmApp({ ...baseProps, disableLogging: true });
+    const imageProps = (instance.image as any).props;
+    expect(imageProps.Logging.props.Disabled).toBe(true);
+    expect(imageProps.Logging.props.CloudWatch).toBeUndefined();
+  });
+
+  test("environment variables become Key/Value pairs", () => {
+    const instance = MicrovmApp({ ...baseProps, environment: { MODE: "prod" } });
+    const imageProps = (instance.image as any).props;
+    expect(imageProps.EnvironmentVariables).toHaveLength(1);
+    expect(imageProps.EnvironmentVariables[0].props).toEqual({ Key: "MODE", Value: "prod" });
+  });
+
+  test("rejects a reserved AWS_REGION environment key", () => {
+    expect(() => MicrovmApp({ ...baseProps, environment: { AWS_REGION: "us-east-1" } })).toThrow(/reserved/);
+  });
+
+  test("rejects an invalid memoryMiB", () => {
+    expect(() => MicrovmApp({ ...baseProps, memoryMiB: 3000 as any })).toThrow(/memoryMiB/);
+  });
+
+  test("rejects an invalid name", () => {
+    expect(() => MicrovmApp({ ...baseProps, name: "bad name!" })).toThrow(/name must match/);
+  });
+
+  test("full ARN base image passes through; alias resolves via Sub", () => {
+    const aliasInstance = MicrovmApp(baseProps);
+    const aliasArn = (aliasInstance.image as any).props.BaseImageArn;
+    expect(aliasArn).not.toBe("al2023-1");
+    expect(typeof aliasArn).toBe("object"); // SubIntrinsic
+
+    const fullArn = "arn:aws:lambda:us-east-1:aws:microvm-image:al2023-1";
+    const arnInstance = MicrovmApp({ ...baseProps, baseImage: fullArn });
+    expect((arnInstance.image as any).props.BaseImageArn).toBe(fullArn);
+  });
+
+  describe("with buildConnector", () => {
+    const withConnector = {
+      ...baseProps,
+      buildConnector: { vpcId: "vpc-123", subnetIds: ["subnet-1", "subnet-2"] },
+    };
+
+    test("adds connectorSecurityGroup, connectorOperatorRole, and connector members", () => {
+      const instance = MicrovmApp(withConnector);
+      expect(instance.connectorSecurityGroup).toBeDefined();
+      expect(instance.connectorOperatorRole).toBeDefined();
+      expect(instance.connector).toBeDefined();
+      expect(Object.keys(instance.members)).toEqual([
+        "buildRole",
+        "executionRole",
+        "image",
+        "connectorSecurityGroup",
+        "connectorOperatorRole",
+        "connector",
+      ]);
+    });
+
+    test("connector security group is deny-all egress, no ingress", () => {
+      const instance = MicrovmApp(withConnector);
+      const sgProps = (instance.connectorSecurityGroup as any).props;
+      expect(sgProps.SecurityGroupIngress).toBeUndefined();
+      expect(sgProps.SecurityGroupEgress).toHaveLength(1);
+      expect(sgProps.SecurityGroupEgress[0].props).toEqual({
+        CidrIp: "255.255.255.255/32",
+        Description: "Disallow all traffic",
+        IpProtocol: "icmp",
+        FromPort: 252,
+        ToPort: 86,
+      });
+    });
+
+    test("image.EgressNetworkConnectors references connector.Arn", () => {
+      const instance = MicrovmApp(withConnector);
+      const imageProps = (instance.image as any).props;
+      expect(imageProps.EgressNetworkConnectors).toHaveLength(1);
+      expect(imageProps.EgressNetworkConnectors[0]).toBeInstanceOf(AttrRef);
+    });
+
+    test("rejects an out-of-range subnet count", () => {
+      expect(() =>
+        MicrovmApp({ ...baseProps, buildConnector: { vpcId: "vpc-1", subnetIds: [] } }),
+      ).toThrow(/subnets/);
+    });
+
+    test("additionalEgressConnectors plus a buildConnector over the max of 10 throws", () => {
+      const extra = Array.from({ length: 10 }, (_, i) => `arn:aws:lambda:us-east-1:123456789012:network-connector:nc-${i}`);
+      expect(() =>
+        MicrovmApp({ ...withConnector, additionalEgressConnectors: extra }),
+      ).toThrow(/egress connectors/);
+    });
+  });
+
+  test("expandComposite produces correct logical names (no connector)", () => {
+    const instance = MicrovmApp(baseProps);
+    const expanded = expandComposite("worker", instance);
+    expect(expanded.has("workerBuildRole")).toBe(true);
+    expect(expanded.has("workerExecutionRole")).toBe(true);
+    expect(expanded.has("workerImage")).toBe(true);
+    expect(expanded.size).toBe(3);
+  });
+
+  describe("CloudFormation serialization", () => {
+    test("serializes to a valid CloudFormation template (no connector)", () => {
+      const instance = MicrovmApp(baseProps);
+      const entities = expandComposite("worker", instance);
+      resolveAttrRefs(entities);
+      const output = awsSerializer.serialize(entities);
+      const template = JSON.parse(output);
+
+      expect(template.AWSTemplateFormatVersion).toBe("2010-09-09");
+
+      const image = template.Resources.workerImage;
+      expect(image.Type).toBe("AWS::Lambda::MicrovmImage");
+      expect(image.Properties.Name).toBe("worker-image");
+      expect(image.Properties.Description).toBe("Worker MicroVM image");
+      expect(image.Properties.CodeArtifact).toEqual({ Uri: "s3://microvm-artifacts/worker/context.zip" });
+      expect(image.Properties.CpuConfigurations).toEqual([{ Architecture: "ARM_64" }]);
+      expect(image.Properties.Resources).toEqual([{ MinimumMemoryInMiB: 2048 }]);
+      expect(image.Properties.AdditionalOsCapabilities).toEqual([]);
+      expect(image.Properties.EgressNetworkConnectors).toEqual([]);
+      expect(image.Properties.Hooks).toEqual({});
+      expect(image.Properties.BuildRoleArn).toEqual({ "Fn::GetAtt": ["workerBuildRole", "Arn"] });
+
+      const buildRole = template.Resources.workerBuildRole;
+      expect(buildRole.Type).toBe("AWS::IAM::Role");
+      expect(buildRole.Properties.AssumeRolePolicyDocument.Statement).toHaveLength(2);
+      expect(buildRole.Properties.Policies[0].PolicyDocument.Statement[0].Resource).toBe(
+        "arn:aws:s3:::microvm-artifacts/worker/context.zip",
+      );
+
+      const executionRole = template.Resources.workerExecutionRole;
+      expect(executionRole.Type).toBe("AWS::IAM::Role");
+      expect(executionRole.Properties.Policies[0].PolicyName).toBe("MicrovmRuntimeLogs");
+
+      // Required CFN properties for AWS::Lambda::MicrovmImage all present.
+      for (const key of [
+        "Name",
+        "BaseImageArn",
+        "BaseImageVersion",
+        "BuildRoleArn",
+        "Description",
+        "CodeArtifact",
+        "Logging",
+        "EgressNetworkConnectors",
+        "CpuConfigurations",
+        "Resources",
+        "AdditionalOsCapabilities",
+        "Hooks",
+        "EnvironmentVariables",
+      ]) {
+        expect(image.Properties).toHaveProperty(key);
+      }
+    });
+
+    test("serializes the network connector + its security group and operator role", () => {
+      const instance = MicrovmApp({
+        ...baseProps,
+        buildConnector: { vpcId: "vpc-123", subnetIds: ["subnet-1", "subnet-2"], networkProtocol: "DualStack" },
+      });
+      const entities = expandComposite("worker", instance);
+      resolveAttrRefs(entities);
+      const output = awsSerializer.serialize(entities);
+      const template = JSON.parse(output);
+
+      const connector = template.Resources.workerConnector;
+      expect(connector.Type).toBe("AWS::Lambda::NetworkConnector");
+      expect(connector.Properties.OperatorRole).toEqual({ "Fn::GetAtt": ["workerConnectorOperatorRole", "Arn"] });
+      expect(connector.Properties.Configuration.VpcEgressConfiguration).toEqual({
+        AssociatedComputeResourceTypes: ["MicroVm"],
+        SubnetIds: ["subnet-1", "subnet-2"],
+        SecurityGroupIds: [{ "Fn::GetAtt": ["workerConnectorSecurityGroup", "GroupId"] }],
+        NetworkProtocol: "DualStack",
+      });
+
+      const sg = template.Resources.workerConnectorSecurityGroup;
+      expect(sg.Type).toBe("AWS::EC2::SecurityGroup");
+      expect(sg.Properties.VpcId).toBe("vpc-123");
+
+      const operatorRole = template.Resources.workerConnectorOperatorRole;
+      expect(operatorRole.Type).toBe("AWS::IAM::Role");
+      expect(operatorRole.Properties.AssumeRolePolicyDocument.Statement).toHaveLength(1);
+
+      const image = template.Resources.workerImage;
+      expect(image.Properties.EgressNetworkConnectors).toEqual([
+        { "Fn::GetAtt": ["workerConnector", "Arn"] },
+      ]);
+    });
+  });
+});