@cosmicdrift/kumiko-framework 0.220.1 → 0.222.0

package/src/db/__tests__/migrate-generator.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import type { EntityTableMeta } from "../entity-table-meta";
 import {
+  assertValidMigrationName,
   diffSnapshots,
   generateMigration,
   renderMigrationSql,
@@ -197,3 +198,14 @@ describe("renderMigrationSql — managed recreate vs unmanaged in-place", () =>
     expect(sql).toContain("new NOT NULL column(s) without default: envelope");
   });
 });
+
+describe("assertValidMigrationName", () => {
+  test("accepts alphanumeric hyphenated names", () => {
+    expect(() => assertValidMigrationName("add-user-table")).not.toThrow();
+  });
+
+  test("rejects leading hyphen and oversized names", () => {
+    expect(() => assertValidMigrationName("-foo")).toThrow(/Invalid migration name/);
+    expect(() => assertValidMigrationName(`a${"x".repeat(64)}`)).toThrow(/Invalid migration name/);
+  });
+});

package/src/db/__tests__/multi-row-insert.integration.test.ts

@@ -9,6 +9,7 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { Temporal } from "temporal-polyfill";
 import { selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField } from "../../engine";
@@ -61,6 +62,7 @@ describe("instant() customType is forgiving with ISO strings", () => {
     expect(rows).toHaveLength(1);
     const insertedAt = rows[0]?.["insertedAt"];
     expect(insertedAt).toBeDefined();
+    expect(insertedAt).toBeInstanceOf(Temporal.Instant);
     expect((insertedAt as Temporal.Instant).toString()).toBe(isoString);
   });
 });

package/src/db/__tests__/schema-migration.integration.test.ts

@@ -314,6 +314,7 @@ describe("date field — real DATE column, no TZ dependence (kumiko-framework#19
     const rows = await selectMany(testDb.db, table);
     expect(rows).toHaveLength(1);
     const periodFrom = (rows[0] as { periodFrom: unknown }).periodFrom;
+    expect(periodFrom).toBeInstanceOf(Temporal.PlainDate);
     expect((periodFrom as Temporal.PlainDate).toString()).toBe("2026-03-15");
   });
 

package/src/db/__tests__/source-shadow-create.integration.test.ts

@@ -13,6 +13,7 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { Temporal } from "temporal-polyfill";
 import { selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField } from "../../engine";
@@ -52,6 +53,7 @@ describe("entity with a `source` field — create-path is shadow-proof", () => {
     expect(rows[0]?.["source"]).toBe("import");
     const insertedAt = rows[0]?.["insertedAt"];
     expect(insertedAt).toBeDefined();
+    expect(insertedAt).toBeInstanceOf(Temporal.Instant);
     expect((insertedAt as Temporal.Instant).toString()).toBe("2026-01-15T12:00:00Z");
   });
 });

package/src/db/__tests__/table-builder-meta-lockstep.test.ts

@@ -160,3 +160,32 @@ describe("lock-step — lookupable / blind-index (#818)", () => {
     expect(partial?.whereSql).toBe('"email_bidx" IS NOT NULL');
   });
 });
+
+// Fourth probe: softDelete + lookupable (#2464) — the partial bidx unique
+// must exclude soft-deleted rows from the uniqueness scope, otherwise a
+// soft-deleted row blocks the same value for a new/restored row.
+const entityWithSoftDeleteAndLookupable = createEntity({
+  table: "read_lockstep_probe_bidx_sd",
+  fields: {
+    email: { type: "text", required: true, pii: true, lookupable: true },
+    tenantSlug: { type: "text", required: true },
+  },
+  softDelete: true,
+  indexes: [{ columns: ["tenantSlug", "email"], unique: true }],
+});
+
+describe("lock-step — softDelete + lookupable/blind-index (#2464)", () => {
+  const fromBuilder = asEntityTableMeta(
+    buildEntityTable("lockstepProbeBidxSd", entityWithSoftDeleteAndLookupable),
+  );
+  const fromMeta = deriveEntityTableMeta("lockstepProbeBidxSd", entityWithSoftDeleteAndLookupable);
+
+  test("identical indexes incl. soft-delete-aware bidx partial where", () => {
+    expect(byName<IndexMeta>(fromBuilder?.indexes ?? [])).toEqual(
+      byName<IndexMeta>(fromMeta.indexes),
+    );
+    const partial = fromMeta.indexes.find((i) => i.name.endsWith("_tenant_slug_email_unique_bidx"));
+    expect(partial).toBeDefined();
+    expect(partial?.whereSql).toBe('"email_bidx" IS NOT NULL AND "is_deleted" = false');
+  });
+});

