@cosmicdrift/kumiko-framework 0.354.1 → 0.355.0

package/dist/db/entity-field-encryption.d.ts

@@ -1,4 +1,5 @@
 import type { EntityDefinition } from "../engine/types/index.js";
+import { type Logger } from "../logging/index.js";
 import type { EnvelopeCipher } from "../secrets/envelope-cipher.js";
 export declare function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySet<string>;
 export declare function isSensitiveLabelField(entity: EntityDefinition, field: string): boolean;
@@ -6,7 +7,15 @@ export declare function hasSearchablePlaintext(entity: EntityDefinition, field:
 export declare function encryptEntityFieldValues(row: Record<string, unknown>, encryptedFields: ReadonlySet<string>, cipher: EnvelopeCipher, opts?: {
     onlyKeys?: Iterable<string>;
 }): Promise<Record<string, unknown>>;
-export declare function decryptEntityFieldValues(row: Record<string, unknown>, encryptedFields: ReadonlySet<string>, cipher: EnvelopeCipher): Promise<Record<string, unknown>>;
+export declare function logUndecryptableField(info: {
+    entityName: string | undefined;
+    rowId: unknown;
+    field: string;
+    error: unknown;
+}, logger?: Logger): void;
+export declare function decryptEntityFieldValues(row: Record<string, unknown>, encryptedFields: ReadonlySet<string>, cipher: EnvelopeCipher, opts?: {
+    onFieldError?: (field: string, error: unknown) => void;
+}): Promise<Record<string, unknown>>;
 export declare function configureEntityFieldEncryption(cipher: EnvelopeCipher | undefined): void;
 export declare function resolveEntityFieldEncryption(): EnvelopeCipher;
 export declare function configuredEntityFieldEncryption(): EnvelopeCipher | undefined;

package/dist/db/entity-field-encryption.js

@@ -4,6 +4,7 @@
 // single-key ciphertexts (pre-envelope ENCRYPTION_KEY era) readable via
 // the cipher's legacy fallback until re-encrypted.
 import { collectPiiSubjectFields } from "../crypto/index.js";
+import { createLogger } from "../logging/index.js";
 import { createEnvMasterKeyProvider } from "../secrets/env-master-key-provider.js";
 export function collectEncryptedFieldNames(entity) {
     const names = new Set();
@@ -60,7 +61,25 @@ export async function encryptEntityFieldValues(row, encryptedFields, cipher, opt
     }
     return out;
 }
-export async function decryptEntityFieldValues(row, encryptedFields, cipher) {
+let undecryptableFieldLogger;
+function defaultUndecryptableFieldLogger() {
+    undecryptableFieldLogger ??= createLogger();
+    return undecryptableFieldLogger;
+}
+// Logs identifiers and the error class only: ciphertext, key material and the
+// cipher's error message (which may echo envelope content) never reach the log.
+export function logUndecryptableField(info, logger = defaultUndecryptableFieldLogger()) {
+    logger.error("encrypted field could not be decrypted; returned as null", {
+        entity: info.entityName,
+        rowId: info.rowId,
+        field: info.field,
+        errorName: info.error instanceof Error ? info.error.name : typeof info.error,
+    });
+}
+// With `onFieldError` a field that fails to decrypt (wrong key, corrupt
+// envelope) reads as null and is reported instead of throwing, so one bad row
+// cannot fail a whole list. Without it decrypt stays fail-loud (write paths).
+export async function decryptEntityFieldValues(row, encryptedFields, cipher, opts) {
     if (encryptedFields.size === 0)
         return row;
     const out = { ...row };
@@ -71,7 +90,17 @@ export async function decryptEntityFieldValues(row, encryptedFields, cipher) {
             continue;
         if (typeof value !== "string")
             continue;
-        out[name] = await cipher.decrypt(value, scope);
+        if (!opts?.onFieldError) {
+            out[name] = await cipher.decrypt(value, scope);
+            continue;
+        }
+        try {
+            out[name] = await cipher.decrypt(value, scope);
+        }
+        catch (error) {
+            out[name] = null;
+            opts.onFieldError(name, error);
+        }
     }
     return out;
 }

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

@@ -9,11 +9,15 @@ import type { EventStoreExecutorOptions } from "./event-store-executor.js";
 import type { TenantDb } from "./tenant-db.js";
 export type Table = TableColumns<any>;
 export declare function buildFilterWhere(field: string, op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in", value: unknown): WhereObject | null;
+export declare function ownershipSubject(user: SessionUser, streamTenantId: TenantId | undefined): SessionUser;
 export declare function isForeignTenantOnGlobalEntity(entity: EntityDefinition, tenantIdValue: unknown): boolean;
 export declare function tryMapUniqueViolation(e: unknown, entityName: string): WriteFailure | null;
 export declare function buildEventMetadata(user: SessionUser): EventMetadata;
 export type EntityLifecycleVerb = "created" | "updated" | "deleted" | "restored" | "forgotten";
 export declare function entityEventName(entityName: string, verb: EntityLifecycleVerb): string;
+export type DecryptForReadOptions = {
+    readonly degradeUndecryptable?: (field: string) => void;
+};
 export type ExecutorContext = {
     readonly table: Table;
     readonly entity: EntityDefinition;
@@ -21,7 +25,8 @@ export type ExecutorContext = {
     readonly entityCache?: EntityCache;
     readonly searchAdapter?: SearchAdapter;
     readonly softDelete: boolean;
-    readonly streamTenantFor: (user: SessionUser) => TenantId;
+    readonly streamTenantFor: (user: SessionUser, requestedStreamTenantId?: TenantId) => TenantId;
+    readonly streamTenantOverrideFailure: (db: TenantDb, row: Record<string, unknown>, requestedStreamTenantId: TenantId | undefined) => WriteFailure | undefined;
     readonly idFilter: (id: EntityId) => WhereObject;
     readonly loadById: (id: EntityId, db: TenantDb) => Promise<Record<string, unknown> | null>;
     readonly assertStreamWritable: (db: TenantDb, id: EntityId, tenantId: TenantId) => Promise<void>;
@@ -53,8 +58,9 @@ export type ExecutorContext = {
     readonly encryptForStorage: (row: Record<string, unknown>, user: SessionUser, opts?: {
         onlyKeys?: Iterable<string>;
         subjectSource?: Record<string, unknown>;
+        keyTenantId?: TenantId | undefined;
     }) => Promise<Record<string, unknown>>;
-    readonly decryptForRead: (row: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    readonly decryptForRead: (row: Record<string, unknown>, opts?: DecryptForReadOptions) => Promise<Record<string, unknown>>;
     readonly applyDefaults: (payload: Record<string, unknown>) => Record<string, unknown>;
     readonly stripSensitive: (payload: Record<string, unknown> | undefined) => Record<string, unknown>;
 };

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

@@ -4,11 +4,11 @@ import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
 import { shiftParams } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
-import { InternalError, subjectErasedConflict, UniqueViolationError, writeFailure, } from "../errors/index.js";
+import { AccessDeniedError, InternalError, subjectErasedConflict, UniqueViolationError, writeFailure, } from "../errors/index.js";
 import { ArchivedStreamError, isStreamArchived } from "../event-store/index.js";
 import { assertUnreachable } from "../utils/index.js";
 import { rehydrateCompoundTypes } from "./compound-types.js";
-import { collectEncryptedFieldNames, decryptEntityFieldValues, encryptEntityFieldValues, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
+import { collectEncryptedFieldNames, decryptEntityFieldValues, encryptEntityFieldValues, logUndecryptableField, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
 import { constraintOf, isUniqueViolation } from "./pg-error.js";
 import { toSnakeCase } from "./table-builder.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
@@ -39,6 +39,13 @@ export function buildFilterWhere(field, op, value) {
             return assertUnreachable(op, "filter op");
     }
 }
+// Tenant-based write-ownership rules (from("user:tenantId", "tenantId")) compare the caller's
+// tenant with the row's. An explicit cross-tenant grant (streamTenantId, checked against the
+// loaded row) is evaluated as the operator acting inside the target tenant. Only this
+// evaluation sees the target tenant: stream actor, metadata and PII keys keep the real identity.
+export function ownershipSubject(user, streamTenantId) {
+    return streamTenantId === undefined ? user : { ...user, tenantId: streamTenantId };
+}
 // Returns the scalar default of a field, or undefined if the field's type
 // doesn't carry a default or no default was declared. Only scalar types
 // (text/number/boolean/select) support creation-time defaults — money/date/
@@ -110,7 +117,24 @@ export function buildExecutorContext(table, entity, options) {
     // user) lives on SYSTEM_TENANT_ID deterministically — every op addresses it
     // there. Everything else stays on the caller's tenant (byte-identical to the
     // old hardcoded user.tenantId). Single source of truth for the stream key.
-    const streamTenantFor = (user) => entity.systemStream ? SYSTEM_TENANT_ID : user.tenantId;
+    const streamTenantFor = (user, requestedStreamTenantId) => entity.systemStream ? SYSTEM_TENANT_ID : (requestedStreamTenantId ?? user.tenantId);
+    // Only a system-mode db (r.systemScope() / acknowledged cross-tenant) may address another
+    // tenant's stream, and only the tenant of the row it just loaded.
+    const streamTenantOverrideFailure = (db, row, requestedStreamTenantId) => {
+        if (requestedStreamTenantId === undefined)
+            return undefined;
+        if (db.mode !== "system") {
+            return writeFailure(new AccessDeniedError({
+                message: `${entityName}: streamTenantId requires a system-mode db`,
+            }));
+        }
+        if (row["tenantId"] !== requestedStreamTenantId) {
+            return writeFailure(new AccessDeniedError({
+                message: `${entityName}: streamTenantId does not match the tenant of the addressed row`,
+            }));
+        }
+        return undefined;
+    };
     // idType default (undefined) is now "uuid" — the ES-pivot made UUID the
     // only valid aggregate-id type. Explicit `idType: "serial"` is the only
     // shape that's incompatible with the event-store and still rejected.
@@ -156,10 +180,10 @@ export function buildExecutorContext(table, entity, options) {
     function piiKms() {
         return options.kms ?? configuredPiiSubjectKms();
     }
-    function kmsContextFor(user) {
+    function kmsContextFor(user, keyTenantId) {
         return {
             requestId: requestContext.get()?.requestId ?? "event-store-executor",
-            ...(user && { tenantId: user.tenantId, userId: String(user.id) }),
+            ...(user && { tenantId: keyTenantId ?? user.tenantId, userId: String(user.id) }),
         };
     }
     // Async on purpose: the envelope cipher wraps/unwraps DEKs via the
@@ -176,8 +200,8 @@ export function buildExecutorContext(table, entity, options) {
         const kms = piiKms();
         if (hasPiiFields && kms) {
             try {
-                out = await encryptPiiFieldValues(out, entity, piiSubjectFields, kms, kmsContextFor(user), {
-                    tenantId: user.tenantId,
+                out = await encryptPiiFieldValues(out, entity, piiSubjectFields, kms, kmsContextFor(user, opts?.keyTenantId), {
+                    tenantId: opts?.keyTenantId ?? user.tenantId,
                     entityName,
                     ...(opts?.onlyKeys !== undefined && { onlyKeys: opts.onlyKeys }),
                     ...(opts?.subjectSource !== undefined && { subjectSource: opts.subjectSource }),
@@ -198,14 +222,21 @@ export function buildExecutorContext(table, entity, options) {
     // unwrap before envelope decrypt, or the envelope cipher chokes on a
     // still-PII-wrapped string (auth-mfa.totpSecret/recoveryCodes combine both
     // markers; see pii-subject-encryption.integration.test.ts).
-    async function decryptForRead(row) {
+    async function decryptForRead(row, opts) {
         let out = row;
         const kms = piiKms();
         if (hasPiiFields && kms) {
             out = await decryptPiiFieldValues(out, piiSubjectFields, kms, kmsContextFor());
         }
         if (hasEncryptedFields) {
-            out = await decryptEntityFieldValues(out, encryptedFields, fieldCipher());
+            out = await decryptEntityFieldValues(out, encryptedFields, fieldCipher(), opts?.degradeUndecryptable
+                ? {
+                    onFieldError: (field, error) => {
+                        logUndecryptableField({ entityName, rowId: row["id"], field, error });
+                        opts.degradeUndecryptable?.(field);
+                    },
+                }
+                : undefined);
         }
         return out;
     }
@@ -384,6 +415,7 @@ export function buildExecutorContext(table, entity, options) {
         searchAdapter,
         softDelete,
         streamTenantFor,
+        streamTenantOverrideFailure,
         idFilter,
         loadById,
         assertStreamWritable,

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

@@ -664,7 +664,7 @@ export function createReadVerbs(ctx) {
             // field (ciphertext leaked to the caller).
             const tableInfo = extractTableInfo(table);
             const encryptedRows = rawRows.map((r) => rehydrateCompoundTypes(coerceRow(r, tableInfo), entity));
-            const decryptedRows = await Promise.all(encryptedRows.map((r) => decryptForRead(r)));
+            const decryptedRows = await Promise.all(encryptedRows.map((r) => decryptForRead(r, { degradeUndecryptable: () => { } })));
             // 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.
@@ -744,7 +744,7 @@ export function createReadVerbs(ctx) {
                         // Cached rows are stored re-encrypted (see the `set` below) so an
                         // `encrypted` field's plaintext never sits in a second at-rest
                         // store (Redis) the field-encryption feature doesn't cover.
-                        return withStreamVersion(await decryptForRead(cached), streamVersion);
+                        return withStreamVersion(await decryptForRead(cached, { degradeUndecryptable: () => { } }), streamVersion);
                     }
                 }
             }
@@ -755,9 +755,12 @@ export function createReadVerbs(ctx) {
             // Same coerce-before-rehydrate/decrypt ordering as list() above — raw
             // is snake_case (raw SQL); coerceRow maps it to camelCase.
             const rowInfo = extractTableInfo(table);
-            const coerced = await decryptForRead(rehydrateCompoundTypes(coerceRow(raw, rowInfo), entity));
+            const undecryptableFields = [];
+            const coerced = await decryptForRead(rehydrateCompoundTypes(coerceRow(raw, rowInfo), entity), { degradeUndecryptable: (field) => undecryptableFields.push(field) });
             const result = withStreamVersion(coerced, snapshot.streamVersion);
-            if (entityCache && entityName) {
+            // A degraded row must not be cached: re-encrypting its null would
+            // replay the missing value on later cache hits without any error log.
+            if (entityCache && entityName && undecryptableFields.length === 0) {
                 await entityCache.set(user.tenantId, entityName, payload.id, await encryptForStorage(result, user));
             }
             return result;

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

@@ -11,7 +11,7 @@ import { hasLiveProjectionsForEvent, runProjectionsForEvent, } from "../pipeline
 import { generateId } from "../utils/index.js";
 import { applyEntityEvent } from "./apply-entity-event.js";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.js";
-import { buildEventMetadata, entityEventName, isForeignTenantOnGlobalEntity, tryMapUniqueViolation, } from "./event-store-executor-context.js";
+import { buildEventMetadata, entityEventName, isForeignTenantOnGlobalEntity, ownershipSubject, tryMapUniqueViolation, } from "./event-store-executor-context.js";
 import { projectionRegistryOf } from "./projection-registry-binding.js";
 import { runInSavepointIfSupported } from "./query.js";
 import { assertPersonalDataWrite, tableNameOf } from "./tenant-db.js";
@@ -118,12 +118,43 @@ async function runPreSave(preSave, changes, previous, isNew, entityName, action,
     }
 }
 export function createWriteVerbs(ctx) {
-    const { table, entity, entityName, entityCache, softDelete, streamTenantFor, encryptForStorage, decryptForRead, applyDefaults, stripSensitive, loadById, assertStreamWritable, loadExpectSnapshot, } = ctx;
+    const { table, entity, entityName, entityCache, softDelete, streamTenantFor, streamTenantOverrideFailure, encryptForStorage, decryptForRead, applyDefaults, stripSensitive, loadById, assertStreamWritable, loadExpectSnapshot, } = ctx;
     const entityInstructionFieldNames = instructionFieldNames(entity);
+    const eventVersion = entity.eventVersion ?? 1;
     let insertSchema;
     let updateSchema;
     const createOutputSchema = () => (insertSchema ??= buildInsertSchema(entity));
     const updateOutputSchema = () => (updateSchema ??= buildUpdateSchema(entity));
+    // 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
+    // handlers) still read unfiltered. No isDeleted filter in the read: restore
+    // targets exactly the soft-deleted row.
+    async function loadSoftDeletedRow(db, id, streamTenantId) {
+        const row = await db.fetchOne(table, { id });
+        if (!row)
+            return { failure: writeFailure(new NotFoundError(entityName, id)) };
+        const streamTenantMismatch = streamTenantOverrideFailure(db, row, streamTenantId);
+        if (streamTenantMismatch)
+            return { failure: streamTenantMismatch };
+        if (!row["isDeleted"]) {
+            return {
+                failure: writeFailure(new UnprocessableError("not_deleted", { i18nKey: "errors.notDeleted" })),
+            };
+        }
+        return { row: row };
+    }
+    async function expectedStreamVersion(db, id, streamTenant, expect) {
+        const snapshot = await loadExpectSnapshot(db, id, streamTenant, Object.keys(expect));
+        const row = snapshot.row;
+        if (!row)
+            return writeFailure(new PreconditionFailedError({ entityId: id, field: "id" }));
+        const mismatch = Object.entries(expect).find(([key, expected]) => row[key] !== expected);
+        if (mismatch) {
+            return writeFailure(new PreconditionFailedError({ entityId: id, field: mismatch[0] }));
+        }
+        return snapshot.streamVersion;
+    }
     return {
         async create(payload, user, db, options) {
             if (isForeignTenantOnGlobalEntity(entity, payload["tenantId"])) {
@@ -218,6 +249,7 @@ export function createWriteVerbs(ctx) {
                     tenantId: streamTenantFor(user),
                     expectedVersion: 0,
                     type: entityEventName(entityName, "created"),
+                    eventVersion,
                     payload: flatData,
                     metadata: buildEventMetadata(user),
                 }));
@@ -309,6 +341,10 @@ export function createWriteVerbs(ctx) {
             const previous = await loadById(payload.id, db);
             if (!previous)
                 return writeFailure(new NotFoundError(entityName, payload.id));
+            const streamTenantId = updateOptions?.streamTenantId;
+            const streamTenantMismatch = streamTenantOverrideFailure(db, previous, streamTenantId);
+            if (streamTenantMismatch)
+                return streamTenantMismatch;
             const preSaveResult = await runPreSave(updateOptions?.preSave, payload.changes, previous, false, entityName, "update", updateOutputSchema);
             if ("failure" in preSaveResult)
                 return preSaveResult.failure;
@@ -322,7 +358,7 @@ export function createWriteVerbs(ctx) {
             // prevents the attack where role A passes old, role B passes new and
             // aggregation would wrongly allow a row-grab.
             const mergedNew = { ...previous, ...changes };
-            if (!userCanWriteFieldRow(user, entity.access?.write, previous, mergedNew)) {
+            if (!userCanWriteFieldRow(ownershipSubject(user, streamTenantId), entity.access?.write, previous, mergedNew)) {
                 return writeFailure(new UnprocessableError("ownership_denied", {
                     i18nKey: "errors.ownershipDenied",
                     details: {
@@ -350,7 +386,7 @@ export function createWriteVerbs(ctx) {
             // for a checked field is still evaluated against the full post-hook
             // row (`changes` merged onto `previous`) — an ownership rule can
             // reference a column only a hook populates (kumiko-framework#1672).
-            const fieldDeniedUpdate = checkWriteFieldOwnership(entity, payload.changes, user, previous, changes);
+            const fieldDeniedUpdate = checkWriteFieldOwnership(entity, payload.changes, ownershipSubject(user, streamTenantId), previous, changes);
             if (fieldDeniedUpdate) {
                 return writeFailure(new UnprocessableError("ownership_denied", {
                     i18nKey: "errors.ownershipDenied",
@@ -367,7 +403,8 @@ export function createWriteVerbs(ctx) {
             const unavailableOnUpdate = selectOptionNotAvailableFailure(findUnavailableSelectOptions(entity.fields, mergedNew, previous));
             if (unavailableOnUpdate)
                 return unavailableOnUpdate;
-            await assertStreamWritable(db, payload.id, streamTenantFor(user));
+            const streamTenant = streamTenantFor(user, streamTenantId);
+            await assertStreamWritable(db, payload.id, streamTenant);
             // Stream-version is authoritative, not row.version. `ctx.appendEvent`
             // can bump the stream between CRUD writes (domain event on the same
             // aggregate); a stale row.version here would make the next CRUD write
@@ -376,22 +413,12 @@ export function createWriteVerbs(ctx) {
             //
             // 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);
-                const snapshot = await loadExpectSnapshot(db, payload.id, streamTenantFor(user), expectKeys);
-                if (!snapshot.row) {
-                    return writeFailure(new PreconditionFailedError({ entityId: payload.id, field: "id" }));
-                }
-                const mismatch = Object.entries(updateOptions.expect).find(([key, expected]) => snapshot.row?.[key] !== expected);
-                if (mismatch) {
-                    return writeFailure(new PreconditionFailedError({ entityId: payload.id, field: mismatch[0] }));
-                }
-                currentVersion = snapshot.streamVersion;
-            }
-            else {
-                currentVersion = await getStreamVersion(runner, String(payload.id), streamTenantFor(user));
-            }
+            const expect = updateOptions?.expect;
+            const currentVersion = expect
+                ? await expectedStreamVersion(db, payload.id, streamTenant, expect)
+                : await getStreamVersion(runner, String(payload.id), streamTenant);
+            if (typeof currentVersion !== "number")
+                return currentVersion;
             if (!updateOptions?.skipOptimisticLock) {
                 if (payload.version === undefined) {
                     return writeFailure(new FrameworkVersionConflict({
@@ -419,6 +446,7 @@ export function createWriteVerbs(ctx) {
                 const flatChanges = await encryptForStorage(flatChangesPlain, user, {
                     onlyKeys: Object.keys(submittedChanges),
                     subjectSource: mergedNew,
+                    keyTenantId: streamTenantId,
                 });
                 // The event payload carries BOTH `changes` (what the user asked for) AND
                 // `previous` (the pre-update row). Cross-aggregate projections need the
@@ -429,16 +457,19 @@ export function createWriteVerbs(ctx) {
                 // re-encrypt it before it's persisted so plaintext of pii/encrypted
                 // fields doesn't land in the immutable log (flatChanges is already
                 // ciphertext from encryptForStorage above).
-                const encryptedPrevious = await encryptForStorage(previous, user);
+                const encryptedPrevious = await encryptForStorage(previous, user, {
+                    keyTenantId: streamTenantId,
+                });
                 // Savepoint-scoped — see the create() append() above for why:
                 // confines a losing writer's unique-violation to a nested scope
                 // instead of poisoning the whole outer transaction.
                 const event = await runInSavepointIfSupported(runner, (sp) => append(sp, {
                     aggregateId: String(payload.id),
                     aggregateType: entityName,
-                    tenantId: streamTenantFor(user),
+                    tenantId: streamTenant,
                     expectedVersion: currentVersion,
                     type: entityEventName(entityName, "updated"),
+                    eventVersion,
                     payload: {
                         changes: flatChanges,
                         previous: encryptedPrevious,
@@ -472,7 +503,7 @@ export function createWriteVerbs(ctx) {
                 const row = result.row;
                 const data = await decryptForRead(rehydrateCompoundTypes(row, entity));
                 if (entityCache && entityName) {
-                    await entityCache.del(user.tenantId, entityName, payload.id);
+                    await entityCache.del(streamTenantId ?? user.tenantId, entityName, payload.id);
                 }
                 const echoEvent = {
                     ...event,
@@ -514,7 +545,7 @@ export function createWriteVerbs(ctx) {
                 throw e;
             }
         },
-        async delete(payload, user, db) {
+        async delete(payload, user, db, options) {
             if (isIrreversibleEntityVerb("delete", entity)) {
                 assertIrreversibleOperationAllowed(`${entityName}.delete (entity has no softDelete)`);
             }
@@ -522,11 +553,15 @@ export function createWriteVerbs(ctx) {
             const existing = await loadById(payload.id, db);
             if (!existing)
                 return writeFailure(new NotFoundError(entityName, payload.id));
+            const streamTenantId = options?.streamTenantId;
+            const streamTenantMismatch = streamTenantOverrideFailure(db, existing, streamTenantId);
+            if (streamTenantMismatch)
+                return streamTenantMismatch;
             // H.2 — entity-level write-ownership on delete. Only the pre-delete
             // row matters (there's no "new" row for a delete); passing existing
             // twice to userCanWriteFieldRow makes the Straddle check trivial
             // (same row on both sides) while keeping the multi-role-atomic shape.
-            if (!userCanWriteFieldRow(user, entity.access?.write, existing, existing)) {
+            if (!userCanWriteFieldRow(ownershipSubject(user, streamTenantId), entity.access?.write, existing, existing)) {
                 return writeFailure(new UnprocessableError("ownership_denied", {
                     i18nKey: "errors.ownershipDenied",
                     details: {
@@ -538,9 +573,9 @@ export function createWriteVerbs(ctx) {
                     },
                 }));
             }
-            await assertStreamWritable(db, payload.id, streamTenantFor(user));
+            await assertStreamWritable(db, payload.id, streamTenantFor(user, streamTenantId));
             // Stream-version authoritative (see update() for rationale).
-            const currentVersion = await getStreamVersion(runner, String(payload.id), streamTenantFor(user));
+            const currentVersion = await getStreamVersion(runner, String(payload.id), streamTenantFor(user, streamTenantId));
             // Deletes carry the full pre-delete row as `previous`. That's what
             // projections and downstream consumers need to reverse any aggregates —
             // a `{}`-payload delete would make cross-aggregate projections impossible
@@ -552,10 +587,13 @@ export function createWriteVerbs(ctx) {
                 event = await runInSavepointIfSupported(runner, async (sp) => append(sp, {
                     aggregateId: String(payload.id),
                     aggregateType: entityName,
-                    tenantId: streamTenantFor(user),
+                    tenantId: streamTenantFor(user, streamTenantId),
                     expectedVersion: currentVersion,
                     type: entityEventName(entityName, "deleted"),
-                    payload: { previous: await encryptForStorage(existing, user) },
+                    eventVersion,
+                    payload: {
+                        previous: await encryptForStorage(existing, user, { keyTenantId: streamTenantId }),
+                    },
                     metadata: buildEventMetadata(user),
                 }));
             }
@@ -578,7 +616,7 @@ export function createWriteVerbs(ctx) {
                 return writeFailure(new InternalError({ message: "projection delete: applyEntityEvent skipped" }));
             }
             if (entityCache && entityName) {
-                await entityCache.del(user.tenantId, entityName, payload.id);
+                await entityCache.del(streamTenantId ?? user.tenantId, entityName, payload.id);
             }
             const echoEvent = { ...event, payload: { previous: stripSensitive(existing) } };
             await projectEntityEvent(db, runner, echoEvent);
@@ -597,15 +635,19 @@ export function createWriteVerbs(ctx) {
         // hard-deletes the row regardless of softDelete — and, being an auto-verb,
         // the erasure replays on rebuild (created → forgotten → row gone). Loads
         // without the isDeleted filter so trashed (soft-deleted) rows are erased too.
-        async forget(payload, user, db) {
+        async forget(payload, user, db, options) {
             assertIrreversibleOperationAllowed(`${entityName}.forget`);
             const runner = tenantDbRunner(db);
             const raw = await db.fetchOne(table, { id: payload.id });
             if (!raw)
                 return writeFailure(new NotFoundError(entityName, payload.id));
+            const streamTenantId = options?.streamTenantId;
+            const streamTenantMismatch = streamTenantOverrideFailure(db, raw, streamTenantId);
+            if (streamTenantMismatch)
+                return streamTenantMismatch;
             const existing = await decryptForRead(rehydrateCompoundTypes(raw, entity));
             if (!isFrameworkSystemUser(user) &&
-                !userCanWriteFieldRow(user, entity.access?.write, existing, existing)) {
+                !userCanWriteFieldRow(ownershipSubject(user, streamTenantId), entity.access?.write, existing, existing)) {
                 return writeFailure(new UnprocessableError("ownership_denied", {
                     i18nKey: "errors.ownershipDenied",
                     details: {
@@ -617,19 +659,22 @@ export function createWriteVerbs(ctx) {
                     },
                 }));
             }
-            await assertStreamWritable(db, payload.id, streamTenantFor(user));
-            const currentVersion = await getStreamVersion(runner, String(payload.id), streamTenantFor(user));
+            await assertStreamWritable(db, payload.id, streamTenantFor(user, streamTenantId));
+            const currentVersion = await getStreamVersion(runner, String(payload.id), streamTenantFor(user, streamTenantId));
             let event;
             try {
                 event = await runInSavepointIfSupported(runner, async (sp) => append(sp, {
                     aggregateId: String(payload.id),
                     aggregateType: entityName,
-                    tenantId: streamTenantFor(user),
+                    tenantId: streamTenantFor(user, streamTenantId),
                     expectedVersion: currentVersion,
                     type: entityEventName(entityName, "forgotten"),
+                    eventVersion,
                     // Re-encrypt like delete(): `existing` came decrypted from loadById —
                     // plaintext must not land in the immutable log, least of all on forget.
-                    payload: { previous: await encryptForStorage(existing, user) },
+                    payload: {
+                        previous: await encryptForStorage(existing, user, { keyTenantId: streamTenantId }),
+                    },
                     metadata: buildEventMetadata(user),
                 }));
             }
@@ -651,7 +696,7 @@ export function createWriteVerbs(ctx) {
                 return writeFailure(new InternalError({ message: "projection forget: applyEntityEvent skipped" }));
             }
             if (entityCache && entityName) {
-                await entityCache.del(user.tenantId, entityName, payload.id);
+                await entityCache.del(streamTenantId ?? user.tenantId, entityName, payload.id);
             }
             const echoEvent = { ...event, payload: { previous: stripSensitive(existing) } };
             await projectEntityEvent(db, runner, echoEvent);
@@ -666,29 +711,22 @@ export function createWriteVerbs(ctx) {
                 },
             };
         },
-        async restore(payload, user, db) {
+        async restore(payload, user, db, options) {
             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
-            // handlers) still read unfiltered. No isDeleted filter here: restore
-            // targets exactly the soft-deleted row.
-            const row = await db.fetchOne(table, { id: payload.id });
-            if (!row)
-                return writeFailure(new NotFoundError(entityName, payload.id));
-            const data = row;
-            if (!data["isDeleted"]) {
-                return writeFailure(new UnprocessableError("not_deleted", { i18nKey: "errors.notDeleted" }));
-            }
+            const streamTenantId = options?.streamTenantId;
+            const target = await loadSoftDeletedRow(db, payload.id, streamTenantId);
+            if ("failure" in target)
+                return target.failure;
+            const data = target.row;
             // H.2 — entity-level write-ownership on restore. Same shape as delete:
             // only the stored row matters. Stored row carries pre-soft-delete
             // teamId/... fields, so the ownership predicate still applies cleanly.
-            if (!userCanWriteFieldRow(user, entity.access?.write, data, data)) {
+            if (!userCanWriteFieldRow(ownershipSubject(user, streamTenantId), entity.access?.write, data, data)) {
                 return writeFailure(new UnprocessableError("ownership_denied", {
                     i18nKey: "errors.ownershipDenied",
                     details: {
@@ -700,9 +738,9 @@ export function createWriteVerbs(ctx) {
                     },
                 }));
             }
-            await assertStreamWritable(db, payload.id, streamTenantFor(user));
+            await assertStreamWritable(db, payload.id, streamTenantFor(user, streamTenantId));
             // Stream-version authoritative (see update() for rationale).
-            const currentVersion = await getStreamVersion(runner, String(payload.id), streamTenantFor(user));
+            const currentVersion = await getStreamVersion(runner, String(payload.id), streamTenantFor(user, streamTenantId));
             // 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
@@ -713,9 +751,10 @@ export function createWriteVerbs(ctx) {
                 event = await runInSavepointIfSupported(runner, (sp) => append(sp, {
                     aggregateId: String(payload.id),
                     aggregateType: entityName,
-                    tenantId: streamTenantFor(user),
+                    tenantId: streamTenantFor(user, streamTenantId),
                     expectedVersion: currentVersion,
                     type: entityEventName(entityName, "restored"),
+                    eventVersion,
                     payload: { previous: data },
                     metadata: buildEventMetadata(user),
                 }));
@@ -752,7 +791,7 @@ export function createWriteVerbs(ctx) {
             }
             const restored = restoreResult.row;
             if (entityCache && entityName) {
-                await entityCache.del(user.tenantId, entityName, payload.id);
+                await entityCache.del(streamTenantId ?? user.tenantId, entityName, payload.id);
             }
             // Read-side auto-convert for compound types, same as update/list.
             // decryptForRead matches create/update/list/detail: the caller-facing