@aws-blocks/core 0.3.0 → 0.5.0

package/src/cdk/internal.ts

@@ -23,8 +23,12 @@
  * @internal
  */
 
-export { Compute } from './compute/compute.js';
-export type { DefaultComputeFactory } from './compute/default-compute-factory.js';
 // Reserved `/aws-blocks` path segment, needed by concrete computes (e.g.
 // LambdaCompute in @aws-blocks/bb-lambda-compute) to build their API route tree.
 export { BLOCKS_NAMESPACE } from '../constants.js';
+export type { ComputeDashboardSection } from './compute/compute.js';
+export { Compute } from './compute/compute.js';
+// Enumerate the computes registered on a stack — the Dashboard BB's default
+// compute selection resolves through this at finalize.
+export { getComputes } from './compute/compute-registry.js';
+export type { DefaultComputeFactory } from './compute/default-compute-factory.js';

package/src/cdk/tracer-registry.ts

@@ -0,0 +1,54 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as cdk from 'aws-cdk-lib';
+import { type IRole, PolicyStatement } from 'aws-cdk-lib/aws-iam';
+import type { Construct } from 'constructs';
+import { getComputes } from './compute/compute-registry.js';
+
+const REGISTRY_KEY = Symbol.for('BLOCKS_TRACER_PRESENCE');
+
+/**
+ * Mark that the app contains a `Tracer`. Tracing is **presence-gated**: a Tracer
+ * anywhere in the app means every compute should be traced (X-Ray provisions
+ * real, costed infra, so it's off unless the app opts in by creating a Tracer).
+ * Multiple Tracers are fine — this just records the boolean. Stored per stack
+ * (keyed by a Symbol), like the config/compute registries.
+ *
+ * @param scope - Any construct in the stack (used to locate the stack).
+ */
+export function registerTracer(scope: Construct): void {
+	(cdk.Stack.of(scope) as unknown as Record<symbol, boolean>)[REGISTRY_KEY] = true;
+}
+
+function hasTracer(stack: cdk.Stack): boolean {
+	return (stack as unknown as Record<symbol, boolean | undefined>)[REGISTRY_KEY] === true;
+}
+
+/**
+ * If the app contains a `Tracer`, enable tracing on **every** compute in the
+ * stack and grant X-Ray publish **once** on the shared execution role. Runs at
+ * the end of `create()` (after the backend module has imported, so all computes
+ * are registered). `Compute.enableTracing()` is idempotent, so this is safe
+ * regardless of how many Tracers exist.
+ *
+ * The IAM grant lives here — at the framework level, once on the shared role —
+ * rather than in each compute's `applyTracing()`: every compute assumes the same
+ * execution role, so a per-compute grant would add N identical statements. The
+ * compute only flips its own tracing mode (e.g. Lambda `TracingConfig: Active`);
+ * the permission to publish segments is a single stack-level concern.
+ *
+ * @param scope - Any construct in the stack (used to locate the stack + computes).
+ * @param executionRole - The shared execution role every compute assumes; granted
+ *   X-Ray publish once when tracing is enabled.
+ */
+export function finalizeTracing(scope: Construct, executionRole: IRole): void {
+	if (!hasTracer(cdk.Stack.of(scope))) return;
+	for (const compute of getComputes(scope)) compute.enableTracing();
+	// One grant on the shared role rather than one per traced compute.
+	executionRole.addToPrincipalPolicy(
+		new PolicyStatement({
+			actions: ['xray:PutTraceSegments', 'xray:PutTelemetryRecords'],
+			resources: ['*'],
+		}),
+	);
+}

package/src/cdk/vpc-requirements-registry.ts

