@aws-blocks/core 0.3.0 → 0.5.0

package/dist/cdk/config-registry.js

@@ -3,8 +3,9 @@
 import * as cdk from 'aws-cdk-lib';
 import * as s3 from 'aws-cdk-lib/aws-s3';
 import * as s3deploy from 'aws-cdk-lib/aws-s3-deployment';
-import * as iam from 'aws-cdk-lib/aws-iam';
 const REGISTRY_KEY = Symbol.for('BLOCKS_CONFIG_REGISTRY');
+/** The object key of the config JSON under {@link getConfigLocation}'s bucket. */
+const CONFIG_KEY = 'blocks-config.json';
 /**
  * Get or create the config registry for a given stack.
  * The registry collects BB config entries (env var key → CDK token value)
@@ -34,47 +35,104 @@ export function registerConfig(scope, key, value) {
     const registry = getRegistry(stack);
     registry.entries.set(key, value);
 }
+/**
+ * Ensure the shared config bucket exists and return where the config JSON lives
+ * (`{ bucketName, key }`). The bucket is created **once per stack** (memoized on
+ * the registry) and this is idempotent — the first caller creates it, later
+ * callers get the same bucket regardless of order.
+ *
+ * Any compute that loads config at runtime (`loadConfigToProcessEnv()`) injects
+ * these two values as `BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY`. The Lambda
+ * handler gets them from {@link finalizeConfigRegistry}; other compute that runs
+ * as the shared execution role (e.g. the Agent BB's AgentCore Runtime) calls this
+ * at construction to inject them too, so it loads the same app config the handler
+ * does. IAM is not granted here — `finalizeConfigRegistry` grants read on the config
+ * object to the shared execution role, which such compute inherits.
+ *
+ * @param scope - Any construct in the stack; the bucket is created under the stack.
+ */
+export function getConfigLocation(scope) {
+    return { bucketName: ensureConfigBucket(scope).bucketName, key: CONFIG_KEY };
+}
+/**
+ * Create-or-return the shared config bucket (memoized on the per-stack registry). Created under the
+ * owning `BlocksStack`/`BlocksBackend` (`globalThis.CURRENT_BLOCKS_STACK` — the construct finalize
+ * historically used), so its logical ID is stable regardless of which caller creates it first: a
+ * co-located BB (e.g. the AgentCore Runtime, a deep construct) may be the first to call it, and a
+ * `BlocksBackend` embedded in a customer stack must keep `Blocks/BlocksConfigBucket` (no replacement).
+ * Falls back to the stack when no owner is registered (isolated unit tests). Returns a concrete
+ * `s3.Bucket` so callers don't need a non-null assertion.
+ */
+function ensureConfigBucket(scope) {
+    const stack = cdk.Stack.of(scope);
+    const registry = getRegistry(stack);
+    if (!registry.bucket) {
+        const owner = globalThis.CURRENT_BLOCKS_STACK ?? stack;
+        registry.bucket = new s3.Bucket(owner, 'BlocksConfigBucket', {
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+            autoDeleteObjects: true,
+            encryption: s3.BucketEncryption.S3_MANAGED,
+            blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+            lifecycleRules: [
+                { noncurrentVersionExpiration: cdk.Duration.days(1) },
+            ],
+        });
+    }
+    return registry.bucket;
+}
 /**
  * Finalize the config registry: create an S3 bucket, upload the config JSON,
- * set env vars on the handler, and grant read access.
+ * grant read to the shared execution role, and stamp the config coordinates
+ * (`BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY`) onto every compute.
+ *
+ * Read access is granted once to the shared role (`root.executionRole`) rather
+ * than to a single function, so every compute that assumes the role can read
+ * the object. The bucket/key coordinates can't live on a role (env vars are
+ * per-compute), so they are set on each compute via `setEnv`.
  *
  * Must be called after all BBs are constructed (i.e., after the backendCDKPath
  * import completes in BlocksStack.create() / BlocksBackend.create()).
  *
- * @param scope - The CDK construct to create resources under
- * @param handler - The Lambda function that needs to read the config
+ * @param root - The construct to create the config resources under (also used
+ *   to locate the owning stack).
+ * @param executionRole - The shared role every compute assumes; config read is
+ *   granted to it once.
+ * @param computes - The computes to stamp `BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY` on.
  */
