@aws-blocks/core 0.2.0 → 0.4.0

package/README.md

@@ -313,6 +313,19 @@ new Hosting(stack, 'Web', {
 
 The `framework` option selects the frontend type: `'spa' | 'static' | 'nextjs'`. When omitted, the framework is auto-detected by reading your app's OWN `package.json` (not `node_modules`): a `next` dependency → `nextjs`; otherwise `spa`; and `static` when there is no `package.json`. Set `framework: 'spa'` explicitly to override auto-detection — e.g. when a stray `next` dependency would otherwise trigger an unwanted Next.js/OpenNext build. Full reference lives in the source JSDoc.
 
+Old builds are retained for rollback and expired by an S3 lifecycle rule after `buildRetentionDays` (default **30**). The build currently being served is never expired regardless of deploy cadence — only superseded builds are cleaned up. Only builds superseded by a normal `Update` cutover are auto-tagged (and thus auto-expired): pre-existing/orphaned builds and aborted or rolled-back deploys are never tagged and need manual cleanup (e.g. an S3 inventory / Batch Operations sweep). Raise the window with `buildRetentionDays` (it must be ≥ `skewProtection.maxAge` in days):
+
+```typescript
+new Hosting(stack, 'Web', {
+  root: join(__dirname, '..'),
+  api: blocksStack,
+  buildRetentionDays: 90,
+});
+```
+
+Core's top-level `buildRetentionDays` maps to the L3 construct's `storage.buildRetentionDays`.
+
+
 ## Building Blocks
 
 Import Building Blocks from their specific packages (or from the `@aws-blocks/blocks` umbrella):

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QACxC,IAAI,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5B;;;;;;;;;;WAUG;QACH,GAAG,EAAE,GAAG,CAAC;QACT;;;;;WAKG;QACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B;;;;;;;;;WASG;QACH,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,CAAC;IACF,QAAQ,EAAE;QACR,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC;KAC3B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,KAAK,CAAC,CAAC;AAG1G,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACtC,KAAK;CACV,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,eAAoC,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;CAChI;AAED,eAAO,MAAM,YAAY,EAAE,uBAKnB,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QACxC,IAAI,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5B;;;;;;;;;;WAUG;QACH,GAAG,EAAE,GAAG,CAAC;QACT;;;;;WAKG;QACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B;;;;;;;;;WASG;QACH,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,CAAC;IACF,QAAQ,EAAE;QACR,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC;KAC3B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,KAAK,CAAC,CAAC;AAG1G,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACtC,KAAK;CACV,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,eAAoC,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAsCrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;CAChI;AAED,eAAO,MAAM,YAAY,EAAE,uBAQnB,CAAC"}

package/dist/api.js

@@ -2,9 +2,41 @@
 // SPDX-License-Identifier: Apache-2.0
 /** Marker symbol to identify ApiNamespace instances during discovery. */
 export const API_NAMESPACE_MARKER = Symbol.for('blocks:ApiNamespace');
+/**
+ * Record this namespace on its resolved compute so request routing can later
+ * map a namespace to the compute that hosts it.
+ *
+ * CDK-synth concern only: in the CDK bundle `scope.compute` resolves to the
+ * namespace's compute (the stack default today), and we append the name to its
+ * `namespaces` list. In the mock/runtime bundles — or a scopeless test — the
+ * property is absent, so `scope.compute` is `undefined` and this is a silent
+ * no-op. The public `ApiNamespace` signature is unchanged; this is a purely
+ * internal side effect.
+ *
+ * No `try/catch`: `BlocksBackend.create()` initializes the default compute
+ * before it imports the backend module that constructs any `ApiNamespace`, so
+ * the `compute` getter always resolves at this call site. If it ever threw
+ * here it would signal a genuine lifecycle violation (an `ApiNamespace` built
+ * before `create()` resolved), which should surface rather than be swallowed.
+ */
+function recordNamespaceOnCompute(scope, name) {
+    // An API created without a Scope stays unrecorded and routes to the
+    // default compute.
+    if (!scope || typeof scope !== 'object')
+        return;
+    const compute = scope.compute;
+    // Guard against duplicates so `namespaces` stays a set of names: a namespace
+    // could otherwise be recorded twice (e.g. a re-imported module during synth).
+    if (compute && Array.isArray(compute.namespaces) && !compute.namespaces.includes(name)) {
+        compute.namespaces.push(name);
+    }
+}
 export const ApiNamespace = class ApiNamespace {
     constructor(scope, name, handler) {
         handler[API_NAMESPACE_MARKER] = name;
+        // Record the namespace → compute association for per-compute routing.
+        // No-op outside CDK synth. Signature and returned handler are unchanged.
+        recordNamespaceOnCompute(scope, name);
         return handler;
     }
 };

package/dist/api.test.js

@@ -17,3 +17,25 @@ test('Different ApiNamespace names should not collide', () => {
     assert.strictEqual(api1[API_NAMESPACE_MARKER], 'api1');
     assert.strictEqual(api2[API_NAMESPACE_MARKER], 'api2');
 });
+// ApiNamespace records its name on the scope's resolved compute (CDK
+// synth), while staying a silent no-op where no compute is resolvable.
+test('ApiNamespace records its name on a resolvable compute', () => {
+    const compute = { namespaces: [] };
+    new ApiNamespace({ id: 'app', compute }, 'myapi', () => ({ ping: () => 'ok' }));
+    assert.deepStrictEqual(compute.namespaces, ['myapi']);
+});
+test('ApiNamespace is a no-op recorder when the scope has no compute', () => {
+    // The common Scope (mock/runtime) has no `compute`; recording must not throw
+    // and the handler is still tagged and returned unchanged.
+    const handler = new ApiNamespace(new Scope('no-compute'), 'plainapi', () => ({ x: () => 1 }));
+    assert.strictEqual(handler[API_NAMESPACE_MARKER], 'plainapi');
+});
+test('ApiNamespace records a namespace at most once per compute', () => {
+    // `namespaces` is a set of names: recording the same name twice (e.g. a
+    // re-imported module during synth) must not append a duplicate.
+    const compute = { namespaces: [] };
+    const scopeLike = { id: 'app', compute };
+    new ApiNamespace(scopeLike, 'dup', () => ({ ping: () => 'ok' }));
+    new ApiNamespace(scopeLike, 'dup', () => ({ ping: () => 'ok' }));
+    assert.deepStrictEqual(compute.namespaces, ['dup']);
+});

package/dist/bb-utils.d.ts

@@ -8,4 +8,5 @@ export { getMockDataDir } from './common/mock-data.js';
 export { API_NAMESPACE_MARKER } from './api.js';
 export { EventSourceMapping } from './lambda-handler.js';
 export { constantTimeEquals } from './common/crypto.js';
+export { sanitizeConfigKey } from './common/config.js';
 //# sourceMappingURL=bb-utils.d.ts.map

package/dist/bb-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bb-utils.d.ts","sourceRoot":"","sources":["../src/bb-utils.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"bb-utils.d.ts","sourceRoot":"","sources":["../src/bb-utils.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/bb-utils.js

@@ -10,3 +10,6 @@ export { getMockDataDir } from './common/mock-data.js';
 export { API_NAMESPACE_MARKER } from './api.js';
 export { EventSourceMapping } from './lambda-handler.js';
 export { constantTimeEquals } from './common/crypto.js';
+// Defined in the config module (it owns the config-key contract), re-exported
+// here so BB authors get it alongside the other BB utilities.
+export { sanitizeConfigKey } from './common/config.js';

package/dist/cdk/apigateway-account.d.ts

@@ -0,0 +1,33 @@
+import type * as cdk from 'aws-cdk-lib';
+import { CfnAccount } from 'aws-cdk-lib/aws-apigateway';
+/**
+ * Ensure the account-level API Gateway CloudWatch Logs role exists on `stack`,
+ * creating it at most once per stack.
+ *
+ * API Gateway access logging — for both REST (v1) and WebSocket (v2) stages —
+ * requires an `AWS::ApiGateway::Account` whose `cloudWatchRoleArn` points at a
+ * role trusted by `apigateway.amazonaws.com` and carrying
+ * `AmazonAPIGatewayPushToCloudWatchLogs`. Nothing else in a Blocks stack
+ * provisions it, so a clean-account first deploy of any access-logging stage
+ * otherwise fails at CreateStage with "CloudWatch Logs role ARN must be set in
+ * account settings to enable logging".
+ *
+ * Callers should add their stage's dependency on the returned account so the
+ * account setting is applied before the stage is created.
+ *
+ * ⚠️ Single-Blocks-stack-per-region assumption. `AWS::ApiGateway::Account` is an
+ * account/region-level singleton (one effective `cloudWatchRoleArn` per region),
+ * but this provisions one per Blocks stack. If two Blocks stacks in the same
+ * account+region both enable access logging:
+ *   - on deploy, the later stack's role wins (overwrites the account setting); and
+ *   - on teardown of that later stack, its role is deleted and the account
+ *     setting is left pointing at a now-deleted role — silently breaking access
+ *     logging (or blocking `CreateStage`) for the surviving stack until it
+ *     redeploys.
+ * Enabling `accessLogging` is therefore safe for one Blocks stack per region.
+ * Multi-stack support (a shared/imported account) is deferred; if you run
+ * multiple Blocks stacks per region, manage the account role out-of-band and
+ * leave `accessLogging` to a single owner.
+ */
+export declare function ensureApiGatewayAccount(stack: cdk.Stack): CfnAccount;
+//# sourceMappingURL=apigateway-account.d.ts.map

package/dist/cdk/apigateway-account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apigateway-account.d.ts","sourceRoot":"","sources":["../../src/cdk/apigateway-account.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,GAAG,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAaxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,UAAU,CAmBpE"}

package/dist/cdk/apigateway-account.js

@@ -0,0 +1,60 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { CfnAccount } from 'aws-cdk-lib/aws-apigateway';
+import { ManagedPolicy, Role, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
+/**
+ * Global registry key for the per-stack API Gateway CloudWatch Logs account
+ * resource. Deliberately a `Symbol.for(...)` string key so the SAME symbol is
+ * shared across packages (core, hosting) — each package can carry its own copy
+ * of {@link ensureApiGatewayAccount} yet still find and reuse the one account a
+ * sibling package already created on the stack, instead of emitting a second
+ * `AWS::ApiGateway::Account` (which is account/region-level and would clash).
+ */
+const ACCOUNT_KEY = Symbol.for('BLOCKS_APIGATEWAY_ACCOUNT');
+/**
+ * Ensure the account-level API Gateway CloudWatch Logs role exists on `stack`,
+ * creating it at most once per stack.
+ *
+ * API Gateway access logging — for both REST (v1) and WebSocket (v2) stages —
+ * requires an `AWS::ApiGateway::Account` whose `cloudWatchRoleArn` points at a
+ * role trusted by `apigateway.amazonaws.com` and carrying
+ * `AmazonAPIGatewayPushToCloudWatchLogs`. Nothing else in a Blocks stack
+ * provisions it, so a clean-account first deploy of any access-logging stage
+ * otherwise fails at CreateStage with "CloudWatch Logs role ARN must be set in
+ * account settings to enable logging".
+ *
+ * Callers should add their stage's dependency on the returned account so the
+ * account setting is applied before the stage is created.
+ *
+ * ⚠️ Single-Blocks-stack-per-region assumption. `AWS::ApiGateway::Account` is an
+ * account/region-level singleton (one effective `cloudWatchRoleArn` per region),
+ * but this provisions one per Blocks stack. If two Blocks stacks in the same
+ * account+region both enable access logging:
+ *   - on deploy, the later stack's role wins (overwrites the account setting); and
+ *   - on teardown of that later stack, its role is deleted and the account
+ *     setting is left pointing at a now-deleted role — silently breaking access
+ *     logging (or blocking `CreateStage`) for the surviving stack until it
+ *     redeploys.
+ * Enabling `accessLogging` is therefore safe for one Blocks stack per region.
+ * Multi-stack support (a shared/imported account) is deferred; if you run
+ * multiple Blocks stacks per region, manage the account role out-of-band and
+ * leave `accessLogging` to a single owner.
+ */
+export function ensureApiGatewayAccount(stack) {
+    const existing = stack[ACCOUNT_KEY];
+    if (existing)
+        return existing;
+    const role = new Role(stack, 'BlocksApiGatewayCloudWatchRole', {
+        assumedBy: new ServicePrincipal('apigateway.amazonaws.com'),
+        managedPolicies: [
+            ManagedPolicy.fromAwsManagedPolicyName('service-role/AmazonAPIGatewayPushToCloudWatchLogs'),
+        ],
+    });
+    // `cloudWatchRoleArn: role.roleArn` already gives CDK an implicit dependency
+    // on the role, so no explicit node.addDependency is needed.
+    const account = new CfnAccount(stack, 'BlocksApiGatewayAccount', {
+        cloudWatchRoleArn: role.roleArn,
+    });
+    stack[ACCOUNT_KEY] = account;
+    return account;
+}

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,28 @@ 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;
+    /**
+     * Path to the app's backend module (`props.backendCDKPath`). Exposed so Building Blocks that
+     * co-bundle the backend at synth (e.g. the Agent BB's AgentCore Runtime) can discover it via
+     * `globalThis.CURRENT_BLOCKS_STACK.backendModulePath`.
+     */
+    readonly backendModulePath: 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;
+    /** The default compute's handler CloudWatch log group. `bb-logger` reconfigures its retention. */
+    get handlerLogGroup(): cdk.aws_logs.ILogGroup;
+    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 +112,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;AAEpD,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;;EAyFxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAC3C;;;;OAIG;IACH,SAAgB,iBAAiB,EAAE,MAAM,CAAC;IAC1C,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;IACD,kGAAkG;IAClG,IAAI,eAAe,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAE5C;IAED,OAAO,CAAC,qBAAqB;IAO7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO;WAoBM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB;CA6BhF"}

package/dist/cdk/blocks-backend.js

@@ -1,18 +1,14 @@
 // 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';
+import { getComputes } from './compute/compute-registry.js';
 /**
  * Validate that the Node.js process was started with `--conditions=cdk`.
  *
@@ -35,7 +31,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,70 +51,30 @@ 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
-        // (e.g. ECS tasks via ecs-tasks.amazonaws.com), by adding principals here.
+        // CompositePrincipal (rather than a bare ServicePrincipal) so a Building Block
+        // whose compute runs AS this shared role can add its own trust principal here
+        // (e.g. the Agent BB adds bedrock-agentcore in its CDK construct) — core stays
+        // agnostic and only Lambda is trusted by default.
         assumedBy: new iam.CompositePrincipal(new iam.ServicePrincipal('lambda.amazonaws.com')),
         managedPolicies: [
             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 +108,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 +121,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 +141,41 @@ export function setupBlocksInfra(scope, props, id) {
  * ```
  */
 export class BlocksBackend extends Construct {
-    apiUrl;
-    gateway;
-    handler;
     backendHandlerPath;
+    /**
+     * Path to the app's backend module (`props.backendCDKPath`). Exposed so Building Blocks that
+     * co-bundle the backend at synth (e.g. the Agent BB's AgentCore Runtime) can discover it via
+     * `globalThis.CURRENT_BLOCKS_STACK.backendModulePath`.
+     */
+    backendModulePath;
     /** 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;
+    }
+    /** The default compute's handler CloudWatch log group. `bb-logger` reconfigures its retention. */
+    get handlerLogGroup() {
+        return this.requireDefaultCompute().logGroup;
+    }
+    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).
@@ -216,6 +209,7 @@ export class BlocksBackend extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
         this.backendHandlerPath = props.backendHandlerPath;
+        this.backendModulePath = props.backendCDKPath;
         // Expose self to Building Blocks at CDK time
         globalThis.CURRENT_BLOCKS_STACK = this;
         // Store defaults on the backend (not the stack) so several BlocksBackends
@@ -223,18 +217,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);
@@ -250,7 +246,7 @@ export class BlocksBackend extends Construct {
         }
         addBlocksStackMetadata(cdk.Stack.of(backend));
         // Finalize BB config → S3 (after all BBs have registered their config)
-        finalizeConfigRegistry(backend, backend.handler);
+        finalizeConfigRegistry(backend, backend.executionRole, getComputes(backend));
         return backend;
     }
 }