@cosmicdrift/kumiko-framework 0.334.0 → 0.336.0

package/dist/crypto/kek-source.js

@@ -34,12 +34,12 @@ async function decryptCiphertext(ciphertext, keyId, token, region, fetchImpl, lo
                 signal: AbortSignal.timeout(DECRYPT_TIMEOUT_MS),
             });
         }
-        catch {
+        catch (error) {
             if (attempt < maxAttempts) {
                 await sleep(RETRY_DELAYS_MS[attempt - 1] ?? 0);
                 continue;
             }
-            throw new Error(`${prefix}Key Manager decrypt failed for key ${keyId}: network error or timeout`);
+            throw new Error(`${prefix}Key Manager decrypt failed for key ${keyId}: network error or timeout`, { cause: error });
         }
         if (!response.ok) {
             if (isRetryableStatus(response.status) && attempt < maxAttempts) {
@@ -62,60 +62,64 @@ async function decryptCiphertext(ciphertext, keyId, token, region, fetchImpl, lo
     }
     throw new Error(`${prefix}Key Manager decrypt failed for key ${keyId}: retries exhausted`);
 }
+// A leftover plaintext beside a ciphertext boots green while nothing was
+// migrated, which is indistinguishable from a finished cutover unless the
+// boot says which source won. The line is built from the path actually taken.
 async function resolveSlot(name, env, options, fetchImpl) {
     const plaintext = env[name];
-    if (plaintext)
-        return plaintext;
     const ciphertext = env[`${name}_CIPHERTEXT`];
+    if (plaintext) {
+        return {
+            value: plaintext,
+            sourceLine: ciphertext
+                ? `${name} source=plaintext-env (ciphertext present and ignored)`
+                : `${name} source=plaintext-env`,
+        };
+    }
     if (!ciphertext)
-        return undefined;
+        return { value: undefined, sourceLine: undefined };
     const keyId = env.PLATFORM_KEK_KMS_KEY_ID;
     const token = env.PLATFORM_KEK_KMS_TOKEN;
     if (!keyId || !token) {
         const prefix = options.logPrefix ? `${options.logPrefix} ` : "";
-        throw new Error(`${prefix}PLATFORM_KEK_KMS_KEY_ID / PLATFORM_KEK_KMS_TOKEN are all-or-none with a KEK ciphertext (slot ${name}) — a partial set means the KMS wiring is broken.`);
-    }
-    const region = env.PLATFORM_KEK_KMS_REGION ?? DEFAULT_REGION;
-    return decryptCiphertext(ciphertext, keyId, token, region, fetchImpl, options.logPrefix);
-}
-// A leftover plaintext beside a ciphertext boots green while nothing was
-// migrated, which is indistinguishable from a finished cutover unless the
-// boot says which source won. Never carries a key value, only its origin.
-function describeKekSource(name, env) {
-    const plaintext = env[name];
-    const ciphertext = env[`${name}_CIPHERTEXT`];
-    if (plaintext) {
-        return ciphertext
-            ? `${name} source=plaintext-env (ciphertext present and ignored)`
-            : `${name} source=plaintext-env`;
+        throw new Error(`${prefix}${name}_CIPHERTEXT is set but PLATFORM_KEK_KMS_KEY_ID / PLATFORM_KEK_KMS_TOKEN are missing — a partial set means the KMS wiring is broken.`);
     }
-    if (!ciphertext)
-        return undefined;
     const region = env.PLATFORM_KEK_KMS_REGION ?? DEFAULT_REGION;
-    return `${name} source=key-manager keyId=${env.PLATFORM_KEK_KMS_KEY_ID} region=${region}`;
+    const value = await decryptCiphertext(ciphertext, keyId, token, region, fetchImpl, options.logPrefix);
+    return {
+        value,
+        sourceLine: `${name} source=key-manager keyId=${keyId} region=${region}`,
+    };
 }
 // Each slot resolves independently so a rollback that clears one slot's
 // plaintext (leaving its ciphertext/_VERSION behind or gone) never blocks
 // another slot's fallback path — the trio check downstream still applies.
+// Slots resolve in parallel: sequentially, a slow Key Manager would cost up to
+// ~16 s per slot (3 x 5 s timeout + backoff) and could trip startup probes.
 export async function resolvePlatformKeks(env, options = {}) {
     const fetchImpl = options.fetch ?? globalThis.fetch;
+    const prefix = options.logPrefix ? `${options.logPrefix} ` : "";
     const slots = options.slots ?? LEGACY_SLOTS;
-    const resolved = {};
-    for (const name of slots) {
-        resolved[name] = await resolveSlot(name, env, options, fetchImpl);
+    // Misconfiguration must not cost a Key Manager round trip.
+    if (slots.includes("PLATFORM_KEK_PREVIOUS") &&
+        (env.PLATFORM_KEK_PREVIOUS || env.PLATFORM_KEK_PREVIOUS_CIPHERTEXT) &&
+        !env.PLATFORM_KEK_PREVIOUS_VERSION) {
+        throw new Error(`${prefix}PLATFORM_KEK_PREVIOUS_VERSION must be set when PLATFORM_KEK_PREVIOUS is set.`);
     }
-    const prefix = options.logPrefix ? `${options.logPrefix} ` : "";
+    const results = await Promise.all(slots.map((name) => resolveSlot(name, env, options, fetchImpl)));
     // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
     const log = options.log ?? console.info;
-    for (const name of slots) {
-        const line = describeKekSource(name, env);
-        if (line)
-            log(`${prefix}${line}`);
-    }
-    if (resolved["PLATFORM_KEK_PREVIOUS"] && !env.PLATFORM_KEK_PREVIOUS_VERSION) {
-        throw new Error(`${prefix}PLATFORM_KEK_PREVIOUS_VERSION must be set when PLATFORM_KEK_PREVIOUS is set.`);
-    }
-    const changed = slots.some((name) => resolved[name] !== env[name]);
+    const resolved = {};
+    slots.forEach((name, index) => {
+        const result = results[index];
+        // skip: slot without a resolved result stays unset
+        if (!result)
+            return;
+        resolved[name] = result.value;
+        if (result.sourceLine)
+            log(`${prefix}${result.sourceLine}`);
+    });
+    const changed = Object.keys(resolved).some((name) => resolved[name] !== env[name]);
     if (!changed)
         return env;
     return { ...env, ...resolved };

package/dist/crypto/kms-adapter.js

@@ -3,8 +3,8 @@ import * as z from "zod";
 export * from "@cosmicdrift/kumiko-types/kms-adapter-types";
 // The KMS error classes live here and not in kumiko-types (#1629): callers
 // branch on them with `instanceof`, which needs a single copy of the class.
-// `satisfies z.ZodType<SubjectId>` binds this to the TS type at compile time
-// (fw#2801) — mint (subjectKeyForRecord) and shred (forget-subject) can no
+// `satisfies z.ZodType<SubjectId>` plus the reverse check in subject-id-schema.test.ts bind this to the TS type
+// at compile time (fw#2801) — mint (subjectKeyForRecord) and shred (forget-subject) can no
 // longer drift apart on which subjects are valid, the way #2809 happened.
 export const subjectIdSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("user"), userId: z.uuid() }),

package/dist/db/apply-entity-event.js

@@ -114,8 +114,14 @@ export async function applyEntityEvent(event, table, entity, tx) {
             // UPDATE so Postgres doesn't error with "column X does not exist".
             const changes = {};
             for (const [key, value] of Object.entries(rawChanges)) {
-                const fieldType = entity.fields[key]?.type;
-                if (fieldType === "files" || fieldType === "images")
+                const field = entity.fields[key];
+                // Historical events can carry fields since removed from the entity; the
+                // tolerance lives here (not in updateMany) so a live typo still throws.
+                // Base/soft-delete columns (insertedById, deletedAt, ...) are table
+                // columns without an entity field and must still be applied.
+                if (field === undefined && !(key in table))
+                    continue;
+                if (field?.type === "files" || field?.type === "images")
                     continue;
                 changes[key] = value;
             }

package/dist/db/blind-index-cleanup.js

@@ -16,9 +16,10 @@ import { isSelfPiiField } from "../crypto/is-self-pii-field.js";
 import { toSnakeCase } from "../utils/case.js";
 import { resolveTableName } from "./entity-table-meta.js";
 import { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
-import { tableExists } from "./schema-inspection.js";
+import { columnNamesOf, tableExists } from "./schema-inspection.js";
 export async function nullBlindIndexesForSubject(db, features, subjectKey) {
     const likePattern = subjectCiphertextLikePattern(subjectKey);
+    const candidates = [];
     for (const feature of features.values()) {
         for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
             const lookupable = collectLookupableFields(entity);
@@ -27,20 +28,36 @@ export async function nullBlindIndexesForSubject(db, features, subjectKey) {
             // No featureName prefix — the dispatcher builds entity tables without
             // one (buildEntityTable with no featureName option), the sweep has to
             // hit the same names.
-            const tableName = resolveTableName(entityName, entity, undefined);
-            // Skip entities whose projection was never migrated — same class as
-            // subjectRowExistsInTenant (fw#2348). A throw here runs AFTER eraseKey
-            // in forget-subject and would leave deterministic bidx columns still
-            // linkable (fw#2550).
-            if (!(await tableExists(db, tableName)))
+            candidates.push({ tableName: resolveTableName(entityName, entity, undefined), lookupable });
+        }
+    }
+    // Skip entities whose projection was never migrated — same class as
+    // subjectRowExistsInTenant (fw#2348). A throw here runs AFTER eraseKey
+    // in forget-subject and would leave deterministic bidx columns still
+    // linkable (fw#2550). One batched existence query instead of one
+    // roundtrip per entity.
+    const existing = await existingTableNames(db, candidates.map((c) => c.tableName));
+    for (const { tableName, lookupable } of candidates) {
+        if (!existing.has(tableName))
+            continue;
+        // Same hazard for a migrated table that predates a later-added
+        // lookupable field: skip fields whose columns are missing instead of
+        // aborting the sweep for the remaining ones.
+        const columns = await columnNamesOf(db, tableName);
+        for (const fieldName of lookupable) {
+            const snake = toSnakeCase(fieldName);
+            if (!columns.has(snake) || !columns.has(`${snake}_bidx`))
                 continue;
-            for (const fieldName of lookupable) {
-                const snake = toSnakeCase(fieldName);
-                await executeRawQuery(db, `UPDATE ${quoteIdent(tableName)} SET ${quoteIdent(`${snake}_bidx`)} = NULL WHERE ${quoteIdent(snake)} LIKE $1`, [likePattern]);
-            }
+            await executeRawQuery(db, `UPDATE ${quoteIdent(tableName)} SET ${quoteIdent(`${snake}_bidx`)} = NULL WHERE ${quoteIdent(snake)} LIKE $1`, [likePattern]);
         }
     }
 }
+async function existingTableNames(db, tableNames) {
+    if (tableNames.length === 0)
+        return new Set();
+    const rows = await executeRawQueryRead(db, `SELECT t.name FROM unnest($1::text[]) AS t(name) WHERE to_regclass(quote_ident(t.name)) IS NOT NULL`, [tableNames]);
+    return new Set(rows.map((r) => r.name));
+}
 // 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 (`pii: true`,
@@ -67,6 +84,10 @@ export async function subjectRowExistsInTenant(db, features, subjectId, tenantId
             const hasSelfPiiField = Object.values(entity.fields).some(isSelfPiiField);
             if (!hasSelfPiiField)
                 continue;
+            // Subject ids are uuids; comparing one to a serial id column makes
+            // postgres throw (invalid input syntax for integer) mid forget-TX.
+            if (entity.idType === "serial")
+                continue;
             candidateTables.push(resolveTableName(entityName, entity, undefined));
         }
     }

package/dist/db/entity-table-meta.js

@@ -17,7 +17,7 @@
 //      `store_` table name — `read_` is reserved for managed projections (#1208/#1220).
 import { collectPiiSubjectFields } from "../crypto/index.js";
 import { SQL_EXPR_BRAND } from "./dialect.js";
-import { READ_MODEL_PREFIX, toSnakeCase, toTableName } from "./table-builder.js";
+import { READ_MODEL_PREFIX, SOFT_DELETE_LIVE_ROW_PREDICATE, toSnakeCase, toTableName, } from "./table-builder.js";
 // Standard base columns for event-sourced read-model tables. Mirrors
 // `buildBaseColumns()` from table-builder.ts (drizzle variant).
 function fullBaseColumns(idType, softDelete) {
@@ -300,7 +300,7 @@ export function deriveEntityTableMeta(entityName, entity, options) {
         // 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`
+                ? SOFT_DELETE_LIVE_ROW_PREDICATE
                 : undefined);
         indexes.push({
             name: indexName,
@@ -322,7 +322,9 @@ export function deriveEntityTableMeta(entityName, entity, options) {
                 // 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;
+                const whereParts = entity.softDelete === true
+                    ? [...notNullParts, SOFT_DELETE_LIVE_ROW_PREDICATE]
+                    : notNullParts;
                 indexes.push({
                     name: `${indexName}_bidx`,
                     columns: bidxCols,

package/dist/db/event-store-executor-context.js

@@ -289,27 +289,21 @@ export function buildExecutorContext(table, entity, options) {
             ...(await executeRawQueryRead(tenantDbRunner(db), sqlText, params)),
         ];
     }
-    // Combined, atomic read for the `expect:` precondition (#3024): the
-    // projection row's expect-checked fields AND the events table's current
-    // MAX(version) for this aggregate, in ONE SQL statement.
+    // Combined, atomic read for the `expect:` precondition: the projection
+    // row's expect-checked fields AND the events table's current MAX(version)
+    // for this aggregate, in ONE SQL statement.
     //
-    // Two separate reads (loadById then getStreamVersion, in either order)
-    // leave a real gap: applyEntityEvent writes the projection in a SEPARATE
-    // statement AFTER its event commits, so a second reader can see a version
-    // that already reflects a concurrent writer's event while its OWN read of
-    // the expect fields still reflects the pre-write projection row — verified
-    // empirically: ~40% of genuinely concurrent update() calls slipped a stale
-    // precondition through with two round-trips, regardless of read order. One
-    // query removes the gap: Postgres executes it against a single consistent
-    // snapshot.
+    // Two separate reads leave a gap: applyEntityEvent writes the projection in
+    // a separate statement after its event commits, so a second reader can see
+    // a version that already reflects a concurrent writer's event while its read
+    // of the expect fields still shows the pre-write row. One query runs against
+    // a single consistent snapshot.
     //
-    // This also sidesteps a correctness bug the row's own `version` column
-    // can't be trusted for: applyEntityEvent only keeps row.version in
-    // lock-step with the OTHER projection columns for rows this executor
-    // itself wrote. A row seeded directly (raw INSERT — test fixtures, or
-    // legacy pre-#762 data) can carry a default version (e.g. 1) with ZERO
-    // matching events. Deriving expectedVersion from such a row.version makes
-    // the append below target a non-existent predecessor and fail outright.
+    // The row's own `version` column can't be trusted instead: it is only in
+    // lock-step with the events for rows this executor wrote. A raw-seeded row
+    // (test fixtures, legacy data) can carry a default version with zero
+    // matching events, so deriving expectedVersion from it makes the append
+    // target a non-existent predecessor and fail.
     // The events table's MAX(version) (0 for such a row) is the only value
     // append() can safely use as expectedVersion — exactly what
     // getStreamVersion() already returns for every other (non-`expect`)

package/dist/db/event-store-executor-read.js

@@ -1,6 +1,6 @@
 import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { escapeLikePattern } from "../crypto/ciphertext-pattern.js";
-import { collectPiiSubjectFields, computeBlindIndex, configuredBlindIndexKey, } from "../crypto/index.js";
+import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/index.js";
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
 import { coerceRow, extractTableInfo } from "../db/query.js";
 import { buildOwnershipClause, combineClauses, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
@@ -10,7 +10,7 @@ import { getStreamVersion } from "../event-store/index.js";
 import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta.js";
 import { rehydrateCompoundTypes } from "./compound-types.js";
 import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.js";
-import { collectEncryptedFieldNames, hasSearchablePlaintext, isSensitiveLabelField, } from "./entity-field-encryption.js";
+import { hasSearchablePlaintext, isSensitiveLabelField } from "./entity-field-encryption.js";
 import { buildFilterWhere, } from "./event-store-executor-context.js";
 import { buildParentRefClause } from "./parent-ref-clause.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
@@ -105,20 +105,29 @@ function applyMultiSelectFilter(colSql, whereSql, params, f) {
             return;
         }
         const parts = f.value.map((v) => {
-            params.push([v]);
-            return `${colSql(f.field)} @> $${params.length}::jsonb`;
+            params.push(JSON.stringify([v]));
+            return `${colSql(f.field)} @> $${params.length}::text::jsonb`;
         });
         whereSql.push(`(${parts.join(" OR ")})`);
         // skip: containment condition already pushed — don't fall through to the eq/ne branch below
         return;
     }
-    // Bind a JS array, not JSON.stringify(value) — postgres.js double-encodes
-    // a stringified array through an `::jsonb` cast, so `@>` would never match
-    // (see update-roles.ts:67-68). An array value means "contains all of
-    // these" (the natural `@>` reading).
-    params.push(Array.isArray(f.value) ? f.value : [f.value]);
-    const containment = `${colSql(f.field)} @> $${params.length}::jsonb`;
-    whereSql.push(f.op === "ne" ? `NOT (${containment})` : containment);
+    const candidates = Array.isArray(f.value) ? f.value : [f.value];
+    // `@> '[]'` is true for every non-null row, so an empty array would turn
+    // the filter into a silent match-all.
+    if (candidates.length === 0) {
+        whereSql.push("FALSE");
+        // skip: empty candidate list is unsatisfiable
+        return;
+    }
+    // Bound as text then cast: a JS array makes postgres.js infer boolean[]/int4[]
+    // for client-supplied non-string values, and `boolean[]::jsonb` is rejected
+    // (500 on client input). An array value means "contains all of these".
+    params.push(JSON.stringify(candidates));
+    const containment = `${colSql(f.field)} @> $${params.length}::text::jsonb`;
+    // A NULL column must count as "does not contain" — plain NOT(...) yields
+    // NULL and would drop those rows.
+    whereSql.push(f.op === "ne" ? `(${colSql(f.field)} IS NULL OR NOT (${containment}))` : containment);
 }
 // Falls through to the screen-filter WHERE builder shared with
 // screen-declared filters — buildFilterWhere flattens the op into a
@@ -308,7 +317,7 @@ async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db
         // `name` is a declared field on the tenant entity, not an id/row-meta column
         return undefined;
     }
-    const targetTable = buildEntityTable(descriptor.targetEntityName, targetEntity);
+    const targetTable = referenceTargetTable(descriptor.targetEntityName, targetEntity);
     const targetTableName = String(targetTable[KUMIKO_NAME_SYMBOL]);
     if (!isSensitiveLabelField(targetEntity, descriptor.labelField)) {
         return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetTable, targetTableName, db);
@@ -320,6 +329,17 @@ async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db
     }
     return resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, searchAdapter);
 }
+// Building the table is pure but not free, and runs on every search request;
+// keyed by the definition object so a re-registered entity never sees a stale table.
+const referenceTargetTables = new WeakMap();
+function referenceTargetTable(name, entity) {
+    const cached = referenceTargetTables.get(entity);
+    if (cached?.name === name)
+        return cached.table;
+    const table = buildEntityTable(name, entity);
+    referenceTargetTables.set(entity, { name, table });
+    return table;
+}
 // Projected alongside the row when a reference sort is active, so the keyset
 // cursor carries the label that was ordered by instead of the FK's UUID.
 const SORT_LABEL_ALIAS = "__kumiko_sort_label";
@@ -342,8 +362,7 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
         // skip: labelField isn't a real (declared) column on the target entity
         return undefined;
     }
-    if (collectEncryptedFieldNames(targetEntity).has(descriptor.labelField) ||
-        collectPiiSubjectFields(targetEntity).includes(descriptor.labelField)) {
+    if (isSensitiveLabelField(targetEntity, descriptor.labelField)) {
         // skip: encrypted/PII labelField — ciphertext orders by its bytes, which is
         // arbitrary to the reader and would also rank rows by their stored secret
         return undefined;
@@ -389,10 +408,6 @@ export function createReadVerbs(ctx) {
                 return { rows: [], nextCursor: null, ...(totalCount && { total: 0 }) };
             }
             let filterIds;
-            // fw#2660 — true once a searchable-reference or row-meta-reference
-            // clause contributed rows, so the total-count fast-path below knows
-            // `filterIds.length` alone would undercount.
-            let referenceClauseActive = false;
             // Build the WHERE clause as raw SQL — ownership produces a
             // parameterised fragment that we splice in alongside simple WhereObject
             // conditions (cursor, search-filter-IDs, screen-filter, tenant-scope).
@@ -461,17 +476,12 @@ export function createReadVerbs(ctx) {
                         return `$${params.length}`;
                     });
                     orParts.push(`${colSql(match.ownColumn)} IN (${placeholders.join(", ")})`);
-                    referenceClauseActive = true;
                 }
                 // Parenthesized as one whereSql entry — whereSql is joined with
                 // " AND " below, an unparenthesized OR here would leak past the
                 // tenant filter that follows.
                 whereSql.push(`(${orParts.join(" OR ")})`);
             }
-            // The total-count fast-path below is only valid while this is still
-            // true after every later clause (tenant, soft-delete, cursor,
-            // ownership, parent-ref, filters) — see where it's checked.
-            const whereSqlLenAfterSearch = whereSql.length;
             const sortCandidate = payload.sort && table[payload.sort] && fieldReadClause(payload.sort).kind === "pass"
                 ? payload.sort
                 : undefined;
@@ -558,8 +568,12 @@ export function createReadVerbs(ctx) {
                 : referenceSortExpr !== undefined
                     ? referenceSortExpr(params)
                     : colSql(sortField);
-            const orderByClause = sortSql !== undefined
-                ? ` ORDER BY ${sortSql} ${sortDescending ? "DESC" : "ASC"}, ${colSql("id")} ASC`
+            // The projected label alias is ordered by directly, so Postgres evaluates
+            // the correlated subquery once per row instead of once for ORDER BY and
+            // once for the SELECT list.
+            const orderBySortSql = referenceSortExpr !== undefined ? `"${SORT_LABEL_ALIAS}"` : sortSql;
+            const orderByClause = orderBySortSql !== undefined
+                ? ` ORDER BY ${orderBySortSql} ${sortDescending ? "DESC" : "ASC"}, ${colSql("id")} ASC`
                 : ` ORDER BY ${colSql("id")} ASC`;
             const useOffset = !payload.cursor && offset > 0;
             const offsetClause = useOffset ? ` OFFSET ${offset}` : "";
@@ -608,21 +622,14 @@ export function createReadVerbs(ctx) {
             // total: extra COUNT(*) — only when explicitly requested (pager UI).
             // Postgres cost is O(table-scan) without a filter, with a filter as
             // expensive as the corresponding WHERE — cheap enough on indexed columns.
-            // On the search path, `total = filterIds.length` needs no extra query —
-            // unless a reference match contributed additional rows (fw#2660), or the
-            // WHERE grew past the search block (ownership, parent-ref, filters,
-            // soft-delete, cursor all splice in afterwards), in which case the raw
-            // filterIds length alone would undercount.
+            // Always counted over the full WHERE: search ids, reference matches, tenant,
+            // soft-delete, cursor, ownership and filters all narrow the result, so the
+            // search hit count alone is never the total.
             let total;
             if (totalCount) {
-                if (filterIds && !referenceClauseActive && whereSql.length === whereSqlLenAfterSearch) {
-                    total = filterIds.length;
-                }
-                else {
-                    const countSql = `SELECT COUNT(*)::int AS count FROM "${tableName}"${whereClauseSqlText}`;
-                    const countRows = await executeRawQueryRead(runner, countSql, whereParams);
-                    total = countRows[0]?.count ?? 0;
-                }
+                const countSql = `SELECT COUNT(*)::int AS count FROM "${tableName}"${whereClauseSqlText}`;
+                const countRows = await executeRawQueryRead(runner, countSql, whereParams);
+                total = countRows[0]?.count ?? 0;
             }
             return { rows, nextCursor, ...(total !== undefined && { total }) };
         },

package/dist/db/event-store-executor-write.js

@@ -66,13 +66,13 @@ export function createWriteVerbs(ctx) {
     const entityInstructionFieldNames = instructionFieldNames(entity);
     return {
         async create(payload, user, db, options) {
-            const runner = tenantDbRunner(db);
             if (isForeignTenantOnGlobalEntity(entity, payload["tenantId"])) {
                 throw new AccessDeniedError({
                     message: `${entityName}.create: entity is tenancy: "global" — payload.tenantId must be ` +
                         "SYSTEM_TENANT_ID or omitted.",
                 });
             }
+            const runner = tenantDbRunner(db);
             // Respect an explicit id in the payload (seed pattern, SCIM import). Without
             // one the framework mints a fresh UUIDv7 via generateId. Strip it out of the
             // event payload so defaults + downstream consumers don't see a redundant id field.
@@ -304,20 +304,8 @@ export function createWriteVerbs(ctx) {
             // trip `events_aggregate_version_uq` (tenant_id, aggregate_id, version)
             // with version_conflict.
             //
-            // `expect:` (#3024) reads this same authoritative version, but through
-            // loadExpectSnapshot's single combined query instead of a second,
-            // separate getStreamVersion() round-trip: two reads (in either order)
-            // leave a real gap — applyEntityEvent writes the projection in a
-            // SEPARATE statement after its event commits, so a second reader's
-            // version-read can land in that gap and see a fresh, non-conflicting
-            // version paired with a still-stale projection row (verified
-            // empirically: ~40% of genuinely concurrent runs slipped through with
-            // two round-trips). One query removes the gap. It also avoids trusting
-            // the row's own `version` column for the expectedVersion: that column
-            // is only in lock-step with the rest of the row for rows THIS executor
-            // wrote — a raw-seeded row (test fixture, or legacy pre-#762 data) can
-            // carry a default version with zero matching events, which would make
-            // the append below target a non-existent predecessor and fail outright.
+            // With `expect:` the version comes from loadExpectSnapshot's combined
+            // query instead; see its comment for why.
             let currentVersion;
             if (updateOptions?.expect) {
                 const expectKeys = Object.keys(updateOptions.expect);
@@ -603,12 +591,12 @@ export function createWriteVerbs(ctx) {
             };
         },
         async restore(payload, user, db) {
-            const runner = tenantDbRunner(db);
             if (!softDelete) {
                 return writeFailure(new UnprocessableError("soft_delete_not_enabled", {
                     i18nKey: "errors.softDeleteNotEnabled",
                 }));
             }
+            const runner = tenantDbRunner(db);
             // Tenant boundary: db.fetchOne applies TenantDb's tenant predicate,
             // selectMany(runner, ...) did not — any caller could un-delete a foreign
             // tenant's row by id. "system"-mode dbs (r.systemScope() / escapeHatch
@@ -672,7 +660,17 @@ export function createWriteVerbs(ctx) {
             // Live==Rebuild via applyEntityEvent. Restore only writes isDeleted=false
             // plus the version bump, so there is no sensitive-field drift and no
             // payload override is needed.
-            const restoreResult = await runInSavepointIfSupported(runner, async (sp) => applyEntityEvent(event, table, entity, sp));
+            // Soft-delete unique indexes are partial (WHERE is_deleted = false), so a live row may have re-taken the value this restore brings back.
+            let restoreResult;
+            try {
+                restoreResult = await runInSavepointIfSupported(runner, async (sp) => applyEntityEvent(event, table, entity, sp));
+            }
+            catch (e) {
+                const mapped = tryMapUniqueViolation(e, entityName);
+                if (mapped)
+                    return mapped;
+                throw e;
+            }
             if (restoreResult.kind !== "applied" || restoreResult.row === null) {
                 return writeFailure(new InternalError({ message: "projection restore returned no row" }));
             }

package/dist/db/migrate-generator.js

@@ -115,34 +115,25 @@ function diffOneTable(prev, next) {
             newIndexes.push(idx);
             continue;
         }
-        const change = { name };
-        if (!indexColumnsEqual(prevI.columns, idx.columns)) {
-            Object.assign(change, {
-                columnsChanged: { from: prevI.columns, to: idx.columns },
-            });
-        }
-        if ((prevI.unique ?? false) !== (idx.unique ?? false)) {
-            Object.assign(change, {
-                uniqueChanged: { from: prevI.unique ?? false, to: idx.unique ?? false },
-            });
-        }
-        if (prevI.whereSql !== idx.whereSql) {
-            Object.assign(change, {
-                whereSqlChanged: { from: prevI.whereSql, to: idx.whereSql },
-            });
-        }
-        if ((prevI.needsManualWhere ?? false) !== (idx.needsManualWhere ?? false)) {
-            Object.assign(change, {
-                needsManualWhereChanged: {
-                    from: prevI.needsManualWhere ?? false,
-                    to: idx.needsManualWhere ?? false,
-                },
-            });
-        }
-        if (change.columnsChanged ||
-            change.uniqueChanged ||
-            change.whereSqlChanged ||
-            change.needsManualWhereChanged) {
+        const columnsChanged = indexColumnsEqual(prevI.columns, idx.columns)
+            ? undefined
+            : { from: prevI.columns, to: idx.columns };
+        const uniqueChanged = (prevI.unique ?? false) === (idx.unique ?? false)
+            ? undefined
+            : { from: prevI.unique ?? false, to: idx.unique ?? false };
+        const whereSqlChanged = prevI.whereSql === idx.whereSql ? undefined : { from: prevI.whereSql, to: idx.whereSql };
+        const needsManualWhereChanged = (prevI.needsManualWhere ?? false) === (idx.needsManualWhere ?? false)
+            ? undefined
+            : { from: prevI.needsManualWhere ?? false, to: idx.needsManualWhere ?? false };
+        if (columnsChanged || uniqueChanged || whereSqlChanged || needsManualWhereChanged) {
+            // Single literal typed as IndexChange so a misspelled key fails to compile instead of silently dropping the change.
+            const change = {
+                name,
+                ...(columnsChanged && { columnsChanged }),
+                ...(uniqueChanged && { uniqueChanged }),
+                ...(whereSqlChanged && { whereSqlChanged }),
+                ...(needsManualWhereChanged && { needsManualWhereChanged }),
+            };
             changedIndexes.push(change);
         }
     }
@@ -215,6 +206,14 @@ function describeRecreateReasons(td) {
     if (newUniqueIndexes.length > 0) {
         reasons.push(`new UNIQUE index(es): ${newUniqueIndexes.join(", ")}`);
     }
+    // A changed index that ends up UNIQUE (newly unique, new columns, widened WHERE) can fail on existing duplicates in place.
+    const uniqueNextNames = new Set(td.nextMeta.indexes.filter((idx) => idx.unique === true).map((idx) => idx.name));
+    const changedToUnique = td.changedIndexes
+        .filter((c) => uniqueNextNames.has(c.name))
+        .map((c) => c.name);
+    if (changedToUnique.length > 0) {
+        reasons.push(`changed UNIQUE index(es): ${changedToUnique.join(", ")}`);
+    }
     const madeNotNull = td.changedColumns
         .filter((c) => c.nullabilityChanged?.to === true)
         .map((c) => c.name);

package/dist/db/pg-error.js

@@ -4,14 +4,18 @@
 // error. Used by the event-store to distinguish a unique-violation on the
 // aggregate-version index (optimistic-concurrency conflict) from the one on
 // the idempotency-key index (caller-side replay signal).
+const MAX_CAUSE_DEPTH = 8;
 export function extractPgError(e) {
     if (typeof e !== "object" || e === null)
         return null;
-    const layers = [e];
-    // @cast-boundary error-details — DrizzleQueryError wraps PG-error in .cause
-    const cause = e.cause;
-    if (typeof cause === "object" && cause !== null)
-        layers.push(cause);
+    const layers = [];
+    let current = e;
+    // Depth cap doubles as cycle protection for self-referential causes.
+    while (typeof current === "object" && current !== null && layers.length < MAX_CAUSE_DEPTH) {
+        layers.push(current);
+        // @cast-boundary error-details — DrizzleQueryError wraps PG-error in .cause
+        current = current.cause;
+    }
     for (const layer of layers) {
         // @cast-boundary error-details — postgres-js error shape (code, constraint_name)
         const code = layer.code;