@cosmicdrift/kumiko-framework 0.339.0 → 0.341.0

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

package/dist/pipeline/dispatch-shared.js

@@ -5,7 +5,7 @@ import { createTenantDb, createUncheckedSystemDb, hasTenantColumn, } from "../db
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
 import { createSystemUser } from "../engine/system-user.js";
 import { isRateLimitDisabled, resolveAgentExposure } from "../engine/types/index.js";
-import { AccessDeniedError, FeatureDisabledError, InternalError, memberResolutionReadOnlyDenied, VersionConflictError, } from "../errors/index.js";
+import { AccessDeniedError, FeatureDisabledError, InternalError, memberResolutionReadOnlyDenied, RateLimitError, RateLimitUnavailableError, VersionConflictError, } from "../errors/index.js";
 import { archiveStream as archiveStreamHelper, isStreamArchived, restoreStream as restoreStreamHelper, } from "../event-store/archive.js";
 import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError, } from "../event-store/errors.js";
 import { getStreamVersion, loadAggregate, loadAggregateAsOf, } from "../event-store/event-store.js";
@@ -14,8 +14,9 @@ import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.j
 import { createFileContext } from "../files/file-handle.js";
 import { DEFAULT_LOCALE, isValidLocaleTag } from "../i18n/request-locale.js";
 import { createEscapeHatchReporter, createMetricsHandle, createNoopMetricsHandle, createSafeMetricsHandle, emitDispatcherError, emitDispatcherHandler, getFallbackTracer, observabilityContext, } from "../observability/index.js";
-import { buildBucketKey } from "../rate-limit/index.js";
+import { buildBucketKey, buildPayloadBucketKey, normalizePayloadBucketValue, } from "../rate-limit/index.js";
 import { createTzContext, isValidIanaTimeZone } from "../time/index.js";
+import { isPlainObject } from "../utils/is-plain-object.js";
 import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership.js";
 import { appendDomainEventCore } from "./append-event-core.js";
 import { resolveAuthClaims as runAuthClaimsResolver } from "./auth-claims-resolver.js";
@@ -92,6 +93,14 @@ function createSystemScopedDbGuard(handlerType, fieldName, hint) {
 export function isMemberResolutionPrincipal(user) {
     return user.origin === "member-resolution";
 }
+// DispatchContext.jobRunner is typed as the handleEvent-only JobRunnerRef but
+// holds the concrete runner at boot; narrow instead of casting.
+function isNotifyJobDispatcher(runner) {
+    return (typeof runner === "object" &&
+        runner !== null &&
+        "dispatch" in runner &&
+        typeof runner.dispatch === "function");
+}
 async function denyMemberResolutionWrite() {
     throw memberResolutionReadOnlyDenied();
 }
@@ -206,7 +215,9 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         userId: user.id,
         ...(reqCtx && { requestId: reqCtx.requestId }),
     });
