@cosmicdrift/kumiko-framework 0.354.1 → 0.356.0

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";
@@ -80,7 +80,7 @@ export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUse
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
 export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, type TransferAdjacency, type TransferEdge, type TransferEdgeLink, } from "./transfer-adjacency.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
-export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
+export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TenantWriteTarget, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.js";
 export { runValidation } from "./validation.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,8 +6,8 @@ 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 { 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 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, TenantWriteTarget, 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";
 export type { HttpRouteDefinition, HttpRouteHandler, HttpRouteHandlerDeps, HttpRouteMethod, } from "@cosmicdrift/kumiko-types/http-route";
@@ -17,7 +17,7 @@ export type { ContentCollectionDefinition, NavDefinition, NavIconKey, } from "@c
 export type { FromRule, FromRuleKind, OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule, SqlFragment, WhereRule, WhereRuleContext, } from "@cosmicdrift/kumiko-types/ownership";
 export type { EntityProjectionExtension, MspErrorMode, MspErrorPolicy, MultiStreamApplyFn, MultiStreamProjectionDefinition, ProjectionDefinition, ProjectionRowIdOf, ProjectionTable, SingleStreamApplyFn, } from "@cosmicdrift/kumiko-types/projection";
 export type { BelongsToRelation, EntityRelations, HasManyRelation, ManyToManyRelation, RelationDefinition, } from "@cosmicdrift/kumiko-types/relations";
