@aws-blocks/core 0.3.0 → 0.5.0

package/dist/cdk/index.js

@@ -1,25 +1,40 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import * as cdk from 'aws-cdk-lib';
-import { Construct } from 'constructs';
 import { pathToFileURL } from 'node:url';
 import { __PIPELINE_STAGE_SCOPE__ } from '@aws-blocks/pipeline';
+import * as cdk from 'aws-cdk-lib';
+import { Construct } from 'constructs';
 import { computeScopeFullId, } from '../common/index.js';
-import { setupBlocksInfra, BlocksBackend, assertCdkConditionActive } from './blocks-backend.js';
-import { addBlocksStackMetadata } from './stack-metadata.js';
-import { finalizeConfigRegistry } from './config-registry.js';
+import { assertCdkConditionActive, BlocksBackend, setupBlocksInfra } from './blocks-backend.js';
 import { BlocksPresets } from './blocks-defaults.js';
+import { getComputes } from './compute/compute-registry.js';
+import { finalizeConfigRegistry } from './config-registry.js';
+import { finalizeDashboards } from './dashboard-registry.js';
+import { addBlocksStackMetadata } from './stack-metadata.js';
+import { finalizeTracing } from './tracer-registry.js';
+import { anyRequirementNeedsVpc, finalizeVpc, getOrCreateVpc, initializeVpc } from './vpc.js';
+import { registerVpcRequirements } from './vpc-requirements-registry.js';
+export { ApiError, DEFAULT_API_ERROR_NAME, hasAuthError, isBlocksError } from '../errors.js';
+export { ensureApiGatewayAccount } from './apigateway-account.js';
 export { BlocksBackend, SHARED_HANDLER_TIMEOUT_SECONDS, } from './blocks-backend.js';
-export { DEFAULT_NODE_RUNTIME } from './node-version.js';
+export { BlocksPresets, } from './blocks-defaults.js';
 export { blocksNodejsBundling } from './bundling.js';
+export { finalizeConfigRegistry, getConfigLocation, registerConfig } from './config-registry.js';
+export { finalizeDashboards, registerDashboardFinalizer } from './dashboard-registry.js';
 export { SandboxDisableDeletionProtection } from './mixins.js';
-export { registerConfig, finalizeConfigRegistry } from './config-registry.js';
-export { BlocksPresets, } from './blocks-defaults.js';
+export { DEFAULT_NODE_RUNTIME } from './node-version.js';
 export { synthGuard } from './synth-guard.js';
-export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
+export { finalizeTracing, registerTracer } from './tracer-registry.js';
+export { getVpcContext } from './vpc.js';
 export class BlocksStack extends cdk.Stack {
     id;
     backendHandlerPath;
+    /**
+     * Path to the app's backend module (`props.backendCDKPath`). Exposed so Building Blocks that
+     * co-bundle the backend at synth (e.g. the Agent BB's AgentCore Runtime) can discover it via
+     * `globalThis.CURRENT_BLOCKS_STACK.backendModulePath`.
+     */
+    backendModulePath;
     /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
     executionRole;
     /** Infrastructure defaults for Building Blocks created under this stack. */
@@ -38,19 +53,35 @@ export class BlocksStack extends cdk.Stack {
     get apiUrl() {
         return this.requireDefaultCompute().apiUrl;
     }
+    /** The default compute's handler CloudWatch log group. Its retention comes from
+     * the compute's `logRetention` (falling back to `defaults.logRetention`); the
+     * `bb-logger` CDK construct is a no-op and no longer touches it. */
+    get handlerLogGroup() {
+        return this.requireDefaultCompute().logGroup;
+    }
     requireDefaultCompute() {
         if (!this._defaultCompute) {
             throw new Error('Blocks stack not fully initialized — access .handler/.gateway/.apiUrl after BlocksStack.create() resolves.');
         }
         return this._defaultCompute;
     }
+    _vpcOptions;
     constructor(scope, id, props) {
         super(scope, id, props);
         this.id = id;
         this.backendHandlerPath = props.backendHandlerPath;
+        this.backendModulePath = props.backendCDKPath;
         this.defaults = props.defaults;
+        this._vpcOptions = props.defaults.vpc;
         // Set globalThis so Building Blocks attach directly to this stack
         globalThis.CURRENT_BLOCKS_STACK = this;
+        // Initialize VPC context before the default compute is created and before
+        // BBs are constructed, so both can discover it: the default compute
+        // (LambdaCompute) reads it via getVpcContext(this) to place its function in
+        // the VPC, and BBs (e.g. bb-data) read it to co-locate their resources.
+        if (this._vpcOptions) {
+            initializeVpc(this, this._vpcOptions);
+        }
         const infra = setupBlocksInfra(this, props, id);
         this.executionRole = infra.executionRole;
     }
@@ -81,7 +112,30 @@ export class BlocksStack extends cdk.Stack {
             }
         }
         // Finalize BB config → S3 (after all BBs have registered their config)
-        finalizeConfigRegistry(stack, stack.handler);
+        finalizeConfigRegistry(stack, stack.executionRole, getComputes(stack));
+        // Tracing is presence-gated: if the app contains a Tracer, enable X-Ray on
+        // every compute. Runs before the dashboard finalize so tracingEnabled is
+        // set when the dashboard reads it.
+        finalizeTracing(stack, stack.executionRole);
+        // Build any deferred Dashboards now that every compute's observability
+        // state is settled — so the dashboard is order-independent.
+        finalizeDashboards(stack);
+        // Finalize VPC. A VPC is a derived resource: use the customer's if they
+        // brought one, else lazily create one only if a Building Block genuinely
+        // requires it (requiresVpc). Most apps need neither — Lambda reaches AWS
+        // services from the managed network without a VPC.
+        if (stack._vpcOptions) {
+            finalizeVpc(stack, stack._vpcOptions);
+        }
+        else if (anyRequirementNeedsVpc(stack)) {
+            const derived = getOrCreateVpc(stack);
+            const options = { network: derived };
+            initializeVpc(stack, options);
+            finalizeVpc(stack, options);
+            cdk.Annotations.of(stack).addInfoV2('blocks:vpc:derived', 'A Building Block required a VPC and none was provided, so Blocks created one ' +
+                '(with a NAT gateway, which has an ongoing cost). Pass `defaults.vpc: { network }` to ' +
+                'BlocksStack.create to bring your own. See packages/blocks/VPC.md.');
+        }
         new cdk.CfnOutput(stack, 'ApiUrl', { value: stack.apiUrl });
         addBlocksStackMetadata(stack);
         return stack;
@@ -165,6 +219,23 @@ export class Scope extends Construct {
         }
         return defaultCompute;
     }
