@aws-blocks/core 0.3.0 → 0.5.0

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

@@ -1,4 +1,18 @@
 import { RemovalPolicy } from 'aws-cdk-lib';
+import { RetentionDays } from 'aws-cdk-lib/aws-logs';
+import type { BlocksVpcOptions } from './vpc-types.js';
+/**
+ * Request-rate limits applied to an API Gateway stage. On a REST API these are
+ * requests/second; on a WebSocket API the unit is messages/second across the
+ * connection. `rateLimit` is the steady-state ceiling and `burstLimit` the
+ * token-bucket size for short spikes.
+ */
+export interface BlocksThrottling {
+    /** Steady-state request (or WebSocket message) rate ceiling, per second. */
+    rateLimit: number;
+    /** Token-bucket burst size for short spikes above `rateLimit`. */
+    burstLimit: number;
+}
 /**
  * Default values for every Amazon-authored Building Block created within a
  * `BlocksStack` or `BlocksBackend`. A per-block option always overrides the
@@ -42,6 +56,50 @@ export interface BlocksDefaults {
     pointInTimeRecovery: boolean | {
         retentionDays: number;
     };
+    /**
+     * How long CloudWatch Logs keeps log events written by Blocks-managed log
+     * groups (the core handler Lambda, migration/GSI Lambdas, hosting compute,
+     * `bb-logger`, and API Gateway access logs) before expiring them. Without a
+     * retention set, AWS keeps log events forever, which grows cost unbounded —
+     * every Blocks-managed log group reads this default so retention is applied
+     * consistently.
+     */
+    logRetention: RetentionDays;
+    /**
+     * Request-rate limits applied to every Blocks-managed API Gateway stage: the
+     * core REST API, the SSR/hosting REST API, and the `bb-realtime` WebSocket
+     * stage. Protects the backend from runaway clients and caps blast radius.
+     * The sandbox preset caps tighter (200/400) than production (1000/2000) so a
+     * disposable stack is well-protected without throttling real production
+     * traffic. See {@link BlocksThrottling}.
+     */
+    throttling: BlocksThrottling;
+    /**
+     * Whether to emit structured JSON access logs from every Blocks-managed API
+     * Gateway stage to a dedicated CloudWatch log group (retention follows
+     * {@link logRetention}).
+     *
+     * **Off by default in both presets** — opt in with a per-stack override
+     * (`defaults: { ...BlocksPresets.production, accessLogging: true }`). It is
+     * off by default (rather than on for production) because enabling it
+     * provisions the account-level API Gateway CloudWatch Logs role, which is an
+     * account/region-level singleton: a second Blocks stack in the same
+     * account+region that also enables access logging can repoint that role on
+     * deploy or, on teardown, leave the survivor's access logging broken.
+     * Enabling it is therefore safe for **one Blocks stack per region** — see
+     * `ensureApiGatewayAccount` for the full multi-stack teardown caveat.
+     */
+    accessLogging: boolean;
+    /**
+     * Place the app's compute and VPC-resident resources in a VPC. Pass a
+     * standard CDK VPC — Blocks handles Lambda placement, endpoint provisioning
+     * (based on which Building Blocks are in scope), and security-group wiring.
+     *
+     * Omit for no VPC (the preset default — Lambda runs in the AWS-managed
+     * network). A Building Block that can't function without a VPC causes Blocks
+     * to derive one on demand even when this is unset.
+     */
+    vpc?: BlocksVpcOptions;
 }
 /**
  * Prepared starting points for {@link BlocksDefaults}. Pick one and override
@@ -58,13 +116,30 @@ export declare const BlocksPresets: {
         deletionProtection: false;
         allowedOrigins: string[];
         pointInTimeRecovery: false;
+        logRetention: RetentionDays.ONE_WEEK;
+        throttling: {
+            rateLimit: number;
+            burstLimit: number;
+        };
+        accessLogging: false;
     };
-    /** Durable, protected posture for permanent deployments. */
+    /**
+     * Durable, protected posture for permanent deployments. A higher throttle
+     * ceiling (1000/2000) than sandbox so the default doesn't 429 real
+     * production traffic — raise it via a per-stack `throttling` override for
+     * higher-volume APIs.
+     */
     production: {
         removalPolicy: RemovalPolicy.RETAIN;
         deletionProtection: true;
         allowedOrigins: never[];
         pointInTimeRecovery: true;
+        logRetention: RetentionDays.ONE_YEAR;
+        throttling: {
+            rateLimit: number;
+            burstLimit: number;
+        };
+        accessLogging: false;
     };
 };
 //# 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;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"}
