@cosmicdrift/kumiko-framework 0.354.1 → 0.355.0

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 {};

package/dist/engine/registry-validate.js

@@ -1,5 +1,6 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii.js";
 import { hasSearchablePlaintext, isSensitiveLabelField } from "../db/entity-field-encryption.js";
+import { entityEventName } from "../db/event-store-executor-context.js";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js";
 import { resolveName } from "./handler-helpers.js";
 import { parseRefTargetEntityName } from "./parse-ref-target.js";
@@ -327,6 +328,86 @@ export function validateEventMigrationVersions(state, features) {
         }
     }
 }
+export const ENTITY_LIFECYCLE_VERBS = [
+    "created",
+    "updated",
+    "deleted",
+    "restored",
+    "forgotten",
+];
+const MAX_ENTITY_EVENT_VERSION = 999;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// created is the flat row, updated carries changes + previous, the rest only previous.
+function rowPartKeys(verb) {
+    if (verb === "created")
+        return "whole";
+    if (verb === "updated")
+        return ["changes", "previous"];
+    return ["previous"];
+}
+export function adaptRowTransformToPayload(verb, transform) {
+    const parts = rowPartKeys(verb);
+    return async (payload, ctx) => {
+        if (!isRecord(payload))
+            return payload;
+        if (parts === "whole")
+            return transform(payload, ctx);
+        const result = { ...payload };
+        for (const key of parts) {
+            const part = payload[key];
+            if (isRecord(part))
+                result[key] = await transform(part, ctx);
+        }
+        return result;
+    };
+}
+// Boot-time check of an entity's eventVersion/eventMigrations; returns the steps keyed by fromVersion, empty for v1.
+function entityEventMigrationSteps(entityName, eventVersion, migrations) {
+    if (!Number.isInteger(eventVersion) ||
+        eventVersion < 1 ||
+        eventVersion > MAX_ENTITY_EVENT_VERSION) {
+        throw new Error(`Entity "${entityName}" declares eventVersion ${String(eventVersion)}; it must be an integer between 1 and ${MAX_ENTITY_EVENT_VERSION}.`);
+    }
+    if (eventVersion === 1 && migrations.length > 0) {
+        throw new Error(`Entity "${entityName}" declares eventMigrations but no eventVersion > 1. Set eventVersion to the target version.`);
+    }
+    const steps = new Map();
+    for (const m of migrations) {
+        if (m.toVersion !== m.fromVersion + 1 || m.toVersion > eventVersion) {
+            throw new Error(`Entity "${entityName}" declares an eventMigration v${m.fromVersion} → v${m.toVersion}; ` +
+                `steps must advance by exactly one and not exceed eventVersion ${eventVersion}.`);
+        }
+        steps.set(m.fromVersion, m.transform);
+    }
+    for (let v = 1; v < eventVersion; v++) {
+        if (!steps.has(v)) {
+            throw new Error(`Entity "${entityName}" declares eventVersion ${eventVersion} but no eventMigration ` +
+                `covers the step v${v} → v${v + 1}.`);
+        }
+    }
+    return steps;
+}
+export function buildEntityEventUpcasterChains(state) {
+    for (const [entityName, entity] of state.entityMap) {
+        const eventVersion = entity.eventVersion ?? 1;
+        const steps = entityEventMigrationSteps(entityName, eventVersion, entity.eventMigrations ?? []);
+        if (eventVersion === 1)
+            continue;
+        for (const verb of ENTITY_LIFECYCLE_VERBS) {
+            const key = entityEventName(entityName, verb);
+            if (state.eventUpcasterMap.has(key) || state.eventMap.has(key)) {
+                throw new Error(`Entity event type "${key}" collides with an already registered event; event types must be unique.`);
+            }
+            const chain = new Map();
+            for (const [from, transform] of steps) {
+                chain.set(from, adaptRowTransformToPayload(verb, transform));
+            }
+            state.eventUpcasterMap.set(key, { currentVersion: eventVersion, chain });
+        }
+    }
+}
 export function buildEventUpcasterChains(state, features) {
     // Stitch the upcaster chain per qualified event. At this point, gaps in
     // the chain (e.g. defineEvent version=3 but only a 1→2 migration exists)
@@ -371,7 +452,6 @@ export function validateProjectionApplyKeys(state) {
     // CRUD types per source entity PLUS every domain event registered via
     // r.defineEvent — an apply-handler for a domain event is how a projection
     // reacts to ctx.appendEvent writes on the same aggregate stream.
-    const AUTO_EVENT_VERBS = ["created", "updated", "deleted", "restored", "forgotten"];
     const allDomainEventNames = new Set(state.eventMap.keys());
     for (const [projName, projDef] of state.projectionMap) {
         const sources = Array.isArray(projDef.source) ? projDef.source : [projDef.source];
@@ -397,7 +477,7 @@ export function validateProjectionApplyKeys(state) {
         const isEventsOnlySource = !sources.every((src) => state.entityMap.has(src));
         for (const src of rebuildSources) {
             if (state.entityMap.has(src)) {
-                for (const verb of AUTO_EVENT_VERBS)
+                for (const verb of ENTITY_LIFECYCLE_VERBS)
                     validEventTypes.add(`${src}.${verb}`);
             }
         }

package/dist/engine/registry.js

@@ -3,7 +3,7 @@ import { dedupeFeatures } from "./dedupe-features.js";
 import { buildRegistryFacade } from "./registry-facade.js";
 import { populateClaimsAndAuth, populateConfigKeys, populateEvents, populateExtensionsAndSeeds, populateFeatureCore, populateHandlers, populateHooks, populateJobsAndNotifications, populateMetricsAndSecrets, populateProjectionsAndTables, populateScreensNavWorkspaces, populateSystemEvents, populateTranslations, } from "./registry-ingest.js";
 import { createInitialState } from "./registry-state.js";
-import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
+import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEntityEventUpcasterChains, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
 // This is where the magic happens. By "magic" I mean: precomputed maps.
 // I build everything once at boot (hooks, relations, searchable fields, ...)
 // so nothing has to iterate over objects at runtime. O(1) instead of O(n*m).
@@ -37,6 +37,7 @@ export function createRegistry(rawFeatures) {
     validateRelationTargetsExist(state);
     validateEventMigrationVersions(state, features);
     buildEventUpcasterChains(state, features);
+    buildEntityEventUpcasterChains(state);
     validateProjectionApplyKeys(state);
     validateRequiredFeatures(state, features);
     resolveNotificationTriggersAndRegisterHooks(state);

package/dist/engine/types/index.d.ts

@@ -6,7 +6,7 @@ export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap,
 export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsMap, } from "@cosmicdrift/kumiko-types/extension-options-map";
 export type { BootCheckContext, BootCheckFn, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
 export type { FieldIconKey } from "@cosmicdrift/kumiko-types/field-icon";
-export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
+export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityEventMigration, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
 export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadRateLimitOption, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
 export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export type { DeleteContext, EntityHookMap, HookMap, HookOwner, HookPhase, LifecycleHookFn, LifecycleResult, OwnedFn, PhasedHook, PostDeleteBatchHookFn, PostDeleteHookFn, PostQueryHookFn, PostSaveBatchHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SaveContext, SearchPayloadContributorFn, ValidationError, ValidationHookFn, } from "@cosmicdrift/kumiko-types/hooks";

package/dist/errors/reasons.d.ts

@@ -6,6 +6,7 @@ export declare const FrameworkReasons: {
     readonly featureDisabled: "feature_disabled";
     readonly systemIdentitySwitchDenied: "system_identity_switch_denied";
     readonly identitySwitchDenied: "identity_switch_denied";
+    readonly tenantOverrideRequiresSystemAdmin: "tenant_override_requires_system_admin";
     readonly unsafeAllTenantsDenied: "unsafe_all_tenants_denied";
     readonly memberResolutionDenied: "member_resolution_denied";
     readonly memberResolutionReadOnly: "member_resolution_read_only";

package/dist/errors/reasons.js

@@ -40,6 +40,8 @@ export const FrameworkReasons = {
     // non-SYSTEM identity other than its own caller (different user, tenant,
     // claims, origin or extra roles) without r.systemScope() or escapeHatch.
     identitySwitchDenied: "identity_switch_denied",
+    // AccessDeniedError: a payload carried tenantIdOverride but the caller is no SystemAdmin.
+    tenantOverrideRequiresSystemAdmin: "tenant_override_requires_system_admin",
     // AccessDeniedError: a handler/hook called ctx.queryProjection(..., { unsafeAllTenants: true })
     // without an r.systemScope() feature or a declared escapeHatch.
     unsafeAllTenantsDenied: "unsafe_all_tenants_denied",

package/dist/event-store/snapshot.d.ts

@@ -4,6 +4,7 @@ import type { DbConnection, DbRunner } from "../db/connection.js";
 import type { TenantId } from "../engine/types/index.js";
 export declare const snapshotsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
 export declare function createSnapshotsTable(db: DbConnection): Promise<void>;
+export declare function effectiveSnapshotGeneration(callerVersion: number, entityEventVersion: number | undefined): number;
 export type Snapshot<TState extends Record<string, unknown> = Record<string, unknown>> = {
     readonly aggregateId: string;
     readonly tenantId: TenantId;

package/dist/event-store/snapshot.js

@@ -68,6 +68,14 @@ export async function createSnapshotsTable(db) {
     }
     await unsafePushTables(db, { kumikoSnapshots: snapshotsTable });
 }
+const ENTITY_EVENT_VERSION_RADIX = 1000;
+// Entity eventVersion 1 keeps the caller generation (existing snapshots stay valid);
+// higher versions map to negative values, disjoint from caller generations (>= 1).
+export function effectiveSnapshotGeneration(callerVersion, entityEventVersion) {
+    if (entityEventVersion === undefined || entityEventVersion === 1)
+        return callerVersion;
+    return -(callerVersion * ENTITY_EVENT_VERSION_RADIX + entityEventVersion);
+}
 // Upsert-style save so re-snapshotting the same (aggregateId, version) is
 // idempotent. Caller can retake a snapshot at the same version without
 // bespoke error handling — useful when a feature's snapshot policy runs
@@ -120,9 +128,10 @@ export async function loadAggregateWithSnapshot(db, aggregateId, tenantId, reduc
             return { state: initial, version: 0, snapshotHit: false };
         }
     }
-    const shapeVersion = options?.snapshotVersion ?? 1;
+    const callerVersion = options?.snapshotVersion ?? 1;
+    const generationFor = (aggregateType) => effectiveSnapshotGeneration(callerVersion, options?.entityEventVersionOf?.(aggregateType));
     const stored = await loadLatestSnapshot(db, aggregateId, tenantId);
-    const snapshot = stored && stored.snapshotVersion === shapeVersion ? stored : null;
+    const snapshot = stored && stored.snapshotVersion === generationFor(stored.aggregateType) ? stored : null;
     const baseState = snapshot ? snapshot.state : initial;
     const afterVersion = snapshot ? snapshot.version : 0;
     const delta = await loadEventsAfterVersion(db, aggregateId, tenantId, afterVersion);
@@ -141,7 +150,7 @@ export async function loadAggregateWithSnapshot(db, aggregateId, tenantId, reduc
                 aggregateType: lastDelta.aggregateType,
                 version: latestVersion,
                 state,
-                snapshotVersion: shapeVersion,
+                snapshotVersion: generationFor(lastDelta.aggregateType),
             });
         }
         catch {

package/dist/jobs/job-runner.js

@@ -11,9 +11,10 @@ import { InternalError } from "../errors/index.js";
 import { isKumikoError } from "../errors/kumiko-error.js";
 import { createFileContext } from "../files/file-handle.js";
 import { createFallbackLogger } from "../logging/index.js";
-import { createEscapeHatchProcessDedup, createEscapeHatchReporter, emitJobLastSuccess, emitJobQueueDepth, getFallbackTracer, registerStandardMetrics, } from "../observability/index.js";
+import { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, emitJobLastSuccess, emitJobQueueDepth, flushEscapeHatchAudits, getFallbackTracer, registerStandardMetrics, withEscapeHatchAuditScope, } from "../observability/index.js";
 import { createDistributedLock } from "../pipeline/distributed-lock.js";
 import { RedisKeys } from "../pipeline/redis-keys.js";
+import { createGatedIdentitySwitch } from "../pipeline/system-identity-switch.js";
 import { buildPersonalDataGate, isPersonalDataGated, parseWriteOrigin, } from "../pipeline/write-origin.js";
 import { bridgeStub } from "../testing/handler-context.js";
 // Shape-checked after the BullMQ/Redis JSON round-trip. Unlike `_writeOrigin`
@@ -333,6 +334,7 @@ export function createJobRunner(options) {
     if (context.meter)
         registerStandardMetrics(context.meter);
     // Instance-scoped, not module-level: each runner (and each test) audits a system cron's declared hatch once.
+    const escapeHatchReportWindow = createEscapeHatchReportWindow();
     const systemCronEscapeHatchDedup = createEscapeHatchProcessDedup([
         "unsafe-raw",
         "global-write",
@@ -365,7 +367,8 @@ export function createJobRunner(options) {
                 tenantId: SYSTEM_TENANT_ID,
                 actor: systemUser.id,
                 sink: context._escapeHatchAuditSink,
-                log: context.log,
+                log: errorLogger,
+                window: escapeHatchReportWindow,
             });
             const result = await handler.handler({ type: ACTIVE_TENANT_IDS_QUERY_NAME, payload: {}, user: systemUser }, {
                 db: systemModeDb,
@@ -815,7 +818,9 @@ export function createJobRunner(options) {
             tenantId,
             actor: jobSystemUser.id,
             sink: context._escapeHatchAuditSink,
-            log: context.log,
+            log: errorLogger,
+            window: escapeHatchReportWindow,
+            ...(triggeredById !== null && { caller: triggeredById }),
             ...(isSystemCronRun && { processDedup: systemCronEscapeHatchDedup }),
             ...(context.meter && { meter: context.meter }),
         });
@@ -855,6 +860,25 @@ export function createJobRunner(options) {
         // Per-job-run reader, created lazily on queryAsMember's first call and
         // cached for the rest of this run.
         let memberReader;
+        const identitySwitchHatch = escapeHatchFor(jobDef.escapeHatch, "systemIdentity");
+        const identitySwitchGrantReason = identitySwitchHatch?.reason ??
+            (isSystemJob ? `r.systemScope() feature of job "${jobName}"` : undefined);
+        const ungatedQueryAs = (user, qn, payload) => {
+            if (!dispatchWriteRef) {
+                throw new Error("JobContext.queryAs called before dispatcher attached — call attachDispatcher() first");
+            }
+            return dispatchWriteRef.queryAs(user, qn, payload, jobOrigin);
+        };
+        // Only writeAs is gated for jobs; queryAs stays ungated (fw#2859).
+        const gatedIdentitySwitch = createGatedIdentitySwitch(`job "${jobName}"`, jobSystemUser, isSystemJob || identitySwitchHatch !== undefined, {
+            queryAs: ungatedQueryAs,
+            writeAs: async (user, qn, payload) => {
+                if (!dispatchWriteRef) {
+                    throw new Error("JobContext.writeAs called before dispatcher attached — call attachDispatcher() first");
+                }
+                return dispatchWriteRef.write(user, qn, payload, jobOrigin);
+            },
+        }, { reason: identitySwitchGrantReason, report: reportEscapeHatch });
         const jobContext = {
             ...context,
             db: jobDb ?? missingDbProxy(jobName),
@@ -884,18 +908,8 @@ export function createJobRunner(options) {
                 }
                 return dispatchWriteRef.write(jobSystemUser, qn, payload, jobOrigin);
             },
-            writeAs: (user, qn, payload) => {
-                if (!dispatchWriteRef) {
-                    throw new Error("JobContext.writeAs called before dispatcher attached — call attachDispatcher() first");
-                }
-                return dispatchWriteRef.write(user, qn, payload, jobOrigin);
-            },
-            queryAs: (user, qn, payload) => {
-                if (!dispatchWriteRef) {
-                    throw new Error("JobContext.queryAs called before dispatcher attached — call attachDispatcher() first");
-                }
-                return dispatchWriteRef.queryAs(user, qn, payload, jobOrigin);
-            },
+            writeAs: gatedIdentitySwitch.writeAs,
+            queryAs: ungatedQueryAs,
             queryAsMember: (userId, qn, payload) => {
                 if (!dispatchWriteRef) {
                     throw new Error("JobContext.queryAsMember called before dispatcher attached — call attachDispatcher() first");
@@ -970,7 +984,7 @@ export function createJobRunner(options) {
         // When parentContext is set, the new parent-aware StartSpanOptions
         // plumbs it through to startSpan — no manual try/finally needed.
         try {
-            await tracer.withSpan("job.execute", {
+            await withEscapeHatchAuditScope(() => tracer.withSpan("job.execute", {
                 attributes: {
                     "job.name": jobName,
                     "job.id": jobId,
@@ -988,7 +1002,7 @@ export function createJobRunner(options) {
                     ...(consumerLane !== undefined ? { "kumiko.job.consumer_lane": consumerLane } : {}),
                 },
                 ...(parentContext ? { parent: parentContext } : {}),
-            }, runInSpan);
+            }, runInSpan));
         }
         finally {
             // Release the sequential lock value-matched (Lua compare-and-delete
@@ -1191,6 +1205,7 @@ export function createJobRunner(options) {
                 readinessTimeout.cancel();
             }
             await Promise.all([queues.api.close(), queues.worker.close()]);
+            await flushEscapeHatchAudits();
             if (lockRedis) {
                 // quit() drains in-flight commands; disconnect() would cancel them
                 // and risk a half-released lock.

package/dist/observability/escape-hatch-report.d.ts

@@ -14,16 +14,19 @@ export type EscapeHatchProcessDedup = {
     readonly seen: Set<string>;
 };
 export declare function createEscapeHatchProcessDedup(kinds: readonly EscapeHatchKind[]): EscapeHatchProcessDedup;
+export declare function withEscapeHatchAuditScope<T>(run: () => Promise<T>): Promise<T>;
+export declare function flushEscapeHatchAudits(): Promise<void>;
 export declare function reportEscapeHatchUse(event: EscapeHatchUseEvent, deps: {
     readonly sink?: EscapeHatchAuditSink;
-    readonly log?: Logger;
+    readonly log: Pick<Logger, "warn" | "error">;
 }): void;
 export declare function createEscapeHatchReporter(opts: {
     readonly handler: string;
     readonly tenantId: TenantId;
     readonly actor: string;
+    readonly caller?: string | undefined;
     readonly sink?: EscapeHatchAuditSink;
-    readonly log?: Logger;
+    readonly log: Pick<Logger, "warn" | "error">;
     readonly window?: EscapeHatchReportWindow;
     readonly processDedup?: EscapeHatchProcessDedup;
     readonly meter?: Meter;