@cosmicdrift/kumiko-framework 0.304.0 → 0.306.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.304.0",
+  "version": "0.306.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.304.0",
-    "@cosmicdrift/kumiko-types": "0.304.0",
+    "@cosmicdrift/kumiko-http": "0.306.0",
+    "@cosmicdrift/kumiko-types": "0.306.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.304.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.306.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/extra-route-rejection.test.ts

@@ -0,0 +1,38 @@
+// Constructor invariants for ExtraRouteRejection's `retryAfterSeconds` option
+// (kumiko-framework#3168): it only makes sense together with 503 and must
+// render as a valid Retry-After delta-seconds header.
+
+import { describe, expect, test } from "bun:test";
+import { ExtraRouteRejection } from "../extra-route";
+
+describe("ExtraRouteRejection retryAfterSeconds invariants", () => {
+  test("retryAfterSeconds with a non-503 status throws RangeError", () => {
+    expect(
+      () => new ExtraRouteRejection(404, { error: "x" }, undefined, { retryAfterSeconds: 30 }),
+    ).toThrow(RangeError);
+  });
+
+  test("negative retryAfterSeconds throws RangeError", () => {
+    expect(
+      () => new ExtraRouteRejection(503, { error: "x" }, undefined, { retryAfterSeconds: -1 }),
+    ).toThrow(RangeError);
+  });
+
+  test("non-integer retryAfterSeconds throws RangeError", () => {
+    expect(
+      () => new ExtraRouteRejection(503, { error: "x" }, undefined, { retryAfterSeconds: 1.5 }),
+    ).toThrow(RangeError);
+  });
+
+  test("retryAfterSeconds: 0 with status 503 is accepted", () => {
+    const rejection = new ExtraRouteRejection(503, { error: "x" }, undefined, {
+      retryAfterSeconds: 0,
+    });
+    expect(rejection.retryAfterSeconds).toBe(0);
+  });
+
+  test("no options leaves retryAfterSeconds undefined", () => {
+    const rejection = new ExtraRouteRejection(503, { error: "x" });
+    expect(rejection.retryAfterSeconds).toBeUndefined();
+  });
+});

package/src/api/__tests__/extra-routes.integration.test.ts