+    /**
+     * The stack's default compute, **ignoring** any per-scope `_compute`
+     * assignment (unlike {@link compute}, which resolves the nearest assigned
+     * one). Use when a resource is a stack-level singleton that must bind to one
+     * deterministic compute regardless of the block's resolved compute — e.g.
+     * Realtime's shared WebSocket route integration, where one WebSocket API
+     * integrates to a single target and connection bookkeeping is compute-agnostic.
+     *
+     * @internal Not a customer surface; for framework/BB singleton infra only.
+     */
+    get defaultCompute() {
+        const defaultCompute = this.root._defaultCompute;
+        if (!defaultCompute) {
+            throw new Error('Default compute not initialized — BlocksStack/BlocksBackend.create() must run before resolving `defaultCompute`.');
+        }
+        return defaultCompute;
+    }
     /**
      * The backend entry file the owning BlocksStack/BlocksBackend runs — the
      * single handler entry shared across the whole app.
@@ -187,6 +258,16 @@ export class Scope extends Construct {
         }
         return name;
     }
+    /**
+     * The shared handler Lambda's CloudWatch log group (the default compute's).
+     * Resolves the same way as {@link handler} — via the owning
+     * BlocksStack/BlocksBackend. Its retention comes from the compute's
+     * `logRetention` (falling back to `defaults.logRetention`); the `bb-logger`
+     * CDK construct is a no-op and no longer reconfigures it.
+     */
+    get handlerLogGroup() {
+        return this.root.handlerLogGroup;
+    }
     get fullId() {
         return computeScopeFullId(this);
     }
@@ -212,7 +293,8 @@ export class Scope extends Construct {
                 return current.defaults;
             }
         }
-        const ambient = globalThis.CURRENT_BLOCKS_STACK?.defaults;
+        const ambient = globalThis.CURRENT_BLOCKS_STACK
+            ?.defaults;
         if (ambient)
             return ambient;
         // No owning BlocksStack/BlocksBackend in the tree and none ambient — this is
