@cosmicdrift/kumiko-framework 0.354.0 → 0.355.0

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/schema-builder.js

@@ -406,6 +406,38 @@ export function buildInsertSchema(entity, currencies = [...DEFAULT_CURRENCIES],
     }
     return applyTotalsMatchRefinements(entity, z.object(shape));
 }
+// Field types whose column is nullable and whose projection write accepts a
+// plain `null`. Excluded: select/writeOnly text (fieldToZod is already
+// nullable there), and types where null would not clear cleanly — NOT NULL
+// jsonb columns (multiSelect, embedded, jsonb, multi reference), files/images
+// (no column; stripped from updates), locatedTimestamp (split into _utc/_tz
+// columns, a bare null targets a column that does not exist) and money (the
+// currency column would keep its stale value).
+const NULL_CLEARABLE_FIELD_TYPES = new Set([
+    "text",
+    "longText",
+    "boolean",
+    "number",
+    "bigInt",
+    "decimal",
+    "reference",
+    "date",
+    "timestamp",
+    "tz",
+    "file",
+    "image",
+]);
+function isClearableByNull(field) {
+    if (!NULL_CLEARABLE_FIELD_TYPES.has(field.type))
+        return false;
+    if (field.type === "reference" && field.multiple === true)
+        return false;
+    if (field.type === "text" && field.writeOnly === true)
+        return false;
+    const isRequired = "required" in field && field.required === true;
+    const hasDefault = "default" in field && field.default !== undefined;
+    return !isRequired && !hasDefault;
+}
 export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES], excludedFields = []) {
     const shape = {};
     for (const [name, field] of Object.entries(entity.fields)) {
@@ -421,10 +453,11 @@ export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES],
         // fieldToZod still knows the default for its "" → default mapping
         // (e.g. select) — applyDefaults: false only suppresses the schema-level
         // `.default(...)` fallback for a genuinely omitted key.
-        shape[name] = fieldToZod(field, currencies, {
+        const zodField = fieldToZod(field, currencies, {
             applyDefaults: false,
             isUpdate: true,
-        }).optional();
+        });
+        shape[name] = (isClearableByNull(field) ? zodField.nullable() : zodField).optional();
     }
     return applyTotalsMatchRefinements(entity, z.object(shape));
 }

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/event-store.d.ts

@@ -24,6 +24,7 @@ export declare function loadAggregateAsOf(db: DbRunner, aggregateId: string, ten
     readonly includeArchived?: boolean;
 }): Promise<readonly StoredEvent[]>;
 export declare function getStreamVersion(db: DbRunner, aggregateId: string, tenantId: TenantId): Promise<number>;
+export declare function getStreamVersions(db: DbRunner, aggregateIds: readonly string[], tenantId: TenantId): Promise<Map<string, number>>;
 /** MAX(version) for one aggregate — no tenant filter. SECURITY: existence-oracle,
  *  a caller can probe whether an aggregateId has any events regardless of tenant
  *  membership. Only call from seed/system-internal paths (idempotency checks

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

@@ -4,7 +4,7 @@ import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { requestContext } from "../api/request-context.js";
 import { encryptEventPayloadPii } from "../crypto/event-pii.js";
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
-import { claimXactId, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, } from "../db/queries/event-store.js";
+import { claimXactId, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
 import { insertOne, selectMany } from "../db/query.js";
 import { isStreamArchived } from "./archive.js";
 import { IdempotentAppendConflictError, VersionConflictError } from "./errors.js";
@@ -223,6 +223,9 @@ export async function loadAggregateAsOf(db, aggregateId, tenantId, asOf, options
 export async function getStreamVersion(db, aggregateId, tenantId) {
     return selectStreamMaxVersion(db, aggregateId, tenantId);
 }
+export async function getStreamVersions(db, aggregateIds, tenantId) {
+    return selectStreamMaxVersions(db, aggregateIds, tenantId);
+}
 /** MAX(version) for one aggregate — no tenant filter. SECURITY: existence-oracle,
  *  a caller can probe whether an aggregateId has any events regardless of tenant
  *  membership. Only call from seed/system-internal paths (idempotency checks

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

@@ -2,7 +2,7 @@ export { APP_INSTANCE_STREAM_TYPE, APP_STARTED_EVENT_TYPE } from "../crypto/syst
 export { backfillEventPiiEncryption, backfillEventPiiEncryptionBatch, type PiiBackfillBatchOptions, type PiiBackfillBatchResult, type PiiBackfillFailure, type PiiBackfillOptions, type PiiBackfillResult, type PiiBackfillScanCache, } from "../db/queries/backfill-pii.js";
 export { type ArchiveStreamArgs, archivedStreamsTable, archiveStream, createArchivedStreamsTable, isStreamArchived, restoreStream, } from "./archive.js";
 export { ArchivedStreamError, IdempotentAppendConflictError, VersionConflictError, } from "./errors.js";
-export { append, EVENTS_PUBSUB_CHANNEL, type EventMetadata, type EventToAppend, getEventsHighWaterMark, getStreamVersion, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, type StoredEvent, streamAllEventsByType, } from "./event-store.js";
+export { append, EVENTS_PUBSUB_CHANNEL, type EventMetadata, type EventToAppend, getEventsHighWaterMark, getStreamVersion, getStreamVersions, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, type StoredEvent, streamAllEventsByType, } from "./event-store.js";
 export { createEventsTable, eventsTable } from "./events-schema.js";
 export { appendProvenanceEvent, type ProvenanceEventInput } from "./provenance-append.js";
 export { createRebuildDeadLetterTable, listRebuildDeadLetters, type RebuildDeadLetterRow, rebuildDeadLetterTable, recordRebuildDeadLetters, type SkippedApply, } from "./rebuild-dead-letter.js";

package/dist/event-store/index.js

@@ -2,7 +2,7 @@ export { APP_INSTANCE_STREAM_TYPE, APP_STARTED_EVENT_TYPE } from "../crypto/syst
 export { backfillEventPiiEncryption, backfillEventPiiEncryptionBatch, } from "../db/queries/backfill-pii.js";
 export { archivedStreamsTable, archiveStream, createArchivedStreamsTable, isStreamArchived, restoreStream, } from "./archive.js";
 export { ArchivedStreamError, IdempotentAppendConflictError, VersionConflictError, } from "./errors.js";
-export { append, EVENTS_PUBSUB_CHANNEL, getEventsHighWaterMark, getStreamVersion, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, streamAllEventsByType, } from "./event-store.js";
+export { append, EVENTS_PUBSUB_CHANNEL, getEventsHighWaterMark, getStreamVersion, getStreamVersions, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, streamAllEventsByType, } from "./event-store.js";
 export { createEventsTable, eventsTable } from "./events-schema.js";
 export { appendProvenanceEvent } from "./provenance-append.js";
 export { createRebuildDeadLetterTable, listRebuildDeadLetters, rebuildDeadLetterTable, recordRebuildDeadLetters, } from "./rebuild-dead-letter.js";

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;

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