@aws-blocks/core 0.1.18 → 0.3.0

package/src/cdk/blocks-backend.ts

@@ -2,17 +2,17 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import * as cdk from 'aws-cdk-lib';
-import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
-import * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import type * as apigateway from 'aws-cdk-lib/aws-apigateway';
 import * as iam from 'aws-cdk-lib/aws-iam';
 import { CfnGroup } from 'aws-cdk-lib/aws-resourcegroups';
 import { Construct } from 'constructs';
 import { pathToFileURL } from 'node:url';
-import { DEFAULT_NODE_RUNTIME } from './node-version.js';
 import { addBlocksStackMetadata } from './stack-metadata.js';
 import { finalizeConfigRegistry, registerConfig } from './config-registry.js';
-import { BLOCKS_NAMESPACE, BLOCKS_RPC_PREFIX } from '../constants.js';
+import type { BlocksDefaults } from './blocks-defaults.js';
 import { registerBuiltinRoutes } from '../builtin-routes.js';
+import type { Compute } from './compute/compute.js';
+import type { DefaultComputeFactory, LambdaShapedCompute } from './compute/default-compute-factory.js';
 
 /**
  * Validate that the Node.js process was started with `--conditions=cdk`.
@@ -42,21 +42,68 @@ export function assertCdkConditionActive(): void {
   }
 }
 
+/**
+ * Timeout of the shared Blocks handler Lambda, and therefore the ceiling on a
+ * single invocation. Exported because resources that feed the handler have to
+ * size their own timeouts against it (e.g. an SQS queue's visibility timeout).
+ */
+export const SHARED_HANDLER_TIMEOUT_SECONDS = 60 * 15;
+
 export interface BlocksBackendProps {
   backendHandlerPath: string;
   backendCDKPath: string;
+  /**
+   * Stack-wide infrastructure defaults applied to every Building Block (removal
+   * policy, deletion protection, …). See {@link BlocksDefaults}. Start from
+   * `BlocksPresets.sandbox` or `BlocksPresets.production` and override
+   * individual fields as needed. A per-block option always wins over the
+   * corresponding stack default.
+   */
+  defaults: BlocksDefaults;
+}
+
+/**
+ * Core's `create()` props: the public {@link BlocksBackendProps} plus the
+ * required `defaultComputeFactory`, spread on by the umbrella (`@aws-blocks/blocks`).
+ * Customers use {@link BlocksBackendProps} and never set the factory.
+ *
+ * @internal
+ */
+export interface CoreBlocksBackendProps extends BlocksBackendProps {
+  /** Builds the backend's default compute. Injected by `@aws-blocks/blocks`. */
+  defaultComputeFactory: DefaultComputeFactory;
 }
 
-/** Shared infra setup — creates Lambda + API Gateway on the given scope. */
+/**
+ * Shared infra setup — provisions the stack-level resources that are NOT owned
+ * by a compute: the shared execution role, resource groups, and console-redirect
+ * routes.
+ */
 export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id?: string) {
-  // ── Shared execution role ──────────────────────────────────────────────
+  // Fail fast with an actionable message at the create() call site if `defaults`
+  // is missing (e.g. a plain-JS caller, `as any`, or a dynamically-built props
+  // object) — otherwise the first Building Block to read `scope.defaults` throws
+  // a cryptic `Cannot read properties of undefined (reading 'removalPolicy')`.
+  if (!props.defaults) {
+    throw new Error(
+      'BlocksStack/BlocksBackend requires a `defaults` field. Pass a posture from ' +
+      '`@aws-blocks/core/cdk` — typically `defaults: sandboxMode ? BlocksPresets.sandbox : BlocksPresets.production`.',
+    );
+  }
+
+  // ── Shared execution role ───────────────────────────────────────────────
   // A single IAM role that every Building Block grants to. Provisioned here so
   // it exists before the backend module is imported (Building Blocks reach it
   // via `scope.executionRole`). Block grants sit on the role's default (inline)
-  // policy, exactly as they did on the auto-generated NodejsFunction role.
+  // policy. AWSLambdaBasicExecutionRole is attached so compute functions retain
+  // CloudWatch Logs permissions.
   //
-  // AWSLambdaBasicExecutionRole is attached explicitly because the auto-role
-  // included it by default — omitting it would silently break CloudWatch Logs.
+  // INVARIANT: this must be a mutable, framework-owned `iam.Role` — never an
+  // imported role (`Role.fromRoleArn`/`fromRoleName`), which is immutable by
+  // default. On an immutable role, every Building Block's `grant*()` /
+  // `addToPrincipalPolicy()` silently becomes a no-op (returns false, no error),
+  // so permissions would quietly vanish. If a bring-your-own-role option is ever
+  // added, it must resolve to a mutable role (`{ mutable: true }`).
   const executionRole = new iam.Role(scope, 'BlocksRole', {
     // CompositePrincipal (rather than a bare ServicePrincipal) so additional
     // compute types can assume this same shared role as they are introduced
@@ -67,60 +114,7 @@ export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id
     ],
   });
 
