@aws-blocks/core 0.4.0 → 0.5.0

package/src/cdk/vpc.ts

@@ -0,0 +1,336 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Annotations } from 'aws-cdk-lib';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import type { Construct } from 'constructs';
+import { getVpcRequirements as getRegisteredVpcRequirements } from './vpc-requirements-registry.js';
+import type { BlocksVpcOptions, SubnetRole, SubnetScope, VpcContext, VpcRequirements } from './vpc-types.js';
+
+const VPC_CONTEXT_KEY = Symbol.for('BLOCKS_VPC_CONTEXT');
+
+/** Map a subnet role to its concrete CDK subnet type. */
+function subnetTypeForRole(role: SubnetRole): ec2.SubnetType {
+	switch (role) {
+		case 'isolated':
+			return ec2.SubnetType.PRIVATE_ISOLATED;
+		case 'public':
+			return ec2.SubnetType.PUBLIC;
+		case 'private-with-egress':
+			return ec2.SubnetType.PRIVATE_WITH_EGRESS;
+	}
+}
+
+/** Does the VPC actually contain at least one subnet of the given role? */
+function vpcHasRole(vpc: ec2.IVpc, role: SubnetRole): boolean {
+	switch (role) {
+		case 'isolated':
+			return vpc.isolatedSubnets.length > 0;
+		case 'public':
+			return vpc.publicSubnets.length > 0;
+		case 'private-with-egress':
+			return vpc.privateSubnets.length > 0;
+	}
+}
+
+/**
+ * Set the VPC context on a scope (BlocksStack or BlocksBackend).
+ * Called during stack creation when `vpc` prop is provided.
+ * @internal
+ */
+export function setVpcContext(scope: Construct, context: VpcContext): void {
+	(scope as any)[VPC_CONTEXT_KEY] = context;
+}
+
+/**
+ * Get the VPC context from a scope by walking up the construct tree.
+ * Used by BBs (e.g., bb-data) to discover the shared VPC.
+ * @internal
+ */
+export function getVpcContext(scope: Construct): VpcContext | undefined {
+	let current: Construct | undefined = scope;
+	while (current) {
+		const ctx = (current as any)[VPC_CONTEXT_KEY] as VpcContext | undefined;
+		if (ctx) return ctx;
+		current = current.node.scope as Construct | undefined;
+	}
+	return undefined;
+}
+
+const LAZY_VPC_KEY = Symbol.for('BLOCKS_LAZY_VPC');
+
+/**
+ * Does any registered Building Block *require* a VPC (i.e. cannot function
+ * without one)? Used to decide whether to lazily derive a VPC when the customer
+ * didn't provide one. A BB that merely benefits from endpoints does NOT count —
+ * only `requiresVpc: true`.
+ * @internal
+ */
+export function anyRequirementNeedsVpc(scope: Construct): boolean {
+	return getRegisteredVpcRequirements(scope).some((r) => r.requirements.requiresVpc === true);
+}
+
+/**
+ * Get the framework-owned VPC for a stack, creating one on first use.
+ *
+ * VPC is a **derived** resource: when a Building Block (or, later, a container
+ * compute) requires one and the customer didn't bring their own, Blocks
+ * materializes a sensible default here — the same create-if-absent pattern
+ * `bb-data` uses for Aurora, lifted to the framework so the whole app shares a
+ * single VPC. Keyed by a Symbol on the stack so it's a true singleton: the first
+ * caller creates, everyone else reuses. Passing a customer VPC (`vpc:` prop)
+ * pre-seeds this via {@link initializeVpc}, so this default is only built when
+ * nothing was provided.
+ *
+ * The default has both a `private-with-egress` tier (for a runtime that needs
+ * outbound access — the derivation trigger) and public subnets for the NAT
+ * gateway. NAT has a real cost, so this is only created on genuine need, and
+ * `create()` emits a notice when it does.
+ * @internal
+ */
+export function getOrCreateVpc(scope: Construct): ec2.IVpc {
+	const holder = scope as any;
+	const existing = holder[LAZY_VPC_KEY] as ec2.IVpc | undefined;
+	if (existing) return existing;
+	const vpc = new ec2.Vpc(scope, 'BlocksVpc', { maxAzs: 2, natGateways: 1 });
+	holder[LAZY_VPC_KEY] = vpc;
+	return vpc;
+}
+
+/**
+ * Initialize VPC support on a Blocks scope (BlocksStack or BlocksBackend).
+ * Creates the security group, sets VPC context, and returns the VpcContext
+ * that is used for Lambda placement configuration.
+ *
+ * Called during setupBlocksInfra when `vpc` prop is present.
+ * @internal
+ */
+export function initializeVpc(scope: Construct, options: BlocksVpcOptions): VpcContext {
+	const { network: vpc, subnets } = options;
+
+	// Default Lambda placement to private-with-egress. Guard the default: if the
+	// caller didn't specify `subnets` and the VPC has no such tier, fail now with
+	// an actionable message instead of letting Lambda placement throw a cryptic
+	// CDK error later. (A caller who *explicitly* passes an isolated selection is
+	// honored — per-BB `requiresEgress` validation catches BBs that can't run there.)
+	if (!subnets && !vpcHasRole(vpc, 'private-with-egress')) {
+		throw new Error(
+			`VPC '${vpc.vpcId}' has no private-with-egress subnets, which Blocks uses for Lambda ` +
+				`placement by default. Add a PRIVATE_WITH_EGRESS subnet tier (a private subnet with a ` +
+				`NAT gateway), or pass 'vpc.subnets' to choose a different placement explicitly. ` +
+				`See packages/blocks/VPC.md.`,
+		);
+	}
+
+	const resolvedSubnets = subnets ?? { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS };
+
+	const computeSecurityGroup = new ec2.SecurityGroup(scope, 'BlocksLambdaSg', {
+		vpc,
+		description: 'Security group for Blocks Lambda functions in VPC',
+		allowAllOutbound: true,
+	});
+
+	const context: VpcContext = {
+		vpc,
+		computeSecurityGroup,
+		computeSubnets: resolvedSubnets,
+		selectSubnets(scope: SubnetScope, role: SubnetRole, opts?: { fallback?: SubnetRole }): ec2.SubnetSelection {
+			if (vpcHasRole(vpc, role)) {
+				return { subnetType: subnetTypeForRole(role) };
+			}
+			// Requested role is absent. Fall back only if the BB explicitly opted in
+			// AND the fallback role actually exists — never downgrade silently.
+			if (opts?.fallback && vpcHasRole(vpc, opts.fallback)) {
+				return { subnetType: subnetTypeForRole(opts.fallback) };
+			}
+			const wanted = opts?.fallback ? `'${role}' (or '${opts.fallback}')` : `'${role}'`;
+			throw new Error(
+				`${scope.fullId} needs a ${wanted} subnet, but VPC '${vpc.vpcId}' has none. ` +
+					`Add a matching subnet tier to your VPC (e.g. a 'subnetConfiguration' entry of the ` +
+					`required type), or place the Building Block differently. ` +
+					`See packages/blocks/VPC.md for guidance.`,
+			);
+		},
+	};
+
+	setVpcContext(scope, context);
+	return context;
+}
+
+/**
+ * Finalize VPC: query all BuildingBlockScope children for their VPC requirements,
+ * deduplicate, and provision endpoints.
+ * Called after all BBs are constructed (alongside finalizeConfigRegistry).
+ * @internal
+ */
+export function finalizeVpc(scope: Construct, options: BlocksVpcOptions): void {
+	const { network: vpc, subnets } = options;
+
+	// Whether the runtime's placement provides egress (outbound internet). This is
+	// the only capability the requirement check needs — a BB either needs egress
+	// or it doesn't. Resolved from the actual selected subnets rather than guessed
+	// from a subnet role, so an explicit subnet *list* (no subnetType) is handled
+	// correctly. `undefined` = couldn't determine (e.g. an imported VPC whose
+	// subnets aren't known at synth) → we skip validation with a warning rather
+	// than fabricate an answer.
+	const placementHasEgress: boolean | undefined = placementProvidesEgress(vpc, subnets);
+
+	const gatewayEndpoints: ec2.GatewayVpcEndpointAwsService[] = [];
+	const interfaceEndpoints: ec2.InterfaceVpcEndpointAwsService[] = [];
+
+	// Pull requirements from the central registry — every BuildingBlockScope
+	// self-registers in its constructor, so this is a faithful census without a
+	// separate tree walk (mirrors how config/compute registries are consumed).
+	for (const { fullId, requirements: reqs } of getRegisteredVpcRequirements(scope)) {
+		if (reqs.gatewayEndpoints) {
+			gatewayEndpoints.push(...reqs.gatewayEndpoints);
+		}
+		if (reqs.interfaceEndpoints) {
+			interfaceEndpoints.push(...reqs.interfaceEndpoints);
+		}
+		// Validate the BB's runtime egress need against where the runtime is
+		// actually placed. We never move the runtime (that's the customer's
+		// explicit choice) — an unsatisfiable requirement is a synth error, not a
+		// silent relocation. This turns an otherwise-silent runtime failure (e.g.
+		// DSQL in an isolated Lambda: deploys clean, times out on every call) into
+		// an actionable build error.
+		if (reqs.requiresEgress) {
+			if (placementHasEgress === false) {
+				throw new Error(
+					`${fullId} requires its runtime to reach the internet (outbound egress), but the ` +
+						`Blocks runtime is placed in subnets with no egress route. ` +
+						`Set 'vpc.subnets' to a 'private-with-egress' (or 'public') selection, or remove ` +
+						`the Building Block that needs it. See packages/blocks/VPC.md.`,
+				);
+			}
+			if (placementHasEgress === undefined) {
+				// Couldn't determine egress (e.g. imported VPC with unknown subnets).
+				// Don't fabricate a pass/fail — warn so a real mismatch isn't silent.
+				Annotations.of(scope).addWarningV2(
+					'blocks:vpc:egress-unverified',
+					`${fullId} requires runtime egress, but Blocks couldn't determine whether the ` +
+						`configured subnets provide it (e.g. an imported VPC). Ensure the runtime's subnets ` +
+						`have an outbound internet route. See packages/blocks/VPC.md.`,
+				);
+			}
+		}
+	}
+
+	if (options.provisionEndpoints === false) {
+		return;
+	}
+
+	// Always add the S3 gateway endpoint. The runtime pulls config/secrets and
+	// migrations from S3 at cold start, so an in-VPC runtime needs it. Gateway
+	// endpoints are free (route-table entries, no ENI), so this is unconditional.
+	gatewayEndpoints.push(ec2.GatewayVpcEndpointAwsService.S3);
+
+	// Provision gateway endpoints (deduplicated). Gateway endpoints attach to
+	// route tables, not ENIs, so they have no security-group layer.
+	const provisionedGateway = new Set<string>();
+
+	for (const service of gatewayEndpoints) {
+		const key = service.name;
+		if (provisionedGateway.has(key)) continue;
+		provisionedGateway.add(key);
+
+		const constructId = `VpcGw${key.replace(/[^a-zA-Z0-9]/g, '')}`;
+		new ec2.GatewayVpcEndpoint(scope, constructId, { vpc, service });
+	}
+
+	// Always add CloudWatch Logs — every in-VPC Lambda needs it for log delivery,
+	// regardless of which Building Blocks are present. SSM is NOT added here: it
+	// flows from BB requirements (AppSetting and the auth blocks, which compose
+	// AppSetting, declare it), so an app that uses neither doesn't pay for an
+	// unused interface endpoint.
+	interfaceEndpoints.push(ec2.InterfaceVpcEndpointAwsService.CLOUDWATCH_LOGS);
+
+	// Dedicated security group for the interface endpoints. Without an explicit
+	// SG, CDK creates a default that allows 443 from the entire VPC CIDR — on a
+	// bring-your-own VPC that exposes every endpoint to unrelated workloads. Scope
+	// ingress to just the Blocks Lambda SG so only our functions can reach them.
+	const ctx = getVpcContext(scope);
+	const endpointSecurityGroup = new ec2.SecurityGroup(scope, 'BlocksVpcEndpointSg', {
+		vpc,
+		description: 'Blocks interface VPC endpoints — 443 from the Blocks Lambda only',
+		allowAllOutbound: true,
+	});
+	if (ctx) {
+		endpointSecurityGroup.addIngressRule(
+			ec2.Peer.securityGroupId(ctx.computeSecurityGroup.securityGroupId),
+			ec2.Port.tcp(443),
+			'HTTPS from Blocks Lambda',
+		);
+	}
+
+	// Provision interface endpoints (deduplicated)
+	const provisionedInterface = new Set<string>();
+
+	for (const service of interfaceEndpoints) {
+		const key = service.name;
+		if (provisionedInterface.has(key)) continue;
+		provisionedInterface.add(key);
+
+		const constructId = `VpcIf${key.replace(/[^a-zA-Z0-9]/g, '')}`;
+		new ec2.InterfaceVpcEndpoint(scope, constructId, {
+			vpc,
+			service,
+			privateDnsEnabled: true,
+			securityGroups: [endpointSecurityGroup],
+			// `open: false` suppresses CDK's default "allow 443 from the whole VPC
+			// CIDR" ingress rule. Our dedicated SG already allows 443 from just the
+			// Blocks Lambda SG; without this, CDK would re-widen access to the entire
+			// VPC — the exact broadening this dedicated SG exists to prevent.
+			open: false,
+		});
+	}
+}
+
+/**
+ * Does the runtime's subnet placement provide egress (an outbound internet
+ * route)? Returns `true`/`false` when determinable, or `undefined` when it
+ * can't be determined at synth (e.g. an imported VPC whose subnets aren't
+ * known) — callers should warn rather than assume.
+ *
+ * Resolved from the actual subnets, not from a subnet *role*, so an explicit
+ * subnet **list** (which carries no `subnetType`) is handled correctly. For a
+ * multi-subnet selection, egress is only reported when **every** selected
+ * subnet has it (a runtime may land in any of them).
+ */
+function placementProvidesEgress(vpc: ec2.IVpc, selection?: ec2.SubnetSelection): boolean | undefined {
+	// Default placement (no selection) is PRIVATE_WITH_EGRESS — see initializeVpc.
+	if (!selection) {
+		return vpc.privateSubnets.length > 0 ? true : undefined;
+	}
+	// Explicit type: egress iff it's the egress tier; isolated/public are known.
+	if (selection.subnetType !== undefined) {
+		switch (selection.subnetType) {
+			case ec2.SubnetType.PRIVATE_WITH_EGRESS:
+				return true;
+			case ec2.SubnetType.PUBLIC:
+				return true; // public subnets route to an internet gateway
+			case ec2.SubnetType.PRIVATE_ISOLATED:
+				return false;
+			default:
+				return undefined;
+		}
+	}
+	// Explicit subnet list (or filter): resolve the concrete subnets and check
+	// that all of them are egress-capable. If resolution yields nothing usable,
+	// we can't tell.
+	try {
+		const { subnets: selected } = vpc.selectSubnets(selection);
+		if (selected.length === 0) return undefined;
+		// A subnet is egress-capable if it's one of the VPC's private (with-egress)
+		// or public subnets. Isolated subnets are in neither list.
+		const egressCapable = new Set<string>([
+			...vpc.privateSubnets.map((s) => s.subnetId),
+			...vpc.publicSubnets.map((s) => s.subnetId),
+		]);
+		// If the VPC exposes no subnet inventory (imported VPC), we can't classify.
+		if (egressCapable.size === 0 && vpc.isolatedSubnets.length === 0) return undefined;
+		return selected.every((s) => egressCapable.has(s.subnetId));
+	} catch {
+		return undefined;
+	}
+}

