@aws-blocks/core 0.3.0 → 0.5.0

package/src/cdk/blocks-defaults.ts

@@ -2,6 +2,21 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { RemovalPolicy } from 'aws-cdk-lib';
+import { RetentionDays } from 'aws-cdk-lib/aws-logs';
+import type { BlocksVpcOptions } from './vpc-types.js';
+
+/**
+ * Request-rate limits applied to an API Gateway stage. On a REST API these are
+ * requests/second; on a WebSocket API the unit is messages/second across the
+ * connection. `rateLimit` is the steady-state ceiling and `burstLimit` the
+ * token-bucket size for short spikes.
+ */
+export interface BlocksThrottling {
+	/** Steady-state request (or WebSocket message) rate ceiling, per second. */
+	rateLimit: number;
+	/** Token-bucket burst size for short spikes above `rateLimit`. */
+	burstLimit: number;
+}
 
 /**
  * Default values for every Amazon-authored Building Block created within a
@@ -47,6 +62,54 @@ export interface BlocksDefaults {
 	 * 1–35 days). Backups only have a window when on, so the two are one field.
 	 */
 	pointInTimeRecovery: boolean | { retentionDays: number };
+
+	/**
+	 * How long CloudWatch Logs keeps log events written by Blocks-managed log
+	 * groups (the core handler Lambda, migration/GSI Lambdas, hosting compute,
+	 * `bb-logger`, and API Gateway access logs) before expiring them. Without a
+	 * retention set, AWS keeps log events forever, which grows cost unbounded —
+	 * every Blocks-managed log group reads this default so retention is applied
+	 * consistently.
+	 */
+	logRetention: RetentionDays;
+
+	/**
+	 * Request-rate limits applied to every Blocks-managed API Gateway stage: the
+	 * core REST API, the SSR/hosting REST API, and the `bb-realtime` WebSocket
+	 * stage. Protects the backend from runaway clients and caps blast radius.
+	 * The sandbox preset caps tighter (200/400) than production (1000/2000) so a
+	 * disposable stack is well-protected without throttling real production
+	 * traffic. See {@link BlocksThrottling}.
+	 */
+	throttling: BlocksThrottling;
+
+	/**
+	 * Whether to emit structured JSON access logs from every Blocks-managed API
+	 * Gateway stage to a dedicated CloudWatch log group (retention follows
+	 * {@link logRetention}).
+	 *
+	 * **Off by default in both presets** — opt in with a per-stack override
+	 * (`defaults: { ...BlocksPresets.production, accessLogging: true }`). It is
+	 * off by default (rather than on for production) because enabling it
+	 * provisions the account-level API Gateway CloudWatch Logs role, which is an
+	 * account/region-level singleton: a second Blocks stack in the same
+	 * account+region that also enables access logging can repoint that role on
+	 * deploy or, on teardown, leave the survivor's access logging broken.
+	 * Enabling it is therefore safe for **one Blocks stack per region** — see
+	 * `ensureApiGatewayAccount` for the full multi-stack teardown caveat.
+	 */
+	accessLogging: boolean;
+
+	/**
+	 * Place the app's compute and VPC-resident resources in a VPC. Pass a
+	 * standard CDK VPC — Blocks handles Lambda placement, endpoint provisioning
+	 * (based on which Building Blocks are in scope), and security-group wiring.
+	 *
+	 * Omit for no VPC (the preset default — Lambda runs in the AWS-managed
+	 * network). A Building Block that can't function without a VPC causes Blocks
+	 * to derive one on demand even when this is unset.
+	 */
+	vpc?: BlocksVpcOptions;
 }
 
 /**
@@ -64,12 +127,27 @@ export const BlocksPresets = {
 		deletionProtection: false,
 		allowedOrigins: ['^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$'],
 		pointInTimeRecovery: false,
+		logRetention: RetentionDays.ONE_WEEK,
+		throttling: { rateLimit: 200, burstLimit: 400 },
+		accessLogging: false,
 	},
-	/** Durable, protected posture for permanent deployments. */
+	/**
+	 * Durable, protected posture for permanent deployments. A higher throttle
+	 * ceiling (1000/2000) than sandbox so the default doesn't 429 real
+	 * production traffic — raise it via a per-stack `throttling` override for
+	 * higher-volume APIs.
+	 */
 	production: {
 		removalPolicy: RemovalPolicy.RETAIN,
 		deletionProtection: true,
 		allowedOrigins: [],
 		pointInTimeRecovery: true,
+		logRetention: RetentionDays.ONE_YEAR,
+		throttling: { rateLimit: 1000, burstLimit: 2000 },
+		// Off by default even in production: enabling access logging mutates the
+		// account/region-level API Gateway CloudWatch role (a singleton). Opt in
+		// per stack once you've confirmed a single Blocks stack owns it in the
+		// region — see the `accessLogging` field doc.
+		accessLogging: false,
 	},
 } satisfies Record<string, BlocksDefaults>;