-    const notify = context._notifyFactory ? context._notifyFactory(user, user.tenantId) : undefined;
+    const notify = context._notifyFactory
+        ? context._notifyFactory(user, user.tenantId, isNotifyJobDispatcher(jobRunner) ? jobRunner : undefined)
+        : undefined;
     // Mirror notify: only built when the config feature wired its factory.
     const config = context._configAccessorFactory && db
         ? context._configAccessorFactory({
@@ -604,8 +615,11 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     // Request → Session → Boot-Default chain above.
     const safeUserLocale = user.locale !== undefined && isValidLocaleTag(user.locale) ? user.locale : undefined;
     const locale = reqCtx?.locale ?? safeUserLocale ?? context.defaultLocale ?? DEFAULT_LOCALE;
+    // The payload-bucket digest is dispatcher-internal; handlers must not be
+    // able to compute bucket keys.
+    const { _rateLimitPayloadDigest: _omitPayloadDigest, ...contextForHandler } = context;
     const handlerContext = {
-        ...context,
+        ...contextForHandler,
         registry,
         db: exposedDb,
         dbOutsideTransaction,
@@ -636,6 +650,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         // Propagate the feature-toggle resolver so the lifecycle pipeline,
         // MSP runner, and ctx.hasFeature all pull from the same source.
         ...(effectiveFeatures && { effectiveFeatures }),
+        ...(ctx.cacheSync && { cacheSync: ctx.cacheSync }),
         // Lets write handlers call ctx.jobRunner.dispatch(...) directly, same
         // as a follow-up job would (test-stack.ts wires the matching runner).
         ...(jobRunner && { jobRunner }),
@@ -894,11 +909,57 @@ export async function enforceRateLimit(ctx, rateLimit, handlerName, user, isSyst
             message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
         });
     }
-    await context.rateLimit.enforce(bucket.key, {
-        limit: effective.limit,
-        windowSeconds: effective.windowSeconds,
-        cost: effective.cost,
-    });
+    try {
+        await context.rateLimit.enforce(bucket.key, {
+            limit: effective.limit,
+            windowSeconds: effective.windowSeconds,
+            cost: effective.cost,
+        });
+    }
+    catch (error) {
+        // Backend failure (Redis down): fail closed as 503, same as L1/L2.
+        if (error instanceof RateLimitError)
+            throw error;
+        throw new RateLimitUnavailableError({
+            cause: error instanceof Error ? error : new Error(String(error)),
+        });
+    }
+}
+// Payload-field rate limits (additionalRateLimits). Runs after schema
+// validation so the field is typed, regardless of what the handler later
+// returns — hit and non-hit callers see the same limit behavior. SYSTEM
+// identities (jobs, internal dispatches) are not the anonymous traffic this
+// protects against.
+export async function enforcePayloadRateLimits(ctx, limits, handlerName, user, data) {
+    // skip: no payload buckets declared, or a SYSTEM caller
+    if (!limits || isSystemIdentity(user))
+        return;
+    const { appContext: context } = ctx;
+    const digest = context._rateLimitPayloadDigest;
+    if (!context.rateLimit || !digest) {
+        throw new InternalError({
+            message: `Handler "${handlerName}" declares additionalRateLimits but no RateLimitResolver/payload digest is configured.`,
+        });
+    }
+    // Boot validation guarantees an object schema; anything else must not pass unlimited.
+    if (!isPlainObject(data)) {
+        throw new InternalError({
+            message: `Handler "${handlerName}" declares additionalRateLimits but its payload is not an object.`,
+        });
+    }
+    for (const { per, limit, windowSeconds, cost } of limits) {
+        const value = data[per.payloadField];
+        // skip: optional field not sent — nothing to bucket on
+        if (value === undefined)
+            continue;
+        if (typeof value !== "string") {
+            throw new InternalError({
+                message: `Handler "${handlerName}" additionalRateLimits payloadField "${per.payloadField}" is not a string.`,
+            });
+        }
+        const key = buildPayloadBucketKey(handlerName, per.payloadField, digest(normalizePayloadBucketValue(value)));
+        await context.rateLimit.enforce(key, { limit, windowSeconds, cost });
+    }
 }
 // Build the per-hook context every auth-claims invocation gets. Claims
 // hooks run OUTSIDE any request transaction (login is itself the root

package/dist/pipeline/dispatch-write.js

@@ -10,8 +10,9 @@ import { defineTransitions, guardTransition } from "../engine/state-machine.js";
 import { HookPhases } from "../engine/types/index.js";
 import { runValidation } from "../engine/validation.js";
 import { AccessDeniedError, FrameworkReasons, InternalError, isKumikoError, memberResolutionReadOnlyDenied, NotFoundError, ValidationError, validationErrorFromZod, writeFailure, } from "../errors/index.js";
+import { CACHE_SYNC_TOPICS } from "../redis/cache-sync-topics.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
-import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, checkFeatureEnabled, enforceRateLimit, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
+import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, checkFeatureEnabled, enforcePayloadRateLimits, enforceRateLimit, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
 import { describeShape, extractNestedSpecs, isLifecycleResult, isWriteResultShape, prefixValidationPath, wrapToKumiko, } from "./dispatcher-utils.js";
 import { handlerAccessError } from "./handler-access-error.js";
 import { runProjections } from "./projections-runner.js";
@@ -44,12 +45,11 @@ function getTransitions(ctx, args) {
 }
 // A successful config:write:set/reset returns { key, scope, ... } — see
 // bundled-features/src/config/handlers/{set,reset}.write.ts. Narrows the