-export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelGate, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormWidth, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
+export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelGate, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormWidth, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
 export type { TargetRef } from "@cosmicdrift/kumiko-types/target-ref";
 export type { Subscribe, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, } from "@cosmicdrift/kumiko-types/tree-node";

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,24 @@ 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);
+        };
+        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 +907,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: gatedIdentitySwitch.queryAs,
             queryAsMember: (userId, qn, payload) => {
                 if (!dispatchWriteRef) {
                     throw new Error("JobContext.queryAsMember called before dispatcher attached — call attachDispatcher() first");
@@ -970,7 +983,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 +1001,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 +1204,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;

package/dist/observability/escape-hatch-report.js

@@ -1,3 +1,5 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createFallbackLogger } from "../logging/utils.js";
 import { emitEscapeHatchUse } from "./standard-metrics.js";
 export const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
 const DEFAULT_WINDOW_MS = 60_000;
@@ -30,21 +32,35 @@ export function createEscapeHatchProcessDedup(kinds) {
 }
 // Default window for createEscapeHatchReporter callers that don't pass their own.
 const fallbackReportWindow = createEscapeHatchReportWindow();
-const consoleLogger = {
-    info() { },
-    warn(msg, data) {
-        // biome-ignore lint/suspicious/noConsole: fallback for callers without a logger — dropping the call would lose the report silently.
-        console.warn(msg, data);
-    },
-    error(msg, data) {
-        // biome-ignore lint/suspicious/noConsole: same fallback, see warn above.
-        console.error(msg, data);
-    },
-    debug() { },
-    child() {
-        return consoleLogger;
-    },
-};
+// Sink writes that have started and not settled yet, process-wide: shutdown flushes them.
+const processPendingAudits = new Set();
+// The sink writes of the dispatch or job run currently executing.
+const scopePendingAudits = new AsyncLocalStorage();
+function trackPendingAudit(write) {
+    processPendingAudits.add(write);
+    scopePendingAudits.getStore()?.add(write);
+    void write.finally(() => processPendingAudits.delete(write));
+}
+// Awaits the audit writes started inside `run` once it has returned, so callers place it around
+// the transaction and the write is durable when the dispatch or run ends. Nested scopes belong
+// to the outermost one (a nested dispatch runs inside its caller's transaction, which must not
+// wait on the sink). Sink failures are already logged by reportEscapeHatchUse and never throw here.
+export async function withEscapeHatchAuditScope(run) {
+    if (scopePendingAudits.getStore() !== undefined)
+        return run();
+    const pending = new Set();
+    try {
+        return await scopePendingAudits.run(pending, run);
+    }
+    finally {
+        await Promise.allSettled([...pending]);
+    }
+}
+export async function flushEscapeHatchAudits() {
+    while (processPendingAudits.size > 0) {
+        await Promise.allSettled([...processPendingAudits]);
+    }
+}
 function eventFields(event) {
     return {
         handler: event.handler,
@@ -52,26 +68,38 @@ function eventFields(event) {
         reason: event.reason,
         tenantId: event.tenantId,
         actor: event.actor,
+        ...(event.caller !== undefined && { caller: event.caller }),
         ...(event.target && { targetId: event.target.id, targetTenantId: event.target.tenantId }),
     };
 }
 export function reportEscapeHatchUse(event, deps) {
-    const logger = deps.log ?? consoleLogger;
     const fields = eventFields(event);
     if (deps.sink) {
-        void deps.sink(event).catch((err) => {
-            logger.error(`${ESCAPE_HATCH_USED_SIGNAL}: audit sink failed`, {
+        const write = deps.sink(event).catch((err) => {
+            deps.log.error(`${ESCAPE_HATCH_USED_SIGNAL}: audit sink failed`, {
                 ...fields,
                 error: err instanceof Error ? err.message : String(err),
             });
         });
-        return;
+        trackPendingAudit(write);
+    }
+    else {
+        deps.log.warn(ESCAPE_HATCH_USED_SIGNAL, fields);
     }
-    logger.warn(ESCAPE_HATCH_USED_SIGNAL, fields);
 }
 export function createEscapeHatchReporter(opts) {
     const window = opts.window ?? fallbackReportWindow;
     const now = opts.now ?? Date.now;
+    const deps = { sink: opts.sink, log: opts.log };
+    const eventFor = (kind, reason, target) => ({
+        handler: opts.handler,
+        kind,
+        reason,
+        tenantId: opts.tenantId,
+        actor: opts.actor,
+        ...(opts.caller !== undefined && { caller: opts.caller }),
+        target,
+    });
     return (kind, reason, target) => {
         if (opts.meter)
             emitEscapeHatchUse(opts.meter, opts.handler, kind);
@@ -82,7 +110,7 @@ export function createEscapeHatchReporter(opts) {
             if (processDedup.seen.has(processKey))
                 return;
             processDedup.seen.add(processKey);
-            reportEscapeHatchUse({ handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target }, { sink: opts.sink, log: opts.log });
+            reportEscapeHatchUse(eventFor(kind, reason, target), deps);
             // skip: audited above, the window dedup below only serves the other kinds
             return;
         }
@@ -92,13 +120,14 @@ export function createEscapeHatchReporter(opts) {
             reason,
             opts.tenantId,
             opts.actor,
+            opts.caller ?? null,
             target?.id ?? null,
             target?.tenantId ?? null,
         ]);
         // skip: same (handler, kind, reason, target) already reported within the window — dedup
         if (!window.shouldReport(key, now()))
             return;
-        reportEscapeHatchUse({ handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target }, { sink: opts.sink, log: opts.log });
+        reportEscapeHatchUse(eventFor(kind, reason, target), deps);
     };
 }
 // Actor for escape-hatch uses whose caller did not thread one through. Stays
@@ -109,5 +138,6 @@ export function fallbackEscapeHatchReporter(tenantId) {
         handler: "<unattributed>",
         tenantId,
         actor: "<unattributed>",
+        log: createFallbackLogger("escape-hatch"),
     });
 }

package/dist/observability/index.d.ts

@@ -1,6 +1,6 @@
 export { type ConsoleProviderOptions, createConsoleProvider } from "./console-provider.js";
 export { observabilityContext } from "./context.js";
-export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, type EscapeHatchProcessDedup, type EscapeHatchReportWindow, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
+export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, type EscapeHatchProcessDedup, type EscapeHatchReportWindow, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "./escape-hatch-report.js";
 export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback.js";
 export { generateSpanId, generateTraceId } from "./ids.js";
 export { buildMetricName, validateLabelKey, validateMetricName, } from "./metric-validator.js";

package/dist/observability/index.js

@@ -1,7 +1,7 @@
 // Public surface of the observability module.
 export { createConsoleProvider } from "./console-provider.js";
 export { observabilityContext } from "./context.js";
-export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
+export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "./escape-hatch-report.js";
 export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback.js";
 export { generateSpanId, generateTraceId } from "./ids.js";
 export { buildMetricName, validateLabelKey, validateMetricName, } from "./metric-validator.js";

package/dist/pipeline/dispatch-query.js

@@ -1,4 +1,5 @@
 import { hasAccess } from "../engine/access.js";
+import { tenantOverrideDenied } from "../engine/cross-tenant.js";
 import { filterReadFields } from "../engine/field-access.js";
 import { NotFoundError, validationErrorFromZod } from "../errors/index.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
@@ -41,6 +42,9 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx) {
     if (!parsed.success) {
         throw validationErrorFromZod(parsed.error);
     }
+    const overrideDenied = tenantOverrideDenied(user, parsed.data);
+    if (overrideDenied)
+        throw overrideDenied;
     // Trash opt-in rides the validated query payload: only the entity-list
     // schema (and custom query schemas that opt in) carries `includeDeleted`,
     // so other handlers never see the flag. Visibility filters still apply