@cosmicdrift/kumiko-framework 0.249.0 → 0.251.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.249.0",
+  "version": "0.251.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,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.249.0",
+    "@cosmicdrift/kumiko-types": "0.251.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.249.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.251.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/full-stack.integration.test.ts

@@ -63,7 +63,9 @@ async function emitUserCreated(
 const userFeature = defineFeature("users", (r) => {
   const user = r.entity("user", userEntity);
 
-  const userCreated = r.defineEvent("user.created", z.object({ id: z.any(), email: z.string() }));
+  const userCreated = r.defineEvent("user.created", z.object({ id: z.any(), email: z.string() }), {
+    piiFields: "none",
+  });
   USER_CREATED_EVENT = userCreated.name;
 
   // r.multiStreamProjection: capture USER_CREATED_EVENT asynchronously via

package/src/crypto/__tests__/event-pii.test.ts

@@ -83,12 +83,34 @@ describe("defineEvent piiFields validation", () => {
     ).toThrow(/cannot use itself as subjectField/);
   });
 
-  test("events without piiFields do not enter the catalog", () => {
+  test("omitting the options argument throws an explicit PII stance error (fw#2558)", () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        // @cast-boundary test-only — the type signature makes `options`
+        // mandatory, but an untyped JS consumer can still omit it at
+        // runtime; the registrar must fail closed for that caller too.
+        (r.defineEvent as (name: string, schema: typeof attemptSchema) => unknown)(
+          "attempt",
+          attemptSchema,
+        );
+      }),
+    ).toThrow(/explicit PII stance/);
+  });
+
+  test('piiFields: {} throws, recommending piiFields: "none"', () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, { piiFields: {} });
+      }),
+    ).toThrow(/use piiFields: "none"/);
+  });
+
+  test('piiFields: "none" registers successfully and stays out of the catalog', () => {
     const feature = defineFeature("mailer", (r) => {
-      r.defineEvent("attempt", attemptSchema);
+      r.defineEvent("attempt", attemptSchema, { piiFields: "none" });
     });
     createRegistry([feature]);
-    expect(configuredEventPiiCatalog().size).toBe(0);
+    expect(configuredEventPiiCatalog().has(EVENT_TYPE)).toBe(false);
   });
 });
 

package/src/crypto/__tests__/kms-wiring.test.ts