-export function finalizeConfigRegistry(scope, handler) {
-    const stack = cdk.Stack.of(scope);
+export function finalizeConfigRegistry(root, executionRole, computes) {
+    const stack = cdk.Stack.of(root);
     const registry = getRegistry(stack);
     if (registry.finalized)
         return;
     registry.finalized = true;
-    if (registry.entries.size === 0)
+    // Nothing to do only if no config was registered AND no bucket was created (via
+    // getConfigLocation). If a co-located BB created the bucket, still upload (even an empty {}) and
+    // wire the handler so that compute's loadConfigToProcessEnv() resolves instead of 404-ing forever.
+    if (registry.entries.size === 0 && !registry.bucket)
         return;
-    const configBucket = new s3.Bucket(scope, 'BlocksConfigBucket', {
-        removalPolicy: cdk.RemovalPolicy.DESTROY,
-        autoDeleteObjects: true,
-        encryption: s3.BucketEncryption.S3_MANAGED,
-        blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
-        lifecycleRules: [
-            { noncurrentVersionExpiration: cdk.Duration.days(1) },
-        ],
-    });
-    const configKey = 'blocks-config.json';
+    // Ensure the bucket exists (a co-located BB may already have created it via getConfigLocation).
+    const configBucket = ensureConfigBucket(root);
+    const configKey = CONFIG_KEY;
     const configObject = cdk.Lazy.any({
         produce: () => Object.fromEntries(registry.entries),
     });
-    const deployment = new s3deploy.BucketDeployment(scope, 'BlocksConfigDeployment', {
+    new s3deploy.BucketDeployment(root, 'BlocksConfigDeployment', {
         sources: [s3deploy.Source.jsonData(configKey, configObject)],
         destinationBucket: configBucket,
         prune: false,
     });
-    handler.addEnvironment('BLOCKS_CONFIG_BUCKET', configBucket.bucketName);
-    handler.addEnvironment('BLOCKS_CONFIG_KEY', configKey);
-    // Scope IAM grant to the specific config key
-    handler.addToRolePolicy(new iam.PolicyStatement({
-        actions: ['s3:GetObject'],
-        resources: [`${configBucket.bucketArn}/${configKey}`],
-    }));
+    // Grant read once to the shared role (scoped to the config key), so every
+    // compute assuming the role can read it. We intentionally use `grantRead`
+    // (which also adds s3:GetBucket*/s3:List* alongside s3:GetObject*) rather
+    // than a hand-rolled GetObject-only statement: this is a dedicated,
+    // block-all-public, config-only bucket, so the broader action set carries
+    // negligible exposure, and grantRead stays correct automatically if the
+    // bucket ever moves to KMS encryption (it would add kms:Decrypt).
+    configBucket.grantRead(executionRole, configKey);
+    // Stamp the config coordinates on every compute — env vars can't live on a
+    // role, so each compute needs them to locate the object at runtime.
+    for (const compute of computes) {
+        compute.setEnv('BLOCKS_CONFIG_BUCKET', configBucket.bucketName);
+        compute.setEnv('BLOCKS_CONFIG_KEY', configKey);
+    }
 }

package/dist/cdk/config-registry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config-registry.test.d.ts.map

package/dist/cdk/config-registry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-registry.test.d.ts","sourceRoot":"","sources":["../../src/cdk/config-registry.test.ts"],"names":[],"mappings":""}

package/dist/cdk/config-registry.test.js

@@ -0,0 +1,127 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CDK tests for the config registry — specifically the getConfigLocation ↔ finalizeConfigRegistry
+ * interaction. `getConfigLocation()` creates the config bucket eagerly (so co-located compute can
+ * inject BLOCKS_CONFIG_BUCKET/KEY at construction); finalize must therefore still upload the config
+ * object + wire the computes whenever a bucket exists, even if zero entries were registered —
+ * otherwise that compute's loadConfigToProcessEnv() would 404 forever against a created-but-empty
+ * bucket.
+ */
+import assert from 'node:assert';
+import { afterEach, test } from 'node:test';
+import * as cdk from 'aws-cdk-lib';
+import { Match, Template } from 'aws-cdk-lib/assertions';
+import { Construct } from 'constructs';
+import { Compute } from './compute/compute.js';
+import { finalizeConfigRegistry, getConfigLocation, registerConfig } from './config-registry.js';
+import { DEFAULT_NODE_RUNTIME } from './node-version.js';
+// getConfigLocation reads globalThis.CURRENT_BLOCKS_STACK to place the bucket under the owning
+// stack/backend; clear it between tests so one test's owner never leaks into another.
+afterEach(() => {
+    delete globalThis.CURRENT_BLOCKS_STACK;
+});
+// A real app's compute comes from @aws-blocks/bb-lambda-compute, which core's own tests can't
+// depend on. This is the same shape: a Compute that owns a real Lambda function and injects config
+// via addEnvironment — enough for finalizeConfigRegistry to stamp BLOCKS_CONFIG_BUCKET/KEY on it.
+class TestCompute extends Compute {
+    fn;
+    constructor(scope, id) {
+        super(id, { parent: scope });
+        this.fn = new cdk.aws_lambda.Function(this, 'Handler', {
+            runtime: DEFAULT_NODE_RUNTIME,
+            handler: 'index.handler',
+            code: cdk.aws_lambda.Code.fromInline('exports.handler = async () => {};'),
+        });
+    }
+    setEnv(key, value) {
+        this.fn.addEnvironment(key, value);
+    }
+    // Observability hooks are irrelevant to config-registry tests — stub them so
+    // this test double satisfies Compute's abstract contract.
+    applyTracing() { }
+    healthWidgets() {
+        return [];
+    }
+    loggingWidgets() {
+        return [];
+    }
+    tracingWidgets() {
+        return [];
+    }
+}
+function stackWithCompute(id) {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, id);
+    const role = new cdk.aws_iam.Role(stack, 'BlocksRole', {
+        assumedBy: new cdk.aws_iam.ServicePrincipal('lambda.amazonaws.com'),
+    });
+    const compute = new TestCompute(stack, 'Compute');
+    return { stack, role, computes: [compute] };
+}
+test('finalize uploads + wires the computes even with zero entries when a bucket was created', () => {
+    const { stack, role, computes } = stackWithCompute('EmptyWithBucket');
+    // Simulate a co-located BB that creates the bucket but registers no config of its own.
+    getConfigLocation(stack);
+    finalizeConfigRegistry(stack, role, computes);
+    const t = Template.fromStack(stack);
+    assert.strictEqual(Object.keys(t.findResources('AWS::S3::Bucket')).length, 1, 'one config bucket');
+    t.resourceCountIs('Custom::CDKBucketDeployment', 1); // the (empty) blocks-config.json is uploaded
+    t.hasResourceProperties('AWS::Lambda::Function', {
+        Environment: { Variables: Match.objectLike({ BLOCKS_CONFIG_KEY: 'blocks-config.json' }) },
+    });
+    // Read is granted once to the shared role (not per-function), so every compute that assumes it
+    // — including co-located compute that never went through finalize — can read the object.
+    t.hasResourceProperties('AWS::IAM::Policy', {
+        PolicyDocument: {
+            Statement: Match.arrayWith([
+                Match.objectLike({ Action: Match.arrayWith([Match.stringLikeRegexp('^s3:GetObject')]) }),
+            ]),
+        },
+        Roles: Match.arrayWith([Match.objectLike({ Ref: Match.stringLikeRegexp('BlocksRole') })]),
+    });
+});
+test('finalize is a no-op with zero entries and no bucket', () => {
+    const { stack, role, computes } = stackWithCompute('EmptyNoBucket');
+    finalizeConfigRegistry(stack, role, computes);
+    const t = Template.fromStack(stack);
+    assert.strictEqual(Object.keys(t.findResources('AWS::S3::Bucket')).length, 0, 'no config bucket created');
+    t.resourceCountIs('Custom::CDKBucketDeployment', 0);
+});
+test('finalize uploads + wires the computes when config was registered (bucket auto-created)', () => {
+    const { stack, role, computes } = stackWithCompute('WithEntries');
+    registerConfig(stack, 'BLOCKS_SOMETHING', 'value');
+    finalizeConfigRegistry(stack, role, computes);
+    const t = Template.fromStack(stack);
+    assert.strictEqual(Object.keys(t.findResources('AWS::S3::Bucket')).length, 1, 'one config bucket');
+    t.resourceCountIs('Custom::CDKBucketDeployment', 1);
+    t.hasResourceProperties('AWS::Lambda::Function', {
+        Environment: { Variables: Match.objectLike({ BLOCKS_CONFIG_KEY: 'blocks-config.json' }) },
+    });
+});
+test('the config bucket is created under the owning stack/backend, not the (deep) caller scope', () => {
+    // Mimic a BlocksBackend embedded in a customer stack: the owner is a nested construct, and the
+    // first caller of getConfigLocation is a *deep* construct (like the AgentCore Runtime).
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'CustomerStack');
+    const owner = new Construct(stack, 'Embedded'); // stands in for the BlocksBackend construct
+    globalThis.CURRENT_BLOCKS_STACK = owner;
+    const deepScope = new Construct(new Construct(owner, 'agent'), 'runtime');
+    getConfigLocation(deepScope);
+    const t = Template.fromStack(stack);
+    const bucketIds = Object.keys(t.findResources('AWS::S3::Bucket'));
+    assert.strictEqual(bucketIds.length, 1, 'exactly one config bucket');
+    // Logical IDs encode the construct path — under the owner it's `EmbeddedBlocksConfigBucket…`,
+    // at the stack root it would be `BlocksConfigBucket…`. Pin that it follows the owner.
+    assert.ok(bucketIds[0].startsWith('Embedded'), `bucket should be nested under the owner, got ${bucketIds[0]}`);
+});
+test('getConfigLocation creates exactly one bucket across repeated calls (idempotent)', () => {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'Idempotent');
+    const a = getConfigLocation(stack);
+    const b = getConfigLocation(stack);
+    assert.strictEqual(a.key, b.key, 'same config key');
+    assert.strictEqual(a.bucketName, b.bucketName, 'same bucket');
+    const t = Template.fromStack(stack);
+    assert.strictEqual(Object.keys(t.findResources('AWS::S3::Bucket')).length, 1, 'exactly one bucket');
+});

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