@@ -0,0 +1,63 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import * as cdk from 'aws-cdk-lib';
+import type { Construct } from 'constructs';
+import type { VpcRequirements } from './vpc-types.js';
+
+const REGISTRY_KEY = Symbol.for('BLOCKS_VPC_REQUIREMENTS_REGISTRY');
+
+/** A registered requirement plus the fullId of the BB that declared it (for errors). */
+export interface RegisteredVpcRequirement {
+	readonly fullId: string;
+	readonly requirements: VpcRequirements;
+}
+
+/**
+ * Get or create the VPC-requirements list for a given stack. Stored on the stack
+ * object (keyed by a Symbol), so each stack in a multi-stack synth gets its own —
+ * a requirement never leaks into another stack's list. Mirrors the compute and
+ * config registries, which scope their state the same way.
+ */
+function getRegistry(stack: cdk.Stack): RegisteredVpcRequirement[] {
+	let list = (stack as any)[REGISTRY_KEY] as RegisteredVpcRequirement[] | undefined;
+	if (!list) {
+		list = [];
+		(stack as any)[REGISTRY_KEY] = list;
+	}
+	return list;
+}
+
+/**
+ * Register a Building Block's VPC requirements on its owning stack. Called from
+ * the {@link BuildingBlockScope} base constructor, so every BB self-registers the
+ * moment it is constructed — `finalizeVpc` then enumerates them without a separate
+ * discovery pass (mirrors how `registerCompute`/`registerConfig` accumulate during
+ * the backend import). Because it's driven by the base constructor, a BB **cannot**
+ * silently skip declaring its requirements: the constructor won't compile without
+ * supplying them (see `BuildingBlockScope`).
+ *
+ * @param bb - The construct declaring the requirement (used to locate its stack and name it).
+ * @param requirements - What the BB needs from the VPC.
+ */
+export function registerVpcRequirements(
+	bb: Construct & { readonly fullId: string },
+	requirements: VpcRequirements,
+): void {
+	getRegistry(cdk.Stack.of(bb)).push({ fullId: bb.fullId, requirements });
+}
+
+/**
+ * The VPC requirements registered on the stack that owns `scope`, in construction
+ * order. Returns an empty array before any BB is constructed.
+ *
+ * @param scope - Any construct in the stack (used to locate the stack).
+ */
+export function getVpcRequirements(scope: Construct): readonly RegisteredVpcRequirement[] {
+	return getRegistry(cdk.Stack.of(scope));
+}
+
+/** Clear the registry. **For test cleanup only.** */
+export function _resetVpcRequirementsRegistry(stack: cdk.Stack): void {
+	(stack as any)[REGISTRY_KEY] = [];
+}

package/src/cdk/vpc-types.ts

