@cosmicdrift/kumiko-bundled-features 0.213.0 → 0.215.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.213.0",
+  "version": "0.215.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -126,12 +126,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.213.0",
-    "@cosmicdrift/kumiko-framework": "0.213.0",
-    "@cosmicdrift/kumiko-headless": "0.213.0",
-    "@cosmicdrift/kumiko-renderer": "0.213.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.213.0",
-    "@cosmicdrift/kumiko-types": "0.213.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.215.0",
+    "@cosmicdrift/kumiko-framework": "0.215.0",
+    "@cosmicdrift/kumiko-headless": "0.215.0",
+    "@cosmicdrift/kumiko-renderer": "0.215.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.215.0",
+    "@cosmicdrift/kumiko-types": "0.215.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -160,6 +160,6 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.213.0"
+    "@cosmicdrift/kumiko-locale-de": "0.215.0"
   }
 }

package/src/auth-email-password/auth-user-row.ts

@@ -19,6 +19,8 @@ export type AuthUserRow = {
   readonly lastActiveTenantId?: TenantId | string | null;
   // IANA zone — threaded into SessionUser.timezone at login (fw#1636).
   readonly timezone?: string | null;
+  // BCP-47 tag — threaded into SessionUser.locale at login (fw#2333).
+  readonly locale?: string | null;
   // JSON-encoded string[] — globale Rollen die parallel zu tenant-membership-
   // roles gelten (z.B. SystemAdmin, BillingAdmin). Caller deserialisiert via
   // parseRoles() vor dem Merge in die Session.

package/src/auth-email-password/handlers/invite-accept-with-login.write.ts

@@ -32,7 +32,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
-import { decryptStoredPii, sessionTimezoneField } from "../../shared";
+import { decryptStoredPii, sessionLocaleField, sessionTimezoneField } from "../../shared";
 // kumiko-lint-ignore cross-feature-import invite-flow
 import {
   INVITATION_STATUS,
@@ -136,6 +136,7 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
         readonly id: string;
         readonly passwordHash: string | null;
         readonly timezone?: string | null;
+        readonly locale?: string | null;
         readonly emailVerified?: boolean | null;
         readonly status?: string | null;
       };
@@ -251,6 +252,7 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
           tenantId: invitationTenantId,
           roles: mergedRoles,
           ...sessionTimezoneField(userRow.timezone),
+          ...sessionLocaleField(userRow.locale),
         };
 
         committed = true;

package/src/auth-email-password/handlers/login.write.ts

@@ -230,12 +230,14 @@ export async function gateBuildSession(
   tenantId: TenantId,
   mergedRoles: readonly string[],
   timezone?: string | null,
+  locale?: string | null,
 ): Promise<{ readonly kind: "auth-session"; readonly session: SessionUser }> {
   const baseSession: SessionUser = {
     id: userId,
     tenantId,
     roles: mergedRoles,
     ...(timezone !== null && timezone !== undefined && { timezone }),
+    ...(locale !== null && locale !== undefined && { locale }),
   };
   const claims = await ctx.resolveAuthClaims(baseSession);
   const session: SessionUser =
@@ -306,6 +308,7 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
         chosen.tenantId,
         mergedRoles,
         found.timezone,
+        found.locale,
       );
       return { isSuccess: true, data: session };
     },

package/src/auth-mfa/handlers/enable-confirm-preauth.write.ts

@@ -9,7 +9,7 @@ import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/error
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
-import { burnToken, sessionTimezoneField } from "../../shared";
+import { burnToken, sessionLocaleField, sessionTimezoneField } from "../../shared";
 import { USER_STATUS, UserQueries } from "../../user";
 import { base32Decode } from "../base32";
 import { MFA_VERIFY_LOCKOUT_MINUTES, MFA_VERIFY_MAX_ATTEMPTS } from "../constants";
@@ -138,7 +138,12 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
       const systemUser = createSystemUser(tenantId, ["SystemAdmin"]);
       const userRow = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
         id: userId,
-      })) as { roles?: string | null; status?: string; timezone?: string | null } | null; // @cast-boundary engine-payload
+      })) as {
+        roles?: string | null;
+        status?: string;
+        timezone?: string | null;
+        locale?: string | null;
+      } | null; // @cast-boundary engine-payload
 
       if (!userRow) return invalidSetupToken();
       if (
@@ -192,6 +197,7 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
         // a plain password login does — same helper as verify.write.ts /
         // invite-accept-with-login.write.ts (#1759).
         ...sessionTimezoneField(userRow?.timezone),
+        ...sessionLocaleField(userRow?.locale),
       };
       const claims = await ctx.resolveAuthClaims(baseSession);
       const session: SessionUser =

