@aws-blocks/core 0.2.0 → 0.4.0

package/src/cdk/config-registry.ts

@@ -4,14 +4,19 @@
 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';
 import type { Construct } from 'constructs';
+import type { Compute } from './compute/compute.js';
 
 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';
+
 interface ConfigRegistryState {
 	entries: Map<string, unknown>;
 	finalized: boolean;
+	/** The shared config bucket, created once per stack by {@link getConfigLocation}. */
+	bucket?: s3.Bucket;
 }
 
 /**
@@ -45,62 +50,115 @@ export function registerConfig(scope: Construct, key: string, value: unknown): v
 	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: Construct): { bucketName: string; key: string } {
+	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: Construct): s3.Bucket {
+	const stack = cdk.Stack.of(scope);
+	const registry = getRegistry(stack);
+	if (!registry.bucket) {
+		const owner = ((globalThis as any).CURRENT_BLOCKS_STACK as Construct | undefined) ?? 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: Construct,
-	handler: cdk.aws_lambda.IFunction,
+	root: Construct,
+	executionRole: cdk.aws_iam.IRole,
+	computes: readonly Compute[],
 ): void {
-	const stack = cdk.Stack.of(scope);
+	const stack = cdk.Stack.of(root);
 	const registry = getRegistry(stack);
 
 	if (registry.finalized) return;
 	registry.finalized = true;
 
-	if (registry.entries.size === 0) 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) },
-		],
-	});
+	// 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 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 as cdk.aws_lambda.Function).addEnvironment(
-		'BLOCKS_CONFIG_BUCKET',
-		configBucket.bucketName,
-	);
-	(handler as cdk.aws_lambda.Function).addEnvironment(
-		'BLOCKS_CONFIG_KEY',
-		configKey,
-	);
-
-	// Scope IAM grant to the specific config key
-	(handler as cdk.aws_lambda.Function).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/src/cdk/index.ts

@@ -16,48 +16,101 @@ import { setupBlocksInfra, BlocksBackend, assertCdkConditionActive } from './blo
 import { addBlocksStackMetadata } from './stack-metadata.js';
 import { finalizeConfigRegistry } from './config-registry.js';
 import { type BlocksDefaults, BlocksPresets } from './blocks-defaults.js';
+import type { Compute } from './compute/compute.js';
+import { getComputes } from './compute/compute-registry.js';
+import type { DefaultComputeFactory, LambdaShapedCompute } from './compute/default-compute-factory.js';
 
-export { BlocksBackend, type BlocksBackendProps } from './blocks-backend.js';
+export {
+	BlocksBackend,
+	type BlocksBackendProps,
+	type CoreBlocksBackendProps,
+	SHARED_HANDLER_TIMEOUT_SECONDS,
+} from './blocks-backend.js';
 export { DEFAULT_NODE_RUNTIME } from './node-version.js';
 export { blocksNodejsBundling } from './bundling.js';
 export { SandboxDisableDeletionProtection } from './mixins.js';
-export { registerConfig, finalizeConfigRegistry } from './config-registry.js';
+export { registerConfig, finalizeConfigRegistry, getConfigLocation } from './config-registry.js';
+export { ensureApiGatewayAccount } from './apigateway-account.js';
 export {
   type BlocksDefaults,
+  type BlocksThrottling,
   BlocksPresets,
 } from './blocks-defaults.js';
 export { synthGuard } from './synth-guard.js';
 export type { ScopeOptions } from '../index.js';
 export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 
+/**
+ * Core's `create()` props: the public {@link BlocksStackProps} plus the required
+ * `defaultComputeFactory`. The umbrella (`@aws-blocks/blocks`) supplies the
+ * factory (which builds a `LambdaCompute`) by spreading it onto the customer's
+ * props; customers use {@link BlocksStackProps} and never set the factory.
+ *
+ * Kept separate (rather than a `create()` argument) so the factory travels with
+ * the props object and core stays free of any concrete compute class.
+ *
+ * @internal
+ */
+export interface CoreBlocksStackProps extends BlocksStackProps {
+  /** Builds the stack's default compute. Injected by `@aws-blocks/blocks`. */
+  defaultComputeFactory: DefaultComputeFactory;
+}
+
 export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
   public readonly id: string;
