@cosmicdrift/kumiko-framework 0.340.0 → 0.341.0

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

package/dist/pipeline/dispatcher.js

@@ -3,10 +3,11 @@ import { DEPRECATED_CROSS_TENANT_SIGNAL, isDeprecatedCrossTenantHandler, } from
 import { TENANT_MEMBERSHIPS_QUERY } from "../engine/extension-names.js";
 import { InternalError, reraiseAsKumikoError } from "../errors/index.js";
 import { createEscapeHatchReportWindow, getFallbackMeter, getFallbackTracer, registerStandardMetrics, } from "../observability/index.js";
+import { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage } from "../redis/cache-sync-topics.js";
 import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership.js";
 import { runBatch, unwrapSingle } from "./dispatch-batch.js";
 import { executeQuery } from "./dispatch-query.js";
-import { resolveAuthClaimsFn } from "./dispatch-shared.js";
+import { resolveAuthClaimsFn, TENANT_TIMEZONE_CONFIG_KEY } from "./dispatch-shared.js";
 import { executeStream } from "./dispatch-stream.js";
 import { resolveType } from "./dispatcher-utils.js";
 import { createMemberReaderFn } from "./member-reader.js";
@@ -54,6 +55,20 @@ export function createDispatcher(registry, context, options = {}) {
     // One per dispatcher instance (not a module-level singleton) so caches
     // never leak across separately-booted apps or test stacks.
     const tenantTimezoneCache = createTenantTimezoneCache();
+    const cacheSync = options.cacheSync ?? undefined;
+    cacheSync?.subscribe(CACHE_SYNC_TOPICS.tenantConfig, (message) => {
+        // skip: malformed message from another process
+        if (!isTenantConfigSyncMessage(message))
+            return;
+        // skip: a different config key, the timezone cache is unaffected
+        if (message.key !== undefined && message.key !== TENANT_TIMEZONE_CONFIG_KEY)
+            return;
+        if ("scope" in message)
+            tenantTimezoneCache.clear();
+        else
+            tenantTimezoneCache.invalidate(message.tenantId);
+    });
+    cacheSync?.onResync(() => tenantTimezoneCache.clear());
     const escapeHatchReportWindow = createEscapeHatchReportWindow();
     const dispatcherTracer = context.tracer ?? getFallbackTracer();
     const dispatcherMeter = context.meter ?? getFallbackMeter();
@@ -82,6 +97,7 @@ export function createDispatcher(registry, context, options = {}) {
         tableCache,
         transitionCache,
         tenantTimezoneCache,
+        cacheSync,
         escapeHatchReportWindow,
         tracer: dispatcherTracer,
         meter: dispatcherMeter,

package/dist/pipeline/projection-rebuild.js

@@ -186,7 +186,7 @@ export async function rebuildProjection(projectionName, deps) {
             // reconstruct (#498 ghost — direct-inserted without a .created event),
             // which the swap would silently drop. Implicit projections only.
             if (projection.isImplicit === true) {
-                await assertNoUnreachableLiveRows(tx, projectionName, meta.tableName, sourcesList);
+                await assertNoUnreachableLiveRows(tx, projectionName, meta.tableName, sourcesList, projection.extraSourceRowIds);
                 // Non-blocking counterpart: reports column-level drift (bidx excluded)
                 // without aborting — see countColumnDrift for why this isn't fail-hard.
                 const drift = await countColumnDrift(tx, meta.tableName, meta);

package/dist/rate-limit/bucket.d.ts

@@ -12,3 +12,7 @@ export type BucketResult = {
     readonly reason: string;
 };
 export declare function buildBucketKey(option: RateLimitOption, ctx: BucketContext): BucketResult;
+export declare function normalizePayloadBucketValue(value: string): string;
+export declare function buildPayloadBucketKey(handlerName: string, field: string, digest: string): string;
+export declare function toPublicBucketName(bucket: string): string;
+export declare function createPayloadDigest(masterSecret: string): (value: string) => string;

package/dist/rate-limit/bucket.js

@@ -1,3 +1,5 @@
+import { createHmac } from "node:crypto";
+import { derivePurposeSecret } from "../secrets/derive-purpose-secret.js";
 export function buildBucketKey(option, ctx) {
     switch (option.per) {
         case "user":
@@ -18,3 +20,26 @@ export function buildBucketKey(option, ctx) {
             return { kind: "key", key: `ip+handler:${ctx.ip}:${ctx.handlerName}` };
     }
 }
+// Payload-field buckets: the value (e.g. a recipient address) is normalized
+// and HMAC-hashed so Redis never holds it in plaintext.
+const PAYLOAD_BUCKET_PURPOSE = "kumiko:rate-limit:payload-bucket";
+export function normalizePayloadBucketValue(value) {
+    return value.trim().toLowerCase();
+}
+export function buildPayloadBucketKey(handlerName, field, digest) {
+    return `payload+handler:${handlerName}:${field}:${digest}`;
+}
+// Everything after the scope tag identifies the caller (IP, user/tenant id,
+// auth target, payload digest). IPv6 addresses and handler names contain ":",
+// so no later segment can be kept safely by parsing; the client already knows
+// which handler/route it called.
+export function toPublicBucketName(bucket) {
+    const separator = bucket.indexOf(":");
+    return separator === -1 ? bucket : bucket.slice(0, separator);
+}
+// Rotating the JWT secret only resets these buckets (new digests); they are
+// ephemeral (TTL 2x window), so no migration is needed.
+export function createPayloadDigest(masterSecret) {
+    const key = derivePurposeSecret(masterSecret, PAYLOAD_BUCKET_PURPOSE);
+    return (value) => createHmac("sha256", key).update(value).digest("hex");
+}

package/dist/rate-limit/index.d.ts

@@ -1,3 +1,3 @@
-export { type BucketContext, type BucketResult, buildBucketKey } from "./bucket.js";
-export { type AuthEndpointRateLimitOptions, authEndpointRateLimit, type GlobalIpRateLimitOptions, globalIpRateLimit, } from "./middleware.js";
+export { type BucketContext, type BucketResult, buildBucketKey, buildPayloadBucketKey, createPayloadDigest, normalizePayloadBucketValue, } from "./bucket.js";
+export { type AuthEndpointRateLimitOptions, authEndpointRateLimit, type GlobalIpRateLimitOptions, globalIpRateLimit, type HttpRouteRateLimitOptions, httpRouteRateLimit, } from "./middleware.js";
 export { createRateLimitResolver, type RateLimitConfig, type RateLimitDecision, type RateLimitResolver, type RateLimitResolverOptions, } from "./resolver.js";

package/dist/rate-limit/index.js

@@ -1,3 +1,3 @@
-export { buildBucketKey } from "./bucket.js";
-export { authEndpointRateLimit, globalIpRateLimit, } from "./middleware.js";
+export { buildBucketKey, buildPayloadBucketKey, createPayloadDigest, normalizePayloadBucketValue, } from "./bucket.js";
+export { authEndpointRateLimit, globalIpRateLimit, httpRouteRateLimit, } from "./middleware.js";
 export { createRateLimitResolver, } from "./resolver.js";

package/dist/rate-limit/middleware.d.ts

@@ -1,5 +1,6 @@
 import type { Context, MiddlewareHandler } from "hono";
 import { type ClientIpResolver } from "../api/client-ip.js";
+import type { HttpRouteRateLimit } from "../engine/types/http-route.js";
 import type { RateLimitResolver } from "./resolver.js";
 export type GlobalIpRateLimitOptions = {
     readonly resolver: RateLimitResolver;
@@ -11,6 +12,14 @@ export type GlobalIpRateLimitOptions = {
     readonly onFailClosed?: (err: unknown) => void;
 };
 export declare function globalIpRateLimit(opts: GlobalIpRateLimitOptions): MiddlewareHandler;
+export type HttpRouteRateLimitOptions = {
+    readonly resolver: RateLimitResolver;
+    readonly rateLimit: HttpRouteRateLimit;
+    readonly routeKey: string;
+    readonly clientIpResolver: ClientIpResolver;
+    readonly onFailClosed?: (err: unknown) => void;
+};
+export declare function httpRouteRateLimit(opts: HttpRouteRateLimitOptions): MiddlewareHandler;
 export type AuthEndpointRateLimitOptions = {
     readonly resolver: RateLimitResolver;
     readonly limit?: number;

package/dist/rate-limit/middleware.js

@@ -2,6 +2,7 @@ import { isAuthRateLimitExempt } from "../api/api-constants.js";
 import { clientIpSourceFromHonoContext, createClientIpResolver, } from "../api/client-ip.js";
 import { requestContext } from "../api/request-context.js";
 import { RateLimitError, serializeError } from "../errors/index.js";
+import { toPublicBucketName } from "./bucket.js";
 export function globalIpRateLimit(opts) {
     const limit = opts.limit ?? 1000;
     const windowSeconds = opts.windowSeconds ?? 60;
@@ -33,6 +34,34 @@ export function globalIpRateLimit(opts) {
         await next();
     };
 }
+// Per-route limit for r.httpRoute({ rateLimit }). Fail-closed like L1: these
+// routes are anonymous, so an outage must not turn into an unbounded flood.
+export function httpRouteRateLimit(opts) {
+    const { rateLimit, routeKey } = opts;
+    const onFailClosed = opts.onFailClosed ?? defaultOnFailClosed("http-route");
+    const config = {
+        limit: rateLimit.limit,
+        windowSeconds: rateLimit.windowSeconds,
+        ...(rateLimit.cost !== undefined && { cost: rateLimit.cost }),
+    };
+    return async (c, next) => {
+        const ip = opts.clientIpResolver.resolve(clientIpSourceFromHonoContext(c));
+        if (!ip)
+            return next();
+        const bucket = rateLimit.per === "ip" ? `http:${ip}` : `http:${ip}:${routeKey}`;
+        try {
+            const decision = await opts.resolver.check(bucket, config);
+            if (!decision.allowed)
+                return respondRateLimited(c, decision, bucket);
+            setRateLimitHeaders(c, decision);
+        }
+        catch (e) {
+            onFailClosed(e);
+            return c.json({ error: { code: "rate_limit_unavailable", message: "Rate limiter unavailable" } }, 503);
+        }
+        await next();
+    };
+}
 export function authEndpointRateLimit(opts) {
     const limit = opts.limit ?? 5;
     const windowSeconds = opts.windowSeconds ?? 60;
@@ -70,7 +99,9 @@ function defaultOnFailClosed(label) {
         // override this with a structured logger; the default keeps the
         // noise visible if no logger is wired.
         // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-        console.error(`[rate-limit ${label}] fail-closed (refusing request):`, err);
+        console.error(`[rate-limit ${label}] fail-closed (refusing request):`, 
+        // ioredis errors can carry the command args, i.e. the bucket key with IP/target.
+        err instanceof Error ? err.message : String(err));
     };
 }
 function setRateLimitHeaders(c, decision) {
@@ -87,7 +118,7 @@ function respondRateLimited(c, decision, bucket) {
     // dispatcher path. serializeError adds i18nKey, requestId, timestamp —
     // fields a hand-rolled body would silently miss.
     const err = new RateLimitError({
-        bucket,
+        bucket: toPublicBucketName(bucket),
         limit: decision.limit,
         windowSeconds: decision.windowSeconds,
         remaining: decision.remaining,

package/dist/rate-limit/resolver.js

@@ -4,6 +4,7 @@
 import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 import { RateLimitError } from "../errors/index.js";
 import { RedisKeys } from "../pipeline/redis-keys.js";
+import { toPublicBucketName } from "./bucket.js";
 // Token-Bucket rate limiter, atomic via Redis Lua. One round-trip per
 // check — the script computes the bucket state inline and either deducts
 // or rejects.
@@ -148,7 +149,7 @@ export function createRateLimitResolver(opts) {
         if (decision.allowed)
             return decision;
         throw new RateLimitError({
-            bucket,
+            bucket: toPublicBucketName(bucket),
             limit: decision.limit,
             windowSeconds: decision.windowSeconds,
             remaining: decision.remaining,

package/dist/redis/cache-sync-bus.d.ts

@@ -0,0 +1,24 @@
+import type { CacheSyncBus, ClosableCacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
+import { type RedisClientOptions } from "./client.js";
+import { type PubSubSignal } from "./pubsub-signal.js";
+export type { CacheSyncBus, ClosableCacheSyncBus };
+export declare function createLocalCacheSyncBus(): ClosableCacheSyncBus;
+export type CacheSyncBusOverSignalOptions = {
+    readonly channel: string;
+    readonly originId?: string;
+    readonly resyncMinIntervalMs?: number;
+    readonly now?: () => number;
+};
+export declare function createCacheSyncBusOverSignal(signal: PubSubSignal, opts: CacheSyncBusOverSignalOptions): ClosableCacheSyncBus;
+export type RedisCacheSyncBusOptions = {
+    readonly redisUrl: string;
+    readonly clientOptions?: RedisClientOptions;
+    readonly channelPrefix?: string;
+};
+export declare function createRedisCacheSyncBus(opts: RedisCacheSyncBusOptions): ClosableCacheSyncBus;
+export declare function createDefaultCacheSyncBus(envVars?: Record<string, string | undefined>): ClosableCacheSyncBus;
+export type ResolvedCacheSyncBus = {
+    readonly bus: CacheSyncBus | undefined;
+    readonly owned: ClosableCacheSyncBus | undefined;
+};
+export declare function resolveCacheSyncBus(explicit: CacheSyncBus | null | undefined): ResolvedCacheSyncBus;

package/dist/redis/cache-sync-bus.js

@@ -0,0 +1,152 @@
+import { createFallbackLogger } from "../logging/utils.js";
+import { redisClientOptionsFromEnv } from "./client.js";
+import { createRedisPubSubSignal } from "./pubsub-signal.js";
+const log = createFallbackLogger("kumiko:cache-sync");
+const CACHE_SYNC_CHANNEL = "kumiko:cache-sync";
+const RESYNC_MIN_INTERVAL_MS = 5_000;
+function isCacheSyncEnvelope(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "origin" in value &&
+        typeof value.origin === "string" &&
+        "topic" in value &&
+        typeof value.topic === "string" &&
+        "message" in value);
+}
+function createLocalFanout() {
+    const subscribers = new Map();
+    const resyncListeners = new Set();
+    return {
+        deliver(topic, message) {
+            const listeners = subscribers.get(topic);
+            // skip: nobody in this process listens on the topic
+            if (!listeners)
+                return;
+            for (const listener of [...listeners]) {
+                // A failing listener must not starve the others nor the publishing write or the redis event loop.
+                try {
+                    listener(message);
+                }
+                catch (err) {
+                    log.error("subscriber threw", { topic, err });
+                }
+            }
+        },
+        subscribe(topic, listener) {
+            let listeners = subscribers.get(topic);
+            if (!listeners) {
+                listeners = new Set();
+                subscribers.set(topic, listeners);
+            }
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        onResync(listener) {
+            resyncListeners.add(listener);
+            return () => {
+                resyncListeners.delete(listener);
+            };
+        },
+        fireResync() {
+            for (const listener of [...resyncListeners]) {
+                try {
+                    listener();
+                }
+                catch (err) {
+                    log.error("resync listener threw", { err });
+                }
+            }
+        },
+    };
+}
+export function createLocalCacheSyncBus() {
+    const fanout = createLocalFanout();
+    return {
+        publish: fanout.deliver,
+        subscribe: fanout.subscribe,
+        onResync: fanout.onResync,
+        async close() { },
+    };
+}
+export function createCacheSyncBusOverSignal(signal, opts) {
+    const origin = opts.originId ?? crypto.randomUUID();
+    const resyncMinIntervalMs = opts.resyncMinIntervalMs ?? RESYNC_MIN_INTERVAL_MS;
+    const now = opts.now ?? Date.now;
+    const fanout = createLocalFanout();
+    signal.onMessage((_channel, payload) => {
+        // skip: foreign or malformed payload on the channel
+        if (!isCacheSyncEnvelope(payload))
+            return;
+        // skip: own echo, already delivered locally by publish()
+        if (payload.origin === origin)
+            return;
+        fanout.deliver(payload.topic, payload.message);
+    });
+    // Reconnect bursts collapse into one reload per interval; the trailing timer
+    // keeps a reconnect inside the window from being dropped.
+    let lastResyncAt = Number.NEGATIVE_INFINITY;
+    let pendingResync;
+    let closed = false;
+    const runResync = () => {
+        pendingResync = undefined;
+        lastResyncAt = now();
+        fanout.fireResync();
+    };
+    signal.onReconnect(() => {
+        // skip: bus closed, or a resync is already scheduled
+        if (closed || pendingResync !== undefined)
+            return;
+        const wait = lastResyncAt + resyncMinIntervalMs - now();
+        if (wait <= 0) {
+            runResync();
+        }
+        else {
+            pendingResync = setTimeout(runResync, wait);
+            pendingResync.unref();
+        }
+    });
+    return {
+        publish(topic, message) {
+            fanout.deliver(topic, message);
+            const envelope = { origin, topic, message };
+            signal.publish(opts.channel, envelope);
+        },
+        subscribe: fanout.subscribe,
+        onResync: fanout.onResync,
+        async close() {
+            closed = true;
+            if (pendingResync !== undefined)
+                clearTimeout(pendingResync);
+            await signal.close();
+        },
+    };
+}
+export function createRedisCacheSyncBus(opts) {
+    const channel = `${opts.channelPrefix ?? ""}${CACHE_SYNC_CHANNEL}`;
+    const signal = createRedisPubSubSignal({
+        redisUrl: opts.redisUrl,
+        channelPattern: channel,
+        label: "cache-sync",
+        ...(opts.clientOptions ? { clientOptions: opts.clientOptions } : {}),
+    });
+    return createCacheSyncBusOverSignal(signal, { channel });
+}
+// Same REDIS_URL gate as createDefaultSseBroker: replicas > 1 are expected to
+// set it. Without it invalidation stays inside this process.
+export function createDefaultCacheSyncBus(envVars = process.env) {
+    const redisUrl = envVars["REDIS_URL"];
+    return redisUrl
+        ? createRedisCacheSyncBus({ redisUrl, clientOptions: redisClientOptionsFromEnv(envVars) })
+        : createLocalCacheSyncBus();
+}
+// An explicit bus wins (caller owns it), null opts out, undefined builds the default.
+export function resolveCacheSyncBus(explicit) {
+    if (explicit)
+        return { bus: explicit, owned: undefined };
+    if (explicit === null)
+        return { bus: undefined, owned: undefined };
+    const owned = createDefaultCacheSyncBus();
+    return { bus: owned, owned };
+}

package/dist/redis/cache-sync-topics.d.ts

@@ -0,0 +1,17 @@
+import type { TenantId } from "../engine/types/identifiers.js";
+export declare const CACHE_SYNC_TOPICS: {
+    readonly tenantConfig: "tenant-config";
+    readonly tierAssignment: "tier-assignment";
+};
+export type TenantConfigSyncMessage = {
+    readonly tenantId: TenantId;
+    readonly key?: string;
+} | {
+    readonly scope: "all";
+    readonly key?: string;
+};
+export type TierAssignmentSyncMessage = {
+    readonly tenantId: TenantId;
+};
+export declare function isTenantConfigSyncMessage(value: unknown): value is TenantConfigSyncMessage;
+export declare function isTierAssignmentSyncMessage(value: unknown): value is TierAssignmentSyncMessage;

package/dist/redis/cache-sync-topics.js

@@ -0,0 +1,22 @@
+export const CACHE_SYNC_TOPICS = {
+    tenantConfig: "tenant-config",
+    tierAssignment: "tier-assignment",
+};
+function hasOptionalStringKey(value) {
+    return !("key" in value) || value.key === undefined || typeof value.key === "string";
+}
+export function isTenantConfigSyncMessage(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (!hasOptionalStringKey(value))
+        return false;
+    if ("scope" in value)
+        return value.scope === "all";
+    return "tenantId" in value && typeof value.tenantId === "string";
+}
+export function isTierAssignmentSyncMessage(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "tenantId" in value &&
+        typeof value.tenantId === "string");
+}