@aws-blocks/core 0.4.0 → 0.5.0

package/dist/cdk/dashboard-registry.js

@@ -0,0 +1,61 @@
+// 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_DASHBOARD_REGISTRY');
+/**
+ * Get or create the deferred-dashboard 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 — mirrors the config + compute registries.
+ */
+function getRegistry(stack) {
+    let list = stack[REGISTRY_KEY];
+    if (!list) {
+        list = [];
+        stack[REGISTRY_KEY] = list;
+    }
+    return list;
+}
+/**
+ * Register a Dashboard's deferred body-build, to run after every Building Block
+ * in the app has been constructed (the end of `BlocksStack`/`BlocksBackend`
+ * `create()`, once the backend module has fully imported).
+ *
+ * The Dashboard builds its widget body here rather than in its constructor
+ * because the body depends on which computes are traced, and a `Tracer` may be
+ * constructed *after* the Dashboard. Deferring makes the Dashboard observe the
+ * complete app, so it never depends on construction order. (The Dashboard's
+ * CloudWatch resource itself is created eagerly in the constructor, so its URL /
+ * redirect route never dangle — only the body is deferred.)
+ *
+ * This is intentionally scoped to the Dashboard (the only deferred-build case
+ * today) rather than a generic finalizer mechanism; generalize it only if a
+ * second use case appears.
+ *
+ * @param scope - Any construct in the stack (used to locate the stack).
+ * @param finalize - The deferred body-build; run once (in registration order)
+ *   by {@link finalizeDashboards}.
+ */
+export function registerDashboardFinalizer(scope, finalize) {
+    getRegistry(cdk.Stack.of(scope)).push(finalize);
+}
+/**
+ * Run — and clear — every registered Dashboard finalizer on `scope`'s stack, in
+ * registration order. Called once from `create()` after the backend module has
+ * imported. Clearing the list makes a repeated call a no-op, so a dashboard's
+ * body is never built twice.
+ *
+ * A Dashboard constructed outside `create()` (e.g. directly in a unit test) must
+ * call this explicitly before synth — the same way `config-registry.test.ts`
+ * drives `finalizeConfigRegistry`. (A Dashboard's CloudWatch resource is created
+ * eagerly in its constructor, so even if its finalizer never runs its URL /
+ * redirect never dangle — only the widget body is missing.)
+ *
+ * @param scope - Any construct in the stack (used to locate the stack).
+ */
+export function finalizeDashboards(scope) {
+    const list = getRegistry(cdk.Stack.of(scope));
+    // Drain the list so a repeated call can't rebuild an already-built dashboard.
+    const pending = list.splice(0, list.length);
+    for (const finalize of pending)
+        finalize();
+}

package/dist/cdk/index.d.ts

@@ -1,19 +1,24 @@
 import * as cdk from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { type BlocksStackProps, type BlocksStack as BaseBlocksStack, type ScopeParent, type ScopeOptions } from '../common/index.js';
+import { type BlocksStack as BaseBlocksStack, type BlocksStackProps, type ScopeOptions, type ScopeParent } from '../common/index.js';
 import { type BlocksDefaults } from './blocks-defaults.js';
 import type { Compute } from './compute/compute.js';
 import type { DefaultComputeFactory } from './compute/default-compute-factory.js';
+import type { VpcRequirements } from './vpc-types.js';
+export { ApiError, DEFAULT_API_ERROR_NAME, hasAuthError, isBlocksError } from '../errors.js';
+export type { ScopeOptions } from '../index.js';
+export { ensureApiGatewayAccount } from './apigateway-account.js';
 export { BlocksBackend, type BlocksBackendProps, type CoreBlocksBackendProps, SHARED_HANDLER_TIMEOUT_SECONDS, } from './blocks-backend.js';
-export { DEFAULT_NODE_RUNTIME } from './node-version.js';
+export { type BlocksDefaults, BlocksPresets, type BlocksThrottling, } 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, getConfigLocation } from './config-registry.js';
-export { ensureApiGatewayAccount } from './apigateway-account.js';
-export { type BlocksDefaults, type BlocksThrottling, BlocksPresets, } from './blocks-defaults.js';
+export { DEFAULT_NODE_RUNTIME } from './node-version.js';
 export { synthGuard } from './synth-guard.js';
