@cosmicdrift/kumiko-framework 0.305.0 → 0.307.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.305.0",
+  "version": "0.307.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.305.0",
-    "@cosmicdrift/kumiko-types": "0.305.0",
+    "@cosmicdrift/kumiko-http": "0.307.0",
+    "@cosmicdrift/kumiko-types": "0.307.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.305.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.307.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/redis-sse-broker.integration.test.ts

@@ -127,6 +127,72 @@ describe("createRedisSseBroker", () => {
     expect(invalidatedA).toBe(false);
   });
 
+  test("publishAccessInvalidation with a keptSessionId spares only the listener whose own sid matches exactly", async () => {
+    const podA = trackedBroker();
+    const podB = trackedBroker();
+    const userId = `user-${generateId()}`;
+    const sidKept = `sid-kept-${generateId()}`;
+    const sidAlreadyRevoked = `sid-already-revoked-${generateId()}`;
+    let invalidatedKept = false;
+    let invalidatedSidless = false;
+    let invalidatedAlreadyRevoked = false;
+
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedKept = true;
+      },
+      sidKept,
+    );
+    // No ownSid — mirrors a PAT/bearer stream, always invalidated (fail-closed).
+    podA.subscribeAccessInvalidation(userId, () => {
+      invalidatedSidless = true;
+    });
+    // Not the kept sid — mirrors a session already revoked through an
+    // eventless path (plain logout): the keep-list must still close it.
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedAlreadyRevoked = true;
+      },
+      sidAlreadyRevoked,
+    );
+
+    await waitFor(() => {
+      podB.publishAccessInvalidation(userId, sidKept);
+      return invalidatedSidless && invalidatedAlreadyRevoked;
+    });
+    // Asserted only after the control listeners above already fired for the
+    // same publish — proves the pipe delivered the message at all, so a
+    // false here means the sid really was spared, not that delivery is slow.
+    expect(invalidatedKept).toBe(false);
+  });
+
+  test("a legacy unscoped invalidation message (bare `1`, pre-scoping pod) still invalidates every listener, sid or not", async () => {
+    const podA = trackedBroker();
+    const publisherRaw = new (await import("ioredis")).default(testRedis.redisUrl);
+    const userId = `user-${generateId()}`;
+    let invalidatedWithSid = false;
+
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedWithSid = true;
+      },
+      `sid-${generateId()}`,
+    );
+
+    try {
+      await waitFor(async () => {
+        await publisherRaw.publish(`kumiko:sse:inval:${userId}`, JSON.stringify(1));
+        return invalidatedWithSid;
+      });
+      expect(invalidatedWithSid).toBe(true);
+    } finally {
+      publisherRaw.disconnect();
+    }
+  });
+
   test("a malformed message on the channel namespace is dropped, not thrown, and does not kill delivery", async () => {
     const podA = trackedBroker();
     const publisherRaw = new (await import("ioredis")).default(testRedis.redisUrl);

package/src/api/__tests__/server-boot-guards.test.ts

@@ -228,6 +228,7 @@ describe("buildServer — auth membershipQuery requires a principalStatus provid
     r.extendsRegistrar(EXT_PRINCIPAL_STATUS, {});
     r.useExtension(EXT_PRINCIPAL_STATUS, "has-principal-status", {
       resolveStatus: async () => "active" as const,
+      resolveProfile: async () => ({ globalRoles: [] }),
     });
   });
 

package/src/api/__tests__/server-error-logging.test.ts

@@ -66,6 +66,16 @@ const boomFeature = defineFeature("boom", (r) => {
     async () => ({ ok: true }),
     openToAll,
   );
+  // Same abort path TenantDb uses (signal.throwIfAborted()), without a DB.
+  r.queryHandler(
+    "abort-probe",
+    z.object({}),
+    async (_query, ctx) => {
+      ctx.signal?.throwIfAborted();
+      return { ok: true };
+    },
+    openToAll,
+  );
 });
 
 const { app, jwt } = buildServer({
@@ -178,6 +188,67 @@ describe("HTTP layer logs unexpected 5xx faults", () => {
     expect(status).toBe(404);
     expect(apiFaultLog(errors)).toBeUndefined();
   });
+
+  test("a pre-aborted client signal 499s and logs a warn, not '[api] handler failed'", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const warnings: unknown[][] = [];
+    const errors: unknown[][] = [];
+    const warnSpy = spyOn(console, "warn").mockImplementation((...args) => {
+      warnings.push(args);
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation((...args) => {
+      errors.push(args);
+    });
+    try {
+      const res = await app.request(
+        new Request("http://test.local/api/query", {
+          method: "POST",
+          headers: await auth(),
+          body: JSON.stringify({ type: "boom:query:abort-probe", payload: {} }),
+          signal: controller.signal,
+        }),
+      );
+      expect(res.status).toBe(499);
+      expect(apiFaultLog(errors)).toBeUndefined();
+      const hit = warnings.find(
+        (args) =>
+          typeof args[0] === "string" && args[0].includes("[api] request aborted by client"),
+      );
+      expect(hit).toBeDefined();
+      const data = hit?.[1];
+      expect(isRecord(data)).toBe(true);
+      if (!isRecord(data)) return;
+      expect(data["status"]).toBe(499);
+      expect(data["type"]).toBe("boom:query:abort-probe");
+    } finally {
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  test("a pre-aborted client signal still 500s + logs when the handler fails for an unrelated reason", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const calls: unknown[][] = [];
+    const spy = spyOn(console, "error").mockImplementation((...args) => {
+      calls.push(args);
+    });
+    try {
+      const res = await app.request(
+        new Request("http://test.local/api/query", {
+          method: "POST",
+          headers: await auth(),
+          body: JSON.stringify({ type: "boom:query:explode", payload: {} }),
+          signal: controller.signal,
+        }),
+      );
+      expect(res.status).toBe(500);
+      expect(apiFaultLog(calls)).toBeDefined();
+    } finally {
+      spy.mockRestore();
+    }
+  });
 });
 
 describe("HTTP layer logs 4xx client faults on warn (#3077)", () => {

package/src/api/__tests__/sse-broker.test.ts

@@ -121,4 +121,53 @@ describe("SSE broker", () => {
     const { publish } = requireAccessInvalidation(createSseBroker());
     expect(() => publish("nobody-listening")).not.toThrow();
   });
+
+  test("publishAccessInvalidation with a keptSessionId spares only the listener whose own sid matches exactly", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const spared = mock();
+    const unrelated = mock();
+
+    subscribe("user-a", spared, "sid-kept");
+    subscribe("user-a", unrelated, "sid-other");
+    publish("user-a", "sid-kept");
+
+    expect(spared).not.toHaveBeenCalled();
+    expect(unrelated).toHaveBeenCalledTimes(1);
+  });
+
+  test("publishAccessInvalidation with a keptSessionId still closes a listener whose sid was already revoked through an eventless path (keep-list, not a kill-list)", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const alreadyRevoked = mock();
+
+    // Simulates a stream from a session logged out earlier via a path that
+    // never appended session-revoked — the keep-list must not accidentally
+    // exempt it just because its sid isn't the freshly-kept one.
+    subscribe("user-a", alreadyRevoked, "sid-logged-out-earlier");
+    publish("user-a", "sid-kept");
+
+    expect(alreadyRevoked).toHaveBeenCalledTimes(1);
+  });
+
+  test("publishAccessInvalidation with a keptSessionId still fires a listener with no sid of its own (fail-closed, e.g. a PAT/bearer stream)", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const sidless = mock();
+
+    subscribe("user-a", sidless);
+    publish("user-a", "sid-kept");
+
+    expect(sidless).toHaveBeenCalledTimes(1);
+  });
+
+  test("publishAccessInvalidation with no keptSessionId (unscoped) still invalidates every listener, matching pre-scoping behavior", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const first = mock();
+    const second = mock();
+
+    subscribe("user-a", first, "sid-1");
+    subscribe("user-a", second, "sid-2");
+    publish("user-a");
+
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+  });
 });