-  const handler = new lambda.NodejsFunction(scope, 'Handler', {
-    entry: props.backendHandlerPath,
-    runtime: DEFAULT_NODE_RUNTIME,
-    handler: 'handler',
-    role: executionRole,
-    memorySize: 2048,
-    timeout: cdk.Duration.seconds(60 * 15),
-    environment: {
-      NODE_ENV: 'production',
-      /**
-       * BLOCKS_STACK_NAME is used at runtime to derive physical resource names
-       * (DynamoDB table names, env var prefixes). It must match the CDK-time
-       * fullId of the BlocksStack/BlocksBackend so resource lookups work correctly.
-       *
-       * For BlocksStack: this equals the stack name (id).
-       * For BlocksBackend: the caller overrides this after construction to include
-       * the parent stack name for deployment uniqueness.
-       */
-      BLOCKS_STACK_NAME: id ?? cdk.Stack.of(scope).stackName,
-    },
-    bundling: {
-      minify: true,
-      esbuildArgs: { '--conditions': 'aws-runtime' },
-    },
-  });
-
-  // In sandbox mode, allow localhost origins so the local dev frontend can
-  // reach the deployed Lambda API via CORS.
-  const isSandbox =
-    scope.node.tryGetContext('sandboxMode') === 'true' ||
-    scope.node.tryGetContext('sandboxMode') === true;
-  if (isSandbox) {
-    handler.addEnvironment('CORS_ALLOWED_ORIGINS', '^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$');
-  }
-
-  const api = new apigateway.RestApi(scope, 'API', {
-    restApiName: 'Blocks API',
-    deployOptions: { cachingEnabled: false },
-  });
-
-  const integration = new apigateway.LambdaIntegration(handler);
-
-  // Build the nested resource tree for /aws-blocks/api.
-  // Intermediate resource gets a proxy so sub-paths (RawRoutes) still reach Lambda.
-  const awsBlocksResource = api.root.addResource(BLOCKS_NAMESPACE.slice(1));
-  awsBlocksResource.addProxy({ defaultIntegration: integration, anyMethod: true });
-  
-  const apiResource = awsBlocksResource.addResource('api');
-  apiResource.addMethod('POST', integration);
-  apiResource.addMethod('OPTIONS', integration);
-
-  api.root.addProxy({ defaultIntegration: integration, anyMethod: true });
-
-  // ── Resource Groups ────────────────────────────────────────────────────
+  // ── Resource Groups ───────────────────────────────────────────────────
   let rootStack = cdk.Stack.of(scope);
   while (rootStack.nestedStackParent) rootStack = rootStack.nestedStackParent;
   const groupPrefix = (id && id !== rootStack.stackName) ? `${rootStack.stackName}-${id}` : rootStack.stackName;
@@ -156,7 +150,7 @@ export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id
     },
   });
 
