@cosmicdrift/kumiko-framework 0.334.0 → 0.335.0

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

@@ -16,7 +16,7 @@ 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);
     for (const feature of features.values()) {
@@ -34,8 +34,14 @@ export async function nullBlindIndexesForSubject(db, features, subjectKey) {
             // linkable (fw#2550).
             if (!(await tableExists(db, 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;
                 await executeRawQuery(db, `UPDATE ${quoteIdent(tableName)} SET ${quoteIdent(`${snake}_bidx`)} = NULL WHERE ${quoteIdent(snake)} LIKE $1`, [likePattern]);
             }
         }
@@ -67,6 +73,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;
@@ -608,21 +618,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;

package/dist/db/queries/backfill-pii.js

@@ -249,11 +249,21 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
         const catalogFields = eventCatalog.get(row.type);
         if (catalogFields) {
             for (const [field, spec] of Object.entries(catalogFields)) {
-                const subject = resolveEventSubject(field, spec, payload, {
-                    tenantId: row.tenant_id, // @cast-boundary db-read — tenant_id column is the branded TenantId
-                    aggregateType: row.aggregate_type,
-                    aggregateId: row.aggregate_id,
-                });
+                let subject;
+                try {
+                    subject = resolveEventSubject(field, spec, payload, {
+                        tenantId: row.tenant_id, // @cast-boundary db-read — tenant_id column is the branded TenantId
+                        aggregateType: row.aggregate_type,
+                        aggregateId: row.aggregate_id,
+                    });
+                }
+                catch (e) {
+                    // Re-thrown as a plain Error: the owner-resolution retry hint added for
+                    // SubjectResolutionError only applies to entity events.
+                    if (!(e instanceof SubjectResolutionError))
+                        throw e;
+                    throw new Error(`catalog event subject unresolvable: ${e.message} (fix aggregate_type/tenant_id or the piiFields declaration)`);
+                }
                 if (subject === null)
                     continue;
                 const outcome = await encryptField(payload, field, subject);

package/dist/db/queries/shadow-swap.js

@@ -109,8 +109,8 @@ export async function assertLiveTableHasNoRowLevelSecurity(tx, tableName, projec
     throw new Error(`${context}: live table "${tableName}" has row level security (enabled: ${row.rls_enabled}, ` +
         `forced: ${row.rls_forced}, policies: ${row.policy_count}). The shadow swap rebuilds the table ` +
         "from EntityTableMeta and would silently drop RLS and every policy. Kumiko does not support RLS " +
-        "on rebuildable tables — see kumiko-platform docs/plans/rls-evaluation.md. Rebuild aborted; live " +
-        "table untouched.");
+        "on rebuildable tables: drop the RLS flags/policies on this table or exclude it from online " +
+        "rebuild. Rebuild aborted; live table untouched.");
 }
 // Runs INSIDE the rebuild tx, AFTER the state/consumer row lock is taken.
 // Points search_path at the shadow schema (SET LOCAL → auto-reset on commit or
@@ -227,8 +227,9 @@ export async function assertNoBlindIndexLoss(tx, tableName, meta, projectionName
     throw new Error(`projection-rebuild "${projectionName}": "${tableName}" has ${count} row(s) with a populated ` +
         `blind-index column, but KUMIKO_BLIND_INDEX_KEY is not configured in this process. The rebuild ` +
         `would recompute those columns to NULL, and equality lookups on that field (login, password ` +
-        `reset) would stop matching afterward. Configure the blind-index key before this apply/rebuild ` +
-        `runs. See fw#3091. Rebuild aborted; live table untouched.`);
+        `reset) would stop matching afterward. Configure the complete KMS wiring (PLATFORM_KEK, ` +
+        `SUBJECT_KEYS_DATABASE_URL, KUMIKO_BLIND_INDEX_KEY, all-or-none) in the process running this ` +
+        `apply/rebuild. See fw#3091. Rebuild aborted; live table untouched.`);
 }
 // Columns ignored by countColumnDrift — the one PROVABLY legitimate class of
 // live-vs-shadow divergence. A blind-index column (`<field>_bidx`) is

package/dist/db/table-builder.d.ts

@@ -5,6 +5,7 @@ import type { EntityDefinition, EntityRelations, FieldDefinition, FieldsMap } fr
 import type { Table } from "./event-store-executor-context.js";
 export { toSnakeCase } from "../utils/case.js";
 import { type ColumnBuilder, type ColumnHandle, type SchemaTable, type TableColumns } from "./dialect.js";
+export declare const SOFT_DELETE_LIVE_ROW_PREDICATE = "\"is_deleted\" = false";
 export declare function physicalColumnName(table: Table, field: string): string;
 export type AnyPgColumn = ColumnHandle;
 export declare const READ_MODEL_PREFIX = "read_";

package/dist/db/table-builder.js

@@ -2,7 +2,10 @@ import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types
 import { toSnakeCase } from "../utils/case.js";
 import { assertUnreachable } from "../utils/index.js";
 export { toSnakeCase } from "../utils/case.js";
-import { bigint, boolean, decimalColumn, doublePrecision, index, instant, integer, jsonb, moneyAmount, table as pgTable, plainDate, SQL_EXPR_BRAND, serial, sql, text, uniqueIndex, uuid, } from "./dialect.js";
+import { bigint, boolean, decimalColumn, doublePrecision, index, instant, integer, jsonb, moneyAmount, table as pgTable, plainDate, serial, sql, text, uniqueIndex, uuid, } from "./dialect.js";
+// Partial-index predicate for soft-delete entities; table-builder and
+// entity-table-meta must render identical index definitions.
+export const SOFT_DELETE_LIVE_ROW_PREDICATE = `"is_deleted" = false`;
 // Shared by the CRUD executor and the parent-ref read-gate — a field's
 // declared column name if it has one, else its snake_case default.
 export function physicalColumnName(table, field) {
@@ -382,13 +385,7 @@ export function buildEntityTable(entityName, entity, options) {
             else if (def.unique === true && entity.softDelete === true) {
                 // Soft-deleted rows keep their value, so a full unique index would
                 // permanently block reuse; kept in lock-step with entity-table-meta.ts (framework#2593).
-                const softDeleteWhere = {
-                    kind: "sql-expr",
-                    text: `"is_deleted" = false`,
-                    params: [],
-                    [SQL_EXPR_BRAND]: true,
-                };
-                chain = chain.where(softDeleteWhere);
+                chain = chain.where(sql.raw(SOFT_DELETE_LIVE_ROW_PREDICATE));
             }
             indexes[indexName] = chain;
             // Partielles bidx-Pendant für unique-Indices über lookupable-Spalten
@@ -407,14 +404,9 @@ export function buildEntityTable(entityName, entity, options) {
                         // restored row can't reuse a value a soft-deleted sibling still
                         // holds (framework#2464).
                         const whereText = (entity.softDelete === true
-                            ? [...notNullParts, `"is_deleted" = false`]
+                            ? [...notNullParts, SOFT_DELETE_LIVE_ROW_PREDICATE]
                             : notNullParts).join(" AND ");
-                        const partialWhere = {
-                            kind: "sql-expr",
-                            text: whereText,
-                            params: [],
-                            [SQL_EXPR_BRAND]: true,
-                        };
+                        const partialWhere = sql.raw(whereText);
                         indexes[`${indexName}_bidx`] = uniqueIndex(`${indexName}_bidx`)
                             .on(...bidxCols)
                             .where(partialWhere);

package/dist/db/tenant-db.js

@@ -3,8 +3,7 @@ import { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-t
 import { asEntityTableMeta, asRawClient, aggregateWhere as bunAggregateWhere, countWhere as bunCountWhere, deleteMany as bunDeleteMany, fetchOne as bunFetchOne, insertOne as bunInsertOne, selectMany as bunSelectMany, updateMany as bunUpdateMany, runInNewTransaction, } from "../db/query.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
-import { fallbackEscapeHatchReporter } from "../observability/escape-hatch-report.js";
-import { emitDbQuery, registerStandardMetrics, } from "../observability/index.js";
+import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
 import { bindTenantDbRunner, tenantDbRunner } from "./tenant-db-runner.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 const declaredUnsafeRawRunners = new WeakMap();
@@ -361,6 +360,17 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             return undefined;
         return new AccessDeniedError({ message });
     }
+    // A tenant-mode write against a "global" table can never match (rows carry SYSTEM_TENANT_ID, writeWhere pins the caller's tenant), so reject loudly instead of silently affecting zero rows.
+    function tenantWriteOnGlobalTable(table, method) {
+        if (mode !== "tenant" || !hasTenantColumn(table))
+            return undefined;
+        if (asEntityTableMeta(table)?.tenancy !== "global")
+            return undefined;
+        return new AccessDeniedError({
+            message: `${method}(${tableNameOf(table)}): "global" table rows carry SYSTEM_TENANT_ID and never match the caller's tenant; ` +
+                "use db.global(table) with escapeHatch instead.",
+        });
+    }
     function globalTable(table) {
         const meta = asEntityTableMeta(table);
         if (meta?.tenancy !== "global") {
@@ -466,6 +476,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             if (!where || Object.keys(where).length === 0) {
                 return Promise.reject(new Error("TenantDb.updateMany without where would mass-update all tenant rows. Pass at least one where condition."));
             }
+            const globalDenied = tenantWriteOnGlobalTable(table, "updateMany");
+            if (globalDenied)
+                return Promise.reject(globalDenied);
             const personalDenied = personalDataDenied(table, Object.keys(set));
             if (personalDenied)
                 return Promise.reject(personalDenied);
@@ -476,6 +489,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             if (!where || Object.keys(where).length === 0) {
                 return Promise.reject(new Error("TenantDb.deleteMany without where would mass-delete all tenant rows. Pass at least one where condition."));
             }
+            const globalDenied = tenantWriteOnGlobalTable(table, "deleteMany");
+            if (globalDenied)
+                return Promise.reject(globalDenied);
             const filter = writeWhere(table, where);
             return withDbSpan("delete", table, async () => bunDeleteMany(db, table, filter));
         },

package/dist/derivatives/variant-key.js

@@ -34,7 +34,9 @@ export function variantSuffix(name, spec) {
 // A full derivative-suffix segment is `<name>-<16 hex chars>` — mirrors
 // VARIANT_NAME_PATTERN (name grammar) + specHash's fixed 16-char slice.
 // Keep in sync with both if either changes.
-const DERIVATIVE_SUFFIX_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}-[0-9a-f]{16}$/i;
+// The hash part stays case-sensitive (specHash emits lowercase hex only), so
+// the erasure sweep never matches a differently-cased sibling file.
+const DERIVATIVE_SUFFIX_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9-]{0,31}-[0-9a-f]{16}$/;
 // Mirrors deriveKey's own split so callers get the exact same base/ext this
 // key's derivatives were built from.
 function splitKey(key) {