@aws-blocks/core 0.1.17 → 0.2.0

package/dist/cdk/bundling.js

@@ -0,0 +1,72 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { OutputFormat } 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',
+};
+/**
+ * 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 = {}) {
+    // 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/dist/cdk/bundling.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bundling.test.d.ts.map

package/dist/cdk/bundling.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundling.test.d.ts","sourceRoot":"","sources":["../../src/cdk/bundling.test.ts"],"names":[],"mappings":""}

package/dist/cdk/bundling.test.js

@@ -0,0 +1,80 @@
+// 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 = {};
+        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/dist/cdk/compute/compute.d.ts

@@ -0,0 +1,33 @@
+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 declare 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;
+}
+//# sourceMappingURL=compute.d.ts.map

package/dist/cdk/compute/compute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute.d.ts","sourceRoot":"","sources":["../../../src/cdk/compute/compute.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,OAAQ,SAAQ,KAAK;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAM;IAEnC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CACjD"}

package/dist/cdk/compute/compute.js

@@ -0,0 +1,28 @@
+// 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 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).
+     */
+    namespaces = [];
+}

package/dist/cdk/index.d.ts

@@ -1,10 +1,13 @@
 import * as cdk from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { type BlocksStackProps, type BlocksStack as BaseBlocksStack, type ScopeParent, type ScopeOptions } from '../common/index.js';
+import { type BlocksDefaults } from './blocks-defaults.js';
 export { BlocksBackend, type BlocksBackendProps } 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';
@@ -14,6 +17,10 @@ export declare class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     readonly gateway: cdk.aws_apigateway.RestApi;
     readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
     readonly backendHandlerPath: string;
+    /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
+    readonly executionRole: cdk.aws_iam.IRole;
+    /** Infrastructure defaults for Building Blocks created under this stack. */
+    readonly defaults: BlocksDefaults;
     private constructor();
     static create(scope: Construct, id: string, props: BlocksStackProps): Promise<BlocksStack>;
 }
