@cosmicdrift/kumiko-framework 0.364.0 → 0.365.1

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

@@ -43,7 +43,11 @@
 //   unresolvable subject still fails loud into `failures`, as before.
 //   4. owner re-key ({@link PiiBackfillOptions.rekeyTenantKeyedOwnerFields}) —
 //   tenant-keyed ciphertext of a userOwned field moves under the user the
-//   strict chain (stages 1+2, never whenAbsent) names.
+//   strict chain (stages 1+2, never whenAbsent) names; user-keyed ciphertext
+//   moves under the projection's current owner when that is another user (an
+//   owner change made before owner transitions re-keyed the value). An owner
+//   cleared again (owner → none) is not recoverable from the projection: such
+//   values stay tenant-keyed, unlike the live path that keeps the last owner.
 //
 // Snapshots of touched aggregates are dropped per batch (they may cache
 // plaintext); the next snapshotting load recreates them. AFTER a run, rebuild the
@@ -54,11 +58,13 @@ import { asRawClient } from "../../bun-db/index.js";
 import { quoteIdent } from "../../crypto/ciphertext-pattern.js";
 import { configuredEventPiiCatalog } from "../../crypto/event-pii.js";
 import { isLocalKeyKmsAdapter, KeyErasedError, KeyNotFoundError, } from "../../crypto/kms-adapter.js";
+import { isPlainUserOwnedField } from "../../crypto/owner-transition-rekey.js";
 import { configuredPiiSubjectKms, decryptPiiValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_ERASED_SENTINEL, piiCiphertextSubject, } from "../../crypto/pii-field-encryption.js";
-import { collectPiiEncryptedFields, resolveEventSubject, resolveSubjectForField, SubjectResolutionError, } from "../../crypto/subject-resolver.js";
+import { collectPiiEncryptedFields, nonEmptyString, resolveEventSubject, resolveSubjectForField, SubjectResolutionError, } from "../../crypto/subject-resolver.js";
 import { resolveTableName } from "../entity-table-meta.js";
 import { tableExists } from "../schema-inspection.js";
 import { toSnakeCase } from "../table-builder.js";
+import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 const LIFECYCLE_VERBS = ["created", "updated", "deleted", "restored", "forgotten"];
 function collectPiiTargets(registry) {
     const entityTargets = new Map();
@@ -154,12 +160,21 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
         ? raw.unsafe(`SELECT "id", "aggregate_id", "aggregate_type", "tenant_id", "type", "payload"
            FROM "kumiko_events"
           WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" = ANY($3::bigint[])
-          ORDER BY "id" ASC`, [aggregateTypes, catalogTypes, [...options.eventIds]])
+          ORDER BY "id" ASC`, [
+            toPostgresArrayLiteral(aggregateTypes),
+            toPostgresArrayLiteral(catalogTypes),
+            toPostgresArrayLiteral([...options.eventIds]),
+        ])
         : raw.unsafe(`SELECT "id", "aggregate_id", "aggregate_type", "tenant_id", "type", "payload"
            FROM "kumiko_events"
           WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" > $3::bigint
           ORDER BY "id" ASC
-          LIMIT $4`, [aggregateTypes, catalogTypes, String(options.afterEventId ?? 0), batchSize]));
+          LIMIT $4`, [
+            toPostgresArrayLiteral(aggregateTypes),
+            toPostgresArrayLiteral(catalogTypes),
+            String(options.afterEventId ?? 0),
+            batchSize,
+        ]));
     const last = rows[rows.length - 1];
     if (last === undefined)
         return emptyBatch();