@@ -0,0 +1,158 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type * as ec2 from 'aws-cdk-lib/aws-ec2';
+
+/**
+ * A subnet role — the kind of subnet a Building Block needs, expressed as an
+ * intent the VPC resolves to a concrete {@link ec2.SubnetSelection}:
+ *
+ * - `'private-with-egress'` — private subnets with outbound internet access via
+ *   a NAT gateway. Required by anything that must reach a public AWS endpoint at
+ *   runtime (e.g. a service with no interface endpoint).
+ * - `'isolated'` — private subnets with no internet route at all. Best for
+ *   resources reached entirely over VPC endpoints or in-VPC (e.g. a database).
+ * - `'public'` — subnets with a direct internet gateway route.
+ */
+export type SubnetRole = 'private-with-egress' | 'isolated' | 'public';
+
+/**
+ * Options for VPC integration on BlocksStack / BlocksBackend.
+ *
+ * @example
+ * ```ts
+ * const vpc = new ec2.Vpc(app, 'AppVpc', { maxAzs: 2, natGateways: 1 });
+ * await BlocksStack.create(app, stackName, {
+ *   backendHandlerPath: join(__dirname, 'index.handler.ts'),
+ *   backendCDKPath: join(__dirname, 'index.ts'),
+ *   defaults: { ...BlocksPresets.production, vpc: { network: vpc } },
+ * });
+ * ```
+ */
+export interface BlocksVpcOptions {
+	/**
+	 * The VPC to place Lambdas and VPC-resident resources into.
+	 * Create this however you like — standard CDK:
+	 *
+	 * @example
+	 * const vpc = new ec2.Vpc(stack, 'AppVpc', { maxAzs: 2, natGateways: 1 });
+	 * // or
+	 * const vpc = ec2.Vpc.fromLookup(stack, 'SharedVpc', { vpcId: 'vpc-abc123' });
+	 */
+	network: ec2.IVpc;
+
+	/**
+	 * Subnet selection for Lambda and Blocks-managed compute placement.
+	 *
+	 * Any subnets you select must belong to {@link network}. This is not
+	 * validated at synth — CDK can't check it for an imported subnet (which
+	 * carries no `vpcId`) — so a mismatch surfaces as a CloudFormation error at
+	 * deploy, not a synth-time failure.
+	 *
+	 * @default { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS }
+	 */
+	subnets?: ec2.SubnetSelection;
+
+	/**
+	 * Whether to auto-provision VPC endpoints based on BB registrations.
+	 * Set to `false` to disable (e.g., when using a shared VPC that already has endpoints).
+	 *
+	 * @default true
+	 */
+	provisionEndpoints?: boolean;
+}
+
+/**
+ * VPC requirements declared by a Building Block.
+ * Supplied to the `BuildingBlockScope` constructor and collected in the central
+ * requirements registry; `finalizeVpc` pulls them to provision endpoints, and the
+ * lazy VPC uses `requiresVpc` to decide whether to derive a VPC when none was
+ * provided.
+ */
+export interface VpcRequirements {
+	/** Gateway VPC endpoints this BB needs (e.g., S3, DynamoDB). */
+	gatewayEndpoints?: ec2.GatewayVpcEndpointAwsService[];
+	/** Interface VPC endpoints this BB needs (e.g., SQS, SSM, Secrets Manager). */
+	interfaceEndpoints?: ec2.InterfaceVpcEndpointAwsService[];
+	/**
+	 * Whether this BB **cannot function without a VPC** — i.e. it must run in (or
+	 * provision resources into) a VPC regardless of whether the customer asked
+	 * for one. When any registered requirement sets this and no `vpc` was
+	 * provided, the framework **lazily derives** a default VPC (see
+	 * `getOrCreateVpc`) rather than erroring — mirroring how bb-data creates its
+	 * own VPC when no shared one exists.
+	 *
+	 * Most BBs leave this unset: they reach AWS services from the AWS-managed
+	 * Lambda network and only *benefit* from a VPC (endpoints) when one is present.
+	 * Set it only for a BB whose resources are intrinsically VPC-resident.
+	 *
+	 * @default false
+	 */
+	requiresVpc?: boolean;
+	/**
+	 * Whether the BB's **parent runtime** — the shared Blocks handler Lambda (or,
+	 * in future, a container) that executes this BB's operations — must be able to
+	 * reach the internet (outbound egress) for the BB to work at runtime.
+	 *
+	 * Set this when your BB's runtime code calls a service it can only reach over
+	 * the public internet. The canonical case: a service with no VPC endpoint
+	 * (e.g. Aurora DSQL) is reached over a public HTTPS endpoint, so the runtime
+	 * must sit in a subnet with an egress route; if it's placed in isolated
+	 * subnets the deploy still succeeds but every call times out at runtime.
+	 *
+	 * The framework **validates** this at synth against the runtime's resolved
+	 * placement (egress is satisfied by a `private-with-egress` or `public`
+	 * selection) and fails the build with an actionable message on a mismatch. It
+	 * never moves the runtime — reassigning a customer's explicit placement is not
+	 * a BB's responsibility, so an unsatisfiable requirement is an error, not a
+	 * silent relocation.
+	 *
+	 * This constrains the BB's **host**. To place compute the BB provisions
+	 * **itself** (e.g. an Aurora cluster), resolve a subnet inline in your
+	 * constructor via {@link VpcContext.selectSubnets} instead.
+	 *
+	 * @default false
+	 */
+	requiresEgress?: boolean;
+}
+
+/**
+ * The minimal shape {@link VpcContext.selectSubnets} needs from a Building
+ * Block to produce an instructive, BB-named error — just its `fullId`. Typed
+ * structurally so `vpc-types.ts` stays type-only and free of a dependency on
+ * the `Scope` class.
+ */
+export interface SubnetScope {
+	readonly fullId: string;
+}
+
+/**
+ * Internal VPC context propagated through the construct tree.
+ * Set by the CDK-level VPC option. BBs read this to determine their VPC placement.
+ * @internal
+ */
+export interface VpcContext {
+	readonly vpc: ec2.IVpc;
+	readonly computeSecurityGroup: ec2.ISecurityGroup;
+	readonly computeSubnets: ec2.SubnetSelection;
+	/**
+	 * Resolve a {@link SubnetRole} to a concrete {@link ec2.SubnetSelection} for a
+	 * resource this Building Block provisions itself, verifying the VPC actually
+	 * has subnets of that role.
+	 *
+	 * Prefer this over building an `ec2.SubnetSelection` by hand: if the VPC has
+	 * no matching subnet, it throws an actionable, BB-named error at synth
+	 * ("`KVStore 'app/cache'` needs an 'isolated' subnet, but VPC 'vpc-…' has
+	 * none …") instead of the opaque CDK "no subnet groups" error thrown later.
+	 *
+	 * @param scope   the BB requesting the subnet (its `fullId` names the error)
+	 * @param role    the subnet role the BB's own resource needs
+	 * @param opts.fallback  an alternate role to use when `role` is absent from
+	 *   the VPC. Provide it to **explicitly** allow graceful degradation (e.g.
+	 *   Aurora over the Data API works from `'private-with-egress'` when there is
+	 *   no isolated tier); omit it to require `role` strictly and fail otherwise.
+	 *   The downgrade is never silent — it only happens when you opt in here.
+	 * @throws if the VPC has neither `role` nor (when given) `opts.fallback`
+	 */
+	selectSubnets(scope: SubnetScope, role: SubnetRole, opts?: { fallback?: SubnetRole }): ec2.SubnetSelection;
+}

