@cosmicdrift/kumiko-framework 0.340.0 → 0.341.0

package/dist/engine/feature-entity-handlers.d.ts

@@ -3,7 +3,7 @@ import type { ZodType } from "zod";
 import { type QueryHandlerDefinition, type StreamHandlerDefinition, type WriteHandlerDefinition } from "./define-handler.js";
 import type { RegisterEntityCrudOptions } from "./entity-handlers.js";
 import type { FeatureBuilderState } from "./feature-builder-state.js";
-import type { AccessRule, AgentHandlerHints, EntityDefinition, EntityRef, EscapeHatchDeclaration, HandlerRef, NameOrRef, QueryHandlerFn, RateLimitDeclaration, RelationDefinition, StreamHandlerFn, WriteHandlerFn } from "./types/index.js";
+import type { AccessRule, AgentHandlerHints, EntityDefinition, EntityRef, EscapeHatchDeclaration, HandlerRef, NameOrRef, PayloadRateLimitOption, QueryHandlerFn, RateLimitDeclaration, RelationDefinition, StreamHandlerFn, WriteHandlerFn } from "./types/index.js";
 export declare function buildEntityHandlerMethods<TName extends string>(state: FeatureBuilderState, name: TName): {
     entity(nameOrDefinition: string | ({
         readonly name: string;
@@ -17,6 +17,7 @@ export declare function buildEntityHandlerMethods<TName extends string>(state: F
     writeHandler<TName_1 extends string, TSchema extends ZodType>(nameOrDef: string | WriteHandlerDefinition<TName_1, TSchema>, schema?: TSchema, handler?: WriteHandlerFn<z.infer<TSchema>>, options?: {
         access: AccessRule;
         rateLimit?: RateLimitDeclaration;
+        additionalRateLimits?: readonly PayloadRateLimitOption[];
         description?: string;
         agent?: AgentHandlerHints;
         escapeHatch?: EscapeHatchDeclaration;

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

@@ -105,6 +105,7 @@ export function buildEntityHandlerMethods(state, name) {
                     ...agentSlots(def),
                     ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
                     ...(def.rateLimit && { rateLimit: def.rateLimit }),
+                    ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
                     ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
                     ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
                     // Forward the pipeline-build closure so boot-validators and
@@ -129,6 +130,9 @@ export function buildEntityHandlerMethods(state, name) {
                 access: inline.options.access,
                 ...agentSlots(inline.options),
                 ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
+                ...(inline.options.additionalRateLimits && {
+                    additionalRateLimits: inline.options.additionalRateLimits,
+                }),
                 ...(inline.options.escapeHatch && { escapeHatch: inline.options.escapeHatch }),
             };
             tryMapEntity(state, name, nameOrDef);

package/dist/engine/feature-ui-extensions.js

@@ -421,6 +421,15 @@ export function buildUiExtensionsMethods(state, name) {
                 throw new Error(`[Feature ${name}] httpRoute "${definition.method} ${definition.path}" must declare ` +
                     `anonymous: true | false — true mounts it public, false behind the session auth chain.`);
             }
+            const routeLimit = definition.rateLimit;
+            if (routeLimit !== undefined &&
+                (!Number.isInteger(routeLimit.limit) ||
+                    routeLimit.limit < 1 ||
+                    !Number.isInteger(routeLimit.windowSeconds) ||
+                    routeLimit.windowSeconds < 1)) {
+                throw new Error(`[Feature ${name}] httpRoute "${definition.method} ${definition.path}" rateLimit needs ` +
+                    `positive integer limit and windowSeconds.`);
+            }
             const key = `${definition.method} ${definition.path}`;
             if (state.httpRoutes[key]) {
                 throw new Error(`[Feature ${name}] HTTP-Route "${key}" already registered. ` +

package/dist/engine/index.d.ts

@@ -74,7 +74,7 @@ export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.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, 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, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, 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, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, 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, 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, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, 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 { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases, isAgentVisibleScreen, 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/membership-roles.js

@@ -10,6 +10,7 @@
 // matching strip (anonymous/all only) to globalRoles, where SystemAdmin
 // legitimately lives.
 import { access } from "./config-helpers.js";
+import { SYSTEM_ROLE } from "./system-user.js";
 export const FORBIDDEN_MEMBERSHIP_ROLES = new Set([
     ...access.privileged, // system, SystemAdmin
     ...access.all, // all
@@ -26,10 +27,13 @@ export function findForbiddenMembershipRole(roles) {
 export function stripForbiddenMembershipRoles(roles) {
     return roles.filter((role) => !isForbiddenMembershipRole(role));
 }
-// "anonymous"/"all" are never legitimate global roles; system/SystemAdmin stay.
+// "anonymous"/"all" are never legitimate global roles; SystemAdmin stays.
+// "system" is the in-process identity (system-identity-switch treats any user
+// carrying it as System) and must never end up in a session.
 const NON_MINTABLE_GLOBAL_ROLES = new Set([
     ...access.all,
     ...access.anonymous,
+    SYSTEM_ROLE,
 ]);
 function stripNonMintableGlobalRoles(roles) {
     return roles.filter((role) => !NON_MINTABLE_GLOBAL_ROLES.has(role));

package/dist/engine/pattern-library/mixed-schemas.js

@@ -78,6 +78,11 @@ export const writeHandlerSchema = {
             label: { en: "Rate limit", de: "Rate-Limit" },
             input: "json-readonly",
         },
+        {
+            path: "additionalRateLimits",
+            label: { en: "Per-payload rate limits", de: "Payload-Rate-Limits" },
+            input: "json-readonly",
+        },
         {
             path: "unsafeSkipTransitionGuard",
             label: { en: "Skip transition guard", de: "Übergangs-Guard überspringen" },

package/dist/engine/registry-state.js

@@ -43,7 +43,6 @@ export function buildImplicitProjection(featureName, entityName, entity, qualify
     // r.extendEntityProjection: merge extension applies into the rebuild
     // replay. Collisions with lifecycle applies (or another extension) are
     // authoring bugs — fail at boot, not by silently overwriting a handler.
-    const extraSources = [];
     for (const ext of extensions) {
         for (const [eventType, fn] of Object.entries(ext.apply)) {
             if (apply[eventType]) {
@@ -52,20 +51,54 @@ export function buildImplicitProjection(featureName, entityName, entity, qualify
             }
             apply[eventType] = fn;
         }
-        for (const s of ext.sources ?? []) {
-            if (s !== entityName && !extraSources.includes(s))
-                extraSources.push(s);
-        }
     }
+    const { extraSources, extraSourceRowIds } = collectExtensionSources(name, entityName, extensions);
     return {
         name,
         source: entityName,
         ...(extraSources.length > 0 && { extraSources }),
+        ...(Object.keys(extraSourceRowIds).length > 0 && { extraSourceRowIds }),
         table: drizzleTable,
         apply,
         isImplicit: true,
     };
 }
+function assertRowIdOfSources(projectionName, entityName, ext) {
+    // skip: extension maps no rowIdOf, nothing to validate
+    if (ext.rowIdOf === undefined)
+        return;
+    const sources = ext.sources ?? [];
+    if (sources.length === 0) {
+        throw new Error(`Implicit projection "${projectionName}": extendEntityProjection declares rowIdOf without ` +
+            `\`sources\` — rowIdOf maps events of the declared sources to row ids.`);
+    }
+    if (sources.includes(entityName)) {
+        throw new Error(`Implicit projection "${projectionName}": extendEntityProjection rowIdOf cannot apply to the ` +
+            `entity's own stream "${entityName}" — host-stream rows are keyed by the aggregate id.`);
+    }
+}
+function collectExtensionSources(projectionName, entityName, extensions) {
+    const extraSources = [];
+    const extraSourceRowIds = {};
+    const rowIdDeclaredBy = new Map();
+    for (const ext of extensions) {
+        for (const s of ext.sources ?? []) {
+            if (s !== entityName && !extraSources.includes(s))
+                extraSources.push(s);
+        }
+        assertRowIdOfSources(projectionName, entityName, ext);
+        for (const s of ext.sources ?? []) {
+            if (rowIdDeclaredBy.has(s) && rowIdDeclaredBy.get(s) !== ext.rowIdOf) {
+                throw new Error(`Implicit projection "${projectionName}": source "${s}" is declared by several extensions with ` +
+                    `different or missing rowIdOf — the row id for its events is ambiguous.`);
+            }
+            rowIdDeclaredBy.set(s, ext.rowIdOf);
+            if (ext.rowIdOf !== undefined)
+                extraSourceRowIds[s] = ext.rowIdOf;
+        }
+    }
+    return { extraSources, extraSourceRowIds };
+}
 // Validates a r.entity backing table is a superset of the entity's field-
 // derived columns, then hands it back as the projection table. The cast is a
 // system-boundary reconstitution: the table is stored as `unknown` on

package/dist/engine/registry-validate.js

@@ -655,6 +655,8 @@ export function computeHasRateLimitedHandler(state) {
         for (const h of state.writeHandlerMap.values()) {
             if (h.rateLimit !== undefined && !isRateLimitDisabled(h.rateLimit))
                 return true;
+            if (h.additionalRateLimits !== undefined)
+                return true;
         }
         for (const h of state.queryHandlerMap.values()) {
             if (h.rateLimit !== undefined && !isRateLimitDisabled(h.rateLimit))

package/dist/engine/tier-resolver-extension.d.ts

@@ -1,3 +1,4 @@
+import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
 import type { DbConnection } from "../db/connection.js";
 import type { RegistrarExtensionRegistration } from "./types/config.js";
 import type { FeatureDefinition, Registry } from "./types/feature.js";
@@ -44,6 +45,7 @@ export type TierResolverPlugin = {
     readonly build: (deps: {
         readonly db: DbConnection;
         readonly registry: Registry;
+        readonly cacheSync?: CacheSyncBus;
     }) => Promise<EffectiveFeaturesResolver>;
 };
 /**

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

@@ -7,7 +7,7 @@ export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsM
 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, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, 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 { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, 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 { 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";
@@ -15,7 +15,7 @@ export type { EntityId, TenantId } from "@cosmicdrift/kumiko-types/identifiers";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-types/identifiers";
 export type { ContentCollectionDefinition, NavDefinition, NavIconKey, } from "@cosmicdrift/kumiko-types/nav";
 export type { FromRule, FromRuleKind, OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule, SqlFragment, WhereRule, WhereRuleContext, } from "@cosmicdrift/kumiko-types/ownership";
-export type { EntityProjectionExtension, MspErrorMode, MspErrorPolicy, MultiStreamApplyFn, MultiStreamProjectionDefinition, ProjectionDefinition, ProjectionTable, SingleStreamApplyFn, } from "@cosmicdrift/kumiko-types/projection";
+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, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, 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 { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";

package/dist/entrypoint/index.js

@@ -45,6 +45,7 @@ import { createJobRunner } from "../jobs/job-runner.js";
 import { createLifecycle } from "../lifecycle/index.js";
 import { createNoopProvider } from "../observability/index.js";
 import { dispatcherToWriteRef } from "../pipeline/dispatcher.js";
+import { resolveCacheSyncBus } from "../redis/cache-sync-bus.js";
 // --- Shared builders ------------------------------------------------------
 //
 // Three factories, three near-identical buildServer() + createJobRunner()
@@ -71,6 +72,24 @@ function mergeDispatcherOptions(caller, jobRunner) {
 function resolveObservability(observability) {
     return observability ?? createNoopProvider();
 }
+// One bus per process, decided before the file-provider resolver is built so
+// the resolver subscribes to it; buildServer then receives it explicitly and
+// does not create a second one.
+function resolveEntrypointCacheSync(options, lifecycle) {
+    const { bus, owned } = resolveCacheSyncBus(options.dispatcherOptions?.cacheSync);
+    if (owned) {
+        lifecycle.registerShutdownHook("cacheSync", async () => {
+            await owned.close();
+        });
+    }
+    return {
+        options: {
+            ...options,
+            dispatcherOptions: { ...options.dispatcherOptions, cacheSync: bus ?? null },
+        },
+        context: withFileProviderResolver(options.registry, options.context, bus),
+    };
+}
 function contextWithObservability(context, observability, effectiveFeatures) {
     return {
         ...context,
@@ -177,7 +196,7 @@ function requireDispatcher(server, mode) {
 export function createApiEntrypoint(options) {
     const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
     const observability = resolveObservability(options.observability);
-    const context = withFileProviderResolver(options.registry, options.context);
+    const { options: busOptions, context } = resolveEntrypointCacheSync(options, lifecycle);
     // Boot-validation (Welle 2.6.c) — fail loud before traffic arrives:
     //   (a) Any jobs declared + no jobs-block → command-dispatcher would
     //       silently drop every event-triggered enqueue. Fix: add jobs:
@@ -211,7 +230,7 @@ export function createApiEntrypoint(options) {
     // processLane is "both": worker-lane MSPs must run here or they'd never
     // apply anywhere.
     const { runLocal: runLocalDispatcher, ...dispatcherTunables } = options.eventDispatcher ?? {};
-    const server = buildApiServer({ ...options, context }, lifecycle, runLocalDispatcher ? dispatcherTunables : { disabled: true }, apiJobRunner, runLocalDispatcher ? "both" : "api");
+    const server = buildApiServer({ ...busOptions, context }, lifecycle, runLocalDispatcher ? dispatcherTunables : { disabled: true }, apiJobRunner, runLocalDispatcher ? "both" : "api");
     apiJobRunner?.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
     return {
         app: server.app,
@@ -243,9 +262,9 @@ export function createApiEntrypoint(options) {
 export function createWorkerEntrypoint(options) {
     const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
     const observability = resolveObservability(options.observability);
-    const context = withFileProviderResolver(options.registry, options.context);
+    const { options: busOptions, context } = resolveEntrypointCacheSync(options, lifecycle);
     const jobRunner = buildJobRunnerWithHook(options.registry, contextWithObservability(context, observability, options.dispatcherOptions?.effectiveFeatures), options, "worker", lifecycle, "jobRunner");
-    const server = buildWorkerServer({ ...options, context }, lifecycle, jobRunner);
+    const server = buildWorkerServer({ ...busOptions, context }, lifecycle, jobRunner);
     jobRunner.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
     const eventDispatcher = requireDispatcher(server, "worker");
     return {
@@ -268,7 +287,7 @@ export function createWorkerEntrypoint(options) {
 export function createAllInOneEntrypoint(options) {
     const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
     const observability = resolveObservability(options.observability);
-    const context = withFileProviderResolver(options.registry, options.context);
+    const { options: busOptions, context } = resolveEntrypointCacheSync(options, lifecycle);
     const jobRunnerContext = contextWithObservability(context, observability, options.dispatcherOptions?.effectiveFeatures);
     // All-in-one consumes BOTH lanes: two runners, each with a BullMQ worker
     // for its own lane's queue. Both runners hold queue-clients for both
@@ -286,7 +305,7 @@ export function createAllInOneEntrypoint(options) {
     // every MSP (api-only, worker-only, both) must run here. `runLocal` is
     // the API-mode flag — all-in-one is always local, strip it.
     const { runLocal: _runLocal, ...allInOneDispatcherTunables } = options.eventDispatcher ?? {};
-    const server = buildApiServer({ ...options, context }, lifecycle, allInOneDispatcherTunables, workerJobRunner, "both");
+    const server = buildApiServer({ ...busOptions, context }, lifecycle, allInOneDispatcherTunables, workerJobRunner, "both");
     workerJobRunner.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
     apiJobRunner.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
     const eventDispatcher = requireDispatcher(server, "all-in-one");

package/dist/errors/classes.d.ts

@@ -112,3 +112,8 @@ export declare class RateLimitError extends KumikoError {
     readonly details: RateLimitDetails;
     constructor(details: RateLimitDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
 }
+export declare class RateLimitUnavailableError extends KumikoError {
+    readonly code = "rate_limit_unavailable";
+    readonly httpStatus = 503;
+    constructor(opts?: Pick<ErrorOpts, "cause">);
+}

package/dist/errors/classes.js

@@ -203,3 +203,16 @@ export class RateLimitError extends KumikoError {
         this.details = details;
     }
 }
+// The rate-limit backend (Redis) failed, so no decision could be made. The
+// request is refused (fail-closed) with 503 instead of leaking a generic 500.
+export class RateLimitUnavailableError extends KumikoError {
+    code = "rate_limit_unavailable";
+    httpStatus = 503;
+    constructor(opts) {
+        super({
+            message: "rate limiter unavailable",
+            i18nKey: "errors.rate_limit_unavailable",
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}

package/dist/errors/index.d.ts

@@ -1,5 +1,5 @@
 export type { FeatureDisabledDetails, FieldIssue, NotFoundDetails, PreconditionFailedDetails, RateLimitDetails, UnconfiguredDetails, UniqueViolationDetails, UnprocessableOpts, ValidationDetails, VersionConflictDetails, } from "./classes.js";
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";

package/dist/errors/index.js

@@ -1,4 +1,4 @@
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";

package/dist/files/file-routes.js

@@ -13,6 +13,7 @@ import { buildContentDispositionHeader } from "./content-disposition.js";
 import { createFileContext } from "./file-handle.js";
 import { fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
+import { resolveContentType } from "./resolve-content-type.js";
 import { buildStorageKey, parseMaxSize, resolveServedContentType, resolveUploadMimeType, validateFile, validateFileContent, } from "./types.js";
 const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"];
 // 15 minutes — long enough for a download to start, short enough that a
@@ -195,10 +196,14 @@ export function createFileRoutes(options) {
             if (mimeTypeResolution.kind === "rejected") {
                 return c.json({ error: mimeTypeResolution.error }, 400);
             }
-            mimeType = mimeTypeResolution.mimeType;
+            mimeType = resolveContentType({
+                declared: mimeTypeResolution.mimeType,
+                bytes: data,
+                filename: file.name,
+            });
         }
         const fileRefId = generateId();
-        const storageKey = buildStorageKey(user.tenantId, entityType ?? "unattached", entityId ?? "", fieldName ?? "file", file.name, generateId(), contentValidation.kind === "normalized" ? contentValidation.extension : undefined);
+        const storageKey = buildStorageKey(user.tenantId, entityType ?? "unattached", entityId, fieldName ?? "file", file.name, generateId(), contentValidation.kind === "normalized" ? contentValidation.extension : undefined);
         // Write binary FIRST (outside the tx — network/disk I/O doesn't belong
         // inside a PG connection's tx window). On DB-tx rollback below the bytes
         // are orphaned in the provider; cleanup-jobs sweep those later. Losing a

package/dist/files/index.d.ts

@@ -10,6 +10,7 @@ export { createInMemoryFileProvider } from "./in-memory-provider.js";
 export { createLocalProvider } from "./local-provider.js";
 export type { FileProviderContext, FileProviderPlugin, FileProviderResolver, FileProviderResolverDeps, } from "./provider-resolver.js";
 export { createFileProviderForTenant, isFileProviderPlugin, makeFileProviderResolver, } from "./provider-resolver.js";
+export { resolveContentType } from "./resolve-content-type.js";
 export { fileRefStorageDelta, filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.js";
 export type { FileContentValidationResult, FileMetadata, FileStorageProvider, FileValidationOptions, SignedUrlOptions, UploadMimeTypeResolution, WriteStreamOptions, } from "./types.js";
 export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, parseMaxSize, resolveUploadMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, validateFileContent, } from "./types.js";

package/dist/files/index.js

@@ -8,6 +8,7 @@ export { createFileRoutes, readFilesRouteOptions, resolveMaxUploadBodyBytes, } f
 export { createInMemoryFileProvider } from "./in-memory-provider.js";
 export { createLocalProvider } from "./local-provider.js";
 export { createFileProviderForTenant, isFileProviderPlugin, makeFileProviderResolver, } from "./provider-resolver.js";
+export { resolveContentType } from "./resolve-content-type.js";
 export { fileRefStorageDelta, filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.js";
 export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, parseMaxSize, resolveUploadMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, validateFileContent, } from "./types.js";
 export { createZipStream } from "./zip-stream.js";

package/dist/files/provider-resolver.d.ts

@@ -1,3 +1,4 @@
+import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { DbConnection } from "../db/connection.js";
 import type { TenantDb } from "../db/tenant-db.js";
@@ -54,5 +55,6 @@ export type FileProviderResolverDeps = {
     readonly _configAccessorFactory?: ConfigAccessorFactory;
     readonly secrets?: SecretsContext;
     readonly db?: DbConnection | TenantDb;
+    readonly cacheSync?: CacheSyncBus;
 };
 export declare function makeFileProviderResolver(deps: FileProviderResolverDeps): FileProviderResolver;

package/dist/files/provider-resolver.js

@@ -13,6 +13,8 @@
 // (moved here from there) so existing imports keep working.
 import { EXT_FILE_PROVIDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, } from "../engine/extension-names.js";
 import { SYSTEM_USER_ID } from "../engine/system-user.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
+import { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage } from "../redis/cache-sync-topics.js";
 const FEATURE_NAME = "file-foundation";
 // extension-usage `options` is engine-payload (unknown) — structurally validate
 // instead of casting blind.
@@ -83,6 +85,16 @@ export function makeFileProviderResolver(deps) {
     // promise is evicted so a transient failure (or a secret genuinely not
     // configured yet) doesn't permanently poison this tenant's entry.
     const cache = new Map();
+    deps.cacheSync?.subscribe(CACHE_SYNC_TOPICS.tenantConfig, (message) => {
+        // skip: malformed message from another process
+        if (!isTenantConfigSyncMessage(message))
+            return;
+        if ("scope" in message || message.tenantId === SYSTEM_TENANT_ID)
+            cache.clear();
+        else
+            cache.delete(message.tenantId);
+    });
+    deps.cacheSync?.onResync(() => cache.clear());
     return (tenantId) => {
         const cached = cache.get(tenantId);
         if (cached)
@@ -99,7 +111,10 @@ export function makeFileProviderResolver(deps) {
             });
             return createFileProviderForTenant({ config, registry: deps.registry, secrets: deps.secrets, _userId: SYSTEM_USER_ID }, tenantId);
         })();
-        built.catch(() => cache.delete(tenantId));
+        built.catch(() => {
+            if (cache.get(tenantId) === built)
+                cache.delete(tenantId);
+        });
         cache.set(tenantId, built);
         return built;
     };

package/dist/files/resolve-content-type.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Content type for a file whose sender may not have declared a useful one
+ * (mail attachments commonly arrive as application/octet-stream). A concrete
+ * declared type is returned untouched; a generic/missing one is resolved from
+ * the bytes first and the file extension only as fallback.
+ */
+export declare function resolveContentType(args: {
+    readonly declared: string | undefined;
+    readonly bytes: Uint8Array;
+    readonly filename: string | undefined;
+}): string;

package/dist/files/resolve-content-type.js

@@ -0,0 +1,71 @@
+import { normalizeMimeType, sniffMimeType } from "./types.js";
+const OCTET_STREAM = "application/octet-stream";
+const GENERIC_MIME_TYPES = new Set(["", OCTET_STREAM, "binary/octet-stream"]);
+// Signatures that identify exactly one type. sniffMimeType also matches OLE and
+// ZIP, which it maps to msword/docx — wrong for .xls/.xlsx/.zip, so they are
+// handled separately below.
+const UNAMBIGUOUS_SNIFFED_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "application/pdf",
+]);
+const ZIP_SIGNATURE = [0x50, 0x4b, 0x03, 0x04];
+const XML_PROBE_BYTES = 512;
+const EXTENSION_FALLBACK = {
+    xml: "application/xml",
+    pdf: "application/pdf",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    zip: "application/zip",
+    json: "application/json",
+    csv: "text/csv",
+    txt: "text/plain",
+};
+function hasPrefix(bytes, prefix) {
+    return prefix.every((byte, i) => bytes[i] === byte);
+}
+// Textual start only: a NUL in the probe means binary (or UTF-16, which is
+// deliberately not detected). HTML also starts with `<` and must not be
+// relabelled as XML.
+function looksLikeXml(bytes) {
+    const probe = bytes.subarray(0, XML_PROBE_BYTES);
+    if (probe.includes(0))
+        return false;
+    const text = new TextDecoder().decode(probe).replace(/^/, "").trimStart();
+    if (text.startsWith("<?xml"))
+        return true;
+    if (!/^<[A-Za-z_]/.test(text))
+        return false;
+    return !/^<(html|head|body|script)\b/i.test(text);
+}
+function extensionOf(filename) {
+    const dot = filename.lastIndexOf(".");
+    return dot === -1 ? "" : filename.slice(dot + 1).toLowerCase();
+}
+/**
+ * Content type for a file whose sender may not have declared a useful one
+ * (mail attachments commonly arrive as application/octet-stream). A concrete
+ * declared type is returned untouched; a generic/missing one is resolved from
+ * the bytes first and the file extension only as fallback.
+ */
+export function resolveContentType(args) {
+    const declared = args.declared ?? "";
+    if (!GENERIC_MIME_TYPES.has(normalizeMimeType(declared)))
+        return declared;
+    const sniffed = sniffMimeType(args.bytes);
+    if (sniffed !== null && UNAMBIGUOUS_SNIFFED_TYPES.has(sniffed))
+        return sniffed;
+    if (looksLikeXml(args.bytes))
+        return "application/xml";
+    const fromExtension = EXTENSION_FALLBACK[extensionOf(args.filename ?? "")];
+    if (fromExtension !== undefined)
+        return fromExtension;
+    if (hasPrefix(args.bytes, ZIP_SIGNATURE))
+        return "application/zip";
+    return OCTET_STREAM;
+}

package/dist/files/types.d.ts

@@ -47,7 +47,7 @@ export type UploadMimeTypeResolution = {
  */
 export declare function resolveUploadMimeType(fileName: string, declaredMimeType: string, content: Uint8Array): UploadMimeTypeResolution;
 export declare function assertSafeStorageKey(key: string): void;
-export declare function buildStorageKey(tenantId: TenantId, entityType: string, entityId: number | string, fieldName: string, fileName: string, uniqueId: string, extensionOverride?: string): string;
+export declare function buildStorageKey(tenantId: TenantId, entityType: string, entityId: number | string | undefined, fieldName: string, fileName: string, uniqueId: string, extensionOverride?: string): string;
 /** Fixed leading segment so one S3 lifecycle rule (Prefix: "exports/") can expire export bundles for every tenant without matching a buildStorageKey() upload. */
 export declare function tenantExportPrefix(tenantId: TenantId): string;
 /**

package/dist/files/types.js

@@ -261,6 +261,9 @@ export function assertSafeStorageKey(key) {
         throw new Error(`storage key contains a path-traversal segment: "${key}"`);
     }
 }
+// Object stores (S3/MinIO) reject keys with an empty path segment, so an
+// upload without an owning entity needs a placeholder id segment.
+const NO_ENTITY_ID_SEGMENT = "none";
 export function buildStorageKey(tenantId, entityType, entityId, fieldName, fileName, uniqueId, 
 // Set when validateFileContent normalized the upload to a different real
 // type — the storage key then reflects the sniffed type, not the user's
@@ -268,7 +271,8 @@ export function buildStorageKey(tenantId, entityType, entityId, fieldName, fileN
 extensionOverride) {
     const rawExt = extensionOverride ?? fileName.split(".").pop() ?? "";
     const ext = /^[A-Za-z0-9]+$/.test(rawExt) ? rawExt.toLowerCase() : "bin";
-    return `${tenantId}/${entityType}/${entityId}/${fieldName}/${uniqueId}.${ext}`;
+    const entitySegment = entityId === undefined || entityId === "" ? NO_ENTITY_ID_SEGMENT : entityId;
+    return `${tenantId}/${entityType}/${entitySegment}/${fieldName}/${uniqueId}.${ext}`;
 }
 const EXPORTS_PREFIX_SEGMENT = "exports";
 /** Fixed leading segment so one S3 lifecycle rule (Prefix: "exports/") can expire export bundles for every tenant without matching a buildStorageKey() upload. */

package/dist/jobs/job-runner.js

@@ -677,7 +677,7 @@ export function createJobRunner(options) {
         // must resolve for jobs the same way they do for write-handlers, or an
         // app-author job calling ctx.notify(...)/ctx.config(...) hits a TypeError
         // at runtime the write-handler path never would (framework#1532).
-        const notify = context._notifyFactory?.(jobSystemUser, tenantId);
+        const notify = context._notifyFactory?.(jobSystemUser, tenantId, selfRunner);
         const configDb = context.db; // @cast-boundary db-operator
         // Shared by the config accessor and ctx.derivatives below — both need the
         // same tenant-scoped db, and building it twice would let the two calls

package/dist/pipeline/dispatch-shared.d.ts

@@ -1,10 +1,11 @@
+import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
 import type { SseBroker } from "../api/sse-broker.js";
 import type { DbConnection, DbTx } from "../db/connection.js";
 import type { buildEntityTable } from "../db/table-builder.js";
 import type { defineTransitions } from "../engine/state-machine.js";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension.js";
 import type { TenantId } from "../engine/types/identifiers.js";
-import type { AppContext, HandlerContext, JobRunnerRef, RateLimitDeclaration, Registry, SessionUser, WriteResult } from "../engine/types/index.js";
+import type { AppContext, HandlerContext, JobRunnerRef, PayloadRateLimitOption, RateLimitDeclaration, Registry, SessionUser, WriteResult } from "../engine/types/index.js";
 import { type WriteErrorInfo } from "../errors/index.js";
 import { type EscapeHatchReportWindow, type getFallbackMeter, getFallbackTracer } from "../observability/index.js";
 import { type AfterCommitHook } from "./dispatcher-utils.js";
@@ -40,6 +41,7 @@ export type DispatchContext = {
     tableCache: Map<string, ReturnType<typeof buildEntityTable>>;
     transitionCache: Map<string, ReturnType<typeof defineTransitions>>;
     tenantTimezoneCache: TenantTimezoneCache;
+    cacheSync: CacheSyncBus | undefined;
     escapeHatchReportWindow: EscapeHatchReportWindow;
     tracer: ReturnType<typeof getFallbackTracer>;
     meter: ReturnType<typeof getFallbackMeter>;
@@ -54,4 +56,5 @@ export declare function runStreamInstrumented<T>(ctx: DispatchContext, type: str
 export declare function checkFeatureEnabled(ctx: DispatchContext, qualifiedHandler: string, tenantId: TenantId): Promise<import("../errors/index.js").FeatureDisabledError | undefined>;
 export declare function ensureFeatureEnabled(ctx: DispatchContext, qualifiedHandler: string, tenantId: TenantId): Promise<void>;
 export declare function enforceRateLimit(ctx: DispatchContext, rateLimit: RateLimitDeclaration | undefined, handlerName: string, user: SessionUser, isSystemScope: boolean): Promise<void>;
+export declare function enforcePayloadRateLimits(ctx: DispatchContext, limits: readonly PayloadRateLimitOption[] | undefined, handlerName: string, user: SessionUser, data: unknown): Promise<void>;
 export declare function resolveAuthClaimsFn(ctx: DispatchContext, user: SessionUser): Promise<Record<string, unknown>>;