-  public readonly apiUrl: string;
-  public readonly gateway: cdk.aws_apigateway.RestApi;
-  public readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
   public 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`.
+   */
+  public readonly backendModulePath: string;
   /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
   public readonly executionRole: cdk.aws_iam.IRole;
   /** Infrastructure defaults for Building Blocks created under this stack. */
   public 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 {
+    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(): cdk.aws_apigateway.RestApi {
+    return this.requireDefaultCompute().apiGateway;
+  }
+  /** The default compute's RPC endpoint URL. To be removed once consumers move to the multi-compute model. */
+  get apiUrl(): string {
+    return this.requireDefaultCompute().apiUrl;
+  }
+  /** The default compute's handler CloudWatch log group. `bb-logger` reconfigures its retention. */
+  get handlerLogGroup(): cdk.aws_logs.ILogGroup {
+    return this.requireDefaultCompute().logGroup;
+  }
+
+  private requireDefaultCompute(): LambdaShapedCompute {
+    if (!this._defaultCompute) {
+      throw new Error('Blocks stack not fully initialized — access .handler/.gateway/.apiUrl after BlocksStack.create() resolves.');
+    }
+    return this._defaultCompute as LambdaShapedCompute;
+  }
 
   private constructor(scope: Construct, id: string, props: BlocksStackProps) {
     super(scope, id, props);
     this.id = id;
     this.backendHandlerPath = props.backendHandlerPath;
     this.defaults = props.defaults;
+    this.backendModulePath = props.backendCDKPath;
 
     // Set globalThis so Building Blocks attach directly to this stack
     (globalThis as any).CURRENT_BLOCKS_STACK = this;
 
     const infra = setupBlocksInfra(this, props, id);
-    this.handler = infra.handler;
-    this.gateway = infra.gateway;
-    this.apiUrl = infra.apiUrl;
     this.executionRole = infra.executionRole;
   }
 
-  static async create(scope: Construct, id: string, props: BlocksStackProps) {
+  static async create(scope: Construct, id: string, props: CoreBlocksStackProps) {
     assertCdkConditionActive();
 
     // Detect ambient pipeline stage scope set by Pipeline appFile imports
@@ -65,6 +118,13 @@ export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     const actualScope = pipelineScope || scope;
 
     const stack = new BlocksStack(actualScope, 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.
+    stack._defaultCompute = props.defaultComputeFactory(stack);
     // 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);
@@ -78,7 +138,7 @@ export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
       }
     }
     // Finalize BB config → S3 (after all BBs have registered their config)
-    finalizeConfigRegistry(stack, stack.handler);
+    finalizeConfigRegistry(stack, stack.executionRole, getComputes(stack));
 
     new cdk.CfnOutput(stack, 'ApiUrl', { value: stack.apiUrl });
 
@@ -104,6 +164,15 @@ export class Scope extends Construct {
    */
   private readonly root: BlocksStack | BlocksBackend;
 
+  /**
+   * Compute assigned at this node. Applies to this block and is inherited by
+   * descendants (a nearer assignment wins). Covers both a handler assigned to a
+   * specific compute and a scope-level default for its subtree. Internal until
+   * the customer-facing surface exists.
+   * @internal
+   */
+  _compute?: Compute;
+
   constructor(id: string, options?: ScopeOptions) {
     const parent = options?.parent || (globalThis as any).CURRENT_BLOCKS_STACK;
     super(parent, id);
@@ -144,6 +213,45 @@ export class Scope extends Construct {
     return this.root.executionRole;
   }
 
+  /**
+   * The compute this block runs on: the nearest `_compute` assigned on this
+   * block or an ancestor scope, else the owning stack/backend's default compute.
+   *
+   * For any app that doesn't assign a compute, this always resolves to the
+   * default — so reads are a no-op refactor. `_compute` is internal
+   * (test/framework) until the customer-facing surface exists; there is no
+   * public option to set it yet.
+   */
+  get compute(): Compute {
+    for (let current: ScopeParent | undefined = this; current; current = (current as Scope).parent) {
+      const assigned = (current as Scope)._compute;
+      if (assigned) return assigned;
+    }
+    const defaultCompute = this.root._defaultCompute;
+    if (!defaultCompute) {
+      throw new Error('Default compute not initialized — BlocksStack/BlocksBackend.create() must run before resolving `compute`.');
+    }
+    return defaultCompute;
+  }
+
+  /**
+   * The stack's default compute, **ignoring** any per-scope `_compute`
+   * assignment (unlike {@link compute}, which resolves the nearest assigned
+   * one). Use when a resource is a stack-level singleton that must bind to one
+   * deterministic compute regardless of the block's resolved compute — e.g.
+   * Realtime's shared WebSocket route integration, where one WebSocket API
+   * integrates to a single target and connection bookkeeping is compute-agnostic.
+   *
+   * @internal Not a customer surface; for framework/BB singleton infra only.
+   */
+  get defaultCompute(): Compute {
+    const defaultCompute = this.root._defaultCompute;
+    if (!defaultCompute) {
+      throw new Error('Default compute not initialized — BlocksStack/BlocksBackend.create() must run before resolving `defaultCompute`.');
+    }
+    return defaultCompute;
+  }
+
   /**
    * The backend entry file the owning BlocksStack/BlocksBackend runs — the
    * single handler entry shared across the whole app.
@@ -168,6 +276,17 @@ export class Scope extends Construct {
     return name;
   }
 
+  /**
+   * The shared handler Lambda's CloudWatch log group (the default compute's).
+   * Resolves the same way as {@link handler} — via the owning
+   * BlocksStack/BlocksBackend. `bb-logger` uses this to reconfigure retention on
+   * the single, framework-owned group rather than creating a second one that
+   * would collide on the log-group name.
+   */
+  get handlerLogGroup(): cdk.aws_logs.ILogGroup {
+    return this.root.handlerLogGroup;
+  }
+
   get fullId(): string {
     return computeScopeFullId(this);
   }

package/src/cdk/internal.ts

@@ -24,6 +24,7 @@
  */
 
 export { Compute } from './compute/compute.js';
+export type { DefaultComputeFactory } from './compute/default-compute-factory.js';
 // Reserved `/aws-blocks` path segment, needed by concrete computes (e.g.
 // LambdaCompute in @aws-blocks/bb-lambda-compute) to build their API route tree.
 export { BLOCKS_NAMESPACE } from '../constants.js';

package/src/client/index.ts

@@ -316,5 +316,5 @@ export function ApiNamespaceClient<T extends Record<string, (...args: any[]) =>
   });
 }
 
-export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
+export { ApiError, blocksError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 export { Scope, type ScopeOptions } from '../common/index.js';

package/src/common/config.test.ts

@@ -131,6 +131,27 @@ describe('config — S3 errors', () => {
 		assert.strictEqual(result, '', 'Should return empty string (empty config) on 404');
 	});
 
+	it('does not cache a not-found result — a later call re-fetches once the config exists', async () => {
+		process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+		process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+
+		// Simulate the transient post-deploy window: the object isn't written yet on the first
+		// fetch, then becomes available. A not-found result must NOT be cached, or the container
+		// would be poisoned with empty config for its lifetime.
+		let call = 0;
+		const notFound = new Error('The specified key does not exist.');
+		(notFound as any).name = 'NoSuchKey';
+		_setS3Fetcher(async () => {
+			call++;
+			if (call === 1) throw notFound;
+			return JSON.stringify({ READY_KEY: 'ready-value' });
+		});
+
+		assert.strictEqual(await getConfig('READY_KEY'), '', 'first call sees the not-yet-written config as empty');
+		assert.strictEqual(await getConfig('READY_KEY'), 'ready-value', 'later call re-fetches once the config exists');
+		assert.strictEqual(call, 2, 'a not-found result must not be cached — S3 is retried');
+	});
+
 	it('throws with clear message on S3 network error', async () => {
 		process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
 		process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';

package/src/common/config.ts

@@ -60,9 +60,13 @@ async function loadConfigFromS3(): Promise<Record<string, string>> {
 			|| error?.Code === 'NoSuchKey'
 			|| error?.$metadata?.httpStatusCode === 404;
 		if (isNotFound) {
-			console.warn(`[Blocks] Config file not found in S3 (${bucket}/${key}), proceeding with empty config`);
-			configCache = {};
-			return configCache;
+			// Do NOT cache the empty result: a 404 right after deploy is usually the config file
+			// not being readable yet (the transient window before the BucketDeployment settles), not
+			// a genuinely config-less app. Caching {} here would poison the container for its whole
+			// lifetime. Returning without caching lets the next invocation re-fetch and pick up the
+			// real config once it's present. (Apps that truly have no config just re-check cheaply.)
+			console.warn(`[Blocks] Config file not found in S3 (${bucket}/${key}), proceeding with empty config (will retry on next request)`);
+			return {};
 		}
 		const msg = error instanceof Error ? error.message : String(error);
 		throw new Error(`[Blocks] Failed to load config from S3 (${bucket}/${key}): ${msg}`);
@@ -152,6 +156,46 @@ export async function loadConfigToProcessEnv(): Promise<void> {
 	}
 }
 
+/**
+ * Whether a config load has resolved and cached a result.
+ *
+ * Returns `true` once `loadConfigFromS3()` has cached a config object — either a
+ * successful S3 load, a genuinely-empty `{}` config, or the no-bucket local-dev
+ * path (both of which cache `{}`). Returns `false` in the initial state AND
+ * after a transient not-found miss: the 404 path deliberately does NOT cache its
+ * empty result (see `loadConfigFromS3`), so a `false` return immediately after
+ * awaiting a load uniquely identifies the post-deploy S3 window where
+ * blocks-config.json isn't readable yet.
+ *
+ * Callers use this to tell a transient-empty load (retry on the next request)
+ * apart from a legitimately-config-less app (do nothing) without reaching into
+ * the module's private cache.
+ */
+export function isConfigResolved(): boolean {
+	return configCache !== null;
+}
+
+/**
+ * Sanitize a Blocks identifier into a valid config/env-var key segment:
+ * uppercase, with every non-alphanumeric character replaced by `_`.
+ *
+ * Config entries are loaded into `process.env` at runtime (see
+ * {@link loadConfigToProcessEnv}), so a key must be a valid env-var name. This
+ * is the single rule both sides of a key share: whoever *writes* a config key
+ * (`registerConfig(\`PREFIX_${sanitizeConfigKey(id)}\`, …)`) and whoever *reads*
+ * it (`getConfigSync(\`PREFIX_${sanitizeConfigKey(id)}\`)`) MUST go through this
+ * function so they reconstruct a byte-identical key — a hand-inlined variant
+ * that drifts silently misses the lookup at runtime.
+ *
+ * @example
+ * ```typescript
+ * registerConfig(this, `BLOCKS_QUEUE_URL_${sanitizeConfigKey(this.fullId)}`, url);
+ * ```
+ */
+export function sanitizeConfigKey(id: string): string {
+	return id.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+}
+
 /**
  * Reset the config cache. **For testing only.**
  */