package/src/db/blind-index-cleanup.ts

@@ -13,11 +13,12 @@
 
 import { collectLookupableFields } from "../crypto/blind-index";
 import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-pattern";
+import { isSelfPiiField } from "../crypto/is-self-pii-field";
 import type { FeatureDefinition } from "../engine/types";
 import { toSnakeCase } from "../utils/case";
 import type { DbRunner } from "./connection";
 import { resolveTableName } from "./entity-table-meta";
-import { executeRawQuery } from "./queries/raw-sql";
+import { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql";
 
 export async function nullBlindIndexesForSubject(
   db: DbRunner,
@@ -47,38 +48,54 @@ export async function nullBlindIndexesForSubject(
 
 // Tenant-scope oracle for crypto-shredding's forget-subject (mh#349): a
 // "user"-kind subject id is often not a real user (share-token recipient,
-// email subscriber, ...) — those entities self-own their PII (`personal:
-// "self"`, i.e. their own row id IS the subject) and carry a real tenant_id,
+// email subscriber, ...) — those entities self-own their PII (`pii: true`,
+// i.e. their own row id IS the subject) and carry a real tenant_id,
 // unlike read_users (systemStream, tenant_id always SYSTEM_TENANT_ID). This
 // checks whether the subject row lives in the given tenant, so a tenant-
 // scoped DPO can still forget subjects it truly owns without needing a
 // tenant-membership row (which only exists for real users).
+//
+// Invariant: `id` must never be client-settable on self-PII entities — the
+// framework create path strips client ids; app write paths MUST do the same
+// or a DPO could plant a foreign subject id in their tenant and pass this
+// oracle (#2348). Upgrade path: require an event-store provenance check
+// (`aggregate_id = subjectId` under the actor tenant) when apps need
+// client-supplied ids.
 export async function subjectRowExistsInTenant(
   db: DbRunner,
   features: ReadonlyMap<string, FeatureDefinition>,
   subjectId: string,
   tenantId: string,
 ): Promise<boolean> {
+  // Prefetch which self-PII projection tables actually exist — probing a
+  // missing relation used to throw (and get swallowed), which both hid
+  // real schema bugs and risked poisoning the Bun.SQL connection for the
+  // rest of the forget TX (fw#2348 / framework#356).
+  const candidateTables: string[] = [];
   for (const feature of features.values()) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
-      const hasSelfPiiField = Object.values(entity.fields).some(
-        (field) => "pii" in field && field.pii === true,
-      );
+      const hasSelfPiiField = Object.values(entity.fields).some(isSelfPiiField);
       if (!hasSelfPiiField) continue;
-      const tableName = resolveTableName(entityName, entity, undefined);
-      try {
-        const rows = await executeRawQuery(
-          db,
-          `SELECT 1 FROM ${quoteIdent(tableName)} WHERE id = $1 AND tenant_id = $2 LIMIT 1`,
-          [subjectId, tenantId],
-        );
-        if (rows.length > 0) return true;
-      } catch {
-        // Table missing, id-type mismatch, ... — not evidence the subject is
-        // owned here. Fail-closed must come from an honest "not found" across
-        // every entity, never from a query blowing up on one of them.
-      }
+      candidateTables.push(resolveTableName(entityName, entity, undefined));
     }
   }
+  const existing = new Set<string>();
+  for (const tableName of candidateTables) {
+    const rows = await executeRawQueryRead<{ exists: boolean }>(
+      db,
+      `SELECT to_regclass(quote_ident($1)) IS NOT NULL AS exists`,
+      [tableName],
+    );
+    if (rows[0]?.exists === true) existing.add(tableName);
+  }
+  for (const tableName of candidateTables) {
+    if (!existing.has(tableName)) continue;
+    const rows = await executeRawQueryRead(
+      db,
+      `SELECT 1 FROM ${quoteIdent(tableName)} WHERE id = $1 AND tenant_id = $2 LIMIT 1`,
+      [subjectId, tenantId],
+    );
+    if (rows.length > 0) return true;
+  }
   return false;
 }

package/src/db/entity-table-meta.ts

@@ -356,11 +356,16 @@ export function deriveEntityTableMeta(
         const notNullParts = bidxCols
           .filter((c, i) => c !== cols[i])
           .map((c) => `"${c}" IS NOT NULL`);
+        // Soft-deleted rows keep their bidx hash — without this, a restored
+        // row can't reuse a value a soft-deleted sibling still holds
+        // (framework#2464). Kept in lock-step with table-builder.ts.
+        const whereParts =
+          entity.softDelete === true ? [...notNullParts, `"is_deleted" = false`] : notNullParts;
         indexes.push({
           name: `${indexName}_bidx`,
           columns: bidxCols,
           unique: true,
-          whereSql: notNullParts.join(" AND "),
+          whereSql: whereParts.join(" AND "),
         });
       }
     }