package/src/errors.ts

@@ -48,6 +48,11 @@ export class ApiError extends Error {
 	 * when `retriable === true`; non-retriable errors (expired session,
 	 * tampered envelope, too-many-attempts lockouts) require restarting the
 	 * flow. Defaults to `false` when unspecified.
+	 *
+	 * This marks whether the *kind* of failure is retriable in principle, not a
+	 * guarantee that a given retry will succeed — e.g. an optimistic-lock
+	 * conflict against a missing row is flagged retriable, yet a blind retry
+	 * fails identically.
 	 */
 	readonly retriable: boolean;
 

package/src/hosting.test.ts

@@ -13,7 +13,7 @@ import { App, Duration, Stack } from 'aws-cdk-lib';
 import { Match, Template } from 'aws-cdk-lib/assertions';
 import { BLOCKS_RPC_PREFIX } from './constants.js';
 import { type BlocksStackApi, Hosting } from './hosting.js';
-import { clearRouteRegistry, registerRoute } from './raw-route.js';
+import { clearRouteRegistry, compilePath, registerRoute, type RegisteredRoute } from './raw-route.js';
 
 // ================================================================
 // Hosting construct tests
@@ -736,6 +736,50 @@ describe('Hosting', () => {
       assert.ok(patterns.includes('/users/*'), 'Should have /users/* behavior for parameterized RawRoute');
     });
 
+    it('adds a CloudFront behavior for a route another core copy registered', () => {
+      createSpaBuildOutput(tmpDir);
+
+      // Synth has the same split as dispatch: a bundle can hold more than one
+      // copy of @aws-blocks/core, and this loop reads whichever route table
+      // its own copy owns. Register the way a second copy would — straight
+      // into the shared state, not through this copy's registerRoute() — and
+      // the behavior must still be emitted. With a module-local registry it
+      // never is, and the route 404s at CloudFront before Lambda is reached.
+      const REGISTRY_KEY = '__AWS_BLOCKS_RAW_ROUTE_REGISTRY_V1__';
+      const state = (globalThis as typeof globalThis & { [REGISTRY_KEY]?: { routes: RegisteredRoute[] } })[
+        REGISTRY_KEY
+      ];
+      assert.ok(state, `route registry state must live on globalThis['${REGISTRY_KEY}']`);
+
+      const { pattern, paramNames } = compilePath('/from-other-copy');
+      state.routes.push({
+        method: 'GET',
+        path: '/from-other-copy',
+        pattern,
+        paramNames,
+        handler: async () => {},
+      });
+
+      const app = new App();
+      const stack = new Stack(app, 'ForeignRouteBehaviorStack');
+
+      new Hosting(stack, 'Hosting', {
+        root: tmpDir,
+        api: MOCK_API,
+      });
+
+      const template = Template.fromStack(stack);
+      const distributions = template.findResources('AWS::CloudFront::Distribution');
+      const distKeys = Object.keys(distributions);
+      const distConfig = (distributions[distKeys[0]] as any).Properties.DistributionConfig;
+      const patterns = (distConfig.CacheBehaviors ?? []).map((b: any) => b.PathPattern);
+
+      assert.ok(
+        patterns.includes('/from-other-copy'),
+        `synth must see routes from every core copy, got: ${JSON.stringify(patterns)}`,
+      );
+    });
+
     it('proxies the reserved /aws-blocks/auth subtree with a single behavior', () => {
       createSpaBuildOutput(tmpDir);
 
@@ -1568,6 +1612,20 @@ describe('Hosting', () => {
         `BlocksConfigDeployment must DependsOn the asset deployment(s); ` +
           `found DependsOn=${JSON.stringify(dependsOn)}`,
       );
+
+      const routeCutoverId = Object.entries(tpl.Resources).find(
+        ([id, resource]) =>
+          resource.Type === 'AWS::CloudFormation::CustomResource' &&
+          /RouteStoreKeys/.test(id),
+      )?.[0];
+      assert.ok(routeCutoverId, 'expected a RouteStoreKeys cutover resource');
+
+      const routeCutoverDeps = tpl.Resources[routeCutoverId].DependsOn ?? [];
+      assert.ok(
+        routeCutoverDeps.includes(configId),
+        `RouteStoreKeys must DependsOn BlocksConfigDeployment; ` +
+          `found DependsOn=${JSON.stringify(routeCutoverDeps)}`,
+      );
     });
   });
 

