@aws-blocks/core 0.2.0 → 0.4.0

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

@@ -1,17 +1,67 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { test, describe, before } from 'node:test';
 import assert from 'node:assert';
-import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+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 * 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';
 
+// 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
+// equivalent inline stub: a Compute that owns a NodejsFunction + API Gateway,
+// so create() can build the default and the handler/gateway/apiUrl accessors
+// and synth-shape assertions have something real to resolve to. It is passed to
+// each create() via the internal `defaultComputeFactory` option (see makeStack /
+// makeBackend), exactly as @aws-blocks/blocks injects LambdaCompute.
+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' } },
+		});
+		this.apiGateway = new apigateway.RestApi(this, 'API', { restApiName: 'Blocks API' });
+		this.apiGateway.root.addProxy({
+			defaultIntegration: new apigateway.LambdaIntegration(this.fn),
+			anyMethod: true,
+		});
+		this.apiUrl = `${this.apiGateway.url}${BLOCKS_RPC_PREFIX.slice(1)}`;
+	}
+
+	setEnv(key: string, value: string): void {
+		this.fn.addEnvironment(key, value);
+	}
+}
+
+const stubComputeFactory: DefaultComputeFactory = (root) => new StubLambdaCompute(root as never, 'DefaultCompute');
+
 // Simulate the CDK condition being active (tests import CDK files directly)
 before(() => {
-  process.env.NODE_OPTIONS = (process.env.NODE_OPTIONS ?? '') + ' --conditions=cdk';
+	process.env.NODE_OPTIONS = (process.env.NODE_OPTIONS ?? '') + ' --conditions=cdk';
 });
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -19,135 +69,153 @@ const handlerPath = join(__dirname, '__fixtures__', 'handler.js');
 const sideEffectBackendPath = join(__dirname, '__fixtures__', 'side-effect-backend.js');
 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 });
