@aws-blocks/core 0.3.0 → 0.5.0

package/dist/lambda-handler.test.js

@@ -2,9 +2,10 @@
 // SPDX-License-Identifier: Apache-2.0
 import { describe, it, beforeEach } from 'node:test';
 import assert from 'node:assert';
-import { createLambdaHandler, _resetCorsPatterns, requestCookies, isApiGatewayHttpEvent, computeHttpDeadlineMs, classifyEvent, buildEventUrl, isLoopbackForwardedHost } from './lambda-handler.js';
-import { registerRoute, clearRouteRegistry } from './raw-route.js';
+import { createLambdaHandler, _resetCorsPatterns, requestCookies, isApiGatewayHttpEvent, computeHttpDeadlineMs, classifyEvent, buildEventUrl, isLoopbackForwardedHost, TransientConfigError } from './lambda-handler.js';
+import { registerRoute, clearRouteRegistry, getRegisteredRoutes } from './raw-route.js';
 import { decodeRpcResponse } from './rpc.js';
+import { _resetConfigCache, _setS3Fetcher } from './common/config.js';
 beforeEach(() => {
     clearRouteRegistry();
 });
@@ -22,6 +23,134 @@ async function invoke(backend, event) {
     const handler = createLambdaHandler(async () => backend);
     return handler(event);
 }