package/src/hosting.ts

@@ -788,6 +788,9 @@ export class Hosting extends Construct {
       for (const dep of assetDeployments) {
         configDeployment.node.addDependency(dep);
       }
+
+      // Delay route cutover until resolved config replaces the static placeholder.
+      hosting.addBuildAssetDependency(configDeployment);
     }
 
     // ── 9. Register public origin + CORS hosting origin into S3 config ──

package/src/index.cdk.ts

@@ -18,6 +18,7 @@ export {
 	type ValueKind,
 } from '@aws-blocks/hosting';
 export { type ApiHandler, ApiNamespace, type BlocksContext } from './api.js';
+export type { BlocksVpcOptions, ScopeOptions, SubnetRole, VpcContext, VpcRequirements } from './cdk/index.js';
 export {
 	BlocksBackend,
 	type BlocksBackendProps,
@@ -25,14 +26,20 @@ export {
 	BlocksPresets,
 	BlocksStack,
 	type BlocksThrottling,
+	BuildingBlockScope,
 	blocksNodejsBundling,
 	type CoreBlocksBackendProps,
 	type CoreBlocksStackProps,
 	DEFAULT_NODE_RUNTIME,
 	ensureApiGatewayAccount,
 	finalizeConfigRegistry,
+	finalizeDashboards,
+	finalizeTracing,
 	getConfigLocation,
+	getVpcContext,
 	registerConfig,
+	registerDashboardFinalizer,
+	registerTracer,
 	SandboxDisableDeletionProtection,
 	Scope,
 	SHARED_HANDLER_TIMEOUT_SECONDS,

package/src/lambda-handler.test.ts

@@ -5,7 +5,7 @@ import { describe, it, beforeEach } from 'node:test';
 import assert from 'node:assert';
 import { createLambdaHandler, _resetCorsPatterns, requestCookies, isApiGatewayHttpEvent, computeHttpDeadlineMs, classifyEvent, buildEventUrl, isLoopbackForwardedHost, TransientConfigError } from './lambda-handler.js';
 import type { LambdaContext } from './lambda-handler.js';
-import { registerRoute, clearRouteRegistry } from './raw-route.js';
+import { registerRoute, clearRouteRegistry, getRegisteredRoutes } from './raw-route.js';
 import { decodeRpcResponse } from './rpc.js';
 import { _resetConfigCache, _setS3Fetcher } from './common/config.js';
 import type { BlocksContext } from './api.js';
@@ -414,6 +414,84 @@ describe('createLambdaHandler — RawRoute body handling', () => {
 
 // ── Cookie extraction tests ─────────────────────────────────────────────────
 
+// ── Unmatched RawRoute diagnostics ──────────────────────────────────────────
+//
+// A request that matches no RawRoute used to return 404 without a trace in
+// CloudWatch, which is what made the duplicate-core-copy bug invisible.
+
+describe('createLambdaHandler — unmatched RawRoute diagnostics', () => {
+  /** Run `fn` with console.error captured; returns the collected lines. */
+  async function captureErrors(fn: () => Promise<void>): Promise<string[]> {
+    const lines: string[] = [];
+    const original = console.error;
+    console.error = (...args: unknown[]) => {
+      lines.push(args.map((a) => String(a)).join(' '));
+    };
+    try {
+      await fn();
+    } finally {
+      console.error = original;
+    }
+    return lines;
+  }
+
+  it('logs method, path and route count when no RawRoute matches', async () => {
+    registerRoute({ method: 'GET', path: '/known', handler: async (ctx) => ctx.response.send({ ok: true }) });
+
+    let result: any;
+    const logged = await captureErrors(async () => {
+      result = await invoke({}, makeEvent({ httpMethod: 'GET', path: '/unknown', body: null }));
+    });
+
+    assert.strictEqual(result.statusCode, 404);
+    // The count must match the registry the dispatcher actually consulted —
+    // a "0 routes registered" line is the fingerprint of a split registry.
+    const expectedCount = getRegisteredRoutes().length;
+    assert.ok(expectedCount > 0, 'precondition: routes are registered');
+    assert.ok(
+      logged.some(
+        (line) =>
+          line.includes('No RawRoute matched GET /unknown') &&
+          line.includes(`${expectedCount} routes registered`),
+      ),
+      `expected a diagnostic for the unmatched route, got: ${JSON.stringify(logged)}`,
+    );
+  });
+
+  it('does not log when a RawRoute matches', async () => {
+    registerRoute({ method: 'GET', path: '/known', handler: async (ctx) => ctx.response.send({ ok: true }) });
+
+    const logged = await captureErrors(async () => {
+      const result = await invoke({}, makeEvent({ httpMethod: 'GET', path: '/known', body: null }));
+      assert.strictEqual(result.statusCode, 200);
+    });
+
+    assert.deepStrictEqual(logged, []);
+  });
+
+  it('names duplicate core copies as the likely cause when more than one is loaded', async () => {
+    const REGISTRY_KEY = '__AWS_BLOCKS_RAW_ROUTE_REGISTRY_V1__';
+    const state = (globalThis as typeof globalThis & { [REGISTRY_KEY]?: { copies: number } })[REGISTRY_KEY];
+    assert.ok(state, `route registry state must live on globalThis['${REGISTRY_KEY}']`);
+
+    const originalCopies = state.copies;
+    state.copies = 2;
+    try {
+      const logged = await captureErrors(async () => {
+        const result = await invoke({}, makeEvent({ httpMethod: 'GET', path: '/unknown', body: null }));
+        assert.strictEqual(result.statusCode, 404);
+      });
+
+      assert.ok(
+        logged.some((line) => line.includes('2 copies of @aws-blocks/core are loaded')),
+        `expected the copy count in the diagnostic, got: ${JSON.stringify(logged)}`,
+      );
+    } finally {
+      state.copies = originalCopies;
+    }
+  });
+});
+
 describe('createLambdaHandler — cookie extraction', () => {
   it('extracts cookies from lowercase "cookie" header (API Gateway v2)', async () => {
     let capturedCookies = '';

package/src/lambda-handler.ts

@@ -5,7 +5,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { ApiError } from './errors.js';
 import { BLOCKS_RPC_PREFIX } from './constants.js';
-import { matchRoute, lockRouteRegistry } from './raw-route.js';
+import { matchRoute, lockRouteRegistry, getRegisteredRoutes, getLoadedCoreCopies } from './raw-route.js';
 import { registerBuiltinRoutes } from './builtin-routes.js';
 import { loadConfigToProcessEnv, isConfigResolved } from './common/config.js';
 import {
@@ -529,8 +529,17 @@ function createHandler(backend: any) {
       if (matched) {
         return handleRawRoute(event, matched.route, matched.params, corsHeaders, signal);
       }
-      // No RawRoute matched and path is not the RPC endpoint — return 404
+      // No RawRoute matched and path is not the RPC endpoint — return 404.
+      // Log it: an unmatched route used to be entirely silent, which is what
+      // made a split route registry (duplicate @aws-blocks/core copies)
+      // undiagnosable from CloudWatch alone. The path is already in the API
+      // Gateway access logs, so this adds no new category of data.
       if (!requestPath.startsWith(BLOCKS_RPC_PREFIX)) {
+        const copies = getLoadedCoreCopies();
+        const copiesNote = copies > 1 ? ` — ${copies} copies of @aws-blocks/core are loaded` : '';
+        console.error(
+          `No RawRoute matched ${httpMethod} ${requestPath} (${getRegisteredRoutes().length} routes registered)${copiesNote}`,
+        );
         return {
           statusCode: 404,
           headers: {