@@ -95,7 +95,9 @@ describe("resolveKmsWiring", () => {
   test("falls back to plaintext PII when the trio is entirely absent", () => {
     const wiring = resolveKmsWiring({});
 
-    expect(wiring).toEqual({ allowPlaintextPii: "local dev without subject-keys KMS (fw#818)" });
+    expect("kms" in wiring).toBe(false);
+    if ("kms" in wiring) throw new Error("unreachable");
+    expect(wiring.allowPlaintextPii).toBe("local dev without subject-keys KMS (fw#818)");
   });
 
   // Regression: every member being optional made TypeScript's weak-type
@@ -111,7 +113,18 @@ describe("resolveKmsWiring", () => {
   test("carries an app-supplied fallback reason into the boot log", () => {
     const wiring = resolveKmsWiring({}, { plaintextReason: "solon pre-UI gate" });
 
-    expect(wiring).toEqual({ allowPlaintextPii: "solon pre-UI gate" });
+    expect("kms" in wiring).toBe(false);
+    if ("kms" in wiring) throw new Error("unreachable");
+    expect(wiring.allowPlaintextPii).toBe("solon pre-UI gate");
+  });
+
+  // fw#2551: an ops script must be able to release the subject-keys pool in a
+  // `finally` without knowing which branch it got — this compiles only while
+  // `close` sits on BOTH union members, and the plaintext branch must resolve
+  // rather than blow up on a wiring that opened nothing.
+  test("exposes close on both branches, callable without narrowing", async () => {
+    await expect(resolveKmsWiring({}).close()).resolves.toBeUndefined();
+    await expect(resolveKmsWiring(fullTrio).close()).resolves.toBeUndefined();
   });
 
   // All-or-none is the core of this module: a partial trio means someone

package/src/crypto/__tests__/pg-kms-adapter.integration.test.ts

@@ -3,6 +3,7 @@ import { randomBytes, randomUUID } from "node:crypto";
 import postgres from "postgres";
 import { createTestDb } from "../../stack/db";
 import { type KmsContext, type SubjectId, subjectIdToKey } from "../kms-adapter";
+import { resolveKmsWiring } from "../kms-wiring";
 import { PgKmsAdapter } from "../pg-kms-adapter";
 import { describeKmsAdapterContract } from "./kms-adapter-contract";
 
@@ -133,4 +134,21 @@ describe("PgKmsAdapter — pg specifics", () => {
     expect(rows[0]?.["erased_by"]).toBe("operator-1");
     expect(rows[0]?.["erase_reason"]).toBe("user-forget");
   });
+
+  // fw#2551: the pool resolveKmsWiring opens is what kept ops scripts from
+  // exiting. Proving release needs a pool that was genuinely open, so the
+  // health() before close is half the assertion.
+  test("resolveKmsWiring's close releases the pool it opened", async () => {
+    const wiring = resolveKmsWiring({
+      PLATFORM_KEK: platformKek,
+      SUBJECT_KEYS_DATABASE_URL: databaseUrl,
+      KUMIKO_BLIND_INDEX_KEY: "blind-index-key",
+    });
+    if (!("kms" in wiring)) throw new Error("unreachable");
+
+    expect((await wiring.kms.health()).ok).toBe(true);
+    await wiring.close();
+
+    await expect(wiring.kms.health()).rejects.toThrow();
+  });
 });

package/src/crypto/event-pii.ts

@@ -4,7 +4,13 @@
 // path at all. `r.defineEvent(name, schema, { piiFields })` declares which
 // payload fields are PII and which payload field names the owning user;
 // createRegistry publishes the catalog and append() — the single write funnel
-// into kumiko_events — encrypts every catalogued field. No caller can forget.
+// into kumiko_events — encrypts every catalogued field.
+//
+// `piiFields` is a mandatory, explicit stance (fw#2558): a payload can only
+// go uncatalogued through a declared `piiFields: "none"`, never by omission —
+// defineEvent refuses to register an event without one. What used to be a
+// silent no-op (forgetting the option) is now either an explicit "none" or a
+// missing subject KMS at encrypt-time, both visible states, not a gap.
 
 import { requestContext } from "../api/request-context";
 import type { EventPiiFields } from "../engine/types/handlers";

package/src/crypto/index.ts

@@ -39,6 +39,7 @@ export {
   type KmsWiring,
   type KmsWiringEnv,
   type KmsWiringOptions,
+  type KmsWiringRelease,
   type PgKmsRotationEnv,
   type PlaintextPiiWiring,
   requireKmsWiring,

package/src/crypto/kms-wiring.ts

@@ -33,14 +33,22 @@ export type PgKmsRotationEnv = KmsWiringEnv & {
   readonly SUBJECT_KEYS_DATABASE_URL: string;
 };
 
-export type ActiveKmsWiring = {
+/** Releases what the wiring opened. Present on BOTH branches (a no-op on the
+ *  plaintext fallback) so a short-lived process can `finally { await
+ *  wiring.close() }` without narrowing first. Skipping it leaves the adapter's
+ *  connection pool holding the event loop open and the process never exits —
+ *  a long-running server is supposed to hold it, every ops script is not
+ *  (fw#2551). */
+export type KmsWiringRelease = { readonly close: () => Promise<void> };
+
+export type ActiveKmsWiring = KmsWiringRelease & {
   readonly kms: PgKmsAdapter;
   readonly blindIndexKey: string;
 };
 
 /** Plaintext fallback carries its reason so the boot log says WHY PII is
  *  unencrypted — an app running like this by accident is a reportable breach. */
-export type PlaintextPiiWiring = { readonly allowPlaintextPii: string };
+export type PlaintextPiiWiring = KmsWiringRelease & { readonly allowPlaintextPii: string };
 
 export type KmsWiring = ActiveKmsWiring | PlaintextPiiWiring;
 
@@ -141,18 +149,23 @@ function assertTrioConsistent(env: KmsWiringEnv, logPrefix: string | undefined):
 export function resolveKmsWiring(env: KmsWiringEnv, options: KmsWiringOptions = {}): KmsWiring {
   const complete = assertTrioConsistent(env, options.logPrefix);
   if (complete && env.PLATFORM_KEK && env.SUBJECT_KEYS_DATABASE_URL && env.KUMIKO_BLIND_INDEX_KEY) {
+    const kms = createPgKmsAdapter(
+      buildPgKmsOptions({
+        ...env,
+        PLATFORM_KEK: env.PLATFORM_KEK,
+        SUBJECT_KEYS_DATABASE_URL: env.SUBJECT_KEYS_DATABASE_URL,
+      }),
+    );
     return {
-      kms: createPgKmsAdapter(
-        buildPgKmsOptions({
-          ...env,
-          PLATFORM_KEK: env.PLATFORM_KEK,
-          SUBJECT_KEYS_DATABASE_URL: env.SUBJECT_KEYS_DATABASE_URL,
-        }),
-      ),
+      kms,
       blindIndexKey: env.KUMIKO_BLIND_INDEX_KEY,
+      close: () => kms.close(),
     };
   }
-  return { allowPlaintextPii: options.plaintextReason ?? DEFAULT_PLAINTEXT_REASON };
+  return {
+    allowPlaintextPii: options.plaintextReason ?? DEFAULT_PLAINTEXT_REASON,
+    close: () => Promise.resolve(),
+  };
 }
 
 /** Same as `resolveKmsWiring` but the trio is mandatory — an absent trio throws

package/src/db/__tests__/event-store-executor-reference-sort.integration.test.ts

@@ -0,0 +1,258 @@
+// fw#2741 — a list sorted by a `sortable` reference field must order by the
+// target row's labelField, not by the FK column's UUID. The fixture pins three
+// mutually distinct orderings (label / own id / referenced UUID) so a passing
+// assertion can only come from the label expression, never from the column the
+// read path used to fall back to.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { asRawClient } from "../../db/query";
+import { createEntity, createTextField } from "../../engine";
+import type { EntityDefinition } from "../../engine/types";
+import { createEventsTable } from "../../event-store";
+import { TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { seedRows } from "../../testing";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb, type TenantDb } from "../tenant-db";
+
+const customerEntity = createEntity({
+  table: "read_ref_sort_customers",
+  fields: { name: createTextField({ required: true }) },
+});
+const customerTable = buildEntityTable("refSortCustomer", customerEntity);
+
+const orderEntity = createEntity({
+  table: "read_ref_sort_orders",
+  fields: {
+    note: createTextField(),
+    customerId: {
+      type: "reference",
+      entity: "refSortCustomer",
+      labelField: "name",
+      sortable: true,
+    },
+  },
+});
+const orderTable = buildEntityTable("refSortOrder", orderEntity);
+
+// Same shape, but the reference column is Admin-only: a caller who cannot read
+// the column must not be able to probe its target's label through the ordering
+// (fw#2629 parity — the read path gates sorting like projection).
+const restrictedOrderEntity = createEntity({
+  table: "read_ref_sort_restricted_orders",
+  fields: {
+    note: createTextField(),
+    customerId: {
+      type: "reference",
+      entity: "refSortCustomer",
+      labelField: "name",
+      sortable: true,
+      access: { read: { Admin: "all" } },
+    },
+  },
+});
+const restrictedOrderTable = buildEntityTable("refSortRestrictedOrder", restrictedOrderEntity);
+
+const CUSTOMER_MIKE = "11111111-1111-4111-8111-111111111111";
+const CUSTOMER_ALPHA = "22222222-2222-4222-8222-222222222222";
+const CUSTOMER_ZULU = "33333333-3333-4333-8333-333333333333";
+
+// Own ids ascend a < b < c while the labels they point at do not, so the three
+// candidate orderings are pairwise different:
+//   by label:            [orderC, orderB, orderA]  (Alpha, Mike, Zulu)
+//   by own id:           [orderA, orderB, orderC]
+//   by customerId UUID:  [orderB, orderC, orderA]  (1111…, 2222…, 3333…)
+const ORDER_A = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa";
+const ORDER_B = "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb";
+const ORDER_C = "cccccccc-cccc-4ccc-8ccc-cccccccccccc";
+
+function resolveEntity(name: string): EntityDefinition | undefined {
+  return name === "refSortCustomer" ? customerEntity : undefined;
+}
+
+const referenceSort = {
+  fields: [{ fieldName: "customerId", targetEntityName: "refSortCustomer", labelField: "name" }],
+  resolveEntity,
+};
+
+let testDb: BunTestDb;
+let tdbA: TenantDb;
+const admin = TestUsers.admin;
+const otherTenantAdmin = TestUsers.otherTenant;
+const orderExec = createEventStoreExecutor(orderTable, orderEntity, { entityName: "refSortOrder" });
+const restrictedOrderExec = createEventStoreExecutor(restrictedOrderTable, restrictedOrderEntity, {
+  entityName: "refSortRestrictedOrder",
+});
+
+async function seedFixture(): Promise<void> {
+  await seedRows(testDb.db, customerTable, [
+    { id: CUSTOMER_MIKE, tenantId: admin.tenantId, name: "Mike" },
+    { id: CUSTOMER_ALPHA, tenantId: admin.tenantId, name: "Alpha" },
+    { id: CUSTOMER_ZULU, tenantId: admin.tenantId, name: "Zulu" },
+  ]);
+  await seedRows(testDb.db, orderTable, [
+    { id: ORDER_A, tenantId: admin.tenantId, note: "a", customerId: CUSTOMER_ZULU },
+    { id: ORDER_B, tenantId: admin.tenantId, note: "b", customerId: CUSTOMER_MIKE },
+    { id: ORDER_C, tenantId: admin.tenantId, note: "c", customerId: CUSTOMER_ALPHA },
+  ]);
+}
+
+const idsOf = (rows: readonly Record<string, unknown>[]): unknown[] => rows.map((r) => r["id"]);
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, customerEntity, "refSortCustomer");
+  await unsafeCreateEntityTable(testDb.db, orderEntity, "refSortOrder");
+  await unsafeCreateEntityTable(testDb.db, restrictedOrderEntity, "refSortRestrictedOrder");
+  await createEventsTable(testDb.db);
+  tdbA = createTenantDb(testDb.db, admin.tenantId);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    "TRUNCATE kumiko_events, read_ref_sort_customers, read_ref_sort_orders, " +
+      "read_ref_sort_restricted_orders RESTART IDENTITY CASCADE",
+  );
+});
+
+describe("event-store-executor.list — sortable reference fields (fw#2741)", () => {
+  test("orders ascending by the target row's label, not by the FK UUID", async () => {
+    await seedFixture();
+
+    const res = await orderExec.list({ sort: "customerId", sortDirection: "asc" }, admin, tdbA, {
+      referenceSort,
+    });
+
+    expect(idsOf(res.rows)).toEqual([ORDER_C, ORDER_B, ORDER_A]);
+  });
+
+  test("orders descending by the target row's label", async () => {
+    await seedFixture();
+
+    const res = await orderExec.list({ sort: "customerId", sortDirection: "desc" }, admin, tdbA, {
+      referenceSort,
+    });
+
+    expect(idsOf(res.rows)).toEqual([ORDER_A, ORDER_B, ORDER_C]);
+  });
+
+  test("does not leak the sort-label projection into the returned rows", async () => {
+    await seedFixture();
+
+    const res = await orderExec.list({ sort: "customerId" }, admin, tdbA, { referenceSort });
+
+    for (const row of res.rows) {
+      expect(Object.keys(row)).not.toContain("__kumiko_sort_label");
+    }
+  });
+
+  test("pages through the label order with a keyset cursor, no gaps or repeats", async () => {
+    await seedFixture();
+
+    const page1 = await orderExec.list(
+      { sort: "customerId", sortDirection: "asc", limit: 2, totalCount: true },
+      admin,
+      tdbA,
+      { referenceSort },
+    );
+    expect(idsOf(page1.rows)).toEqual([ORDER_C, ORDER_B]);
+    expect(page1.total).toBe(3);
+    expect(page1.nextCursor).not.toBeNull();
+
+    const page2 = await orderExec.list(
+      {
+        sort: "customerId",
+        sortDirection: "asc",
+        limit: 2,
+        cursor: page1.nextCursor as string,
+        totalCount: true,
+      },
+      admin,
+      tdbA,
+      { referenceSort },
+    );
+    expect(idsOf(page2.rows)).toEqual([ORDER_A]);
+    // totalCount counts the same WHERE the page used, so a cursored page counts
+    // what is left. The assertion that matters here is that it answers at all:
+    // the count binds only the WHERE params while ORDER BY now adds its own,
+    // and Postgres rejects a statement handed more parameters than it uses.
+    expect(page2.total).toBe(1);
+  });
+
+  test("a target row in a foreign tenant contributes no label and sorts last", async () => {
+    await seedFixture();
+    const foreignCustomer = "44444444-4444-4444-8444-444444444444";
+    await seedRows(testDb.db, customerTable, [
+      // Reference UUIDs carry no FK constraint, so a tenant-A row can point at
+      // a tenant-B target. The tenant-scoped lookup must not resolve it —
+      // otherwise "AAA Foreign" would sort first and leak its existence.
+      { id: foreignCustomer, tenantId: otherTenantAdmin.tenantId, name: "AAA Foreign" },
+    ]);
+    const orderD = "dddddddd-dddd-4ddd-8ddd-dddddddddddd";
+    await seedRows(testDb.db, orderTable, [
+      { id: orderD, tenantId: admin.tenantId, note: "d", customerId: foreignCustomer },
+    ]);
+
+    const res = await orderExec.list({ sort: "customerId", sortDirection: "asc" }, admin, tdbA, {
+      referenceSort,
+    });
+
+    expect(idsOf(res.rows)).toEqual([ORDER_C, ORDER_B, ORDER_A, orderD]);
+  });
+
+  test("a reference field that did not opt into sortable falls back to id order, never UUID order", async () => {
+    await seedFixture();
+
+    const res = await orderExec.list({ sort: "customerId", sortDirection: "asc" }, admin, tdbA, {
+      referenceSort: { fields: [], resolveEntity },
+    });
+
+    expect(idsOf(res.rows)).toEqual([ORDER_A, ORDER_B, ORDER_C]);
+  });
+
+  test("an unresolvable target entity falls back to id order, never UUID order", async () => {
+    await seedFixture();
+
+    const res = await orderExec.list({ sort: "customerId", sortDirection: "asc" }, admin, tdbA, {
+      referenceSort: { fields: referenceSort.fields, resolveEntity: () => undefined },
+    });
+
+    expect(idsOf(res.rows)).toEqual([ORDER_A, ORDER_B, ORDER_C]);
+  });
+
+  test("a caller without read access to the reference column gets id order, an Admin gets label order", async () => {
+    await seedRows(testDb.db, customerTable, [
+      { id: CUSTOMER_MIKE, tenantId: admin.tenantId, name: "Mike" },
+      { id: CUSTOMER_ALPHA, tenantId: admin.tenantId, name: "Alpha" },
+      { id: CUSTOMER_ZULU, tenantId: admin.tenantId, name: "Zulu" },
+    ]);
+    await seedRows(testDb.db, restrictedOrderTable, [
+      { id: ORDER_A, tenantId: admin.tenantId, note: "a", customerId: CUSTOMER_ZULU },
+      { id: ORDER_B, tenantId: admin.tenantId, note: "b", customerId: CUSTOMER_MIKE },
+      { id: ORDER_C, tenantId: admin.tenantId, note: "c", customerId: CUSTOMER_ALPHA },
+    ]);
+
+    const asUser = await restrictedOrderExec.list(
+      { sort: "customerId", sortDirection: "asc" },
+      TestUsers.user,
+      tdbA,
+      { referenceSort },
+    );
+    expect(idsOf(asUser.rows)).toEqual([ORDER_A, ORDER_B, ORDER_C]);
+
+    const asAdmin = await restrictedOrderExec.list(
+      { sort: "customerId", sortDirection: "asc" },
+      admin,
+      tdbA,
+      { referenceSort },
+    );
+    expect(idsOf(asAdmin.rows)).toEqual([ORDER_C, ORDER_B, ORDER_A]);
+  });
+});

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

@@ -120,6 +120,23 @@ describe("lock-step — softDelete + explizite Indexes", () => {
     );
     expect((fromBuilder?.indexes ?? []).length).toBeGreaterThanOrEqual(3);
   });
+
+  test("explicit unique index without author where gets the soft-delete predicate (#2593)", () => {
+    const idx = fromMeta.indexes.find((i) => i.name.endsWith("_owner_id_status_unique"));
+    expect(idx?.unique).toBe(true);
+    expect(idx?.whereSql).toBe('"is_deleted" = false');
+  });
+
+  test("author-provided where is left unchanged, no is_deleted appended (#2593)", () => {
+    const idx = fromMeta.indexes.find((i) => i.name === "open_title_unique");
+    expect(idx?.whereSql).toBe("status = 'open'");
+  });
+
+  test("non-unique explicit index gets no predicate at all (#2593)", () => {
+    const idx = fromMeta.indexes.find((i) => i.name.endsWith("_owner_id_idx"));
+    expect(idx?.unique).toBeUndefined();
+    expect(idx?.whereSql).toBeUndefined();
+  });
 });
 
 // Dritte Probe: lookupable-Feld (#818) — bidx-Spalte, bidx-Index und das
@@ -159,6 +176,14 @@ describe("lock-step — lookupable / blind-index (#818)", () => {
     expect(partial?.columns).toEqual(["tenant_slug", "email_bidx"]);
     expect(partial?.whereSql).toBe('"email_bidx" IS NOT NULL');
   });
+
+  test("without softDelete, the plaintext unique index gets no predicate (#2593)", () => {
+    const plaintext = fromMeta.indexes.find(
+      (i) => i.name.endsWith("_tenant_slug_email_unique") && !i.name.endsWith("_bidx"),
+    );
+    expect(plaintext?.unique).toBe(true);
+    expect(plaintext?.whereSql).toBeUndefined();
+  });
 });
 
 // Fourth probe: softDelete + lookupable (#2464) — the partial bidx unique
@@ -188,4 +213,12 @@ describe("lock-step — softDelete + lookupable/blind-index (#2464)", () => {
     expect(partial).toBeDefined();
     expect(partial?.whereSql).toBe('"email_bidx" IS NOT NULL AND "is_deleted" = false');
   });
+
+  test("plaintext unique index also gets the soft-delete predicate (#2593)", () => {
+    const plaintext = fromMeta.indexes.find(
+      (i) => i.name.endsWith("_tenant_slug_email_unique") && !i.name.endsWith("_bidx"),
+    );
+    expect(plaintext?.unique).toBe(true);
+    expect(plaintext?.whereSql).toBe('"is_deleted" = false');
+  });
 });

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

@@ -338,13 +338,20 @@ export function deriveEntityTableMeta(
     );
     const suffix = def.unique === true ? "unique" : "idx";
     const indexName = def.name ?? `${tableName}_${cols.join("_")}_${suffix}`;
-    const whereSql = sqlExpressionText(def.where);
+    const explicitWhereSql = sqlExpressionText(def.where);
+    // Soft-deleted rows keep their value, so a full unique index would
+    // permanently block reuse; kept in lock-step with table-builder.ts (framework#2593).
+    const whereSql =
+      explicitWhereSql ??
+      (def.where === undefined && def.unique === true && entity.softDelete === true
+        ? `"is_deleted" = false`
+        : undefined);
     indexes.push({
       name: indexName,
       columns: cols,
       ...(def.unique === true && { unique: true }),
       ...(whereSql !== undefined && { whereSql }),
-      ...(def.where !== undefined && whereSql === undefined && { needsManualWhere: true }),
+      ...(def.where !== undefined && explicitWhereSql === undefined && { needsManualWhere: true }),
     });
     // Unique index over lookupable columns: partial bidx counterpart, so
     // uniqueness also holds for encrypted rows. The original stays