@aws-blocks/core 0.2.0 → 0.3.0

package/dist/cdk/blocks-backend.d.ts

@@ -1,8 +1,10 @@
 import * as cdk from 'aws-cdk-lib';
-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 { Construct } from 'constructs';
 import type { BlocksDefaults } from './blocks-defaults.js';
+import type { Compute } from './compute/compute.js';
+import type { DefaultComputeFactory } from './compute/default-compute-factory.js';
 /**
  * Validate that the Node.js process was started with `--conditions=cdk`.
  *
@@ -12,6 +14,12 @@ import type { BlocksDefaults } from './blocks-defaults.js';
  * no real infrastructure (no tables, no IAM, no Lambda configs).
  */
 export declare 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 declare const SHARED_HANDLER_TIMEOUT_SECONDS: number;
 export interface BlocksBackendProps {
     backendHandlerPath: string;
     backendCDKPath: string;
@@ -24,11 +32,23 @@ export interface BlocksBackendProps {
      */
     defaults: BlocksDefaults;
 }
-/** Shared infra setup — creates Lambda + API Gateway on the given scope. */
+/**
+ * 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 — provisions the stack-level resources that are NOT owned
+ * by a compute: the shared execution role, resource groups, and console-redirect
+ * routes.
+ */
 export declare function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id?: string): {
-    handler: cdk.aws_lambda_nodejs.NodejsFunction;
-    gateway: cdk.aws_apigateway.RestApi;
-    apiUrl: string;
     executionRole: cdk.aws_iam.Role;
 };
 /**
@@ -49,14 +69,20 @@ export declare function setupBlocksInfra(scope: Construct, props: BlocksBackendP
  * ```
  */
 export declare class BlocksBackend extends Construct {
-    readonly apiUrl: string;
-    readonly gateway: 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: iam.IRole;
     /** Infrastructure defaults for Building Blocks created under this backend. */
     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;
+    /** The default compute's API Gateway REST API. To be removed once consumers move to the multi-compute model. */
+    get gateway(): apigateway.RestApi;
+    /** The default compute's RPC endpoint URL. To be removed once consumers move to the multi-compute model. */
+    get apiUrl(): string;
+    private requireDefaultCompute;
     /**
      * The fullId used by child Scopes to compute their env var names,
      * construct IDs, and physical resource names (e.g., DynamoDB table names).
@@ -78,6 +104,6 @@ export declare class BlocksBackend extends Construct {
      */
     get fullId(): string;
     private constructor();
-    static create(scope: Construct, id: string, props: BlocksBackendProps): Promise<BlocksBackend>;
+    static create(scope: Construct, id: string, props: CoreBlocksBackendProps): Promise<BlocksBackend>;
 }
 //# sourceMappingURL=blocks-backend.d.ts.map

package/dist/cdk/blocks-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks-backend.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAEnC,OAAO,KAAK,UAAU,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAMvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAkB/C;AAED,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC,EAAE,MAAM;;;;;EAyIxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC;IAC5C,SAAgB,OAAO,EAAE,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAC9D,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAC3C,yFAAyF;IACzF,SAAgB,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC;IACzC,8EAA8E;IAC9E,SAAgB,QAAQ,EAAE,cAAc,CAAC;IAEzC;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO;WAyBM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB;CAsB5E"}
+{"version":3,"file":"blocks-backend.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,KAAK,KAAK,UAAU,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAuB,MAAM,sCAAsC,CAAC;AAEvG;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAkB/C;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,QAAU,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,8EAA8E;IAC9E,qBAAqB,EAAE,qBAAqB,CAAC;CAC9C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC,EAAE,MAAM;;EAwFxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAC3C,yFAAyF;IACzF,SAAgB,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC;IACzC,8EAA8E;IAC9E,SAAgB,QAAQ,EAAE,cAAc,CAAC;IACzC,iGAAiG;IACjG,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,2GAA2G;IAC3G,IAAI,OAAO,IAAI,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAElD;IACD,gHAAgH;IAChH,IAAI,OAAO,IAAI,UAAU,CAAC,OAAO,CAEhC;IACD,4GAA4G;IAC5G,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,OAAO,CAAC,qBAAqB;IAO7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO;WAmBM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB;CA6BhF"}

package/dist/cdk/blocks-backend.js

@@ -1,17 +1,12 @@
 // 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 * 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 { blocksNodejsBundling } from './bundling.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`.
@@ -35,7 +30,17 @@ export function assertCdkConditionActive() {
             'Or use the Blocks CLI commands (npm run deploy / npm run sandbox) which set this automatically.');
     }
 }
