@cosmicdrift/kumiko-bundled-features 0.304.0 → 0.306.0

package/src/billing-foundation/__tests__/tenant-destroy.integration.test.ts

@@ -0,0 +1,199 @@
+// Drives the real tenant-lifecycle destruction sweep: a direct hook call with a hand-built
+// TenantDb hides the escapeHatch grant the "app-data" stage actually resolves.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { append, isStreamArchived, loadAggregate } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  resetPiiSubjectKmsForTests,
+  resetTestTables,
+  updateRows,
+} from "@cosmicdrift/kumiko-framework/testing";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+  tenantComplianceProfileTable,
+} from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { tenantMembershipEntity } from "../../tenant";
+import { TenantHandlers } from "../../tenant/constants";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantEntity, tenantTable } from "../../tenant/schema/tenant";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import {
+  TENANT_AGGREGATE_TYPE,
+  TENANT_DESTRUCTION_STARTED_EVENT_QN,
+} from "../../tenant-lifecycle/constants";
+import { runTenantDestructionSweep } from "../../tenant-lifecycle/run-tenant-destroy";
+import { subscriptionAggregateId } from "../aggregate-id";
+import { SubscriptionEventTypes, SubscriptionFoundationHandlers } from "../constants";
+import { billingFoundationFeature } from "../feature";
+import { subscriptionsProjectionTable } from "../projection";
+
+const SET_PROFILE = "compliance-profiles:write:set-profile";
+
+let stack: TestStack;
+let db: DbConnection;
+
+function adminFor(tenantNumber: number) {
+  return createTestUser({
+    id: tenantNumber,
+    tenantId: testTenantId(tenantNumber),
+    roles: ["TenantAdmin", "SystemAdmin"],
+  });
+}
+
+const tenantA = adminFor(9001);
+const tenantB = adminFor(9002);
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      billingFoundationFeature,
+    ],
+  });
+  db = stack.db;
+  await unsafeCreateEntityTable(db, tenantEntity);
+  await unsafeCreateEntityTable(db, tenantComplianceProfileEntity);
+  await unsafeCreateEntityTable(db, tenantMembershipEntity);
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+  resetPiiSubjectKmsForTests();
+});
+
+beforeEach(async () => {
+  stack.events.reset();
+  await resetTestTables(db, [tenantTable, tenantComplianceProfileTable]);
+  await stack.db.unsafe?.(`TRUNCATE kumiko_events, read_subscriptions RESTART IDENTITY CASCADE`);
+});
+
+async function seedTenant(user: typeof tenantA, profileKey = "eu-dsgvo"): Promise<void> {
+  await stack.http.writeOk(
+    TenantHandlers.create,
+    { id: user.tenantId, key: `t-${user.tenantId}`, name: "Tenant" },
+    TestUsers.systemAdmin,
+  );
+  await stack.http.writeOk(SET_PROFILE, { profileKey }, user);
+}
+
+async function seedSubscription(user: typeof tenantA, eventIdSuffix: string): Promise<void> {
+  await stack.http.writeOk(
+    SubscriptionFoundationHandlers.processEvent,
+    {
+      providerEventId: `evt_${eventIdSuffix}`,
+      providerName: "stripe",
+      type: SubscriptionEventTypes.created,
+      status: "active",
+      tier: "pro",
+      providerCustomerId: `cus_${eventIdSuffix}`,
+      providerSubscriptionId: `sub_${eventIdSuffix}`,
+      currentPeriodEndIso: "2030-01-01T00:00:00Z",
+      rawPayload: "{}",
+    },
+    user,
+  );
+}
+
+async function seedDestroyingTenant(tenantId: TenantId): Promise<void> {
+  const now = getTemporal().Now.instant();
+  await updateRows(
+    db,
+    tenantTable,
+    { status: "destroying", destroyStartedAt: now },
+    { id: tenantId },
+  );
+  await append(db, {
+    aggregateId: tenantId,
+    aggregateType: TENANT_AGGREGATE_TYPE,
+    tenantId,
+    expectedVersion: (await loadAggregate(db, tenantId, tenantId)).at(-1)?.version ?? 0,
+    type: TENANT_DESTRUCTION_STARTED_EVENT_QN,
+    payload: { startedAt: now.toString() },
+    metadata: { userId: "system", requestId: "test:destruction-started" },
+  });
+}
+
+async function driveDestructionToCompletion(tenantId: TenantId): Promise<string> {
+  const farFuture = getTemporal()
+    .Now.instant()
+    .add({ hours: 24 * 3650 });
+  let status = "";
+  for (let i = 0; i < 20; i++) {
+    await runTenantDestructionSweep({ db: stack.db, registry: stack.registry, now: farFuture });
+    const rows = await selectMany(db, tenantTable, { id: tenantId });
+    status = String(rows[0]?.["status"]);
+    if (status === "destroyed" || status === "destroyFailed") break;
+  }
+  return status;
+}
+
+describe("billing-foundation :: tenant destroy (#3196)", () => {
+  test("deletes the subscription row for the destroyed tenant, archives its stream, leaves another tenant's row untouched", async () => {
+    await seedTenant(tenantA);
+    await seedTenant(tenantB);
+
+    await seedSubscription(tenantA, "a");
+    await seedSubscription(tenantB, "b");
+
+    await seedDestroyingTenant(tenantA.tenantId);
+
+    const finalStatus = await driveDestructionToCompletion(tenantA.tenantId);
+    expect(finalStatus).toBe("destroyed");
+
+    const rowsA = await selectMany(db, subscriptionsProjectionTable, {
+      id: subscriptionAggregateId(tenantA.tenantId),
+    });
+    expect(rowsA).toHaveLength(0);
+
+    const rowsB = await selectMany(db, subscriptionsProjectionTable, {
+      id: subscriptionAggregateId(tenantB.tenantId),
+    });
+    expect(rowsB).toHaveLength(1);
+
+    expect(
+      await isStreamArchived(db, tenantA.tenantId, subscriptionAggregateId(tenantA.tenantId)),
+    ).toBe(true);
+  });
+
+  test("HGB profile: redacts PII fields but keeps the row and archives its stream", async () => {
+    const tenantHgb = adminFor(9003);
+    await seedTenant(tenantHgb, "de-hr-dsgvo-hgb");
+
+    await seedSubscription(tenantHgb, "c");
+
+    await seedDestroyingTenant(tenantHgb.tenantId);
+
+    const finalStatus = await driveDestructionToCompletion(tenantHgb.tenantId);
+    expect(finalStatus).toBe("destroyed");
+
+    const rowsA = await selectMany(db, subscriptionsProjectionTable, {
+      id: subscriptionAggregateId(tenantHgb.tenantId),
+    });
+    expect(rowsA).toHaveLength(1);
+    expect(rowsA[0]?.["providerCustomerId"]).toBe("[erased]");
+    expect(rowsA[0]?.["providerSubscriptionId"]).toBe("[erased]");
+
+    expect(
+      await isStreamArchived(db, tenantHgb.tenantId, subscriptionAggregateId(tenantHgb.tenantId)),
+    ).toBe(true);
+  });
+});