+{"version":3,"file":"blocks-defaults.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-defaults.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;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;IAEzD;;;;;;;OAOG;IACH,YAAY,EAAE,aAAa,CAAC;IAE5B;;;;;;;OAOG;IACH,UAAU,EAAE,gBAAgB,CAAC;IAE7B;;;;;;;;;;;;;;OAcG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,gBAAgB,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;IACzB,qFAAqF;;;;;;;;;;;;;IAUrF;;;;;OAKG;;;;;;;;;;;;;CAcsC,CAAC"}

package/dist/cdk/blocks-defaults.js

@@ -1,6 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 import { RemovalPolicy } from 'aws-cdk-lib';
+import { RetentionDays } from 'aws-cdk-lib/aws-logs';
 /**
  * Prepared starting points for {@link BlocksDefaults}. Pick one and override
  * individual fields with a spread:
@@ -16,12 +17,27 @@ export const BlocksPresets = {
         deletionProtection: false,
         allowedOrigins: ['^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$'],
         pointInTimeRecovery: false,
+        logRetention: RetentionDays.ONE_WEEK,
+        throttling: { rateLimit: 200, burstLimit: 400 },
+        accessLogging: false,
     },
-    /** Durable, protected posture for permanent deployments. */
+    /**
+     * Durable, protected posture for permanent deployments. A higher throttle
+     * ceiling (1000/2000) than sandbox so the default doesn't 429 real
+     * production traffic — raise it via a per-stack `throttling` override for
+     * higher-volume APIs.
+     */
     production: {
         removalPolicy: RemovalPolicy.RETAIN,
         deletionProtection: true,
         allowedOrigins: [],
         pointInTimeRecovery: true,
+        logRetention: RetentionDays.ONE_YEAR,
+        throttling: { rateLimit: 1000, burstLimit: 2000 },
+        // Off by default even in production: enabling access logging mutates the
+        // account/region-level API Gateway CloudWatch role (a singleton). Opt in
+        // per stack once you've confirmed a single Blocks stack owns it in the
+        // region — see the `accessLogging` field doc.
+        accessLogging: false,
     },
 };

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

@@ -9,6 +9,7 @@
 import { test, describe } from 'node:test';
 import assert from 'node:assert';
 import { RemovalPolicy } from 'aws-cdk-lib';
+import { RetentionDays } from 'aws-cdk-lib/aws-logs';
 import { BlocksPresets } from './blocks-defaults.js';
 describe('BlocksPresets', () => {
     test('sandbox is disposable: DESTROY + deletion protection off + no PITR', () => {
@@ -21,4 +22,20 @@ describe('BlocksPresets', () => {
         assert.strictEqual(BlocksPresets.production.deletionProtection, true);
         assert.strictEqual(BlocksPresets.production.pointInTimeRecovery, true);
     });
+    test('sandbox keeps logs briefly', () => {
+        assert.strictEqual(BlocksPresets.sandbox.logRetention, RetentionDays.ONE_WEEK);
+    });
+    test('production keeps logs a year', () => {
+        assert.strictEqual(BlocksPresets.production.logRetention, RetentionDays.ONE_YEAR);
+    });
+    test('access logging is off by default in BOTH presets (opt-in; mutates an account singleton)', () => {
+        assert.strictEqual(BlocksPresets.sandbox.accessLogging, false);
+        assert.strictEqual(BlocksPresets.production.accessLogging, false);
+    });
+    test('sandbox caps tighter (200/400) than production (1000/2000)', () => {
+        assert.strictEqual(BlocksPresets.sandbox.throttling.rateLimit, 200);
+        assert.strictEqual(BlocksPresets.sandbox.throttling.burstLimit, 400);
+        assert.strictEqual(BlocksPresets.production.throttling.rateLimit, 1000);
+        assert.strictEqual(BlocksPresets.production.throttling.burstLimit, 2000);
+    });
 });

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

@@ -10,7 +10,8 @@ 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 { BlocksStack, BlocksPresets, Scope } from './index.js';
+import { getComputes } from './compute/compute-registry.js';
+import { BlocksPresets, BlocksStack, 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,
@@ -22,13 +23,18 @@ 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' } },
         });
@@ -42,6 +48,16 @@ class StubLambdaCompute extends Compute {
     setEnv(key, value) {
         this.fn.addEnvironment(key, value);
     }
+    applyTracing() { }
+    healthWidgets(_region) {
+        return [];
+    }
+    loggingWidgets(_region) {
+        return [];
+    }
+    tracingWidgets(_region) {
+        return [];
+    }
 }
 const stubComputeFactory = (root) => new StubLambdaCompute(root, 'DefaultCompute');
 // Simulate the CDK condition being active (tests import CDK files directly)
@@ -54,8 +70,18 @@ const sideEffectBackendPath = join(__dirname, '__fixtures__', 'side-effect-backe
 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 });
