@cosmicdrift/kumiko-framework 0.363.0 → 0.364.0

package/dist/bun-db/query.js

@@ -21,7 +21,7 @@
 // Static import (not getTemporal()): coercion works without an installed
 // global and returns the same Temporal classes as the rest of the repo (#1480).
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { isOneOf, isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { isOneOf, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { requestContext } from "../api/request-context.js";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index.js";
 import { isPiiCiphertext } from "../crypto/pii-ciphertext-format.js";
@@ -50,6 +50,9 @@ function snakeToCamel(key) {
 // would overwrite the matching meta key — reading the meta from the symbol is
 // the only collision-safe path.
 export { asEntityTableMeta, requireEntityTableMeta };
+export function hasBegin(client) {
+    return typeof client.begin === "function";
+}
 function isRawClient(value) {
     return typeof propertyOf(value, "unsafe") === "function";
 }
@@ -77,6 +80,9 @@ export function asRawClient(db) {
         return sessionClient;
     throw new Error("bun-db: db argument has no .unsafe() — pass Bun.SQL, postgres-js Sql, or a transaction handle.");
 }
+export function runnerCanBeginTransaction(db) {
+    return hasBegin(asRawClient(db));
+}
 // postgres.js / Bun.SQL reject the WHOLE begin() when any statement inside
 // it errored — even if the JS error was caught (the driver tracks per-block
 // query failures). Error confinement therefore must go through the driver's
@@ -329,8 +335,10 @@ function plainDateFromDriver(value, column) {
 //
 // Unknown columns (computed/aliased) pass through unchanged.
 export function coerceRow(row, info) {
-    if (!isPlainObject(row))
-        return row;
+    // @cast-boundary db-row — the driver row (raw column names/types) becomes the caller's entity row shape here, and only here
+    return coerceDriverRow(row, info);
+}
+function coerceDriverRow(row, info) {
     const out = {};
     let changed = false;
     for (const key of Object.keys(row)) {
@@ -400,7 +408,7 @@ export function coerceRow(row, info) {
             changed = true;
         out[fieldName] = coerced;
     }
-    return (changed ? out : row);
+    return changed ? out : row;
 }
 function coerceRows(rows, info) {
     return rows.map((r) => coerceRow(r, info));
@@ -547,8 +555,14 @@ function buildWhereClause(info, where, startIndex, qualifier) {
                     throw new Error(`where: jsonText requires a jsonb column, "${col}" is ${pgType}`);
                 }
                 const matches = isJsonTextMatchList(value.jsonText) ? value.jsonText : [value.jsonText];
+                if (matches.length === 0) {
+                    conditions.push("FALSE");
+                    continue;
+                }
                 for (const match of matches) {
-                    if (!Array.isArray(match.keys) ||
+                    if (match === null ||
+                        typeof match !== "object" ||
+                        !Array.isArray(match.keys) ||
                         match.keys.length === 0 ||
                         !match.keys.every((k) => typeof k === "string") ||
                         typeof match.eq !== "string") {
@@ -1376,12 +1390,18 @@ export async function deleteManyBatched(db, table, where, options) {
     return { deleted, batches };
 }
 export async function transaction(db, fn) {
-    return asRawClient(db).begin(fn);
+    const raw = asRawClient(db);
+    if (!hasBegin(raw)) {
+        throw new InternalError({
+            message: "transaction: runner has no begin() — already inside a transaction or savepoint.",
+        });
+    }
+    return raw.begin(fn);
 }
 // A tx/savepoint handle has no begin(); fail closed instead of nesting silently or TypeError-ing.
 export async function runInNewTransaction(db, fn) {
     const raw = asRawClient(db);
-    if (typeof raw.begin !== "function") {
+    if (!hasBegin(raw)) {
         throw new InternalError({
             message: "runInNewTransaction: runner has no begin() — already inside a transaction or savepoint.",
         });

package/dist/db/collect-table-metas.js

@@ -15,6 +15,15 @@ function canonicalColumnsKey(meta) {
         .map((c) => `${c.name}|${c.pgType}|${c.notNull}|${c.defaultSql ?? ""}|${c.primaryKey ?? false}|${c.identity ?? false}|${c.bigintJsMode ?? ""}`)
         .join("\n");
 }
+function registerPass1Meta(metas, byName, meta, origin) {
+    const existing = byName.get(meta.tableName);
+    if (existing) {
+        throw new Error(`collectTableMetas: table "${meta.tableName}" is registered by ${origin} and ${existing.origin}. ` +
+            "Give one of them a different table name.");
+    }
+    metas.push(meta);
+    byName.set(meta.tableName, { meta, origin });
+}
 export function collectTableMetas(features) {
     const metas = [];
     const byName = new Map();
@@ -37,15 +46,10 @@ export function collectTableMetas(features) {
                 assertBackingTableSuperset(name, fieldMeta, tableMeta);
                 meta = tableMeta;
             }
-            metas.push(meta);
-            byName.set(meta.tableName, { meta, origin: `entity "${name}" (${feature.name})` });
+            registerPass1Meta(metas, byName, meta, `entity "${name}" (${feature.name})`);
         }
         for (const entry of Object.values(feature.storeTables)) {
-            metas.push(entry.meta);
-            byName.set(entry.meta.tableName, {
-                meta: entry.meta,
-                origin: `storeTable "${entry.name}" (${feature.name})`,
-            });
+            registerPass1Meta(metas, byName, entry.meta, `storeTable "${entry.name}" (${feature.name})`);
         }
     }
     // Pass 2: table-tragende Registrierungen. Zwei Pässe, damit eine Entity-

package/dist/db/eagerload.js

@@ -18,7 +18,7 @@
 // Custom handlers must pass the viewer explicitly so the parentRef gate is
 // never skipped silently.
 import { requestContext } from "../api/request-context.js";
-import { collectPiiEncryptedFields, configuredPiiSubjectKms, decryptPiiFieldValues, } from "../crypto/index.js";
+import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, } from "../crypto/index.js";
 import { selectMany } from "../db/query.js";
 import { filterReadFields } from "../engine/field-access.js";
 import { buildOwnershipClause, combineClauses, shiftParams, tableNameOf, } from "../engine/ownership.js";
@@ -162,7 +162,7 @@ export async function enrichWithReferences(rows, entity, resolveEntity, db, view
         const rawRefRows = scope.kind === "restricted"
             ? lookedUpRows.filter((r) => scope.readableIds.has(String(r["id"])))
             : lookedUpRows;
-        const piiFields = collectPiiEncryptedFields(refEntity);
+        const piiFields = collectPiiSubjectFields(refEntity);
         const encryptedFields = collectEncryptedFieldNames(refEntity);
         const kms = configuredPiiSubjectKms();
         const map = await buildRefLookupMap(rawRefRows, refEntity, rf.refEntityName, viewer, piiFields, encryptedFields, kms);

package/dist/db/event-store-executor-context.d.ts

@@ -33,15 +33,14 @@ export type ExecutorContext = {
         readonly includeDeleted?: boolean;
     }) => Promise<Record<string, unknown> | null>;
     readonly assertStreamWritable: (db: TenantDb, id: EntityId, tenantId: TenantId) => Promise<void>;
-    readonly loadWithOwnership: (db: TenantDb, idWhere: WhereObject, ownership: {
-        kind: "pass";
-    } | {
-        kind: "empty";
-    } | {
+    readonly probeOwnershipWithStreamVersion: (db: TenantDb, idWhere: WhereObject, ownership: {
         kind: "sql";
         sqlText: string;
         params: readonly unknown[];
-    }) => Promise<Record<string, unknown>[]>;
+    }, streamTenantId: TenantId, aggregateId: string) => Promise<{
+        readonly owned: boolean;
+        readonly streamVersion: number;
+    }>;
     readonly loadDetailSnapshot: (db: TenantDb, idWhere: WhereObject, ownership: {
         kind: "pass";
     } | {

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

@@ -1,5 +1,5 @@
 import { requestContext } from "../api/request-context.js";
-import { collectPiiEncryptedFields, configuredPiiSubjectKms, decryptPiiFieldValues, encryptPiiFieldValues, KeyErasedError, } from "../crypto/index.js";
+import { collectPiiEncryptedFields, collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, encryptPiiFieldValues, KeyErasedError, } from "../crypto/index.js";
 import { personalFieldsRekeyedOnOwnerTransition } from "../crypto/owner-transition-rekey.js";
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
 import { shiftParams } from "../engine/ownership.js";
@@ -173,6 +173,11 @@ export function buildExecutorContext(table, entity, options) {
     const hasEncryptedFields = encryptedFields.size > 0;
     const piiSubjectFields = collectPiiEncryptedFields(entity);
     const hasPiiFields = piiSubjectFields.length > 0;
+    // Decrypt keeps file-reference fields: rows and event payloads written by
+    // the old backfill may hold ciphertext there, and decrypt passes plaintext
+    // through untouched.
+    const piiDecryptFields = collectPiiSubjectFields(entity);
+    const hasPiiDecryptFields = piiDecryptFields.length > 0;
     function fieldCipher() {
         if (options.encryption)
             return options.encryption;
@@ -230,8 +235,8 @@ export function buildExecutorContext(table, entity, options) {
     async function decryptForRead(row, opts) {
         let out = row;
         const kms = piiKms();
-        if (hasPiiFields && kms) {
-            out = await decryptPiiFieldValues(out, piiSubjectFields, kms, kmsContextFor());
+        if (hasPiiDecryptFields && kms) {
+            out = await decryptPiiFieldValues(out, piiDecryptFields, kms, kmsContextFor());
         }
         if (hasEncryptedFields) {
             out = await decryptEntityFieldValues(out, encryptedFields, fieldCipher(), opts?.degradeUndecryptable
@@ -301,24 +306,6 @@ export function buildExecutorContext(table, entity, options) {
             throw new ArchivedStreamError(tenantId, String(id));
         }
     }
-    // SELECT a row by id with the ownership clause applied at the DB layer.
-    // Detail() uses this both on cold path and as a cache-revalidation probe.
-    async function loadWithOwnership(db, idWhere, ownership) {
-        if (ownership.kind === "empty")
-            return [];
-        if (ownership.kind === "pass") {
-            const row = await db.fetchOne(table, idWhere);
-            return row ? [row] : [];
-        }
-        // ownership has raw SQL — splice it into a raw query alongside the
-        // idFilter + tenant-filter that TenantDb would have added.
-        const tableName = String(schemaTableName(table));
-        const { whereParts, params } = buildRawIdWhere(db, idWhere, ownership);
-        const sqlText = `SELECT * FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
-        return [
-            ...(await executeRawQueryRead(tenantDbRunner(db), sqlText, params)),
-        ];
-    }
     // Tenant filter + idFilter + ownership predicate as raw SQL, mirroring what
     // TenantDb.fetchOne/readWhere add. idFilter only yields `id` and a boolean
     // `isDeleted`, so no null/IS NULL branch is needed.
@@ -351,6 +338,21 @@ export function buildExecutorContext(table, entity, options) {
         return (`(SELECT MAX("version") FROM "kumiko_events" WHERE "aggregate_id" = $${aggregateIdParam} ` +
             `AND "tenant_id" = $${tenantIdParam}) AS "__streamVersion"`);
     }
+    // Cache-hit revalidation: ownership predicate and live stream version in ONE
+    // statement, so a cache hit costs the same single roundtrip as the cold path.
+    async function probeOwnershipWithStreamVersion(db, idWhere, ownership, streamTenantId, aggregateId) {
+        const tableName = String(schemaTableName(table));
+        const { whereParts, params } = buildRawIdWhere(db, idWhere, ownership);
+        params.push(aggregateId, streamTenantId);
+        const sqlText = `SELECT 1 AS "__owned", ${streamVersionSubquerySql(params.length - 1, params.length)} ` +
+            `FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
+        const rows = await executeRawQueryRead(tenantDbRunner(db), sqlText, params);
+        const first = rows[0];
+        if (!first)
+            return { owned: false, streamVersion: 0 };
+        const version = first["__streamVersion"];
+        return { owned: true, streamVersion: typeof version === "number" ? version : 0 };
+    }
     // Row and MAX(version) in ONE statement: two reads can pair a post-write
     // version with a pre-write row, and update({version: detail.version}) would
     // then pass the optimistic lock and overwrite the newer write (lost update).
@@ -431,7 +433,7 @@ export function buildExecutorContext(table, entity, options) {
         idFilter,
         loadById,
         assertStreamWritable,
-        loadWithOwnership,
+        probeOwnershipWithStreamVersion,
         loadDetailSnapshot,
         loadExpectSnapshot,
         encryptForStorage,

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

@@ -6,7 +6,7 @@ import { coerceRow, extractTableInfo } from "../db/query.js";
 import { buildOwnershipClause, combineClauses, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { UnprocessableError } from "../errors/index.js";
-import { getStreamVersion, getStreamVersions } from "../event-store/index.js";
+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";
@@ -387,6 +387,7 @@ function referenceTargetTable(name, entity) {
 // 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";
+const STREAM_VERSION_ALIAS = "__streamVersion";
 // fw#2741 — resolve a `sortable: true` reference field's label inline for
 // ORDER BY. A correlated scalar subquery, not a join: the result set keeps one
 // row per entity row, the read model stays untouched, and the lookup rides the
@@ -448,7 +449,7 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
     };
 }
 export function createReadVerbs(ctx) {
-    const { table, entity, entityName, entityCache, searchAdapter, softDelete, streamTenantFor, idFilter, loadWithOwnership, loadDetailSnapshot, decryptForRead, encryptForStorage, } = ctx;
+    const { table, entity, entityName, entityCache, searchAdapter, softDelete, streamTenantFor, idFilter, probeOwnershipWithStreamVersion, loadDetailSnapshot, decryptForRead, encryptForStorage, } = ctx;
     return {
         // list + detail are unchanged from crud-executor — projections are the
         // read-model and serve these queries directly.
@@ -644,15 +645,28 @@ export function createReadVerbs(ctx) {
             const whereClauseSqlText = whereSql.length > 0 ? ` WHERE ${whereSql.join(" AND ")}` : "";
             // Project the resolved label too, so the keyset cursor below carries the
             // value that was ordered by rather than the FK column's UUID.
-            const selectList = referenceSortExpr !== undefined && sortSql !== undefined
-                ? `*, ${sortSql} AS "${SORT_LABEL_ALIAS}"`
-                : "*";
+            const sortLabelProjection = referenceSortExpr !== undefined && sortSql !== undefined
+                ? `, ${sortSql} AS "${SORT_LABEL_ALIAS}"`
+                : "";
+            // Stream version in the same statement as the rows: a separate read could pair a
+            // post-write version with a pre-write row, and update({version}) would then pass
+            // the optimistic lock against a state the client never saw (see loadDetailSnapshot).
+            params.push(streamTenantFor(user));
+            const streamVersionProjection = `, (SELECT MAX("version") FROM "kumiko_events" ` +
+                `WHERE "aggregate_id" = "${tableName}"."id" AND "tenant_id" = $${params.length}) ` +
+                `AS "${STREAM_VERSION_ALIAS}"`;
+            const selectList = `*${sortLabelProjection}${streamVersionProjection}`;
             const listSql = `SELECT ${selectList} FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
             const rawRows = await executeRawQueryRead(runner, listSql, params);
             const lastSortLabel = rawRows[rawRows.length - 1]?.[SORT_LABEL_ALIAS];
+            // Aliases are query artifacts, not columns of this entity — strip them before
+            // coercion so they never reach the caller or the entity cache.
+            const streamVersions = rawRows.map((r) => {
+                const v = r[STREAM_VERSION_ALIAS];
+                delete r[STREAM_VERSION_ALIAS];
+                return typeof v === "number" ? v : 0;
+            });
             if (referenceSortExpr !== undefined) {
-                // The alias is a sort artifact, not a column of this entity — strip it
-                // before coercion so it never reaches the caller or the entity cache.
                 for (const row of rawRows)
                     delete row[SORT_LABEL_ALIAS];
             }
@@ -668,10 +682,7 @@ export function createReadVerbs(ctx) {
             // Stream version is authoritative (see detail()): ctx.appendEvent bumps the
             // stream without touching row.version, so the raw row version would hand
             // clients a stale optimistic-lock base. Rows without events keep theirs.
-            const streamVersions = decryptedRows.length > 0
-                ? await getStreamVersions(runner, decryptedRows.map((r) => String(r["id"])), streamTenantFor(user))
-                : new Map();
-            const rows = decryptedRows.map((r) => withStreamVersion(r, streamVersions.get(String(r["id"])) ?? 0));
+            const rows = decryptedRows.map((r, i) => withStreamVersion(r, streamVersions[i] ?? 0));
             // Cache the still-encrypted raw rows (read-row version): same at-rest guarantee as
             // detail()'s encryptForStorage round-trip, without a re-encrypt; detail() rejects
             // a cached version that differs from the stream.
@@ -730,16 +741,20 @@ export function createReadVerbs(ctx) {
             if (entityCache && entityName) {
                 const cached = await entityCache.get(user.tenantId, entityName, payload.id);
                 if (cached) {
+                    let streamVersion;
                     if (ownership.kind === "sql") {
                         // Re-check ownership predicate (incl. the parent-ref gate) against
                         // the live row — the cache is keyed only by tenant + id, not by
-                        // role, so a cache hit can't bypass either gate. Deliberate price:
-                        // one extra roundtrip per cache hit once either gate produces SQL.
-                        const checkRows = await loadWithOwnership(db, idWhere, ownership);
-                        if (checkRows.length === 0)
+                        // role, so a cache hit can't bypass either gate. The probe carries
+                        // the stream version in the same statement.
+                        const probe = await probeOwnershipWithStreamVersion(db, idWhere, ownership, streamTenantFor(user), String(payload.id));
+                        if (!probe.owned)
                             return null;
+                        streamVersion = probe.streamVersion;
+                    }
+                    else {
+                        streamVersion = await getStreamVersion(tenantDbRunner(db), String(payload.id), streamTenantFor(user));
                     }
-                    const streamVersion = await getStreamVersion(tenantDbRunner(db), String(payload.id), streamTenantFor(user));
                     if (!(streamVersion > 0 && cached["version"] !== streamVersion)) {
                         // Cached rows are stored re-encrypted (see the `set` below) so an
                         // `encrypted` field's plaintext never sits in a second at-rest

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

@@ -3,7 +3,6 @@ import { instructionFieldNames } from "../engine/instruction-fields.js";
 import { userCanCreateFieldRow, userCanWriteFieldRow } from "../engine/ownership.js";
 import { buildInsertSchema, buildUpdateSchema } from "../engine/schema-builder.js";
 import { findUnavailableSelectOptions, isRecordLocked, } from "../engine/screen-helpers.js";
-import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
 import { AccessDeniedError, VersionConflictError as FrameworkVersionConflict, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RecordLockedError, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { append, IdempotentAppendConflictError as EventStoreIdempotentAppendConflict, VersionConflictError as EventStoreVersionConflict, getStreamVersion, } from "../event-store/index.js";
 import { assertInstructionFieldWriteAllowed, assertIrreversibleOperationAllowed, isIrreversibleEntityVerb, } from "../pipeline/irreversible-operation-gate.js";
@@ -12,10 +11,11 @@ import { generateId } from "../utils/index.js";
 import { applyEntityEvent } from "./apply-entity-event.js";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.js";
 import { buildEventMetadata, entityEventName, isForeignTenantOnGlobalEntity, ownershipSubject, tryMapUniqueViolation, } from "./event-store-executor-context.js";
+import { isFrameworkSystemUser, isLockGuardBypassed } from "./lock-guard.js";
 import { projectionRegistryOf } from "./projection-registry-binding.js";
 import { runInSavepointIfSupported } from "./query.js";
 import { assertPersonalDataWrite, tableNameOf } from "./tenant-db.js";
-import { tenantDbRunner } from "./tenant-db-runner.js";
+import { tenantDbWriteRunner } from "./tenant-db-runner.js";
 // Custom projections for a write that did not go through the dispatcher (hook or
 // job writing a second aggregate). Savepoint like applyEntityEvent: a throwing
 // projection fails the write and the caller's transaction rolls it back.
@@ -29,12 +29,6 @@ async function projectEntityEvent(db, runner, event) {
         return;
     await runInSavepointIfSupported(runner, (sp) => runProjectionsForEvent(event, registry, sp));
 }
-// Art. 17 erasure runs as the framework operator, not as a row owner; a
-// per-role ownership map can never cover it, and a silent deny means the
-// erasure never happened.
-function isFrameworkSystemUser(user) {
-    return user.id === SYSTEM_USER_ID && user.roles.includes(SYSTEM_ROLE);
-}
 // The five write verbs (create/update/delete/forget/restore) of the event-
 // store-executor. Split out of event-store-executor.ts (#1005, Welle 2) —
 // behavior-preserving relocation, not a redesign: every closure below is
@@ -126,9 +120,7 @@ export function createWriteVerbs(ctx) {
     // statutory deletion must reach locked rows, and forget (Art. 17) never checks the lock
     // at all. The options are server-code only; no request field is ever copied into them.
     function recordLockedFailure(row, id, user, options) {
-        if (options?.unsafeSkipLockGuard === true ||
-            (options?.writePurpose !== undefined && isFrameworkSystemUser(user)) ||
-            !isRecordLocked(entity.lockedWhen, row)) {
+        if (isLockGuardBypassed(user, options) || !isRecordLocked(entity.lockedWhen, row)) {
             return undefined;
         }
         return writeFailure(new RecordLockedError({ entityName, entityId: id }));
@@ -180,7 +172,7 @@ export function createWriteVerbs(ctx) {
             const streamTenantMismatch = streamTenantCreateFailure(db, payload, streamTenantId);
             if (streamTenantMismatch)
                 return streamTenantMismatch;
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor create");
             // 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.
@@ -349,7 +341,7 @@ export function createWriteVerbs(ctx) {
             };
         },
         async update(payload, user, db, updateOptions) {
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor update");
             if (isForeignTenantOnGlobalEntity(entity, payload.changes["tenantId"])) {
                 throw new AccessDeniedError({
                     message: `${entityName}.update: entity is tenancy: "global" — payload.changes.tenantId must ` +
@@ -582,7 +574,7 @@ export function createWriteVerbs(ctx) {
             if (isIrreversibleEntityVerb("delete", entity)) {
                 assertIrreversibleOperationAllowed(`${entityName}.delete (entity has no softDelete)`);
             }
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor delete");
             const existing = await loadById(payload.id, db);
             if (!existing)
                 return writeFailure(new NotFoundError(entityName, payload.id));
@@ -664,6 +656,7 @@ export function createWriteVerbs(ctx) {
                     data: existing,
                     entityName,
                     event: echoEvent,
+                    ...(isLockGuardBypassed(user, options) && { lockGuardBypassed: true }),
                 },
             };
         },
@@ -673,7 +666,7 @@ export function createWriteVerbs(ctx) {
         // without the isDeleted filter so trashed (soft-deleted) rows are erased too.
         async forget(payload, user, db, options) {
             assertIrreversibleOperationAllowed(`${entityName}.forget`);
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor forget");
             const raw = await db.fetchOne(table, { id: payload.id });
             if (!raw)
                 return writeFailure(new NotFoundError(entityName, payload.id));
@@ -744,6 +737,7 @@ export function createWriteVerbs(ctx) {
                     data: existing,
                     entityName,
                     event: echoEvent,
+                    lockGuardBypassed: true,
                 },
             };
         },
@@ -753,7 +747,7 @@ export function createWriteVerbs(ctx) {
                     i18nKey: "errors.softDeleteNotEnabled",
                 }));
             }
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor restore");
             const streamTenantId = options?.streamTenantId;
             const target = await loadSoftDeletedRow(db, payload.id, streamTenantId);
             if ("failure" in target)
@@ -780,8 +774,13 @@ export function createWriteVerbs(ctx) {
             // Restore carries the soft-deleted snapshot as `previous` — mirror of
             // delete for symmetry. Projections that decremented on delete use
             // `previous` to re-increment on restore without re-querying the entity
-            // table. `data` is the raw stored row — pii/encrypted fields are
-            // already ciphertext, no re-encrypt needed.
+            // table. Rows predating the subject-KMS rollout may still hold plaintext
+            // pii, and envelope encryption is not idempotent: decrypt, then
+            // re-encrypt as delete does.
+            const previousPlain = await decryptForRead(data);
+            const previousForStorage = await encryptForStorage(previousPlain, user, {
+                keyTenantId: streamTenantId,
+            });
             let event;
             try {
                 event = await runInSavepointIfSupported(runner, (sp) => append(sp, {
@@ -791,7 +790,7 @@ export function createWriteVerbs(ctx) {
                     expectedVersion: currentVersion,
                     type: entityEventName(entityName, "restored"),
                     eventVersion,
-                    payload: { previous: data },
+                    payload: { previous: previousForStorage },
                     metadata: buildEventMetadata(user),
                 }));
             }
@@ -835,7 +834,6 @@ export function createWriteVerbs(ctx) {
             // same as every other executor method — `data`/`restored` are raw rows
             // (db.fetchOne / applyEntityEvent), never decrypted before this point.
             const restoredHydrated = await decryptForRead(rehydrateCompoundTypes(restored, entity));
-            const previousPlain = await decryptForRead(data);
             const echoEvent = { ...event, payload: { previous: stripSensitive(previousPlain) } };
             await projectEntityEvent(db, runner, echoEvent);
             return {

package/dist/db/index.d.ts

@@ -35,4 +35,4 @@ export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFramework
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityTable, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
 export type { TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb } from "./tenant-db.js";
-export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, } from "./tenant-db.js";
+export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";

package/dist/db/index.js

@@ -27,4 +27,4 @@ export { diffReplayAgainstSnapshot, replayMigrationsDir, } from "./replay-migrat
 export { findCommentedDropTables, isRetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
-export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, } from "./tenant-db.js";
+export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";

package/dist/db/lock-guard.d.ts

@@ -0,0 +1,4 @@
+import type { SessionUser } from "../engine/types/index.js";
+import type { LockGuardOption } from "./event-store-executor.js";
+export declare function isFrameworkSystemUser(user: SessionUser): boolean;
+export declare function isLockGuardBypassed(user: SessionUser, options: LockGuardOption | undefined): boolean;

package/dist/db/lock-guard.js

@@ -0,0 +1,14 @@
+import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
+// Art. 17 erasure runs as the framework operator, not as a row owner; a
+// per-role ownership map can never cover it, and a silent deny means the
+// erasure never happened.
+export function isFrameworkSystemUser(user) {
+    return user.id === SYSTEM_USER_ID && user.roles.includes(SYSTEM_ROLE);
+}
+// Framework system writes that name a writePurpose (retention, erasure) are exempt:
+// statutory deletion must reach locked rows. The options are server-code only; no
+// request field is ever copied into them.
+export function isLockGuardBypassed(user, options) {
+    return (options?.unsafeSkipLockGuard === true ||
+        (options?.writePurpose !== undefined && isFrameworkSystemUser(user)));
+}

package/dist/db/migrate-generator.js

@@ -437,7 +437,7 @@ export function assertUniqueTableNames(metas) {
     const duplicates = [...counts].filter(([, count]) => count > 1);
     if (duplicates.length > 0) {
         throw new Error(duplicates
-            .map(([tableName, count]) => `ENTITY_METAS lists table "${tableName}" ${count} times — the migration diff would silently use only one definition. collectTableMetas(features) already includes every table a feature registers (r.storeTable, entities, projections); remove the hand-added meta for "${tableName}".`)
+            .map(([tableName, count]) => `ENTITY_METAS lists table "${tableName}" ${count} times — the migration diff would silently use only one definition. collectTableMetas(features) already includes every table a feature registers (r.storeTable, entities, projections); remove the duplicate entry for "${tableName}" (a hand-added meta, or two features registering the same table).`)
             .join("\n"));
     }
 }

package/dist/db/migrate-runner.js

@@ -17,7 +17,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
-import { asRawClient } from "../bun-db/query.js";
+import { asRawClient, hasBegin } from "../bun-db/query.js";
 // Advisory-lock key (random 32-bit int, stable). Verhindert dass zwei
 // gleichzeitig bootende Pods beide migrate apply laufen lassen (zweiter
 // blockiert bis erster fertig).
@@ -169,17 +169,18 @@ export function readMigrationSqlTexts(dir) {
 // without it fall through to the drizzle wrappers and otherwise fail here,
 // before any SQL runs, with the migrate-runner message.
 function migrationClient(db) {
-    const hasDirectClient = typeof propertyOf(db, "unsafe") === "function" && typeof propertyOf(db, "begin") === "function";
-    if (hasDirectClient)
-        return asRawClient(db);
-    for (const wrapped of [
+    for (const candidate of [
+        db,
         propertyOf(db, "$client"),
         propertyOf(propertyOf(db, "session"), "client"),
     ]) {
-        if (typeof propertyOf(wrapped, "unsafe") === "function")
-            return asRawClient(wrapped);
+        if (typeof propertyOf(candidate, "unsafe") !== "function")
+            continue;
+        const client = asRawClient(candidate);
+        if (hasBegin(client))
+            return client;
     }
-    throw new Error("migrate-runner: db argument has no .unsafe() (need Bun.SQL or drizzle DbConnection)");
+    throw new Error("migrate-runner: db argument has no .unsafe() and .begin() (need Bun.SQL or drizzle DbConnection)");
 }
 // Raw-SQL via postgres-js or Bun.sql .unsafe() — same shape for both.
 async function executeRaw(db, sqlText) {

package/dist/db/queries/event-consumer.d.ts

@@ -13,7 +13,7 @@ export declare function selectProvablyIdleConsumerPairs(db: AnyDb, names: readon
     readonly name: string;
     readonly instanceId: string;
 }>>;
-export declare function selectConsumerForUpdateSkipLocked<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string): Promise<TRow | undefined>;
+export declare function selectConsumerForUpdateSkipLocked(db: AnyDb, name: string, instanceId: string): Promise<Record<string, unknown> | undefined>;
 export declare function markConsumerProcessing(db: AnyDb, name: string, instanceId: string): Promise<void>;
 export declare function recordConsumerPassFailure(db: AnyDb, name: string, instanceId: string, errorMessage: string, cursorBeforePass?: bigint): Promise<void>;
 export type ConsumerDeliveryOutcome = {
@@ -26,11 +26,11 @@ export type ConsumerDeliveryOutcome = {
     readonly failedEventId: bigint | null;
 };
 export declare function updateConsumerDeliveryOutcome(db: AnyDb, name: string, instanceId: string, outcome: ConsumerDeliveryOutcome): Promise<void>;
-export declare function updateConsumerStatusReturning<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string, status: "idle" | "disabled"): Promise<TRow | undefined>;
-export declare function advanceConsumerPastEventReturning<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string, eventId: bigint, pendingGaps: readonly PendingGapEntry[]): Promise<TRow | undefined>;
+export declare function updateConsumerStatusReturning(db: AnyDb, name: string, instanceId: string, status: "idle" | "disabled"): Promise<Record<string, unknown> | undefined>;
+export declare function advanceConsumerPastEventReturning(db: AnyDb, name: string, instanceId: string, eventId: bigint, pendingGaps: readonly PendingGapEntry[]): Promise<Record<string, unknown> | undefined>;
 export declare function resetConsumerForMspRebuild(db: AnyDb, name: string, instanceId: string): Promise<void>;
-export declare function selectConsumerForUpdate<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string): Promise<TRow | undefined>;
+export declare function selectConsumerForUpdate(db: AnyDb, name: string, instanceId: string): Promise<Record<string, unknown> | undefined>;
 export declare function updateConsumerRebuildCursor(db: AnyDb, name: string, instanceId: string, lastProcessedEventId: bigint, pendingGaps: readonly PendingGapEntry[]): Promise<void>;
 export declare function markConsumerRebuildFailed(db: AnyDb, name: string, instanceId: string, errorMessage: string): Promise<void>;
-export declare function rearmDeadConsumer<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string): Promise<TRow | undefined>;
-export declare function removePendingGapReturning<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string, newPendingGaps: readonly PendingGapEntry[]): Promise<TRow | undefined>;
+export declare function rearmDeadConsumer(db: AnyDb, name: string, instanceId: string): Promise<Record<string, unknown> | undefined>;
+export declare function removePendingGapReturning(db: AnyDb, name: string, instanceId: string, newPendingGaps: readonly PendingGapEntry[]): Promise<Record<string, unknown> | undefined>;

package/dist/db/queries/event-store.d.ts

@@ -56,5 +56,5 @@ export type PendingIdRange = {
     readonly from: bigint;
     readonly to: bigint;
 };
-export declare function selectPendingAndNewEventRows<TRow = Record<string, unknown>>(db: AnyDb, cursor: bigint, pendingRanges: readonly PendingIdRange[], batchSize: number): Promise<ReadonlyArray<TRow>>;
+export declare function selectPendingAndNewEventRows(db: AnyDb, cursor: bigint, pendingRanges: readonly PendingIdRange[], batchSize: number): Promise<ReadonlyArray<Record<string, unknown>>>;
 export declare function selectSmallestVisibleIdInRanges(db: AnyDb, pendingRanges: readonly PendingIdRange[]): Promise<bigint | null>;

package/dist/db/queries/projection-rebuild.d.ts

@@ -1,6 +1,6 @@
 import type { AnyDb } from "../query.js";
 export declare function markProjectionRebuilding(db: AnyDb, projectionName: string): Promise<void>;
-export declare function selectEventsForProjectionRebuildBatch<TRow = Record<string, unknown>>(db: AnyDb, aggregateTypes: readonly string[], eventTypes: readonly string[], afterId: bigint, limit: number): Promise<ReadonlyArray<TRow>>;
+export declare function selectEventsForProjectionRebuildBatch(db: AnyDb, aggregateTypes: readonly string[], eventTypes: readonly string[], afterId: bigint, limit: number): Promise<ReadonlyArray<Record<string, unknown>>>;
 export declare function countSubscribedEvents(db: AnyDb, aggregateTypes: readonly string[], eventTypes: readonly string[]): Promise<bigint>;
 export declare function finalizeProjectionRebuild(db: AnyDb, projectionName: string, lastProcessedEventId: bigint): Promise<void>;
 export declare function markProjectionRebuildFailed(db: AnyDb, projectionName: string, errorMessage: string): Promise<void>;

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

@@ -1,4 +1,8 @@
 import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { InternalError } from "../errors/index.js";
 import type { DbRunner } from "./connection.js";
 export declare function bindTenantDbRunner(tenantDb: TenantDb, runner: DbRunner): void;
 export declare function tenantDbRunner(tenantDb: TenantDb): DbRunner;
+export declare function denyTenantDbWrites(tenantDb: TenantDb, reason: string): void;
+export declare function tenantDbWritesDeniedError(operation: string, reason: string): InternalError;
+export declare function tenantDbWriteRunner(tenantDb: TenantDb, operation: string): DbRunner;