package/src/db/event-store-executor-context.ts

@@ -8,7 +8,7 @@ import {
   type KmsContext,
   type LocalKeyKmsAdapter,
 } from "../crypto";
-import { executeRawQuery } from "../db/queries/raw-sql";
+import { executeRawQueryRead } from "../db/queries/raw-sql";
 import type { WhereObject } from "../db/query";
 import { shiftParams } from "../engine/ownership";
 import type {
@@ -381,7 +381,7 @@ export function buildExecutorContext(
     whereParts.push(shifted.sqlText);
     for (const p of shifted.params) params.push(p);
     const sqlText = `SELECT * FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
-    return [...(await executeRawQuery<Record<string, unknown>>(db.raw, sqlText, params))];
+    return [...(await executeRawQueryRead<Record<string, unknown>>(db.raw, sqlText, params))];
   }
 
   return {

package/src/db/event-store-executor-read.ts

@@ -1,6 +1,6 @@
 import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto";
-import { executeRawQuery } from "../db/queries/raw-sql";
+import { executeRawQueryRead } from "../db/queries/raw-sql";
 import { coerceRow, extractTableInfo } from "../db/query";
 import { buildOwnershipClause, shiftParams } from "../engine/ownership";
 import type { EntityId } from "../engine/types";
@@ -138,9 +138,10 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
             },
           });
         }
-        // system-mode lists (r.systemScope / cross-tenant) index under SYSTEM_TENANT_ID;
-        // searching the caller's session tenant misses the roster and can 500 on Meili.
-        const searchTenantId = db.mode === "system" ? SYSTEM_TENANT_ID : user.tenantId;
+        // Same choke-point as writes/index: systemStream docs live under
+        // SYSTEM_TENANT_ID; everything else under the session tenant — db.mode
+        // must not invent a second predicate (kumiko-framework#2412).
+        const searchTenantId = streamTenantFor(user);
         const results = await effectiveSearchAdapter.search(searchTenantId, payload.search, {
           filterType: entityName,
         });
@@ -275,7 +276,7 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
       const whereClauseSqlText = whereSql.length > 0 ? ` WHERE ${whereSql.join(" AND ")}` : "";
       const listSql = `SELECT * FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
 
-      const rawRows = await executeRawQuery<Record<string, unknown>>(db.raw, listSql, params);
+      const rawRows = await executeRawQueryRead<Record<string, unknown>>(db.raw, listSql, params);
       // Per-row read-side rehydrate + snake→camel coercion for driver-agnostic field names.
       // Coerce BEFORE rehydrate/decrypt: the raw SELECT * rows carry snake_case
       // column names, while compound-type lookups (rehydrateMoney et al.) and the
@@ -321,7 +322,7 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
           total = filterIds.length;
         } else {
           const countSql = `SELECT COUNT(*)::int AS count FROM "${tableName}"${whereClauseSqlText}`;
-          const countRows = await executeRawQuery<{ count: number }>(db.raw, countSql, params);
+          const countRows = await executeRawQueryRead<{ count: number }>(db.raw, countSql, params);
           total = countRows[0]?.count ?? 0;
         }
       }