package/src/cdk/vpc.test.ts

@@ -0,0 +1,348 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import * as assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as cdk from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import { Construct } from 'constructs';
+import {
+	anyRequirementNeedsVpc,
+	finalizeVpc,
+	getOrCreateVpc,
+	getVpcContext,
+	initializeVpc,
+	setVpcContext,
+} from './vpc.js';
+import { registerVpcRequirements } from './vpc-requirements-registry.js';
+import type { BlocksVpcOptions, VpcRequirements } from './vpc-types.js';
+
+// A minimal stand-in for a BuildingBlockScope: finalizeVpc reads requirements
+// from the central registry, and the real BuildingBlockScope base registers in
+// its constructor. This fake does the same (register on construction) so it
+// exercises the real pull-and-provision path without pulling every BB package
+// into core's test graph. A `fullId` getter mirrors the real Scope so error
+// messages that name the BB can be asserted.
+class FakeBB extends Construct {
+	constructor(scope: Construct, id: string, reqs: VpcRequirements) {
+		super(scope, id);
+		registerVpcRequirements(this, reqs);
+	}
+	get fullId(): string {
+		return this.node.id;
+	}
+}
+
+/**
+ * Build a stack + VPC, optionally initialize the VPC context (so the endpoint
+ * SG can scope to the Lambda SG), add fake BBs, then run finalizeVpc.
+ */
+function synthWith(
+	bbs: (scope: Construct) => void,
+	opts?: Partial<BlocksVpcOptions> & { natGateways?: number; withContext?: boolean },
+): Template {
+	const app = new cdk.App();
+	const stack = new cdk.Stack(app, 'TestStack', { env: { account: '123456789012', region: 'us-east-1' } });
+	const vpc = new ec2.Vpc(stack, 'Vpc', { maxAzs: 2, natGateways: opts?.natGateways ?? 1 });
+	const options: BlocksVpcOptions = {
+		network: vpc,
+		subnets: opts?.subnets,
+		provisionEndpoints: opts?.provisionEndpoints,
+	};
+	if (opts?.withContext !== false) initializeVpc(stack, options);
+	bbs(stack);
+	finalizeVpc(stack, options);
+	return Template.fromStack(stack);
+}
+
+const IFACE = 'AWS::EC2::VPCEndpoint';
+
+/** Count interface vs gateway endpoints in a synthesized template. */
+function endpointCounts(template: Template): { iface: number; gateway: number } {
+	const eps = template.findResources(IFACE);
+	let iface = 0;
+	let gateway = 0;
+	for (const ep of Object.values(eps)) {
+		const type = (ep as { Properties?: { VpcEndpointType?: string } }).Properties?.VpcEndpointType;
+		// Interface endpoints set VpcEndpointType: 'Interface'; gateway endpoints
+		// default the property (Gateway) and omit it in the synthesized template.
+		if (type === 'Interface') iface += 1;
+		else gateway += 1;
+	}
+	return { iface, gateway };
+}
+
+describe('finalizeVpc — endpoint provisioning', () => {
+	it('always provisions CloudWatch Logs (interface) and S3 (gateway), even with no BBs', () => {
+		const template = synthWith(() => {});
+		const { iface, gateway } = endpointCounts(template);
+		assert.equal(gateway, 1); // S3 gateway, always-on (free)
+		assert.equal(iface, 1); // Logs, always-on
+		template.hasResourceProperties(IFACE, {
+			VpcEndpointType: 'Interface',
+			ServiceName: 'com.amazonaws.us-east-1.logs',
+		});
+		// Exactly one gateway endpoint (S3). Its ServiceName synthesizes as a
+		// region-tokenized Fn::Join, so assert by type/count rather than a literal.
+		const gateways = template.findResources(IFACE, { Properties: { VpcEndpointType: 'Gateway' } });
+		assert.equal(Object.keys(gateways).length, 1, 'exactly one gateway endpoint (S3)');
+		// SSM is NOT always-on — it flows from BB requirements only.
+		const ssm = template.findResources(IFACE, {
+			Properties: { ServiceName: 'com.amazonaws.us-east-1.ssm' },
+		});
+		assert.equal(Object.keys(ssm).length, 0, 'no SSM endpoint without a BB that needs it');
+	});
+
+	it('provisions the union of BB-declared endpoints plus the always-on Logs + S3', () => {
+		const template = synthWith((scope) => {
+			new FakeBB(scope, 'Kv', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+			new FakeBB(scope, 'Bucket', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.S3] });
+			new FakeBB(scope, 'Job', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS] });
+			new FakeBB(scope, 'Db', {
+				interfaceEndpoints: [
+					ec2.InterfaceVpcEndpointAwsService.SECRETS_MANAGER,
+					ec2.InterfaceVpcEndpointAwsService.RDS_DATA,
+				],
+			});
+		});
+		const { iface, gateway } = endpointCounts(template);
+		// Gateways: DynamoDB + S3 (BB's S3 dedups with the always-on S3).
+		assert.equal(gateway, 2);
+		// Interfaces: SQS + Secrets Manager + RDS Data + always-on Logs.
+		assert.equal(iface, 4);
+	});
+
+	it('deduplicates endpoints requested by multiple BBs', () => {
+		const template = synthWith((scope) => {
+			new FakeBB(scope, 'Kv1', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+			new FakeBB(scope, 'Kv2', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+			new FakeBB(scope, 'Job1', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS] });
+			new FakeBB(scope, 'Job2', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS] });
+		});
+		const { iface, gateway } = endpointCounts(template);
+		// Two DynamoDB requests collapse to one; plus always-on S3 = 2 gateways.
+		assert.equal(gateway, 2);
+		// Two SQS requests collapse to one; plus always-on Logs = 2 interfaces.
+		assert.equal(iface, 2);
+	});
+
+	it('provisions SSM only when a BB declares it (and dedups multiple declarations)', () => {
+		const template = synthWith((scope) => {
+			new FakeBB(scope, 'AppSetting', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SSM] });
+			new FakeBB(scope, 'Auth', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SSM] });
+		});
+		const { iface } = endpointCounts(template);
+		// Two SSM requests collapse to one; plus always-on Logs = 2 interfaces.
+		assert.equal(iface, 2);
+		template.hasResourceProperties(IFACE, {
+			VpcEndpointType: 'Interface',
+			ServiceName: 'com.amazonaws.us-east-1.ssm',
+		});
+	});
+
+	it('provisions nothing when provisionEndpoints is false (but still validates requiresEgress)', () => {
+		const template = synthWith(
+			(scope) => {
+				new FakeBB(scope, 'Kv', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+			},
+			{ provisionEndpoints: false },
+		);
+		template.resourceCountIs(IFACE, 0);
+	});
+
+	it('scopes the interface-endpoint SG to 443 from the Blocks Lambda SG only', () => {
+		const template = synthWith((scope) => {
+			new FakeBB(scope, 'Job', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS] });
+		});
+		// A dedicated endpoint SG exists, described as Lambda-scoped, with a 443
+		// ingress rule sourced from another SG (the Lambda SG) rather than the whole
+		// VPC CIDR. We assert the rule is present (arrayWith) rather than the exact
+		// array, since CDK may add its own paired rule for the endpoint association.
+		const sgs = template.findResources('AWS::EC2::SecurityGroup', {
+			Properties: { GroupDescription: 'Blocks interface VPC endpoints — 443 from the Blocks Lambda only' },
+		});
+		assert.equal(Object.keys(sgs).length, 1, 'exactly one dedicated endpoint SG');
+		const sg = Object.values(sgs)[0] as {
+			Properties: { SecurityGroupIngress: Array<{ FromPort?: number; ToPort?: number; CidrIp?: string }> };
+		};
+		const ingress = sg.Properties.SecurityGroupIngress ?? [];
+		const https = ingress.filter((r) => r.FromPort === 443 && r.ToPort === 443);
+		assert.equal(https.length, 1, 'exactly one 443 ingress rule');
+		// Must NOT be open to a CIDR (that would be the broad default we're avoiding).
+		assert.equal(https[0].CidrIp, undefined, '443 ingress is SG-sourced, not CIDR-open');
+	});
+});
+
+describe('finalizeVpc — requiresEgress validation', () => {
+	it('passes when the runtime placement provides egress', () => {
+		// Default placement is private-with-egress, which provides egress.
+		assert.doesNotThrow(() =>
+			synthWith((scope) => {
+				new FakeBB(scope, 'Dsql', { requiresEgress: true });
+			}),
+		);
+	});
+
+	it('throws an actionable, BB-named error when the placement has no egress', () => {
+		// Place the runtime in isolated subnets; a BB needing egress cannot be served.
+		assert.throws(
+			() =>
+				synthWith(
+					(scope) => {
+						new FakeBB(scope, 'Dsql', { requiresEgress: true });
+					},
+					{ subnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED } },
+				),
+			/Dsql requires its runtime to reach the internet.*no egress/s,
+		);
+	});
+
+	it('does not validate a BB that does not require egress', () => {
+		// A BB with no egress need is fine in isolated subnets.
+		assert.doesNotThrow(() =>
+			synthWith(
+				(scope) => {
+					new FakeBB(scope, 'Bb', {});
+				},
+				{ subnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED } },
+			),
+		);
+	});
+});
+
+describe('initializeVpc — Lambda placement guard', () => {
+	function init(natGateways: number, subnets?: ec2.SubnetSelection) {
+		const app = new cdk.App();
+		const stack = new cdk.Stack(app, 'S', { env: { account: '123456789012', region: 'us-east-1' } });
+		const subnetConfiguration =
+			natGateways === 0
+				? [{ name: 'isolated', subnetType: ec2.SubnetType.PRIVATE_ISOLATED, cidrMask: 24 }]
+				: undefined;
+		const vpc = new ec2.Vpc(stack, 'Vpc', { maxAzs: 2, natGateways, subnetConfiguration });
+		return () => initializeVpc(stack, { network: vpc, subnets });
+	}
+
+	it('throws an actionable error when defaulting to private-with-egress but the VPC has none', () => {
+		assert.throws(init(0), /no private-with-egress subnets.*NAT gateway/s);
+	});
+
+	it('does not throw when the VPC has a private-with-egress tier', () => {
+		assert.doesNotThrow(init(1));
+	});
+
+	it('honors an explicit isolated placement without the private-with-egress guard', () => {
+		// Caller explicitly chose isolated; the default-path guard must not fire.
+		assert.doesNotThrow(init(0, { subnetType: ec2.SubnetType.PRIVATE_ISOLATED }));
+	});
+});
+
+describe('VpcContext.selectSubnets — instructive resolution', () => {
+	function contextFor(natGateways: number) {
+		const app = new cdk.App();
+		const stack = new cdk.Stack(app, 'S', { env: { account: '123456789012', region: 'us-east-1' } });
+		const vpc = new ec2.Vpc(stack, 'Vpc', { maxAzs: 2, natGateways });
+		// With natGateways: 0 CDK still creates the default public+private config,
+		// but the private tier becomes isolated (no NAT). Build an explicit
+		// isolated-only VPC to exercise the "no isolated" and "no egress" cases.
+		return initializeVpc(stack, { network: vpc, subnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS } });
+	}
+
+	it('returns the requested role when the VPC has it', () => {
+		const ctx = contextFor(1);
+		const sel = ctx.selectSubnets({ fullId: 'app/db' }, 'private-with-egress');
+		assert.equal(sel.subnetType, ec2.SubnetType.PRIVATE_WITH_EGRESS);
+	});
+
+	it('falls back to an explicit fallback role when the requested role is absent', () => {
+		const ctx = contextFor(1); // has public + private-with-egress, no isolated
+		const sel = ctx.selectSubnets({ fullId: 'app/db' }, 'isolated', { fallback: 'private-with-egress' });
+		assert.equal(sel.subnetType, ec2.SubnetType.PRIVATE_WITH_EGRESS);
+	});
+
+	it('throws a BB-named error when neither the role nor its fallback exists', () => {
+		const ctx = contextFor(1); // no isolated tier, and no public fallback requested that helps
+		assert.throws(
+			() => ctx.selectSubnets({ fullId: 'app/db' }, 'isolated'),
+			/app\/db needs a 'isolated' subnet.*has none/s,
+		);
+	});
+});
+
+// We can't fully test CDK constructs without a Stack, but we can test
+// the getVpcContext logic with mock constructs.
+
+describe('VPC utilities', () => {
+	it('getVpcContext returns undefined when no context set', () => {
+		const fakeScope: any = { node: { scope: undefined } };
+		assert.equal(getVpcContext(fakeScope), undefined);
+	});
+
+	it('getVpcContext walks up the scope tree', () => {
+		const vpcContext = { vpc: 'mock-vpc', computeSecurityGroup: 'mock-sg', computeSubnets: {} };
+		const parent: any = { node: { scope: undefined } };
+		setVpcContext(parent, vpcContext as any);
+
+		const child: any = { node: { scope: parent } };
+		assert.equal(getVpcContext(child), vpcContext);
+	});
+
+	it('setVpcContext stores context on the scope', () => {
+		const fakeScope: any = { node: { scope: undefined } };
+		const vpcContext = { vpc: 'mock-vpc', computeSecurityGroup: 'mock-sg', computeSubnets: {} };
+		setVpcContext(fakeScope, vpcContext as any);
+		assert.equal(getVpcContext(fakeScope), vpcContext);
+	});
+});
+
+describe('lazy VPC derivation', () => {
+	function stackWith(bbs: (scope: Construct) => void): { stack: cdk.Stack; scope: Construct } {
+		const app = new cdk.App();
+		const stack = new cdk.Stack(app, 'LazyStack', { env: { account: '123456789012', region: 'us-east-1' } });
+		bbs(stack);
+		return { stack, scope: stack };
+	}
+
+	it('anyRequirementNeedsVpc is false for BBs that only declare endpoints', () => {
+		const { scope } = stackWith((s) => {
+			new FakeBB(s, 'Kv', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+			new FakeBB(s, 'Job', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS] });
+		});
+		assert.equal(anyRequirementNeedsVpc(scope), false);
+	});
+
+	it('anyRequirementNeedsVpc is true when a BB declares requiresVpc', () => {
+		const { scope } = stackWith((s) => {
+			new FakeBB(s, 'Kv', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+			new FakeBB(s, 'Container', { requiresVpc: true });
+		});
+		assert.equal(anyRequirementNeedsVpc(scope), true);
+	});
+
+	it('getOrCreateVpc returns the same VPC on repeated calls (singleton)', () => {
+		const { scope } = stackWith(() => {});
+		const a = getOrCreateVpc(scope);
+		const b = getOrCreateVpc(scope);
+		assert.equal(a, b, 'lazy VPC is a per-stack singleton');
+	});
+
+	it('a derived VPC + finalizeVpc provisions endpoints for a requiresVpc app', () => {
+		const app = new cdk.App();
+		const stack = new cdk.Stack(app, 'DerivedStack', { env: { account: '123456789012', region: 'us-east-1' } });
+		new FakeBB(stack, 'Container', {
+			requiresVpc: true,
+			interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS],
+		});
+		assert.equal(anyRequirementNeedsVpc(stack), true);
+		const vpc = getOrCreateVpc(stack);
+		const options = { network: vpc };
+		initializeVpc(stack, options);
+		finalizeVpc(stack, options);
+		const template = Template.fromStack(stack);
+		// SQS (from the BB) + always-on CloudWatch Logs interface endpoints, plus
+		// the always-on S3 gateway endpoint.
+		const { iface, gateway } = endpointCounts(template);
+		assert.equal(iface, 2, 'SQS + Logs');
+		assert.equal(gateway, 1, 'S3 gateway');
+	});
+});