@aws-blocks/core 0.1.0

package/src/cdk/__fixtures__/fullid-construct-backend.ts

@@ -0,0 +1,42 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Test fixture: a child Scope that embeds its `fullId` directly into a CDK
+ * construct ID.
+ *
+ * Why this matters
+ * ----------------
+ * Building Blocks routinely use their `fullId` as part of a construct ID, e.g.
+ * a DSQL block creating its migration Lambda as
+ * `new lambda.NodejsFunction(stack, `${this.fullId}DsqlMigrationFn`, ...)`.
+ * CDK forbids unresolved tokens in construct IDs (it throws
+ * "ID components may not include unresolved tokens" at synth time).
+ *
+ * `fullId` is derived from the enclosing stack name. In a nested-stack topology
+ * (e.g. Amplify Gen2's `backend.createStack('blocks')`) that stack name is a
+ * deploy-time token, so a naive `fullId` would carry a token and break synth.
+ *
+ * This fixture reproduces that exact pattern: importing it builds a construct
+ * whose ID is `${this.fullId}Marker`. If `fullId` ever contains a token, this
+ * side-effect import throws at synth time — which is what the test asserts must
+ * NOT happen.
+ */
+import * as cdk from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { Scope } from '../index.js';
+import type { ScopeParent } from '../../common/index.js';
+
+class FullIdConstructBlock extends Scope {
+  constructor(scope: ScopeParent, id: string) {
+    super(id, { parent: scope });
+    const stack = cdk.Stack.of(this);
+    // Use fullId as a construct ID, the same way real Building Blocks do.
+    new cdk.CfnResource(stack, `${this.fullId}Marker`, {
+      type: 'AWS::CloudFormation::WaitConditionHandle',
+    });
+  }
+}
+
+const parent = (globalThis as any).CURRENT_BLOCKS_STACK;
+new FullIdConstructBlock(parent, 'db');

package/src/cdk/__fixtures__/handler.ts

@@ -0,0 +1,4 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export const handler = async () => ({ statusCode: 200, body: '{}' });

package/src/cdk/__fixtures__/side-effect-backend.ts

@@ -0,0 +1,7 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Construct } from 'constructs';
+
+const parent = (globalThis as any).CURRENT_BLOCKS_STACK;
+new Construct(parent, 'SideEffectMarker');

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