+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();
@@ -130,6 +156,21 @@ describe('root is bound to the owning stack (multi-stack synth)', () => {
         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 () => {

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,5 @@
+import type { IWidget } from 'aws-cdk-lib/aws-cloudwatch';
+import type { ScopeOptions } from '../../common/index.js';
 import { Scope } from '../index.js';
 /**
  * Base class for a Blocks *compute* — a runtime that executes handler code
@@ -10,11 +12,17 @@ import { Scope } from '../index.js';
  * compute in an app runs the same backend and agrees on the resource-name
  * namespace.
  *
+ * **Observability is compute-owned at deploy time.** Logging is always on (a
+ * compute owns its log group and captures stdout; retention is a compute-level
+ * setting), so there is no "enable logging" — logs always exist. Tracing, by
+ * contrast, provisions real infrastructure (X-Ray) and has cost, so it is
+ * enabled explicitly via {@link enableTracing} — which the framework calls on
+ * every compute when the app contains a `Tracer` (presence-gated).
+ *
  * The abstract base lives in core (a framework primitive); concrete computes
  * live in their own packages (e.g. `LambdaCompute` in `@aws-blocks/bb-lambda-compute`).
  *
- * @internal Not exported from the package's public entry points. Customers
- * cannot instantiate a compute until the customer-facing surface exists.
+ * @internal Not exported from the package's public entry points.
  */
 export declare abstract class Compute extends Scope {
     /**
@@ -23,11 +31,83 @@ export declare abstract class Compute extends Scope {
      * unpopulated (no compute assignment surface yet).
      */
     readonly namespaces: string[];
+    /**
+     * Whether tracing has been enabled on this compute — flipped by
+     * {@link enableTracing}. Private so it can't be set independently of the
+     * infra; read internally by {@link dashboardSection} to decide whether to
+     * render the traces section.
+     */
+    private tracerEnabled;
+    /** Read-only view of {@link tracerEnabled} for subclasses (e.g. to guard
+     * their `tracingWidgets` builder). Subclasses can read but not set it. */
+    protected get isTracerEnabled(): boolean;
+    constructor(id: string, options?: ScopeOptions);
     /**
      * Inject a runtime configuration value (an environment variable) into this
      * compute. The framework calls this instead of `handler.addEnvironment()`
      * directly so config targets the right compute.
      */
     abstract setEnv(key: string, value: string): void;
+    /**
+     * Enable distributed tracing on this compute: mark it traced (so the Dashboard
+     * renders its traces section) and turn on the compute's active tracing via
+     * {@link applyTracing}. Idempotent — the framework calls this on **every**
+     * compute when the app contains a `Tracer` (tracing is presence-gated, not
+     * per-compute), so calling it more than once is a no-op.
+     */
+    enableTracing(): void;
+    /**
+     * Turn on this compute's active tracing (e.g. X-Ray) and grant its role the
+     * permission to publish trace segments. Called by {@link enableTracing};
+     * `protected` so tracing can't be turned on without marking the compute
+     * traced.
+     */
+    protected abstract applyTracing(): void;
+    /**
+     * Build this compute's CloudWatch Dashboard section: health widgets and log
+     * widgets **always** (logs are always captured for a compute), plus trace
+     * widgets **only when** tracing is enabled on this compute (via
+     * {@link enableTracing}).
+     *
+     * This is the single public entry the Dashboard Building Block uses; the
+     * per-kind builders below are `protected`. Whether the logs / traces sections
+     * are actually shown is a display choice the Dashboard makes on top (its
+     * `logs` / `traces` options) — this returns what the compute *has*.
+     *
+     * @param region - AWS region the widgets query metrics in.
+     */
+    dashboardSection(region: string): ComputeDashboardSection;
+    /**
+     * Build this compute's health widget rows. Implemented by a concrete compute;
+     * obtained only via {@link dashboardSection}.
+     */
+    protected abstract healthWidgets(region: string): IWidget[][];
+    /**
+     * Build this compute's **log** widget rows for its own log group. Logs always
+     * exist, so this is always available; the Dashboard's `logs` option decides
+     * whether to render it.
+     */
+    protected abstract loggingWidgets(region: string): IWidget[][];
+    /**
+     * Build this compute's **trace** widget rows. Gated behind
+     * {@link dashboardSection} so it is only used when tracing is enabled.
+     */
+    protected abstract tracingWidgets(region: string): IWidget[][];
+}
+/**
+ * A compute's self-reported CloudWatch Dashboard section. `health` and `logging`
+ * are always present; `tracing` is populated only when tracing is enabled on the
+ * compute. (The Dashboard may still hide `logging` / `tracing` via its display
+ * options.)
+ */
+export interface ComputeDashboardSection {
+    /** Display label used as the compute's group header. */
+    label: string;
+    /** Health widget rows — always present. */
+    health: IWidget[][];
+    /** Log widget rows — always present (logs are always captured). */
+    logging?: IWidget[][];
+    /** Trace widget rows — present only when tracing is enabled. */
+    tracing?: IWidget[][];
 }
 //# sourceMappingURL=compute.d.ts.map

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,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,OAAQ,SAAQ,KAAK;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAM;IAEnC;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAAS;IAE9B;8EAC0E;IAC1E,SAAS,KAAK,eAAe,IAAI,OAAO,CAEvC;gBAEW,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAQ9C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAEjD;;;;;;OAMG;IACH,aAAa,IAAI,IAAI;IAMrB;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,IAAI,IAAI;IAEvC;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,uBAAuB;IAWzD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,EAAE;IAE7D;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,EAAE;IAE9D;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,EAAE;CAC9D;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC;IACpB,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC;IACtB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC;CACtB"}

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
@@ -12,11 +13,17 @@ import { Scope } from '../index.js';
  * compute in an app runs the same backend and agrees on the resource-name
  * namespace.
  *
+ * **Observability is compute-owned at deploy time.** Logging is always on (a
+ * compute owns its log group and captures stdout; retention is a compute-level
+ * setting), so there is no "enable logging" — logs always exist. Tracing, by
+ * contrast, provisions real infrastructure (X-Ray) and has cost, so it is
+ * enabled explicitly via {@link enableTracing} — which the framework calls on
+ * every compute when the app contains a `Tracer` (presence-gated).
+ *
  * The abstract base lives in core (a framework primitive); concrete computes
  * live in their own packages (e.g. `LambdaCompute` in `@aws-blocks/bb-lambda-compute`).
  *
- * @internal Not exported from the package's public entry points. Customers
- * cannot instantiate a compute until the customer-facing surface exists.
+ * @internal Not exported from the package's public entry points.
  */
 export class Compute extends Scope {
     /**
@@ -25,4 +32,59 @@ export class Compute extends Scope {
      * unpopulated (no compute assignment surface yet).
      */
     namespaces = [];
+    /**
+     * Whether tracing has been enabled on this compute — flipped by
+     * {@link enableTracing}. Private so it can't be set independently of the
+     * infra; read internally by {@link dashboardSection} to decide whether to
+     * render the traces section.
+     */
+    tracerEnabled = false;
+    /** Read-only view of {@link tracerEnabled} for subclasses (e.g. to guard
+     * their `tracingWidgets` builder). Subclasses can read but not set it. */
+    get isTracerEnabled() {
+        return this.tracerEnabled;
+    }
+    constructor(id, options) {
+        super(id, options);
+        // Self-register on the owning stack so finalize steps (tracing, routing,
+        // dashboards) can enumerate every compute without a separate discovery
+        // pass. Scoped per stack, so a multi-stack synth keeps lists isolated.
+        registerCompute(this);
+    }
+    /**
+     * Enable distributed tracing on this compute: mark it traced (so the Dashboard
+     * renders its traces section) and turn on the compute's active tracing via
+     * {@link applyTracing}. Idempotent — the framework calls this on **every**
+     * compute when the app contains a `Tracer` (tracing is presence-gated, not
+     * per-compute), so calling it more than once is a no-op.
+     */
+    enableTracing() {
+        if (this.tracerEnabled)
+            return;
+        this.tracerEnabled = true;
+        this.applyTracing();
+    }
+    /**
+     * Build this compute's CloudWatch Dashboard section: health widgets and log
+     * widgets **always** (logs are always captured for a compute), plus trace
+     * widgets **only when** tracing is enabled on this compute (via
+     * {@link enableTracing}).
+     *
+     * This is the single public entry the Dashboard Building Block uses; the
+     * per-kind builders below are `protected`. Whether the logs / traces sections
+     * are actually shown is a display choice the Dashboard makes on top (its
+     * `logs` / `traces` options) — this returns what the compute *has*.
+     *
+     * @param region - AWS region the widgets query metrics in.
+     */
+    dashboardSection(region) {
+        return {
+            // The scope id (e.g. 'DefaultCompute', 'api') — short and readable for a
+            // section header, and distinct per compute within a stack.
+            label: this.id,
+            health: this.healthWidgets(region),
+            logging: this.loggingWidgets(region),
+            tracing: this.tracerEnabled ? this.tracingWidgets(region) : undefined,
+        };
+    }
 }

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

@@ -16,6 +16,7 @@ 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

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

@@ -1 +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;CACxB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,WAAW,GAAG,aAAa,KAAK,OAAO,CAAC"}
+{"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/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"}