-/** Shared infra setup — creates Lambda + API Gateway on the given scope. */
+/**
+ * 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;
+/**
+ * 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, props, id) {
     // 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
@@ -45,12 +50,19 @@ export function setupBlocksInfra(scope, props, id) {
         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 ──────────────────────────────────────────────
+    // ── 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. AWSLambdaBasicExecutionRole is attached so the handler retains
+    // policy. AWSLambdaBasicExecutionRole is attached so compute functions retain
     // CloudWatch Logs permissions.
+    //
+    // 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
@@ -60,55 +72,7 @@ export function setupBlocksInfra(scope, props, id) {
             iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole'),
         ],
     });
-    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,
-        },
-        // blocksNodejsBundling shims import.meta.* to CommonJS equivalents so a
-        // CJS-bundled `fileURLToPath(import.meta.url)` resolves instead of throwing at
-        // Lambda load. See ./bundling.ts.
-        bundling: blocksNodejsBundling({
-            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;
@@ -142,7 +106,7 @@ export function setupBlocksInfra(scope, props, 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/',
@@ -155,7 +119,7 @@ export function setupBlocksInfra(scope, props, id) {
     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)}`, executionRole };
+    return { executionRole };
 }
 /**
  * Standalone CDK construct that provisions the Blocks backend: a single Lambda
@@ -175,14 +139,31 @@ export function setupBlocksInfra(scope, props, id) {
  * ```
  */
 export class BlocksBackend extends Construct {
-    apiUrl;
-    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 backend. */
     defaults;
+    /** The default compute (owns the Lambda function + API Gateway); set in `create()`. @internal */
+    _defaultCompute;
+    /** The default compute's Lambda function. To be removed once consumers move to the multi-compute model. */
+    get handler() {
+        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() {
+        return this.requireDefaultCompute().apiGateway;
+    }
+    /** The default compute's RPC endpoint URL. To be removed once consumers move to the multi-compute model. */
+    get apiUrl() {
+        return this.requireDefaultCompute().apiUrl;
+    }
+    requireDefaultCompute() {
+        if (!this._defaultCompute) {
+            throw new Error('Blocks backend not fully initialized — access .handler/.gateway/.apiUrl after BlocksBackend.create() resolves.');
+        }
+        return this._defaultCompute;
+    }
     /**
      * The fullId used by child Scopes to compute their env var names,
      * construct IDs, and physical resource names (e.g., DynamoDB table names).
@@ -223,18 +204,20 @@ export class BlocksBackend extends Construct {
         // 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, id, props) {
         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/dist/cdk/blocks-backend.test.js

@@ -1,15 +1,52 @@
 // 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 { Template, Match } from 'aws-cdk-lib/assertions';
+import { Match, Template } from 'aws-cdk-lib/assertions';
+import * as apigateway from 'aws-cdk-lib/aws-apigateway';
 import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
+import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
+import { BLOCKS_RPC_PREFIX } from '../constants.js';
 import { BlocksBackend } from './blocks-backend.js';
 import { BlocksPresets } from './blocks-defaults.js';
+import { Compute } from './compute/compute.js';
 import { 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
+// makeBackend), exactly as @aws-blocks/blocks injects LambdaCompute.
+class StubLambdaCompute extends Compute {
+    fn;
+    apiGateway;
+    apiUrl;
+    constructor(scope, id) {
+        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, value) {
+        this.fn.addEnvironment(key, value);
+    }
+}
+const stubComputeFactory = (root) => new StubLambdaCompute(root, 'DefaultCompute');
 // Simulate the CDK condition being active (tests import CDK files directly)
 before(() => {
     process.env.NODE_OPTIONS = (process.env.NODE_OPTIONS ?? '') + ' --conditions=cdk';
@@ -21,20 +58,15 @@ const factoryBackendPath = join(__dirname, '__fixtures__', 'factory-backend.js')
 const fullIdConstructBackendPath = join(__dirname, '__fixtures__', 'fullid-construct-backend.js');
 const EXECUTION_ROLE_MARKER_ACTION = 'blocks-test:MarkerAction';
 const importMetaHandlerPath = join(__dirname, '__fixtures__', 'import-meta-handler.js');
+// Wraps BlocksBackend.create, injecting the stub default-compute factory the way
+// @aws-blocks/blocks injects LambdaCompute — so tests don't repeat it 15 times.
+const makeBackend = (scope, id, backendCDKPath) => BlocksBackend.create(scope, id, { backendHandlerPath: handlerPath, backendCDKPath, defaults: BlocksPresets.production, defaultComputeFactory: stubComputeFactory });
 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,
-            defaults: BlocksPresets.production,
-        });
-        const backend2 = await BlocksBackend.create(stack, 'Stage2', {
-            backendHandlerPath: handlerPath,
-            backendCDKPath: sideEffectBackendPath,
-            defaults: BlocksPresets.production,
-        });
+        const backend1 = await makeBackend(stack, 'Stage1', sideEffectBackendPath);
+        const backend2 = await makeBackend(stack, 'Stage2', sideEffectBackendPath);
         const findMarker = (scope) => 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');
@@ -44,11 +76,7 @@ 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,
-            defaults: BlocksPresets.production,
-        });
+        const backend = await makeBackend(parent, 'Blocks', sideEffectBackendPath);
         // Public surface mirrors BlocksStack.
         assert.ok(backend.handler, 'BlocksBackend should expose .handler');
         assert.ok(backend.gateway, 'BlocksBackend should expose .gateway');
@@ -62,16 +90,8 @@ describe('synth shape (drop into existing stack)', () => {
     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,
-            defaults: BlocksPresets.production,
-        });
-        await BlocksBackend.create(parent, 'BackendB', {
-            backendHandlerPath: handlerPath,
-            backendCDKPath: sideEffectBackendPath,
-            defaults: BlocksPresets.production,
-        });
+        await makeBackend(parent, 'BackendA', sideEffectBackendPath);
+        await makeBackend(parent, 'BackendB', sideEffectBackendPath);
         const template = Template.fromStack(parent);
         template.resourceCountIs('AWS::ApiGateway::RestApi', 2);
     });
@@ -80,21 +100,13 @@ describe('shared execution role', () => {
     test('exposes executionRole on the backend', async () => {
         const app = new cdk.App();
         const parent = new cdk.Stack(app, 'RoleSurfaceStack');
-        const backend = await BlocksBackend.create(parent, 'Blocks', {
-            backendHandlerPath: handlerPath,
-            backendCDKPath: sideEffectBackendPath,
-            defaults: BlocksPresets.production,
-        });
+        const backend = await makeBackend(parent, 'Blocks', sideEffectBackendPath);
         assert.ok(backend.executionRole, 'BlocksBackend should expose .executionRole');
     });
     test('synth produces a Lambda-assumable role with basic execution, and the handler uses it', async () => {
         const app = new cdk.App();
         const parent = new cdk.Stack(app, 'RoleSynthStack');
-        await BlocksBackend.create(parent, 'Blocks', {
-            backendHandlerPath: handlerPath,
-            backendCDKPath: sideEffectBackendPath,
-            defaults: BlocksPresets.production,
-        });
+        await makeBackend(parent, 'Blocks', sideEffectBackendPath);
         const template = Template.fromStack(parent);
         // The shared role (logical id derived from the 'BlocksRole' construct id)
         // is assumable by Lambda and carries AWSLambdaBasicExecutionRole (so
@@ -102,7 +114,7 @@ describe('shared execution role', () => {
         // roles exist (API Gateway CloudWatch role, config BucketDeployment role),
         // so we target ours by logical id.
         const roles = template.findResources('AWS::IAM::Role');
-        const blocksRoleId = Object.keys(roles).find(k => k.includes('BlocksRole'));
+        const blocksRoleId = Object.keys(roles).find((k) => k.includes('BlocksRole'));
         assert.ok(blocksRoleId, 'expected a role from the BlocksRole construct');
         const blocksRole = roles[blocksRoleId];
         assert.deepStrictEqual(blocksRole.Properties.AssumeRolePolicyDocument.Statement[0], {
@@ -119,11 +131,7 @@ describe('shared execution role', () => {
     test('a nested block resolves executionRole via the construct-tree walk', async () => {
         const app = new cdk.App();
         const parent = new cdk.Stack(app, 'RoleResolveStack');
-        const backend = await BlocksBackend.create(parent, 'Blocks', {
-            backendHandlerPath: handlerPath,
-            backendCDKPath: sideEffectBackendPath,
-            defaults: BlocksPresets.production,
-        });
+        const backend = await makeBackend(parent, 'Blocks', sideEffectBackendPath);
         // Build nested Scopes under the backend (outer → inner), the same shape a
         // real Building Block tree has, and grant a uniquely-named marker action to
         // `this.executionRole` from the innermost scope. If the getter's tree-walk
@@ -160,6 +168,7 @@ describe('CJS bundle: import.meta.url in the handler is shimmed (no Lambda-load
             backendHandlerPath: importMetaHandlerPath,
             backendCDKPath: sideEffectBackendPath,
             defaults: BlocksPresets.production,
+            defaultComputeFactory: stubComputeFactory,
         }));
     });
 });
@@ -167,11 +176,7 @@ 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,
-            defaults: BlocksPresets.production,
-        });
+        const backend = await makeBackend(stack, 'FactoryStage', factoryBackendPath);
         const marker = backend.node.tryFindChild('FactoryMarker');
         assert.ok(marker, 'Factory function should have created FactoryMarker on the backend');
     });
@@ -180,11 +185,7 @@ 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,
-            defaults: BlocksPresets.production,
-        });
+        const backend = await makeBackend(stack, 'blocks', sideEffectBackendPath);
         assert.strictEqual(backend.fullId, 'TopLevelStack-blocks');
         assert.ok(!cdk.Token.isUnresolved(backend.fullId), 'fullId must not contain a token');
     });
@@ -198,11 +199,7 @@ describe('fullId is token-free (construct IDs / env-var keys)', () => {
         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,
-            defaults: BlocksPresets.production,
-        });
+        const backend = await makeBackend(nested, 'blocks', 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');
@@ -213,11 +210,7 @@ describe('fullId is token-free (construct IDs / env-var keys)', () => {
         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,
-            defaults: BlocksPresets.production,
-        });
+        const backend = await makeBackend(nested, 'blocks', 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}"`);
@@ -234,11 +227,7 @@ describe('fullId is token-free (construct IDs / env-var keys)', () => {
         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,
-            defaults: BlocksPresets.production,
-        });
+        const backend = await makeBackend(nested, 'blocks', sideEffectBackendPath);
         const template = Template.fromStack(nested);
         const fns = template.findResources('AWS::Lambda::Function');
         const envValues = Object.values(fns)
@@ -259,11 +248,13 @@ describe('infrastructure defaults (backend-anchored)', () => {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
             defaults: BlocksPresets.production,
+            defaultComputeFactory: stubComputeFactory,
         });
         const b = await BlocksBackend.create(stack, 'B', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
             defaults: BlocksPresets.sandbox,
+            defaultComputeFactory: stubComputeFactory,
         });
         // Two backends in one stack must NOT clobber each other — defaults are
         // anchored on the backend, not the shared stack.
@@ -277,6 +268,7 @@ describe('infrastructure defaults (backend-anchored)', () => {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
             defaults: BlocksPresets.sandbox,
+            defaultComputeFactory: stubComputeFactory,
         });
         // A Scope under the backend resolves scope.defaults by walking up to it.
         const outer = new Scope('outer');

package/dist/cdk/blocks-defaults.d.ts

@@ -20,6 +20,28 @@ export interface BlocksDefaults {
      * 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
@@ -30,15 +52,19 @@ export interface BlocksDefaults {
  * ```
  */
 export declare const BlocksPresets: {
-    /** Disposable development stacks: tear down cleanly, no delete guard. */
+    /** Disposable development stacks: tear down cleanly, no delete guard, no backups. */
     sandbox: {
         removalPolicy: RemovalPolicy.DESTROY;
         deletionProtection: false;
+        allowedOrigins: string[];
+        pointInTimeRecovery: false;
     };
     /** Durable, protected posture for permanent deployments. */
     production: {
         removalPolicy: RemovalPolicy.RETAIN;
         deletionProtection: true;
+        allowedOrigins: never[];
+        pointInTimeRecovery: true;
     };
 };
 //# sourceMappingURL=blocks-defaults.d.ts.map

package/dist/cdk/blocks-defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks-defaults.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-defaults.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;OAKG;IACH,aAAa,EAAE,aAAa,CAAC;IAE7B;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;IACzB,yEAAyE;;;;;IAKzE,4DAA4D;;;;;CAKnB,CAAC"}
+{"version":3,"file":"blocks-defaults.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-defaults.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;OAKG;IACH,aAAa,EAAE,aAAa,CAAC;IAE7B;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAE5B;;;;;OAKG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB;;;;;;;;;;;OAWG;IACH,mBAAmB,EAAE,OAAO,GAAG;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACzD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;IACzB,qFAAqF;;;;;;;IAOrF,4DAA4D;;;;;;;CAOnB,CAAC"}

package/dist/cdk/blocks-defaults.js

@@ -10,14 +10,18 @@ import { RemovalPolicy } from 'aws-cdk-lib';
  * ```
  */
 export const BlocksPresets = {
-    /** Disposable development stacks: tear down cleanly, no delete guard. */
+    /** 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,
     },
 };

package/dist/cdk/blocks-defaults.test.js

@@ -11,12 +11,14 @@ 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', () => {
+    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', () => {
+    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);
     });
 });