@@ -230,6 +312,46 @@ export class Scope extends Construct {
     registerClientMiddleware(_packageSpecifier) { }
     registerDevAttachment(_packageSpecifier) { }
     registerLambdaEventHandler(_eventSource, _identifier, _handler) { }
-    get clientMiddleware() { return []; }
-    get devAttachments() { return []; }
+    get clientMiddleware() {
+        return [];
+    }
+    get devAttachments() {
+        return [];
+    }
+}
+/**
+ * Base class for Building Block CDK constructs.
+ *
+ * BBs extend this instead of `Scope` directly and **must** declare their VPC
+ * requirements as a constructor argument — the base registers them centrally
+ * (see `vpc-requirements-registry.ts`) so `finalizeVpc` can pull, deduplicate,
+ * and provision endpoints, and so the lazy VPC can answer "does anything here
+ * need a VPC?". Passing the requirements is required by the constructor
+ * signature, so a BB author cannot silently forget to declare them — the same
+ * forcing the previous `abstract getVpcRequirements()` gave, but without a
+ * standing method on every subclass.
+ *
+ * Declare `{}` when the BB needs nothing VPC-specific.
+ *
+ * @example
+ * ```ts
+ * export class KVStore extends BuildingBlockScope {
+ *   constructor(scope: ScopeParent, id: string) {
+ *     super(id, { parent: scope, vpc: { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] } });
+ *     // …
+ *   }
+ * }
+ * ```
+ */
+export class BuildingBlockScope extends Scope {
+    constructor(id, options) {
+        const { vpc, ...scopeOptions } = options;
+        super(id, scopeOptions);
+        // Resolve the provider (callback form is evaluated here, after super(), so
+        // values that depend on this.fullId are available) and self-register on the
+        // owning stack. Register even when empty so the registry is a faithful
+        // census of every BB — the lazy VPC and finalizeVpc both rely on that.
+        const requirements = typeof vpc === 'function' ? vpc() : vpc;
+        registerVpcRequirements(this, requirements);
+    }
 }

package/dist/cdk/internal.d.ts

@@ -19,7 +19,9 @@
  *
  * @internal
  */
+export { BLOCKS_NAMESPACE } from '../constants.js';
+export type { ComputeDashboardSection } from './compute/compute.js';
 export { Compute } from './compute/compute.js';
+export { getComputes } from './compute/compute-registry.js';
 export type { DefaultComputeFactory } from './compute/default-compute-factory.js';
-export { BLOCKS_NAMESPACE } from '../constants.js';
 //# sourceMappingURL=internal.d.ts.map

package/dist/cdk/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/cdk/internal.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAGlF,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/cdk/internal.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAG/C,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,YAAY,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC"}

package/dist/cdk/internal.js

@@ -21,7 +21,10 @@
  *
  * @internal
  */
-export { Compute } from './compute/compute.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 { 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';

package/dist/cdk/tracer-registry.d.ts

@@ -0,0 +1,31 @@
+import { type IRole } from 'aws-cdk-lib/aws-iam';
+import type { Construct } from 'constructs';
+/**
+ * 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 declare function registerTracer(scope: Construct): void;
+/**
+ * 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 declare function finalizeTracing(scope: Construct, executionRole: IRole): void;
+//# sourceMappingURL=tracer-registry.d.ts.map

package/dist/cdk/tracer-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer-registry.d.ts","sourceRoot":"","sources":["../../src/cdk/tracer-registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,KAAK,EAAmB,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK5C;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAErD;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,GAAG,IAAI,CAU5E"}

package/dist/cdk/tracer-registry.js

@@ -0,0 +1,49 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as cdk from 'aws-cdk-lib';
+import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
+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) {
+    cdk.Stack.of(scope)[REGISTRY_KEY] = true;
+}
+function hasTracer(stack) {
+    return stack[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, executionRole) {
+    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/dist/cdk/vpc-requirements-registry.d.ts

@@ -0,0 +1,33 @@
+import * as cdk from 'aws-cdk-lib';
+import type { Construct } from 'constructs';
+import type { VpcRequirements } from './vpc-types.js';
+/** A registered requirement plus the fullId of the BB that declared it (for errors). */
+export interface RegisteredVpcRequirement {
+    readonly fullId: string;
+    readonly requirements: VpcRequirements;
+}
+/**
+ * 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 declare function registerVpcRequirements(bb: Construct & {
+    readonly fullId: string;
+}, requirements: VpcRequirements): void;
+/**
+ * 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 declare function getVpcRequirements(scope: Construct): readonly RegisteredVpcRequirement[];
+/** Clear the registry. **For test cleanup only.** */
+export declare function _resetVpcRequirementsRegistry(stack: cdk.Stack): void;
+//# sourceMappingURL=vpc-requirements-registry.d.ts.map

package/dist/cdk/vpc-requirements-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpc-requirements-registry.d.ts","sourceRoot":"","sources":["../../src/cdk/vpc-requirements-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAItD,wFAAwF;AACxF,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;CACvC;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACtC,EAAE,EAAE,SAAS,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC3C,YAAY,EAAE,eAAe,GAC3B,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,wBAAwB,EAAE,CAExF;AAED,qDAAqD;AACrD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,IAAI,CAEpE"}

package/dist/cdk/vpc-requirements-registry.js

