@cosmicdrift/kumiko-framework 0.339.0 → 0.341.0

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");
+}

package/dist/redis/index.d.ts

@@ -1,3 +1,7 @@
+export type { CacheSyncBus, CacheSyncBusOverSignalOptions, ClosableCacheSyncBus, RedisCacheSyncBusOptions, ResolvedCacheSyncBus, } from "./cache-sync-bus.js";
+export { createCacheSyncBusOverSignal, createDefaultCacheSyncBus, createLocalCacheSyncBus, createRedisCacheSyncBus, resolveCacheSyncBus, } from "./cache-sync-bus.js";
+export type { TenantConfigSyncMessage, TierAssignmentSyncMessage } from "./cache-sync-topics.js";
+export { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage, isTierAssignmentSyncMessage, } from "./cache-sync-topics.js";
 export type { RedisClientOptions } from "./client.js";
 export { createRedisClient, redisClientOptionsFromEnv } from "./client.js";
 export type { PubSubSignal, PubSubSignalOptions } from "./pubsub-signal.js";

package/dist/redis/index.js

@@ -1,2 +1,4 @@
+export { createCacheSyncBusOverSignal, createDefaultCacheSyncBus, createLocalCacheSyncBus, createRedisCacheSyncBus, resolveCacheSyncBus, } from "./cache-sync-bus.js";
+export { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage, isTierAssignmentSyncMessage, } from "./cache-sync-topics.js";
 export { createRedisClient, redisClientOptionsFromEnv } from "./client.js";
 export { createRedisPubSubSignal } from "./pubsub-signal.js";

package/dist/redis/pubsub-signal.d.ts

