@aws-blocks/core 0.2.0 → 0.4.0

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

@@ -1,12 +1,55 @@
 // 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 * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
+import { BLOCKS_RPC_PREFIX } from '../constants.js';
 import { BlocksBackend } from './blocks-backend.js';
+import { Compute } from './compute/compute.js';
+import { getComputes } from './compute/compute-registry.js';
 import { BlocksStack, BlocksPresets, 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 makeStack /
+// makeBackend), exactly as @aws-blocks/blocks injects LambdaCompute.
+class StubLambdaCompute extends Compute {
+    fn;
+    apiGateway;
+    apiUrl;
+    logGroup;
+    constructor(scope, id) {
+        super(id, { parent: scope });
+        this.logGroup = new cdk.aws_logs.LogGroup(this, 'HandlerLogGroup', {
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+        });
+        this.fn = new lambda.NodejsFunction(this, 'Handler', {
+            entry: this.backendHandlerPath,
+            runtime: cdk.aws_lambda.Runtime.NODEJS_22_X,
+            handler: 'handler',
+            role: this.executionRole,
+            logGroup: this.logGroup,
+            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';
@@ -15,19 +58,15 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const handlerPath = join(__dirname, '__fixtures__', 'handler.js');
 const sideEffectBackendPath = join(__dirname, '__fixtures__', 'side-effect-backend.js');
 const factoryBackendPath = join(__dirname, '__fixtures__', 'factory-backend.js');
+// Wrap create(), injecting the stub default-compute factory the way
+// @aws-blocks/blocks injects LambdaCompute — so tests don't repeat it.
+const makeStack = (scope, id, backendCDKPath) => BlocksStack.create(scope, id, { backendHandlerPath: handlerPath, backendCDKPath, defaults: BlocksPresets.production, defaultComputeFactory: stubComputeFactory });
+const makeBackend = (scope, id, backendCDKPath) => BlocksBackend.create(scope, id, { backendHandlerPath: handlerPath, backendCDKPath, defaults: BlocksPresets.production, defaultComputeFactory: stubComputeFactory });
 describe('ESM cache-busting (multi-stage)', () => {
     test('BlocksStack.create() with same backendCDKPath but different IDs produces constructs in each', async () => {
         const app = new cdk.App();
-        const stack1 = await BlocksStack.create(app, 'PipelineStage1', {
-            backendHandlerPath: handlerPath,
-            backendCDKPath: sideEffectBackendPath,
-            defaults: BlocksPresets.production,
-        });
-        const stack2 = await BlocksStack.create(app, 'PipelineStage2', {
-            backendHandlerPath: handlerPath,
-            backendCDKPath: sideEffectBackendPath,
-            defaults: BlocksPresets.production,
-        });
+        const stack1 = await makeStack(app, 'PipelineStage1', sideEffectBackendPath);
+        const stack2 = await makeStack(app, 'PipelineStage2', sideEffectBackendPath);
         const findMarker = (scope) => scope.node.tryFindChild('SideEffectMarker');
         assert.ok(findMarker(stack1), 'First stack should have SideEffectMarker from module side effect');
         assert.ok(findMarker(stack2), 'Second stack should have SideEffectMarker from re-executed module (cache busted)');
@@ -36,11 +75,7 @@ describe('ESM cache-busting (multi-stage)', () => {
 describe('factory function support', () => {
     test('BlocksStack.create() calls default export function with the stack instance', async () => {
         const app = new cdk.App();
-        const stack = await BlocksStack.create(app, 'FactoryBlocksStack', {
-            backendHandlerPath: handlerPath,
-            backendCDKPath: factoryBackendPath,
-            defaults: BlocksPresets.production,
-        });
+        const stack = await makeStack(app, 'FactoryBlocksStack', factoryBackendPath);
         const marker = stack.node.tryFindChild('FactoryMarker');
         assert.ok(marker, 'Factory function should have created FactoryMarker on the stack');
     });
@@ -49,11 +84,7 @@ describe('legacy side-effect mode (no default export)', () => {
     test('module with only side effects still registers constructs via globalThis', async () => {
         const app = new cdk.App();
         const stack = new cdk.Stack(app, 'LegacyTestStack');
-        const backend = await BlocksBackend.create(stack, 'LegacyStage', {
-            backendHandlerPath: handlerPath,
-            backendCDKPath: sideEffectBackendPath,
-            defaults: BlocksPresets.production,
-        });
+        const backend = await makeBackend(stack, 'LegacyStage', sideEffectBackendPath);
         const marker = backend.node.tryFindChild('SideEffectMarker');
         assert.ok(marker, 'Side-effect-only module should register construct via globalThis.CURRENT_BLOCKS_STACK');
     });
@@ -65,22 +96,14 @@ describe('shared execution role (BlocksStack)', () => {
     // executionRole — a separate code path from BlocksBackend's constructor.
     test('BlocksStack wires executionRole via its constructor', async () => {
         const app = new cdk.App();
-        const stack = await BlocksStack.create(app, 'StackRoleStack', {
-            backendHandlerPath: handlerPath,
-            backendCDKPath: sideEffectBackendPath,
-            defaults: BlocksPresets.production,
-        });
+        const stack = await makeStack(app, 'StackRoleStack', sideEffectBackendPath);
         assert.ok(stack.executionRole, 'BlocksStack should expose a populated .executionRole');
     });
 });
 describe('executionRole globalThis fallback', () => {
     test('resolves via globalThis.CURRENT_BLOCKS_STACK when no owner is in the tree', async () => {
         const app = new cdk.App();
-        const stack = await BlocksStack.create(app, 'FallbackStack', {
-            backendHandlerPath: handlerPath,
-            backendCDKPath: sideEffectBackendPath,
-            defaults: BlocksPresets.production,
-        });
+        const stack = await makeStack(app, 'FallbackStack', sideEffectBackendPath);
         // A Scope whose construct-tree ancestry has no BlocksStack/BlocksBackend
         // (parented under a plain cdk.Stack) exhausts the tree-walk and falls back
         // to globalThis.CURRENT_BLOCKS_STACK. The `as any` is test plumbing — a
@@ -91,6 +114,44 @@ describe('executionRole globalThis fallback', () => {
         assert.strictEqual(orphan.executionRole, stack.executionRole, 'fallback resolves to the ambient stack role');
     });
 });
+describe('root is bound to the owning stack (multi-stack synth)', () => {
+    test('a block under each of two stacks resolves its OWN stack, not the last globalThis', async () => {
+        // `root` is resolved once at Scope construction (not re-walked per getter),
+        // and `create()` mutates globalThis.CURRENT_BLOCKS_STACK for each stack it
+        // builds. With two stacks in one synth, a block constructed under the first
+        // must stay bound to the first even after the second stack is created and
+        // overwrites globalThis — otherwise its root-derived accessors (handler,
+        // executionRole, backendStackName) would silently point at the wrong stack.
+        const app = new cdk.App();
+        const stackA = await makeStack(app, 'RootBindingA', sideEffectBackendPath);
+        // A block explicitly parented under stackA (construct-tree walk resolves
+        // stackA regardless of the ambient globalThis).
+        const blockA = new Scope('blockA', { parent: stackA });
+        // Building the second stack overwrites globalThis.CURRENT_BLOCKS_STACK.
+        const stackB = await makeStack(app, 'RootBindingB', sideEffectBackendPath);
+        const blockB = new Scope('blockB', { parent: stackB });
+        assert.strictEqual(blockA.executionRole, stackA.executionRole, 'blockA stays bound to stackA');
+        assert.strictEqual(blockB.executionRole, stackB.executionRole, 'blockB binds to stackB');
+        assert.notStrictEqual(stackA.executionRole, stackB.executionRole, 'the two stacks have distinct roles');
+        assert.strictEqual(blockA.backendStackName, 'RootBindingA', 'blockA derives its own stack name');
+        assert.strictEqual(blockB.backendStackName, 'RootBindingB', 'blockB derives its own stack name');
+    });
+    test('each stack owns an isolated compute registry (no cross-stack bleed)', async () => {
+        // Computes self-register on their owning stack (keyed per stack, not a
+        // process-global list), so a multi-stack synth keeps each stack's computes
+        // separate — finalize steps for one stack never see another's compute.
+        const app = new cdk.App();
+        const stackA = await makeStack(app, 'ComputeRegistryA', sideEffectBackendPath);
+        const stackB = await makeStack(app, 'ComputeRegistryB', sideEffectBackendPath);
+        const computesA = getComputes(stackA);
+        const computesB = getComputes(stackB);
+        assert.strictEqual(computesA.length, 1, 'stackA registered exactly its default compute');
+        assert.strictEqual(computesB.length, 1, 'stackB registered exactly its default compute');
+        assert.strictEqual(computesA[0], stackA._defaultCompute, 'stackA lists its own default');
+        assert.strictEqual(computesB[0], stackB._defaultCompute, 'stackB lists its own default');
+        assert.notStrictEqual(computesA[0], computesB[0], 'the two stacks hold distinct computes');
+    });
+});
 describe('assertCdkConditionActive', () => {
     test('BlocksStack.create() throws when --conditions=cdk is missing', async () => {
         const origNodeOptions = process.env.NODE_OPTIONS;
@@ -99,11 +160,7 @@ describe('assertCdkConditionActive', () => {
         process.execArgv = [];
         try {
             const app = new cdk.App();
-            await assert.rejects(BlocksStack.create(app, 'MissingConditionStack', {
-                backendHandlerPath: handlerPath,
-                backendCDKPath: sideEffectBackendPath,
-                defaults: BlocksPresets.production,
-            }), (err) => {
+            await assert.rejects(makeStack(app, 'MissingConditionStack', sideEffectBackendPath), (err) => {
                 assert.ok(err.message.includes('Missing --conditions=cdk'), `Expected condition error, got: ${err.message}`);
                 return true;
             });

package/dist/cdk/compute/compute-registry.d.ts

@@ -0,0 +1,19 @@
+import type { Construct } from 'constructs';
+import type { Compute } from './compute.js';
+/**
+ * Register a compute on its owning stack. Called from the {@link Compute} base
+ * constructor, so every compute self-registers the moment it is constructed —
+ * the finalize steps then enumerate them without a separate discovery pass
+ * (mirrors how `registerConfig` accumulates config during the backend import).
+ *
+ * @param compute - The compute to register (used to locate its stack).
+ */
+export declare function registerCompute(compute: Compute): void;
+/**
+ * The computes registered on the stack that owns `scope`, in construction
+ * order. Returns an empty array before any compute is constructed.
+ *
+ * @param scope - Any construct in the stack (used to locate the stack).
+ */
+export declare function getComputes(scope: Construct): readonly Compute[];
+//# sourceMappingURL=compute-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compute-registry.d.ts","sourceRoot":"","sources":["../../../src/cdk/compute/compute-registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAmB5C;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,OAAO,EAAE,CAEhE"}

package/dist/cdk/compute/compute-registry.js

@@ -0,0 +1,38 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as cdk from 'aws-cdk-lib';
+const REGISTRY_KEY = Symbol.for('BLOCKS_COMPUTE_REGISTRY');
+/**
+ * Get or create the compute list for a given stack. The list is stored on the
+ * stack object (keyed by a Symbol), so each stack in a multi-stack synth gets
+ * its own — a compute never leaks into another stack's list. Mirrors the config
+ * registry (`config-registry.ts`), which scopes its state the same way.
+ */
+function getRegistry(stack) {
+    let list = stack[REGISTRY_KEY];
+    if (!list) {
+        list = [];
+        stack[REGISTRY_KEY] = list;
+    }
+    return list;
+}
+/**
+ * Register a compute on its owning stack. Called from the {@link Compute} base
+ * constructor, so every compute self-registers the moment it is constructed —
+ * the finalize steps then enumerate them without a separate discovery pass
+ * (mirrors how `registerConfig` accumulates config during the backend import).
+ *
+ * @param compute - The compute to register (used to locate its stack).
+ */
+export function registerCompute(compute) {
+    getRegistry(cdk.Stack.of(compute)).push(compute);
+}
+/**
+ * The computes registered on the stack that owns `scope`, in construction
+ * order. Returns an empty array before any compute is constructed.
+ *
+ * @param scope - Any construct in the stack (used to locate the stack).
+ */
+export function getComputes(scope) {
+    return getRegistry(cdk.Stack.of(scope));
+}

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

@@ -1,3 +1,4 @@
+import type { ScopeOptions } from '../../common/index.js';
 import { Scope } from '../index.js';
 /**
  * Base class for a Blocks *compute* — a runtime that executes handler code
@@ -23,6 +24,7 @@ export declare abstract class Compute extends Scope {
      * unpopulated (no compute assignment surface yet).
      */
     readonly namespaces: string[];
+    constructor(id: string, options?: ScopeOptions);
     /**
      * Inject a runtime configuration value (an environment variable) into this
      * compute. The framework calls this instead of `handler.addEnvironment()`

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

@@ -1 +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"}
+{"version":3,"file":"compute.d.ts","sourceRoot":"","sources":["../../../src/cdk/compute/compute.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,OAAQ,SAAQ,KAAK;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAM;gBAEvB,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAQ9C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CACjD"}

package/dist/cdk/compute/compute.js

@@ -1,6 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 import { Scope } from '../index.js';
+import { registerCompute } from './compute-registry.js';
 /**
  * Base class for a Blocks *compute* — a runtime that executes handler code
  * (Lambda today; containers later). A compute owns the physical function/service
@@ -25,4 +26,11 @@ export class Compute extends Scope {
      * unpopulated (no compute assignment surface yet).
      */
     namespaces = [];
+    constructor(id, options) {
+        super(id, options);
+        // Self-register on the owning stack so finalize steps (config, routing,
+        // dashboards) can enumerate every compute without a separate discovery
+        // pass. Scoped per stack, so a multi-stack synth keeps lists isolated.
+        registerCompute(this);
+    }
 }

package/dist/cdk/compute/default-compute-factory.d.ts

@@ -0,0 +1,34 @@
+import type * as cdk from 'aws-cdk-lib';
+import type { Compute } from './compute.js';
+import type { BlocksStack } from '../index.js';
+import type { BlocksBackend } from '../blocks-backend.js';
+/**
+ * Lambda-shaped surface of the default compute that the legacy
+ * `handler` / `gateway` / `apiUrl` accessors on BlocksStack/BlocksBackend read.
+ * The default compute (`LambdaCompute` from `@aws-blocks/bb-lambda-compute`)
+ * satisfies this structurally, so core exposes those accessors without
+ * importing the concrete class. To be removed with those accessors once
+ * consumers move to the multi-compute model.
+ *
+ * @internal
+ */
+export interface LambdaShapedCompute extends Compute {
+    readonly fn: cdk.aws_lambda_nodejs.NodejsFunction;
+    readonly apiGateway: cdk.aws_apigateway.RestApi;
+    readonly apiUrl: string;
+    readonly logGroup: cdk.aws_logs.ILogGroup;
+}
+/**
+ * Builds the default {@link Compute} for a stack/backend. `create()` reads it
+ * from its props (`CoreBlocksStackProps.defaultComputeFactory`) and calls it to
+ * build the default without importing a concrete compute class — the factory is
+ * supplied by whoever owns both core and a concrete compute package (the
+ * umbrella `@aws-blocks/blocks`, which injects `LambdaCompute`). It lives on
+ * `CoreBlocksStackProps`/`CoreBlocksBackendProps`, which the umbrella derives
+ * from the customer-facing props, so it is absent from `BlocksStackProps` and
+ * customers cannot set it.
+ *
+ * @internal
+ */
+export type DefaultComputeFactory = (root: BlocksStack | BlocksBackend) => Compute;
+//# sourceMappingURL=default-compute-factory.d.ts.map

package/dist/cdk/compute/default-compute-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-compute-factory.d.ts","sourceRoot":"","sources":["../../../src/cdk/compute/default-compute-factory.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,GAAG,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAoB,SAAQ,OAAO;IACnD,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAClD,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC;CAC1C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,WAAW,GAAG,aAAa,KAAK,OAAO,CAAC"}

package/dist/cdk/compute/default-compute-factory.js

@@ -0,0 +1,3 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/dist/cdk/config-registry.d.ts

@@ -1,5 +1,6 @@
 import * as cdk from 'aws-cdk-lib';
 import type { Construct } from 'constructs';
+import type { Compute } from './compute/compute.js';
 /**
  * Register a config entry for a Building Block. This replaces
  * `handler.addEnvironment(key, value)` for BB resource mappings.
@@ -12,15 +13,44 @@ import type { Construct } from 'constructs';
  * @param value - The config value (can be a CDK token that resolves at deploy time)
  */
 export declare function registerConfig(scope: Construct, key: string, value: unknown): void;
+/**
+ * Ensure the shared config bucket exists and return where the config JSON lives
+ * (`{ bucketName, key }`). The bucket is created **once per stack** (memoized on
+ * the registry) and this is idempotent — the first caller creates it, later
+ * callers get the same bucket regardless of order.
+ *
+ * Any compute that loads config at runtime (`loadConfigToProcessEnv()`) injects
+ * these two values as `BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY`. The Lambda
+ * handler gets them from {@link finalizeConfigRegistry}; other compute that runs
+ * as the shared execution role (e.g. the Agent BB's AgentCore Runtime) calls this
+ * at construction to inject them too, so it loads the same app config the handler
+ * does. IAM is not granted here — `finalizeConfigRegistry` grants read on the config
+ * object to the shared execution role, which such compute inherits.
+ *
+ * @param scope - Any construct in the stack; the bucket is created under the stack.
+ */
+export declare function getConfigLocation(scope: Construct): {
+    bucketName: string;
+    key: string;
+};
 /**
  * Finalize the config registry: create an S3 bucket, upload the config JSON,
- * set env vars on the handler, and grant read access.
+ * grant read to the shared execution role, and stamp the config coordinates
+ * (`BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY`) onto every compute.
+ *
+ * Read access is granted once to the shared role (`root.executionRole`) rather
+ * than to a single function, so every compute that assumes the role can read
+ * the object. The bucket/key coordinates can't live on a role (env vars are
+ * per-compute), so they are set on each compute via `setEnv`.
  *
  * Must be called after all BBs are constructed (i.e., after the backendCDKPath
  * import completes in BlocksStack.create() / BlocksBackend.create()).
  *
- * @param scope - The CDK construct to create resources under
- * @param handler - The Lambda function that needs to read the config
+ * @param root - The construct to create the config resources under (also used
+ *   to locate the owning stack).
+ * @param executionRole - The shared role every compute assumes; config read is
+ *   granted to it once.
+ * @param computes - The computes to stamp `BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY` on.
  */
-export declare function finalizeConfigRegistry(scope: Construct, handler: cdk.aws_lambda.IFunction): void;
+export declare function finalizeConfigRegistry(root: Construct, executionRole: cdk.aws_iam.IRole, computes: readonly Compute[]): void;
 //# sourceMappingURL=config-registry.d.ts.map

package/dist/cdk/config-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-registry.d.ts","sourceRoot":"","sources":["../../src/cdk/config-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAInC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAuB5C;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAIlF;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,SAAS,GAC/B,IAAI,CA6CN"}
+{"version":3,"file":"config-registry.d.ts","sourceRoot":"","sources":["../../src/cdk/config-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAGnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AA4BpD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAIlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAEvF;AA6BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,SAAS,EACf,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,EAChC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC1B,IAAI,CAyCN"}

package/dist/cdk/config-registry.js

@@ -3,8 +3,9 @@
 import * as cdk from 'aws-cdk-lib';
 import * as s3 from 'aws-cdk-lib/aws-s3';
 import * as s3deploy from 'aws-cdk-lib/aws-s3-deployment';
-import * as iam from 'aws-cdk-lib/aws-iam';
 const REGISTRY_KEY = Symbol.for('BLOCKS_CONFIG_REGISTRY');
+/** The object key of the config JSON under {@link getConfigLocation}'s bucket. */
+const CONFIG_KEY = 'blocks-config.json';
 /**
  * Get or create the config registry for a given stack.
  * The registry collects BB config entries (env var key → CDK token value)
@@ -34,47 +35,104 @@ export function registerConfig(scope, key, value) {
     const registry = getRegistry(stack);
     registry.entries.set(key, value);
 }
+/**
+ * Ensure the shared config bucket exists and return where the config JSON lives
+ * (`{ bucketName, key }`). The bucket is created **once per stack** (memoized on
+ * the registry) and this is idempotent — the first caller creates it, later
+ * callers get the same bucket regardless of order.
+ *
+ * Any compute that loads config at runtime (`loadConfigToProcessEnv()`) injects
+ * these two values as `BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY`. The Lambda
+ * handler gets them from {@link finalizeConfigRegistry}; other compute that runs
+ * as the shared execution role (e.g. the Agent BB's AgentCore Runtime) calls this
+ * at construction to inject them too, so it loads the same app config the handler
+ * does. IAM is not granted here — `finalizeConfigRegistry` grants read on the config
+ * object to the shared execution role, which such compute inherits.
+ *
+ * @param scope - Any construct in the stack; the bucket is created under the stack.
+ */
+export function getConfigLocation(scope) {
+    return { bucketName: ensureConfigBucket(scope).bucketName, key: CONFIG_KEY };
+}
+/**
+ * Create-or-return the shared config bucket (memoized on the per-stack registry). Created under the
+ * owning `BlocksStack`/`BlocksBackend` (`globalThis.CURRENT_BLOCKS_STACK` — the construct finalize
+ * historically used), so its logical ID is stable regardless of which caller creates it first: a
+ * co-located BB (e.g. the AgentCore Runtime, a deep construct) may be the first to call it, and a
+ * `BlocksBackend` embedded in a customer stack must keep `Blocks/BlocksConfigBucket` (no replacement).
+ * Falls back to the stack when no owner is registered (isolated unit tests). Returns a concrete
+ * `s3.Bucket` so callers don't need a non-null assertion.
+ */
+function ensureConfigBucket(scope) {
+    const stack = cdk.Stack.of(scope);
+    const registry = getRegistry(stack);
+    if (!registry.bucket) {
+        const owner = globalThis.CURRENT_BLOCKS_STACK ?? stack;
+        registry.bucket = new s3.Bucket(owner, 'BlocksConfigBucket', {
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+            autoDeleteObjects: true,
+            encryption: s3.BucketEncryption.S3_MANAGED,
+            blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+            lifecycleRules: [
+                { noncurrentVersionExpiration: cdk.Duration.days(1) },
+            ],
+        });
+    }
+    return registry.bucket;
+}
 /**
  * Finalize the config registry: create an S3 bucket, upload the config JSON,
- * set env vars on the handler, and grant read access.
+ * grant read to the shared execution role, and stamp the config coordinates
+ * (`BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY`) onto every compute.
+ *
+ * Read access is granted once to the shared role (`root.executionRole`) rather
+ * than to a single function, so every compute that assumes the role can read
+ * the object. The bucket/key coordinates can't live on a role (env vars are
+ * per-compute), so they are set on each compute via `setEnv`.
  *
  * Must be called after all BBs are constructed (i.e., after the backendCDKPath
  * import completes in BlocksStack.create() / BlocksBackend.create()).
  *
- * @param scope - The CDK construct to create resources under
- * @param handler - The Lambda function that needs to read the config
+ * @param root - The construct to create the config resources under (also used
+ *   to locate the owning stack).
+ * @param executionRole - The shared role every compute assumes; config read is
+ *   granted to it once.
+ * @param computes - The computes to stamp `BLOCKS_CONFIG_BUCKET` / `BLOCKS_CONFIG_KEY` on.
  */
-export function finalizeConfigRegistry(scope, handler) {
-    const stack = cdk.Stack.of(scope);
+export function finalizeConfigRegistry(root, executionRole, computes) {
+    const stack = cdk.Stack.of(root);
     const registry = getRegistry(stack);
     if (registry.finalized)
         return;
     registry.finalized = true;
-    if (registry.entries.size === 0)
+    // Nothing to do only if no config was registered AND no bucket was created (via
+    // getConfigLocation). If a co-located BB created the bucket, still upload (even an empty {}) and
+    // wire the handler so that compute's loadConfigToProcessEnv() resolves instead of 404-ing forever.
+    if (registry.entries.size === 0 && !registry.bucket)
         return;
-    const configBucket = new s3.Bucket(scope, 'BlocksConfigBucket', {
-        removalPolicy: cdk.RemovalPolicy.DESTROY,
-        autoDeleteObjects: true,
-        encryption: s3.BucketEncryption.S3_MANAGED,
-        blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
-        lifecycleRules: [
-            { noncurrentVersionExpiration: cdk.Duration.days(1) },
-        ],
-    });
-    const configKey = 'blocks-config.json';
+    // Ensure the bucket exists (a co-located BB may already have created it via getConfigLocation).
+    const configBucket = ensureConfigBucket(root);
+    const configKey = CONFIG_KEY;
     const configObject = cdk.Lazy.any({
         produce: () => Object.fromEntries(registry.entries),
     });
-    const deployment = new s3deploy.BucketDeployment(scope, 'BlocksConfigDeployment', {
+    new s3deploy.BucketDeployment(root, 'BlocksConfigDeployment', {
         sources: [s3deploy.Source.jsonData(configKey, configObject)],
         destinationBucket: configBucket,
         prune: false,
     });
-    handler.addEnvironment('BLOCKS_CONFIG_BUCKET', configBucket.bucketName);
-    handler.addEnvironment('BLOCKS_CONFIG_KEY', configKey);
-    // Scope IAM grant to the specific config key
-    handler.addToRolePolicy(new iam.PolicyStatement({
-        actions: ['s3:GetObject'],
-        resources: [`${configBucket.bucketArn}/${configKey}`],
-    }));
+    // Grant read once to the shared role (scoped to the config key), so every
+    // compute assuming the role can read it. We intentionally use `grantRead`
+    // (which also adds s3:GetBucket*/s3:List* alongside s3:GetObject*) rather
+    // than a hand-rolled GetObject-only statement: this is a dedicated,
+    // block-all-public, config-only bucket, so the broader action set carries
+    // negligible exposure, and grantRead stays correct automatically if the
+    // bucket ever moves to KMS encryption (it would add kms:Decrypt).
+    configBucket.grantRead(executionRole, configKey);
+    // Stamp the config coordinates on every compute — env vars can't live on a
+    // role, so each compute needs them to locate the object at runtime.
+    for (const compute of computes) {
+        compute.setEnv('BLOCKS_CONFIG_BUCKET', configBucket.bucketName);
+        compute.setEnv('BLOCKS_CONFIG_KEY', configKey);
+    }
 }

package/dist/cdk/config-registry.test.d.ts

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

package/dist/cdk/config-registry.test.d.ts.map

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