package/src/api/redis-sse-broker.ts

@@ -60,6 +60,17 @@ function isSseEvent(value: unknown): value is SseEvent {
   );
 }
 
+// Invalidation payload: `1` means userwide, `{ keptSessionId }` spares that one
+// session. Anything else falls back to userwide. Older pods never read the
+// payload and invalidate userwide, which keeps a mixed rolling deploy safe.
+function extractInvalidationKeptSessionId(payload: unknown): string | undefined {
+  if (typeof payload !== "object" || payload === null || !("keptSessionId" in payload)) {
+    return undefined;
+  }
+  const { keptSessionId } = payload;
+  return typeof keptSessionId === "string" && keptSessionId.length > 0 ? keptSessionId : undefined;
+}
+
 // Transport layer around a local `createSseBroker()` — all client/listener
 // state lives in `inner`, this only moves events across the Redis wire via
 // the shared PubSubSignal. `pushToChannel`/`publishAccessInvalidation` never
@@ -89,7 +100,10 @@ export function createRedisSseBroker(opts: RedisSseBrokerOptions): RedisSseBroke
     }
 
     if (channel.startsWith(INVALIDATION_PREFIX)) {
-      inner.publishAccessInvalidation(channel.slice(INVALIDATION_PREFIX.length));
+      inner.publishAccessInvalidation(
+        channel.slice(INVALIDATION_PREFIX.length),
+        extractInvalidationKeptSessionId(payload),
+      );
     }
   });
 