@@ -0,0 +1,207 @@
+// 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 * as cdk from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import { BlocksBackend } from './blocks-backend.js';
+
+// Simulate the CDK condition being active (tests import CDK files directly)
+before(() => {
+  process.env.NODE_OPTIONS = (process.env.NODE_OPTIONS ?? '') + ' --conditions=cdk';
+});
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const handlerPath = join(__dirname, '__fixtures__', 'handler.js');
+const sideEffectBackendPath = join(__dirname, '__fixtures__', 'side-effect-backend.js');
+const factoryBackendPath = join(__dirname, '__fixtures__', 'factory-backend.js');
+const fullIdConstructBackendPath = join(__dirname, '__fixtures__', 'fullid-construct-backend.js');
+
+describe('ESM cache-busting (multi-stage)', () => {
+  test('BlocksBackend.create() with same backendCDKPath but different IDs produces constructs in each', async () => {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'TestStack');
+
+    const backend1 = await BlocksBackend.create(stack, 'Stage1', {
+      backendHandlerPath: handlerPath,
+      backendCDKPath: sideEffectBackendPath,
+    });
+
+    const backend2 = await BlocksBackend.create(stack, 'Stage2', {
+      backendHandlerPath: handlerPath,
+      backendCDKPath: sideEffectBackendPath,
+    });
+
+    const findMarker = (scope: cdk.aws_lambda_nodejs.NodejsFunction | any) =>
+      scope.node.tryFindChild('SideEffectMarker');
+
+    assert.ok(
+      findMarker(backend1),
+      'Stage1 backend should have SideEffectMarker construct from module side effect',
+    );
+    assert.ok(
+      findMarker(backend2),
+      'Stage2 backend should have SideEffectMarker construct from re-executed module',
+    );
+  });
+});
+
+describe('synth shape (drop into existing stack)', () => {
+  test('BlocksBackend lives inside the parent stack and synthesizes Lambda + API Gateway', async () => {
+    const app = new cdk.App();
+    const parent = new cdk.Stack(app, 'MyExistingStack');
+
+    const backend = await BlocksBackend.create(parent, 'Blocks', {
+      backendHandlerPath: handlerPath,
+      backendCDKPath: sideEffectBackendPath,
+    });
+
+    // Public surface mirrors BlocksStack.
+    assert.ok(backend.handler, 'BlocksBackend should expose .handler');
+    assert.ok(backend.gateway, 'BlocksBackend should expose .gateway');
+    assert.ok(backend.apiUrl, 'BlocksBackend should expose .apiUrl');
+
+    // Synth produces the expected resources inside the parent stack —
+    // no separate stack is created.
+    const template = Template.fromStack(parent);
+    template.hasResourceProperties('AWS::Lambda::Function', {});
+    template.resourceCountIs('AWS::ApiGateway::RestApi', 1);
+  });
+
+  test('multiple BlocksBackends in the same parent stack do not collide', async () => {
+    const app = new cdk.App();
+    const parent = new cdk.Stack(app, 'MultiBackendStack');
+
+    await BlocksBackend.create(parent, 'BackendA', {
+      backendHandlerPath: handlerPath,
+      backendCDKPath: sideEffectBackendPath,
+    });
+    await BlocksBackend.create(parent, 'BackendB', {
+      backendHandlerPath: handlerPath,
+      backendCDKPath: sideEffectBackendPath,
+    });
+
+    const template = Template.fromStack(parent);
+    template.resourceCountIs('AWS::ApiGateway::RestApi', 2);
+  });
+});
+
+describe('factory function support', () => {
+  test('BlocksBackend.create() calls default export function with the backend instance', async () => {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'FactoryTestStack');
+
+    const backend = await BlocksBackend.create(stack, 'FactoryStage', {
+      backendHandlerPath: handlerPath,
+      backendCDKPath: factoryBackendPath,
+    });
+
+    const marker = backend.node.tryFindChild('FactoryMarker');
+    assert.ok(marker, 'Factory function should have created FactoryMarker on the backend');
+  });
+});
+
+describe('fullId is token-free (construct IDs / env-var keys)', () => {
+  test('top-level stack: fullId is {stackName}-{id} and resolvable', async () => {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'TopLevelStack');
+
+    const backend = await BlocksBackend.create(stack, 'blocks', {
+      backendHandlerPath: handlerPath,
+      backendCDKPath: sideEffectBackendPath,
+    });
+
+    assert.strictEqual(backend.fullId, 'TopLevelStack-blocks');
+    assert.ok(!cdk.Token.isUnresolved(backend.fullId), 'fullId must not contain a token');
+  });
+
+  test('nested stack: fullId stays token-free (regression for #714 / Amplify Gen2)', async () => {
+    // Amplify Gen2 wires Blocks into a NestedStack via backend.createStack('blocks').
+    // A NestedStack has a tokenized stackName that only resolves at deploy time —
+    // embedding it in fullId broke construct IDs with
+    // "ID components may not include unresolved tokens".
+    const app = new cdk.App();
+    const parent = new cdk.Stack(app, 'ParentStack');
+    const nested = new cdk.NestedStack(parent, 'blocks');
+
+    // Sanity: the nested stack's own name really is a token.
+    assert.ok(
+      cdk.Token.isUnresolved(nested.stackName),
+      'precondition: NestedStack.stackName should be an unresolved token',
+    );
+
+    const backend = await BlocksBackend.create(nested, 'blocks', {
+      backendHandlerPath: handlerPath,
+      backendCDKPath: sideEffectBackendPath,
+    });
+
+    assert.ok(
+      !cdk.Token.isUnresolved(backend.fullId),
+      `fullId must be token-free inside a nested stack, got: ${backend.fullId}`,
+    );
+    // Falls back to the top-level (concrete) stack name, keeping uniqueness.
+    assert.strictEqual(backend.fullId, 'ParentStack-blocks');
+  });
+
+  test('child Scope can use fullId as a construct ID inside a nested stack', async () => {
+    // The fixture mirrors bb-distributed-data: it builds a construct whose ID is
+    // `${this.fullId}Marker`. If fullId carried a token, synth would throw.
+    const app = new cdk.App();
+    const parent = new cdk.Stack(app, 'Gen2ParentStack');
+    const nested = new cdk.NestedStack(parent, 'blocks');
+
+    const backend = await BlocksBackend.create(nested, 'blocks', {
+      backendHandlerPath: handlerPath,
+      backendCDKPath: fullIdConstructBackendPath,
+    });
+
+    // The construct ID is `${scope.fullId}Marker` → `ParentStack-blocks-blocks-dbMarker`.
+    const expectedId = `${backend.fullId}-dbMarker`;
+    assert.ok(
+      nested.node.tryFindChild(expectedId),
+      `expected a child construct with id "${expectedId}"`,
+    );
+
+    // Full synth must not throw on unresolved-token-in-construct-id.
+    assert.doesNotThrow(() => app.synth());
+  });
+
+  test('BLOCKS_STACK_NAME env var equals fullId (CDK-time ↔ runtime invariant)', async () => {
+    // Physical resource names (DynamoDB tables, DSQL env-var keys, IAM ARNs) are
+    // derived from fullId on BOTH sides: at synth via BlocksBackend.fullId, and at
+    // runtime via the root parent `{ id: process.env.BLOCKS_STACK_NAME }`. They MUST
+    // be byte-for-byte identical, otherwise the runtime looks up names/grants that
+    // were never created. BlocksBackend keeps them in sync by writing fullId into the
+    // handler's BLOCKS_STACK_NAME env var — assert that contract holds and is token-free.
+    const app = new cdk.App();
+    const parent = new cdk.Stack(app, 'InvariantParent');
+    const nested = new cdk.NestedStack(parent, 'blocks');
+
+    const backend = await BlocksBackend.create(nested, 'blocks', {
+      backendHandlerPath: handlerPath,
+      backendCDKPath: sideEffectBackendPath,
+    });
+
+    const template = Template.fromStack(nested);
+    const fns = template.findResources('AWS::Lambda::Function');
+    const envValues = Object.values(fns)
+      .map((fn: any) => fn.Properties?.Environment?.Variables?.BLOCKS_STACK_NAME)
+      .filter((v): v is string => typeof v === 'string');
+
+    assert.ok(envValues.length > 0, 'expected a Lambda with a BLOCKS_STACK_NAME env var');
+    for (const value of envValues) {
+      assert.strictEqual(
+        value,
+        backend.fullId,
+        'BLOCKS_STACK_NAME must equal BlocksBackend.fullId so runtime names match synth',
+      );
+      assert.ok(
+        !cdk.Token.isUnresolved(value),
+        `BLOCKS_STACK_NAME must be token-free, got: ${value}`,
+      );
+    }
+  });
+});

