@aws-blocks/core 0.1.18 → 0.3.0

package/src/cdk/bundling.test.ts

@@ -0,0 +1,90 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { createRequire } from 'node:module';
+import { build } from 'esbuild';
+import { OutputFormat } from 'aws-cdk-lib/aws-lambda-nodejs';
+import { blocksNodejsBundling } from './bundling.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const importMetaFixture = join(__dirname, '__fixtures__', 'import-meta-handler.js');
+const requireCjs = createRequire(import.meta.url);
+
+describe('blocksNodejsBundling', () => {
+  test('injects the import.meta.* CJS shim for the default (CJS) output', () => {
+    const out = blocksNodejsBundling({ minify: true, esbuildArgs: { '--conditions': 'aws-runtime' } });
+
+    // Caller options are preserved.
+    assert.equal(out.minify, true);
+    assert.equal(out.esbuildArgs?.['--conditions'], 'aws-runtime');
+
+    // All three import.meta path properties are substituted.
+    assert.ok(out.esbuildArgs?.['--define:import.meta.url']);
+    assert.ok(out.esbuildArgs?.['--define:import.meta.dirname']);
+    assert.ok(out.esbuildArgs?.['--define:import.meta.filename']);
+
+    // The banner defines the substituted identifiers via CommonJS primitives.
+    assert.match(out.banner ?? '', /pathToFileURL\(__filename\)/);
+    assert.match(out.banner ?? '', /__dirname/);
+    assert.match(out.banner ?? '', /__filename/);
+  });
+
+  test('leaves ESM output untouched (import.meta works natively there)', () => {
+    const input = { format: OutputFormat.ESM, esbuildArgs: { '--conditions': 'aws-runtime' } };
+    const out = blocksNodejsBundling(input);
+
+    assert.deepEqual(out, input);
+    assert.equal(out.esbuildArgs?.['--define:import.meta.url'], undefined);
+    assert.equal(out.banner, undefined);
+  });
+
+  test('prepends the shim while keeping a caller-supplied banner', () => {
+    const out = blocksNodejsBundling({ banner: '// caller banner' });
+    assert.match(out.banner ?? '', /pathToFileURL\(__filename\)/);
+    assert.ok((out.banner ?? '').includes('// caller banner'));
+  });
+
+  test('a CJS bundle built with the shim resolves import.meta.url at load (no crash)', async () => {
+    // Bundle the fixture exactly as NodejsFunction would: apply the helper's `banner`
+    // and its `--define:import.meta.*` esbuildArgs. Without the shim this fixture's
+    // top-level `fileURLToPath(import.meta.url)` becomes `fileURLToPath(undefined)`
+    // and throws when the module is loaded.
+    const opts = blocksNodejsBundling({ minify: true });
+    const define: Record<string, string> = {};
+    for (const [key, value] of Object.entries(opts.esbuildArgs ?? {})) {
+      const m = key.match(/^--define:(.+)$/);
+      if (m) define[m[1]] = String(value);
+    }
+
+    const tmp = mkdtempSync(join(tmpdir(), 'bb-shim-'));
+    const outfile = join(tmp, 'out.cjs');
+    try {
+      await build({
+        entryPoints: [importMetaFixture],
+        bundle: true,
+        platform: 'node',
+        format: 'cjs',
+        minify: true,
+        banner: { js: opts.banner ?? '' },
+        define,
+        outfile,
+        logLevel: 'silent',
+      });
+
+      // Loading the bundle must not throw, and import.meta.url must resolve to a real
+      // (file-URL-derived) path rather than being undefined.
+      const mod = requireCjs(outfile);
+      assert.equal(typeof mod.moduleDir, 'string');
+      assert.ok(mod.moduleDir.length > 0, 'moduleDir should resolve to a non-empty path');
+      assert.equal(typeof mod.handler, 'function');
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});

package/src/cdk/bundling.ts

@@ -0,0 +1,76 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { OutputFormat, type BundlingOptions } from 'aws-cdk-lib/aws-lambda-nodejs';
+
+/** Banner-defined identifiers the shim substitutes `import.meta.*` with (CJS only). */
+const IMPORT_META_SHIM = {
+  url: '__blocksImportMetaUrl',
+  dirname: '__blocksImportMetaDirname',
+  filename: '__blocksImportMetaFilename',
+} as const;
+
+/**
+ * Wrap a `NodejsFunction` `bundling` config with the framework's hardened esbuild
+ * defaults, so every Lambda the framework bundles behaves consistently.
+ *
+ * **What it fixes.** `NodejsFunction` bundles to **CommonJS**, where `import.meta` is
+ * empty. Any bundled code that does `fileURLToPath(import.meta.url)` (a customer
+ * handler, a Building Block's `aws-runtime` code, or a dependency) would otherwise
+ * become `fileURLToPath(undefined)` and throw at Lambda load — esbuild only *warns*
+ * (`empty-import-meta`), so the broken bundle deploys and 502s on first invocation.
+ *
+ * **How.** For CJS output this shims `import.meta.url` / `import.meta.dirname` /
+ * `import.meta.filename` to their CommonJS equivalents (`pathToFileURL(__filename)`,
+ * `__dirname`, `__filename`) via an esbuild `--define` + `banner`. This is the same
+ * approach esbuild blesses (defining `import.meta` also suppresses the warning) and
+ * that Rollup applies by default, so:
+ * - a handler that reads `import.meta.url` no longer crashes at load, and
+ * - a bundled dependency that merely *contains* `import.meta` (even in dead code) no
+ *   longer trips a build failure.
+ *
+ * The value resolves to the **bundled output file** (esbuild flattens the module tree),
+ * which is correct for the common cases — a value computed at synth (e.g. a
+ * `migrationsPath`) or dead interop fallbacks — but note it does not point at your
+ * source layout. Runtime code that must read a file relative to itself should not rely
+ * on `import.meta.url` inside a bundle; resolve such paths at synth time or ship the
+ * file as an asset. ESM output (`OutputFormat.ESM`) supports `import.meta` natively and
+ * is left untouched.
+ *
+ * All other options (`minify`, `commandHooks`, `externalModules`, other `esbuildArgs`
+ * such as `--conditions`, and any caller `banner`) are preserved.
+ *
+ * @param options - The site-specific `NodejsFunction` bundling options (optional).
+ * @returns The same options with the CJS `import.meta` shim merged in.
+ *
+ * @example
+ * new lambda.NodejsFunction(scope, 'Handler', {
+ *   entry,
+ *   bundling: blocksNodejsBundling({ minify: true, esbuildArgs: { '--conditions': 'aws-runtime' } }),
+ * });
+ */
+export function blocksNodejsBundling(options: BundlingOptions = {}): BundlingOptions {
+  // ESM output has real `import.meta` — nothing to shim, and `require` in the banner
+  // wouldn't resolve. Only the CommonJS bundle needs the shim.
+  if (options.format === OutputFormat.ESM) return options;
+
+  const shimBanner = [
+    `const ${IMPORT_META_SHIM.url}=require('url').pathToFileURL(__filename).href;`,
+    `const ${IMPORT_META_SHIM.dirname}=__dirname;`,
+    `const ${IMPORT_META_SHIM.filename}=__filename;`,
+  ].join('');
+
+  return {
+    ...options,
+    // Prepend the shim definitions; keep any caller-supplied banner after them.
+    banner: options.banner ? `${shimBanner}\n${options.banner}` : shimBanner,
+    esbuildArgs: {
+      ...options.esbuildArgs,
+      // Substitute import.meta.* with the banner identifiers. Also suppresses esbuild's
+      // empty-import-meta warning, so import.meta anywhere in the graph is safe.
+      '--define:import.meta.url': IMPORT_META_SHIM.url,
+      '--define:import.meta.dirname': IMPORT_META_SHIM.dirname,
+      '--define:import.meta.filename': IMPORT_META_SHIM.filename,
+    },
+  };
+}

package/src/cdk/compute/compute.ts

@@ -0,0 +1,37 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Scope } from '../index.js';
+
+/**
+ * Base class for a Blocks *compute* — a runtime that executes handler code
+ * (Lambda today; containers later). A compute owns the physical function/service
+ * plus its ingress, and receives config via {@link setEnv}.
+ *
+ * The backend entry and stack name a compute needs are inherited from
+ * {@link Scope} (`backendHandlerPath` / `backendStackName`), which resolve them
+ * from the owning BlocksStack/BlocksBackend — never caller-supplied, so every
+ * compute in an app runs the same backend and agrees on the resource-name
+ * namespace.
+ *
+ * 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.
+ */
+export abstract class Compute extends Scope {
+	/**
+	 * API namespaces assigned to run on this compute — recorded so request
+	 * routing can map a namespace to the compute that hosts it. Currently
+	 * unpopulated (no compute assignment surface yet).
+	 */
+	readonly namespaces: string[] = [];
+
+	/**
+	 * 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;
+}

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

@@ -0,0 +1,37 @@
+// 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;
+}
+
+/**
+ * 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/index.ts

@@ -15,40 +15,88 @@ import {
 import { setupBlocksInfra, BlocksBackend, assertCdkConditionActive } from './blocks-backend.js';
 import { addBlocksStackMetadata } from './stack-metadata.js';
 import { finalizeConfigRegistry } from './config-registry.js';
+import { type BlocksDefaults, BlocksPresets } from './blocks-defaults.js';
+import type { Compute } from './compute/compute.js';
+import type { DefaultComputeFactory, LambdaShapedCompute } from './compute/default-compute-factory.js';
 
-export { BlocksBackend, type BlocksBackendProps } from './blocks-backend.js';
+export {
+	BlocksBackend,
+	type BlocksBackendProps,
+	type CoreBlocksBackendProps,
+	SHARED_HANDLER_TIMEOUT_SECONDS,
+} from './blocks-backend.js';
 export { DEFAULT_NODE_RUNTIME } from './node-version.js';
+export { blocksNodejsBundling } from './bundling.js';
 export { SandboxDisableDeletionProtection } from './mixins.js';
 export { registerConfig, finalizeConfigRegistry } from './config-registry.js';
+export {
+  type BlocksDefaults,
+  BlocksPresets,
+} from './blocks-defaults.js';
 export { synthGuard } from './synth-guard.js';
 export type { ScopeOptions } from '../index.js';
 export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 
+/**
+ * Core's `create()` props: the public {@link BlocksStackProps} plus the required
+ * `defaultComputeFactory`. The umbrella (`@aws-blocks/blocks`) supplies the
+ * factory (which builds a `LambdaCompute`) by spreading it onto the customer's
+ * props; customers use {@link BlocksStackProps} and never set the factory.
+ *
+ * Kept separate (rather than a `create()` argument) so the factory travels with
+ * the props object and core stays free of any concrete compute class.
+ *
+ * @internal
+ */
+export interface CoreBlocksStackProps extends BlocksStackProps {
+  /** Builds the stack's default compute. Injected by `@aws-blocks/blocks`. */
+  defaultComputeFactory: DefaultComputeFactory;
+}
+
 export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
   public readonly id: string;
-  public readonly apiUrl: string;
-  public readonly gateway: cdk.aws_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: cdk.aws_iam.IRole;
+  /** Infrastructure defaults for Building Blocks created under this stack. */
+  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(): cdk.aws_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 stack not fully initialized — access .handler/.gateway/.apiUrl after BlocksStack.create() resolves.');
+    }
+    return this._defaultCompute as LambdaShapedCompute;
+  }
 
   private constructor(scope: Construct, id: string, props: BlocksStackProps) {
     super(scope, id, props);
     this.id = id;
     this.backendHandlerPath = props.backendHandlerPath;
+    this.defaults = props.defaults;
 
     // Set globalThis so Building Blocks attach directly to this stack
     (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;
     this.executionRole = infra.executionRole;
   }
 
-  static async create(scope: Construct, id: string, props: BlocksStackProps) {
+  static async create(scope: Construct, id: string, props: CoreBlocksStackProps) {
     assertCdkConditionActive();
 
     // Detect ambient pipeline stage scope set by Pipeline appFile imports
@@ -56,6 +104,13 @@ export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     const actualScope = pipelineScope || scope;
 
     const stack = new BlocksStack(actualScope, 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.
+    stack._defaultCompute = props.defaultComputeFactory(stack);
     // 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);
@@ -86,50 +141,146 @@ export class Scope extends Construct {
   readonly bbName?: string;
   readonly bbVersion?: string;
 
+  /**
+   * The owning stack/backend (the root of the Blocks construct tree), resolved
+   * once at construction: the nearest BlocksStack/BlocksBackend up the construct
+   * tree, or the ambient `globalThis.CURRENT_BLOCKS_STACK` fallback. All
+   * root-derived accessors below read from this instead of each repeating the
+   * tree walk.
+   */
+  private readonly root: BlocksStack | BlocksBackend;
+
+  /**
+   * Compute assigned at this node. Applies to this block and is inherited by
+   * descendants (a nearer assignment wins). Covers both a handler assigned to a
+   * specific compute and a scope-level default for its subtree. Internal until
+   * the customer-facing surface exists.
+   * @internal
+   */
+  _compute?: Compute;
+
   constructor(id: string, options?: ScopeOptions) {
     const parent = options?.parent || (globalThis as any).CURRENT_BLOCKS_STACK;
     super(parent, id);
     this.id = id;
     this.parent = parent;
+    this.root = this.resolveRoot();
   }
 
-  get handler() {
-    // Walk up the construct tree to find the owning BlocksStack/BlocksBackend
+  /**
+   * Walk up the construct tree to the nearest owning BlocksStack/BlocksBackend;
+   * fall back to the ambient `globalThis.CURRENT_BLOCKS_STACK`. Called once from
+   * the constructor; the result is cached in {@link root}.
+   */
+  private resolveRoot(): BlocksStack | BlocksBackend {
     let current: Construct = this;
     while (current.node.scope) {
         current = current.node.scope as Construct;
         if (current instanceof BlocksStack || current instanceof BlocksBackend) {
-            return current.handler;
+            return current;
         }
     }
-    // Fallback to globalThis for backward compatibility
-    return ((globalThis as any).CURRENT_BLOCKS_STACK as { handler: cdk.aws_lambda_nodejs.NodejsFunction }).handler;
+    // Fallback to the ambient stack. In production this is always a real
+    // BlocksStack/BlocksBackend; the cast also admits the test doubles that set
+    // globalThis.CURRENT_BLOCKS_STACK to a stub exposing the same surface.
+    return (globalThis as any).CURRENT_BLOCKS_STACK as BlocksStack | BlocksBackend;
+  }
+
+  get handler() {
+    return this.root.handler;
   }
 
   /**
    * The shared IAM role assumed by all Blocks compute. Building Blocks grant
-   * their permissions to this role instead of to an individual function's
-   * auto-role. CDK's `grant*()` / `addToPrincipalPolicy()` route those grants
-   * to the role's default (inline) policy — exactly where they landed on the
-   * auto-generated role before.
-   *
-   * Resolves the same way as {@link handler}: walk up to the owning
-   * BlocksStack/BlocksBackend, falling back to the ambient stack.
+   * their permissions to this role; CDK's `grant*()` / `addToPrincipalPolicy()`
+   * route those grants to the role's default (inline) policy.
    */
   get executionRole(): cdk.aws_iam.IRole {
+    return this.root.executionRole;
+  }
+
+  /**
+   * The compute this block runs on: the nearest `_compute` assigned on this
+   * block or an ancestor scope, else the owning stack/backend's default compute.
+   *
+   * For any app that doesn't assign a compute, this always resolves to the
+   * default — so reads are a no-op refactor. `_compute` is internal
+   * (test/framework) until the customer-facing surface exists; there is no
+   * public option to set it yet.
+   */
+  get compute(): Compute {
+    for (let current: ScopeParent | undefined = this; current; current = (current as Scope).parent) {
+      const assigned = (current as Scope)._compute;
+      if (assigned) return assigned;
+    }
+    const defaultCompute = this.root._defaultCompute;
+    if (!defaultCompute) {
+      throw new Error('Default compute not initialized — BlocksStack/BlocksBackend.create() must run before resolving `compute`.');
+    }
+    return defaultCompute;
+  }
+
+  /**
+   * The backend entry file the owning BlocksStack/BlocksBackend runs — the
+   * single handler entry shared across the whole app.
+   */
+  get backendHandlerPath(): string {
+    return this.root.backendHandlerPath;
+  }
+
+  /**
+   * The owning stack/backend's token-free root identity. This is the value the
+   * runtime receives as `BLOCKS_STACK_NAME` and rebuilds `fullId` from, so
+   * physical resource names (DynamoDB tables, env-var keys, IAM ARNs) derived
+   * from `fullId` match byte-for-byte between synth and runtime — otherwise the
+   * runtime looks up names that were never created. `BlocksBackend` exposes this
+   * as `fullId` ({@link BlocksBackend.fullId}); `BlocksStack` as `id`.
+   */
+  get backendStackName(): string {
+    const name = this.root instanceof BlocksBackend ? this.root.fullId : this.root.id;
+    if (!name) {
+      throw new Error('Owning Blocks stack/backend has no id to derive BLOCKS_STACK_NAME');
+    }
+    return name;
+  }
+
+  get fullId(): string {
+    return computeScopeFullId(this);
+  }
+
+  /**
+   * The stack-wide infrastructure {@link BlocksDefaults} registered by
+   * `BlocksStack.create` / `BlocksBackend.create`. Read these in a Building
+   * Block's CDK constructor to resolve a durability value, letting a per-block
+   * option override:
+   *
+   * ```ts
+   * const removalPolicy = options?.removalPolicy ?? this.defaults.removalPolicy;
+   * ```
+   */
+  get defaults(): BlocksDefaults {
+    // Resolve the same way as handler/executionRole: walk up to the owning
+    // BlocksStack/BlocksBackend and read its defaults, so several backends in
+    // one stack each keep their own posture. Falls back to the ambient stack,
+    // then to the production preset when none was registered.
     let current: Construct = this;
     while (current.node.scope) {
         current = current.node.scope as Construct;
         if (current instanceof BlocksStack || current instanceof BlocksBackend) {
-            return current.executionRole;
+            return current.defaults;
         }
     }
-    // Fallback to globalThis for backward compatibility
-    return ((globalThis as any).CURRENT_BLOCKS_STACK as { executionRole: cdk.aws_iam.IRole }).executionRole;
-  }
-
-  get fullId(): string {
-    return computeScopeFullId(this);
+    const ambient = ((globalThis as any).CURRENT_BLOCKS_STACK as { defaults?: BlocksDefaults } | undefined)?.defaults;
+    if (ambient) return ambient;
+    // No owning BlocksStack/BlocksBackend in the tree and none ambient — this is
+    // usually a deliberate test stub, but could be a real misconfiguration (a
+    // block built outside any Blocks backend). Fall back to the safe production
+    // posture, and log so it's debuggable if it fires unexpectedly.
+    console.warn(
+      `[Blocks] Scope "${this.id}" resolved infrastructure defaults with no owning ` +
+      'BlocksStack/BlocksBackend in scope; falling back to BlocksPresets.production.',
+    );
+    return BlocksPresets.production;
   }
 
   protected buildUserAgentChain(): [string, string][] {

package/src/cdk/internal.ts

@@ -0,0 +1,30 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Internal CDK entry point — framework- and test-only surface that is
+ * intentionally NOT part of the public API (`@aws-blocks/core` /
+ * `@aws-blocks/core/cdk`).
+ *
+ * The compute abstraction lives behind this path while it has no public,
+ * customer-facing surface. Importing from here is a signal that you are inside
+ * the framework or a test, not a customer.
+ *
+ * Planned removal: once a customer can assign a compute and have it actually
+ * take effect — i.e. `this.compute` resolution and request routing to the
+ * chosen compute both exist, plus a synth-time guard that rejects an assignment
+ * with no route — these exports move to the public CDK entry point
+ * (`@aws-blocks/core/cdk`, re-exported from `index.cdk.ts`) and this file is
+ * deleted. It must NOT be made public before then: a compute a customer can
+ * declare but that is silently ignored is a worse experience than not having
+ * the feature. Until that flip, treat everything here as unstable — no
+ * backward-compatibility guarantee.
+ *
+ * @internal
+ */
+
+export { Compute } from './compute/compute.js';
+export type { DefaultComputeFactory } from './compute/default-compute-factory.js';
+// Reserved `/aws-blocks` path segment, needed by concrete computes (e.g.
+// LambdaCompute in @aws-blocks/bb-lambda-compute) to build their API route tree.
+export { BLOCKS_NAMESPACE } from '../constants.js';

package/src/cdk/mixins.test.ts

@@ -2,7 +2,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { test, describe } from 'node:test';
-import assert from 'node:assert';
 import * as cdk from 'aws-cdk-lib';
 import { Template, Match } from 'aws-cdk-lib/assertions';
 import { Table, AttributeType, BillingMode } from 'aws-cdk-lib/aws-dynamodb';
@@ -110,6 +109,62 @@ describe('sandbox removal policy', () => {
     });
   });
 
+  test('SandboxDisableDeletionProtection mixin: deletionProtection disabled on DynamoDB table', () => {
+    const app = new cdk.App({ context: { sandboxMode: 'true' } });
+    const stack = new cdk.Stack(app, 'TestStack');
+
+    new Table(stack, 'MyTable', {
+      partitionKey: { name: 'pk', type: AttributeType.STRING },
+      billingMode: BillingMode.PAY_PER_REQUEST,
+      deletionProtection: true,
+    });
+
+    RemovalPolicies.of(stack).destroy();
+    Mixins.of(stack).apply(new SandboxDisableDeletionProtection());
+
+    const template = Template.fromStack(stack);
+    // DynamoDB refuses DeleteTable while protection is on, regardless of DeletionPolicy
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      DeletionProtectionEnabled: false,
+    });
+    template.hasResource('AWS::DynamoDB::Table', {
+      DeletionPolicy: 'Delete',
+    });
+  });
+
+  test('production mode: deletionProtection stays enabled on DynamoDB table when mixin is not applied', () => {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'TestStack');
+
+    new Table(stack, 'MyTable', {
+      partitionKey: { name: 'pk', type: AttributeType.STRING },
+      billingMode: BillingMode.PAY_PER_REQUEST,
+      deletionProtection: true,
+    });
+
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      DeletionProtectionEnabled: true,
+    });
+  });
+
+  test('SandboxDisableDeletionProtection mixin: does not set DeletionProtectionEnabled on unprotected tables', () => {
+    const app = new cdk.App({ context: { sandboxMode: 'true' } });
+    const stack = new cdk.Stack(app, 'TestStack');
+
+    new Table(stack, 'MyTable', {
+      partitionKey: { name: 'pk', type: AttributeType.STRING },
+      billingMode: BillingMode.PAY_PER_REQUEST,
+    });
+
+    Mixins.of(stack).apply(new SandboxDisableDeletionProtection());
+
+    const template = Template.fromStack(stack);
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      DeletionProtectionEnabled: Match.absent(),
+    });
+  });
+
   test('SandboxDisableDeletionProtection mixin: skips constructs without deletionProtection', () => {
     const app = new cdk.App();
     const stack = new cdk.Stack(app, 'TestStack');