@@ -205,7 +220,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
     }
     // Snapshots may cache the plaintext state of touched aggregates.
     if (!options.dryRun && touchedAggregates.size > 0) {
-        const deleted = await raw.unsafe(`DELETE FROM "kumiko_snapshots" WHERE "aggregate_id" = ANY($1::uuid[]) RETURNING "aggregate_id"`, [[...touchedAggregates]]);
+        const deleted = await raw.unsafe(`DELETE FROM "kumiko_snapshots" WHERE "aggregate_id" = ANY($1::uuid[]) RETURNING "aggregate_id"`, [toPostgresArrayLiteral([...touchedAggregates])]);
         result.deletedSnapshots = deleted.length;
     }
     return {
@@ -250,7 +265,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
             // aborts the surrounding transaction (25P02). Entity never mounted/rebuilt
             // → stage 3 still gets a chance; this batch just contributes no owners.
             if (await tableExists(db, `public.${tableName}`)) {
-                const projectionRows = await raw.unsafe(`SELECT * FROM ${quoteIdent(tableName)} WHERE "id" = ANY($1::uuid[])`, [[...ids]]);
+                const projectionRows = await raw.unsafe(`SELECT * FROM ${quoteIdent(tableName)} WHERE "id" = ANY($1::uuid[])`, [toPostgresArrayLiteral([...ids])]);
                 for (const projectionRow of projectionRows) {
                     const id = projectionRow["id"];
                     if (typeof id === "string") {
@@ -456,24 +471,20 @@ function projectionOwnerRowOfTenant(owner, tenantId) {
         return undefined;
     return owner.tenantId === undefined || owner.tenantId === tenantId ? owner.fields : undefined;
 }
-function isPlainUserOwnedField(entity, field) {
-    const fieldDef = entity.fields[field];
-    if (fieldDef === undefined || !("userOwned" in fieldDef) || fieldDef.userOwned === undefined) {
-        return false;
-    }
-    return !("recordOwned" in fieldDef && fieldDef.recordOwned === true);
-}
 // Stage 4. In dryRun the "rekeyed" value is the untouched ciphertext (nothing is written).
 async function rekeyTenantKeyedValue(deps, target) {
     const { entity, field, ciphertext } = target;
-    if (!isPlainUserOwnedField(entity, field) || !isTenantKeyedUnder(ciphertext, target.tenantId)) {
+    const fieldDef = entity.fields[field];
+    if (fieldDef === undefined || !isPlainUserOwnedField(fieldDef))
         return { kind: "unchanged" };
-    }
-    const resolution = resolveOwnerSubject(entity, field, target.subjectSource, target.ownerFallback, target.projectionOwnerRow, target.tenantId, target.aggregateType);
-    if (resolution.kind !== "resolved" || resolution.subject.kind !== "user") {
+    const keyedUnder = ciphertextSubjectOrNull(ciphertext);
+    const userSubject = keyedUnder?.kind === "tenant" && keyedUnder.tenantId === target.tenantId
+        ? ownerOfTenantKeyedValue(target)
+        : keyedUnder?.kind === "user"
+            ? currentProjectionOwnerIfOther(target, keyedUnder.userId)
+            : null;
+    if (userSubject === null)
         return { kind: "unchanged" };
-    }
-    const userSubject = resolution.subject;
     if (await deps.isForgottenSubject(userSubject))
         return { kind: "erased" };
     if (deps.dryRun) {
@@ -494,16 +505,32 @@ async function rekeyTenantKeyedValue(deps, target) {
         throw e;
     }
 }
-// Only the row's own tenant key counts: another tenant's or a user's key is
+// Strict chain (payload, then projection), never whenAbsent.
+function ownerOfTenantKeyedValue(target) {
+    const resolution = resolveOwnerSubject(target.entity, target.field, target.subjectSource, target.ownerFallback, target.projectionOwnerRow, target.tenantId, target.aggregateType);
+    return resolution.kind === "resolved" && resolution.subject.kind === "user"
+        ? resolution.subject
+        : null;
+}
+// A value keyed under a previous owner moves to the owner the row has now. The
+// projection of the event's own tenant is authoritative here: the payload of
+// an old created event still names the owner the row had back then.
+function currentProjectionOwnerIfOther(target, keyedUserId) {
+    const fieldDef = target.entity.fields[target.field];
+    if (fieldDef === undefined || !("userOwned" in fieldDef) || !fieldDef.userOwned)
+        return null;
+    const owner = nonEmptyString(target.projectionOwnerRow?.[fieldDef.userOwned.ownerField]);
+    return owner === null || owner === keyedUserId ? null : { kind: "user", userId: owner };
+}
+// Only the row's own tenant key or a user key counts: another tenant's key is
 // never decrypted here.
-function isTenantKeyedUnder(ciphertext, tenantId) {
+function ciphertextSubjectOrNull(ciphertext) {
     try {
-        const subject = piiCiphertextSubject(ciphertext);
-        return subject.kind === "tenant" && subject.tenantId === tenantId;
+        return piiCiphertextSubject(ciphertext);
     }
     catch {
         // skip: a malformed ciphertext prefix is not ours to re-key
-        return false;
+        return null;
     }
 }
 function attemptResolve(entity, field, source, opts) {
@@ -516,6 +543,17 @@ function attemptResolve(entity, field, source, opts) {
         return { ok: false, error: e };
     }
 }
+// An explicit owner key (even null) means the event itself knows the row had no
+// owner then; only a missing key predates the owner field and may use the
+// projection's current owner.
+function payloadNamesOwnerKey(entity, field, subjectSource, ownerFallback) {
+    const fieldDef = entity.fields[field];
+    if (fieldDef === undefined || !("userOwned" in fieldDef) || !fieldDef.userOwned)
+        return false;
+    const { ownerField } = fieldDef.userOwned;
+    return (Object.hasOwn(subjectSource, ownerField) ||
+        (ownerFallback !== undefined && Object.hasOwn(ownerFallback, ownerField)));
+}
 // Stage 1 (payload) and stage 2 (projection row, when supplied) resolve the
 // owner strictly, ignoring whenAbsent — an ownerless payload must not shadow
 // an owner the projection knows. Stage 2b then applies whenAbsent to the
@@ -529,7 +567,7 @@ function resolveOwnerSubject(entity, field, subjectSource, ownerFallback, projec
             ? { kind: "unannotated" }
             : { kind: "resolved", subject: payloadAttempt.subject, viaProjection: false };
     }
-    if (projectionOwnerRow) {
+    if (projectionOwnerRow && !payloadNamesOwnerKey(entity, field, subjectSource, ownerFallback)) {
         const augmented = { ...subjectSource, ...projectionOwnerRow };
         const projectionAttempt = attemptResolve(entity, field, augmented, strictOpts);
         if (projectionAttempt.ok && projectionAttempt.subject !== null) {

package/dist/db/queries/event-consumer.js

@@ -1,4 +1,5 @@
 import { asRawClient } from "../query.js";
+import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 // Per-turn snapshot bounds for pending-gap finality (event-dispatcher.ts's
 // processConsumer). pg_current_snapshot() is this transaction's MVCC view;
 // xmin is the oldest still-in-progress xact id in it, xmax the next
@@ -123,7 +124,7 @@ export async function selectProvablyIdleConsumerPairs(db, names, instanceIds, de
        AND "pending_gaps" = '[]'::jsonb
        AND NOT EXISTS (
          SELECT 1 FROM "kumiko_events" e WHERE e."id" > c."last_processed_event_id"
-       )`, [names, instanceIds, deadStatus]);
+       )`, [toPostgresArrayLiteral(names), toPostgresArrayLiteral(instanceIds), deadStatus]);
     return rows.map((r) => ({ name: r.name, instanceId: r.instance_id }));
 }
 export async function selectConsumerForUpdateSkipLocked(db, name, instanceId) {

package/dist/db/queries/event-store-transfer.js

@@ -4,12 +4,18 @@
 // backfill-pii.ts): the one place in the repo allowed to write tenant_id
 // directly onto kumiko_events / kumiko_snapshots / kumiko_archived_streams.
 import { asRawClient } from "../query.js";
+import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 // Postgres' RETURNING clause has no DISTINCT keyword — dedupe the
 // per-event-row hits in-process instead of relying on invalid SQL.
 export async function transferEventRows(db, params) {
     const rows = await asRawClient(db).unsafe(`UPDATE "kumiko_events" SET "tenant_id" = $1 ` +
-        `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4) ` +
-        `RETURNING "aggregate_id" AS id`, [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds]);
+        `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4::uuid[]) ` +
+        `RETURNING "aggregate_id" AS id`, [
+        params.destinationTenantId,
+        params.sourceTenantId,
+        params.aggregateType,
+        toPostgresArrayLiteral(params.aggregateIds),
+    ]);
     return [...new Set(rows.map((row) => row.id))];
 }
 // Snapshots are a pure read-performance cache (event-store/snapshot.ts) —
@@ -17,7 +23,7 @@ export async function transferEventRows(db, params) {
 // events on next read instead of carrying the snapshot's own generation
 // bookkeeping across the tenant boundary.
 export async function deleteSnapshotsForAggregates(db, params) {
-    await asRawClient(db).unsafe(`DELETE FROM "kumiko_snapshots" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2)`, [params.tenantId, params.aggregateIds]);
+    await asRawClient(db).unsafe(`DELETE FROM "kumiko_snapshots" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2::uuid[])`, [params.tenantId, toPostgresArrayLiteral(params.aggregateIds)]);
 }
 // An archived stream's marker must move with it — leaving it behind would
 // make the stream writable again the instant it lands in the destination
@@ -27,5 +33,10 @@ export async function deleteSnapshotsForAggregates(db, params) {
 // moved aggregate's id must stay in the source tenant.
 export async function transferArchivedStreamRows(db, params) {
     await asRawClient(db).unsafe(`UPDATE "kumiko_archived_streams" SET "tenant_id" = $1 ` +
-        `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4)`, [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds]);
+        `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4::uuid[])`, [
+        params.destinationTenantId,
+        params.sourceTenantId,
+        params.aggregateType,
+        toPostgresArrayLiteral(params.aggregateIds),
+    ]);
 }

package/dist/db/queries/event-store.js

@@ -1,5 +1,6 @@
 import { constraintOf, isLockNotAvailable, isTableAlreadyExists, isUniqueViolation, } from "../pg-error.js";
-import { asRawClient, runInNewTransaction, unsafeReadRetrying } from "../query.js";
+import { asRawClient, runInNewTransaction, runnerCanBeginTransaction, unsafeReadRetrying, } from "../query.js";
+import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 // Gap-finality (event-dispatcher pending_gaps) needs every holder of an
 // event id to already have a *real* xact id by the time it inserts — Postgres
 // assigns those lazily on first write, so a bare INSERT alone doesn't
@@ -12,12 +13,9 @@ export async function claimXactId(db) {
 // notify would be three commits and the claimed xact id would be released before
 // the insert's. A pool runner (has begin()) therefore gets one transaction around
 // the whole write; inside a caller's tx or savepoint the caller's tx already is
-// that unit. Bun.SQL's TransactionSQL extends SQL and still exposes begin(), so
-// only a runner without savepoint() counts as a pool.
+// that unit.
 export async function runAtomicEventWrite(db, write) {
-    const raw = asRawClient(db);
-    const isPool = typeof raw.begin === "function" && typeof raw.savepoint !== "function";
-    if (!isPool)
+    if (!runnerCanBeginTransaction(db))
         return write(db);
     return runInNewTransaction(db, (tx) => write(tx));
 }
@@ -175,7 +173,7 @@ export async function selectStreamMaxVersions(db, aggregateIds, tenantId) {
     const versions = new Map();
     if (aggregateIds.length === 0)
         return versions;
-    const rows = await unsafeReadRetrying(db, `SELECT "aggregate_id" AS id, MAX("version") AS v FROM "kumiko_events" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2::uuid[]) GROUP BY "aggregate_id"`, [tenantId, [...aggregateIds]]);
+    const rows = await unsafeReadRetrying(db, `SELECT "aggregate_id" AS id, MAX("version") AS v FROM "kumiko_events" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2::uuid[]) GROUP BY "aggregate_id"`, [tenantId, toPostgresArrayLiteral(aggregateIds)]);
     for (const row of rows) {
         if (row.v !== null)
             versions.set(row.id, row.v);
@@ -260,8 +258,8 @@ export async function selectPendingAndNewEventRows(db, cursor, pendingRanges, ba
      (SELECT * FROM "kumiko_events" WHERE "id" > $1 ORDER BY "id" ASC LIMIT $4)
      ORDER BY "id" ASC LIMIT $4`, [
         cursor,
-        pendingRanges.map((r) => r.from.toString()),
-        pendingRanges.map((r) => r.to.toString()),
+        toPostgresArrayLiteral(pendingRanges.map((r) => r.from)),
+        toPostgresArrayLiteral(pendingRanges.map((r) => r.to)),
         batchSize,
     ]);
 }
@@ -274,7 +272,10 @@ export async function selectSmallestVisibleIdInRanges(db, pendingRanges) {
     const rows = await unsafeReadRetrying(db, `SELECT MIN("id")::text AS id FROM "kumiko_events"
      WHERE EXISTS (
        SELECT 1 FROM unnest($1::bigint[], $2::bigint[]) AS g(f, t) WHERE "id" BETWEEN g.f AND g.t
-     )`, [pendingRanges.map((r) => r.from.toString()), pendingRanges.map((r) => r.to.toString())]);
+     )`, [
+        toPostgresArrayLiteral(pendingRanges.map((r) => r.from)),
+        toPostgresArrayLiteral(pendingRanges.map((r) => r.to)),
+    ]);
     const id = rows[0]?.id;
     return id === null || id === undefined ? null : BigInt(id);
 }

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

@@ -1,4 +1,5 @@
 import { asRawClient } from "../query.js";
+import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 export async function readPiiBackfillState(db, fingerprint) {
     const rows = await asRawClient(db).unsafe(`SELECT "cursor_event_id"::text AS "cursor", "completed_at" IS NOT NULL AS "completed",
             "failed_event_ids"::text[] AS "failedEventIds"
@@ -19,7 +20,7 @@ export async function persistPiiBackfillState(db, fingerprint, update) {
         fingerprint,
         update.cursor.toString(),
         update.markCompleted,
-        [...update.addFailedEventIds],
-        [...update.removeFailedEventIds],
+        toPostgresArrayLiteral(update.addFailedEventIds),
+        toPostgresArrayLiteral(update.removeFailedEventIds),
     ]);
 }

package/dist/db/queries/postgres-array-literal.d.ts

@@ -0,0 +1,2 @@
+export type PostgresArrayElement = string | number | bigint | null;
+export declare function toPostgresArrayLiteral(values: readonly PostgresArrayElement[]): string;

package/dist/db/queries/postgres-array-literal.js

@@ -0,0 +1,6 @@
+// Bun.SQL stringifies JS arrays via toString, so array params travel as a
+// Postgres array-literal string (`$1::text[]`) — identical on postgres-js and Bun.SQL.
+export function toPostgresArrayLiteral(values) {
+    const elements = values.map((value) => value === null ? "NULL" : `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
+    return `{${elements.join(",")}}`;
+}

package/dist/db/queries/projection-rebuild.js

@@ -1,4 +1,5 @@
 import { asRawClient, unsafeReadRetrying } from "../query.js";
+import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 export async function markProjectionRebuilding(db, projectionName) {
     await asRawClient(db).unsafe(`INSERT INTO "kumiko_projections" ("name", "status") VALUES ($1, 'rebuilding')
      ON CONFLICT ("name") DO UPDATE SET
@@ -23,7 +24,7 @@ export async function selectEventsForProjectionRebuildBatch(db, aggregateTypes,
           WHERE a."tenant_id" = e."tenant_id" AND a."aggregate_id" = e."aggregate_id"
        )
      ORDER BY e."id" ASC
-     LIMIT $4`, [aggregateTypes, eventTypes, afterId, limit]);
+     LIMIT $4`, [toPostgresArrayLiteral(aggregateTypes), toPostgresArrayLiteral(eventTypes), afterId, limit]);
 }
 // Total subscribed events in the log — same source/type filter as
 // selectEventsForProjectionRebuildBatch, no id cursor. Under the cutover fence
@@ -39,7 +40,7 @@ export async function countSubscribedEvents(db, aggregateTypes, eventTypes) {
        AND NOT EXISTS (
          SELECT 1 FROM "kumiko_archived_streams" a
           WHERE a."tenant_id" = e."tenant_id" AND a."aggregate_id" = e."aggregate_id"
-       )`, [aggregateTypes, eventTypes]);
+       )`, [toPostgresArrayLiteral(aggregateTypes), toPostgresArrayLiteral(eventTypes)]);
     const raw = rows[0]?.n;
     if (typeof raw === "bigint")
         return raw;

package/dist/db/queries/shadow-swap.d.ts

@@ -9,7 +9,7 @@ export declare function assertLiveColumnsMatchMeta(db: DbConnection | DbTx, meta
 export declare function assertLiveTableHasNoRowLevelSecurity(tx: AnyDb, tableName: string, projectionName?: string): Promise<void>;
 export declare function buildShadowTable(tx: AnyDb, meta: EntityTableMeta): Promise<void>;
 export declare function fenceLiveTable(tx: AnyDb, tableName: string, lockTimeoutMs: number): Promise<void>;
-export declare function assertNoUnreachableLiveRows(tx: AnyDb, projectionName: string, tableName: string, aggregateTypes: readonly string[], derivedRowIds?: Readonly<Record<string, ProjectionRowIdOf>>): Promise<void>;
+export declare function assertNoUnreachableLiveRows(tx: AnyDb, projectionName: string, tableName: string, aggregateTypes: readonly string[], derivedRowIds?: Readonly<Record<string, ProjectionRowIdOf>>, derivedRowIdBatchSize?: number): Promise<void>;
 export declare function assertNoBlindIndexLoss(tx: AnyDb, tableName: string, meta: EntityTableMeta, projectionName: string): Promise<void>;
 export type ColumnDriftResult = {
     readonly rowCount: number;

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

@@ -22,6 +22,7 @@ import { configuredBlindIndexKey } from "../../crypto/index.js";
 import { asEntityTableMeta, asRawClient } from "../query.js";
 import { renderTableDdl } from "../render-ddl.js";
 import { columnNamesOf, tableExists } from "../schema-inspection.js";
+import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 import { quoteTableIdent } from "./table-ops.js";
 export const PROJECTION_REBUILD_SCHEMA = "kumiko_rebuild";
 const SCHEMA_IDENT = quoteTableIdent(PROJECTION_REBUILD_SCHEMA);
@@ -187,15 +188,18 @@ const UNREACHABLE_SAMPLE_LIMIT = 20;
 // strict — a row keyed by the raw aggregate id of a derived stream is a ghost.
 const DERIVED_ROW_ID_BATCH_SIZE = 5000;
 const DERIVED_ROW_ID_TABLE = "pg_temp.kumiko_derived_row_ids";
-async function fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf) {
+async function fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf, batchSize) {
     let cursor;
     for (;;) {
-        const page = await raw.unsafe(`SELECT DISTINCT "tenant_id"::text AS tenant_id, "aggregate_id"::text AS aggregate_id
+        const page = await raw.unsafe(
+        // Selecting the uuid columns (no text alias) keeps ORDER BY and the keyset
+        // comparison on the same type; text ordering is collation-dependent.
+        `SELECT DISTINCT "tenant_id", "aggregate_id"
          FROM "kumiko_events"
         WHERE "aggregate_type" = $1
           ${cursor ? `AND ("tenant_id", "aggregate_id") > ($2::uuid, $3::uuid)` : ""}
         ORDER BY "tenant_id", "aggregate_id"
-        LIMIT ${DERIVED_ROW_ID_BATCH_SIZE}`, cursor ? [aggregateType, cursor.tenant_id, cursor.aggregate_id] : [aggregateType]);
+        LIMIT ${batchSize}`, cursor ? [aggregateType, cursor.tenant_id, cursor.aggregate_id] : [aggregateType]);
         // skip: keyset exhausted — every source event of this type has been mapped
         if (page.length === 0)
             return;
@@ -212,14 +216,14 @@ async function fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf
             }
             return derived;
         });
-        await raw.unsafe(`INSERT INTO ${DERIVED_ROW_ID_TABLE} ("id") SELECT unnest($1::uuid[]) ON CONFLICT DO NOTHING`, [derivedIds]);
+        await raw.unsafe(`INSERT INTO ${DERIVED_ROW_ID_TABLE} ("id") SELECT unnest($1::uuid[]) ON CONFLICT DO NOTHING`, [toPostgresArrayLiteral(derivedIds)]);
         // skip: a short page is the last one
-        if (page.length < DERIVED_ROW_ID_BATCH_SIZE)
+        if (page.length < batchSize)
             return;
         cursor = page[page.length - 1];
     }
 }
-export async function assertNoUnreachableLiveRows(tx, projectionName, tableName, aggregateTypes, derivedRowIds = {}) {
+export async function assertNoUnreachableLiveRows(tx, projectionName, tableName, aggregateTypes, derivedRowIds = {}, derivedRowIdBatchSize = DERIVED_ROW_ID_BATCH_SIZE) {
     // skip: no source streams → no events could back any row anyway; a rebuild
     // of a subscription-less projection swaps an empty shadow (handled upstream).
     if (aggregateTypes.length === 0)
@@ -237,7 +241,7 @@ export async function assertNoUnreachableLiveRows(tx, projectionName, tableName,
             // skip: filtered by derivedTypes above, narrows the Record lookup for the compiler
             if (rowIdOf === undefined)
                 continue;
-            await fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf);
+            await fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf, derivedRowIdBatchSize);
         }
     }
     const unbackedClauses = [];
@@ -252,7 +256,7 @@ export async function assertNoUnreachableLiveRows(tx, projectionName, tableName,
     }
     const ghosts = await raw.unsafe(`SELECT l."id" FROM public.${t} l
      WHERE ${unbackedClauses.join(" AND ")}
-     LIMIT ${UNREACHABLE_SAMPLE_LIMIT}`, directTypes.length > 0 ? [directTypes] : []);
+     LIMIT ${UNREACHABLE_SAMPLE_LIMIT}`, directTypes.length > 0 ? [toPostgresArrayLiteral(directTypes)] : []);
     // skip: every live row has a backing event — nothing unreachable, swap is safe
     if (ghosts.length === 0)
         return;

package/dist/db/query.d.ts

@@ -1 +1 @@
-export { type AnyDb, aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, type JsonTextMatch, type OrderByClause, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, type SelectOptions, selectMany, type TableInfo, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, type WhereObject, type WhereOperator, type WhereValue, } from "../bun-db/query.js";
+export { type AnyDb, aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, type JsonTextMatch, type OrderByClause, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, type SelectOptions, selectMany, type TableInfo, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, type WhereObject, type WhereOperator, type WhereValue, } from "../bun-db/query.js";

package/dist/db/query.js

@@ -1,3 +1,3 @@
 // Provider-neutrale Query-API. Re-exported aus bun-db/query.
 // Alle Consumer importieren von hier, nicht direkt aus bun-db/.
-export { aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOne, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "../bun-db/query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOne, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "../bun-db/query.js";

package/dist/db/retired-framework-tables.js

@@ -14,10 +14,23 @@ export const retiredFrameworkTables = [
         explanation: "replaced by store_job_runs; the job run history was not migrated (operational data, not a system of record)",
     },
 ];
-const IDENT = `"?([^"\\s(;,.]+)"?`;
+// Optional schema prefix is skipped; only the table name is captured.
+const IDENT = `(?:"?[^"\\s(;,.]+"?\\.)?"?([^"\\s(;,.]+)"?`;
 const CREATE_TABLE_RE = new RegExp(`^CREATE TABLE\\s+(?:IF NOT EXISTS\\s+)?${IDENT}`, "i");
-const DROP_TABLE_RE = new RegExp(`^DROP TABLE\\s+(?:IF EXISTS\\s+)?${IDENT}`, "i");
+// DROP TABLE accepts a comma list; the list is split and each entry parsed with IDENT.
+const DROP_TABLE_LIST_RE = /^DROP TABLE\s+(?:IF EXISTS\s+)?([^;]+)/i;
+const IDENT_ONLY_RE = new RegExp(`^\\s*${IDENT}`);
+const RENAME_TABLE_RE = new RegExp(`^ALTER TABLE\\s+(?:IF EXISTS\\s+)?(?:ONLY\\s+)?${IDENT}\\s+RENAME TO\\s+${IDENT}`, "i");
 const COMMENTED_DROP_TABLE_RE = new RegExp(`^--\\s*DESTRUCTIVE:\\s*DROP TABLE\\s+(?:IF EXISTS\\s+)?${IDENT}`, "i");
+function droppedTableNames(line) {
+    const list = DROP_TABLE_LIST_RE.exec(line)?.[1];
+    if (list === undefined)
+        return [];
+    return list
+        .split(",")
+        .map((entry) => IDENT_ONLY_RE.exec(entry)?.[1])
+        .filter((name) => name !== undefined);
+}
 // Last known state per table across all migrations, in order — so a
 // DROP followed by a re-CREATE (managed-projection recreate) counts as
 // "created", and a commented drop followed by an executable one as "dropped".
@@ -38,8 +51,13 @@ function scanTableLifecycle(sqlTexts) {
                 states.set(created, "created");
                 continue;
             }
-            const dropped = DROP_TABLE_RE.exec(line)?.[1];
-            if (dropped !== undefined)
+            const renamed = RENAME_TABLE_RE.exec(line);
+            if (renamed?.[1] !== undefined && renamed[2] !== undefined) {
+                states.set(renamed[1], "dropped");
+                states.set(renamed[2], "created");
+                continue;
+            }
+            for (const dropped of droppedTableNames(line))
                 states.set(dropped, "dropped");
         }
     }

package/dist/db/table-builder.js

@@ -378,8 +378,12 @@ export function buildEntityTable(entityName, entity, options) {
             // entity.indexes[].where is now a SqlExpression (was drizzle SQL).
             // Pass through to the IndexBuilderWithCols.where()-API.
             if (def.where !== undefined) {
-                if (isSqlExpression(def.where))
-                    chain = chain.where(def.where);
+                // A silently dropped where would build a full (unique) index that
+                // entity-table-meta flags as needsManualWhere.
+                if (!isSqlExpression(def.where)) {
+                    throw new Error(`[${tableName}] index "${indexName}": where must be a sql\`...\` expression`);
+                }
+                chain = chain.where(def.where);
             }
             else if (def.unique === true && entity.softDelete === true) {
                 // Soft-deleted rows keep their value, so a full unique index would

package/dist/db/tenant-db.d.ts

@@ -19,6 +19,7 @@ export declare function createSystemDbView(db: TenantDb, dbOutsideTransaction?:
 export declare function scopeTenantDbToTenant(db: TenantDb, tenantId: TenantId): TenantDb;
 export declare function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[];
 export { tableNameOf };
+export declare function requestedTenantIds(requested: unknown): readonly unknown[] | undefined;
 export declare function hasTenantColumn(table: Table | EntityTableMeta): boolean;
 export type TenantDbGrants = {
     readonly globalWrites?: EscapeHatchDeclaration;
@@ -37,4 +38,5 @@ export declare function acknowledgeConventionCrossTenant(tenantDb: TenantDb, rea
 export declare function reportConventionCrossTenantUse(acknowledged: TenantDb, target?: EscapeHatchTarget): void;
 export declare function runInOwnTransaction<T>(tenantDb: TenantDb, fn: (txDb: TenantDb) => Promise<T>): Promise<T>;
 export declare function createTenantDb(db: DbRunner, tenantId: TenantId, mode?: TenantDbMode, tracer?: Tracer, meter?: Meter, signal?: AbortSignal, grants?: TenantDbGrants): TenantDb;
+export declare function createProjectingTenantDb(db: DbRunner, tenantId: TenantId, projectionRegistry: Registry | undefined): TenantDb;
 export { asRawClient };

package/dist/db/tenant-db.js

@@ -1,4 +1,5 @@
 import { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 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";
@@ -235,6 +236,19 @@ export { tableNameOf };
 function hasGrant(decl) {
     return decl !== undefined && decl.reason.trim().length > 0;
 }
+// Tenant ids a where.tenantId filter asks for; undefined for operator forms
+// that cannot narrow to a tenant list (ne, like, ...).
+export function requestedTenantIds(requested) {
+    if (Array.isArray(requested))
+        return requested;
+    if (!isPlainObject(requested))
+        return [requested];
+    if (Array.isArray(requested["in"]))
+        return requested["in"];
+    if ("eq" in requested)
+        return [requested["eq"]];
+    return undefined;
+}
 function isForeignTenantId(tenantIdValue) {
     return tenantIdValue !== undefined && tenantIdValue !== SYSTEM_TENANT_ID;
 }
@@ -360,7 +374,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         const allowed = [tenantId, SYSTEM_TENANT_ID];
         const requested = where?.["tenantId"];
         if (requested !== undefined) {
-            const requestedList = Array.isArray(requested) ? requested : [requested];
+            const requestedList = requestedTenantIds(requested) ?? [];
             const narrowed = requestedList.filter((t) => typeof t === "string" && allowed.includes(t));
             return { ...where, tenantId: narrowed.length > 0 ? narrowed : allowed };
         }
@@ -605,4 +619,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         bindProjectionRegistry(tenantDb, projectionRegistry);
     return tenantDb;
 }
+// Tenant-mode TenantDb whose writes reach the registry's custom projections. The positional
+// undefineds of createTenantDb would hide a moved grants parameter from the type checker.
+export function createProjectingTenantDb(db, tenantId, projectionRegistry) {
+    return createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, projectionRegistry ? { projectionRegistry } : undefined);
+}
 export { asRawClient };

package/dist/derivatives/delete-stored-file.d.ts

@@ -1,6 +1,10 @@
+import type { FileContext } from "@cosmicdrift/kumiko-types/file-handle-types";
 export type StoredFileStore = {
     list(prefix: string): Promise<readonly string[]>;
     delete(key: string): Promise<void>;
 };
 export declare function listDerivativeKeys(originalKey: string, store: Pick<StoredFileStore, "list">, errorContext: string): Promise<readonly string[]>;
 export declare function deleteStoredFileAndDerivatives(originalKey: string, store: StoredFileStore, errorContext: string): Promise<readonly string[]>;
+export declare function deleteFileRefBytes(files: FileContext, row: {
+    readonly storageKey: string;
+}, errorContext: string): Promise<readonly string[]>;

package/dist/derivatives/delete-stored-file.js

@@ -68,3 +68,12 @@ export async function deleteStoredFileAndDerivatives(originalKey, store, errorCo
     }
     return failedKeys;
 }
+// deleteStoredFileAndDerivatives through ctx.files for a key read from a tenant-filtered fileRef
+// row. After a tenant handover the key keeps the previous tenant's prefix, which ref() and list()
+// reject; every key the helper deletes is the original or one of its derivatives.
+export function deleteFileRefBytes(files, row, errorContext) {
+    return deleteStoredFileAndDerivatives(row.storageKey, {
+        list: () => files.listFromFileRef(row),
+        delete: (key) => files.refFromFileRef({ storageKey: key }).delete(),
+    }, errorContext);
+}

package/dist/derivatives/index.d.ts

@@ -1,5 +1,5 @@
 export type { StoredFileStore } from "./delete-stored-file.js";
-export { deleteStoredFileAndDerivatives, listDerivativeKeys } from "./delete-stored-file.js";
+export { deleteFileRefBytes, deleteStoredFileAndDerivatives, listDerivativeKeys, } from "./delete-stored-file.js";
 export type { DerivativesContextDeps } from "./derivatives-context.js";
 export { createDerivativesContext, resolveRenderer } from "./derivatives-context.js";
 export { resolveFieldVariant } from "./field-variants.js";

package/dist/derivatives/index.js

@@ -1,4 +1,4 @@
-export { deleteStoredFileAndDerivatives, listDerivativeKeys } from "./delete-stored-file.js";
+export { deleteFileRefBytes, deleteStoredFileAndDerivatives, listDerivativeKeys, } from "./delete-stored-file.js";
 export { createDerivativesContext, resolveRenderer } from "./derivatives-context.js";
 export { resolveFieldVariant } from "./field-variants.js";
 export { canonicalJson, derivativeListPrefix, isDerivativeKeyOf, parseDerivativeKey, specHash, VARIANT_NAME_PATTERN, variantSuffix, } from "./variant-key.js";

package/dist/engine/boot-validator/entity-handler.js

@@ -929,6 +929,9 @@ export function validateLockedWhen(feature) {
         if (isCiphertextAtRest(field)) {
             throw new Error(`${where} is personal or encrypted — the lock condition is evaluated on the stored value, which is ciphertext. Use a plaintext field.`);
         }
+        if (field.access?.read !== undefined) {
+            throw new Error(`${where} has a read restriction — roles that cannot read it get records without it, and the client would show every record as locked. Drop field access.read or use another field.`);
+        }
         if (!LOCKABLE_FIELD_TYPES.has(field.type)) {
             throw new Error(`${where} has type "${field.type}", which does not store a plain scalar the condition can compare. Use a text, select, boolean, number or reference field.`);
         }