package/src/cdk/blocks-backend.ts

@@ -0,0 +1,249 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// 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 { CfnGroup } from 'aws-cdk-lib/aws-resourcegroups';
+import { Construct } from 'constructs';
+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 { registerBuiltinRoutes } from '../builtin-routes.js';
+
+/**
+ * Validate that the Node.js process was started with `--conditions=cdk`.
+ *
+ * Without this condition, conditional exports in Building Block packages
+ * resolve to their mock/default entry points instead of the CDK entry points.
+ * This causes a silent deployment failure: CDK synth "succeeds" but produces
+ * no real infrastructure (no tables, no IAM, no Lambda configs).
+ */
+export function assertCdkConditionActive(): void {
+  const nodeOptions = process.env.NODE_OPTIONS ?? '';
+  const execArgv = process.execArgv ?? [];
+
+  const hasCdkCondition =
+    execArgv.some(arg => arg === '--conditions=cdk') ||
+    execArgv.some((arg, i) => (arg === '--conditions' || arg === '-C') && execArgv[i + 1] === 'cdk') ||
+    nodeOptions.includes('--conditions=cdk') ||
+    /(?:--conditions|-C)\s+cdk/.test(nodeOptions);
+
+  if (!hasCdkCondition) {
+    throw new Error(
+      'Missing --conditions=cdk: Building Blocks will silently load mock implementations instead of CDK constructs.\n\n' +
+      'Fix: Set NODE_OPTIONS="--conditions=cdk" before running CDK synth:\n' +
+      '  NODE_OPTIONS="--conditions=cdk" npx cdk synth\n\n' +
+      'Or use the Blocks CLI commands (npm run deploy / npm run sandbox) which set this automatically.',
+    );
+  }
+}
+
+export interface BlocksBackendProps {
+  backendHandlerPath: string;
+  backendCDKPath: string;
+}
+
+/** Shared infra setup — creates Lambda + API Gateway on the given scope. */
+export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id?: string) {
+  const handler = new lambda.NodejsFunction(scope, 'Handler', {
+    entry: props.backendHandlerPath,
+    runtime: DEFAULT_NODE_RUNTIME,
+    handler: 'handler',
+    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 ────────────────────────────────────────────────────
+  let rootStack = cdk.Stack.of(scope);
+  while (rootStack.nestedStackParent) rootStack = rootStack.nestedStackParent;
+  const groupPrefix = (id && id !== rootStack.stackName) ? `${rootStack.stackName}-${id}` : rootStack.stackName;
+
+  new CfnGroup(scope, 'StackResources', {
+    name: `${groupPrefix}-resources`,
+    resourceQuery: {
+      type: 'CLOUDFORMATION_STACK_1_0',
+      query: {
+        resourceTypeFilters: [
+          'AWS::CloudWatch::Dashboard',
+          'AWS::Cognito::UserPool',
+          'AWS::DynamoDB::Table',
+          'AWS::Logs::LogGroup',
+          'AWS::RDS::DBCluster',
+          'AWS::RDS::DBInstance',
+          'AWS::S3::Bucket',
+          'AWS::SQS::Queue',
+        ],
+        stackIdentifier: cdk.Stack.of(scope).stackId,
+      },
+    },
+  });
+
+  new CfnGroup(scope, 'StackSettings', {
+    name: `${groupPrefix}-settings`,
+    resourceQuery: {
+      type: 'TAG_FILTERS_1_0',
+      query: {
+        resourceTypeFilters: ['AWS::SSM::Parameter'],
+        tagFilters: [{ key: 'aws-blocks-stack', values: [rootStack.stackName] }],
+      },
+    },
+  });
+
+  // ── Console redirect routes ────────────────────────────────────────────
+  const region = cdk.Fn.ref('AWS::Region');
+  const resourcesUrl = cdk.Fn.join('', [
+    'https://', region, '.console.aws.amazon.com/resource-groups/group/',
+    `${groupPrefix}-resources`, '?region=', region,
+  ]);
+  const settingsUrl = cdk.Fn.join('', [
+    'https://', region, '.console.aws.amazon.com/resource-groups/group/',
+    `${groupPrefix}-settings`, '?region=', region,
+  ]);
+
+  registerConfig(scope, 'BB_RESOURCES_GROUP_URL', resourcesUrl);
+  registerConfig(scope, 'BB_SETTINGS_GROUP_URL', settingsUrl);
+
+  registerBuiltinRoutes();
+
+  return { handler, gateway: api, apiUrl: `${api.url}${BLOCKS_RPC_PREFIX.slice(1)}` };
+}
+
+/**
+ * Standalone CDK construct that provisions the Blocks backend: a single Lambda
+ * function fronted by API Gateway with RPC + catch-all proxy routing.
+ *
+ * Use this to embed a Blocks backend into any existing CDK stack. Building Blocks
+ * instantiated during the `backendCDKPath` import will automatically attach to
+ * this construct's Lambda handler.
+ *
+ * @example Drop into an existing stack
+ * ```ts
+ * const blocks = await BlocksBackend.create(myStack, 'Blocks', {
+ *   backendHandlerPath: join(__dirname, 'handler.ts'),
+ *   backendCDKPath: join(__dirname, 'infra.ts'),
+ * });
+ * // blocks.apiUrl, blocks.handler, blocks.gateway available
+ * ```
+ */
+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;
+
+  /**
+   * The fullId used by child Scopes to compute their env var names,
+   * construct IDs, and physical resource names (e.g., DynamoDB table names).
+   *
+   * Includes the CDK stack name to ensure physical resources are unique
+   * per deployment. This matches what the runtime sees via BLOCKS_STACK_NAME.
+   *
+   * IMPORTANT: this value MUST be token-free. Child Scopes embed `fullId` in
+   * CDK construct IDs (e.g. `${fullId}DsqlMigrationFn`), and CDK forbids
+   * unresolved tokens in construct IDs ("ID components may not include
+   * unresolved tokens"). It is also used to build env-var keys that must match
+   * byte-for-byte between synth time and runtime.
+   *
+   * A nested stack (e.g. Amplify Gen2 `backend.createStack('blocks')`) has a
+   * tokenized `stackName` that only resolves at deploy time. We therefore walk
+   * up to the top-level stack, whose name is concrete at synth time and still
+   * unique per deployment. The `Token.isUnresolved` guard is a defensive
+   * fallback to the (token-free) construct id should no resolvable name exist.
+   */
+  get fullId(): string {
+    let stack = cdk.Stack.of(this);
+    while (stack.nestedStackParent) {
+      stack = stack.nestedStackParent;
+    }
+    const stackName = stack.stackName;
+    if (cdk.Token.isUnresolved(stackName)) {
+      return this.node.id;
+    }
+    return `${stackName}-${this.node.id}`;
+  }
+
+  private constructor(scope: Construct, id: string, props: BlocksBackendProps) {
+    super(scope, id);
+
+    this.backendHandlerPath = props.backendHandlerPath;
+
+    // Expose self to Building Blocks at CDK time
+    (globalThis as any).CURRENT_BLOCKS_STACK = this;
+
+    const infra = setupBlocksInfra(this, props, id);
+    this.handler = infra.handler;
+    this.gateway = infra.gateway;
+    this.apiUrl = infra.apiUrl;
+
+    // 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);
+  }
+
+  static async create(scope: Construct, id: string, props: BlocksBackendProps) {
+    assertCdkConditionActive();
+    const backend = new BlocksBackend(scope, id, props);
+    // ESM caches modules by URL — append a unique query string so each stage re-executes the module body
+    const mod = await import(`${props.backendCDKPath}?stack=${id}`);
+    if (typeof mod.default === 'function') {
+      try {
+        await mod.default(backend);
+      } catch (error) {
+        throw new Error(`Error executing default export function for backend "${id}": ${error instanceof Error ? error.message : error}`, { cause: error });
+      }
+    }
+    addBlocksStackMetadata(cdk.Stack.of(backend));
+
+    // Finalize BB config → S3 (after all BBs have registered their config)
+    finalizeConfigRegistry(backend, backend.handler);
+
+    return backend;
+  }
+}

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

@@ -0,0 +1,106 @@
+// 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 * as cdk from 'aws-cdk-lib';
+import { BlocksBackend } from './blocks-backend.js';
+import { BlocksStack } from './index.js';
+
+// Simulate the CDK condition being active (tests import CDK files directly)
+before(() => {
+  process.env.NODE_OPTIONS = (process.env.NODE_OPTIONS ?? '') + ' --conditions=cdk';
+});
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const handlerPath = join(__dirname, '__fixtures__', 'handler.js');
+const sideEffectBackendPath = join(__dirname, '__fixtures__', 'side-effect-backend.js');
+const factoryBackendPath = join(__dirname, '__fixtures__', 'factory-backend.js');
+
+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)',
+    );
+  });
+});
+
+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,
+    });
+
+    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',
+    );
+  });
+});
+
+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;
+    }
+  });
+});