-// otherwise-`unknown` WriteResult.data so invalidateTenantTimezoneCache
-// below can check `key` without an unchecked cast.
-function isConfigWriteResultForKey(data, key) {
+// otherwise-`unknown` WriteResult.data without an unchecked cast.
+function isConfigWriteResult(data) {
     if (typeof data !== "object" || data === null || !("key" in data))
         return false;
-    return data.key === key; // @cast-boundary engine-payload
+    return typeof data.key === "string";
 }
 // fw#2462: dispatch-shared.ts caches the resolved tenant:config:timezone
 // value per tenant. A successful write to that key must drop the stale
@@ -64,14 +64,30 @@ function invalidateTenantTimezoneCache(ctx, type, user, result) {
     if (type !== CONFIG_WRITE_SET_TYPE && type !== CONFIG_WRITE_RESET_TYPE)
         return;
     // skip: write was for a different config key
-    if (!isConfigWriteResultForKey(result.data, TENANT_TIMEZONE_CONFIG_KEY))
+    if (!isConfigWriteResult(result.data) || result.data.key !== TENANT_TIMEZONE_CONFIG_KEY)
         return;
-    if (result.data.scope === ConfigScopes.system) {
+    if (result.data.scope === ConfigScopes.system)
         ctx.tenantTimezoneCache.clear();
-    }
-    else {
+    else
         ctx.tenantTimezoneCache.invalidate(user.tenantId);
-    }
+}
+// Every committed config write tells the other processes (config-derived
+// caches such as the tenant timezone and the file provider live per process).
+// Only after commit: a pod receiving this earlier would re-read the pre-write
+// row and cache the stale value again.
+function publishConfigWrite(ctx, type, user, result) {
+    // skip: failed write, nothing changed
+    if (!result.isSuccess)
+        return;
+    // skip: not a config:write:set/reset dispatch
+    if (type !== CONFIG_WRITE_SET_TYPE && type !== CONFIG_WRITE_RESET_TYPE)
+        return;
+    // skip: result carries no config key to announce
+    if (!isConfigWriteResult(result.data))
+        return;
+    const { key, scope } = result.data;
+    const message = scope === ConfigScopes.system ? { scope: "all", key } : { tenantId: user.tenantId, key };
+    ctx.cacheSync?.publish(CACHE_SYNC_TOPICS.tenantConfig, message);
 }
 // Runs lifecycle hooks for a handler result. inTransaction hooks fire NOW
 // (they see the tx via ctx.db when batch/write opens a transaction).
@@ -329,6 +345,14 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
     if (!parsed.success) {
         return writeFailure(validationErrorFromZod(parsed.error));
     }
+    try {
+        await enforcePayloadRateLimits(ctx, handler.additionalRateLimits, type, user, parsed.data);
+    }
+    catch (e) {
+        if (isKumikoError(e))
+            return writeFailure(e);
+        throw e;
+    }
     const hookErrors = runValidation(registry, type, parsed.data); // @cast-boundary engine-payload
     if (hookErrors) {
         return writeFailure(new ValidationError({
@@ -459,6 +483,7 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
         // repopulate the cache with the stale value for a full TTL.
         afterCommitHooks.push(async () => {
             invalidateTenantTimezoneCache(ctx, type, user, result);
+            publishConfigWrite(ctx, type, user, result);
         });
     }
     // Response-guard: block Secret<> leaks in write responses (SaveContext

package/dist/pipeline/dispatcher.d.ts

@@ -1,3 +1,4 @@
+import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
 import type { SseBroker } from "../api/sse-broker.js";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension.js";
 import type { TenantId } from "../engine/types/identifiers.js";
@@ -15,6 +16,7 @@ export type DispatcherOptions = {
     membershipQuery?: string;
     effectiveFeatures?: EffectiveFeaturesResolver;
     sseBroker?: SseBroker;
+    cacheSync?: CacheSyncBus | null;
 };
 export type Dispatcher = {
     write(type: HandlerType, payload: unknown, user: SessionUser, requestId?: string): Promise<WriteResult>;