From 5a82c7530dbd91689ed05e9c362d308aef9611a9 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Sun, 19 Apr 2026 12:20:54 -0400
Subject: [PATCH 1/4] fix: eliminate Promise.race handler-stacking in
 batchPackageStream
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 https://github.com/nodejs/node/issues/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.
---
 src/socket-sdk-class.ts | 63 +++++++++++++++++++++++++++++++----------
 1 file changed, 48 insertions(+), 15 deletions(-)

diff --git a/src/socket-sdk-class.ts b/src/socket-sdk-class.ts
index 952bb94b..5248b313 100644
--- a/src/socket-sdk-class.ts
+++ b/src/socket-sdk-class.ts
@@ -867,10 +867,50 @@ 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: {
+      resolve: (step: GeneratorStep) => void
+      reject: (err: unknown) => void
+    } | null = null
+    let pendingError: { err: unknown } | null = null
+    const deliverStep = (step: GeneratorStep) => {
+      if (waiter) {
+        const w = waiter
+        waiter = null
+        w.resolve(step)
+      } else {
+        completed.push(step)
+      }
+    }
+    const deliverError = (err: unknown) => {
+      if (waiter) {
+        const w = waiter
+        waiter = null
+        w.reject(err)
+      } else if (!pendingError) {
+        pendingError = { err }
+      }
+    }
+    const takeStep = (): Promise<GeneratorStep> => {
+      if (pendingError) {
+        const { err } = pendingError
+        pendingError = null
+        return Promise.reject(err)
+      }
+      if (completed.length) {
+        return Promise.resolve(completed.shift()!)
+      }
+      const { promise, resolve, reject } = promiseWithResolvers<GeneratorStep>()
+      waiter = { resolve, reject }
+      return promise
+    }
     let index = 0
     const enqueueGen = () => {
       if (index >= componentsCount) {
@@ -888,17 +928,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 +942,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) {

From f9cd3ef98dfeed873689f78a56cb3aa6c2f2f7a5 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Sun, 19 Apr 2026 12:30:02 -0400
Subject: [PATCH 2/4] 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.
---
 CLAUDE.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1f748755..6cf1ac09 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -23,6 +23,7 @@
 - 🚨 **NEVER use `npx`, `pnpm dlx`, or `yarn dlx`** — use `pnpm exec <package>` for devDep binaries, or `pnpm run <script>` for package.json scripts. If a tool is needed, add it as a pinned devDependency 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.
 
 ---
 
@@ -162,6 +163,7 @@ All `logger.error()` and `logger.log()` calls include empty string:
 - **Type safety**: ❌ FORBIDDEN `any`; use `unknown` or specific
 - **Type imports**: Always `import type`
 - **Nullish values**: Prefer `undefined` over `null` - use `undefined` for absent/missing values
+- **Promise.race in loops**: ❌ NEVER re-race the same pool across iterations. Each race attaches fresh `.then` handlers to every arm; long-surviving promises accumulate handler sets ([nodejs/node#17469](https://github.com/nodejs/node/issues/17469)). Fresh-both-arms races (timeout wrappers) are fine. For concurrency limiters like `batchPackageStream`, use a single-waiter queue — each in-flight task's own `.then` delivers into a buffer, the loop awaits a one-shot `promiseWithResolvers` and replaces it per iteration.
 
 #### HTTP Requests
 

From 1b7d774126957c1842ae46ee7abbf58d1efe4be9 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Sun, 19 Apr 2026 12:32:56 -0400
Subject: [PATCH 3/4] docs(claude): drop duplicate Promise.race rule from
 TypeScript Patterns
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 CLAUDE.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6cf1ac09..b0788dba 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -163,7 +163,6 @@ All `logger.error()` and `logger.log()` calls include empty string:
 - **Type safety**: ❌ FORBIDDEN `any`; use `unknown` or specific
 - **Type imports**: Always `import type`
 - **Nullish values**: Prefer `undefined` over `null` - use `undefined` for absent/missing values
-- **Promise.race in loops**: ❌ NEVER re-race the same pool across iterations. Each race attaches fresh `.then` handlers to every arm; long-surviving promises accumulate handler sets ([nodejs/node#17469](https://github.com/nodejs/node/issues/17469)). Fresh-both-arms races (timeout wrappers) are fine. For concurrency limiters like `batchPackageStream`, use a single-waiter queue — each in-flight task's own `.then` delivers into a buffer, the loop awaits a one-shot `promiseWithResolvers` and replaces it per iteration.
 
 #### HTTP Requests
 

From ca2260cff6817a898ec5561a430faa1f54020669 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Mon, 20 Apr 2026 14:15:07 -0400
Subject: [PATCH 4/4] 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.
---
 src/socket-sdk-class.ts | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/src/socket-sdk-class.ts b/src/socket-sdk-class.ts
index 5248b313..50eb1dd6 100644
--- a/src/socket-sdk-class.ts
+++ b/src/socket-sdk-class.ts
@@ -875,15 +875,17 @@ export class SocketSdk {
     // See https://github.com/nodejs/node/issues/17469.
     const running = new Set<AsyncGenerator<BatchPackageFetchResultType>>()
     const completed: GeneratorStep[] = []
-    let waiter: {
-      resolve: (step: GeneratorStep) => void
-      reject: (err: unknown) => void
-    } | null = null
-    let pendingError: { err: unknown } | null = null
+    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 = null
+        waiter = undefined
         w.resolve(step)
       } else {
         completed.push(step)
@@ -892,7 +894,7 @@ export class SocketSdk {
     const deliverError = (err: unknown) => {
       if (waiter) {
         const w = waiter
-        waiter = null
+        waiter = undefined
         w.reject(err)
       } else if (!pendingError) {
         pendingError = { err }
@@ -901,14 +903,14 @@ export class SocketSdk {
     const takeStep = (): Promise<GeneratorStep> => {
       if (pendingError) {
         const { err } = pendingError
-        pendingError = null
+        pendingError = undefined
         return Promise.reject(err)
       }
       if (completed.length) {
         return Promise.resolve(completed.shift()!)
       }
-      const { promise, resolve, reject } = promiseWithResolvers<GeneratorStep>()
-      waiter = { resolve, reject }
+      const { promise, reject, resolve } = promiseWithResolvers<GeneratorStep>()
+      waiter = { reject, resolve }
       return promise
     }
     let index = 0