+// ── init self-heal (retry on failed initialization) ─────────────────────────
+describe('createLambdaHandler — init self-heal', () => {
+    it('retries initialize() on a later request instead of caching a failed init', async () => {
+        let initCalls = 0;
+        const backend = {
+            api: (_ctx) => ({
+                async echo(msg) {
+                    return { msg };
+                },
+            }),
+        };
+        // Fail the first initialization (e.g. config not readable yet in the brief post-deploy
+        // window), then succeed. The SAME handler instance must recover — a cached rejected
+        // initPromise would poison the container and fail every subsequent request.
+        const backendFactory = async () => {
+            initCalls++;
+            if (initCalls === 1)
+                throw new Error('transient init failure');
+            return backend;
+        };
+        const handler = createLambdaHandler(backendFactory);
+        // 1st request: init fails, so the handler rejects.
+        await assert.rejects(() => handler(makeEvent()), /transient init failure/);
+        // 2nd request: init is retried and succeeds → 200 (not a re-thrown cached rejection).
+        const res = (await handler(makeEvent()));
+        assert.strictEqual(res.statusCode, 200);
+        assert.strictEqual(initCalls, 2, 'initialize() must be retried on the next request, not cached');
+    });
+    it('recovers from a transient-empty (post-deploy 404) config load on the next request', async () => {
+        // Reproduces the poisoned-container bug: the first S3 load hits the transient
+        // post-deploy window (NoSuchKey), so config resolves empty; the handler must
+        // NOT lock in that empty config, and the NEXT request must re-fetch and pick
+        // up the now-present config.
+        _resetConfigCache();
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        delete process.env.SELFHEAL_KEY;
+        let fetchCall = 0;
+        const notFound = new Error('The specified key does not exist.');
+        notFound.name = 'NoSuchKey';
+        _setS3Fetcher(async () => {
+            fetchCall++;
+            if (fetchCall === 1)
+                throw notFound; // config not readable yet
+            return JSON.stringify({ SELFHEAL_KEY: 'ready' });
+        });
+        let backendImports = 0;
+        const handler = createLambdaHandler(async () => {
+            backendImports++;
+            return {
+                api: (_ctx) => ({
+                    async echo(msg) { return { msg, cfg: process.env.SELFHEAL_KEY }; },
+                }),
+            };
+        });
+        try {
+            // 1st request: transient-empty load → initialize() throws TransientConfigError
+            // BEFORE importing the backend (so we never lock in empty config), and the
+            // request rejects.
+            await assert.rejects(() => handler(makeEvent()), TransientConfigError);
+            assert.strictEqual(backendImports, 0, 'backend must NOT be imported while config is unresolved');
+            // 2nd request: config now present → initialize() re-runs, re-fetches, and
+            // injects the config into process.env before importing the backend.
+            const res = (await handler(makeEvent()));
+            assert.strictEqual(res.statusCode, 200);
+            const body = JSON.parse(res.body);
+            assert.strictEqual(body.result.cfg, 'ready', 'now-present config was injected on the retry');
+            assert.strictEqual(backendImports, 1, 'backend imported exactly once, on the successful retry');
+            assert.strictEqual(fetchCall, 2, 'S3 was re-fetched on the retry (transient miss is not cached)');
+        }
+        finally {
+            _resetConfigCache();
+            delete process.env.BLOCKS_CONFIG_BUCKET;
+            delete process.env.BLOCKS_CONFIG_KEY;
+            delete process.env.SELFHEAL_KEY;
+        }
+    });
+    it('does NOT re-init for a config-less app (no bucket, local dev) — initialize runs once', async () => {
+        _resetConfigCache();
+        delete process.env.BLOCKS_CONFIG_BUCKET;
+        delete process.env.BLOCKS_CONFIG_KEY;
+        let backendImports = 0;
+        const handler = createLambdaHandler(async () => {
+            backendImports++;
+            return { api: (_ctx) => ({ async echo(msg) { return { msg }; } }) };
+        });
+        try {
+            const r1 = (await handler(makeEvent()));
+            const r2 = (await handler(makeEvent()));
+            assert.strictEqual(r1.statusCode, 200);
+            assert.strictEqual(r2.statusCode, 200);
+            assert.strictEqual(backendImports, 1, 'no re-init for a genuinely config-less (local dev) app');
+        }
+        finally {
+            _resetConfigCache();
+        }
+    });
+    it('does NOT re-init or spin for a genuinely-empty ({}) S3 config', async () => {
+        // A real, readable empty config must be treated as resolved — distinct from
+        // the transient 404 miss — so the container does not throw/retry forever nor
+        // re-fetch S3 on every request.
+        _resetConfigCache();
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        let fetchCall = 0;
+        _setS3Fetcher(async () => { fetchCall++; return JSON.stringify({}); });
+        let backendImports = 0;
+        const handler = createLambdaHandler(async () => {
+            backendImports++;
+            return { api: (_ctx) => ({ async echo(msg) { return { msg }; } }) };
+        });
+        try {
+            const r1 = (await handler(makeEvent()));
+            const r2 = (await handler(makeEvent()));
+            const r3 = (await handler(makeEvent()));
+            assert.strictEqual(r1.statusCode, 200);
+            assert.strictEqual(r2.statusCode, 200);
+            assert.strictEqual(r3.statusCode, 200);
+            assert.strictEqual(backendImports, 1, 'genuinely-empty config resolves; no re-init');
+            assert.strictEqual(fetchCall, 1, 'S3 fetched once and cached — no per-request re-fetch spin');
+        }
+        finally {
+            _resetConfigCache();
+            delete process.env.BLOCKS_CONFIG_BUCKET;
+            delete process.env.BLOCKS_CONFIG_KEY;
+        }
+    });
+});
 // ── RPC body tests ──────────────────────────────────────────────────────────
 describe('createLambdaHandler — RPC body handling', () => {
     it('populates ctx.request.body as a ReadableStream for RPC calls', async () => {
@@ -224,6 +353,66 @@ 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) {
+        const lines = [];
+        const original = console.error;
+        console.error = (...args) => {
+            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;
+        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[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/dist/raw-route.d.ts

@@ -72,6 +72,16 @@ export interface RegisteredRoute {
     paramNames: string[];
     handler: (context: BlocksContext) => Promise<void>;
 }
+/**
+ * Number of `@aws-blocks/core` copies taking part in the shared route registry.
+ *
+ * `1` for a healthy install. A higher number means the dependency tree carries
+ * duplicates — routes still work (the registry is shared), but it is worth
+ * reporting in diagnostics.
+ *
+ * **Internal.** Not re-exported from the package entry point.
+ */
+export declare function getLoadedCoreCopies(): number;
 /** Prevent further route registration. Call after initialization is complete. */
 export declare function lockRouteRegistry(): void;
 /** Re-allow route registration (useful in tests after lock). */
@@ -92,7 +102,11 @@ export declare function registerRoute(options: RawRouteOptions & {
 }): void;
 /** Return a read-only snapshot of all registered routes. */
 export declare function getRegisteredRoutes(): readonly RegisteredRoute[];
-/** Remove all registered routes and unlock registration (used by tests). */
+/**
+ * Remove all registered routes and unlock registration (used by tests).
+ *
+ * Leaves the copy counter alone — it tracks module copies, not routes.
+ */
 export declare function clearRouteRegistry(): void;
 /**
  * Match an incoming HTTP request against registered routes.

package/dist/raw-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"raw-route.d.ts","sourceRoot":"","sources":["../src/raw-route.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKrD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,UAAU,CAAC;IACnB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc;;CAEjB,CAAC;AAIX;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAc1E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAEjG;AAID,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAOD,iFAAiF;AACjF,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,gEAAgE;AAChE,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAuC/E;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,IAAI,SAAS,eAAe,EAAE,CAEhE;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAoBnE;AA6BD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAgEnF"}
+{"version":3,"file":"raw-route.d.ts","sourceRoot":"","sources":["../src/raw-route.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKrD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,UAAU,CAAC;IACnB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc;;CAEjB,CAAC;AAIX;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAc1E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAEjG;AAID,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAmGD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAID,iFAAiF;AACjF,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,gEAAgE;AAChE,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAwC/E;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,IAAI,SAAS,eAAe,EAAE,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAoBnE;AA6BD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAgEnF"}

package/dist/raw-route.js

@@ -60,16 +60,94 @@ export function derivePathFromScope(scope, id) {
 export function resolveRoutePath(scope, id, options) {
     return options.path ?? derivePathFromScope(scope, id);
 }
-const routeRegistry = [];
-let registrationLocked = false;
+/**
+ * Well-known `globalThis` key holding the shared registry state.
+ *
+ * A plain string rather than a `Symbol.for()` key, deliberately: duplicate
+ * copies are diagnosed by counting strings in the deployed bundle, and a
+ * symbol would be invisible to that. It also matches the existing
+ * `__BLOCKS_LAMBDA_EVENT_HANDLERS__` precedent.
+ *
+ * **The key is a permanent contract — do not bump it.** `_V1_` names the shape
+ * this file introduced; it is not a license to mint `_V2_`. The copies that
+ * share a process are usually *different versions* of `@aws-blocks/core` — that
+ * is how a tree ends up with duplicates in the first place — so a copy reading
+ * a different key does not get a private namespace, it re-splits the registry:
+ * routes registered through one key, dispatched through the other, 404. And
+ * silently, because each key carries its own `copies` counter, so both sides
+ * report `copies: 1` and the duplicate warning never fires. That is the bug
+ * this module exists to fix, reintroduced with its own diagnostic switched off.
+ *
+ * Evolve the shape **additively** instead: add optional fields, and tolerate
+ * fields a peer copy did not write (`getState()` does). If a `_V2_` key ever
+ * proves unavoidable, it has to adopt the V1 state — read it, and keep writing
+ * it — so that a mixed tree still routes through one table.
+ */
+const REGISTRY_KEY = '__AWS_BLOCKS_RAW_ROUTE_REGISTRY_V1__';
+/** Whether *this* module copy has already counted itself. Intentionally module-local. */
+let thisCopyCounted = false;
+/**
+ * Resolve the shared registry state, creating it on first access.
+ *
+ * The copy count is incremented here rather than at module load so that it
+ * counts the copies actually taking part in routing, not every copy a bundle
+ * happens to carry. Bundled code is where duplicate copies occur, and a copy
+ * that is imported but never routes is not what the diagnostic is about.
+ *
+ * Tree-shaking is not the reason. `sideEffects` in package.json lets a bundler
+ * drop this module whole when nothing it exports is used, but a module that
+ * *is* used keeps its top-level statements — measured with esbuild under
+ * `--bundle --minify`, and covered by the bundling test in `raw-route.test.ts`.
+ */
+function getState() {
+    const g = globalThis;
+    let state = g[REGISTRY_KEY];
+    if (!state) {
+        state = { routes: [], locked: false, copies: 0 };
+        g[REGISTRY_KEY] = state;
+    }
+    // The state may have been left by a copy that evolved the shape (see the
+    // contract on REGISTRY_KEY), so fill in what this copy needs rather than
+    // assume it is there. A missing `routes` would throw on the first
+    // registration, and a missing `copies` would go NaN on the increment below —
+    // silencing the duplicate warning, which is the failure this module exists to
+    // report. `locked` needs no default: absent reads as unlocked, which is what
+    // a registry still accepting registrations means.
+    if (!Array.isArray(state.routes))
+        state.routes = [];
+    if (typeof state.copies !== 'number')
+        state.copies = 0;
+    if (!thisCopyCounted) {
+        thisCopyCounted = true;
+        state.copies += 1;
+        if (state.copies > 1) {
+            console.warn(`AWS Blocks: ${state.copies} copies of @aws-blocks/core loaded in this process. ` +
+                'They now share one RawRoute registry, but duplicate copies indicate a ' +
+                'dependency-tree problem — deduplicate @aws-blocks/core.');
+        }
+    }
+    return state;
+}
+/**
+ * Number of `@aws-blocks/core` copies taking part in the shared route registry.
+ *
+ * `1` for a healthy install. A higher number means the dependency tree carries
+ * duplicates — routes still work (the registry is shared), but it is worth
+ * reporting in diagnostics.
+ *
+ * **Internal.** Not re-exported from the package entry point.
+ */
+export function getLoadedCoreCopies() {
+    return getState().copies;
+}
 const VALID_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']);
 /** Prevent further route registration. Call after initialization is complete. */
 export function lockRouteRegistry() {
-    registrationLocked = true;
+    getState().locked = true;
 }
 /** Re-allow route registration (useful in tests after lock). */
 export function unlockRouteRegistry() {
-    registrationLocked = false;
+    getState().locked = false;
 }
 /**
  * Register a raw HTTP route for runtime dispatch.
@@ -83,7 +161,8 @@ export function unlockRouteRegistry() {
  * @throws {RawRouteErrors.DuplicateRoute} If the same method+path is registered twice.
  */
 export function registerRoute(options) {
-    if (registrationLocked) {
+    const state = getState();
+    if (state.locked) {
         throw new Error('Routes must be registered during initialization. Cannot register routes after handler creation.');
     }
     if (!VALID_METHODS.has(options.method)) {
@@ -97,14 +176,14 @@ export function registerRoute(options) {
     if (lowerPath === BLOCKS_NAMESPACE || lowerPath === BLOCKS_RPC_PREFIX || lowerPath.startsWith(`${BLOCKS_RPC_PREFIX}/`)) {
         throw new Error(`Cannot register RawRoute at ${BLOCKS_NAMESPACE} or ${BLOCKS_RPC_PREFIX}/* — these paths are reserved for RPC dispatch`);
     }
-    const existing = routeRegistry.find((r) => r.method === options.method && r.path === normalizedPath);
+    const existing = state.routes.find((r) => r.method === options.method && r.path === normalizedPath);
     if (existing) {
         const err = new Error(`${RawRouteErrors.DuplicateRoute}: ${options.method} ${normalizedPath} is already registered`);
         err.name = RawRouteErrors.DuplicateRoute;
         throw err;
     }
     const { pattern, paramNames } = compilePath(normalizedPath);
-    routeRegistry.push({
+    state.routes.push({
         method: options.method,
         path: normalizedPath,
         pattern,
@@ -114,12 +193,17 @@ export function registerRoute(options) {
 }
 /** Return a read-only snapshot of all registered routes. */
 export function getRegisteredRoutes() {
-    return routeRegistry;
+    return getState().routes;
 }
-/** Remove all registered routes and unlock registration (used by tests). */
+/**
+ * Remove all registered routes and unlock registration (used by tests).
+ *
+ * Leaves the copy counter alone — it tracks module copies, not routes.
+ */
 export function clearRouteRegistry() {
-    routeRegistry.length = 0;
-    registrationLocked = false;
+    const state = getState();
+    state.routes.length = 0;
+    state.locked = false;
 }
 /**
  * Match an incoming HTTP request against registered routes.
@@ -129,7 +213,7 @@ export function clearRouteRegistry() {
 export function matchRoute(method, path) {
     // Normalize incoming path: collapse double slashes
     path = path.replace(/\/+/g, '/');
-    for (const route of routeRegistry) {
+    for (const route of getState().routes) {
         if (route.method !== method)
             continue;
         const match = route.pattern.exec(path);