@@ -0,0 +1,41 @@
+import type { Construct } from 'constructs';
+/** A Dashboard's deferred widget-body build, run once after the app is constructed. */
+type DashboardFinalizer = () => void;
+/**
+ * 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 declare function registerDashboardFinalizer(scope: Construct, finalize: DashboardFinalizer): void;
+/**
+ * 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 declare function finalizeDashboards(scope: Construct): void;
+export {};
+//# sourceMappingURL=dashboard-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-registry.d.ts","sourceRoot":"","sources":["../../src/cdk/dashboard-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C,uFAAuF;AACvF,KAAK,kBAAkB,GAAG,MAAM,IAAI,CAAC;AAgBrC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAE/F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAKzD"}

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,18 +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 } from './config-registry.js';
-export { type BlocksDefaults, 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
@@ -31,6 +37,12 @@ export interface CoreBlocksStackProps extends BlocksStackProps {
 export declare class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     readonly id: string;
     readonly backendHandlerPath: string;
+    /**
+     * 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`.
+     */
+    readonly backendModulePath: string;
     /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
     readonly executionRole: cdk.aws_iam.IRole;
     /** Infrastructure defaults for Building Blocks created under this stack. */
@@ -43,7 +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. 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>;
 }
@@ -92,6 +109,17 @@ export declare class Scope extends Construct {
      * public option to set it yet.
      */
     get compute(): Compute;
+    /**
+     * 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(): Compute;
     /**
      * The backend entry file the owning BlocksStack/BlocksBackend runs — the
      * single handler entry shared across the whole app.
@@ -106,6 +134,14 @@ export declare class Scope extends Construct {
      * as `fullId` ({@link BlocksBackend.fullId}); `BlocksStack` as `id`.
      */
     get backendStackName(): string;
+    /**
+     * 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(): cdk.aws_logs.ILogGroup;
     get fullId(): string;
     /**
      * The stack-wide infrastructure {@link BlocksDefaults} registered by
@@ -125,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":"AAKA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EACN,KAAK,WAAW,IAAI,eAAe,EACnC,KAAK,gBAAgB,EAErB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,qBAAqB,EAAuB,MAAM,sCAAsC,CAAC;AAOvG,OAAO,KAAK,EAAoB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAExE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7F,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EACN,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,8BAA8B,GAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,KAAK,cAAc,EACnB,aAAa,EACb,KAAK,gBAAgB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjG,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACzF,OAAO,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEhG;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC7D,4EAA4E;IAC5E,qBAAqB,EAAE,qBAAqB,CAAC;CAC7C;AAED,qBAAa,WAAY,SAAQ,GAAG,CAAC,KAAM,YAAW,eAAe;IACpE,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAC3C;;;;OAIG;IACH,SAAgB,iBAAiB,EAAE,MAAM,CAAC;IAC1C,yFAAyF;IACzF,SAAgB,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC;IACjD,4EAA4E;IAC5E,SAAgB,QAAQ,EAAE,cAAc,CAAC;IACzC,iGAAiG;IACjG,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,2GAA2G;IAC3G,IAAI,OAAO,IAAI,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAElD;IACD,gHAAgH;IAChH,IAAI,OAAO,IAAI,GAAG,CAAC,cAAc,CAAC,OAAO,CAExC;IACD,4GAA4G;IAC5G,IAAI,MAAM,IAAI,MAAM,CAEnB;IACD;;wEAEoE;IACpE,IAAI,eAAe,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAE5C;IAED,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,WAAW,CAAC,CAAmB;IAEvC,OAAO;WAuBM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB;CAmE7E;AAED,qBAAa,KAAM,SAAQ,SAAS;IACnC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8B;IAEnD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;gBAEP,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAQ9C;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAcnB,IAAI,OAAO,yCAEV;IAED;;;;OAIG;IACH,IAAI,aAAa,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAErC;IAED;;;;;;;;OAQG;IACH,IAAI,OAAO,IAAI,OAAO,CAYrB;IAED;;;;;;;;;OASG;IACH,IAAI,cAAc,IAAI,OAAO,CAQ5B;IAED;;;OAGG;IACH,IAAI,kBAAkB,IAAI,MAAM,CAE/B;IAED;;;;;;;OAOG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAM7B;IAED;;;;;;OAMG;IACH,IAAI,eAAe,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAE5C;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;;;;OASG;IACH,IAAI,QAAQ,IAAI,cAAc,CAwB7B;IAED,SAAS,CAAC,mBAAmB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;IAKnD,wBAAwB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACzD,qBAAqB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACtD,0BAA0B,CACzB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GACtC,IAAI;IACP,IAAI,gBAAgB,IAAI,SAAS,MAAM,EAAE,CAExC;IACD,IAAI,cAAc,IAAI,SAAS,MAAM,EAAE,CAEtC;CACD;AAED;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,eAAe,GAAG,CAAC,MAAM,eAAe,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,WAAW,yBAA0B,SAAQ,YAAY;IAC9D;;;;OAIG;IACH,GAAG,EAAE,uBAAuB,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAChC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB;CAU1D"}