@@ -0,0 +1,46 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as cdk from 'aws-cdk-lib';
+const REGISTRY_KEY = Symbol.for('BLOCKS_VPC_REQUIREMENTS_REGISTRY');
+/**
+ * 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) {
+    let list = stack[REGISTRY_KEY];
+    if (!list) {
+        list = [];
+        stack[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, requirements) {
+    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) {
+    return getRegistry(cdk.Stack.of(scope));
+}
+/** Clear the registry. **For test cleanup only.** */
+export function _resetVpcRequirementsRegistry(stack) {
+    stack[REGISTRY_KEY] = [];
+}

package/dist/cdk/vpc-types.d.ts

@@ -0,0 +1,151 @@
+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;
+}
+//# sourceMappingURL=vpc-types.d.ts.map

package/dist/cdk/vpc-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpc-types.d.ts","sourceRoot":"","sources":["../../src/cdk/vpc-types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,qBAAqB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;OAQG;IACH,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC;IAElB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,eAAe,CAAC;IAE9B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC/B,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,GAAG,CAAC,4BAA4B,EAAE,CAAC;IACtD,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,GAAG,CAAC,8BAA8B,EAAE,CAAC;IAC1D;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC;IACvB,QAAQ,CAAC,oBAAoB,EAAE,GAAG,CAAC,cAAc,CAAC;IAClD,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC,eAAe,CAAC;IAC7C;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,UAAU,CAAA;KAAE,GAAG,GAAG,CAAC,eAAe,CAAC;CAC3G"}

package/dist/cdk/vpc-types.js

@@ -0,0 +1,3 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/dist/cdk/vpc.d.ts

@@ -0,0 +1,59 @@
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import type { Construct } from 'constructs';
+import type { BlocksVpcOptions, VpcContext } from './vpc-types.js';
+/**
+ * Set the VPC context on a scope (BlocksStack or BlocksBackend).
+ * Called during stack creation when `vpc` prop is provided.
+ * @internal
+ */
+export declare function setVpcContext(scope: Construct, context: VpcContext): void;
+/**
+ * Get the VPC context from a scope by walking up the construct tree.
+ * Used by BBs (e.g., bb-data) to discover the shared VPC.
+ * @internal
+ */
+export declare function getVpcContext(scope: Construct): VpcContext | undefined;
+/**
+ * Does any registered Building Block *require* a VPC (i.e. cannot function
+ * without one)? Used to decide whether to lazily derive a VPC when the customer
+ * didn't provide one. A BB that merely benefits from endpoints does NOT count —
+ * only `requiresVpc: true`.
+ * @internal
+ */
+export declare function anyRequirementNeedsVpc(scope: Construct): boolean;
+/**
+ * Get the framework-owned VPC for a stack, creating one on first use.
+ *
+ * VPC is a **derived** resource: when a Building Block (or, later, a container
+ * compute) requires one and the customer didn't bring their own, Blocks
+ * materializes a sensible default here — the same create-if-absent pattern
+ * `bb-data` uses for Aurora, lifted to the framework so the whole app shares a
+ * single VPC. Keyed by a Symbol on the stack so it's a true singleton: the first
+ * caller creates, everyone else reuses. Passing a customer VPC (`vpc:` prop)
+ * pre-seeds this via {@link initializeVpc}, so this default is only built when
+ * nothing was provided.
+ *
+ * The default has both a `private-with-egress` tier (for a runtime that needs
+ * outbound access — the derivation trigger) and public subnets for the NAT
+ * gateway. NAT has a real cost, so this is only created on genuine need, and
+ * `create()` emits a notice when it does.
+ * @internal
+ */
+export declare function getOrCreateVpc(scope: Construct): ec2.IVpc;
+/**
+ * Initialize VPC support on a Blocks scope (BlocksStack or BlocksBackend).
+ * Creates the security group, sets VPC context, and returns the VpcContext
+ * that is used for Lambda placement configuration.
+ *
+ * Called during setupBlocksInfra when `vpc` prop is present.
+ * @internal
+ */
+export declare function initializeVpc(scope: Construct, options: BlocksVpcOptions): VpcContext;
+/**
+ * Finalize VPC: query all BuildingBlockScope children for their VPC requirements,
+ * deduplicate, and provision endpoints.
+ * Called after all BBs are constructed (alongside finalizeConfigRegistry).
+ * @internal
+ */
+export declare function finalizeVpc(scope: Construct, options: BlocksVpcOptions): void;
+//# sourceMappingURL=vpc.d.ts.map

package/dist/cdk/vpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpc.d.ts","sourceRoot":"","sources":["../../src/cdk/vpc.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAA2B,UAAU,EAAmB,MAAM,gBAAgB,CAAC;AA4B7G;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAQtE;AAID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAEhE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,GAAG,CAAC,IAAI,CAOzD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,UAAU,CAkDrF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAyH7E"}