-export type { ScopeOptions } from '../index.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 type { BlocksVpcOptions, SubnetRole, VpcContext, VpcRequirements } from './vpc-types.js';
 /**
  * Core's `create()` props: the public {@link BlocksStackProps} plus the required
  * `defaultComputeFactory`. The umbrella (`@aws-blocks/blocks`) supplies the
@@ -50,9 +55,12 @@ export declare class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     get gateway(): cdk.aws_apigateway.RestApi;
     /** The default compute's RPC endpoint URL. To be removed once consumers move to the multi-compute model. */
     get apiUrl(): string;
-    /** The default compute's handler CloudWatch log group. `bb-logger` reconfigures its retention. */
+    /** 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(): cdk.aws_logs.ILogGroup;
     private requireDefaultCompute;
+    private _vpcOptions?;
     private constructor();
     static create(scope: Construct, id: string, props: CoreBlocksStackProps): Promise<BlocksStack>;
 }
@@ -129,9 +137,9 @@ export declare class Scope extends Construct {
     /**
      * The shared handler Lambda's CloudWatch log group (the default compute's).
      * Resolves the same way as {@link handler} — via the owning
-     * BlocksStack/BlocksBackend. `bb-logger` uses this to reconfigure retention on
-     * the single, framework-owned group rather than creating a second one that
-     * would collide on the log-group name.
+     * 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(): cdk.aws_logs.ILogGroup;
     get fullId(): string;
@@ -153,4 +161,52 @@ export declare class Scope extends Construct {
     get clientMiddleware(): readonly string[];
     get devAttachments(): readonly string[];
 }
+/**
+ * A VPC-requirements provider: either the requirements directly, or a callback
+ * that returns them. Use the callback form when the value depends on `fullId`
+ * or other post-construction state — it is evaluated by the base constructor
+ * *after* `super()` runs, so `this` is fully available.
+ */
+export type VpcRequirementsProvider = VpcRequirements | (() => VpcRequirements);
+/**
+ * Constructor options for a {@link BuildingBlockScope} — the {@link ScopeOptions}
+ * every Scope takes, plus the block's VPC requirements. `vpc` is **required** so
+ * a BB author can't silently omit it; pass `{}` when the block needs nothing
+ * VPC-specific.
+ */
+export interface BuildingBlockScopeOptions extends ScopeOptions {
+    /**
+     * What this block needs from the VPC — endpoints, runtime egress, whether it
+     * requires a VPC at all. A value, or a callback (evaluated after `super()`,
+     * so it may read `this.fullId`). See {@link VpcRequirements}.
+     */
+    vpc: VpcRequirementsProvider;
+}
+/**
+ * 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 declare class BuildingBlockScope extends Scope {
+    constructor(id: string, options: BuildingBlockScopeOptions);
+}
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cdk/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cdk/index.ts"],"names":[],"mappings":"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"}

package/dist/cdk/index.js

@@ -1,24 +1,31 @@
 // 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, getConfigLocation } from './config-registry.js';
-export { ensureApiGatewayAccount } from './apigateway-account.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;
@@ -46,7 +53,9 @@ export class BlocksStack extends cdk.Stack {
     get apiUrl() {
         return this.requireDefaultCompute().apiUrl;
     }
-    /** The default compute's handler CloudWatch log group. `bb-logger` reconfigures its retention. */
+    /** 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;
     }
@@ -56,14 +65,23 @@ export class BlocksStack extends cdk.Stack {
         }
         return this._defaultCompute;
     }
+    _vpcOptions;
     constructor(scope, id, props) {
         super(scope, id, props);
         this.id = id;
         this.backendHandlerPath = props.backendHandlerPath;
-        this.defaults = props.defaults;
         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;
     }
@@ -95,6 +113,29 @@ export class BlocksStack extends cdk.Stack {
         }
         // Finalize BB config → S3 (after all BBs have registered their config)
         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;
@@ -220,9 +261,9 @@ export class Scope extends Construct {
     /**
      * The shared handler Lambda's CloudWatch log group (the default compute's).
      * Resolves the same way as {@link handler} — via the owning
-     * BlocksStack/BlocksBackend. `bb-logger` uses this to reconfigure retention on
-     * the single, framework-owned group rather than creating a second one that
-     * would collide on the log-group name.
+     * 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;
@@ -252,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
@@ -270,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] = [];
+}