@aws-blocks/core 0.3.0 → 0.5.0

package/dist/raw-route.test.js

@@ -1,7 +1,13 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import { describe, it, beforeEach } from 'node:test';
+import { describe, it, before, beforeEach } from 'node:test';
 import assert from 'node:assert';
+import { spawnSync } from 'node:child_process';
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildSync } from 'esbuild';
 import { compilePath, registerRoute, matchRoute, getRegisteredRoutes, clearRouteRegistry, lockRouteRegistry, unlockRouteRegistry, RawRouteErrors, derivePathFromScope, resolveRoutePath, } from './raw-route.js';
 const noop = async (_ctx) => { };
 /** Create a null-prototype object for comparing with params from matchRoute. */
@@ -595,3 +601,328 @@ describe('resolveRoutePath', () => {
         assert.strictEqual(path, '/v1/users');
     });
 });
+// ── Cross-copy registry sharing ─────────────────────────────────────────────
+//
+// A bundle can contain more than one physical copy of @aws-blocks/core (an
+// unlucky dependency tree, no dedupe). With module-local registry state, every
+// copy gets its own route table: Building Blocks register into theirs, the
+// dispatcher reads its own, and the routes 404 silently.
+//
+// These tests stand in for a second copy: they poke the shared state directly
+// through globalThis, exactly as a second copy of the module would see it.
+// The key is spelled out as a literal on purpose — it IS the cross-copy
+// contract, so changing it must break a test.
+const REGISTRY_KEY = '__AWS_BLOCKS_RAW_ROUTE_REGISTRY_V1__';
+/** Read the registry state that a second core copy would share with us. */
+function sharedState() {
+    const state = globalThis[REGISTRY_KEY];
+    assert.ok(state, `route registry state must live on globalThis['${REGISTRY_KEY}']`);
+    return state;
+}
+describe('registry state is shared across core copies', () => {
+    it('matchRoute() resolves a route registered by another core copy', () => {
+        const { pattern, paramNames } = compilePath('/from-other-copy');
+        sharedState().routes.push({
+            method: 'GET',
+            path: '/from-other-copy',
+            pattern,
+            paramNames,
+            handler: noop,
+        });
+        const result = matchRoute('GET', '/from-other-copy');
+        assert.ok(result, 'route registered by another copy must be dispatchable');
+        assert.strictEqual(result.route.path, '/from-other-copy');
+    });
+    it('getRegisteredRoutes() reports routes registered by another core copy', () => {
+        const { pattern, paramNames } = compilePath('/synth-visible');
+        sharedState().routes.push({
+            method: 'GET',
+            path: '/synth-visible',
+            pattern,
+            paramNames,
+            handler: noop,
+        });
+        // Synth-time consumers (CloudFront behaviors in hosting.ts) iterate this.
+        assert.ok(getRegisteredRoutes().some((r) => r.path === '/synth-visible'));
+    });
+    it('registerRoute() publishes the route into the shared state', () => {
+        registerRoute({ method: 'POST', path: '/published', handler: noop });
+        assert.ok(sharedState().routes.some((r) => r.method === 'POST' && r.path === '/published'), 'another copy must be able to see routes we registered');
+    });
+    it('registerRoute() honours a lock set by another core copy', () => {
+        sharedState().locked = true;
+        assert.throws(() => registerRoute({ method: 'GET', path: '/after-foreign-lock', handler: noop }), (err) => {
+            assert.ok(err.message.includes('Cannot register routes after handler creation'));
+            return true;
+        });
+    });
+    it('lockRouteRegistry() locks the shared state, not a module-local flag', () => {
+        lockRouteRegistry();
+        assert.strictEqual(sharedState().locked, true);
+    });
+    it('clearRouteRegistry() clears the shared state and releases the shared lock', () => {
+        registerRoute({ method: 'GET', path: '/leftover', handler: noop });
+        lockRouteRegistry();
+        clearRouteRegistry();
+        assert.deepStrictEqual(sharedState().routes, []);
+        assert.strictEqual(sharedState().locked, false);
+    });
+    it('clearRouteRegistry() does not reset the copy counter', () => {
+        const before = sharedState().copies;
+        clearRouteRegistry();
+        assert.strictEqual(sharedState().copies, before, 'copies counts module loads, not routes');
+    });
+    // Behavior change, deliberately kept: with a shared registry, duplicate
+    // detection reaches across copies for the first time. An app with two core
+    // copies AND two instances of the same Building Block used to split the
+    // routes silently (half of them 404ing); it now fails loudly at startup.
+    // The app was already broken — this only makes it say so.
+    it('rejects a duplicate of a route another core copy registered', () => {
+        const { pattern, paramNames } = compilePath('/shared-path');
+        sharedState().routes.push({
+            method: 'GET',
+            path: '/shared-path',
+            pattern,
+            paramNames,
+            handler: noop,
+        });
+        assert.throws(() => registerRoute({ method: 'GET', path: '/shared-path', handler: noop }), (err) => {
+            assert.strictEqual(err.name, RawRouteErrors.DuplicateRoute);
+            return true;
+        });
+    });
+});
+describe('duplicate core copies are announced', () => {
+    /**
+     * Use raw-route.js in a fresh process, optionally pre-seeding the shared
+     * state as an earlier copy would have left it, and return stderr.
+     *
+     * The copy must be *used*, not merely imported: the counter increments on
+     * first registry access, so a copy that never touches the registry is never
+     * counted — deliberately, since only routing copies matter here.
+     */
+    function useInFreshProcess(preSeededCopies) {
+        const moduleUrl = new URL('./raw-route.js', import.meta.url).href;
+        const seed = preSeededCopies === null
+            ? ''
+            : `globalThis[${JSON.stringify(REGISTRY_KEY)}] = { routes: [], locked: false, copies: ${preSeededCopies} };`;
+        const script = `${seed}const m = await import(${JSON.stringify(moduleUrl)}); m.registerRoute({ method: 'GET', path: '/probe', handler: async () => {} });`;
+        const result = spawnSync(process.execPath, ['--input-type=module', '-e', script], { encoding: 'utf8' });
+        assert.strictEqual(result.status, 0, `using raw-route.js failed: ${result.stderr}`);
+        return result.stderr;
+    }
+    it('warns when a second copy of @aws-blocks/core joins the shared registry', () => {
+        const stderr = useInFreshProcess(1);
+        assert.match(stderr, /2 copies of @aws-blocks\/core/);
+    });
+    it('stays silent for a healthy single-copy install', () => {
+        const stderr = useInFreshProcess(null);
+        assert.doesNotMatch(stderr, /copies of @aws-blocks\/core/);
+    });
+    it('warns once per copy, not once per registry access', () => {
+        const moduleUrl = new URL('./raw-route.js', import.meta.url).href;
+        const script = `globalThis[${JSON.stringify(REGISTRY_KEY)}] = { routes: [], locked: false, copies: 1 };
+      const m = await import(${JSON.stringify(moduleUrl)});
+      m.registerRoute({ method: 'GET', path: '/a', handler: async () => {} });
+      m.registerRoute({ method: 'GET', path: '/b', handler: async () => {} });
+      m.matchRoute('GET', '/a');`;
+        const result = spawnSync(process.execPath, ['--input-type=module', '-e', script], { encoding: 'utf8' });
+        assert.strictEqual(result.status, 0, result.stderr);
+        const warnings = result.stderr.split('\n').filter((line) => line.includes('copies of @aws-blocks/core'));
+        assert.strictEqual(warnings.length, 1, `expected exactly one warning, got: ${JSON.stringify(warnings)}`);
+    });
+});
+// ── A peer copy's state is adopted, not trusted ─────────────────────────────
+//
+// The registry key is a permanent contract: copies sharing a process are
+// usually different *versions* of @aws-blocks/core, so the shape may only grow
+// — a copy that renamed the key would re-split the registry silently, each key
+// holding its own copy counter. The other half of that contract is this side:
+// a copy must cope with a state a peer left without the fields it expects.
+describe('registry state from a peer copy is adopted, not trusted', () => {
+    /**
+     * Import raw-route.js in a fresh process on top of a pre-seeded shared state
+     * and report what the copy made of it.
+     *
+     * `seed` stands in for a copy whose registry shape differs from this one's.
+     * Fields are omitted, never renamed — that is exactly the evolution the key's
+     * contract permits.
+     */
+    function useOnTopOf(seed) {
+        const moduleUrl = new URL('./raw-route.js', import.meta.url).href;
+        const script = `globalThis[${JSON.stringify(REGISTRY_KEY)}] = ${seed};
+      const m = await import(${JSON.stringify(moduleUrl)});
+      m.registerRoute({ method: 'GET', path: '/probe', handler: async () => {} });
+      console.log(JSON.stringify({
+        matched: m.matchRoute('GET', '/probe') !== null,
+        copies: m.getLoadedCoreCopies(),
+      }));`;
+        const result = spawnSync(process.execPath, ['--input-type=module', '-e', script], { encoding: 'utf8' });
+        assert.strictEqual(result.status, 0, `using raw-route.js failed: ${result.stderr}`);
+        // NaN serializes to null — which is the point of reporting it this way.
+        return JSON.parse(result.stdout.trim());
+    }
+    it('registers into a state that arrived without a route table', () => {
+        const { matched } = useOnTopOf('{ locked: false, copies: 1 }');
+        assert.strictEqual(matched, true, 'a missing route table must be created, not thrown on');
+    });
+    it('keeps the copy count a number when the state arrived without one', () => {
+        const { copies } = useOnTopOf('{ routes: [], locked: false }');
+        assert.strictEqual(copies, 1, 'a missing counter must restart at a number — NaN would mute the warning');
+    });
+});
+/**
+ * The probe itself: a Building Block registers its route through one copy of
+ * the package, the dispatcher looks it up through the other.
+ *
+ * Kept as a standalone ES module with static imports so the very same source
+ * can be run as-is and, in the test below, sent through a bundler first.
+ */
+const TWO_COPY_ENTRY = `
+import * as a from './copy-a/dist/raw-route.js';
+import * as b from './copy-b/dist/raw-route.js';
+
+a.registerRoute({ method: 'GET', path: '/aws-blocks/auth/signin/google', handler: async () => {} });
+const matched = b.matchRoute('GET', '/aws-blocks/auth/signin/google');
+
+const observed = {
+  distinctInstances: a !== b,
+  matchedPath: matched ? matched.route.path : null,
+  routesSeenByDispatcher: b.getRegisteredRoutes().length,
+  copiesReported: null,
+};
+// Report the routing facts even if the diagnostics helper is missing or
+// throws — whether the route resolves is what this probe is about, and a
+// build that lost the helper must not hide that behind a crashed child.
+try {
+  observed.copiesReported = b.getLoadedCoreCopies();
+} catch {}
+console.log(JSON.stringify(observed));
+`;
+/**
+ * Install two physical copies of this package and route a request across them.
+ *
+ * Runs in a child process so the copies start from a clean `globalThis` and
+ * cannot leak registry state into this test run. The whole directory is copied
+ * rather than the two files currently needed, so the probe keeps working when
+ * `raw-route.js` grows an import.
+ *
+ * With `bundle`, the probe is first bundled the way a deployed handler is —
+ * `NodejsFunction` runs esbuild with `--conditions=aws-runtime` — before it is
+ * executed.
+ */
+function runTwoCopyProbe({ bundle }) {
+    const distDir = dirname(fileURLToPath(import.meta.url));
+    const packageDir = dirname(distDir);
+    const root = mkdtempSync(join(tmpdir(), 'aws-blocks-two-copies-'));
+    try {
+        // Copy A belongs to the Building Block, copy B to the dispatcher. Each is
+        // laid out as an installed package — `package.json` beside `dist/`, the
+        // shape npm produces for a nested `node_modules/@aws-blocks/core`. The
+        // manifest has to come along: a real install has one, and it is what a
+        // bundler reads for `type` and `sideEffects` — without it the bundle here
+        // would be built under different rules than the deployed one.
+        for (const copy of ['copy-a', 'copy-b']) {
+            cpSync(distDir, join(root, copy, 'dist'), { recursive: true });
+            cpSync(join(packageDir, 'package.json'), join(root, copy, 'package.json'));
+        }
+        const entry = join(root, 'entry.mjs');
+        writeFileSync(entry, TWO_COPY_ENTRY);
+        let script = entry;
+        let bundleText = null;
+        if (bundle) {
+            const outfile = join(root, 'bundle.mjs');
+            buildSync({
+                entryPoints: [entry],
+                outfile,
+                bundle: true,
+                format: 'esm',
+                platform: 'node',
+                conditions: ['aws-runtime'],
+                minify: true,
+                logLevel: 'silent',
+            });
+            bundleText = readFileSync(outfile, 'utf8');
+            script = outfile;
+        }
+        const result = spawnSync(process.execPath, [script], { encoding: 'utf8' });
+        assert.strictEqual(result.status, 0, `two-copy probe failed: ${result.stderr}`);
+        return {
+            ...JSON.parse(result.stdout),
+            stderr: result.stderr,
+            bundleText,
+        };
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+describe('two physical core copies share one registry', () => {
+    let probe;
+    before(() => {
+        probe = runTwoCopyProbe({ bundle: false });
+    });
+    it('loads two separate module instances', () => {
+        // Guards the probe itself: if this ever collapses to one instance, the
+        // tests below would pass without exercising anything.
+        assert.strictEqual(probe.distinctInstances, true);
+    });
+    it('dispatches a route the other copy registered', () => {
+        assert.strictEqual(probe.matchedPath, '/aws-blocks/auth/signin/google', 'the dispatcher copy must resolve a route registered through the other copy');
+    });
+    it('shows the route in the table the dispatcher consults', () => {
+        // A zero here is the fingerprint of the original defect: registration
+        // succeeded, and the dispatcher looked at an empty table.
+        assert.strictEqual(probe.routesSeenByDispatcher, 1);
+    });
+    it('counts and announces both copies', () => {
+        assert.strictEqual(probe.copiesReported, 2);
+        assert.match(probe.stderr, /2 copies of @aws-blocks\/core/);
+    });
+});
+// ── The same thing, but bundled ─────────────────────────────────────────────
+//
+// Duplicate copies are a bundling phenomenon: the reported defect was found in
+// a deployed bundle, not in a node_modules tree at rest. A deployed handler is
+// built by `NodejsFunction`, which runs esbuild with `--conditions=aws-runtime`
+// (see cdk/blocks-backend.ts), so this repeats that step and then runs the
+// result. Minified on purpose — it is the harsher case, and passing it implies
+// the unminified one.
+//
+// What this pins down that the unbundled probe cannot:
+//
+//   - that a bundler keeps two copies of the same file at different paths
+//     rather than collapsing them, i.e. that the failure mode reaches the
+//     deployed artifact at all;
+//   - that reaching the registry through `globalThis[<string key>]` survives
+//     minification, so the two copies still meet;
+//   - that the key stays a greppable literal, which is the documented way to
+//     diagnose a duplicate install in a deployed bundle (and the reason it is
+//     a plain string rather than a `Symbol.for()` key).
+//
+// What it deliberately does *not* claim: that counting copies on first use
+// rather than at module load is required to survive tree-shaking. That was
+// measured — with `sideEffects` honoured and `--minify` on, esbuild retains a
+// top-level counter here, because a module whose exports are used is kept
+// whole. Counting on first use stands on its other stated reason: it counts the
+// copies that take part in routing, not the ones merely imported.
+describe('the shared registry survives bundling', () => {
+    let probe;
+    before(() => {
+        probe = runTwoCopyProbe({ bundle: true });
+    });
+    it('keeps two participating copies in one bundle', () => {
+        // Also guards the test: were the two copies collapsed into one module
+        // scope, the assertions below would pass without ever crossing a copy
+        // boundary — and there would be no defect left to protect against.
+        assert.strictEqual(probe.copiesReported, 2, 'the bundle must still contain two participating copies');
+        assert.strictEqual(probe.distinctInstances, true);
+    });
+    it('dispatches a route the other copy registered', () => {
+        assert.strictEqual(probe.matchedPath, '/aws-blocks/auth/signin/google');
+        assert.strictEqual(probe.routesSeenByDispatcher, 1);
+    });
+    it('keeps the registry key greppable in the bundle', () => {
+        assert.ok(probe.bundleText?.includes('__AWS_BLOCKS_RAW_ROUTE_REGISTRY_V1__'));
+    });
+});

package/dist/scripts/dev-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/scripts/dev-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/scripts/dev-server.ts"],"names":[],"mappings":"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"}

package/dist/scripts/dev-server.js

@@ -784,6 +784,10 @@ export async function startDevServer(options) {
     });
     // WebSocket upgrade — route to frontend (HMR) or dev attachments
     server.on('upgrade', (req, socket, head) => {
+        // A stale client can reset the connection mid-upgrade (ECONNRESET). The raw
+        // socket has no 'error' listener at this point, so Node's default handler
+        // would kill the dev server. Attach one before any parsing/routing.
+        socket.on('error', () => socket.destroy());
         const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
         if (url.pathname === '/realtime')
             return; // handled by dev attachment (noServer mode)
@@ -869,6 +873,13 @@ export async function startDevServer(options) {
         onExhausted: () => process.exit(1),
         warn: (msg) => console.error(msg),
     });
+    // Malformed/aborted requests must not become unhandled socket errors.
+    server.on('clientError', (_err, socket) => {
+        if (socket.writable)
+            socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+        else
+            socket.destroy();
+    });
     server.on('error', (err) => {
         if (err.code === 'EADDRINUSE') {
             // Keep the telemetry signal (unchanged) …

package/dist/scripts/extract-ts-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-ts-types.d.ts","sourceRoot":"","sources":["../../src/scripts/extract-ts-types.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,gBAAgB;IAChC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,+GAA+G;IAC/G,QAAQ,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,UAAU,EAAE,UAAU,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAS3D;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CA4DzE;AAED,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAC5C,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,oBAAoB,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAqElF"}
+{"version":3,"file":"extract-ts-types.d.ts","sourceRoot":"","sources":["../../src/scripts/extract-ts-types.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,gBAAgB;IAChC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,+GAA+G;IAC/G,QAAQ,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,UAAU,EAAE,UAAU,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAS3D;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAgEzE;AAED,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAC5C,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,oBAAoB,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAoHlF"}

package/dist/scripts/extract-ts-types.js

@@ -46,13 +46,16 @@ export function extractSkipCodegenMethods(sourcePath) {
         return result;
     const sourceFile = ts.createSourceFile(absPath, fileText, ts.ScriptTarget.ESNext, 
     /*setParentNodes*/ true, ts.ScriptKind.TS);
-    function visitObjectLiteral(obj) {
+    function visitObjectLiteral(obj, namespaceName) {
         for (const prop of obj.properties) {
             if (ts.isMethodDeclaration(prop) &&
                 prop.name &&
                 ts.isIdentifier(prop.name) &&
                 hasBlocksSkipCodegenTag(prop)) {
-                result.add(prop.name.text);
+                // Qualify by namespace (like extractMethodTypes) so a tag on one
+                // namespace's `create` doesn't cause another namespace's `create` to be
+                // dropped from the spec. Bare key only when the namespace is unknown.
+                result.add(namespaceName ? `${namespaceName}.${prop.name.text}` : prop.name.text);
             }
         }
     }
@@ -61,23 +64,24 @@ export function extractSkipCodegenMethods(sourcePath) {
             const callee = node.expression;
             if (ts.isIdentifier(callee) && callee.text === 'ApiNamespace' && node.arguments && node.arguments.length >= 2) {
                 const handler = node.arguments[node.arguments.length - 1];
+                const nsName = enclosingBindingName(node);
                 if (ts.isArrowFunction(handler) || ts.isFunctionExpression(handler)) {
                     const body = handler.body;
                     if (ts.isParenthesizedExpression(body) && ts.isObjectLiteralExpression(body.expression)) {
-                        visitObjectLiteral(body.expression);
+                        visitObjectLiteral(body.expression, nsName);
                     }
                     else if (ts.isObjectLiteralExpression(body)) {
-                        visitObjectLiteral(body);
+                        visitObjectLiteral(body, nsName);
                     }
                     else if (ts.isBlock(body)) {
                         for (const stmt of body.statements) {
                             if (ts.isReturnStatement(stmt) && stmt.expression) {
                                 if (ts.isObjectLiteralExpression(stmt.expression)) {
-                                    visitObjectLiteral(stmt.expression);
+                                    visitObjectLiteral(stmt.expression, nsName);
                                 }
                                 else if (ts.isParenthesizedExpression(stmt.expression) &&
                                     ts.isObjectLiteralExpression(stmt.expression.expression)) {
-                                    visitObjectLiteral(stmt.expression.expression);
+                                    visitObjectLiteral(stmt.expression.expression, nsName);
                                 }
                             }
                         }
@@ -135,7 +139,7 @@ export function extractMethodTypes(sourcePath) {
             const fnName = node.expression;
             if (ts.isIdentifier(fnName) && fnName.text === 'ApiNamespace' && node.arguments && node.arguments.length >= 2) {
                 const handlerArg = node.arguments[node.arguments.length - 1];
-                extractMethodsFromHandler(handlerArg, checker, sourceFile, result);
+                extractMethodsFromHandler(handlerArg, checker, sourceFile, result, enclosingBindingName(node));
             }
         }
         ts.forEachChild(node, visit);
@@ -148,19 +152,67 @@ export function extractMethodTypes(sourcePath) {
         if (!ts.isVariableStatement(node))
             return;
         for (const decl of node.declarationList.declarations) {
-            if (!decl.initializer || !ts.isIdentifier(decl.name))
+            if (!decl.initializer)
+                continue;
+            // (a) Simple binding: `const api = auth.createApi()` /
+            //     `export const api = backend.namespace`.
+            if (ts.isIdentifier(decl.name)) {
+                // Skip if we already extracted methods for this via the AST walk
+                if (ts.isNewExpression(decl.initializer)) {
+                    const callee = decl.initializer.expression;
+                    if (ts.isIdentifier(callee) && callee.text === 'ApiNamespace')
+                        continue;
+                }
+                // Use the type checker to get the type of the initializer expression.
+                // For `auth.createApi()`, this resolves through the method's return type
+                // to the `AsyncAPI<T>` type that ApiNamespace returns.
+                const initType = checker.getTypeAtLocation(decl.initializer);
+                extractMethodsFromResolvedType(initType, checker, result, decl.name.text);
                 continue;
-            // Skip if we already extracted methods for this via the AST walk
-            if (ts.isNewExpression(decl.initializer)) {
-                const callee = decl.initializer.expression;
-                if (ts.isIdentifier(callee) && callee.text === 'ApiNamespace')
-                    continue;
             }
-            // Use the type checker to get the type of the initializer expression.
-            // For `auth.createApi()`, this resolves through the method's return type
-            // to the `AsyncAPI<T>` type that ApiNamespace returns.
-            const initType = checker.getTypeAtLocation(decl.initializer);
-            extractMethodsFromResolvedType(initType, checker, result);
+            // (b) Object binding pattern: `const { indirectNamespace } = factory()`.
+            // Each destructured binding is a separate namespace whose name is the
+            // LOCAL binding name (the name it's exported under). Resolve the property
+            // type off the initializer and extract methods keyed by that name, so a
+            // factory-returned namespace keys qualified (`indirectNamespace.method`)
+            // like a directly-constructed one — instead of landing on a bare key that
+            // collides with same-named methods in other namespaces (#444, #445).
+            //
+            // This adds the qualified key ALONGSIDE the bare key the first-pass AST
+            // walk already emitted for the same `new ApiNamespace(...)` (its
+            // `enclosingBindingName` returns undefined behind the factory, so it keys
+            // bare). Leaving the bare key is harmless: `generate-spec` looks up
+            // `tsTypes.get(qualified) ?? tsTypes.get(bare)`, so the qualified key
+            // added here always wins for an attributable namespace, and the bare
+            // entry never influences the emitted schema (a regression test asserts
+            // this under a name collision). The #498 bare-name fallback is retained
+            // on purpose — it's the last resort for namespaces this pass still can't
+            // attribute (default exports, deeper indirection, the patterns below), so
+            // it is NOT redundant.
+            //
+            // Boundary: only a top-level identifier (a) and a shallow object binding
+            // pattern (b) are attributed. Array patterns (`const [ns] = factory()`)
+            // and nested patterns (`const { a: { b } } = …`) fall through to the
+            // bare-key path, where the #498 fallback still resolves the schema when
+            // there's no collision. These shapes are rare for namespace exports and
+            // fail soft; widening the traversal can come later if a real case appears.
+            if (ts.isObjectBindingPattern(decl.name)) {
+                const initType = checker.getTypeAtLocation(decl.initializer);
+                for (const element of decl.name.elements) {
+                    if (!ts.isIdentifier(element.name))
+                        continue;
+                    const localName = element.name.text;
+                    // `const { foo: bar } = …` binds `bar` but reads property `foo`.
+                    const propKey = element.propertyName && ts.isIdentifier(element.propertyName)
+                        ? element.propertyName.text
+                        : localName;
+                    const propSymbol = initType.getProperty(propKey);
+                    if (!propSymbol)
+                        continue;
+                    const propType = checker.getTypeOfSymbol(propSymbol);
+                    extractMethodsFromResolvedType(propType, checker, result, localName);
+                }
+            }
         }
     });
     return result;
@@ -180,7 +232,7 @@ function findTsConfig(dir) {
     return undefined;
 }
 // ── Handler extraction ──────────────────────────────────────────────────────
-function extractMethodsFromHandler(handlerNode, checker, sourceFile, result) {
+function extractMethodsFromHandler(handlerNode, checker, sourceFile, result, namespaceName) {
     let objectLiteral;
     if (ts.isArrowFunction(handlerNode) || ts.isFunctionExpression(handlerNode)) {
         const body = handlerNode.body;
@@ -212,11 +264,42 @@ function extractMethodsFromHandler(handlerNode, checker, sourceFile, result) {
         if (ts.isMethodDeclaration(prop) && prop.name && ts.isIdentifier(prop.name)) {
             const methodName = prop.name.text;
             const info = extractMethodTypeInfo(prop, checker, sourceFile);
+            // Key by the namespace-qualified name when the namespace is known, so two
+            // namespaces sharing a method name (e.g. widgets.create / subscriptions.create)
+            // don't collide and cross-assign schemas. Fall back to the bare name when the
+            // namespace can't be determined (consumers try qualified, then bare).
             if (info)
-                result.set(methodName, info);
+                result.set(namespaceName ? `${namespaceName}.${methodName}` : methodName, info);
         }
     }
 }
+/**
+ * Walk up from a `new ApiNamespace(...)` node to the name it's bound to
+ * (`export const widgets = new ApiNamespace(...)` → `"widgets"`). This is the
+ * name the dev server / Lambda handler route by, and the one `generate-spec`
+ * uses to qualify method names. Returns `undefined` when the namespace is
+ * created behind indirection (factory return, etc.), in which case methods key
+ * by their bare name.
+ *
+ * Limitation: this is the local binding name, not the export name. An export
+ * rename — `const widgets = new ApiNamespace(...); export { widgets as gadgets }`
+ * — keys `widgets.*` while `generate-spec` looks up `gadgets.*`, so the qualified
+ * lookup misses and falls back to the bare key (schemas resolve if there's no
+ * collision, else `unknown`). Rare; resolving the export alias would remove it.
+ */
+function enclosingBindingName(node) {
+    let current = node.parent;
+    while (current) {
+        if (ts.isVariableDeclaration(current) && ts.isIdentifier(current.name))
+            return current.name.text;
+        // Don't cross a function/block boundary — beyond it the binding no longer
+        // corresponds to a directly-exported namespace.
+        if (ts.isSourceFile(current) || ts.isBlock(current) || ts.isFunctionLike(current))
+            return undefined;
+        current = current.parent;
+    }
+    return undefined;
+}
 function extractMethodTypeInfo(method, checker, sourceFile) {
     const params = [];
     for (const param of method.parameters) {
@@ -284,7 +367,7 @@ function unwrapPromiseTypeNode(node) {
  * We also handle the case where the type is callable (the raw handler function
  * before `AsyncAPI` wrapping) — we call-resolve it and inspect the result.
  */
-function extractMethodsFromResolvedType(type, checker, result) {
+function extractMethodsFromResolvedType(type, checker, result, namespaceName) {
     // The runtime value of an ApiNamespace export is the handler function itself
     // (with the marker symbol attached). Its TS type is `AsyncAPI<T>`, which is
     // an object type with method-like properties. But it could also be typed as
@@ -309,8 +392,9 @@ function extractMethodsFromResolvedType(type, checker, result) {
         // Skip internal symbols and the marker
         if (propName.startsWith('_') || propName === 'Symbol(blocks:ApiNamespace)')
             continue;
+        const key = namespaceName ? `${namespaceName}.${propName}` : propName;
         // Don't overwrite methods already found by the AST walk
-        if (result.has(propName))
+        if (result.has(key))
             continue;
         const propType = checker.getTypeOfSymbol(prop);
         const methodSigs = propType.getCallSignatures();
@@ -346,7 +430,7 @@ function extractMethodsFromResolvedType(type, checker, result) {
         if (declaration && hasBlocksSkipCodegenTag(declaration)) {
             skipCodegen = true;
         }
-        result.set(propName, { params, returnType, transferable, skipCodegen });
+        result.set(key, { params, returnType, transferable, skipCodegen });
     }
 }
 // ── Transferable detection ───────────────────────────────────────────────────