package/src/cdk/blocks-stack.test.ts

@@ -7,14 +7,16 @@ import { before, describe, test } from 'node:test';
 import { fileURLToPath } from 'node:url';
 import * as cdk from 'aws-cdk-lib';
 import * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import type { IWidget } from 'aws-cdk-lib/aws-cloudwatch';
 import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
 import type { Construct } from 'constructs';
 import type { ScopeParent } from '../common/index.js';
 import { BLOCKS_RPC_PREFIX } from '../constants.js';
 import { BlocksBackend } from './blocks-backend.js';
 import { Compute } from './compute/compute.js';
+import { getComputes } from './compute/compute-registry.js';
 import type { DefaultComputeFactory } from './compute/default-compute-factory.js';
-import { BlocksStack, BlocksPresets, Scope } from './index.js';
+import { BlocksPresets, BlocksStack, Scope } from './index.js';
 
 // A real app gets its default compute from @aws-blocks/bb-lambda-compute (via
 // @aws-blocks/blocks), which core's own tests can't depend on. Use an
@@ -27,14 +29,19 @@ class StubLambdaCompute extends Compute {
 	readonly fn: lambda.NodejsFunction;
 	readonly apiGateway: apigateway.RestApi;
 	readonly apiUrl: string;
+	readonly logGroup: cdk.aws_logs.LogGroup;
 
 	constructor(scope: ScopeParent, id: string) {
 		super(id, { parent: scope });
+		this.logGroup = new cdk.aws_logs.LogGroup(this, 'HandlerLogGroup', {
+			removalPolicy: cdk.RemovalPolicy.DESTROY,
+		});
 		this.fn = new lambda.NodejsFunction(this, 'Handler', {
 			entry: this.backendHandlerPath,
 			runtime: cdk.aws_lambda.Runtime.NODEJS_22_X,
 			handler: 'handler',
 			role: this.executionRole,
+			logGroup: this.logGroup,
 			environment: { BLOCKS_STACK_NAME: this.backendStackName },
 			bundling: { minify: true, esbuildArgs: { '--conditions': 'aws-runtime' } },
 		});
@@ -49,6 +56,17 @@ class StubLambdaCompute extends Compute {
 	setEnv(key: string, value: string): void {
 		this.fn.addEnvironment(key, value);
 	}
+
+	protected applyTracing(): void {}
+	protected healthWidgets(_region: string): IWidget[][] {
+		return [];
+	}
+	protected loggingWidgets(_region: string): IWidget[][] {
+		return [];
+	}
+	protected tracingWidgets(_region: string): IWidget[][] {
+		return [];
+	}
 }
 
 const stubComputeFactory: DefaultComputeFactory = (root) => new StubLambdaCompute(root as never, 'DefaultCompute');
@@ -66,9 +84,19 @@ const factoryBackendPath = join(__dirname, '__fixtures__', 'factory-backend.js')
 // Wrap create(), injecting the stub default-compute factory the way
 // @aws-blocks/blocks injects LambdaCompute — so tests don't repeat it.
 const makeStack = (scope: Construct, id: string, backendCDKPath: string) =>
-	BlocksStack.create(scope, id, { backendHandlerPath: handlerPath, backendCDKPath, defaults: BlocksPresets.production, defaultComputeFactory: stubComputeFactory });
+	BlocksStack.create(scope, id, {
+		backendHandlerPath: handlerPath,
+		backendCDKPath,
+		defaults: BlocksPresets.production,
+		defaultComputeFactory: stubComputeFactory,
+	});
 const makeBackend = (scope: Construct, id: string, backendCDKPath: string) =>
-	BlocksBackend.create(scope, id, { backendHandlerPath: handlerPath, backendCDKPath, defaults: BlocksPresets.production, defaultComputeFactory: stubComputeFactory });
+	BlocksBackend.create(scope, id, {
+		backendHandlerPath: handlerPath,
+		backendCDKPath,
+		defaults: BlocksPresets.production,
+		defaultComputeFactory: stubComputeFactory,
+	});
 
 describe('ESM cache-busting (multi-stage)', () => {
 	test('BlocksStack.create() with same backendCDKPath but different IDs produces constructs in each', async () => {
@@ -166,6 +194,25 @@ describe('root is bound to the owning stack (multi-stack synth)', () => {
 		assert.strictEqual(blockA.backendStackName, 'RootBindingA', 'blockA derives its own stack name');
 		assert.strictEqual(blockB.backendStackName, 'RootBindingB', 'blockB derives its own stack name');
 	});
+
+	test('each stack owns an isolated compute registry (no cross-stack bleed)', async () => {
+		// Computes self-register on their owning stack (keyed per stack, not a
+		// process-global list), so a multi-stack synth keeps each stack's computes
+		// separate — finalize steps for one stack never see another's compute.
+		const app = new cdk.App();
+
+		const stackA = await makeStack(app, 'ComputeRegistryA', sideEffectBackendPath);
+		const stackB = await makeStack(app, 'ComputeRegistryB', sideEffectBackendPath);
+
+		const computesA = getComputes(stackA);
+		const computesB = getComputes(stackB);
+
+		assert.strictEqual(computesA.length, 1, 'stackA registered exactly its default compute');
+		assert.strictEqual(computesB.length, 1, 'stackB registered exactly its default compute');
+		assert.strictEqual(computesA[0], stackA._defaultCompute, 'stackA lists its own default');
+		assert.strictEqual(computesB[0], stackB._defaultCompute, 'stackB lists its own default');
+		assert.notStrictEqual(computesA[0], computesB[0], 'the two stacks hold distinct computes');
+	});
 });
 
 describe('assertCdkConditionActive', () => {
@@ -178,16 +225,13 @@ describe('assertCdkConditionActive', () => {
 		try {
 			const app = new cdk.App();
 
-			await assert.rejects(
-				makeStack(app, 'MissingConditionStack', sideEffectBackendPath),
-				(err: Error) => {
-					assert.ok(
-						err.message.includes('Missing --conditions=cdk'),
-						`Expected condition error, got: ${err.message}`,
-					);
-					return true;
-				},
-			);
+			await assert.rejects(makeStack(app, 'MissingConditionStack', sideEffectBackendPath), (err: Error) => {
+				assert.ok(
+					err.message.includes('Missing --conditions=cdk'),
+					`Expected condition error, got: ${err.message}`,
+				);
+				return true;
+			});
 		} finally {
 			process.env.NODE_OPTIONS = origNodeOptions;
 			process.execArgv = origExecArgv;

package/src/cdk/compute/compute-registry.ts

@@ -0,0 +1,45 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import * as cdk from 'aws-cdk-lib';
+import type { Construct } from 'constructs';
+import type { Compute } from './compute.js';
+
+const REGISTRY_KEY = Symbol.for('BLOCKS_COMPUTE_REGISTRY');
+
+/**
+ * Get or create the compute list for a given stack. The list is stored on the
+ * stack object (keyed by a Symbol), so each stack in a multi-stack synth gets
+ * its own — a compute never leaks into another stack's list. Mirrors the config
+ * registry (`config-registry.ts`), which scopes its state the same way.
+ */
+function getRegistry(stack: cdk.Stack): Compute[] {
+	let list = (stack as any)[REGISTRY_KEY] as Compute[] | undefined;
+	if (!list) {
+		list = [];
+		(stack as any)[REGISTRY_KEY] = list;
+	}
+	return list;
+}
+
+/**
+ * Register a compute on its owning stack. Called from the {@link Compute} base
+ * constructor, so every compute self-registers the moment it is constructed —
+ * the finalize steps then enumerate them without a separate discovery pass
+ * (mirrors how `registerConfig` accumulates config during the backend import).
+ *
+ * @param compute - The compute to register (used to locate its stack).
+ */
+export function registerCompute(compute: Compute): void {
+	getRegistry(cdk.Stack.of(compute)).push(compute);
+}
+
+/**
+ * The computes registered on the stack that owns `scope`, in construction
+ * order. Returns an empty array before any compute is constructed.
+ *
+ * @param scope - Any construct in the stack (used to locate the stack).
+ */
+export function getComputes(scope: Construct): readonly Compute[] {
+	return getRegistry(cdk.Stack.of(scope));
+}

package/src/cdk/compute/compute.ts

@@ -1,7 +1,10 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import type { IWidget } from 'aws-cdk-lib/aws-cloudwatch';
+import type { ScopeOptions } from '../../common/index.js';
 import { Scope } from '../index.js';
+import { registerCompute } from './compute-registry.js';
 
 /**
  * Base class for a Blocks *compute* — a runtime that executes handler code
@@ -14,11 +17,17 @@ import { Scope } from '../index.js';
  * compute in an app runs the same backend and agrees on the resource-name
  * namespace.
  *
+ * **Observability is compute-owned at deploy time.** Logging is always on (a
+ * compute owns its log group and captures stdout; retention is a compute-level
+ * setting), so there is no "enable logging" — logs always exist. Tracing, by
+ * contrast, provisions real infrastructure (X-Ray) and has cost, so it is
+ * enabled explicitly via {@link enableTracing} — which the framework calls on
+ * every compute when the app contains a `Tracer` (presence-gated).
+ *
  * The abstract base lives in core (a framework primitive); concrete computes
  * live in their own packages (e.g. `LambdaCompute` in `@aws-blocks/bb-lambda-compute`).
  *
- * @internal Not exported from the package's public entry points. Customers
- * cannot instantiate a compute until the customer-facing surface exists.
+ * @internal Not exported from the package's public entry points.
  */
 export abstract class Compute extends Scope {
 	/**
@@ -28,10 +37,113 @@ export abstract class Compute extends Scope {
 	 */
 	readonly namespaces: string[] = [];
 
+	/**
+	 * Whether tracing has been enabled on this compute — flipped by
+	 * {@link enableTracing}. Private so it can't be set independently of the
+	 * infra; read internally by {@link dashboardSection} to decide whether to
+	 * render the traces section.
+	 */
+	private tracerEnabled = false;
+
+	/** Read-only view of {@link tracerEnabled} for subclasses (e.g. to guard
+	 * their `tracingWidgets` builder). Subclasses can read but not set it. */
+	protected get isTracerEnabled(): boolean {
+		return this.tracerEnabled;
+	}
+
+	constructor(id: string, options?: ScopeOptions) {
+		super(id, options);
+		// Self-register on the owning stack so finalize steps (tracing, routing,
+		// dashboards) can enumerate every compute without a separate discovery
+		// pass. Scoped per stack, so a multi-stack synth keeps lists isolated.
+		registerCompute(this);
+	}
+
 	/**
 	 * Inject a runtime configuration value (an environment variable) into this
 	 * compute. The framework calls this instead of `handler.addEnvironment()`
 	 * directly so config targets the right compute.
 	 */
 	abstract setEnv(key: string, value: string): void;
+
+	/**
+	 * Enable distributed tracing on this compute: mark it traced (so the Dashboard
+	 * renders its traces section) and turn on the compute's active tracing via
+	 * {@link applyTracing}. Idempotent — the framework calls this on **every**
+	 * compute when the app contains a `Tracer` (tracing is presence-gated, not
+	 * per-compute), so calling it more than once is a no-op.
+	 */
+	enableTracing(): void {
+		if (this.tracerEnabled) return;
+		this.tracerEnabled = true;
+		this.applyTracing();
+	}
+
+	/**
+	 * Turn on this compute's active tracing (e.g. X-Ray) and grant its role the
+	 * permission to publish trace segments. Called by {@link enableTracing};
+	 * `protected` so tracing can't be turned on without marking the compute
+	 * traced.
+	 */
+	protected abstract applyTracing(): void;
+
+	/**
+	 * Build this compute's CloudWatch Dashboard section: health widgets and log
+	 * widgets **always** (logs are always captured for a compute), plus trace
+	 * widgets **only when** tracing is enabled on this compute (via
+	 * {@link enableTracing}).
+	 *
+	 * This is the single public entry the Dashboard Building Block uses; the
+	 * per-kind builders below are `protected`. Whether the logs / traces sections
+	 * are actually shown is a display choice the Dashboard makes on top (its
+	 * `logs` / `traces` options) — this returns what the compute *has*.
+	 *
+	 * @param region - AWS region the widgets query metrics in.
+	 */
+	dashboardSection(region: string): ComputeDashboardSection {
+		return {
+			// The scope id (e.g. 'DefaultCompute', 'api') — short and readable for a
+			// section header, and distinct per compute within a stack.
+			label: this.id,
+			health: this.healthWidgets(region),
+			logging: this.loggingWidgets(region),
+			tracing: this.tracerEnabled ? this.tracingWidgets(region) : undefined,
+		};
+	}
+
+	/**
+	 * Build this compute's health widget rows. Implemented by a concrete compute;
+	 * obtained only via {@link dashboardSection}.
+	 */
+	protected abstract healthWidgets(region: string): IWidget[][];
+
+	/**
+	 * Build this compute's **log** widget rows for its own log group. Logs always
+	 * exist, so this is always available; the Dashboard's `logs` option decides
+	 * whether to render it.
+	 */
+	protected abstract loggingWidgets(region: string): IWidget[][];
+
+	/**
+	 * Build this compute's **trace** widget rows. Gated behind
+	 * {@link dashboardSection} so it is only used when tracing is enabled.
+	 */
+	protected abstract tracingWidgets(region: string): IWidget[][];
+}
+
+/**
+ * A compute's self-reported CloudWatch Dashboard section. `health` and `logging`
+ * are always present; `tracing` is populated only when tracing is enabled on the
+ * compute. (The Dashboard may still hide `logging` / `tracing` via its display
+ * options.)
+ */
+export interface ComputeDashboardSection {
+	/** Display label used as the compute's group header. */
+	label: string;
+	/** Health widget rows — always present. */
+	health: IWidget[][];
+	/** Log widget rows — always present (logs are always captured). */
+	logging?: IWidget[][];
+	/** Trace widget rows — present only when tracing is enabled. */
+	tracing?: IWidget[][];
 }

package/src/cdk/compute/default-compute-factory.ts

@@ -20,6 +20,7 @@ export interface LambdaShapedCompute extends Compute {
 	readonly fn: cdk.aws_lambda_nodejs.NodejsFunction;
 	readonly apiGateway: cdk.aws_apigateway.RestApi;
 	readonly apiUrl: string;
+	readonly logGroup: cdk.aws_logs.ILogGroup;
 }
 
 /**

package/src/cdk/config-registry.test.ts

@@ -0,0 +1,149 @@
+// 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 type { IWidget } from 'aws-cdk-lib/aws-cloudwatch';
+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 as any).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 {
+	readonly fn: cdk.aws_lambda.Function;
+
+	constructor(scope: Construct, id: string) {
+		super(id, { parent: scope as never });
+		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: string, value: string): void {
+		this.fn.addEnvironment(key, value);
+	}
+
+	// Observability hooks are irrelevant to config-registry tests — stub them so
+	// this test double satisfies Compute's abstract contract.
+	protected applyTracing(): void {}
+	protected healthWidgets(): IWidget[][] {
+		return [];
+	}
+	protected loggingWidgets(): IWidget[][] {
+		return [];
+	}
+	protected tracingWidgets(): IWidget[][] {
+		return [];
+	}
+}
+
+function stackWithCompute(id: string): {
+	stack: cdk.Stack;
+	role: cdk.aws_iam.Role;
+	computes: readonly Compute[];
+} {
+	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 as any).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');
+});