@cosmicdrift/kumiko-framework 0.354.0 → 0.355.0

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

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

@@ -27,6 +27,7 @@ export type SubsequentEventInsertRow = {
 /** INSERT … SELECT … WHERE EXISTS predecessor — stays raw (typed builder can't express this). */
 export declare function insertSubsequentEventRow(db: AnyDb, params: SubsequentEventInsertParams): Promise<SubsequentEventInsertRow | undefined>;
 export declare function selectStreamMaxVersion(db: AnyDb, aggregateId: string, tenantId: string): Promise<number>;
+export declare function selectStreamMaxVersions(db: AnyDb, aggregateIds: readonly string[], tenantId: string): Promise<Map<string, number>>;
 /** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
 export declare function selectAggregateMaxVersion(db: AnyDb, aggregateId: string): Promise<number>;
 export declare function selectEventsHighWaterMark(db: AnyDb): Promise<bigint>;

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

@@ -171,6 +171,17 @@ export async function selectStreamMaxVersion(db, aggregateId, tenantId) {
     const rows = await unsafeReadRetrying(db, `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "tenant_id" = $2`, [aggregateId, tenantId]);
     return rows[0]?.v ?? 0;
 }
+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]]);
+    for (const row of rows) {
+        if (row.v !== null)
+            versions.set(row.id, row.v);
+    }
+    return versions;
+}
 /** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
 export async function selectAggregateMaxVersion(db, aggregateId) {
     const rows = await unsafeReadRetrying(db, `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1`, [aggregateId]);

package/dist/engine/build-app-schema.js

@@ -273,15 +273,42 @@ function projectScreens(featureName, screens, registry, urlPrefillFieldsByScreen
             return projectConfigEditScreen(screen, encryptedConfigKeyQns);
         if (screen.type === "projectionList")
             return projectProjectionListScreen(screen, registry);
-        if (screen.type === "actionForm" ||
-            screen.type === "secretMint" ||
-            screen.type === "entityEdit") {
-            const declared = urlPrefillFieldsByScreenQn.get(qualifyEntityName(featureName, "screen", shortId));
-            return { ...screen, urlPrefillFields: declared === undefined ? [] : [...declared].sort() };
+        if (screen.type === "entityEdit") {
+            const { writeExcludedFields: _authoredExclusions, ...authoredScreen } = screen;
+            return {
+                ...authoredScreen,
+                urlPrefillFields: sortedUrlPrefillFields(urlPrefillFieldsByScreenQn.get(qualifyEntityName(featureName, "screen", shortId))),
+                ...entityEditWriteExcludedFields(featureName, screen.entity, registry),
+            };
+        }
+        if (screen.type === "actionForm" || screen.type === "secretMint") {
+            return {
+                ...screen,
+                urlPrefillFields: sortedUrlPrefillFields(urlPrefillFieldsByScreenQn.get(qualifyEntityName(featureName, "screen", shortId))),
+            };
         }
         return screen;
     });
 }
+function sortedUrlPrefillFields(declared) {
+    return declared === undefined ? [] : [...declared].sort();
+}
+// The screen is the one thing the renderer reads, so the per-verb excludeFields
+// of the entity's generic create/update handlers are projected onto it here.
+function entityEditWriteExcludedFields(featureName, entityName, registry) {
+    const excludedFor = (verb) => registry.getWriteHandler(`${qualifyEntityName(featureName, QnTypes.write, entityName)}:${verb}`)
+        ?.excludedFields;
+    const create = excludedFor("create");
+    const update = excludedFor("update");
+    if (create === undefined && update === undefined)
+        return {};
+    return {
+        writeExcludedFields: {
+            ...(create !== undefined && { create }),
+            ...(update !== undefined && { update }),
+        },
+    };
+}
 function collectEncryptedConfigKeyQns(registry) {
     const qns = new Set();
     for (const [featureName, feature] of registry.features) {

package/dist/engine/cross-tenant.d.ts

@@ -1,3 +1,4 @@
 import { AccessDeniedError } from "../errors/index.js";
 import type { SessionUser } from "./types/index.js";
-export declare function crossTenantOverrideDenied(user: SessionUser, tenantIdOverride: string | undefined, i18nKey: string): AccessDeniedError | undefined;
+export declare function mayOverrideTenant(user: SessionUser): boolean;
+export declare function tenantOverrideDenied(user: SessionUser, parsedPayload: unknown): AccessDeniedError | undefined;

package/dist/engine/cross-tenant.js

@@ -1,18 +1,22 @@
-import { AccessDeniedError } from "../errors/index.js";
-// A payload-supplied target tenant (tenantIdOverride) on a TenantAdmin-reachable
-// handler is the cross-tenant escape hatch: hasAccess passes the handler for any
-// TenantAdmin, so without a SystemAdmin gate a TenantAdmin could act on another
-// tenant. Centralizes the check the override handlers used to inline. Returns
-// the denial to `throw` (queries) or wrap in `writeFailure` (writes), or
-// undefined when allowed. The i18nKey stays per-feature so existing
-// translations keep resolving.
-export function crossTenantOverrideDenied(user, tenantIdOverride, i18nKey) {
-    if (tenantIdOverride === undefined)
-        return undefined;
-    if (user.roles.includes("SystemAdmin"))
+import { ROLES } from "../auth/roles.js";
+import { AccessDeniedError, FrameworkReasons } from "../errors/index.js";
+export function mayOverrideTenant(user) {
+    return user.roles.includes(ROLES.SystemAdmin);
+}
+function carriesTenantOverride(payload) {
+    return (typeof payload === "object" &&
+        payload !== null &&
+        "tenantIdOverride" in payload &&
+        payload.tenantIdOverride !== undefined);
+}
+// A payload-supplied target tenant (tenantIdOverride) is the cross-tenant escape hatch:
+// hasAccess passes a handler for any TenantAdmin, so the dispatcher refuses the field
+// for everyone but a SystemAdmin before any handler sees it. Runs on the schema-parsed
+// payload, so only handlers that declare the field are affected.
+export function tenantOverrideDenied(user, parsedPayload) {
+    if (!carriesTenantOverride(parsedPayload) || mayOverrideTenant(user))
         return undefined;
     return new AccessDeniedError({
-        i18nKey,
-        details: { reason: "tenant_override_requires_system_admin" },
+        details: { reason: FrameworkReasons.tenantOverrideRequiresSystemAdmin },
     });
 }

package/dist/engine/entity-handlers.js

@@ -217,15 +217,14 @@ export function defineEntityWriteHandler(name, entity, options) {
     // actingUserFor reads the row it is about to touch anyway, so for these calls it reports the
     // cross-tenant use per row (with that row as target) instead of dbFor reporting once up front.
     const reportsPerTouchedRow = (ctx) => ctx.systemDb === undefined && crossTenantReason !== undefined && !entity.systemStream;
-    // The event stream is keyed by the acting user's tenantId (streamTenantFor in
-    // event-store-executor-context.ts), not by the db handed to the executor — an
-    // unfiltered "system"-mode db alone reads the foreign row but appends to an
-    // empty stream in the operator's own tenant, surfacing as a bogus
-    // version_conflict. Rewriting the acting tenant also keeps PII envelope keys
-    // derived from the row's tenant rather than the operator's.
-    const actingUserFor = async (user, id, db, ctx) => {
+    // The event stream defaults to the acting user's tenant (streamTenantFor in
+    // event-store-executor-context.ts), not the db's — an unfiltered "system"-mode db alone
+    // reads the foreign row but appends to an empty stream in the operator's own tenant,
+    // surfacing as a bogus version_conflict. The row's tenant goes to the executor as
+    // streamTenantId so stream and PII keys follow the row while the actor stays the operator.
+    const foreignRowTenantFor = async (user, id, db, ctx) => {
         if (crossTenantReason === undefined || entity.systemStream)
-            return user;
+            return undefined;
         const row = await db.fetchOne(table, { id });
         const rowTenantId = row?.["tenantId"];
         if (reportsPerTouchedRow(ctx)) {
@@ -235,8 +234,8 @@ export function defineEntityWriteHandler(name, entity, options) {
                 : undefined);
         }
         if (typeof rowTenantId !== "string" || rowTenantId === user.tenantId)
-            return user;
-        return { ...user, tenantId: rowTenantId };
+            return undefined;
+        return parseTenantId(rowTenantId) ?? undefined;
     };
     let schema;
     let handler;
@@ -272,14 +271,15 @@ export function defineEntityWriteHandler(name, entity, options) {
                     ...submitted,
                     changes: dropEmptyWriteOnlyValues(entity, submitted.changes),
                 };
-                const user = await actingUserFor(event.user, payload.id, db, ctx);
+                const streamTenantId = await foreignRowTenantFor(event.user, payload.id, db, ctx);
                 // skipUnchanged (#464): API-driven updates diff against the stored
                 // row so a resubmitted-but-identical field doesn't force a fresh
                 // pii/encrypted ciphertext. Direct executor.update() callers (e.g.
                 // KEK-rotation, the user-data-rights #494 backfill) don't go through
                 // this handler and keep today's always-re-encrypt behavior, which
                 // they rely on to intentionally force a fresh event/ciphertext.
-                return executor.update(payload, user, db, {
+                return executor.update(payload, event.user, db, {
+                    streamTenantId,
                     skipUnchanged: true,
                     preSave: runPreSave &&
                         ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
@@ -291,8 +291,8 @@ export function defineEntityWriteHandler(name, entity, options) {
             handler = async (event, ctx) => {
                 const db = dbFor(ctx);
                 const payload = event.payload; // @cast-boundary engine-payload
-                const user = await actingUserFor(event.user, payload.id, db, ctx);
-                return executor.delete(payload, user, db);
+                const streamTenantId = await foreignRowTenantFor(event.user, payload.id, db, ctx);
+                return executor.delete(payload, event.user, db, { streamTenantId });
             };
             break;
         case "restore":
@@ -300,8 +300,8 @@ export function defineEntityWriteHandler(name, entity, options) {
             handler = async (event, ctx) => {
                 const db = dbFor(ctx);
                 const payload = event.payload; // @cast-boundary engine-payload
-                const user = await actingUserFor(event.user, payload.id, db, ctx);
-                return executor.restore(payload, user, db);
+                const streamTenantId = await foreignRowTenantFor(event.user, payload.id, db, ctx);
+                return executor.restore(payload, event.user, db, { streamTenantId });
             };
             break;
         default:
@@ -315,6 +315,7 @@ export function defineEntityWriteHandler(name, entity, options) {
         access: options.access,
         ...(options.description !== undefined && { description: options.description }),
         ...(agentHints !== undefined && { agent: agentHints }),
+        ...(excludedFields.length > 0 && { excludedFields }),
     };
 }
 // Append read-time derived-field values (EntityDefinition.derivedFields) to

package/dist/engine/factories.d.ts

@@ -179,6 +179,8 @@ export declare function createEntity<F, const T extends EntityTenancy = "tenant"
     /** Event stream lives on SYSTEM_TENANT_ID (tenant-independent aggregate, e.g.
      *  user) instead of the creator's tenant. See EntityDefinition.systemStream. */
     readonly systemStream?: boolean;
+    readonly eventVersion?: number;
+    readonly eventMigrations?: EntityDefinition["eventMigrations"];
     readonly searchWeight?: number;
     readonly defaultCurrency?: string;
     readonly transitions?: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;

package/dist/engine/feature-ast/extractors/handlers.js

@@ -29,6 +29,7 @@ const WRITE_HANDLER_KEY_KINDS = {
     access: "modeled",
     description: "modeled",
     agent: "modeled",
+    excludedFields: "opaque",
     unsafeSkipTransitionGuard: "modeled",
     rateLimit: "modeled",
     additionalRateLimits: "modeled",

package/dist/engine/feature-entity-handlers.js

@@ -103,6 +103,7 @@ export function buildEntityHandlerMethods(state, name) {
                     handler: def.handler,
                     access: def.access,
                     ...agentSlots(def),
+                    ...(def.excludedFields && { excludedFields: def.excludedFields }),
                     ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
                     ...(def.rateLimit && { rateLimit: def.rateLimit }),
                     ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),

package/dist/engine/index.d.ts

@@ -14,7 +14,7 @@ export type { SystemHookName } from "./constants.js";
 export { ConcurrencyModes, ConfigScopes, LifecycleHookTypes, MessageKind, OnDeleteStrategies, SystemHookNames, SystemHookPriorities, TENANT_CURRENCY_CONFIG_KEY, tenantChannel, } from "./constants.js";
 export type { App, AppConfig } from "./create-app.js";
 export { createApp } from "./create-app.js";
-export { crossTenantOverrideDenied } from "./cross-tenant.js";
+export { mayOverrideTenant, tenantOverrideDenied } from "./cross-tenant.js";
 export { dedupeFeatures } from "./dedupe-features.js";
 export { defineFeature } from "./define-feature.js";
 export type { PagedQueryHandlerDefinition, QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "./define-handler.js";

package/dist/engine/index.js

@@ -12,7 +12,7 @@ export { parseChangesetChanges } from "./changeset-changes.js";
 export { access, createSeed, createSystemConfig, createSystemSeed, createTenantConfig, createTenantSeed, createUserConfig, createUserSeed, isEncryptedAtRest, } from "./config-helpers.js";
 export { ConcurrencyModes, ConfigScopes, LifecycleHookTypes, MessageKind, OnDeleteStrategies, SystemHookNames, SystemHookPriorities, TENANT_CURRENCY_CONFIG_KEY, tenantChannel, } from "./constants.js";
 export { createApp } from "./create-app.js";
-export { crossTenantOverrideDenied } from "./cross-tenant.js";
+export { mayOverrideTenant, tenantOverrideDenied } from "./cross-tenant.js";
 export { dedupeFeatures } from "./dedupe-features.js";
 export { defineFeature } from "./define-feature.js";
 export { definePagedQueryHandler, defineQueryHandler, defineWriteHandler, isPagedQueryHandler, } from "./define-handler.js";

package/dist/engine/registry-validate.d.ts

@@ -1,5 +1,6 @@
+import { type EntityLifecycleVerb } from "../db/event-store-executor-context.js";
 import type { RegistryState } from "./registry-state.js";
-import type { FeatureDefinition } from "./types/index.js";
+import type { EntityEventMigration, EventUpcastFn, FeatureDefinition } from "./types/index.js";
 export declare function finalizeWorkspaceNavMembership(state: RegistryState): void;
 export declare function populateHandlerEntityMappings(state: RegistryState, features: readonly FeatureDefinition[]): void;
 export declare function validateExtensionSelectors(state: RegistryState): void;
@@ -10,6 +11,10 @@ export declare function buildIncomingRelations(state: RegistryState): void;
 export declare function validateFieldAccessHandlersAreEntityMapped(state: RegistryState, features: readonly FeatureDefinition[]): void;
 export declare function validateRelationTargetsExist(state: RegistryState): void;
 export declare function validateEventMigrationVersions(state: RegistryState, features: readonly FeatureDefinition[]): void;
+export declare const ENTITY_LIFECYCLE_VERBS: readonly ["created", "updated", "deleted", "restored", "forgotten"];
+type RowTransform = EntityEventMigration["transform"];
+export declare function adaptRowTransformToPayload(verb: EntityLifecycleVerb, transform: RowTransform): EventUpcastFn;
+export declare function buildEntityEventUpcasterChains(state: RegistryState): void;
 export declare function buildEventUpcasterChains(state: RegistryState, features: readonly FeatureDefinition[]): void;
 export declare function validateProjectionApplyKeys(state: RegistryState): void;
 export declare function validateRequiredFeatures(state: RegistryState, features: readonly FeatureDefinition[]): void;
@@ -24,3 +29,4 @@ export declare function validateExtensionUsageTargets(state: RegistryState): voi
 export declare function computeHasRateLimitedHandler(state: RegistryState): void;
 export declare function publishEventPiiCatalog(state: RegistryState): void;
 export declare function autoWireSoftDeleteJobs(state: RegistryState): void;
+export {};