package/src/billing-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.306.0",
+    "type": "fix",
+    "title": "Tenant destroy no longer fails on subscription and payment rows",
+    "detail": "The subscription and payment tenant-destroy hooks passed the tenant-scoped TenantDb they receive into raw DbRunner helpers, so the app-data stage failed and the tenant ended in destroyFailed. They now use ctx.db methods and declare an escapeHatch for the compliance-profile lookup and the event-stream archive."
+  },
   {
     "version": "0.301.0",
     "type": "breaking",

package/src/billing-foundation/feature.ts

@@ -81,7 +81,12 @@ import {
   paymentsProjectionTable,
   subscriptionsProjectionTable,
 } from "./projection";
-import { paymentTenantDestroyHook, subscriptionTenantDestroyHook } from "./tenant-destroy-hook";
+import {
+  PAYMENT_TENANT_DESTROY_ARCHIVE_REASON,
+  paymentTenantDestroyHook,
+  SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON,
+  subscriptionTenantDestroyHook,
+} from "./tenant-destroy-hook";
 
 export const billingFoundationFeature = defineFeature(BILLING_FOUNDATION_FEATURE, (r) => {
   r.describe(
@@ -169,8 +174,10 @@ export const billingFoundationFeature = defineFeature(BILLING_FOUNDATION_FEATURE
 
   r.useExtension(EXT_TENANT_DATA, "subscription", {
     destroy: subscriptionTenantDestroyHook,
+    escapeHatch: { reason: SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON },
   });
   r.useExtension(EXT_TENANT_DATA, "payment", {
     destroy: paymentTenantDestroyHook,
+    escapeHatch: { reason: PAYMENT_TENANT_DESTROY_ARCHIVE_REASON },
   });
 });

package/src/billing-foundation/tenant-destroy-hook.ts

@@ -1,5 +1,5 @@
-import { deleteMany, type EntityTableMeta, updateMany } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import { declareEscapeHatch, type TenantDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
 import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
 import { resolveProfileForTenant } from "../compliance-profiles";
 import { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id";
@@ -13,30 +13,33 @@ import { paymentsProjectionTable, subscriptionsProjectionTable } from "./project
 // it redacts the projection row directly instead of relying on key erasure.
 const REDACTED_PII_VALUE = "[erased]";
 
+// Compliance-profile lookup and event-stream archive both sit outside TenantDb's own methods — need the escape hatch.
+export const SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON =
+  "tenant-destroy looks up the compliance profile and archives the subscription event-stream before the projection row is redacted/deleted";
+export const PAYMENT_TENANT_DESTROY_ARCHIVE_REASON =
+  "tenant-destroy looks up the compliance profile and archives the payment event-stream before the projection rows are redacted/deleted";
+
 /** Tenant-destroy hook for billing PII (#800). HGB retains the accounting
  *  row but redacts the two provider-subject PII fields; other profiles
  *  hard-delete the row. Either way the subscription stream is archived so a
  *  future projection rebuild can't resurrect what was erased. */
-export async function subscriptionTenantDestroyHook(ctx: {
-  readonly db: import("@cosmicdrift/kumiko-framework/db").DbRunner;
-  readonly tenantId: TenantId;
-}): Promise<void> {
+export async function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {
+  declareEscapeHatch({ reason: SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON });
   const { profile } = await resolveProfileForTenant({
-    db: ctx.db,
+    db: ctx.db.unsafeRaw(SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON),
     tenantId: ctx.tenantId,
   });
   const aggregateId = subscriptionAggregateId(ctx.tenantId);
   if (profile.key === "de-hr-dsgvo-hgb") {
-    await updateMany(
-      ctx.db,
+    await ctx.db.updateMany(
       subscriptionsProjectionTable as EntityTableMeta,
       { providerCustomerId: REDACTED_PII_VALUE, providerSubscriptionId: REDACTED_PII_VALUE },
       { id: aggregateId },
     );
   } else {
-    await deleteMany(ctx.db, subscriptionsProjectionTable as EntityTableMeta, { id: aggregateId });
+    await ctx.db.deleteMany(subscriptionsProjectionTable as EntityTableMeta, { id: aggregateId });
   }
-  await archiveStream(ctx.db, {
+  await archiveStream(ctx.db.unsafeRaw(SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON), {
     tenantId: ctx.tenantId,
     aggregateId,
     aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
@@ -50,28 +53,25 @@ export async function subscriptionTenantDestroyHook(ctx: {
  *  rows — the predicate here is `tenantId`, not `id`. The payment-stream
  *  itself is still one stream per tenant (paymentAggregateId), so
  *  archiveStream targets that single aggregateId as usual. */
-export async function paymentTenantDestroyHook(ctx: {
-  readonly db: import("@cosmicdrift/kumiko-framework/db").DbRunner;
-  readonly tenantId: TenantId;
-}): Promise<void> {
+export async function paymentTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {
+  declareEscapeHatch({ reason: PAYMENT_TENANT_DESTROY_ARCHIVE_REASON });
   const { profile } = await resolveProfileForTenant({
-    db: ctx.db,
+    db: ctx.db.unsafeRaw(PAYMENT_TENANT_DESTROY_ARCHIVE_REASON),
     tenantId: ctx.tenantId,
   });
   const aggregateId = paymentAggregateId(ctx.tenantId);
   if (profile.key === "de-hr-dsgvo-hgb") {
-    await updateMany(
-      ctx.db,
+    await ctx.db.updateMany(
       paymentsProjectionTable as EntityTableMeta,
       { providerCustomerId: REDACTED_PII_VALUE },
       { tenantId: ctx.tenantId },
     );
   } else {
-    await deleteMany(ctx.db, paymentsProjectionTable as EntityTableMeta, {
+    await ctx.db.deleteMany(paymentsProjectionTable as EntityTableMeta, {
       tenantId: ctx.tenantId,
     });
   }
-  await archiveStream(ctx.db, {
+  await archiveStream(ctx.db.unsafeRaw(PAYMENT_TENANT_DESTROY_ARCHIVE_REASON), {
     tenantId: ctx.tenantId,
     aggregateId,
     aggregateType: PAYMENT_AGGREGATE_TYPE,

package/src/billing-foundation/types.ts

@@ -26,7 +26,12 @@
 
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import type { BillingEventKinds, SubscriptionEventType, SubscriptionStatus } from "./constants";
+import {
+  type BillingEventKinds,
+  SUBSCRIPTION_PROVIDER_EXTENSION,
+  type SubscriptionEventType,
+  type SubscriptionStatus,
+} from "./constants";
 
 // =============================================================================
 // Normalisierter Webhook-Event
@@ -215,3 +220,10 @@ export type SubscriptionProviderPlugin = {
     providerSubscriptionId: string,
   ) => Promise<void>;
 };
+
+// r.useExtension options-shape, co-located since the framework never imports upward.
+declare module "@cosmicdrift/kumiko-framework/engine" {
+  interface KumikoExtensionOptionsMap {
+    [SUBSCRIPTION_PROVIDER_EXTENSION]: SubscriptionProviderPlugin;
+  }
+}

package/src/channel-email/feature.ts

@@ -1,3 +1,4 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { createEmailChannel, type EmailChannelOptions } from "./email-channel";
 
@@ -15,7 +16,7 @@ export function createChannelEmailFeature(options: EmailChannelOptions): Feature
     });
     r.requires("delivery");
 
-    r.useExtension("deliveryChannel", "email", {
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "email", {
       mode: channel.mode,
       resolve: channel.resolve,
       render: channel.render,

package/src/channel-in-app/feature.ts

@@ -1,3 +1,4 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { inboxQuery } from "./handlers/inbox.query";
 import { markAllReadWrite } from "./handlers/mark-all-read.write";
@@ -23,7 +24,7 @@ export function createChannelInAppFeature(): FeatureDefinition {
     });
 
     // Register as delivery channel via extension system
-    r.useExtension("deliveryChannel", "inApp", {
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "inApp", {
       mode: inAppChannel.mode,
       resolve: inAppChannel.resolve,
       send: inAppChannel.send,

package/src/channel-push/feature.ts

@@ -1,3 +1,4 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { createPushChannel, type PushChannelOptions } from "./push-channel";
 
@@ -15,7 +16,7 @@ export function createChannelPushFeature(options: PushChannelOptions): FeatureDe
     });
     r.requires("delivery");
 
-    r.useExtension("deliveryChannel", "push", {
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "push", {
       mode: channel.mode,
       resolve: channel.resolve,
       send: channel.send,

package/src/config/__tests__/reencrypt-job-concurrent-write-race.integration.test.ts

@@ -19,8 +19,8 @@ import { randomBytes } from "node:crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   createEventStoreExecutor,
+  createSystemDbView,
   createTenantDb,
-  createUncheckedSystemDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
@@ -157,12 +157,23 @@ function racyJobCtx(
   };
   return {
     db: createTenantDb(stack.db, SYSTEM_TENANT_ID),
-    systemDb: createUncheckedSystemDb(createTenantDb(stack.db, SYSTEM_TENANT_ID, "system")),
+    systemDb: createSystemDbView(
+      createTenantDb(stack.db, SYSTEM_TENANT_ID, "system", undefined, undefined, undefined, {
+        unsafeRaw: { reason: "test: job context mirrors systemScope() grant" },
+      }),
+    ),
     registry: stack.registry,
     masterKeyProvider: mutableProvider,
     configEncryption: racyCipher,
     log,
-  } as unknown as Parameters<typeof reencryptJob>[1]; // @cast-boundary test-seam — job only reads db/registry/masterKeyProvider/configEncryption/log
+    // Without a sink, the job's escape-hatch reporter warn-logs through `log` and its
+    // report is deduped by the framework's process-wide window (escape-hatch-report.ts),
+    // so whether the unconditional per-run scan ack reaches `log.warn` here depends on
+    // unrelated sibling tests' order in the same process. A sink (mirrors production,
+    // where the audit feature wires one) routes that report away from `log` entirely,
+    // isolating this test from that shared window.
+    _escapeHatchAuditSink: async () => {},
+  } as unknown as Parameters<typeof reencryptJob>[1]; // @cast-boundary test-seam — job only reads db/registry/masterKeyProvider/configEncryption/log/_escapeHatchAuditSink
 }
 
 beforeAll(async () => {

package/src/config/__tests__/reencrypt-job-kek-rotation.integration.test.ts

@@ -12,8 +12,8 @@ import { randomBytes } from "node:crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   createEventStoreExecutor,
+  createSystemDbView,
   createTenantDb,
-  createUncheckedSystemDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
@@ -138,10 +138,18 @@ function capturingLog(captured: CapturedLog): TestJobLog {
 
 function jobCtx(captured?: CapturedLog): Parameters<typeof reencryptJob>[1] {
   const log = captured ? capturingLog(captured) : noopLog;
-  const systemModeDb = createTenantDb(stack.db, SYSTEM_TENANT_ID, "system");
+  const systemModeDb = createTenantDb(
+    stack.db,
+    SYSTEM_TENANT_ID,
+    "system",
+    undefined,
+    undefined,
+    undefined,
+    { unsafeRaw: { reason: "test: job context mirrors systemScope() grant" } },
+  );
   return {
     db: systemModeDb,
-    systemDb: createUncheckedSystemDb(systemModeDb),
+    systemDb: createSystemDbView(systemModeDb),
     registry: stack.registry,
     masterKeyProvider: mutableProvider,
     configEncryption: cipher,

package/src/config/__tests__/reencrypt-job-tenant-checks.integration.test.ts

@@ -1,5 +1,5 @@
 // Regression guard for kumiko-framework#2072: the KEK-rotation job's
-// systemScope() fail-closed checks — createUncheckedSystemDb().
+// systemScope() fail-closed checks — createSystemDbView().
 // acknowledgeCrossTenant() gating the initial cross-tenant scan,
 // assertRowsTenant() re-verifying each per-tenant slice before it's served
 // to the write loop — must not block legitimate multi-tenant rotation. A
@@ -14,8 +14,8 @@ import { randomBytes } from "node:crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   createEventStoreExecutor,
+  createSystemDbView,
   createTenantDb,
-  createUncheckedSystemDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
@@ -117,7 +117,11 @@ function capturingLog(captured: CapturedLog): TestJobLog {
 function jobCtx(captured: CapturedLog): Parameters<typeof reencryptJob>[1] {
   return {
     db: createTenantDb(stack.db, SYSTEM_TENANT_ID),
-    systemDb: createUncheckedSystemDb(createTenantDb(stack.db, SYSTEM_TENANT_ID, "system")),
+    systemDb: createSystemDbView(
+      createTenantDb(stack.db, SYSTEM_TENANT_ID, "system", undefined, undefined, undefined, {
+        unsafeRaw: { reason: "test: job context mirrors systemScope() grant" },
+      }),
+    ),
     registry: stack.registry,
     masterKeyProvider: mutableProvider,
     configEncryption: cipher,

package/src/config/__tests__/require-system-db.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, test } from "bun:test";
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { createUncheckedSystemDb } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemDbView } from "@cosmicdrift/kumiko-framework/db";
 import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
 import { requireSystemDb } from "../feature";
 
 // Minimal TenantDb stub — only .tenantId is read by assertTenantMatch /
-// createUncheckedSystemDb; the real db-query methods are never called by
+// createSystemDbView; the real db-query methods are never called by
 // requireSystemDb itself.
 function fakeTenantDb(tenantId: TenantId): TenantDb {
   return { tenantId, mode: "system" } as unknown as TenantDb;
@@ -16,7 +16,7 @@ function fakeTenantDb(tenantId: TenantId): TenantDb {
 function contextStub(db: TenantDb, withSystemDb: boolean): HandlerContext {
   return {
     db,
-    systemDb: withSystemDb ? createUncheckedSystemDb(db) : undefined,
+    systemDb: withSystemDb ? createSystemDbView(db) : undefined,
     // biome-ignore lint/suspicious/noExplicitAny: rest of HandlerContext isn't touched by requireSystemDb.
   } as any;
 }

package/src/config/handlers/reencrypt.job.ts

@@ -21,12 +21,12 @@
 // UncheckedSystemDb.acknowledgeCrossTenant(). Rows are bucketed by tenant,
 // and assertRowsTenant() re-verifies each row against its bucket's tenant
 // right before the write — both checks are built locally from the exported
-// createUncheckedSystemDb().
+// createSystemDbView().
 
 import {
   createEventStoreExecutor,
+  createSystemDbView,
   createTenantDb,
-  createUncheckedSystemDb,
   type DbConnection,
   type TenantDb,
   type UncheckedSystemDb,
@@ -135,11 +135,7 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   function sdbFor(tenantId: TenantId): UncheckedSystemDb {
     let existing = sdbCache.get(tenantId);
     if (!existing) {
-      existing = createUncheckedSystemDb(
-        tdbFor(tenantId),
-        undefined,
-        reportEscapeHatchFor(tenantId),
-      );
+      existing = createSystemDbView(tdbFor(tenantId), undefined, reportEscapeHatchFor(tenantId));
       sdbCache.set(tenantId, existing);
     }
     return existing;
@@ -149,7 +145,7 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   // to acknowledge the cross-tenant scan below, never bound to a real
   // tenant's writes — sharing it with sdbFor(SYSTEM_TENANT_ID) would make a
   // write-path cache entry double as the scan's ack gate.
-  const scanDb = createUncheckedSystemDb(
+  const scanDb = createSystemDbView(
     createTenantDb(db, SYSTEM_TENANT_ID, "system"),
     undefined,
     reportEscapeHatchFor(SYSTEM_TENANT_ID),

package/src/custom-fields/db/queries/__tests__/{unsafe-read-retrying.test.ts → unsafe-read-retrying.integration.test.ts}

@@ -1,32 +1,33 @@
-// #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.
+// field-access.ts, quota.ts, user-data-rights.ts and retention.ts read
+// custom-field rows through unsafeReadRetrying; this proves the retry fires
+// per call site using a real captured driver error. applyRetentionRemovals
+// (an UPDATE) stays out of scope — unretried by design.
 
-import { describe, expect, test } from "bun:test";
+import { beforeAll, describe, expect, test } from "bun:test";
+import { captureClosedConnectionError } from "@cosmicdrift/kumiko-framework/testing";
 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" });
-}
+let closedConnectionError: unknown;
+
+beforeAll(async () => {
+  closedConnectionError = await captureClosedConnectionError();
+});
 
 type FakeClient = {
   unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
   begin: () => never;
+  options: { max: number };
   calls: number;
 };
 
-function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient {
+function fakeClient(failures: unknown[], row: Record<string, unknown>): FakeClient {
   const remaining = [...failures];
   const client: FakeClient = {
     calls: 0,
+    options: { max: 1 },
     unsafe: async () => {
       client.calls++;
       const err = remaining.shift();
@@ -40,30 +41,30 @@ function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient
   return client;
 }
 
-describe("custom-fields db/queries — closed-connection retry (#2323)", () => {
+describe("custom-fields db/queries — closed-connection retry", () => {
   test("selectSerializedFieldDefinition retries once through db.unsafeRaw and returns the row", async () => {
-    const raw = fakeClient([closedConnectionError()], { serialized_field: "sf1" });
+    const raw = fakeClient([closedConnectionError], { serialized_field: "sf1" });
     const result = await selectSerializedFieldDefinition(raw, "t1", "entity", "field");
     expect(result).toBe("sf1");
     expect(raw.calls).toBe(2);
   });
 
   test("countTenantFieldDefinitions retries once through db.unsafeRaw and returns the count", async () => {
-    const raw = fakeClient([closedConnectionError()], { n: 3 });
+    const raw = fakeClient([closedConnectionError], { n: 3 });
     const result = await countTenantFieldDefinitions(raw, "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 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 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");
@@ -71,7 +72,7 @@ describe("custom-fields db/queries — closed-connection retry (#2323)", () => {
   });
 
   test("selectHostRowsWithCustomFields retries once and returns rows", async () => {
-    const db = fakeClient([closedConnectionError()], {
+    const db = fakeClient([closedConnectionError], {
       id: "1",
       modified_at: null,
       custom_fields: {},
@@ -81,13 +82,13 @@ describe("custom-fields db/queries — closed-connection retry (#2323)", () => {
     expect(db.calls).toBe(2);
   });
 
-  test("gives up after the single retry when the connection stays closed", async () => {
-    const raw = fakeClient([closedConnectionError(), closedConnectionError()], {
+  test("gives up after exhausting pool-bounded retries (max: 1 → 3 total calls)", async () => {
+    const raw = fakeClient([closedConnectionError, closedConnectionError, closedConnectionError], {
       serialized_field: "sf1",
     });
-    await expect(selectSerializedFieldDefinition(raw, "t1", "entity", "field")).rejects.toThrow(
-      "connection was closed",
+    await expect(selectSerializedFieldDefinition(raw, "t1", "entity", "field")).rejects.toBe(
+      closedConnectionError,
     );
-    expect(raw.calls).toBe(2);
+    expect(raw.calls).toBe(3);
   });
 });