+const makeBackend = (scope: Construct, id: string, backendCDKPath: string) =>
+	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 () => {
-    const app = new cdk.App();
-
-    const stack1 = await BlocksStack.create(app, 'PipelineStage1', {
-      backendHandlerPath: handlerPath,
-      backendCDKPath: sideEffectBackendPath,
-      defaults: BlocksPresets.production,
-    });
-
-    const stack2 = await BlocksStack.create(app, 'PipelineStage2', {
-      backendHandlerPath: handlerPath,
-      backendCDKPath: sideEffectBackendPath,
-      defaults: BlocksPresets.production,
-    });
-
-    const findMarker = (scope: any) => scope.node.tryFindChild('SideEffectMarker');
-
-    assert.ok(
-      findMarker(stack1),
-      'First stack should have SideEffectMarker from module side effect',
-    );
-    assert.ok(
-      findMarker(stack2),
-      'Second stack should have SideEffectMarker from re-executed module (cache busted)',
-    );
-  });
+	test('BlocksStack.create() with same backendCDKPath but different IDs produces constructs in each', async () => {
+		const app = new cdk.App();
+
+		const stack1 = await makeStack(app, 'PipelineStage1', sideEffectBackendPath);
+
+		const stack2 = await makeStack(app, 'PipelineStage2', sideEffectBackendPath);
+
+		const findMarker = (scope: any) => scope.node.tryFindChild('SideEffectMarker');
+
+		assert.ok(findMarker(stack1), 'First stack should have SideEffectMarker from module side effect');
+		assert.ok(
+			findMarker(stack2),
+			'Second stack should have SideEffectMarker from re-executed module (cache busted)',
+		);
+	});
 });
 
 describe('factory function support', () => {
-  test('BlocksStack.create() calls default export function with the stack instance', async () => {
-    const app = new cdk.App();
-
-    const stack = await BlocksStack.create(app, 'FactoryBlocksStack', {
-      backendHandlerPath: handlerPath,
-      backendCDKPath: factoryBackendPath,
-      defaults: BlocksPresets.production,
-    });
-
-    const marker = stack.node.tryFindChild('FactoryMarker');
-    assert.ok(marker, 'Factory function should have created FactoryMarker on the stack');
-  });
+	test('BlocksStack.create() calls default export function with the stack instance', async () => {
+		const app = new cdk.App();
+
+		const stack = await makeStack(app, 'FactoryBlocksStack', factoryBackendPath);
+
+		const marker = stack.node.tryFindChild('FactoryMarker');
+		assert.ok(marker, 'Factory function should have created FactoryMarker on the stack');
+	});
 });
 
 describe('legacy side-effect mode (no default export)', () => {
-  test('module with only side effects still registers constructs via globalThis', async () => {
-    const app = new cdk.App();
-    const stack = new cdk.Stack(app, 'LegacyTestStack');
-
-    const backend = await BlocksBackend.create(stack, 'LegacyStage', {
-      backendHandlerPath: handlerPath,
-      backendCDKPath: sideEffectBackendPath,
-      defaults: BlocksPresets.production,
-    });
-
-    const marker = backend.node.tryFindChild('SideEffectMarker');
-    assert.ok(
-      marker,
-      'Side-effect-only module should register construct via globalThis.CURRENT_BLOCKS_STACK',
-    );
-  });
+	test('module with only side effects still registers constructs via globalThis', async () => {
+		const app = new cdk.App();
+		const stack = new cdk.Stack(app, 'LegacyTestStack');
+
+		const backend = await makeBackend(stack, 'LegacyStage', sideEffectBackendPath);
+
+		const marker = backend.node.tryFindChild('SideEffectMarker');
+		assert.ok(marker, 'Side-effect-only module should register construct via globalThis.CURRENT_BLOCKS_STACK');
+	});
 });
 
 describe('shared execution role (BlocksStack)', () => {
-  // The role synth shape and the Scope.executionRole tree-walk are shared code
-  // (setupBlocksInfra + the getter), covered in blocks-backend.test.ts. The only
-  // BlocksStack-specific behavior is that its own constructor wires
-  // executionRole — a separate code path from BlocksBackend's constructor.
-  test('BlocksStack wires executionRole via its constructor', async () => {
-    const app = new cdk.App();
-    const stack = await BlocksStack.create(app, 'StackRoleStack', {
-      backendHandlerPath: handlerPath,
-      backendCDKPath: sideEffectBackendPath,
-      defaults: BlocksPresets.production,
-    });
-
-    assert.ok(stack.executionRole, 'BlocksStack should expose a populated .executionRole');
-  });
+	// The role synth shape and the Scope.executionRole tree-walk are shared code
+	// (setupBlocksInfra + the getter), covered in blocks-backend.test.ts. The only
+	// BlocksStack-specific behavior is that its own constructor wires
+	// executionRole — a separate code path from BlocksBackend's constructor.
+	test('BlocksStack wires executionRole via its constructor', async () => {
+		const app = new cdk.App();
+		const stack = await makeStack(app, 'StackRoleStack', sideEffectBackendPath);
+
+		assert.ok(stack.executionRole, 'BlocksStack should expose a populated .executionRole');
+	});
 });
 
 describe('executionRole globalThis fallback', () => {
-  test('resolves via globalThis.CURRENT_BLOCKS_STACK when no owner is in the tree', async () => {
-    const app = new cdk.App();
-    const stack = await BlocksStack.create(app, 'FallbackStack', {
-      backendHandlerPath: handlerPath,
-      backendCDKPath: sideEffectBackendPath,
-      defaults: BlocksPresets.production,
-    });
-
-    // A Scope whose construct-tree ancestry has no BlocksStack/BlocksBackend
-    // (parented under a plain cdk.Stack) exhausts the tree-walk and falls back
-    // to globalThis.CURRENT_BLOCKS_STACK. The `as any` is test plumbing — a
-    // plain Stack isn't a ScopeParent, but it IS a valid Construct parent.
-    const plainStack = new cdk.Stack(app, 'PlainStack');
-    (globalThis as any).CURRENT_BLOCKS_STACK = stack;
-    const orphan = new Scope('orphan', { parent: plainStack as any });
-
-    assert.strictEqual(
-      orphan.executionRole,
-      stack.executionRole,
-      'fallback resolves to the ambient stack role',
-    );
-  });
+	test('resolves via globalThis.CURRENT_BLOCKS_STACK when no owner is in the tree', async () => {
+		const app = new cdk.App();
+		const stack = await makeStack(app, 'FallbackStack', sideEffectBackendPath);
+
+		// A Scope whose construct-tree ancestry has no BlocksStack/BlocksBackend
+		// (parented under a plain cdk.Stack) exhausts the tree-walk and falls back
+		// to globalThis.CURRENT_BLOCKS_STACK. The `as any` is test plumbing — a
+		// plain Stack isn't a ScopeParent, but it IS a valid Construct parent.
+		const plainStack = new cdk.Stack(app, 'PlainStack');
+		(globalThis as any).CURRENT_BLOCKS_STACK = stack;
+		const orphan = new Scope('orphan', { parent: plainStack as any });
+
+		assert.strictEqual(orphan.executionRole, stack.executionRole, 'fallback resolves to the ambient stack role');
+	});
+});
+
+describe('root is bound to the owning stack (multi-stack synth)', () => {
+	test('a block under each of two stacks resolves its OWN stack, not the last globalThis', async () => {
+		// `root` is resolved once at Scope construction (not re-walked per getter),
+		// and `create()` mutates globalThis.CURRENT_BLOCKS_STACK for each stack it
+		// builds. With two stacks in one synth, a block constructed under the first
+		// must stay bound to the first even after the second stack is created and
+		// overwrites globalThis — otherwise its root-derived accessors (handler,
+		// executionRole, backendStackName) would silently point at the wrong stack.
+		const app = new cdk.App();
+
+		const stackA = await makeStack(app, 'RootBindingA', sideEffectBackendPath);
+		// A block explicitly parented under stackA (construct-tree walk resolves
+		// stackA regardless of the ambient globalThis).
+		const blockA = new Scope('blockA', { parent: stackA });
+
+		// Building the second stack overwrites globalThis.CURRENT_BLOCKS_STACK.
+		const stackB = await makeStack(app, 'RootBindingB', sideEffectBackendPath);
+		const blockB = new Scope('blockB', { parent: stackB });
+
+		assert.strictEqual(blockA.executionRole, stackA.executionRole, 'blockA stays bound to stackA');
+		assert.strictEqual(blockB.executionRole, stackB.executionRole, 'blockB binds to stackB');
+		assert.notStrictEqual(stackA.executionRole, stackB.executionRole, 'the two stacks have distinct roles');
+		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', () => {
-  test('BlocksStack.create() throws when --conditions=cdk is missing', async () => {
-    const origNodeOptions = process.env.NODE_OPTIONS;
-    const origExecArgv = process.execArgv;
-    process.env.NODE_OPTIONS = '';
-    process.execArgv = [];
-
-    try {
-      const app = new cdk.App();
-
-      await assert.rejects(
-        BlocksStack.create(app, 'MissingConditionStack', {
-          backendHandlerPath: handlerPath,
-          backendCDKPath: sideEffectBackendPath,
-          defaults: BlocksPresets.production,
-        }),
-        (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;
-    }
-  });
+	test('BlocksStack.create() throws when --conditions=cdk is missing', async () => {
+		const origNodeOptions = process.env.NODE_OPTIONS;
+		const origExecArgv = process.execArgv;
+		process.env.NODE_OPTIONS = '';
+		process.execArgv = [];
+
+		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;
+				},
+			);
+		} 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,9 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+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
@@ -28,6 +30,14 @@ export abstract class Compute extends Scope {
 	 */
 	readonly namespaces: string[] = [];
 
+	constructor(id: string, options?: ScopeOptions) {
+		super(id, options);
+		// Self-register on the owning stack so finalize steps (config, 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()`

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

@@ -0,0 +1,38 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type * as cdk from 'aws-cdk-lib';
+import type { Compute } from './compute.js';
+import type { BlocksStack } from '../index.js';
+import type { BlocksBackend } from '../blocks-backend.js';
+
+/**
+ * Lambda-shaped surface of the default compute that the legacy
+ * `handler` / `gateway` / `apiUrl` accessors on BlocksStack/BlocksBackend read.
+ * The default compute (`LambdaCompute` from `@aws-blocks/bb-lambda-compute`)
+ * satisfies this structurally, so core exposes those accessors without
+ * importing the concrete class. To be removed with those accessors once
+ * consumers move to the multi-compute model.
+ *
+ * @internal
+ */
+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;
+}
+
+/**
+ * Builds the default {@link Compute} for a stack/backend. `create()` reads it
+ * from its props (`CoreBlocksStackProps.defaultComputeFactory`) and calls it to
+ * build the default without importing a concrete compute class — the factory is
+ * supplied by whoever owns both core and a concrete compute package (the
+ * umbrella `@aws-blocks/blocks`, which injects `LambdaCompute`). It lives on
+ * `CoreBlocksStackProps`/`CoreBlocksBackendProps`, which the umbrella derives
+ * from the customer-facing props, so it is absent from `BlocksStackProps` and
+ * customers cannot set it.
+ *
+ * @internal
+ */
+export type DefaultComputeFactory = (root: BlocksStack | BlocksBackend) => Compute;

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

@@ -0,0 +1,135 @@
+// 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 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);
+	}
+}
+
+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');
+});