@cosmicdrift/kumiko-framework 0.402.0 → 0.404.0

package/dist/engine/boot-validator/entity-list-screens-rules.js

@@ -24,6 +24,11 @@ export const ENTITY_LIST_RULES = {
         summary: "A list whose entity has a detail screen offers a navigate row action.",
         fix: 'Add a navigate rowAction with id "view" or "edit".',
     },
+    unknownNamedFilter: {
+        id: "entity-list/unknown-named-filter",
+        summary: "Every screen namedFilters id is declared in the entity's namedFilters.",
+        fix: "Declare the rule in EntityDefinition.namedFilters or remove the id from the screen.",
+    },
     unknownColumn: {
         id: "entity-list/unknown-column",
         summary: "Every column without a label names an entity field, derived field or row-meta column.",

package/dist/engine/boot-validator/entity-list-screens.js

@@ -95,12 +95,24 @@ function checkColumns(feature, screen) {
         }
     });
 }
+function checkNamedFilters(feature, screen) {
+    const declared = feature.entities?.[screen.entity]?.namedFilters ?? {};
+    collectBootRuleViolations(screen.namedFilters ?? [], (ref) => {
+        // skip: id is declared on the entity
+        if (Object.hasOwn(declared, ref.id))
+            return;
+        throw bootRuleError(ENTITY_LIST_RULES.unknownNamedFilter, {
+            message: `${screenPrefix(feature, screen)}: namedFilters id "${ref.id}" is not declared in entity "${screen.entity}" namedFilters. Known: ${Object.keys(declared).sort().join(", ") || "(none)"}.`,
+        });
+    });
+}
 const ENTITY_LIST_CHECKS = [
     checkSearchable,
     checkDefaultSortRequired,
     checkDefaultSortColumn,
     checkDetailNavigate,
     checkColumns,
+    checkNamedFilters,
 ];
 export function validateEntityListScreens(features) {
     const screens = features.flatMap((feature) => Object.values(feature.screens).flatMap((screen) => screen.type === "entityList" ? [{ feature, screen }] : []));

package/dist/engine/boot-validator/named-filter-rules.d.ts

@@ -0,0 +1,32 @@
+export declare const NAMED_FILTER_RULES: {
+    readonly projectionQueryAcceptsNamedFilter: {
+        readonly id: "named-filter/projection-query-accepts-named-filter";
+        readonly summary: "A projectionList with namedFilters binds a query whose schema has a namedFilter key.";
+        readonly fix: "Add namedFilter: z.string().optional() to the query schema, resolve it with resolveNamedListFilters and pass the conditions into executor.list filters, the only path that applies field-read and PII guards.";
+    };
+    readonly statNavigateTarget: {
+        readonly id: "named-filter/stat-navigate-target";
+        readonly summary: "A stat navigate.screen resolves to an entityList or projectionList screen.";
+        readonly fix: "Point navigate.screen at a registered list screen.";
+    };
+    readonly statNavigateFilterDeclared: {
+        readonly id: "named-filter/stat-navigate-filter-declared";
+        readonly summary: "A stat navigate.namedFilter is declared in the target screen's namedFilters.";
+        readonly fix: "Add { id, label } to namedFilters of the target screen.";
+    };
+    readonly statNavigateSameQuery: {
+        readonly id: "named-filter/stat-navigate-same-query";
+        readonly summary: "A stat with navigate counts with the target list's own query.";
+        readonly fix: "Set the stat query to the target list's query.";
+    };
+    readonly statNavigateSameNamedFilter: {
+        readonly id: "named-filter/stat-navigate-same-named-filter";
+        readonly summary: "A stat's params.namedFilter equals navigate.namedFilter.";
+        readonly fix: "Set params.namedFilter to the same id as navigate.namedFilter.";
+    };
+    readonly statNavigateStaticFilter: {
+        readonly id: "named-filter/stat-navigate-static-filter";
+        readonly summary: "A stat repeats the target screen's static filter in params.filter.";
+        readonly fix: "Set params.filter to the target screen's filter.";
+    };
+};

package/dist/engine/boot-validator/named-filter-rules.js

@@ -0,0 +1,32 @@
+export const NAMED_FILTER_RULES = {
+    projectionQueryAcceptsNamedFilter: {
+        id: "named-filter/projection-query-accepts-named-filter",
+        summary: "A projectionList with namedFilters binds a query whose schema has a namedFilter key.",
+        fix: "Add namedFilter: z.string().optional() to the query schema, resolve it with resolveNamedListFilters and pass the conditions into executor.list filters, the only path that applies field-read and PII guards.",
+    },
+    statNavigateTarget: {
+        id: "named-filter/stat-navigate-target",
+        summary: "A stat navigate.screen resolves to an entityList or projectionList screen.",
+        fix: "Point navigate.screen at a registered list screen.",
+    },
+    statNavigateFilterDeclared: {
+        id: "named-filter/stat-navigate-filter-declared",
+        summary: "A stat navigate.namedFilter is declared in the target screen's namedFilters.",
+        fix: "Add { id, label } to namedFilters of the target screen.",
+    },
+    statNavigateSameQuery: {
+        id: "named-filter/stat-navigate-same-query",
+        summary: "A stat with navigate counts with the target list's own query.",
+        fix: "Set the stat query to the target list's query.",
+    },
+    statNavigateSameNamedFilter: {
+        id: "named-filter/stat-navigate-same-named-filter",
+        summary: "A stat's params.namedFilter equals navigate.namedFilter.",
+        fix: "Set params.namedFilter to the same id as navigate.namedFilter.",
+    },
+    statNavigateStaticFilter: {
+        id: "named-filter/stat-navigate-static-filter",
+        summary: "A stat repeats the target screen's static filter in params.filter.",
+        fix: "Set params.filter to the target screen's filter.",
+    },
+};

package/dist/engine/boot-validator/projection-list-screens.js

@@ -1,8 +1,10 @@
 import { isListQueryWithoutSearchableFields, resolveEntityBehindListQuery, } from "../entity-list-searchability.js";
 import { QnTypes, qualifyEntityName } from "../qualified-name.js";
 import { isEditLayoutScreen } from "../screen-helpers.js";
+import { bootRuleError } from "./boot-rule.js";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
 import { validateListTableAggregateQuery } from "./list-table-aggregate-query.js";
+import { NAMED_FILTER_RULES } from "./named-filter-rules.js";
 import { findEntity } from "./parent-ref.js";
 import { getZodObjectShape } from "./zod-shape.js";
 // Sibling to entity-list-screens.ts rather than an extension of it:
@@ -66,6 +68,7 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers, feature
     }
     validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
     validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