package/src/common/index.ts

@@ -338,6 +338,14 @@ export interface BlocksStackProps extends StackProps {
 
 export class BlocksStack {
 	public readonly id: string;
+	/**
+	 * Path to the app's backend module (`props.backendCDKPath`). A typed contract for Building
+	 * Blocks that co-bundle the backend at synth time and read it off
+	 * `globalThis.CURRENT_BLOCKS_STACK` (the CDK `BlocksStack` / `BlocksBackend` set it). Declared
+	 * here so those consumers can type against this shared `BlocksStack` contract — which the CDK
+	 * `BlocksStack` / `BlocksBackend` implements — instead of `any`.
+	 */
+	declare readonly backendModulePath: string;
 	constructor(scope: Construct, id: string, props: BlocksStackProps) {
 		this.id = id;
 	}

package/src/errors.ts

@@ -78,6 +78,27 @@ export function isBlocksError<N extends string>(e: unknown, name: N): e is Error
 	return e instanceof Error && e.name === name;
 }
 
+/**
+ * Build a named `Error` whose `name` is a BB error constant, so it is matchable
+ * with {@link isBlocksError} on both server and client. The name is also
+ * prefixed into the message for readable logs.
+ *
+ * This is the producer half of the {@link isBlocksError} contract: throw via
+ * this helper so the `name` a consumer matches on is set consistently. It has
+ * no runtime dependencies, so it is safe to use in every bundle — mock,
+ * aws-runtime, and CDK synth.
+ *
+ * @example
+ * ```typescript
+ * throw blocksError(KVStoreErrors.ConditionalCheckFailed, 'Key already exists');
+ * ```
+ */
+export function blocksError(name: string, message: string): Error {
+	const err = new Error(`${name}: ${message}`);
+	err.name = name;
+	return err;
+}
+
 /**
  * Type guard for branching on a failed `AuthState` (the recommended
  * `setAuthState` client path) by its structured `errorName`.

package/src/hosting-secrets.test.ts

@@ -0,0 +1,106 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { config, secret } from '@aws-blocks/hosting';
+import {
+	collectSynthMarkers,
+	partitionEnvironment,
+	resolveDomainNames,
+	resolveSecretsAtSynth,
+} from './hosting-secrets.js';
+
+void describe('partitionEnvironment()', () => {
+	void it('splits plain / managed (secret+config)', () => {
+		const { plain, managed } = partitionEnvironment({
+			FLAG: 'on',
+			STRIPE_KEY: secret('STRIPE_KEY'),
+			FEATURE_FLAGS: config('FEATURE_FLAGS'),
+		});
+		assert.deepStrictEqual(plain, { FLAG: 'on' });
+		assert.deepStrictEqual(managed.map((m) => `${m.key}:${m.kind}`).sort(), [
+			'FEATURE_FLAGS:config',
+			'STRIPE_KEY:secret',
+		]);
+	});
+
+	void it('rejects env key / marker key mismatch', () => {
+		assert.throws(
+			() => partitionEnvironment({ STRIPE_KEY: secret('OTHER') }),
+			/must match the environment variable name/,
+		);
+	});
+
+	void it('handles undefined', () => {
+		const { plain, managed, byo } = partitionEnvironment(undefined);
+		assert.deepStrictEqual(plain, {});
+		assert.strictEqual(managed.length, 0);
+		assert.strictEqual(byo.length, 0);
+	});
+});
+
+void describe('collectSynthMarkers()', () => {
+	void it('gathers domain markers, deduped by key', () => {
+		const markers = collectSynthMarkers(['example.com', config('DOMAIN_PROD'), config('DOMAIN_PROD')]);
+		assert.deepStrictEqual(
+			markers.map((m) => m.key),
+			['DOMAIN_PROD'],
+		);
+	});
+	void it('returns nothing when no markers', () => {
+		assert.deepStrictEqual(collectSynthMarkers('example.com'), []);
+		assert.deepStrictEqual(collectSynthMarkers(undefined), []);
+	});
+});
+
+void describe('resolveSecretsAtSynth() — Blocks namespaces', () => {
+	void it('config marker resolves under /blocks/config (SSM leading-slash)', async () => {
+		const seen: string[] = [];
+		const resolved = await resolveSecretsAtSynth([config('DOMAIN_PROD')], async (name) => {
+			seen.push(name);
+			return 'prod.example.com';
+		});
+		assert.deepStrictEqual(seen, ['/blocks/config/DOMAIN_PROD']);
+		assert.strictEqual(resolved.get('DOMAIN_PROD'), 'prod.example.com');
+	});
+
+	void it('secret marker resolves under /blocks/secrets (Secrets Manager slash-free)', async () => {
+		const seen: string[] = [];
+		await resolveSecretsAtSynth([secret('API_KEY')], async (name) => {
+			seen.push(name);
+			return 'k';
+		});
+		assert.deepStrictEqual(seen, ['blocks/secrets/API_KEY']);
+	});
+
+	void it('throws an actionable error when a value is not set', async () => {
+		await assert.rejects(
+			resolveSecretsAtSynth([config('DOMAIN_PROD')], async () => {
+				const e = new Error('not found');
+				e.name = 'ParameterNotFound';
+				throw e;
+			}),
+			/config 'DOMAIN_PROD' is referenced/,
+		);
+	});
+});
+
+void describe('resolveDomainNames()', () => {
+	void it('replaces markers with resolved literals, preserving shape', () => {
+		const resolved = new Map([['DOMAIN_PROD', 'prod.example.com']]);
+		assert.strictEqual(resolveDomainNames(config('DOMAIN_PROD'), resolved), 'prod.example.com');
+		assert.deepStrictEqual(resolveDomainNames(['www.example.com', config('DOMAIN_PROD')], resolved), [
+			'www.example.com',
+			'prod.example.com',
+		]);
+	});
+
+	void it('throws if a marker reached the sync path unresolved', () => {
+		assert.throws(() => resolveDomainNames(config('DOMAIN_PROD'), new Map()), /requires async resolution/);
+	});
+
+	void it('passes literal domains through untouched', () => {
+		assert.strictEqual(resolveDomainNames('example.com', new Map()), 'example.com');
+	});
+});