@@ -2,6 +2,7 @@ import { type RedisClientOptions } from "./client.js";
 export type PubSubSignal = {
     publish(channel: string, payload: unknown): void;
     onMessage(listener: (channel: string, payload: unknown) => void): void;
+    onReconnect(listener: () => void): void;
     close(): Promise<void>;
 };
 export type PubSubSignalOptions = {

package/dist/redis/pubsub-signal.js

@@ -14,6 +14,7 @@ export function createRedisPubSubSignal(opts) {
     publisher.on("error", logConnectionError(opts.label, "publisher"));
     subscriber.on("error", logConnectionError(opts.label, "subscriber"));
     const listeners = new Set();
+    const reconnectListeners = new Set();
     // Sole purpose: stop close() from racing the initial psubscribe (see
     // below) and silence its logging once a shutdown is already underway —
     // not a defense against ioredis auto-reconnecting later (quit() below
@@ -56,6 +57,30 @@ export function createRedisPubSubSignal(opts) {
         // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
         console.error(`[kumiko:${opts.label}] psubscribe failed:`, err);
     });
+    // ioredis re-sends the psubscribe itself (autoResubscribe) but emits no ack
+    // event; repeating it here queues behind that one on the same connection,
+    // so its reply means the subscription is live again.
+    let hasBeenReady = false;
+    subscriber.on("ready", () => {
+        if (!hasBeenReady) {
+            hasBeenReady = true;
+            // skip: the first ready is the initial connect, not a reconnect
+            return;
+        }
+        subscriber.psubscribe(opts.channelPattern).then(() => {
+            // skip: close() ran while the resubscribe was in flight
+            if (closed)
+                return;
+            for (const listener of reconnectListeners)
+                listener();
+        }, (err) => {
+            // skip: a close() already underway intentionally quit the connection
+            if (closed)
+                return;
+            // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
+            console.error(`[kumiko:${opts.label}] resubscribe failed:`, err);
+        });
+    });
     return {
         publish(channel, payload) {
             publisher.publish(channel, JSON.stringify(payload)).catch((err) => {
@@ -70,6 +95,9 @@ export function createRedisPubSubSignal(opts) {
         onMessage(listener) {
             listeners.add(listener);
         },
+        onReconnect(listener) {
+            reconnectListeners.add(listener);
+        },
         async close() {
             closed = true;
             await initialSubscribe;

package/dist/stack/redis.d.ts

@@ -9,4 +9,9 @@ export type TestRedis = {
     cleanup: () => Promise<void>;
 };
 export declare function queueNamePrefixForTestRedis(keyPrefix: string): string;
-export declare function createTestRedis(): Promise<TestRedis>;
+export type CreateTestRedisOptions = {
+    /** Reuse another stack's keyPrefix on a fresh connection. cleanup() then only
+     *  disconnects — the owning stack flushes the namespace and its queues. */
+    readonly borrowKeyPrefix?: string;
+};
+export declare function createTestRedis(opts?: CreateTestRedisOptions): Promise<TestRedis>;

package/dist/stack/redis.js

@@ -6,13 +6,13 @@ import { requireEnv } from "./db.js";
 export function queueNamePrefixForTestRedis(keyPrefix) {
     return keyPrefix.split(":").filter(Boolean).join("-");
 }
-export async function createTestRedis() {
+export async function createTestRedis(opts = {}) {
     const Redis = (await import("ioredis")).Redis;
     const redisUrl = requireEnv("REDIS_URL");
     // Every test gets a per-file key prefix on a shared DB (no DB-pool-of-15
     // round-robin). Collisions at birthday-paradox rates are gone — the
     // prefix space is unbounded. See Track B.3 in docs/plans/tests-refactor.
-    const prefix = `kt:${generateId().slice(-8)}:`;
+    const prefix = opts.borrowKeyPrefix ?? `kt:${generateId().slice(-8)}:`;
     const redis = new Redis(redisUrl, { keyPrefix: prefix });
     async function deleteKeysMatching(pattern) {
         // Open a prefix-less client for the scan — ioredis' keyPrefix is applied
@@ -38,6 +38,11 @@ export async function createTestRedis() {
         keyPrefix: prefix,
         flushNamespace,
         cleanup: async () => {
+            if (opts.borrowKeyPrefix !== undefined) {
+                redis.disconnect();
+                // skip: the owning stack flushes the shared namespace and its queues
+                return;
+            }
             await flushNamespace();
             // The derived per-stack JobRunner queues sit outside the keyPrefix.
             await deleteKeysMatching(`bull:${queueNamePrefixForTestRedis(prefix)}-*`);

package/dist/stack/test-stack.d.ts

@@ -7,6 +7,7 @@ import { type JobRunner, type JobRunnerOptions } from "../jobs/index.js";
 import type { Lifecycle } from "../lifecycle/index.js";
 import { type ObservabilityProvider } from "../observability/index.js";
 import type { Dispatcher, EventDispatcher } from "../pipeline/index.js";
+import { type ClosableCacheSyncBus } from "../redis/cache-sync-bus.js";
 import type { SearchAdapter } from "../search/types.js";
 import { type EventCollector } from "./event-collector.js";
 import { type TestRedis } from "./redis.js";
@@ -17,6 +18,7 @@ export type TestStack = {
     registry: Registry;
     db: import("../db/index.js").DbConnection;
     redis: TestRedis;
+    cacheSync: ClosableCacheSyncBus;
     search: SearchAdapter;
     events: EventCollector;
     http: RequestHelper;
@@ -157,5 +159,18 @@ export type TestStackOptions = {
     /** Forwarded to buildServer's top-level `ServerOptions.trustedProxyHops`
      *  — see there. Default 0. */
     trustedProxyHops?: number;
+    /** Second stack on the Redis namespace of `owner`: own connection, same
+     *  keyPrefix, so rate-limit buckets, locks, idempotency keys and the
+     *  cache-sync channel are shared across both. The derived
+     *  queueNamePrefix is identical too, so both stacks share BullMQ queues.
+     *  Cleanup only disconnects; the owner flushes the namespace and queues, so
+     *  clean up the borrowing stack first. The DB is NOT shared — pass the same
+     *  `dbName` + `persistentDb` for that. */
+    sharedRedisWith?: TestStack;
+    /** Publish/receive cache invalidations (tenant timezone, file providers,
+     *  tier sets) over Redis Pub/Sub, namespaced by this stack's keyPrefix.
+     *  Implied by `sharedRedisWith`; set it on the owner stack too, or its writes
+     *  never reach the borrower. Without it the stack uses a process-local bus. */
+    cacheSync?: boolean;
 };
 export declare function setupTestStack(options: TestStackOptions): Promise<TestStack>;

package/dist/stack/test-stack.js

@@ -7,6 +7,7 @@ import { createJobRunner } from "../jobs/index.js";
 import { createNoopProvider } from "../observability/index.js";
 import { createEntityCache, createEventDedup, createIdempotencyGuard, dispatcherToWriteRef, } from "../pipeline/index.js";
 import { createRateLimitResolver } from "../rate-limit/index.js";
+import { createLocalCacheSyncBus, createRedisCacheSyncBus, } from "../redis/cache-sync-bus.js";
 import { createInMemorySearchAdapter } from "../search/index.js";
 import { createTestDb } from "./db.js";
 import { createJobFailureTracker, drainJobs } from "./drain-jobs.js";
@@ -39,7 +40,7 @@ export async function setupTestStack(options) {
             ...(options.dbName !== undefined && { dbName: options.dbName }),
             ...(options.persistentDb !== undefined && { persistent: options.persistentDb }),
         }),
-        createTestRedis(),
+        createTestRedis(options.sharedRedisWith && { borrowKeyPrefix: options.sharedRedisWith.redis.keyPrefix }),
     ]);
     // Any throw in this DDL region must still drop the just-created ephemeral
     // DB/Redis — the caller never gets the stack object back to call
@@ -103,6 +104,16 @@ export async function setupTestStack(options) {
         }
         throw error;
     }
+    // Redis only where two stacks can actually disagree (avoids two extra
+    // Pub/Sub connections); otherwise a local bus so invalidation still works
+    // inside this stack. Passing it explicitly keeps buildServer from using its
+    // REDIS_URL default (an unnamespaced channel).
+    const cacheSync = options.cacheSync || options.sharedRedisWith
+        ? createRedisCacheSyncBus({
+            redisUrl: testRedis.redisUrl,
+            channelPrefix: testRedis.keyPrefix,
+        })
+        : createLocalCacheSyncBus();
     const searchAdapter = createInMemorySearchAdapter();
     const events = createEventCollector();
     const registry = createRegistry([...options.features]);
@@ -262,6 +273,7 @@ export async function setupTestStack(options) {
             ...(options.observability ? { observability: options.observability } : {}),
             dispatcherOptions: {
                 idempotency,
+                cacheSync,
                 ...(options.effectiveFeatures && { effectiveFeatures: options.effectiveFeatures }),
                 ...(jobRunner && { jobRunner }),
             },
@@ -338,6 +350,7 @@ export async function setupTestStack(options) {
             registry,
             db: testDb.db,
             redis: testRedis,
+            cacheSync,
             search: searchAdapter,
             events,
             http,
@@ -355,6 +368,7 @@ export async function setupTestStack(options) {
                 if (eventDispatcher)
                     await eventDispatcher.stop();
                 await server.observability.shutdown();
+                await cacheSync.close();
                 await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
             },
         };
@@ -375,6 +389,12 @@ export async function setupTestStack(options) {
                 // ignore — `error` is the one that matters
             }
         }
+        try {
+            await cacheSync.close();
+        }
+        catch {
+            // ignore — `error` is the one that matters
+        }
         try {
             await testDb.cleanup();
         }