+    validateProjectionListNamedFilterSchemaAcceptance(prefix, screen, schema);
     validateListTableAggregateQuery({ prefix, ...screen, handler, featureMap });
 }
 // filter sends `payload.filter` — same 422 footgun as facets below
@@ -78,6 +81,16 @@ function validateProjectionListFilterSchemaAcceptance(prefix, screen, schema) {
         `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
         `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
 }
+// namedFilters send `payload.namedFilter` — same 422 footgun as filter/facets.
+function validateProjectionListNamedFilterSchemaAcceptance(prefix, screen, schema) {
+    // skip: no named filters declared, or the schema already accepts the key — nothing to reject.
+    if (screen.namedFilters === undefined || schemaAccepts(schema, "namedFilter"))
+        return;
+    throw bootRuleError(NAMED_FILTER_RULES.projectionQueryAcceptsNamedFilter, {
+        message: `${prefix}: declares namedFilters but query "${screen.query}" has no "namedFilter" parameter in its ` +
+            `Zod schema — add namedFilter: z.string().optional() to the handler's schema and resolve it with resolveNamedListFilters.`,
+    });
+}
 // facets send `payload.filters` — same failure mode as search/sort:
 // definePagedQueryHandler doesn't auto-merge params into the
 // handler's own Zod schema, so a declared facet would 422 on every query

package/dist/engine/entity-handlers.d.ts

@@ -45,6 +45,7 @@ export declare const entityListSchema: z.ZodObject<{
         }>;
         value: z.ZodUnknown;
     }, z.core.$strip>>>;
