@cosmicdrift/kumiko-framework 0.403.0 → 0.404.0

package/agents/api/framework-engine.md

@@ -971,6 +971,9 @@ type JobTrigger =
     cron: string;
     tz?: string;
   }
+  | {
+    maintenance: true;
+  }
   | {
     manual: true;
   }

package/agents/api/renderer-web.md

@@ -338,6 +338,7 @@ type CreateEventSourceLiveEventsOptions = {
   url?: string; // URL of the SSE endpoint.
   onSessionEnded?: () => void; // Fires once per connection when the session ended: the server refused the SSE handshake, or opened the stream with a `session-ended` frame (stale auth cookie downgraded to anonymous).
   timers?: LiveEventTimers; // Reconnect-timer seam; defaults to the global setTimeout/clearTimeout.
+  stallTimers?: LiveEventTimers; // Stall-watchdog timer seam; defaults to the global setTimeout/clearTimeout.
   random?: () => number; // Jitter source in [0, 1); defaults to Math.random.
   now?: () => number; // Clock for synthetic resync events; defaults to Date.now.
 };

package/agents/api/types.md

@@ -1247,6 +1247,7 @@ type JobQueuedMeta = {
 type JobRunner = {
   start(): Promise<void>;
   stop(): Promise<void>;
+  stopConsuming?(): Promise<void>;
   dispatch(jobName: string, payload?: Record<string, unknown>, meta?: JobMeta): Promise<string>;
   handleEvent(eventName: string, payload: Record<string, unknown>, user?: SessionUser, triggerEvent?: JobTriggerEvent): Promise<void>;
   handleCatchUpEvent(jobName: string, eventName: string, payload: Record<string, unknown>, user: SessionUser, triggerEvent: JobTriggerEvent): Promise<void>;
@@ -1259,6 +1260,8 @@ type JobRunnerOptions = {
   redisUrl: string;
   consumerLane?: JobRunIn | undefined;
   queueNamePrefix?: string | undefined;
+  redisNamespace?: Pick<RedisNamespace, "keyPrefix" | "bullmqPrefix"> | undefined;
+  maintenanceWindow?: MaintenanceWindow | undefined;
   bootRedisTimeoutMs?: number | undefined;
   schedulerSeenRefreshMs?: number | undefined;
   jobRetention?: { completedAgeSec?: number | undefined; failedAgeSec?: number | undefined; } | undefined;
@@ -1272,6 +1275,15 @@ type JobRunnerOptions = {
 };
 ```
 
+## packages/framework/src/jobs/maintenance-window.ts
+
+```ts
+type MaintenanceWindow = {
+  hour: number;
+  minute: number;
+};
+```
+
 ## packages/framework/src/lifecycle/lifecycle.ts
 
 ```ts
@@ -1436,6 +1448,17 @@ type SystemHooks = {
 };
 ```
 
+## packages/framework/src/redis/client.ts
+
+```ts
+type RedisNamespace = {
+  keyPrefix: string; // ioredis keyPrefix for every non-BullMQ key; "" when unnamespaced.
+  bullmqPrefix: string; // BullMQ `prefix` option ("bull" is BullMQ's own default).
+  channelPrefix: string; // Prepended to every Pub/Sub channel (ioredis keyPrefix does not apply to Pub/Sub).
+  channelSubscribePattern: string | undefined; // Set only with KUMIKO_REDIS_PREFIX.
+};
+```
+
 ## packages/framework/src/secrets/dek-cache.ts
 
 ```ts

package/agents/examples/lane-routing.md

@@ -13,6 +13,7 @@ Pin jobs to deploy lanes (`api` | `worker`) with event-triggered fan-out.
 ## What it shows
 
 - `r.job({ runIn: "worker" })` after an HTTP write
+- `trigger: { maintenance: true }` for a daily housekeeping job in the app's maintenance window (`KUMIKO_MAINTENANCE_WINDOW`)
 - End-to-end verification via `createAllInOneEntrypoint`
 
 ## Source
@@ -65,7 +66,12 @@ import {
   type TestDb,
   type TestRedis,
 } from "@cosmicdrift/kumiko-testing/stack";
-import { createLaneRoutingFeature, renderedReceipts, sentConfirmations } from "../feature";
+import {
+  createLaneRoutingFeature,
+  pruneRuns,
+  renderedReceipts,
+  sentConfirmations,
+} from "../feature";
 
 const JWT = "lane-routing-sample-secret-minimum-32-chars!";
 const adminUser = TestUsers.admin;
@@ -87,6 +93,7 @@ afterAll(async () => {
 afterEach(() => {
   renderedReceipts.length = 0;
   sentConfirmations.length = 0;
+  pruneRuns.length = 0;
 });
 
 describe("lane-routing sample", () => {
@@ -132,6 +139,30 @@ describe("lane-routing sample", () => {
       await entry.stop();
     }
   });
+
+  test("a maintenance job is registered for the daily window and runs on the worker lane", async () => {
+    const registry = createRegistry([createLaneRoutingFeature()]);
+    expect(registry.getJob("orders:job:prune-old-receipts")?.trigger).toEqual({
+      maintenance: true,
+    });
+    const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+    const entry = createAllInOneEntrypoint({
+      rowLevelSecurity: "off",
+      registry,
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl,
+      queueNamePrefix: `lane-routing-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      maintenanceWindow: { hour: 5, minute: 30 },
+    });
+    await entry.start();
+    try {
+      await entry.jobRunner.dispatch("orders:job:prune-old-receipts", {});
+      await waitFor(() => expect(pruneRuns).toHaveLength(1));
+    } finally {
+      await entry.stop();
+    }
+  });
 });
 ```
 
@@ -163,6 +194,7 @@ import { z } from "zod";
 // opaque to the framework.
 export const renderedReceipts: Array<{ customerName: string; amount: number }> = [];
 export const sentConfirmations: Array<{ customerName: string; amount: number }> = [];
+export const pruneRuns: number[] = [];
 
 // The entity declaration secures the qualified-name prefix "orders:write:order:create"
 // for the write handler below and thereby the job trigger on this event.
@@ -240,6 +272,13 @@ export function createLaneRoutingFeature(): FeatureDefinition {
         });
       },
     );
+
+    // Housekeeping: `maintenance` runs once a day in the app's maintenance window
+    // (KUMIKO_MAINTENANCE_WINDOW, UTC, default 03:00) instead of a cron time of its own, so a
+    // sleeping app wakes once a day for all its cleanup jobs.
+    r.job("prune-old-receipts", { trigger: { maintenance: true }, runIn: "worker" }, async () => {
+      pruneRuns.push(Date.now());
+    });
   });
 }
 ```

package/dist/api/redis-sse-broker.d.ts

@@ -4,6 +4,7 @@ export type RedisSseBrokerOptions = {
     readonly redisUrl: string;
     readonly clientOptions?: RedisClientOptions;
     readonly channelPrefix?: string;
+    readonly channelSubscribePattern?: string;
 };
 export type RedisSseBroker = SseBroker & {
     readonly kind: "redis";

package/dist/api/redis-sse-broker.js

@@ -1,6 +1,6 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { createFallbackLogger } from "../logging/utils.js";
-import { redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "../redis/client.js";
+import { redisClientOptionsFromEnv, redisNamespaceFromEnv, } from "../redis/client.js";
 import { createRedisPubSubSignal } from "../redis/pubsub-signal.js";
 import { createSseBroker, readNonEmptyStringArray, } from "./sse-broker.js";
 const log = createFallbackLogger("kumiko:sse-broker");
@@ -28,11 +28,13 @@ export function isRedisSseBroker(broker) {
 // REDIS_URL-based default never ran.
 export function createDefaultSseBroker(env = process.env) {
     const redisUrl = env["REDIS_URL"];
+    const { channelPrefix, channelSubscribePattern } = redisNamespaceFromEnv(env);
     const ownedRedisSseBroker = redisUrl
         ? createRedisSseBroker({
             redisUrl,
             clientOptions: redisClientOptionsFromEnv(env),
-            channelPrefix: redisChannelPrefixFromEnv(env),
+            channelPrefix,
+            ...(channelSubscribePattern !== undefined && { channelSubscribePattern }),
         })
         : undefined;
     return { sseBroker: ownedRedisSseBroker ?? createSseBroker(), ownedRedisSseBroker };
@@ -104,7 +106,7 @@ export function createRedisSseBroker(opts) {
     const invalidationPrefix = `${opts.channelPrefix ?? ""}${INVALIDATION_PREFIX}`;
     const signal = createRedisPubSubSignal({
         redisUrl: opts.redisUrl,
-        channelPattern: `${opts.channelPrefix ?? ""}${PSUBSCRIBE_SUFFIX}`,
+        channelPattern: opts.channelSubscribePattern ?? `${opts.channelPrefix ?? ""}${PSUBSCRIBE_SUFFIX}`,
         label: "sse-broker",
         ...(opts.clientOptions ? { clientOptions: opts.clientOptions } : {}),
     });

package/dist/engine/feature-config-events-jobs.js

@@ -6,6 +6,16 @@ import { createEventDef } from "./event-def.js";
 import { resolveName } from "./handler-helpers.js";
 import { requireArgument, splitNamedDefinition, unwrapArrayForm } from "./object-form.js";
 import { QnTypes, qn, toKebab } from "./qualified-name.js";
+function assertScheduleTrigger(featureName, jobName, trigger) {
+    if ("maintenance" in trigger && trigger.maintenance !== true) {
+        throw new Error(`[Feature ${featureName}] r.job("${jobName}") declares trigger { maintenance: ${JSON.stringify(trigger.maintenance)} } — ` +
+            "the only valid value is true; the run time comes from KUMIKO_MAINTENANCE_WINDOW.");
+    }
+    if ("cron" in trigger && trigger.tz !== undefined && !isValidIanaTimeZone(trigger.tz)) {
+        throw new Error(`[Feature ${featureName}] r.job("${jobName}") declares trigger { cron, tz: ${JSON.stringify(trigger.tz)} } — ` +
+            'tz must be an IANA time zone name such as "Europe/Berlin".');
+    }
+}
 // Builds config/secrets/claims/events/jobs/notifications registrar methods.
 export function buildConfigEventsJobsMethods(state, name) {
     function config(arg1, arg2) {
@@ -90,13 +100,7 @@ export function buildConfigEventsJobsMethods(state, name) {
             if (jobGrantsProblem) {
                 throw new Error(`[Feature ${name}] r.job("${jobName}") declares an invalid escapeHatch — ${jobGrantsProblem}`);
             }
-            if ("cron" in jobOptions.trigger && jobOptions.trigger.tz !== undefined) {
-                const tz = jobOptions.trigger.tz;
-                if (!isValidIanaTimeZone(tz)) {
-                    throw new Error(`[Feature ${name}] r.job("${jobName}") declares trigger { cron, tz: ${JSON.stringify(tz)} } — ` +
-                        'tz must be an IANA time zone name such as "Europe/Berlin".');
-                }
-            }
+            assertScheduleTrigger(name, jobName, jobOptions.trigger);
             // Resolve NameOrRef(s) in trigger.on. For the multi-trigger form, arrays
             // become arrays of resolved strings while a single value remains a string;
             // the job runner distinguishes them with Array.isArray.

package/dist/engine/soft-delete-cleanup.js

@@ -161,7 +161,7 @@ export function buildSoftDeleteCleanupJob() {
     return {
         name: SOFT_DELETE_CLEANUP_JOB,
         handler: softDeleteCleanupJob,
-        trigger: { cron: "0 3 * * *" },
+        trigger: { maintenance: true },
         perTenant: true,
         concurrency: "skip",
         runIn: "worker",
@@ -171,7 +171,7 @@ export function buildSoftDeleteCleanupSystemJob() {
     return {
         name: SOFT_DELETE_CLEANUP_SYSTEM_JOB,
         handler: softDeleteCleanupSystemJob,
-        trigger: { cron: "15 3 * * *" },
+        trigger: { maintenance: true },
         concurrency: "skip",
         runIn: "worker",
         escapeHatch: {

package/dist/entrypoint/index.d.ts

@@ -11,6 +11,9 @@ import type { Dispatcher } from "../pipeline/dispatcher.ts";
 import type { EventDispatcher } from "../pipeline/index.ts";
 import type { LifecycleHooks } from "../pipeline/lifecycle-pipeline.ts";
 import type { AllInOneEntrypointOptions, BaseEntrypointOptions, JobsBlock, WorkerEntrypointOptions } from "./internals.ts";
+export type EntrypointStopOptions = {
+    readonly drainTimeoutMs?: number;
+};
 export type ApiEntrypointOptions = BaseEntrypointOptions & {
     readonly auth?: AuthRoutesConfig;
     readonly anonymousAccess?: ServerOptions["anonymousAccess"];
@@ -41,7 +44,7 @@ export type ApiEntrypoint = {
     readonly eventDispatcher?: EventDispatcher;
     readonly mode: "api";
     start(): Promise<void>;
-    stop(): Promise<void>;
+    stop(options?: EntrypointStopOptions): Promise<void>;
 };
 export type WorkerEntrypoint = {
     readonly lifecycle: Lifecycle;
@@ -52,7 +55,7 @@ export type WorkerEntrypoint = {
     readonly dispatcher: Dispatcher;
     readonly mode: "worker";
     start(): Promise<void>;
-    stop(): Promise<void>;
+    stop(options?: EntrypointStopOptions): Promise<void>;
 };
 export type AllInOneEntrypoint = Omit<ApiEntrypoint, "mode"> & Omit<WorkerEntrypoint, "mode"> & {
     readonly mode: "all-in-one";

package/dist/entrypoint/index.js

@@ -176,6 +176,8 @@ function buildJobRunnerWithHook(registry, context, jobs, consumerLane, lifecycle
         redisUrl: jobs.redisUrl,
         consumerLane,
         queueNamePrefix: jobs.queueNamePrefix,
+        redisNamespace: jobs.redisNamespace,
+        maintenanceWindow: jobs.maintenanceWindow,
         getActiveTenantIds: jobs.getActiveTenantIds,
         onJobStart: jobs.onJobStart,
         onJobComplete: jobs.onJobComplete,
@@ -189,6 +191,13 @@ function buildJobRunnerWithHook(registry, context, jobs, consumerLane, lifecycle
     });
     return jobRunner;
 }
+// Before the lifecycle drain, not as a hook: runner hooks drain one after another, and every other
+// hook (cache sync, brokers) would otherwise run first, leaving a window in which a lane still
+// fetches new jobs after SIGTERM.
+async function drainEntrypoint(lifecycle, runners, stopOptions) {
+    await Promise.all(runners.map((runner) => runner.stopConsuming?.()));
+    await lifecycle.drain(stopOptions?.drainTimeoutMs !== undefined ? { timeoutMs: stopOptions.drainTimeoutMs } : {});
+}
 // A worker-shaped process with no consumers (no SSE, no search adapter,
 // no MSPs) has nothing to drain — that's a caller-config bug, not a
 // usable process shape. Fail loud so ops sees it before prod takes
@@ -263,8 +272,8 @@ export function createApiEntrypoint(options) {
             if (server.eventDispatcher)
                 await server.eventDispatcher.start();
         },
-        async stop() {
-            await lifecycle.drain();
+        async stop(stopOptions) {
+            await drainEntrypoint(lifecycle, apiJobRunner ? [apiJobRunner] : [], stopOptions);
         },
     };
 }
@@ -290,8 +299,8 @@ export function createWorkerEntrypoint(options) {
             await eventDispatcher.start();
             await jobRunner.start();
         },
-        async stop() {
-            await lifecycle.drain();
+        async stop(stopOptions) {
+            await drainEntrypoint(lifecycle, [jobRunner], stopOptions);
         },
     };
 }
@@ -339,8 +348,8 @@ export function createAllInOneEntrypoint(options) {
             await workerJobRunner.start();
             await apiJobRunner.start();
         },
-        async stop() {
-            await lifecycle.drain();
+        async stop(stopOptions) {
+            await drainEntrypoint(lifecycle, [workerJobRunner, apiJobRunner], stopOptions);
         },
     };
 }

package/dist/entrypoint/internals.d.ts

@@ -27,6 +27,8 @@ export type BaseEntrypointOptions = {
 export type JobsBlock = {
     readonly redisUrl: string;
     readonly queueNamePrefix?: string;
+    readonly redisNamespace?: JobRunnerOptions["redisNamespace"];
+    readonly maintenanceWindow?: JobRunnerOptions["maintenanceWindow"];
     readonly getActiveTenantIds?: JobRunnerOptions["getActiveTenantIds"];
     readonly onJobStart?: JobRunnerOptions["onJobStart"];
     readonly onJobComplete?: JobRunnerOptions["onJobComplete"];

package/dist/files/feature.js

@@ -40,7 +40,7 @@ export function createFilesFeature(options = {}) {
         r.storeTable(fileUploadLedgerTable, { reason: "coordination.file_upload_ledger" });
         r.job({
             name: "sweep-orphaned-uploads",
-            trigger: { cron: "0 * * * *" },
+            trigger: { maintenance: true },
             perTenant: true,
             concurrency: "skip",
             handler: async (_payload, ctx) => {

package/dist/jobs/cron-repeat-options.d.ts

@@ -1,3 +1,5 @@
+import type { JobTrigger } from "@cosmicdrift/kumiko-types/config";
+import { type MaintenanceWindow } from "./maintenance-window.ts";
 export type CronTrigger = {
     readonly cron: string;
     readonly tz?: string | undefined;
@@ -6,4 +8,11 @@ export type CronRepeatOptions = {
     readonly pattern: string;
     readonly tz?: string;
 };
+export type ScheduledTrigger = Extract<JobTrigger, {
+    readonly cron: string;
+}> | Extract<JobTrigger, {
+    readonly maintenance: true;
+}>;
+export declare function isScheduledTrigger(trigger: JobTrigger): trigger is ScheduledTrigger;
 export declare function cronRepeatOptions(trigger: CronTrigger): CronRepeatOptions;
+export declare function scheduleRepeatOptions(trigger: ScheduledTrigger, window?: MaintenanceWindow): CronRepeatOptions;

package/dist/jobs/cron-repeat-options.js

@@ -1,5 +1,14 @@
+import { DEFAULT_MAINTENANCE_WINDOW } from "./maintenance-window.js";
+export function isScheduledTrigger(trigger) {
+    return "cron" in trigger || "maintenance" in trigger;
+}
 export function cronRepeatOptions(trigger) {
     return trigger.tz === undefined
         ? { pattern: trigger.cron }
         : { pattern: trigger.cron, tz: trigger.tz };
 }
+export function scheduleRepeatOptions(trigger, window = DEFAULT_MAINTENANCE_WINDOW) {
+    return "cron" in trigger
+        ? cronRepeatOptions(trigger)
+        : { pattern: `${window.minute} ${window.hour} * * *`, tz: "UTC" };
+}

package/dist/jobs/index.d.ts

@@ -1,2 +1,3 @@
 export type { JobDroppedMeta, JobLogEntry, JobMeta, JobOutcomeMeta, JobQueuedMeta, JobRunner, JobRunnerOptions, } from "./job-runner.ts";
 export { createJobRunner, serializeJobSubject } from "./job-runner.ts";
+export { DEFAULT_MAINTENANCE_WINDOW, MAINTENANCE_WINDOW_ENV, type MaintenanceWindow, maintenanceWindowFromEnv, } from "./maintenance-window.ts";

package/dist/jobs/index.js

@@ -1 +1,2 @@
 export { createJobRunner, serializeJobSubject } from "./job-runner.js";
+export { DEFAULT_MAINTENANCE_WINDOW, MAINTENANCE_WINDOW_ENV, maintenanceWindowFromEnv, } from "./maintenance-window.js";

package/dist/jobs/job-runner-context.js

@@ -12,6 +12,7 @@ import { configAccessorFactoryOf } from "../pipeline/config-accessor-factory.js"
 import { buildContextServices } from "../pipeline/context-services.js";
 import { createGatedIdentitySwitch } from "../pipeline/system-identity-switch.js";
 import { buildPersonalDataGate, parseWriteOrigin } from "../pipeline/write-origin.js";
+import { isScheduledTrigger } from "./cron-repeat-options.js";
 import { createJobAppendEvent } from "./job-append-event.js";
 import { attemptNumberOf, createJobLogger, handlerPayloadOf, hasDeferBudgetLeft, isFinalAttempt, isJobTriggerEvent, jobSubjectKey, missingDbProxy, tenantIdOfJobData, } from "./job-runner-helpers.js";
 // Tenant-visible failure record (JobDefinition.tenantVisibleFailure). The
@@ -56,7 +57,9 @@ function parseJobWriteOrigin(rawData, jobName) {
 function createJobEscapeHatchReporter(scope, input, systemUser) {
     const { jobName, jobDef, tenantId, triggeredById } = input;
     // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
-    const isSystemCronRun = triggeredById === null && jobDef.escapeHatch !== undefined && "cron" in jobDef.trigger;
+    const isSystemCronRun = triggeredById === null &&
+        jobDef.escapeHatch !== undefined &&
+        isScheduledTrigger(jobDef.trigger);
     return createEscapeHatchReporter({
         handler: jobName,
         tenantId,

package/dist/jobs/job-runner-types.d.ts

@@ -1,6 +1,8 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 import type { DispatchWriteRef, JobTriggerEvent } from "@cosmicdrift/kumiko-types/handlers";
 import type { AppContext, JobRunIn, Registry, SessionUser, TenantId } from "../engine/types/index.ts";
+import type { RedisNamespace } from "../redis/client.ts";
+import type { MaintenanceWindow } from "./maintenance-window.ts";
 export type JobLogEntry = {
     level: "info" | "warn" | "error";
     message: string;
@@ -40,6 +42,7 @@ export type JobSubjectValue = string | number | boolean | null;
 export type JobRunner = {
     start(): Promise<void>;
     stop(): Promise<void>;
+    stopConsuming?(): Promise<void>;
     dispatch(jobName: string, payload?: Record<string, unknown>, meta?: JobMeta): Promise<string>;
     handleEvent(eventName: string, payload: Record<string, unknown>, user?: SessionUser, triggerEvent?: JobTriggerEvent): Promise<void>;
     handleCatchUpEvent(jobName: string, eventName: string, payload: Record<string, unknown>, user: SessionUser, triggerEvent: JobTriggerEvent): Promise<void>;
@@ -52,6 +55,8 @@ export type JobRunnerOptions = {
     redisUrl: string;
     consumerLane?: JobRunIn | undefined;
     queueNamePrefix?: string | undefined;
+    redisNamespace?: Pick<RedisNamespace, "keyPrefix" | "bullmqPrefix"> | undefined;
+    maintenanceWindow?: MaintenanceWindow | undefined;
     bootRedisTimeoutMs?: number | undefined;
     schedulerSeenRefreshMs?: number | undefined;
     jobRetention?: {

package/dist/jobs/job-runner.js

@@ -14,7 +14,7 @@ import { registerStandardMetrics } from "../observability/standard-metrics.js";
 import { attachOutsideTransaction } from "../pipeline/attach-outside-transaction.js";
 import { createDistributedLock } from "../pipeline/distributed-lock.js";
 import { RedisKeys } from "../pipeline/redis-keys.js";
-import { cronRepeatOptions } from "./cron-repeat-options.js";
+import { isScheduledTrigger, scheduleRepeatOptions } from "./cron-repeat-options.js";
 import { createJobEventTriggers } from "./job-runner-event-triggers.js";
 import { applyHandlerDeferral, executeJobInSpan } from "./job-runner-execution.js";
 import { claimSequentialSlot, deferOverTenantLimit, fanOutPerTenantJob, PER_TENANT_PREFIX, perTenantTargetOf, releaseSequentialSlot, resolveJobDefinitionOrFail, startJobRun, } from "./job-runner-gates.js";
@@ -24,12 +24,15 @@ import { announceDropped, announceQueued, isOverPerTenantLimit, laneForJob, } fr
 import { resolveMaxPerTenant } from "./max-per-tenant.js";
 export { serializeJobSubject } from "./job-runner-helpers.js";
 export { bootJobIdForJobName, ORPHAN_SCHEDULER_GRACE_MS, schedulerIdForJobName, } from "./job-runner-schedulers.js";
+const DEFAULT_REDIS_NAMESPACE = { keyPrefix: "", bullmqPrefix: "bull" };
 export function createJobRunner(options) {
     const { registry, context, redisUrl, consumerLane } = options;
     const queueNamePrefix = options.queueNamePrefix ?? DEFAULT_QUEUE_NAME_PREFIX;
     const bootRedisTimeoutMs = options.bootRedisTimeoutMs ?? BOOT_REDIS_TIMEOUT_MS;
     const schedulerSeenRefreshMs = options.schedulerSeenRefreshMs ?? ORPHAN_SCHEDULER_GRACE_MS / 4;
     const redisOpts = parseRedisOpts(redisUrl);
+    // BullMQ rejects an ioredis keyPrefix on its connection, so it gets its own `prefix`; only lockRedis uses keyPrefix.
+    const { keyPrefix, bullmqPrefix } = options.redisNamespace ?? DEFAULT_REDIS_NAMESPACE;
     // Use the context's tracer when present (observability-provider injected at
     // boot); otherwise noop so dispatch/handleJob stay zero-cost without config.
     const tracer = context.tracer ?? getFallbackTracer();
@@ -133,7 +136,7 @@ export function createJobRunner(options) {
     let lockRedis = null;
     let sequentialLock = null;
     if (hasSequential) {
-        lockRedis = new Redis(redisOpts);
+        lockRedis = new Redis({ ...redisOpts, keyPrefix });
         // Without a listener, a post-close 'error' (e.g. a teardown-race
         // "Connection is closed") is unhandled and crashes the process — in
         // bun:test it gets attributed to whichever test happens to run next.
@@ -161,10 +164,12 @@ export function createJobRunner(options) {
     const queues = {
         api: new Queue(queueNameFor(queueNamePrefix, "api"), {
             connection: redisOpts,
+            prefix: bullmqPrefix,
             defaultJobOptions: jobRetentionOpts,
         }),
         worker: new Queue(queueNameFor(queueNamePrefix, "worker"), {
             connection: redisOpts,
+            prefix: bullmqPrefix,
             defaultJobOptions: jobRetentionOpts,
         }),
     };
@@ -292,7 +297,7 @@ export function createJobRunner(options) {
     function cronSchedulerIdsForLane(lane) {
         const ids = new Set();
         for (const [name, jobDef] of allJobs) {
-            if (laneForJob(jobDef) === lane && "cron" in jobDef.trigger) {
+            if (laneForJob(jobDef) === lane && isScheduledTrigger(jobDef.trigger)) {
                 ids.add(schedulerIdForJobName(name));
             }
         }
@@ -302,8 +307,8 @@ export function createJobRunner(options) {
         for (const [name, jobDef] of allJobs) {
             if (laneForJob(jobDef) !== lane)
                 continue;
-            if ("cron" in jobDef.trigger) {
-                await queue.upsertJobScheduler(schedulerIdForJobName(name), cronRepeatOptions(jobDef.trigger), {
+            if (isScheduledTrigger(jobDef.trigger)) {
+                await queue.upsertJobScheduler(schedulerIdForJobName(name), scheduleRepeatOptions(jobDef.trigger, options.maintenanceWindow), {
                     name: jobDef.perTenant ? `${PER_TENANT_PREFIX}${name}` : name,
                     data: {},
                     // Queue-level defaultJobOptions (jobRetentionOpts) covers
@@ -370,6 +375,7 @@ export function createJobRunner(options) {
             const consumerQueue = queues[consumerLane];
             worker = new Worker(queueNameFor(queueNamePrefix, consumerLane), (job, token) => handleJob(job, token), {
                 connection: redisOpts,
+                prefix: bullmqPrefix,
                 concurrency: 5,
                 // Not consuming until the boot gates passed: a job already queued from a
                 // previous run must not execute against an unmet boot precondition.
@@ -460,6 +466,9 @@ export function createJobRunner(options) {
             // Last on purpose: a start() that fails earlier must not leave a timer stamping for a runner that is not running.
             schedulerSeenTimer = startSchedulerSeenRefresh(consumerQueue, consumerLane, expectedSchedulerIds);
         },
+        async stopConsuming() {
+            await worker?.pause(true);
+        },
         async stop() {
             stopping = true;
             if (queueDepthTimer) {

package/dist/jobs/maintenance-window.d.ts

@@ -0,0 +1,7 @@
+export type MaintenanceWindow = {
+    readonly hour: number;
+    readonly minute: number;
+};
+export declare const MAINTENANCE_WINDOW_ENV = "KUMIKO_MAINTENANCE_WINDOW";
+export declare const DEFAULT_MAINTENANCE_WINDOW: MaintenanceWindow;
+export declare function maintenanceWindowFromEnv(env?: Record<string, string | undefined>): MaintenanceWindow;

package/dist/jobs/maintenance-window.js

@@ -0,0 +1,14 @@
+export const MAINTENANCE_WINDOW_ENV = "KUMIKO_MAINTENANCE_WINDOW";
+export const DEFAULT_MAINTENANCE_WINDOW = { hour: 3, minute: 0 };
+const MAINTENANCE_WINDOW_PATTERN = /^([01]\d|2[0-3]):([0-5]\d)$/;
+// UTC wall clock, so the window does not move with the server time zone or DST.
+export function maintenanceWindowFromEnv(env = process.env) {
+    const raw = env[MAINTENANCE_WINDOW_ENV]?.trim();
+    if (raw === undefined || raw === "")
+        return DEFAULT_MAINTENANCE_WINDOW;
+    const match = MAINTENANCE_WINDOW_PATTERN.exec(raw);
+    if (match === null) {
+        throw new Error(`${MAINTENANCE_WINDOW_ENV}="${raw}" is invalid: expected HH:MM in UTC, e.g. "03:00" or "22:45".`);
+    }
+    return { hour: Number(match[1]), minute: Number(match[2]) };
+}

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

@@ -14,6 +14,7 @@ export type RedisCacheSyncBusOptions = {
     readonly redisUrl: string;
     readonly clientOptions?: RedisClientOptions;
     readonly channelPrefix?: string;
+    readonly channelSubscribePattern?: string;
 };
 export declare function createRedisCacheSyncBus(opts: RedisCacheSyncBusOptions): ClosableCacheSyncBus;
 export declare function createDefaultCacheSyncBus(envVars?: Record<string, string | undefined>): ClosableCacheSyncBus;

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

@@ -1,5 +1,5 @@
 import { createFallbackLogger } from "../logging/utils.js";
-import { redisClientOptionsFromEnv } from "./client.js";
+import { redisClientOptionsFromEnv, redisNamespaceFromEnv, } from "./client.js";
 import { createRedisPubSubSignal } from "./pubsub-signal.js";
 const log = createFallbackLogger("kumiko:cache-sync");
 const CACHE_SYNC_CHANNEL = "kumiko:cache-sync";
@@ -80,7 +80,10 @@ export function createCacheSyncBusOverSignal(signal, opts) {
     const resyncMinIntervalMs = opts.resyncMinIntervalMs ?? RESYNC_MIN_INTERVAL_MS;
     const now = opts.now ?? Date.now;
     const fanout = createLocalFanout();
-    signal.onMessage((_channel, payload) => {
+    signal.onMessage((channel, payload) => {
+        // skip: a wide subscribe pattern also delivers other features' channels
+        if (channel !== opts.channel)
+            return;
         // skip: foreign or malformed payload on the channel
         if (!isCacheSyncEnvelope(payload))
             return;
@@ -133,7 +136,7 @@ export function createRedisCacheSyncBus(opts) {
     const channel = `${opts.channelPrefix ?? ""}${CACHE_SYNC_CHANNEL}`;
     const signal = createRedisPubSubSignal({
         redisUrl: opts.redisUrl,
-        channelPattern: channel,
+        channelPattern: opts.channelSubscribePattern ?? channel,
         label: "cache-sync",
         ...(opts.clientOptions ? { clientOptions: opts.clientOptions } : {}),
     });
@@ -143,9 +146,15 @@ export function createRedisCacheSyncBus(opts) {
 // 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();
+    if (!redisUrl)
+        return createLocalCacheSyncBus();
+    const { channelPrefix, channelSubscribePattern } = redisNamespaceFromEnv(envVars);
+    return createRedisCacheSyncBus({
+        redisUrl,
+        clientOptions: redisClientOptionsFromEnv(envVars),
+        channelPrefix,
+        ...(channelSubscribePattern !== undefined && { channelSubscribePattern }),
+    });
 }
 // An explicit bus wins (caller owns it), null opts out, undefined builds the default.
 export function resolveCacheSyncBus(explicit) {

package/dist/redis/client.d.ts

@@ -8,5 +8,17 @@ export type RedisClientOptions = {
 };
 export declare function createRedisClient(url: string, options?: RedisClientOptions): Redis;
 export declare function logRedisConnectionState(redis: Redis, logger: Pick<Logger, "warn" | "info">): void;
+export type RedisNamespace = {
+    /** ioredis keyPrefix for every non-BullMQ key; "" when unnamespaced. */
+    readonly keyPrefix: string;
+    /** BullMQ `prefix` option ("bull" is BullMQ's own default). BullMQ rejects an ioredis keyPrefix. */
+    readonly bullmqPrefix: string;
+    /** Prepended to every Pub/Sub channel (ioredis keyPrefix does not apply to Pub/Sub). */
+    readonly channelPrefix: string;
+    /** Set only with KUMIKO_REDIS_PREFIX. Redis checks PSUBSCRIBE patterns against `&` ACL rules literally,
+     *  so `P:kumiko:sse:*` is NOPERM under `&P:*`; subscribe to `P:*` and filter by channel instead. */
+    readonly channelSubscribePattern: string | undefined;
+};
+export declare function redisNamespaceFromEnv(env?: Readonly<Record<string, string | undefined>>): RedisNamespace;
 export declare function redisChannelPrefixFromEnv(env?: Readonly<Record<string, string | undefined>>): string;
 export declare function redisClientOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): RedisClientOptions;

package/dist/redis/client.js

@@ -46,12 +46,37 @@ export function logRedisConnectionState(redis, logger) {
         logger.info("redis recovered");
     });
 }
-// Redis Pub/Sub ignores the DB index and ioredis keyPrefix, so apps or environments sharing one
-// Redis instance would see each other's SSE and toggle-sync traffic. An optional prefix
-// namespaces those channels; unset keeps the unprefixed channel names.
+const BULLMQ_DEFAULT_PREFIX = "bull";
+// No ":" and no glob characters: the ACL rules `~<P>:*` / `&<P>:*` must not match a sibling app ("app-x" vs "app-x2:").
+const REDIS_PREFIX_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/;
+// KUMIKO_REDIS_PREFIX namespaces keys and channels for apps sharing one Redis behind per-app ACL users.
+// KUMIKO_REDIS_CHANNEL_PREFIX alone keeps its older channels-only behaviour.
+export function redisNamespaceFromEnv(env = process.env) {
+    const prefix = env["KUMIKO_REDIS_PREFIX"]?.trim();
+    const channelPrefix = env["KUMIKO_REDIS_CHANNEL_PREFIX"]?.trim();
+    if (!prefix) {
+        return {
+            keyPrefix: "",
+            bullmqPrefix: BULLMQ_DEFAULT_PREFIX,
+            channelPrefix: channelPrefix ? `${channelPrefix}:` : "",
+            channelSubscribePattern: undefined,
+        };
+    }
+    if (!REDIS_PREFIX_PATTERN.test(prefix)) {
+        throw new Error(`KUMIKO_REDIS_PREFIX "${prefix}" is invalid: use 1-63 characters of A-Z a-z 0-9 _ - starting with a letter or digit (no ":" or glob characters).`);
+    }
+    if (channelPrefix && channelPrefix !== prefix) {
+        throw new Error(`KUMIKO_REDIS_PREFIX "${prefix}" and KUMIKO_REDIS_CHANNEL_PREFIX "${channelPrefix}" differ; unset the channel prefix or make them equal.`);
+    }
+    return {
+        keyPrefix: `${prefix}:`,
+        bullmqPrefix: `${prefix}:${BULLMQ_DEFAULT_PREFIX}`,
+        channelPrefix: `${prefix}:`,
+        channelSubscribePattern: `${prefix}:*`,
+    };
+}
 export function redisChannelPrefixFromEnv(env = process.env) {
-    const raw = env["KUMIKO_REDIS_CHANNEL_PREFIX"]?.trim();
-    return raw ? `${raw}:` : "";
+    return redisNamespaceFromEnv(env).channelPrefix;
 }
 // Env-var reader — mirrors dbConnectionOptionsFromEnv's contract. Strict:
 // malformed values throw at boot rather than silently falling back to

package/dist/redis/index.d.ts

@@ -2,6 +2,6 @@ export type { CacheSyncBus, ClosableCacheSyncBus, } from "./cache-sync-bus.ts";
 export { createDefaultCacheSyncBus, createLocalCacheSyncBus, createRedisCacheSyncBus, } from "./cache-sync-bus.ts";
 export type { TenantConfigSyncMessage, TierAssignmentSyncMessage } from "./cache-sync-topics.ts";
 export { CACHE_SYNC_TOPICS, isTierAssignmentSyncMessage, } from "./cache-sync-topics.ts";
-export type { RedisClientOptions } from "./client.ts";
-export { createRedisClient, logRedisConnectionState, redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "./client.ts";
+export type { RedisClientOptions, RedisNamespace } from "./client.ts";
+export { createRedisClient, logRedisConnectionState, redisChannelPrefixFromEnv, redisClientOptionsFromEnv, redisNamespaceFromEnv, } from "./client.ts";
 export { createRedisPubSubSignal } from "./pubsub-signal.ts";

package/dist/redis/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.403.0",
+  "version": "0.404.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.403.0",
+    "@cosmicdrift/kumiko-types": "0.404.0",
     "bullmq": "^5.76.7",
     "hono": "^4.13.14",
     "i18next": "^26.1.0",
@@ -225,7 +225,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.403.0",
+    "@cosmicdrift/kumiko-testing": "0.404.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
     "meilisearch": "^0.58.0",

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.404.0",
+    "type": "improvement",
+    "title": "Maintenance trigger and KUMIKO_MAINTENANCE_WINDOW",
+    "detail": "The job runner registers maintenance jobs as a daily UTC scheduler at JobRunnerOptions.maintenanceWindow (default 03:00), set from KUMIKO_MAINTENANCE_WINDOW by runProdApp and runWorkerApp; an invalid value aborts the boot. maintenanceWindowFromEnv is exported from the jobs barrel. files sweep-orphaned-uploads (hourly before) and the soft-delete cleanup jobs (03:00 and 03:15 before) now run in the window. A schedule stored with the old time is replaced on the next start."
+  },
+  {
+    "version": "0.404.0",
+    "type": "improvement",
+    "title": "KUMIKO_REDIS_PREFIX namespaces all Redis keys and channels",
+    "detail": "redisNamespaceFromEnv resolves keyPrefix, bullmqPrefix, channelPrefix and the subscribe pattern. Unset keeps today's layout (bull:*, unprefixed locks, rate limit, idempotency and cache keys). Set, the main ioredis client gets keyPrefix <P>:, the job runner passes prefix <P>:bull to every Queue and Worker (new JobRunnerOptions.redisNamespace, also on the entrypoint jobs block) and gives its lock client the keyPrefix, and the SSE broker, cache-sync bus and toggle signal use <P>: channels. Redis matches PSUBSCRIBE patterns literally against ACL channel rules, so with a prefix they subscribe to <P>:* and filter by channel. A value with \":\" or glob characters, or a KUMIKO_REDIS_CHANNEL_PREFIX that differs from it, aborts the boot. The cache-sync bus of runProdApp, runWorkerApp and createDefaultCacheSyncBus now also honours KUMIKO_REDIS_CHANNEL_PREFIX alone (before, only SSE and toggle channels did). JobRunner gains an optional stopConsuming(), which createJobRunner implements. The ACL rule set and the key layout for a wake-up service are in docs/reference/infra-requirements.md."
+  },
   {
     "version": "0.403.0",
     "type": "improvement",