@@ -22,9 +29,54 @@ export declare class Scope extends Construct {
     readonly parent: ScopeParent;
     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;
     constructor(id: string, options?: ScopeOptions);
+    /**
+     * 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;
     get handler(): cdk.aws_lambda_nodejs.NodejsFunction;
+    /**
+     * The shared IAM role assumed by all Blocks compute. Building Blocks grant
+     * 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;
+    /**
+     * The backend entry file the owning BlocksStack/BlocksBackend runs — the
+     * single handler entry shared across the whole app.
+     */
+    get backendHandlerPath(): string;
+    /**
+     * 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;
     get fullId(): string;
+    /**
+     * 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;
     protected buildUserAgentChain(): [string, string][];
     registerClientMiddleware(_packageSpecifier: string): void;
     registerDevAttachment(_packageSpecifier: string): void;

package/dist/cdk/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cdk/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,IAAI,eAAe,EACnC,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE7F,qBAAa,WAAY,SAAQ,GAAG,CAAC,KAAM,YAAW,eAAe;IACnE,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,OAAO,EAAE,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC;IACpD,SAAgB,OAAO,EAAE,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAC9D,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAE3C,OAAO;WAcM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB;CA6B1E;AAED,qBAAa,KAAM,SAAQ,SAAS;IAClC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEhB,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAO9C,IAAI,OAAO,yCAWV;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,SAAS,CAAC,mBAAmB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;IAKnD,wBAAwB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACzD,qBAAqB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACtD,0BAA0B,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IACrH,IAAI,gBAAgB,IAAI,SAAS,MAAM,EAAE,CAAe;IACxD,IAAI,cAAc,IAAI,SAAS,MAAM,EAAE,CAAe;CACvD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cdk/index.ts"],"names":[],"mappings":"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"}

package/dist/cdk/index.js

@@ -8,10 +8,13 @@ import { computeScopeFullId, } from '../common/index.js';
 import { setupBlocksInfra, BlocksBackend, assertCdkConditionActive } from './blocks-backend.js';
 import { addBlocksStackMetadata } from './stack-metadata.js';
 import { finalizeConfigRegistry } from './config-registry.js';
+import { BlocksPresets } from './blocks-defaults.js';
 export { BlocksBackend } 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 { BlocksPresets, } from './blocks-defaults.js';
 export { synthGuard } from './synth-guard.js';
 export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 export class BlocksStack extends cdk.Stack {
@@ -20,16 +23,22 @@ export class BlocksStack extends cdk.Stack {
     gateway;
     handler;
     backendHandlerPath;
+    /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
+    executionRole;
+    /** Infrastructure defaults for Building Blocks created under this stack. */
+    defaults;
     constructor(scope, id, props) {
         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.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, id, props) {
         assertCdkConditionActive();
@@ -62,27 +71,108 @@ export class Scope extends Construct {
     parent;
     bbName;
     bbVersion;
+    /**
+     * 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.
+     */
+    root;
     constructor(id, options) {
         const parent = options?.parent || globalThis.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}.
+     */
+    resolveRoot() {
         let current = this;
         while (current.node.scope) {
             current = current.node.scope;
             if (current instanceof BlocksStack || current instanceof BlocksBackend) {
-                return current.handler;
+                return current;
             }
         }
-        // Fallback to globalThis for backward compatibility
-        return globalThis.CURRENT_BLOCKS_STACK.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.CURRENT_BLOCKS_STACK;
+    }
+    get handler() {
+        return this.root.handler;
+    }
+    /**
+     * The shared IAM role assumed by all Blocks compute. Building Blocks grant
+     * their permissions to this role; CDK's `grant*()` / `addToPrincipalPolicy()`
+     * route those grants to the role's default (inline) policy.
+     */
+    get executionRole() {
+        return this.root.executionRole;
+    }
+    /**
+     * The backend entry file the owning BlocksStack/BlocksBackend runs — the
+     * single handler entry shared across the whole app.
+     */
+    get backendHandlerPath() {
+        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() {
+        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() {
         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() {
+        // 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 = this;
+        while (current.node.scope) {
+            current = current.node.scope;
+            if (current instanceof BlocksStack || current instanceof BlocksBackend) {
+                return current.defaults;
+            }
+        }
+        const ambient = globalThis.CURRENT_BLOCKS_STACK?.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;
+    }
     buildUserAgentChain() {
         return [];
     }

package/dist/cdk/internal.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 { BLOCKS_NAMESPACE } from '../constants.js';
+//# sourceMappingURL=internal.d.ts.map

package/dist/cdk/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/cdk/internal.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAG/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/cdk/internal.js

@@ -0,0 +1,27 @@
+// 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';
+// 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/dist/cdk/mixins.d.ts

@@ -2,13 +2,27 @@ import { Mixin } from 'aws-cdk-lib';
 import type { IConstruct } from 'constructs';
 import type { IMixin } from 'constructs';
 /**
- * Disables deletion protection on any construct that has a `deletionProtection`
- * property (e.g. RDS clusters, RDS instances). Uses duck-typing so it
- * automatically covers current and future resource types.
+ * Disables deletion protection on any construct that exposes a deletion
+ * protection property (e.g. RDS clusters, RDS instances, DynamoDB tables).
+ * Uses duck-typing so it automatically covers current and future resource
+ * types, matching both the `deletionProtection` and
+ * `deletionProtectionEnabled` spellings.
+ *
+ * Note that a DynamoDB L2 `Table` only accepts `deletionProtection` as a prop
+ * and does not re-expose it, so tables are matched through their underlying
+ * L1 `CfnTable.deletionProtectionEnabled`.
  *
  * Intended for sandbox teardown — use in the CDK layer alongside
  * `RemovalPolicies.of(stack).destroy()` to ensure `sandbox:destroy` can
- * delete the entire stack without manual cleanup.
+ * delete the entire stack without manual cleanup. DynamoDB refuses
+ * `DeleteTable` while deletion protection is enabled, regardless of the
+ * CloudFormation `DeletionPolicy`.
+ *
+ * @deprecated Prefer the stack-wide `defaults` prop on `BlocksStack`/`BlocksBackend`
+ * (`defaults: BlocksPresets.sandbox` / `.production`, or `sandboxMode ? … : …`).
+ * Amazon-authored Building Blocks now read removal policy + deletion protection
+ * from `defaults`, so this mixin is no longer needed; it is retained only for
+ * backward compatibility.
  *
  * @example
  * ```ts

package/dist/cdk/mixins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mixins.d.ts","sourceRoot":"","sources":["../../src/cdk/mixins.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,gCAAiC,SAAQ,KAAM,YAAW,MAAM;IAC3E,QAAQ,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO;IAGjC,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;CAShC"}
+{"version":3,"file":"mixins.d.ts","sourceRoot":"","sources":["../../src/cdk/mixins.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAWzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,gCAAiC,SAAQ,KAAM,YAAW,MAAM;IAC3E,QAAQ,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO;IAGjC,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;CAWhC"}

package/dist/cdk/mixins.js

@@ -2,13 +2,35 @@
 // SPDX-License-Identifier: Apache-2.0
 import { Mixin } from 'aws-cdk-lib';
 /**
- * Disables deletion protection on any construct that has a `deletionProtection`
- * property (e.g. RDS clusters, RDS instances). Uses duck-typing so it
- * automatically covers current and future resource types.
+ * Property names used across CloudFormation resources to express deletion
+ * protection. L2 constructs and most L1s use `deletionProtection` (e.g. RDS
+ * clusters and instances, ELBv2 load balancers), while others spell it
+ * `deletionProtectionEnabled` (e.g. the DynamoDB `CfnTable` behind an L2
+ * `Table`, Aurora DSQL clusters).
+ */
+const DELETION_PROTECTION_PROPERTIES = ['deletionProtection', 'deletionProtectionEnabled'];
+/**
+ * Disables deletion protection on any construct that exposes a deletion
+ * protection property (e.g. RDS clusters, RDS instances, DynamoDB tables).
+ * Uses duck-typing so it automatically covers current and future resource
+ * types, matching both the `deletionProtection` and
+ * `deletionProtectionEnabled` spellings.
+ *
+ * Note that a DynamoDB L2 `Table` only accepts `deletionProtection` as a prop
+ * and does not re-expose it, so tables are matched through their underlying
+ * L1 `CfnTable.deletionProtectionEnabled`.
  *
  * Intended for sandbox teardown — use in the CDK layer alongside
  * `RemovalPolicies.of(stack).destroy()` to ensure `sandbox:destroy` can
- * delete the entire stack without manual cleanup.
+ * delete the entire stack without manual cleanup. DynamoDB refuses
+ * `DeleteTable` while deletion protection is enabled, regardless of the
+ * CloudFormation `DeletionPolicy`.
+ *
+ * @deprecated Prefer the stack-wide `defaults` prop on `BlocksStack`/`BlocksBackend`
+ * (`defaults: BlocksPresets.sandbox` / `.production`, or `sandboxMode ? … : …`).
+ * Amazon-authored Building Blocks now read removal policy + deletion protection
+ * from `defaults`, so this mixin is no longer needed; it is retained only for
+ * backward compatibility.
  *
  * @example
  * ```ts
@@ -23,15 +45,17 @@ import { Mixin } from 'aws-cdk-lib';
  */
 export class SandboxDisableDeletionProtection extends Mixin {
     supports(construct) {
-        return 'deletionProtection' in construct;
+        return DELETION_PROTECTION_PROPERTIES.some((property) => property in construct);
     }
     applyTo(node) {
         // Only flip explicitly-enabled protection. When undefined (the default),
         // deletion protection is already off — setting it to false would emit the
         // property in the CloudFormation template, which breaks Aurora DB instances
         // (RDS rejects DeletionProtection on cluster members).
-        if (node.deletionProtection === true) {
-            node.deletionProtection = false;
+        for (const property of DELETION_PROTECTION_PROPERTIES) {
+            if (node[property] === true) {
+                node[property] = false;
+            }
         }
     }
 }