@cosmicdrift/kumiko-framework 0.340.0 → 0.342.0

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

@@ -11,7 +11,7 @@ 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 { createEscapeHatchReporter, emitJobLastSuccess, emitJobQueueDepth, getFallbackTracer, registerStandardMetrics, } from "../observability/index.js";
+import { createEscapeHatchProcessDedup, createEscapeHatchReporter, emitJobLastSuccess, emitJobQueueDepth, getFallbackTracer, registerStandardMetrics, } from "../observability/index.js";
 import { createDistributedLock } from "../pipeline/distributed-lock.js";
 import { RedisKeys } from "../pipeline/redis-keys.js";
 import { buildPersonalDataGate, isPersonalDataGated, parseWriteOrigin, } from "../pipeline/write-origin.js";
@@ -316,6 +316,8 @@ export function createJobRunner(options) {
     // must not depend on buildServer having done it first. Idempotent.
     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 systemCronEscapeHatchDedup = createEscapeHatchProcessDedup(["unsafe-raw", "global-write"]);
     // Set at the top of stop() — a graceful shutdown closes the redis/BullMQ
     // clients itself, which fires the exact same 'error' listeners below with
     // an expected "Connection is closed." Downgrading to debug once stopping
@@ -677,7 +679,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
@@ -692,12 +694,15 @@ export function createJobRunner(options) {
             : undefined;
         const isSystemJob = registry.isJobSystemScoped(jobName);
         // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
+        const isSystemCronRun = triggeredById === null && jobDef.escapeHatch !== undefined && "cron" in jobDef.trigger;
         const reportEscapeHatch = createEscapeHatchReporter({
             handler: jobName,
             tenantId,
             actor: jobSystemUser.id,
             sink: context._escapeHatchAuditSink,
             log: context.log,
+            ...(isSystemCronRun && { processDedup: systemCronEscapeHatchDedup }),
+            ...(context.meter && { meter: context.meter }),
         });
         const systemDb = isSystemJob && tenantScopedDb
             ? createUncheckedSystemDb(tenantScopedDb, undefined, reportEscapeHatch)
@@ -705,6 +710,7 @@ export function createJobRunner(options) {
         const jobDb = configDb
             ? createTenantDb(configDb, tenantId, "tenant", context.tracer, context.meter, undefined, {
                 unsafeRaw: escapeHatchFor(jobDef.escapeHatch, "unsafeRaw"),
+                globalWrites: escapeHatchFor(jobDef.escapeHatch, "globalWrites"),
                 report: reportEscapeHatch,
                 ...(jobPersonalDataGate && { personalDataGate: jobPersonalDataGate }),
             })

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

@@ -1,5 +1,6 @@
-import type { EscapeHatchAuditSink, EscapeHatchReporter, EscapeHatchUseEvent, TenantId } from "../engine/types/index.js";
+import type { EscapeHatchAuditSink, EscapeHatchKind, EscapeHatchReporter, EscapeHatchUseEvent, TenantId } from "../engine/types/index.js";
 import type { Logger } from "../logging/types.js";
+import type { Meter } from "./types/index.js";
 export declare const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
 export type EscapeHatchReportWindow = {
     shouldReport(key: string, nowMs: number): boolean;
@@ -8,6 +9,11 @@ export declare function createEscapeHatchReportWindow(opts?: {
     readonly windowMs?: number;
     readonly maxEntries?: number;
 }): EscapeHatchReportWindow;
+export type EscapeHatchProcessDedup = {
+    readonly kinds: ReadonlySet<EscapeHatchKind>;
+    readonly seen: Set<string>;
+};
+export declare function createEscapeHatchProcessDedup(kinds: readonly EscapeHatchKind[]): EscapeHatchProcessDedup;
 export declare function reportEscapeHatchUse(event: EscapeHatchUseEvent, deps: {
     readonly sink?: EscapeHatchAuditSink;
     readonly log?: Logger;
@@ -19,6 +25,9 @@ export declare function createEscapeHatchReporter(opts: {
     readonly sink?: EscapeHatchAuditSink;
     readonly log?: Logger;
     readonly window?: EscapeHatchReportWindow;
+    readonly processDedup?: EscapeHatchProcessDedup;
+    readonly meter?: Meter;
+    readonly now?: () => number;
 }): EscapeHatchReporter;
 export declare const UNATTRIBUTED_ACTOR = "system";
 export declare function fallbackEscapeHatchReporter(tenantId: TenantId): EscapeHatchReporter;

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

@@ -1,3 +1,4 @@
+import { emitEscapeHatchUse } from "./standard-metrics.js";
 export const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
 const DEFAULT_WINDOW_MS = 60_000;
 const DEFAULT_MAX_ENTRIES = 1_000;
@@ -24,6 +25,9 @@ export function createEscapeHatchReportWindow(opts) {
         },
     };
 }
+export function createEscapeHatchProcessDedup(kinds) {
+    return { kinds: new Set(kinds), seen: new Set() };
+}
 // Default window for createEscapeHatchReporter callers that don't pass their own.
 const fallbackReportWindow = createEscapeHatchReportWindow();
 const consoleLogger = {
@@ -67,7 +71,21 @@ export function reportEscapeHatchUse(event, deps) {
 }
 export function createEscapeHatchReporter(opts) {
     const window = opts.window ?? fallbackReportWindow;
+    const now = opts.now ?? Date.now;
     return (kind, reason, target) => {
+        if (opts.meter)
+            emitEscapeHatchUse(opts.meter, opts.handler, kind);
+        const { processDedup } = opts;
+        if (processDedup?.kinds.has(kind)) {
+            const processKey = JSON.stringify([opts.handler, kind, opts.tenantId]);
+            // skip: this (handler, kind, tenant) was already audited by this process
+            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 });
+            // skip: audited above, the window dedup below only serves the other kinds
+            return;
+        }
         const key = JSON.stringify([
             opts.handler,
             kind,
@@ -78,7 +96,7 @@ export function createEscapeHatchReporter(opts) {
             target?.tenantId ?? null,
         ]);
         // skip: same (handler, kind, reason, target) already reported within the window — dedup
-        if (!window.shouldReport(key, Date.now()))
+        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 });
     };

package/dist/observability/index.d.ts

@@ -1,6 +1,6 @@
 export { type ConsoleProviderOptions, createConsoleProvider } from "./console-provider.js";
 export { observabilityContext } from "./context.js";
-export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, type EscapeHatchReportWindow, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
+export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, type EscapeHatchProcessDedup, type EscapeHatchReportWindow, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } 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";
@@ -12,5 +12,5 @@ export { type MetricEvent, type MetricEventHandler, RecordingMeter, } from "./re
 export { type RecordedSpan, RecordingTracer, type RecordingTracerOptions, serializeSpanContext, } from "./recording-tracer.js";
 export { wrapRedisClient } from "./redis-wrapper.js";
 export { DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig, REDACTED, redactAttributes, redactHeaders, redactQueryString, redactValue, shouldRedactAttribute, } from "./sensitive-filter.js";
-export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
+export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEscapeHatchUse, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
 export type { Counter, Gauge, Histogram, Meter, MetricDefinition, MetricLabels, MetricsHandle, MetricType, ObservabilityOptions, ObservabilityProvider, SamplingConfig, SensitiveFilterConfig, SerializedTraceContext, Span, SpanAttributes, SpanAttributeValue, SpanKind, SpanStatus, StartSpanOptions, Tracer, } from "./types/index.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 { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
+export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } 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";
@@ -13,4 +13,4 @@ export { RecordingMeter, } from "./recording-meter.js";
 export { RecordingTracer, serializeSpanContext, } from "./recording-tracer.js";
 export { wrapRedisClient } from "./redis-wrapper.js";
 export { DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig, REDACTED, redactAttributes, redactHeaders, redactQueryString, redactValue, shouldRedactAttribute, } from "./sensitive-filter.js";
-export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
+export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEscapeHatchUse, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";

package/dist/observability/standard-metrics.d.ts

@@ -43,3 +43,4 @@ export declare function emitEventConsumerPassOutcome(meter: Meter, labels: {
 }, processed: number, failed: number): void;
 export declare function emitJobQueueDepth(meter: Meter, lane: string, counts: Readonly<Record<string, number>>): void;
 export declare function emitJobLastSuccess(meter: Meter, job: string): void;
+export declare function emitEscapeHatchUse(meter: Meter, handler: string, kind: string): void;

package/dist/observability/standard-metrics.js

@@ -140,6 +140,15 @@ export const STANDARD_METRIC_DEFS = [
         description: "Unix timestamp of the last successful run, per registered job.",
         labels: ["job"],
     },
+    // Every escape-hatch use counts here, including the ones the audit sink
+    // dedups away: a system cron firing every minute writes one audit event per
+    // process, so this counter is the only record of how often it ran.
+    {
+        name: "kumiko_escape_hatch_uses_total",
+        type: "counter",
+        description: "Escape-hatch uses by handler and kind, whether or not an audit event was written.",
+        labels: ["handler", "kind"],
+    },
 ];
 export function registerStandardMetrics(meter) {
     for (const def of STANDARD_METRIC_DEFS) {
@@ -251,3 +260,8 @@ export function emitJobQueueDepth(meter, lane, counts) {
 export function emitJobLastSuccess(meter, job) {
     meter.gauge("kumiko_job_last_success_timestamp_seconds").set(Date.now() / 1000, { job });
 }
+// `handler` is a registry-declared handler/job name, `kind` a closed union —
+// no tenant or user input reaches the label set.
+export function emitEscapeHatchUse(meter, handler, kind) {
+    meter.counter("kumiko_escape_hatch_uses_total").inc(1, { handler, kind });
+}

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