@@ -108,8 +122,8 @@ export function createRedisSseBroker(opts: RedisSseBrokerOptions): RedisSseBroke
     // stream must close on every replica, not just the one that observed
     // the revocation event. Publishing (rather than calling inner directly,
     // like the in-memory broker does) is what makes that true here.
-    publishAccessInvalidation(userId) {
-      signal.publish(`${INVALIDATION_PREFIX}${userId}`, 1);
+    publishAccessInvalidation(userId, keptSessionId) {
+      signal.publish(`${INVALIDATION_PREFIX}${userId}`, keptSessionId ? { keptSessionId } : 1);
     },
 
     close: signal.close,

package/src/api/request-context.ts

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { isPersonalDataGated, type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
 import { generateId } from "../utils";
 
 // Request-scoped propagation. Populated by the HTTP middleware and by the
@@ -17,10 +18,11 @@ import { generateId } from "../utils";
 //                   with correlationId, forms a causal DAG across streams.
 //   signal        — AbortSignal from the underlying HTTP request. Aborts
 //                   when the client disconnects (mobile back-press, tab
-//                   close). Long-running framework code (event streaming,
-//                   projection rebuild) checks signal.aborted at chunk
-//                   boundaries; short queries don't pay the overhead.
-//                   Undefined for non-HTTP entry-points (jobs, MSP-applies).
+//                   close). Query/stream handlers check signal.aborted at
+//                   chunk or query boundaries; runBatch (write dispatch)
+//                   strips it before executing so a disconnect can't abort
+//                   a transaction mid-commit. Undefined for non-HTTP
+//                   entry-points (jobs, MSP-applies) and inside write batches.
 export type RequestContextData = {
   readonly requestId: string;
   readonly correlationId: string;
@@ -47,6 +49,9 @@ export type RequestContextData = {
   // performance.now() at request entry, so a failing request can report how
   // long it ran. Monotonic — a wall-clock step cannot make it negative.
   readonly startedAt?: number;
+  // Only ever a gated origin. Read by job enqueue and event-store.append();
+  // dispatch roots never narrow from it, only jobs inherit explicitly.
+  readonly writeOrigin?: WriteOrigin;
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();
@@ -86,3 +91,23 @@ export function runWithOrigin<T>(
     fn,
   );
 }
+
+// An ungated origin never mints a scope: seeds and boot writes keep their missing context.
+export function runWithWriteOrigin<T>(origin: WriteOrigin, fn: () => T): T {
+  const current = requestContext.get();
+  if (!isPersonalDataGated(origin)) {
+    if (!current?.writeOrigin) return fn();
+    const { writeOrigin: _writeOrigin, ...rest } = current;
+    return requestContext.run(rest, fn);
+  }
+  const requestId = current?.requestId ?? requestContext.generateId();
+  return requestContext.run(
+    {
+      ...current,
+      requestId,
+      correlationId: current?.correlationId ?? requestId,
+      writeOrigin: origin,
+    },
+    fn,
+  );
+}

package/src/api/routes.ts

@@ -29,6 +29,10 @@ export const StreamFrame = {
   error: "error",
 } as const;
 
+// Non-standard but widely used for "client hung up" — distinct from a real
+// 5xx so a disconnect never gets logged as a server fault.
+const CLIENT_CLOSED_REQUEST_STATUS = 499;
+
 export type ApiRoutesOptions = {
   // Override the SSE heartbeat interval (ms). Default SSE_HEARTBEAT_INTERVAL_MS.
   // Deployment-tunable for proxies with different idle timeouts — also used
@@ -203,7 +207,7 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
       // in-flight .next(), so awaiting here would block the response until
       // that pending pull resolves (which may be never for an idle stream).
       void generator.return(undefined).catch(() => {});
-      return c.body(null, 499 as ContentfulStatusCode); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
+      return c.body(null, CLIENT_CLOSED_REQUEST_STATUS as ContentfulStatusCode); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
     }
 
     return streamSSE(c, async (stream) => {
@@ -364,6 +368,13 @@ function logClientFault(err: KumikoError, requestId: string | undefined, type?:
   });
 }
 
+// Identity-checked against THIS request's signal — signal.aborted alone
+// would also match a real 5xx that happens to race a disconnect.
+function isClientAbort(err: KumikoError): boolean {
+  const signal = requestContext.get()?.signal;
+  return signal?.aborted === true && err.cause !== undefined && err.cause === signal.reason;
+}
+
 // Unexpected server faults (5xx) carry their diagnostic stack only on the
 // in-process error — serializeError strips cause/details from the wire body.
 // Without this a wrapped throw (InternalError{cause}) returns a 500 with zero
@@ -401,6 +412,20 @@ function writeErrorResponse(c: Context, err: KumikoError, type?: string) {
 // keep the same lean shape on failure — only the `error` key.
 function queryErrorResponse(c: Context, err: KumikoError, type?: string) {
   const requestId = requestContext.get()?.requestId;
+  if (isClientAbort(err)) {
+    if (clientFaultLoggingEnabled()) {
+      const startedAt = requestContext.get()?.startedAt;
+      createFallbackLogger("api").warn("request aborted by client", {
+        requestId,
+        type: type?.slice(0, MAX_LOGGED_TYPE_LENGTH),
+        status: CLIENT_CLOSED_REQUEST_STATUS,
+        ...(startedAt === undefined
+          ? {}
+          : { durationMs: Math.round(performance.now() - startedAt) }),
+      });
+    }
+    return c.body(null, CLIENT_CLOSED_REQUEST_STATUS as ContentfulStatusCode); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
+  }
   logServerFault(err, requestId, type);
   const body = serializeError(err, requestId);
   return c.json(body, err.httpStatus as ContentfulStatusCode); // @cast-boundary engine-payload

package/src/api/sse-broker.ts

@@ -24,21 +24,38 @@ export type SseBroker = {
   // access-teardown security control (#1561) into a no-op — a revoked
   // session keeps receiving live SSE data with no error or log. A no-op
   // stub is one line for a broker that genuinely doesn't need it.
-  subscribeAccessInvalidation(userId: string, onInvalidate: () => void): () => void;
-  publishAccessInvalidation(userId: string): void;
+  subscribeAccessInvalidation(
+    userId: string,
+    onInvalidate: () => void,
+    ownSid?: string,
+  ): () => void;
+  // `keptSessionId` spares exactly one stream: the caller's own session on a
+  // "revoke all others" write. It is a keep-list, not a list of revoked
+  // sessions, so a stream of a session already revoked without an event
+  // (plain logout) still closes. Every other reason stays userwide.
+  publishAccessInvalidation(userId: string, keptSessionId?: string): void;
 };
 
+// Fail-closed: without a kept sid, or for a listener without its own sid
+// (PAT/bearer), nothing is spared.
+function isSparedByKeptSessionId(
+  ownSid: string | undefined,
+  keptSessionId: string | undefined,
+): boolean {
+  return keptSessionId !== undefined && ownSid === keptSessionId;
+}
+
 export function createSseBroker(): SseBroker {
   // Purely local: no cross-replica fanout. buildServer wraps this in
   // createRedisSseBroker (fw#2625) whenever REDIS_URL is set, which is what
   // makes pushToChannel/publishAccessInvalidation reach every replica's
   // clients — this reference implementation stays single-process only.
   const channels = new Map<string, Map<string, SseClient>>();
-  // Set, not Map<listenerId, fn> — dedup key is callback reference. Every
-  // subscriber must pass a distinct closure (dispatch-stream.ts does, one
-  // per stream). Two subscribes with the SAME reference for the same user
+  // Keyed by callback reference, value is the subscriber's own sid. Every
+  // subscriber must pass a distinct closure (dispatch-stream.ts does, one per
+  // stream). Two subscribes with the SAME reference for the same user
   // collapse into one listener, and the first unsubscribe kills both.
-  const accessInvalidationListeners = new Map<string, Set<() => void>>();
+  const accessInvalidationListeners = new Map<string, Map<() => void, string | undefined>>();
 
   function getOrCreateChannel(channel: string): Map<string, SseClient> {
     let clients = channels.get(channel);
@@ -86,14 +103,14 @@ export function createSseBroker(): SseBroker {
       return total;
     },
 
-    subscribeAccessInvalidation(userId, onInvalidate) {
+    subscribeAccessInvalidation(userId, onInvalidate, ownSid) {
       const channel = userAccessChannel(userId);
       let listeners = accessInvalidationListeners.get(channel);
       if (!listeners) {
-        listeners = new Set();
+        listeners = new Map();
         accessInvalidationListeners.set(channel, listeners);
       }
-      listeners.add(onInvalidate);
+      listeners.set(onInvalidate, ownSid);
       return () => {
         const current = accessInvalidationListeners.get(channel);
         // skip: already unsubscribed (e.g. stream ended after a publish already fired)
@@ -103,14 +120,15 @@ export function createSseBroker(): SseBroker {
       };
     },
 
-    publishAccessInvalidation(userId) {
+    publishAccessInvalidation(userId, keptSessionId) {
       const channel = userAccessChannel(userId);
       const listeners = accessInvalidationListeners.get(channel);
       // skip: no live stream is watching this user right now
       if (!listeners) return;
       // Snapshot before iterating — a fired listener unsubscribes itself,
       // which would mutate `listeners` mid-iteration otherwise.
-      for (const onInvalidate of [...listeners]) {
+      for (const [onInvalidate, ownSid] of [...listeners]) {
+        if (isSparedByKeptSessionId(ownSid, keptSessionId)) continue;
         onInvalidate();
       }
     },

package/src/bun-db/__tests__/closed-connection-retry.integration.test.ts

@@ -0,0 +1,159 @@
+// Proves the closed-connection retry against a real postgres-js driver error,
+// plus the Bun.SQL matcher and both drivers' extractPgError — see query.ts.
+
+import { afterAll, describe, expect, test } from "bun:test";
+import postgres from "postgres";
+import { constraintOf, extractPgError, isUniqueViolation } from "../../db/pg-error";
+import { testDatabaseUrl } from "../../testing/closed-connection-error";
+import { waitFor } from "../../testing/wait-for";
+import { isClosedConnectionError, unsafeReadRetrying } from "../query";
+
+const DATABASE_URL = testDatabaseUrl();
+
+// Terminate targets only the backend running the slow query so the retry
+// lands on the pool's idle connection instead of reconnecting — a postgres-js
+// reconnect under Bun can hang until connect_timeout (30s).
+const adminClient = postgres(DATABASE_URL, { max: 1 });
+afterAll(async () => {
+  await adminClient.end({ timeout: 0 });
+});
+
+type UnsafeFn = (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+type Pool = { unsafe: UnsafeFn };
+
+// Counts unsafe() calls while forwarding everything (including begin/
+// savepoint/options) to the real handle — no mocked behavior, only counting.
+type CountingClient<T> = T & { readonly calls: number };
+function countingClient<T extends Pool>(real: T): CountingClient<T> {
+  let calls = 0;
+  return new Proxy(real, {
+    get(target, prop, receiver) {
+      if (prop === "calls") return calls;
+      if (prop === "unsafe") {
+        return async (...args: Parameters<UnsafeFn>) => {
+          calls++;
+          return target.unsafe(...args);
+        };
+      }
+      const value = Reflect.get(target, prop, receiver);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  }) as CountingClient<T>;
+}
+
+function randomAppName(): string {
+  return `kumiko-cc-retry-${crypto.randomUUID()}`;
+}
+
+// Waits for the slow query's backend to show up as the single active
+// session before terminating exactly that one — the pg_sleep(0.3) window
+// bounds this, so short fixed delays instead of waitFor's default backoff.
+async function pollForActivePid(applicationName: string, queryLike: string): Promise<number> {
+  let pid: number | undefined;
+  await waitFor(
+    async () => {
+      const rows = (await adminClient.unsafe(
+        "select pid from pg_stat_activity where application_name = $1 and state = 'active' and query like $2",
+        [applicationName, queryLike],
+      )) as readonly { pid: number }[];
+      if (rows.length === 1 && rows[0]?.pid !== undefined) {
+        pid = rows[0].pid;
+        return true;
+      }
+      return false;
+    },
+    { delays: Array(100).fill(10) },
+  );
+  if (pid === undefined) {
+    throw new Error(`pollForActivePid: no single active backend found for ${applicationName}`);
+  }
+  return pid;
+}
+
+async function terminateBackendPid(pid: number): Promise<void> {
+  await adminClient.unsafe("select pg_terminate_backend($1)", [pid]);
+}
+
+type DriverKind = "postgres-js" | "bun-sql";
+
+function makePool(kind: DriverKind, max: number, applicationName: string): Pool {
+  if (kind === "postgres-js") {
+    return postgres(DATABASE_URL, {
+      max,
+      connection: { application_name: applicationName },
+    }) as unknown as Pool;
+  }
+  return new Bun.SQL({
+    url: DATABASE_URL,
+    max,
+    connection: { application_name: applicationName },
+  }) as unknown as Pool;
+}
+
+async function closePool(kind: DriverKind, pool: unknown): Promise<void> {
+  if (kind === "postgres-js") {
+    await (pool as { end: (opts?: { timeout?: number }) => Promise<void> }).end({ timeout: 0 });
+  } else {
+    await (pool as { close: () => Promise<void> }).close();
+  }
+}
+
+const drivers: DriverKind[] = ["postgres-js", "bun-sql"];
+
+// postgres-js only: Bun.SQL sporadically emits an unhandled reject from its
+// internal handleClose in this terminate window, and isn't the prod driver.
+// Multi-retry (≥3 calls) is covered deterministically by the fake-client
+// test in select-many-retry.integration.test.ts instead of a second live test.
+test("retries through a real server-side connection close", async () => {
+  const applicationName = randomAppName();
+  const pool = postgres(DATABASE_URL, {
+    max: 2,
+    connection: { application_name: applicationName },
+  });
+  try {
+    await Promise.all([pool.unsafe("select 1"), pool.unsafe("select 1")]);
+    const counted = countingClient(pool as unknown as Pool);
+    const pending = unsafeReadRetrying(counted as never, "select 1 as x from pg_sleep(0.3)", []);
+    const pid = await pollForActivePid(applicationName, "%pg_sleep(0.3)%");
+    await terminateBackendPid(pid);
+    const rows = await pending;
+    expect([...rows]).toEqual([{ x: 1 }]);
+    expect(counted.calls).toBe(2);
+  } finally {
+    await pool.end({ timeout: 0 });
+  }
+});
+
+test("Bun.SQL closed-connection error matches isClosedConnectionError", async () => {
+  const pool = new Bun.SQL({ url: DATABASE_URL, max: 1 });
+  await pool.unsafe("select 1");
+  await pool.close();
+  const caught = await pool.unsafe("select 1").catch((e: unknown) => e);
+  // @cast-boundary error-details — asserting the real driver error shape
+  expect((caught as { code?: string }).code).toBe("ERR_POSTGRES_CONNECTION_CLOSED");
+  expect(isClosedConnectionError(caught)).toBe(true);
+});
+
+describe.each(drivers)("extractPgError — %s unique-violation SQLSTATE", (kind) => {
+  test("isUniqueViolation and constraintOf resolve the real driver error", async () => {
+    const applicationName = randomAppName();
+    const pool = makePool(kind, 1, applicationName);
+    const tableName = `cc_retry_uniq_${crypto.randomUUID().replace(/-/g, "").slice(0, 12)}`;
+    await pool.unsafe(
+      `create table "${tableName}" (id uuid not null, constraint "${tableName}_pk" primary key (id))`,
+    );
+    try {
+      const fixedId = crypto.randomUUID();
+      await pool.unsafe(`insert into "${tableName}" (id) values ($1)`, [fixedId]);
+      const caught = await pool
+        .unsafe(`insert into "${tableName}" (id) values ($1)`, [fixedId])
+        .catch((e: unknown) => e);
+      expect(isUniqueViolation(caught)).toBe(true);
+      expect(extractPgError(caught)?.code).toBe("23505");
+      expect(constraintOf(caught)).toBeDefined();
+    } finally {
+      await pool.unsafe(`drop table if exists "${tableName}"`);
+      await closePool(kind, pool);
+    }
+  });
+});