+    namedFilter: z.ZodOptional<z.ZodString>;
     aggregate: z.ZodOptional<z.ZodObject<{
         groupBy: z.ZodOptional<z.ZodString>;
         measures: z.ZodDefault<z.ZodArray<z.ZodObject<{

package/dist/engine/entity-handlers.js

@@ -15,6 +15,7 @@ import { entityListRuntime, parentVisibilityFor } from "./entity-list-runtime-op
 import { assertReason } from "./escape-hatch-reason.js";
 import { dropEmptyWriteOnlyValues } from "./field-access.js";
 import { instructionFieldNames } from "./instruction-fields.js";
+import { resolveNamedListFilters } from "./resolve-named-list-filters.js";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder.js";
 import { parseTenantId } from "./types/identifiers.js";
 // Convention-based handler factories for event-sourced aggregates.
@@ -109,6 +110,8 @@ export const entityListSchema = z.object({
         value: z.unknown(),
     }))
         .optional(),
+    // Entity-defined work-queue rule (EntityDefinition.namedFilters); its conditions are appended to `filters`.
+    namedFilter: z.string().min(1).max(100).optional(),
     aggregate: listAggregatePayloadSchema.optional(),
 });
 function parseHandlerName(name, validVerbs) {
@@ -398,7 +401,16 @@ export function defineEntityQueryHandler(name, entity, options) {
                 // against Meilisearch/InMem at runtime (remote combobox search). The
                 // executor is built at definition time and cannot know the adapter, so the
                 // runtime override supplies it.
-                const listPayload = query.payload; // @cast-boundary engine-payload
+                const requestPayload = query.payload; // @cast-boundary engine-payload
+                const listPayload = requestPayload.namedFilter === undefined
+                    ? requestPayload
+                    : {
+                        ...requestPayload,
+                        filters: [
+                            ...(requestPayload.filters ?? []),
+                            ...(await resolveNamedListFilters(ctx, query.user, entityName, requestPayload.namedFilter)),
+                        ],
+                    };
                 const db = dbFor(ctx);
                 const { runtimeOptions, eagerLoadViewer, resolveEntity } = entityListRuntime(ctx, entityName, query.user);
                 if (listPayload.aggregate !== undefined) {

package/dist/engine/factories.d.ts

@@ -208,6 +208,8 @@ export declare function createEntity<const F, const T extends EntityTenancy = "t
     readonly readGate?: EntityDefinition["readGate"];
     readonly retention?: RetentionDef;
     readonly derivedFields?: EntityDefinition["derivedFields"];
+    /** See EntityDefinition.namedFilters. */
+    readonly namedFilters?: EntityDefinition["namedFilters"];
     readonly tenancy?: T;
     /** See EntityDefinition.transferable. */
     readonly transferable?: boolean;

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/index.d.ts

@@ -80,6 +80,7 @@ export { defineApply, defineMspApply, setFields } from "./projection-helpers.ts"
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.ts";
 export { readClaim } from "./read-claim.ts";
 export { createRegistry } from "./registry.ts";
+export { resolveNamedListFilters } from "./resolve-named-list-filters.ts";
 export type { AssignableAppRoles } from "./role-assignment.ts";
 export { assignableAppRolesFromUsages, assignableAppRolesOf, BUILT_IN_MEMBERSHIP_ROLES, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.ts";
 export { runPipeline, runStepList } from "./run-pipeline.ts";

package/dist/engine/index.js

@@ -64,6 +64,7 @@ export { defineApply, defineMspApply, setFields } from "./projection-helpers.js"
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.js";
 export { readClaim } from "./read-claim.js";
 export { createRegistry } from "./registry.js";
+export { resolveNamedListFilters } from "./resolve-named-list-filters.js";
 export { assignableAppRolesFromUsages, assignableAppRolesOf, BUILT_IN_MEMBERSHIP_ROLES, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.js";
 export { runPipeline, runStepList } from "./run-pipeline.js";
 export { buildInsertSchema, buildUpdateSchema, fieldToZod, SYSTEM_ONLY_JSON_SCHEMA_KEY, } from "./schema-builder.js";

package/dist/engine/resolve-named-list-filters.d.ts

@@ -0,0 +1,3 @@
+import type { NamedListFilterCondition } from "@cosmicdrift/kumiko-types/named-list-filters";
+import type { HandlerContext, SessionUser } from "./types/index.ts";
+export declare function resolveNamedListFilters(ctx: HandlerContext, user: SessionUser, entityName: string, name: string): Promise<readonly NamedListFilterCondition[]>;

package/dist/engine/resolve-named-list-filters.js

@@ -0,0 +1,30 @@
+import { AccessDeniedError, ValidationError } from "../errors/index.js";
+import { hasAccess } from "./access.js";
+export async function resolveNamedListFilters(ctx, user, entityName, name) {
+    const registered = ctx.registry.getEntity(entityName)?.namedFilters ?? {};
+    const def = Object.hasOwn(registered, name) ? registered[name] : undefined;
+    if (def === undefined) {
+        throw new ValidationError({
+            fields: [
+                {
+                    path: "namedFilter",
+                    code: "unknown_named_filter",
+                    i18nKey: "errors.validation.invalid_value",
+                    params: { entity: entityName, namedFilter: name },
+                },
+            ],
+        });
+    }
+    if (def.access !== undefined && !hasAccess(user, def.access)) {
+        throw new AccessDeniedError();
+    }
+    const conditions = await def.filters({ ctx, user, now: ctx.tz.now() });
+    const entityFields = ctx.registry.getEntity(entityName)?.fields ?? {};
+    for (const condition of conditions) {
+        // Fail closed: a condition on a non-column is dropped by the list filter and would widen the queue.
+        if (condition.field !== "id" && !Object.hasOwn(entityFields, condition.field)) {
+            throw new Error(`Named filter "${name}" of entity "${entityName}" filters on unknown field "${condition.field}".`);
+        }
+    }
+    return conditions;
+}

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;