package/src/auth-mfa/handlers/verify.write.ts

@@ -8,7 +8,7 @@ import {
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
-import { burnToken, sessionTimezoneField } from "../../shared";
+import { burnToken, sessionLocaleField, sessionTimezoneField } from "../../shared";
 import { USER_STATUS, UserQueries } from "../../user";
 import { MFA_VERIFY_LOCKOUT_MINUTES, MFA_VERIFY_MAX_ATTEMPTS } from "../constants";
 import { findUserMfaRow } from "../db/queries";
@@ -135,7 +135,12 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       const systemUser = createSystemUser(tenantId, ["SystemAdmin"]);
       const userRow = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
         id: userId,
-      })) as { roles?: string | null; status?: string; timezone?: string | null } | null; // @cast-boundary engine-payload
+      })) as {
+        roles?: string | null;
+        status?: string;
+        timezone?: string | null;
+        locale?: string | null;
+      } | null; // @cast-boundary engine-payload
 
       // Re-check status + membership the way login.write.ts does after its
       // password check — the challenge token only proves "password was
@@ -173,6 +178,7 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
         tenantId,
         roles: mergedRoles,
         ...sessionTimezoneField(userRow?.timezone),
+        ...sessionLocaleField(userRow?.locale),
       };
       const claims = await ctx.resolveAuthClaims(baseSession);
       const session: SessionUser =

package/src/custom-fields/db/queries/__tests__/unsafe-read-retrying.test.ts

@@ -0,0 +1,93 @@
+// #2323: field-access.ts, quota.ts, user-data-rights.ts and retention.ts read
+// custom-field rows via asRawClient(db).unsafe() directly, bypassing the
+// #1163 closed-connection retry that only covered bun-db/query.ts's own
+// selectMany/countWhere. Routed the SELECT-only call sites through
+// unsafeReadRetrying instead — this test mirrors
+// bun-db/__tests__/select-many-retry.test.ts's fake-client pattern to prove
+// the retry now actually fires for each call site. applyRetentionRemovals
+// (an UPDATE) is out of scope per #1358 — writes stay unretried.
+
+import { describe, expect, test } from "bun:test";
+import { selectSerializedFieldDefinition } from "../field-access";
+import { countTenantFieldDefinitions } from "../quota";
+import { selectHostRowsWithCustomFields } from "../retention";
+import { selectCustomFieldsHostRows, selectFieldDefinitionsForEntity } from "../user-data-rights";
+
+function closedConnectionError(): Error {
+  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
+}
+
+type FakeClient = {
+  unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+  begin: () => never;
+  calls: number;
+};
+
+function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient {
+  const remaining = [...failures];
+  const client: FakeClient = {
+    calls: 0,
+    unsafe: async () => {
+      client.calls++;
+      const err = remaining.shift();
+      if (err) throw err;
+      return [row];
+    },
+    begin: () => {
+      throw new Error("not used in test");
+    },
+  };
+  return client;
+}
+
+describe("custom-fields db/queries — closed-connection retry (#2323)", () => {
+  test("selectSerializedFieldDefinition retries once through db.raw and returns the row", async () => {
+    const raw = fakeClient([closedConnectionError()], { serialized_field: "sf1" });
+    const result = await selectSerializedFieldDefinition({ raw } as never, "t1", "entity", "field");
+    expect(result).toBe("sf1");
+    expect(raw.calls).toBe(2);
+  });
+
+  test("countTenantFieldDefinitions retries once through db.raw and returns the count", async () => {
+    const raw = fakeClient([closedConnectionError()], { n: 3 });
+    const result = await countTenantFieldDefinitions({ raw } as never, "t1");
+    expect(result).toBe(3);
+    expect(raw.calls).toBe(2);
+  });
+
+  test("selectCustomFieldsHostRows retries once and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()], { id: "1", custom_fields: {} });
+    const rows = await selectCustomFieldsHostRows(db as never, "host_table", "user_id", "u1", "t1");
+    expect(rows).toHaveLength(1);
+    expect(db.calls).toBe(2);
+  });
+
+  test("selectFieldDefinitionsForEntity retries once and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()], { field_key: "k1", serialized_field: "sf" });
+    const rows = await selectFieldDefinitionsForEntity(db as never, "entity", "t1");
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.field_key).toBe("k1");
+    expect(db.calls).toBe(2);
+  });
+
+  test("selectHostRowsWithCustomFields retries once and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()], {
+      id: "1",
+      modified_at: null,
+      custom_fields: {},
+    });
+    const rows = await selectHostRowsWithCustomFields(db as never, "host_table", "t1");
+    expect(rows).toHaveLength(1);
+    expect(db.calls).toBe(2);
+  });
+
+  test("gives up after the single retry when the connection stays closed", async () => {
+    const raw = fakeClient([closedConnectionError(), closedConnectionError()], {
+      serialized_field: "sf1",
+    });
+    await expect(
+      selectSerializedFieldDefinition({ raw } as never, "t1", "entity", "field"),
+    ).rejects.toThrow("connection was closed");
+    expect(raw.calls).toBe(2);
+  });
+});

