testing: event-pump tests on stub HttpClient + TestClock (comms-e5vm.2)

Tier-2 proof: migrate the event-pump / long-poll LOGIC tests off the real
Bun.serve realm onto the owned-fake stub HttpClient driven by TestClock,
exercised through the full adapter stack. Deterministic, no socket.

- Extend the stub seam with a hang ({ hang: true }) response variant that
  parks on Effect.never. An instant in-memory stub has no long-poll *hold*,
  so an eager Stream.runDrain would burn through the whole response sequence
  in a hot loop; the hang models the hold (and stops one iterator racing
  ahead into another's BAD_EVENT_QUEUE_ID). The downstream Tier-2 migrations
  (.3/.7/.8) drive the same stack and get it from the shared seam.

- New packages/zulip/adapter-events.test.ts on stub + TestClock via
  effectTest: gap-replay watermark across iterator instances (comms-4au),
  429 RATE_LIMIT_HIT recovery on /events and /register (comms-9wi),
  BAD_EVENT_QUEUE_ID reconnect + inbox.replay() gap-backfill (comms-jnn),
  cursor/heartbeat advancement, and the scope-close fiber-interrupt (spj3.8).

- Delete the migrated tests and the happy-path live-contract duplicates
  (first .next, mention-received) from adapter.test.ts. The rest of
  adapter.test.ts stays on the realm for comms-e5vm.3.

Dissolves the real-socket contention flake structurally: the hanging
long-poll tests leave the realm-bound file, so comms-hbm9 auto-resolves.

Tier-3 residue for comms-4lz5: the genuine AbortSignal -> fetch -> TCP
teardown of an in-flight FetchHttpClient long-poll on scope close stays one
real-socket test; the stub only proves the Effect fiber-interrupt logic.

Author: GraemeF

packages/testing/stub-http-client.test.ts

@@ -1,6 +1,6 @@
 import { expect, test } from 'bun:test'
 import { HttpClient, HttpClientRequest } from '@effect/platform'
-import { Effect } from 'effect'
+import { Duration, Effect, Fiber, Option } from 'effect'
 import { makeStubHttpClient } from './stub-http-client.ts'
 
 const REALM = 'https://zulip.example.com/api/v1'
@@ -202,6 +202,29 @@ test('opens no socket — a request to an unroutable host still resolves', () =>
     }),
   ))
 
+test('a hang response captures the request, then never resolves and stays interruptible', () =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      const stub = yield* makeStubHttpClient
+      // The long-poll hold: the stub answers instantly for everything else, so
+      // a terminal hang is what stops an eager consumer draining the sequence.
+      yield* stub.respondSequence('GET', '/api/v1/events', [{ hang: true }])
+      const fiber = yield* Effect.fork(
+        stub.client.execute(HttpClientRequest.get(`${REALM}/events`)),
+      )
+      // Let the forked request issue and park on the hang.
+      yield* Effect.sleep(Duration.millis(10))
+      const captured = yield* stub.captured
+      expect(captured).toHaveLength(1)
+      expect(captured[0]?.url.pathname).toBe('/api/v1/events')
+      // Still parked — a hang resolves to no Exit.
+      expect(Option.isNone(yield* fiber.poll)).toBe(true)
+      // Interrupting unwinds it cleanly (the scope-close path).
+      const exit = yield* Fiber.interrupt(fiber)
+      expect(exit._tag).toBe('Failure')
+    }),
+  ))
+
 test('is a drop-in for the HttpClient.HttpClient service', () =>
   Effect.runPromise(
     Effect.gen(function* () {

packages/testing/stub-http-client.ts

@@ -23,9 +23,22 @@ import {
   type HttpClientRequest,
   HttpClientResponse,
 } from '@effect/platform'
-import { Data, Effect, HashMap, Option, Ref } from 'effect'
+import { Data, Effect, HashMap, Option, Predicate, Ref } from 'effect'
 
-export type StubResponse = {
+/**
+ * A response that never resolves — the request is captured, then the effect
+ * parks on `Effect.never`. Models the real Zulip long-poll *holding* the
+ * connection open: an in-memory stub answers instantly, so without a hold an
+ * eager consumer (the event-pump's `Stream.runDrain`) would burn through the
+ * whole response sequence in a hot loop. A fiber blocked on a hang is
+ * *interrupted* (not errored) when its scope closes — which is exactly the
+ * scope-close-interrupt path the event-pump tests exercise.
+ */
+export type StubHang = {
+  readonly hang: true
+}
+
+export type StubBody = {
   /** Object → JSON-encoded; string → verbatim; `Uint8Array` → raw bytes. */
   readonly body: unknown
   /** HTTP status; defaults to 200. */
@@ -34,6 +47,8 @@ export type StubResponse = {
   readonly headers?: Readonly<Record<string, string>>
 }
 
+export type StubResponse = StubBody | StubHang
+
 export type CapturedHttpRequest = {
   readonly method: string
   readonly url: URL
@@ -87,19 +102,19 @@ const requestBodyInit = (body: HttpBody.HttpBody): string | Uint8Array | FormDat
   }
 }
 
-const responseBodyInit = (response: StubResponse): string | Uint8Array => {
+const responseBodyInit = (response: StubBody): string | Uint8Array => {
   if (response.body instanceof Uint8Array) return response.body
   if (typeof response.body === 'string') return response.body
   return JSON.stringify(response.body)
 }
 
-const responseHeaders = (response: StubResponse): Record<string, string> => {
+const responseHeaders = (response: StubBody): Record<string, string> => {
   const base: Record<string, string> =
     response.body instanceof Uint8Array ? {} : { 'content-type': 'application/json' }
   return { ...base, ...response.headers }
 }
 
-const notFound = (method: string, path: string): StubResponse => ({
+const notFound = (method: string, path: string): StubBody => ({
   body: { result: 'error', code: 'NO_STUB_HANDLER', msg: `no stub handler for ${method} ${path}` },
   status: 404,
 })
@@ -155,14 +170,18 @@ export const makeStubHttpClient: Effect.Effect<StubHttpClient> = Effect.gen(func
   const client = HttpClient.make((request, url) =>
     capture(request, url).pipe(
       Effect.zipRight(nextResponse(request.method, url.pathname)),
-      Effect.map((response) =>
-        HttpClientResponse.fromWeb(
-          request,
-          new Response(responseBodyInit(response), {
-            status: response.status ?? 200,
-            headers: responseHeaders(response),
-          }),
-        ),
+      Effect.flatMap((response) =>
+        Predicate.hasProperty(response, 'hang')
+          ? Effect.never
+          : Effect.succeed(
+              HttpClientResponse.fromWeb(
+                request,
+                new Response(responseBodyInit(response), {
+                  status: response.status ?? 200,
+                  headers: responseHeaders(response),
+                }),
+              ),
+            ),
       ),
     ),
   )