-  // ── Console redirect routes ────────────────────────────────────────────
+  // ── Console redirect routes ───────────────────────────────────────────
   const region = cdk.Fn.ref('AWS::Region');
   const resourcesUrl = cdk.Fn.join('', [
     'https://', region, '.console.aws.amazon.com/resource-groups/group/',
@@ -172,7 +166,7 @@ export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id
 
   registerBuiltinRoutes();
 
-  return { handler, gateway: api, apiUrl: `${api.url}${BLOCKS_RPC_PREFIX.slice(1)}`, executionRole };
+  return { executionRole };
 }
 
 /**
@@ -193,12 +187,33 @@ export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id
  * ```
  */
 export class BlocksBackend extends Construct {
-  public readonly apiUrl: string;
-  public readonly gateway: apigateway.RestApi;
-  public readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
   public readonly backendHandlerPath: string;
   /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
   public readonly executionRole: iam.IRole;
+  /** Infrastructure defaults for Building Blocks created under this backend. */
+  public readonly defaults: BlocksDefaults;
+  /** The default compute (owns the Lambda function + API Gateway); set in `create()`. @internal */
+  _defaultCompute?: Compute;
+
+  /** The default compute's Lambda function. To be removed once consumers move to the multi-compute model. */
+  get handler(): cdk.aws_lambda_nodejs.NodejsFunction {
+    return this.requireDefaultCompute().fn;
+  }
+  /** The default compute's API Gateway REST API. To be removed once consumers move to the multi-compute model. */
+  get gateway(): apigateway.RestApi {
+    return this.requireDefaultCompute().apiGateway;
+  }
+  /** The default compute's RPC endpoint URL. To be removed once consumers move to the multi-compute model. */
+  get apiUrl(): string {
+    return this.requireDefaultCompute().apiUrl;
+  }
+
+  private requireDefaultCompute(): LambdaShapedCompute {
+    if (!this._defaultCompute) {
+      throw new Error('Blocks backend not fully initialized — access .handler/.gateway/.apiUrl after BlocksBackend.create() resolves.');
+    }
+    return this._defaultCompute as LambdaShapedCompute;
+  }
 
   /**
    * The fullId used by child Scopes to compute their env var names,
@@ -239,21 +254,27 @@ export class BlocksBackend extends Construct {
     // Expose self to Building Blocks at CDK time
     (globalThis as any).CURRENT_BLOCKS_STACK = this;
 
+    // Store defaults on the backend (not the stack) so several BlocksBackends
+    // in one stack each keep their own posture; Building Blocks resolve them by
+    // walking up to their owning backend (see Scope.defaults).
+    this.defaults = props.defaults;
+
     const infra = setupBlocksInfra(this, props, id);
-    this.handler = infra.handler;
-    this.gateway = infra.gateway;
-    this.apiUrl = infra.apiUrl;
     this.executionRole = infra.executionRole;
-
-    // Override BLOCKS_STACK_NAME to include the parent stack name so runtime
-    // resource lookups (DynamoDB table names) match the CDK-time fullId
-    // and are unique per deployment.
-    this.handler.addEnvironment('BLOCKS_STACK_NAME', this.fullId);
+    // The default compute (and thus handler/gateway) is created in create(),
+    // after construction — it derives BLOCKS_STACK_NAME from this.fullId.
   }
 
-  static async create(scope: Construct, id: string, props: BlocksBackendProps) {
+  static async create(scope: Construct, id: string, props: CoreBlocksBackendProps) {
     assertCdkConditionActive();
     const backend = new BlocksBackend(scope, id, props);
+    // Create the default compute before importing the backend: it OWNS the
+    // Lambda function + API Gateway (which back .handler/.gateway/.apiUrl), and
+    // a block reading `this.compute` in its constructor (during that import)
+    // must resolve to it. The factory is supplied by the umbrella
+    // @aws-blocks/blocks (which injects LambdaCompute) via props, so core never
+    // imports the concrete compute class.
+    backend._defaultCompute = props.defaultComputeFactory(backend);
     // file:// URL (not a raw path) so the cache-busting query works on Windows,
     // where an absolute path like `D:\...` is rejected as URL scheme `d:`.
     const backendUrl = pathToFileURL(props.backendCDKPath);

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

@@ -0,0 +1,27 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * BlocksPresets carry the expected posture. Resolution/anchoring (a block
+ * reading its owning backend's defaults, and two backends in one stack keeping
+ * separate postures) is covered in blocks-backend.test.ts, which has the
+ * fixtures to construct real backends.
+ */
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import { RemovalPolicy } from 'aws-cdk-lib';
+import { BlocksPresets } from './blocks-defaults.js';
+
+describe('BlocksPresets', () => {
+	test('sandbox is disposable: DESTROY + deletion protection off + no PITR', () => {
+		assert.strictEqual(BlocksPresets.sandbox.removalPolicy, RemovalPolicy.DESTROY);
+		assert.strictEqual(BlocksPresets.sandbox.deletionProtection, false);
+		assert.strictEqual(BlocksPresets.sandbox.pointInTimeRecovery, false);
+	});
+
+	test('production is durable: RETAIN + deletion protection on + PITR on', () => {
+		assert.strictEqual(BlocksPresets.production.removalPolicy, RemovalPolicy.RETAIN);
+		assert.strictEqual(BlocksPresets.production.deletionProtection, true);
+		assert.strictEqual(BlocksPresets.production.pointInTimeRecovery, true);
+	});
+});

package/src/cdk/blocks-defaults.ts

@@ -0,0 +1,75 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { RemovalPolicy } from 'aws-cdk-lib';
+
+/**
+ * Default values for every Amazon-authored Building Block created within a
+ * `BlocksStack` or `BlocksBackend`. A per-block option always overrides the
+ * corresponding default (`option ?? scope.defaults.field`).
+ *
+ * Start from {@link BlocksPresets} and override individual fields as needed.
+ */
+export interface BlocksDefaults {
+	/**
+	 * What happens to a stateful resource (table, bucket, user pool) when the
+	 * stack is deleted, via CDK/CloudFormation: `RETAIN` keeps the resource (and
+	 * its data) behind; `DESTROY` tears it down. Applies only to CDK/CloudFormation
+	 * deletions.
+	 */
+	removalPolicy: RemovalPolicy;
+
+	/**
+	 * Whether to block deletion of a stateful resource. Unlike `removalPolicy`,
+	 * this guards against deletion through **any** path — CDK/CloudFormation as
+	 * well as the CLI, API, and AWS console — until it is turned off.
+	 */
+	deletionProtection: boolean;
+
+	/**
+	 * CORS origins the compute's API accepts, as regular-expression patterns
+	 * matched against the request `Origin` header. Empty means no cross-origin
+	 * requests are allowed. The `sandbox` preset allows localhost so a local dev
+	 * frontend can reach a deployed API; `production` allows none by default.
+	 */
+	allowedOrigins: string[];
+
+	/**
+	 * Whether stateful resources that support continuous backups keep them on by
+	 * default — e.g. DynamoDB Point-in-Time Recovery, letting you restore to any
+	 * second in the retention window. On in `production`, off in `sandbox` (where
+	 * throwaway data isn't worth the backup-storage cost). Blocks whose service
+	 * has no equivalent simply ignore it.
+	 *
+	 * `true` enables backups with the service's default window; `false` disables
+	 * them; `{ retentionDays: n }` enables them and pins the window (a block
+	 * clamps/validates `n` to its service's supported range — DynamoDB PITR is
+	 * 1–35 days). Backups only have a window when on, so the two are one field.
+	 */
+	pointInTimeRecovery: boolean | { retentionDays: number };
+}
+
+/**
+ * Prepared starting points for {@link BlocksDefaults}. Pick one and override
+ * individual fields with a spread:
+ *
+ * ```ts
+ * defaults: { ...BlocksPresets.production, deletionProtection: false }
+ * ```
+ */
+export const BlocksPresets = {
+	/** Disposable development stacks: tear down cleanly, no delete guard, no backups. */
+	sandbox: {
+		removalPolicy: RemovalPolicy.DESTROY,
+		deletionProtection: false,
+		allowedOrigins: ['^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$'],
+		pointInTimeRecovery: false,
+	},
+	/** Durable, protected posture for permanent deployments. */
+	production: {
+		removalPolicy: RemovalPolicy.RETAIN,
+		deletionProtection: true,
+		allowedOrigins: [],
+		pointInTimeRecovery: true,
+	},
+} satisfies Record<string, BlocksDefaults>;

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

@@ -1,17 +1,61 @@
 // 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 { BlocksStack, Scope } from './index.js';
+import { Compute } from './compute/compute.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;
+
+	constructor(scope: ScopeParent, id: string) {
+		super(id, { parent: scope });
+		this.fn = new lambda.NodejsFunction(this, 'Handler', {
+			entry: this.backendHandlerPath,
+			runtime: cdk.aws_lambda.Runtime.NODEJS_22_X,
+			handler: 'handler',
+			role: this.executionRole,
+			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,128 +63,134 @@ 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,
-    });
-
-    const stack2 = await BlocksStack.create(app, 'PipelineStage2', {
-      backendHandlerPath: handlerPath,
-      backendCDKPath: 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)',
-    );
-  });
+	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();
+	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,
-    });
+		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');
-  });
+		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,
-    });
-
-    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,
-    });
-
-    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,
-    });
-
-    // 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');
+	});
 });
 
 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,
-        }),
-        (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;
+		}
+	});
 });