@@ -461,6 +461,14 @@ describe("extraRoutes: entry:signature", () => {
       if (req.headers["x-force-404"] === "1") {
         throw new ExtraRouteRejection(404, { error: "unknown-provider" });
       }
+      if (req.headers["x-force-503"] === "retry") {
+        throw new ExtraRouteRejection(503, { error: "not-ready" }, undefined, {
+          retryAfterSeconds: 30,
+        });
+      }
+      if (req.headers["x-force-503"] === "plain") {
+        throw new ExtraRouteRejection(503, { error: "not-ready" });
+      }
       if (req.headers["x-hmac"] !== signHmac(req.rawBody)) {
         throw new Error("signature mismatch");
       }
@@ -536,6 +544,28 @@ describe("extraRoutes: entry:signature", () => {
     expect(await res.json()).toEqual({ error: "unknown-provider" });
   });
 
+  test("verify() throwing ExtraRouteRejection(503, body, options) surfaces the body and Retry-After header", async () => {
+    const res = await stack.app.request("/webhooks/probe", {
+      method: "POST",
+      headers: { "x-force-503": "retry", "content-type": "application/json" },
+      body: JSON.stringify({ note: "x" }),
+    });
+    expect(res.status).toBe(503);
+    expect(await res.json()).toEqual({ error: "not-ready" });
+    expect(res.headers.get("retry-after")).toBe("30");
+  });
+
+  test("verify() throwing ExtraRouteRejection(503, body) without options omits the Retry-After header", async () => {
+    const res = await stack.app.request("/webhooks/probe", {
+      method: "POST",
+      headers: { "x-force-503": "plain", "content-type": "application/json" },
+      body: JSON.stringify({ note: "x" }),
+    });
+    expect(res.status).toBe(503);
+    expect(await res.json()).toEqual({ error: "not-ready" });
+    expect(res.headers.get("retry-after")).toBeNull();
+  });
+
   test("mounted under /api/:provider — no session needed, honoPathToRegex matches the :param, rawBody arrives intact through /api/*", async () => {
     const rawBody = JSON.stringify({ event: "payment.succeeded" });
     const res = await stack.app.request("/api/webhooks/stripe", {

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

@@ -27,6 +27,14 @@ const boomFeature = defineFeature("boom", (r) => {
     },
     openToAll,
   );
+  r.writeHandler(
+    "explode",
+    z.object({}),
+    async () => {
+      throw new Error("disk on fire during write");
+    },
+    openToAll,
+  );
   r.queryHandler(
     "decode",
     z.object({}),
@@ -58,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({
@@ -140,11 +158,97 @@ describe("HTTP layer logs unexpected 5xx faults", () => {
     }
   });
 
+  test("a throwing write 500s AND its cause reaches the log (reraise keeps the cause)", async () => {
+    const calls: unknown[][] = [];
+    const spy = spyOn(console, "error").mockImplementation((...args) => {
+      calls.push(args);
+    });
+    try {
+      const res = await app.request("/api/write", {
+        method: "POST",
+        headers: await auth(),
+        body: JSON.stringify({ type: "boom:write:explode", payload: {} }),
+      });
+      expect(res.status).toBe(500);
+      const hit = calls.find(
+        (args) => typeof args[0] === "string" && args[0].includes("[api] handler failed"),
+      );
+      const data = hit?.[1];
+      expect(isRecord(data)).toBe(true);
+      if (!isRecord(data)) return;
+      expect(data["type"]).toBe("boom:write:explode");
+      expect(data["cause"]).toBe("disk on fire during write");
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
   test("a 404 stays off the error level (it is a client outcome, not a server fault)", async () => {
     const { status, errors } = await queryWithCapturedWarnings("nope:query:nothing", {});
     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/api-constants.ts

@@ -101,6 +101,19 @@ export const BODY_LIMIT_OPT_OUT_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.files}`,
 ]);
 
+// authEndpointRateLimit (L2) exceptions, exact method+path match, no prefix/glob.
+// A forgotten entry here is safe (over-limited, not unlimited).
+export const AUTH_RATE_LIMIT_EXEMPT_ROUTES: ReadonlyArray<{
+  readonly method: string;
+  readonly path: string;
+}> = [{ method: "GET", path: `/api${Routes.authTenants}` }];
+
+export function isAuthRateLimitExempt(method: string, path: string): boolean {
+  return AUTH_RATE_LIMIT_EXEMPT_ROUTES.some(
+    (route) => route.method === method && route.path === path,
+  );
+}
+
 // Methods that can mutate server state. GET/HEAD/OPTIONS are safe under
 // CORS + SameSite-cookie semantics and skip the CSRF / Origin guards entirely.
 export const STATE_CHANGING_METHODS: ReadonlySet<string> = new Set([

package/src/api/extra-route.ts

@@ -128,19 +128,48 @@ export function signatureRoute<T>(def: SignatureExtraRoute<T>): ExtraRouteDefini
   return def as unknown as SignatureExtraRoute<unknown>;
 }
 
-export type ExtraRouteRejectionStatus = 400 | 401 | 403 | 404 | 500;
+export type ExtraRouteRejectionStatus = 400 | 401 | 403 | 404 | 500 | 503;
+
+export type ExtraRouteRejectionOptions = { readonly retryAfterSeconds?: number };
 
 /** Thrown by `verify()` to reject a signature route with a specific status +
  *  JSON body. Any other throw from `verify()` is mapped to 401
- *  `extra_route_signature_invalid` by the buildServer wrapper. */
+ *  `extra_route_signature_invalid` by the buildServer wrapper.
+ *
+ *  503 signals "temporarily not ready" (e.g. a dependency the verify step
+ *  needs is down) — webhook providers like Stripe retry on 503.
+ *  `options.retryAfterSeconds` renders as the `Retry-After` header. */
 export class ExtraRouteRejection extends Error {
   readonly status: ExtraRouteRejectionStatus;
   readonly body: unknown;
-
-  constructor(status: ExtraRouteRejectionStatus, body: unknown, message?: string) {
+  readonly retryAfterSeconds: number | undefined;
+
+  constructor(
+    status: ExtraRouteRejectionStatus,
+    body: unknown,
+    message?: string,
+    options?: ExtraRouteRejectionOptions,
+  ) {
     super(message ?? `extra route rejected with status ${status}`);
     this.name = "ExtraRouteRejection";
     this.status = status;
     this.body = body;
+    const retryAfterSeconds = options?.retryAfterSeconds;
+    if (retryAfterSeconds !== undefined) {
+      // Retry-After is only meaningful for 503 in this union (RFC 9110) and
+      // is rendered as a delta-seconds header — reject anything that could
+      // not survive that round-trip.
+      if (status !== 503) {
+        throw new RangeError(
+          "ExtraRouteRejection: retryAfterSeconds is only valid with status 503",
+        );
+      }
+      if (!Number.isInteger(retryAfterSeconds) || retryAfterSeconds < 0) {
+        throw new RangeError(
+          "ExtraRouteRejection: retryAfterSeconds must be a non-negative integer",
+        );
+      }
+    }
+    this.retryAfterSeconds = retryAfterSeconds;
   }
 }

package/src/api/index.ts

@@ -33,6 +33,7 @@ export type {
   AnonymousExtraRouteDeps,
   ExtraRouteDefinition,
   ExtraRouteEntry,
+  ExtraRouteRejectionOptions,
   ExtraRouteRejectionStatus,
   SignatureExtraRoute,
   SignatureExtraRouteDeps,

package/src/api/request-context.ts

@@ -17,10 +17,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;

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/server.ts

@@ -160,14 +160,17 @@ export type ServerOptions = {
   //     of the app process.
   //   - `auth`: gates a single path-pattern (default `/api/auth/*`)
   //     with tighter limits. Typically `limit: 5, windowSeconds: 60`
-  //     to slow brute-force without breaking real users.
+  //     to slow brute-force without breaking real users. GET /api/auth/tenants
+  //     (session read, called on every page load) is always exempt — see
+  //     AUTH_RATE_LIMIT_EXEMPT_ROUTES in api-constants.ts.
   // Both omitted → no L1/L2 wired and no resolver auto-built unless an
   // L3 handler declared `rateLimit:`. This keeps zero-cost when unused.
   rateLimit?: {
     readonly global?: Omit<GlobalIpRateLimitOptions, "resolver">;
     readonly auth?: Omit<AuthEndpointRateLimitOptions, "resolver"> & {
       // Path-pattern the L2 middleware applies to. Default `/api/auth/*`.
-      // Override for apps with a different auth route layout.
+      // Override for apps with a different auth route layout. The
+      // GET /api/auth/tenants exemption above applies regardless of `path`.
       readonly path?: string;
     };
   };
@@ -1178,6 +1181,9 @@ function buildExtraRouteHonoHandler(
           );
         } catch (e) {
           if (e instanceof ExtraRouteRejection) {
+            if (e.retryAfterSeconds !== undefined) {
+              return c.json(e.body, e.status, { "Retry-After": String(e.retryAfterSeconds) });
+            }
             return c.json(e.body, e.status);
           }
           return c.json(

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);
+    }
+  });
+});