package/src/db/event-store-executor-write.ts

@@ -18,7 +18,7 @@ import {
 import { generateId } from "../utils";
 import { applyEntityEvent } from "./apply-entity-event";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
-import type { DbRow, DbRunner } from "./connection";
+import type { DbRow } from "./connection";
 import type { EventStoreExecutor } from "./event-store-executor";
 import {
   buildEventMetadata,
@@ -200,8 +200,8 @@ export function createWriteVerbs(
         // its own (same pattern as ctx.tryAppendEvent), and falls back to a
         // plain call when db.raw is a bare pool connection with no active
         // transaction to poison (seeds/tests calling the executor directly).
-        event = await runInSavepointIfSupported(db.raw, (sp) =>
-          append(sp as DbRunner, {
+        event = await runInSavepointIfSupported(db.raw, async (sp) =>
+          append(sp, {
             aggregateId,
             aggregateType: entityName,
             tenantId: streamTenantFor(user),
@@ -251,8 +251,8 @@ export function createWriteVerbs(
       // failed INSERT back; the error still propagates and stays catchable.
       let result: Awaited<ReturnType<typeof applyEntityEvent>>;
       try {
-        result = await runInSavepointIfSupported(db.raw, (sp) =>
-          applyEntityEvent(event, table, entity, sp as DbRunner),
+        result = await runInSavepointIfSupported(db.raw, async (sp) =>
+          applyEntityEvent(event, table, entity, sp),
         );
       } catch (e) {
         const mapped = tryMapUniqueViolation(e, entityName);
@@ -429,7 +429,7 @@ export function createWriteVerbs(
         // confines a losing writer's unique-violation to a nested scope
         // instead of poisoning the whole outer transaction.
         const event = await runInSavepointIfSupported(db.raw, (sp) =>
-          append(sp as DbRunner, {
+          append(sp, {
             aggregateId: String(payload.id),
             aggregateType: entityName,
             tenantId: streamTenantFor(user),
@@ -456,8 +456,8 @@ export function createWriteVerbs(
         // failed nested one throws 500 instead of failing cleanly.
         let result: Awaited<ReturnType<typeof applyEntityEvent>>;
         try {
-          result = await runInSavepointIfSupported(db.raw, (sp) =>
-            applyEntityEvent(event, table, entity, sp as DbRunner),
+          result = await runInSavepointIfSupported(db.raw, async (sp) =>
+            applyEntityEvent(event, table, entity, sp),
           );
         } catch (e) {
           const mapped = tryMapUniqueViolation(e, entityName);
@@ -552,26 +552,38 @@ export function createWriteVerbs(
       // to rebuild from the event log alone. `existing` came from loadById(),
       // which decrypts — re-encrypt before persisting so plaintext doesn't
       // land in the immutable log.
-      const event = await append(db.raw, {
-        aggregateId: String(payload.id),
-        aggregateType: entityName,
-        tenantId: streamTenantFor(user),
-        expectedVersion: currentVersion,
-        type: entityEventName(entityName, "deleted"),
-        payload: { previous: await encryptForStorage(existing, user) },
-        metadata: buildEventMetadata(user),
-      });
+      let event: Awaited<ReturnType<typeof append>>;
+      try {
+        event = await runInSavepointIfSupported(db.raw, async (sp) =>
+          append(sp, {
+            aggregateId: String(payload.id),
+            aggregateType: entityName,
+            tenantId: streamTenantFor(user),
+            expectedVersion: currentVersion,
+            type: entityEventName(entityName, "deleted"),
+            payload: { previous: await encryptForStorage(existing, user) },
+            metadata: buildEventMetadata(user),
+          }),
+        );
+      } catch (e) {
+        if (e instanceof EventStoreVersionConflict) {
+          return writeFailure(
+            new FrameworkVersionConflict({
+              entityId: payload.id,
+              expectedVersion: currentVersion,
+              currentVersion: -1,
+            }),
+          );
+        }
+        if (e instanceof EventStoreIdempotentAppendConflict) {
+          return writeFailure(new IdempotentReplayError({ idempotencyKey: e.idempotencyKey }));
+        }
+        throw e;
+      }
 
-      // Live==Rebuild via applyEntityEvent. Delete-Operation hat keine
-      // sensitive-Drift weil das Event-Payload nur `previous` ist und das
-      // wird vom soft/hard-delete-Code gar nicht in die Tabelle geschrieben
-      // (nur isDeleted/deletedAt/version-Bump). Live + Replay schreiben
-      // dasselbe — kein payload-override nötig.
-      // Savepoint like the create/update paths: a raw DB error out of the
-      // projection delete poisons the enclosing tx otherwise, surfacing as a
-      // 500 on the next write that shares it rather than a clean failure.
-      const deleteResult = await runInSavepointIfSupported(db.raw, (sp) =>
-        applyEntityEvent(event, table, entity, sp as DbRunner),
+      // Live==Rebuild via applyEntityEvent. Savepoint like create/update.
+      const deleteResult = await runInSavepointIfSupported(db.raw, async (sp) =>
+        applyEntityEvent(event, table, entity, sp),
       );
       if (deleteResult.kind !== "applied") {
         return writeFailure(
@@ -626,19 +638,40 @@ export function createWriteVerbs(
         streamTenantFor(user),
       );
 
-      const event = await append(db.raw, {
-        aggregateId: String(payload.id),
-        aggregateType: entityName,
-        tenantId: streamTenantFor(user),
-        expectedVersion: currentVersion,
-        type: entityEventName(entityName, "forgotten"),
-        // Re-encrypt like delete(): `existing` came decrypted from loadById —
-        // plaintext must not land in the immutable log, least of all on forget.
-        payload: { previous: await encryptForStorage(existing, user) },
-        metadata: buildEventMetadata(user),
-      });
+      let event: Awaited<ReturnType<typeof append>>;
+      try {
+        event = await runInSavepointIfSupported(db.raw, async (sp) =>
+          append(sp, {
+            aggregateId: String(payload.id),
+            aggregateType: entityName,
+            tenantId: streamTenantFor(user),
+            expectedVersion: currentVersion,
+            type: entityEventName(entityName, "forgotten"),
+            // Re-encrypt like delete(): `existing` came decrypted from loadById —
+            // plaintext must not land in the immutable log, least of all on forget.
+            payload: { previous: await encryptForStorage(existing, user) },
+            metadata: buildEventMetadata(user),
+          }),
+        );
+      } catch (e) {
+        if (e instanceof EventStoreVersionConflict) {
+          return writeFailure(
+            new FrameworkVersionConflict({
+              entityId: payload.id,
+              expectedVersion: currentVersion,
+              currentVersion: -1,
+            }),
+          );
+        }
+        if (e instanceof EventStoreIdempotentAppendConflict) {
+          return writeFailure(new IdempotentReplayError({ idempotencyKey: e.idempotencyKey }));
+        }
+        throw e;
+      }
 
-      const forgetResult = await applyEntityEvent(event, table, entity, db.raw);
+      const forgetResult = await runInSavepointIfSupported(db.raw, async (sp) =>
+        applyEntityEvent(event, table, entity, sp),
+      );
       if (forgetResult.kind !== "applied") {
         return writeFailure(
           new InternalError({ message: "projection forget: applyEntityEvent skipped" }),
@@ -710,20 +743,41 @@ export function createWriteVerbs(
       // `previous` to re-increment on restore without re-querying the entity
       // table. `data` is the raw stored row — pii/encrypted fields are
       // already ciphertext, no re-encrypt needed.
-      const event = await append(db.raw, {
-        aggregateId: String(payload.id),
-        aggregateType: entityName,
-        tenantId: streamTenantFor(user),
-        expectedVersion: currentVersion,
-        type: entityEventName(entityName, "restored"),
-        payload: { previous: data },
-        metadata: buildEventMetadata(user),
-      });
+      let event: Awaited<ReturnType<typeof append>>;
+      try {
+        event = await runInSavepointIfSupported(db.raw, (sp) =>
+          append(sp, {
+            aggregateId: String(payload.id),
+            aggregateType: entityName,
+            tenantId: streamTenantFor(user),
+            expectedVersion: currentVersion,
+            type: entityEventName(entityName, "restored"),
+            payload: { previous: data },
+            metadata: buildEventMetadata(user),
+          }),
+        );
+      } catch (e) {
+        if (e instanceof EventStoreVersionConflict) {
+          return writeFailure(
+            new FrameworkVersionConflict({
+              entityId: payload.id,
+              expectedVersion: currentVersion,
+              currentVersion: -1,
+            }),
+          );
+        }
+        if (e instanceof EventStoreIdempotentAppendConflict) {
+          return writeFailure(new IdempotentReplayError({ idempotencyKey: e.idempotencyKey }));
+        }
+        throw e;
+      }
 
       // Live==Rebuild via applyEntityEvent. Restore schreibt nur isDeleted=
       // false + version-Bump in die Tabelle — keine sensitive-Drift, daher
       // kein payload-override nötig.
-      const restoreResult = await applyEntityEvent(event, table, entity, db.raw);
+      const restoreResult = await runInSavepointIfSupported(db.raw, async (sp) =>
+        applyEntityEvent(event, table, entity, sp),
+      );
       if (restoreResult.kind !== "applied" || restoreResult.row === null) {
         return writeFailure(new InternalError({ message: "projection restore returned no row" }));
       }

package/src/db/index.ts

@@ -76,6 +76,7 @@ export {
 } from "./feature-table-sources";
 export { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp";
 export {
+  assertValidMigrationName,
   diffSnapshots,
   type GenerateMigrationInput,
   type GenerateMigrationOutput,
@@ -109,6 +110,7 @@ export {
   type PgErrorInfo,
 } from "./pg-error";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock";
+export { executeRawQuery } from "./queries/raw-sql";
 export type { SelectOptions, WhereObject, WhereValue } from "./query-api";
 export {
   asRawClient,

package/src/db/migrate-generator.ts

@@ -415,7 +415,21 @@ export type GenerateMigrationOutput = {
   readonly diff: SchemaDiff;
 };
 
+// Shared allowlist for migration names — used by the CLI and by
+// generateMigration so a programmatic caller cannot skip the check and
+// smuggle path segments / newlines into the filename or SQL header.
+export const MIGRATION_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+
+export function assertValidMigrationName(name: string): void {
+  if (!MIGRATION_NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid migration name "${name}" — must start with a letter or digit, then letters/digits/"-"/"_" only (max 64 chars).`,
+    );
+  }
+}
+
 export function generateMigration(input: GenerateMigrationInput): GenerateMigrationOutput {
+  assertValidMigrationName(input.name);
   const nextSnapshot = snapshotFromMetas(input.metas);
   const diff = diffSnapshots(input.prevSnapshot, nextSnapshot);
   const sqlContent = renderMigrationSql(diff, {

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

@@ -26,18 +26,23 @@ function closedConnectionError(): Error {
   return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
 }
 
+type RecordedCall = { readonly sql: string; readonly params: readonly unknown[] | undefined };
+
 type FakeClient = {
   unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
   begin: () => never;
   calls: number;
+  recordedCalls: RecordedCall[];
 };
 
 function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient {
   const remaining = [...failures];
   const client: FakeClient = {
     calls: 0,
-    unsafe: async () => {
+    recordedCalls: [],
+    unsafe: async (sql, params) => {
       client.calls++;
+      client.recordedCalls.push({ sql, params });
       const err = remaining.shift();
       if (err) throw err;
       return [row];
@@ -55,6 +60,8 @@ describe("framework db/queries — closed-connection retry (#2323)", () => {
     const result = await selectStreamMaxVersion(db as never, "agg1", "t1");
     expect(result).toBe(5);
     expect(db.calls).toBe(2);
+    expect(db.recordedCalls).toHaveLength(2);
+    expect(db.recordedCalls[0]).toEqual(db.recordedCalls[1]);
   });
 
   test("selectAggregateMaxVersion retries once and returns the version", async () => {

package/src/db/queries/backfill-pii.ts

@@ -40,8 +40,13 @@
 import { asRawClient } from "../../bun-db";
 import { quoteIdent } from "../../crypto/ciphertext-pattern";
 import { configuredEventPiiCatalog } from "../../crypto/event-pii";
-import type { KmsContext, LocalKeyKmsAdapter, SubjectId } from "../../crypto/kms-adapter";
-import { KeyErasedError, KeyNotFoundError } from "../../crypto/kms-adapter";
+import {
+  isLocalKeyKmsAdapter,
+  KeyErasedError,
+  KeyNotFoundError,
+  type KmsContext,
+  type SubjectId,
+} from "../../crypto/kms-adapter";
 import {
   configuredPiiSubjectKms,
   encryptPiiValueForSubject,
@@ -117,6 +122,10 @@ export async function backfillEventPiiEncryption(
         "runProdApp({ kms }) / configurePiiSubjectKms(adapter) before running the backfill.",
     );
   }
+  if (!isLocalKeyKmsAdapter(kms)) {
+    throw new Error("backfillEventPiiEncryption requires a local-key KMS adapter");
+  }
+  const subjectKms = kms;
   const batchSize = options.batchSize ?? 500;
   const raw = asRawClient(db);
   const kmsCtx: KmsContext = { requestId: "pii-backfill" };
@@ -353,13 +362,7 @@ export async function backfillEventPiiEncryption(
       }
       if (options.dryRun) return predictEncryptOutcome(subject);
       try {
-        section[field] = await encryptPiiValueForSubject(
-          kms as LocalKeyKmsAdapter,
-          subject,
-          value,
-          kmsCtx,
-          field,
-        );
+        section[field] = await encryptPiiValueForSubject(subjectKms, subject, value, kmsCtx, field);
         return "encrypted";
       } catch (e) {
         if (e instanceof KeyErasedError) {
@@ -376,7 +379,7 @@ export async function backfillEventPiiEncryption(
     // writing to the subject-keys store.
     async function predictEncryptOutcome(subject: SubjectId): Promise<FieldOutcome> {
       try {
-        await (kms as LocalKeyKmsAdapter).getKey(subject, kmsCtx);
+        await subjectKms.getKey(subject, kmsCtx);
         return "encrypted";
       } catch (e) {
         if (e instanceof KeyErasedError) return "erased";

package/src/db/queries/raw-sql.ts

@@ -1,7 +1,9 @@
 import type { AnyDb } from "../query";
-import { asRawClient } from "../query";
+import { asRawClient, unsafeReadRetrying } from "../query";
 
-/** Escape hatch for caller-built SQL (ownership clauses, entity list queries). */
+/** Escape hatch for caller-built SQL that may write (or lock). No closed-connection retry —
+ *  retrying an ambiguous write risks double-apply (#1358). Prefer {@link executeRawQueryRead}
+ *  for SELECT-only paths. */
 export async function executeRawQuery<T = Record<string, unknown>>(
   db: AnyDb,
   sqlText: string,
@@ -10,6 +12,16 @@ export async function executeRawQuery<T = Record<string, unknown>>(
   return (await asRawClient(db).unsafe(sqlText, params)) as readonly T[];
 }
 
+/** SELECT-only escape hatch with the #1163 closed-connection retry. Do not pass
+ *  INSERT/UPDATE/DELETE — retry re-executes the statement. */
+export async function executeRawQueryRead<T = Record<string, unknown>>(
+  db: AnyDb,
+  sqlText: string,
+  params: readonly unknown[] = [],
+): Promise<readonly T[]> {
+  return unsafeReadRetrying<T>(db, sqlText, params);
+}
+
 export async function pingDatabase(db: AnyDb): Promise<void> {
   await asRawClient(db).unsafe("SELECT 1");
 }