package/src/custom-fields/db/queries/field-access.ts

@@ -1,4 +1,4 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 
 export async function selectSerializedFieldDefinition(
@@ -7,7 +7,8 @@ export async function selectSerializedFieldDefinition(
   entityName: string,
   fieldKey: string,
 ): Promise<unknown | null> {
-  const rows = await asRawClient(db.raw).unsafe(
+  const rows = await unsafeReadRetrying(
+    db.raw,
     "SELECT serialized_field FROM read_custom_field_definitions WHERE entity_name = $1 AND field_key = $2 AND tenant_id = $3 LIMIT 1",
     [entityName, fieldKey, tenantId],
   );

package/src/custom-fields/db/queries/quota.ts

@@ -1,10 +1,11 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 
 export async function countTenantFieldDefinitions(db: TenantDb, tenantId: string): Promise<number> {
   // Active definitions only — delete soft-deletes (the deterministic stream is
   // kept so a re-define can restore it), so isDeleted rows must not consume quota.
-  const rowsResult = await asRawClient(db.raw).unsafe(
+  const rowsResult = await unsafeReadRetrying(
+    db.raw,
     "SELECT COUNT(*)::int AS n FROM read_custom_field_definitions WHERE tenant_id = $1 AND is_deleted = FALSE",
     [tenantId],
   );

package/src/custom-fields/db/queries/retention.ts

@@ -1,4 +1,4 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { asRawClient, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 
 export async function selectHostRowsWithCustomFields(
@@ -7,7 +7,8 @@ export async function selectHostRowsWithCustomFields(
   tenantId: string,
 ): Promise<readonly unknown[]> {
   const quoted = `"${tableName.replace(/"/g, '""')}"`;
-  const rowsResult = await asRawClient(db).unsafe(
+  const rowsResult = await unsafeReadRetrying(
+    db,
     `SELECT id, modified_at, custom_fields FROM ${quoted} WHERE tenant_id = $1 AND custom_fields IS NOT NULL`,
     [tenantId],
   );

package/src/custom-fields/db/queries/user-data-rights.ts

@@ -1,4 +1,4 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 
 function quoteTable(tableName: string): string {
@@ -18,7 +18,8 @@ export async function selectCustomFieldsHostRows(
 ): Promise<readonly unknown[]> {
   const tbl = quoteTable(tableName);
   const userCol = quoteColumn(userIdColumn);
-  const rowsResult = await asRawClient(db).unsafe(
+  const rowsResult = await unsafeReadRetrying(
+    db,
     `SELECT id, custom_fields FROM ${tbl} WHERE ${userCol} = $1 AND tenant_id = $2`,
     [userId, tenantId],
   );
@@ -30,7 +31,8 @@ export async function selectFieldDefinitionsForEntity(
   entityName: string,
   tenantId: string,
 ): Promise<readonly { field_key: string; serialized_field: unknown }[]> {
-  return asRawClient(db).unsafe(
+  return unsafeReadRetrying(
+    db,
     "SELECT field_key, serialized_field FROM read_custom_field_definitions WHERE entity_name = $1 AND tenant_id = $2",
     [entityName, tenantId],
   ) as Promise<readonly { field_key: string; serialized_field: unknown }[]>;

package/src/form-draft/db/queries/__tests__/unsafe-read-retrying.test.ts

@@ -0,0 +1,87 @@
+// #2323: draft-count.ts, owned-file-refs.ts and cleanup.ts read form-draft
+// rows via asRawClient(db).unsafe() directly, bypassing the #1163
+// closed-connection retry that only covered bun-db/query.ts's own
+// selectMany/countWhere. Routed the SELECT-only call sites through
+// unsafeReadRetrying instead — this test mirrors
+// bun-db/__tests__/select-many-retry.test.ts's fake-client pattern to prove
+// the retry now actually fires for each call site.
+
+import { describe, expect, test } from "bun:test";
+import { Temporal } from "temporal-polyfill";
+import { selectStaleDraftsBatch } from "../cleanup";
+import { countDraftsByOwner } from "../draft-count";
+import { filterOwnedFileRefs } from "../owned-file-refs";
+
+function closedConnectionError(): Error {
+  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
+}
+
+type FakeClient = {
+  unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+  begin: () => never;
+  calls: number;
+};
+
+function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient {
+  const remaining = [...failures];
+  const client: FakeClient = {
+    calls: 0,
+    unsafe: async () => {
+      client.calls++;
+      const err = remaining.shift();
+      if (err) throw err;
+      return [row];
+    },
+    begin: () => {
+      throw new Error("not used in test");
+    },
+  };
+  return client;
+}
+
+describe("form-draft db/queries — closed-connection retry (#2323)", () => {
+  test("countDraftsByOwner retries once and returns the count", async () => {
+    const db = fakeClient([closedConnectionError()], { count: 4 });
+    const result = await countDraftsByOwner(db as never, "t1" as never, "owner1");
+    expect(result).toBe(4);
+    expect(db.calls).toBe(2);
+  });
+
+  test("filterOwnedFileRefs retries once and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()], { id: "ref1", storage_key: "key1" });
+    const rows = await filterOwnedFileRefs(
+      db as never,
+      "t1" as never,
+      "owner1",
+      ["key1"],
+      Temporal.Now.instant(),
+      false,
+    );
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.storageKey).toBe("key1");
+    expect(db.calls).toBe(2);
+  });
+
+  test("selectStaleDraftsBatch retries once and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()], {
+      id: "d1",
+      tenant_id: "t1",
+      owner_id: "owner1",
+      draft_key: "screen:1",
+      draft: {},
+      inserted_at: new Date("2026-01-01T00:00:00Z"),
+    });
+    const rows = await selectStaleDraftsBatch(db as never, 30, 10);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.id).toBe("d1");
+    expect(db.calls).toBe(2);
+  });
+
+  test("gives up after the single retry when the connection stays closed", async () => {
+    const db = fakeClient([closedConnectionError(), closedConnectionError()], { count: 4 });
+    await expect(countDraftsByOwner(db as never, "t1" as never, "owner1")).rejects.toThrow(
+      "connection was closed",
+    );
+    expect(db.calls).toBe(2);
+  });
+});

package/src/form-draft/db/queries/cleanup.ts

@@ -1,4 +1,4 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "temporal-polyfill";
@@ -29,7 +29,8 @@ export async function selectStaleDraftsBatch(
   olderThanDays: number,
   batchSize: number,
 ): Promise<readonly StaleDraftRow[]> {
-  const rows = (await asRawClient(db).unsafe(
+  const rows = (await unsafeReadRetrying(
+    db,
     `SELECT "id", "tenant_id", "owner_id", "draft_key", "draft", "inserted_at" FROM "read_form_drafts"
      WHERE COALESCE("modified_at", "inserted_at") < now() - ($1::int * interval '1 day')
      ORDER BY COALESCE("modified_at", "inserted_at") ASC

package/src/form-draft/db/queries/draft-count.ts

@@ -1,4 +1,4 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
@@ -11,7 +11,8 @@ export async function countDraftsByOwner(
   tenantId: TenantId,
   ownerId: string,
 ): Promise<number> {
-  const rows = (await asRawClient(db).unsafe(
+  const rows = (await unsafeReadRetrying(
+    db,
     `SELECT count(*)::int AS "count" FROM "read_form_drafts"
      WHERE "tenant_id" = $1 AND "owner_id" = $2`,
     [tenantId, ownerId],

package/src/form-draft/db/queries/owned-file-refs.ts

@@ -1,4 +1,4 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { Temporal } from "temporal-polyfill";
@@ -62,7 +62,8 @@ export async function filterOwnedFileRefs(
   isCreateMode: boolean,
 ): Promise<readonly OwnedFileRef[]> {
   if (candidateKeys.length === 0) return [];
-  const rows = (await asRawClient(db).unsafe(
+  const rows = (await unsafeReadRetrying(
+    db,
     `SELECT "id", "storage_key" FROM "file_refs"
      WHERE "tenant_id" = $1 AND "inserted_by_id" = $2
        AND "storage_key" = ANY($3::text[]) AND "is_deleted" = false

package/src/shared/index.ts

@@ -16,6 +16,7 @@ export { isWithinGracePeriod } from "./grace-period";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash";
 export { mapWithConcurrency } from "./map-with-concurrency";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing";
+export { sessionLocaleField } from "./session-locale-field";
 export { sessionTimezoneField } from "./session-timezone-field";
 export type { SystemQueryFn } from "./system-query";
 export { type BurnResult, burnToken, unburnToken } from "./token-burn-store";

package/src/shared/session-locale-field.ts

@@ -0,0 +1,7 @@
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+
+export function sessionLocaleField(
+  locale: string | null | undefined,
+): Pick<SessionUser, "locale"> | Record<string, never> {
+  return locale !== null && locale !== undefined ? { locale } : {};
+}

package/src/user/db/queries/__tests__/unsafe-read-retrying.test.ts

@@ -0,0 +1,52 @@
+// #2323: stream-tenant-backfill.ts's candidate scan (a plain, non-transactional
+// SELECT) read via asRawClient(db).unsafe() directly, bypassing the #1163
+// closed-connection retry. Routed it through unsafeReadRetrying instead — this
+// test mirrors bun-db/__tests__/select-many-retry.test.ts's fake-client
+// pattern to prove the retry now fires. migrateAggregate's per-aggregate
+// SELECT ... FOR UPDATE stays out of scope: it runs inside transaction(),
+// where the retry guard (no begin() on a tx handle) is a no-op by design.
+
+import { describe, expect, test } from "bun:test";
+import { backfillUserStreamTenants } from "../stream-tenant-backfill";
+
+function closedConnectionError(): Error {
+  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
+}
+
+type FakeClient = {
+  unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+  begin: () => never;
+  calls: number;
+};
+
+function fakeClient(failures: Error[]): FakeClient {
+  const remaining = [...failures];
+  const client: FakeClient = {
+    calls: 0,
+    unsafe: async () => {
+      client.calls++;
+      const err = remaining.shift();
+      if (err) throw err;
+      return [];
+    },
+    begin: () => {
+      throw new Error("not used in test");
+    },
+  };
+  return client;
+}
+
+describe("user db/queries — closed-connection retry (#2323)", () => {
+  test("backfillUserStreamTenants retries the candidate scan once and completes with no candidates", async () => {
+    const db = fakeClient([closedConnectionError()]);
+    const result = await backfillUserStreamTenants(db as never);
+    expect(result).toEqual({ aggregatesMigrated: 0, eventsMigrated: 0, failed: [] });
+    expect(db.calls).toBe(2);
+  });
+
+  test("gives up after the single retry when the connection stays closed", async () => {
+    const db = fakeClient([closedConnectionError(), closedConnectionError()]);
+    await expect(backfillUserStreamTenants(db as never)).rejects.toThrow("connection was closed");
+    expect(db.calls).toBe(2);
+  });
+});

package/src/user/db/queries/stream-tenant-backfill.ts

@@ -24,7 +24,7 @@
 // the stream move: rebuildProjection("user:projection:user-entity", ...) or
 // the jobs:job:projection-rebuild job.
 
-import { asRawClient, transaction } from "@cosmicdrift/kumiko-framework/bun-db";
+import { asRawClient, transaction, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 
@@ -37,7 +37,8 @@ export type UserStreamBackfillResult = {
 export async function backfillUserStreamTenants(
   db: DbConnection,
 ): Promise<UserStreamBackfillResult> {
-  const candidates = (await asRawClient(db).unsafe(
+  const candidates = (await unsafeReadRetrying(
+    db,
     `SELECT DISTINCT "aggregate_id" FROM "kumiko_events"
       WHERE "aggregate_type" = 'user' AND "tenant_id" <> $1::uuid`,
     [SYSTEM_TENANT_ID],