fix: eliminate Promise.race handler-stacking in batchPackageStream (#600)

* fix: eliminate Promise.race handler-stacking in batchPackageStream

The prior implementation stored per-generator promises in a Map and
called `Promise.race(running.values())` every loop iteration. Each
race call re-attached fresh `.then` handlers to every still-pending
promise in the pool, so long-surviving generators accumulated
O(iterations) dead handler closures before finally settling.

See nodejs/node#17469 and
https://github.com/cefn/watchable/tree/main/packages/unpromise for
the pattern.

Switch to a single-waiter queue: each generator's `.then` delivers
its step into a buffer, and the main loop awaits a fresh
promiseWithResolvers each iteration. Handlers are one-shot —
nothing to stack.

All 565 tests pass.

* docs(claude): add Promise.race handler-stacking rule

Pairs with the batchPackageStream fix: documents the anti-pattern
so future code does not reintroduce it. Concise bullet in the
SHARED STANDARDS section alongside the existsSync rule.

* docs(claude): drop duplicate Promise.race rule from TypeScript Patterns

The rule already lives in SHARED STANDARDS (line 26). Having it twice
— once general, once under sdk-specific TypeScript Patterns — adds
maintenance drift without adding clarity. Keep the SHARED STANDARDS
version.

* style(sdk): alphabetize destructuring and prefer undefined in batchPackageStream

Align the single-waiter queue with project rules: alphabetical
destructuring/type property order and undefined (not null) for
absent state.

Author: jdalton

CLAUDE.md

@@ -16,6 +16,7 @@
 - 🚨 **NEVER use `npx`, `pnpm dlx`, or `yarn dlx`** — use `pnpm exec <package>` or `pnpm run <script>`. Add tools as pinned devDependencies first.
 - **minimumReleaseAge**: NEVER add packages to `minimumReleaseAgeExclude` in CI. Locally, ASK before adding — the age threshold is a security control.
 - File existence: ALWAYS `existsSync` from `node:fs`. NEVER `fs.access`, `fs.stat`-for-existence, or an async `fileExists` wrapper. Import form: `import { existsSync, promises as fs } from 'node:fs'`.
+- `Promise.race` / `Promise.any`: NEVER pass a long-lived promise (interrupt signal, pool member) into a race inside a loop. Each call re-attaches `.then` handlers to every arm; handlers accumulate on surviving promises until they settle. For concurrency limiters, use a single-waiter "slot available" signal (resolved by each task's `.then`) instead of re-racing `executing[]`. See nodejs/node#17469 and `@watchable/unpromise`. Race with two fresh arms (e.g. one-shot `withTimeout`) is safe.
 
 ---
 

src/socket-sdk-class.ts

@@ -867,10 +867,52 @@ export class SocketSdk {
     /* c8 ignore stop */
     const { components } = componentsObj
     const { length: componentsCount } = components
-    const running = new Map<
-      AsyncGenerator<BatchPackageFetchResultType>,
-      Promise<GeneratorStep>
-    >()
+    // Tracks in-flight generators only for pool-size accounting.
+    // Completed steps and errors flow through the single-waiter queue below,
+    // not through per-generator promises re-raced each iteration — repeated
+    // Promise.race() over the same pool accumulates unreleased .then
+    // handlers on each still-pending arm until the pool drains.
+    // See https://github.com/nodejs/node/issues/17469.
+    const running = new Set<AsyncGenerator<BatchPackageFetchResultType>>()
+    const completed: GeneratorStep[] = []
+    let waiter:
+      | {
+          reject: (err: unknown) => void
+          resolve: (step: GeneratorStep) => void
+        }
+      | undefined
+    let pendingError: { err: unknown } | undefined
+    const deliverStep = (step: GeneratorStep) => {
+      if (waiter) {
+        const w = waiter
+        waiter = undefined
+        w.resolve(step)
+      } else {
+        completed.push(step)
+      }
+    }
+    const deliverError = (err: unknown) => {
+      if (waiter) {
+        const w = waiter
+        waiter = undefined
+        w.reject(err)
+      } else if (!pendingError) {
+        pendingError = { err }
+      }
+    }
+    const takeStep = (): Promise<GeneratorStep> => {
+      if (pendingError) {
+        const { err } = pendingError
+        pendingError = undefined
+        return Promise.reject(err)
+      }
+      if (completed.length) {
+        return Promise.resolve(completed.shift()!)
+      }
+      const { promise, reject, resolve } = promiseWithResolvers<GeneratorStep>()
+      waiter = { reject, resolve }
+      return promise
+    }
     let index = 0
     const enqueueGen = () => {
       if (index >= componentsCount) {
@@ -888,17 +930,12 @@ export class SocketSdk {
     const continueGen = (
       generator: AsyncGenerator<BatchPackageFetchResultType>,
     ) => {
-      const {
-        promise,
-        reject: rejectFn,
-        resolve: resolveFn,
-      } = promiseWithResolvers<GeneratorStep>()
-      running.set(generator, promise)
+      running.add(generator)
       void generator
         .next()
         .then(
-          iteratorResult => resolveFn({ generator, iteratorResult }),
-          rejectFn,
+          iteratorResult => deliverStep({ generator, iteratorResult }),
+          deliverError,
         )
     }
     // Start initial batch of generators.
@@ -907,9 +944,7 @@ export class SocketSdk {
     }
     while (running.size > 0) {
       // eslint-disable-next-line no-await-in-loop
-      const { generator, iteratorResult }: GeneratorStep = await Promise.race(
-        running.values(),
-      )
+      const { generator, iteratorResult }: GeneratorStep = await takeStep()
       running.delete(generator)
       // Yield the value if one is given, even when done:true.
       if (iteratorResult.value) {