effect-mq 0.4.1 → 0.5.0

package/src/Job.ts

@@ -88,6 +88,28 @@ export interface BackoffInput {
   readonly factor?: number | undefined
 }
 
+/**
+ * The `error` option for `Job.make`: one schema, or a list of schemas the
+ * definition unions for you — the tagged-error-list style of Effect's
+ * `HttpApiEndpoint`:
+ *
+ * ```ts
+ * error: PaymentDeclined
+ * error: [InvoiceNotFound, PaymentDeclined, ProviderTimeout]
+ * ```
+ *
+ * @since 0.4.2
+ */
+export type ErrorInput = Schema.Top | ReadonlyArray<Schema.Top>
+
+/**
+ * The schema a job actually carries for its `error` option: lists become a
+ * `Schema.Union` of their members, single schemas pass through.
+ *
+ * @since 0.4.2
+ */
+export type ResolvedError<E extends ErrorInput> = E extends ReadonlyArray<Schema.Top> ? Schema.Union<E> : E
+
 /**
  * User-facing retention configuration for terminal jobs.
  *
@@ -330,6 +352,12 @@ export interface ScheduleOptions<PayloadInput> {
   readonly keep?: KeepInput | undefined
   /** Per-run execution time limit for each occurrence. */
   readonly timeout?: Duration.Input | undefined
+  /**
+   * Ownership label for declarative reconciliation: `JobSchedules.layer`
+   * prunes only schedules carrying its own group. Unlabeled schedules are
+   * never pruned. Usually set by `JobSchedules`, not by hand.
+   */
+  readonly group?: string | undefined
 }
 
 /**
@@ -962,6 +990,7 @@ const Proto = {
         timeoutMs: options.timeout !== undefined
           ? Duration.toMillis(options.timeout)
           : self.defaults.timeoutMs,
+        group: options.group,
         nextRunAt
       }
       const store = yield* self.store
@@ -1051,7 +1080,7 @@ export const make = <
   const Name extends string,
   Payload extends Schema.Struct.Fields | AnyStructSchema,
   Success extends Schema.Top = Schema.Void,
-  Error extends Schema.Top = Schema.Never,
+  Error extends ErrorInput = Schema.Never,
   StoreId = JobStore
 >(
   name: Name,
@@ -1060,7 +1089,11 @@ export const make = <
     readonly payload: Payload
     /** Schema for the handler's success value (decodable via `awaitResult`/`attempts`). Default `Schema.Void`. */
     readonly success?: Success | undefined
-    /** Schema for the handler's typed failure (round-trips through storage). Default `Schema.Never`. */
+    /**
+     * Schema for the handler's typed failure — one schema, or a list of
+     * schemas unioned for you (round-trips through storage). Default
+     * `Schema.Never`.
+     */
     readonly error?: Error | undefined
     /**
      * Derive a stable job id from the payload. Enqueueing the same key twice
@@ -1099,7 +1132,7 @@ export const make = <
      */
     readonly retryable?:
       | ((
-        error: Error["Type"]
+        error: ResolvedError<Error>["Type"]
       ) => boolean)
       | undefined
     /** The queue this job runs on. Default `"default"`. */
@@ -1116,7 +1149,7 @@ export const make = <
   Name,
   Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
   Success,
-  Error,
+  ResolvedError<Error>,
   StoreId
 > => {
   // SAFETY: `Schema.isSchema` discriminates the `Payload` union at runtime;
@@ -1126,7 +1159,14 @@ export const make = <
     ? options.payload as AnyStructSchema
     : Schema.Struct(options.payload as Schema.Struct.Fields)
   const successSchema = options.success ?? Schema.Void
-  const errorSchema = options.error ?? Schema.Never
+  // SAFETY: `Array.isArray` discriminates the `ErrorInput` union at runtime;
+  // TypeScript cannot narrow an unresolved generic, so each branch asserts
+  // the side the guard just proved.
+  const errorSchema = options.error === undefined
+    ? Schema.Never
+    : Array.isArray(options.error)
+    ? Schema.Union(options.error as ReadonlyArray<Schema.Top>)
+    : options.error as Schema.Top
   // Wrapping the whole Exit schema in the JSON codec makes the *encoded* side
   // plain JSON (a live Exit/Cause instance would not survive serializing
   // drivers like Redis/Postgres).

package/src/JobSchedules.ts

@@ -0,0 +1,223 @@
+/**
+ * Declarative schedule reconciliation.
+ *
+ * `.schedule()` is imperative: it creates and updates, and a schedule whose
+ * call was deleted from code keeps firing forever (deletion drift). This
+ * module declares the FULL schedule set for a service as a layer; on
+ * startup it upserts everything declared (idempotent, cadence-preserving)
+ * and detects group members that are no longer declared:
+ *
+ * ```ts
+ * const SchedulesLive = JobSchedules.layer({
+ *   group: "billing-service",
+ *   schedules: [
+ *     JobSchedules.schedule(SendDigest, "daily", { cron: "0 9 * * *", payload: {} }),
+ *     JobSchedules.schedule(GenerateInvoice, "monthly", { cron: "0 0 1 * *", payload: {} })
+ *   ],
+ *   removal: "group",           // default "warn": log drift, prune nothing
+ *   removeAfter: "10 minutes"   // optional grace window for rolling deploys
+ * })
+ * ```
+ *
+ * Safety model: pruning is scoped to the ownership `group`. Schedules
+ * created by plain `.schedule()` calls carry no group and are NEVER pruned;
+ * other groups' schedules are never touched. The default `removal: "warn"`
+ * only logs — destructive pruning is an explicit opt-in.
+ *
+ * @since 0.5.0
+ */
+import { type Context, Duration, Effect, Layer } from "effect"
+import type { ScheduleOptions } from "./Job.ts"
+import type { ScheduleKey, Service as StoreService } from "./JobStore.ts"
+
+/**
+ * The structural view of a `Job.make` class that `schedule` needs: its tag,
+ * its store key, and its bound `schedule` verb.
+ *
+ * @since 0.5.0
+ */
+export interface SchedulableJob<PayloadInput, R> {
+  readonly _tag: string
+  readonly store: Context.Key<any, StoreService>
+  readonly schedule: (
+    key: string,
+    options: ScheduleOptions<PayloadInput>
+  ) => Effect.Effect<ScheduleKey, never, R>
+}
+
+/**
+ * One declared schedule: a job, its key, and its cadence/options. Built
+ * with `JobSchedules.schedule`; consumed by `JobSchedules.layer`.
+ *
+ * @since 0.5.0
+ */
+export interface ScheduleEntry<R> {
+  readonly jobName: string
+  readonly key: string
+  readonly store: Context.Key<any, StoreService>
+  readonly register: (group: string) => Effect.Effect<ScheduleKey, never, R>
+}
+
+/**
+ * Declare one schedule for the reconciled set. Identical semantics to
+ * `MyJob.schedule(key, options)` — including cadence preservation on
+ * unchanged `cron`/`tz`/`every` — plus the layer's ownership `group`.
+ *
+ * @since 0.5.0
+ */
+export const schedule = <PayloadInput, R>(
+  job: SchedulableJob<PayloadInput, R>,
+  key: string,
+  options: Omit<ScheduleOptions<PayloadInput>, "group">
+): ScheduleEntry<R> => ({
+  jobName: job._tag,
+  key,
+  store: job.store,
+  register: (group) => job.schedule(key, { ...options, group })
+})
+
+/**
+ * Options for `JobSchedules.layer`.
+ *
+ * @since 0.5.0
+ */
+export interface ReconcileOptions<
+  Entries extends ReadonlyArray<ScheduleEntry<any>>,
+  Stores extends ReadonlyArray<Context.Key<any, StoreService>>
+> {
+  /**
+   * Ownership label. Everything this layer declares is upserted with this
+   * group, and only schedules carrying this group are candidates for drift
+   * detection and pruning. Use one group per service/deployable.
+   */
+  readonly group: string
+  /** The full declared schedule set for this group. */
+  readonly schedules: Entries
+  /**
+   * What to do with group members that are no longer declared:
+   * - `"warn"` (default): log them at warning level, prune nothing.
+   * - `"group"`: remove them (never touches unlabeled or other-group rows).
+   */
+  readonly removal?: "warn" | "group" | undefined
+  /**
+   * Grace window before pruning (requires `removal: "group"`). During a
+   * rolling deploy, replicas on the previous release re-declare schedules
+   * the new release dropped; pruning immediately and re-adding would
+   * re-anchor `every` grids and double-fire crons. With a window, the prune
+   * runs this long after startup, re-checks the store, and removes only
+   * members still undeclared. Shutting down before the window fires skips
+   * the prune (the next startup re-evaluates).
+   */
+  readonly removeAfter?: Duration.Input | undefined
+  /**
+   * Extra store keys to reconcile even when no declared entry references
+   * them — needed when a release drops the LAST schedule a store had, since
+   * drift detection only reaches stores it can see.
+   */
+  readonly stores?: Stores | undefined
+}
+
+const reconcile = (options: {
+  readonly group: string
+  readonly schedules: ReadonlyArray<ScheduleEntry<any>>
+  readonly removal?: "warn" | "group" | undefined
+  readonly removeAfter?: Duration.Input | undefined
+  readonly stores?: ReadonlyArray<Context.Key<any, StoreService>> | undefined
+}) =>
+  Effect.gen(function*() {
+    const removal = options.removal ?? "warn"
+    if (options.removeAfter !== undefined && removal !== "group") {
+      return yield* Effect.die(
+        new Error(`effect-mq: \`removeAfter\` requires \`removal: "group"\``)
+      )
+    }
+    // Duplicate declarations are a config bug: the second would silently
+    // overwrite the first's cadence/payload on every startup.
+    const seen = new Set<string>()
+    for (const entry of options.schedules) {
+      const id = `${entry.jobName}/${entry.key}`
+      if (seen.has(id)) {
+        return yield* Effect.die(
+          new Error(`effect-mq: schedule "${id}" is declared twice in group "${options.group}"`)
+        )
+      }
+      seen.add(id)
+    }
+
+    // Upsert every declared schedule, collecting the declared key set per
+    // store (Context.Key identity groups entries onto their stores).
+    const byStore = new Map<Context.Key<any, StoreService>, Set<string>>()
+    for (const storeKey of options.stores ?? []) {
+      byStore.set(storeKey, new Set())
+    }
+    for (const entry of options.schedules) {
+      const registered = yield* entry.register(options.group)
+      const declared = byStore.get(entry.store) ?? new Set<string>()
+      declared.add(registered)
+      byStore.set(entry.store, declared)
+    }
+
+    // Drift detection per store: group members not in the declared set.
+    for (const [storeKey, declared] of byStore) {
+      const store = yield* storeKey
+      const prune = Effect.gen(function*() {
+        const members = yield* store.listSchedules({ group: options.group }).pipe(
+          Effect.retry({ times: 5 }),
+          Effect.orDie
+        )
+        const undeclared = members.filter((member) => !declared.has(member.key))
+        if (undeclared.length === 0) return
+        if (removal === "warn") {
+          return yield* Effect.logWarning(
+            `effect-mq: ${undeclared.length} schedule(s) in group "${options.group}" ` +
+              `are no longer declared and keep firing; \`removal: "group"\` would prune them`,
+            undeclared.map((member) => member.key)
+          )
+        }
+        for (const member of undeclared) {
+          yield* store.removeSchedule(member.key).pipe(Effect.retry({ times: 5 }), Effect.orDie)
+        }
+        yield* Effect.logInfo(
+          `effect-mq: pruned ${undeclared.length} undeclared schedule(s) from group "${options.group}"`,
+          undeclared.map((member) => member.key)
+        )
+      })
+      if (removal === "group" && options.removeAfter !== undefined) {
+        // Deferred prune, tied to the layer scope: it re-lists at fire time,
+        // so anything re-declared during the window survives.
+        yield* prune.pipe(
+          Effect.delay(Duration.toMillis(options.removeAfter)),
+          Effect.catchCause((cause) =>
+            Effect.logError(
+              `effect-mq: deferred schedule prune failed (group "${options.group}")`,
+              cause
+            )
+          ),
+          Effect.forkScoped
+        )
+      } else {
+        yield* prune
+      }
+    }
+  })
+
+/**
+ * Reconcile the declared schedule set on startup: upsert everything
+ * declared, then warn about (or, with `removal: "group"`, prune) group
+ * members that are no longer declared. See the module docs for the safety
+ * model.
+ *
+ * @since 0.5.0
+ */
+export const layer = <
+  const Entries extends ReadonlyArray<ScheduleEntry<any>>,
+  const Stores extends ReadonlyArray<Context.Key<any, StoreService>> = readonly []
+>(
+  options: ReconcileOptions<Entries, Stores>
+): Layer.Layer<never, never, EntryServices<Entries[number]> | StoreId<Stores[number]>> =>
+  Layer.effectDiscard(reconcile(options))
+
+// Naked-parameter conditionals so empty tuples distribute to `never` instead
+// of inferring `unknown` from nothing.
+type EntryServices<E> = E extends ScheduleEntry<infer R> ? R : never
+type StoreId<K> = K extends Context.Key<infer Id, StoreService> ? Id : never

package/src/JobStore.ts

@@ -450,6 +450,12 @@ export interface ScheduleRecord {
   readonly backoff: BackoffPolicy | undefined
   readonly keep: KeepPolicy | undefined
   readonly timeoutMs: number | undefined
+  /**
+   * Ownership label for declarative reconciliation (`JobSchedules.layer`):
+   * a reconciler only ever prunes schedules carrying ITS group. Unlabeled
+   * schedules (plain `.schedule()` calls) are never pruned.
+   */
+  readonly group: string | undefined
   /** Epoch millis of the next occurrence to enqueue. */
   readonly nextRunAt: number
 }
@@ -796,6 +802,8 @@ export interface Service {
   readonly listSchedules: (options?: {
     readonly jobName?: string | undefined
     readonly queue?: QueueName | undefined
+    /** Only schedules carrying this ownership group. */
+    readonly group?: string | undefined
   }) => Effect.Effect<ReadonlyArray<ScheduleRecord>, JobStoreError>
 
   /** Schedules whose `nextRunAt` is due (per the Effect `Clock`). */

package/src/MemoryJobStore.ts

@@ -753,7 +753,8 @@ const makeStoreUnsafe = (options?: MemoryJobStoreOptions | undefined): MemorySto
       Effect.sync(() =>
         Array.from(schedules.values()).filter((schedule) =>
           (options?.jobName === undefined || schedule.jobName === options.jobName) &&
-          (options?.queue === undefined || schedule.queue === options.queue)
+          (options?.queue === undefined || schedule.queue === options.queue) &&
+          (options?.group === undefined || schedule.group === options.group)
         )
       ),
 

package/src/Worker.ts

@@ -142,10 +142,39 @@ export interface WorkerOptions<StoreId = JobStore> {
    * - `"none"`: spans and attributes only, no cross-trace edge.
    */
   readonly traceLinking?: "auto" | "parent" | "link" | "none" | undefined
+  /**
+   * Called after a failed run is acked — both retryable attempts and
+   * terminal failures (`JobFailure.willRetry` tells them apart), including
+   * jobs failed by stall exhaustion. Runs isolated on the worker fiber: a
+   * failing hook is logged and never disturbs job processing. The worker
+   * also logs failures itself (`logWarning` for retries, `logError` for
+   * terminal failures), so the hook is for custom reporting (error
+   * trackers, paging), not a logging prerequisite.
+   */
+  readonly onJobFailure?: ((failure: JobFailure) => Effect.Effect<void>) | undefined
   /** Identifier used in lock tokens (default: random). */
   readonly id?: string | undefined
 }
 
+/**
+ * What `Worker.layer({ onJobFailure })` receives after a failed run is
+ * acked: job identity, attempt accounting, whether the store will retry,
+ * and the failure cause.
+ *
+ * @since 0.4.2
+ */
+export interface JobFailure {
+  readonly jobId: JobId
+  readonly name: string
+  readonly queue: QueueName
+  /** The attempt that failed (1-based). */
+  readonly attempt: number
+  readonly attemptsMax: number
+  /** True when the store will re-run the job after its backoff. */
+  readonly willRetry: boolean
+  readonly cause: Cause.Cause<unknown>
+}
+
 /**
  * @since 0.1.0
  */
@@ -312,6 +341,34 @@ export const make = <StoreId = JobStore>(
         )
       )
 
+    // Every failed run is logged (warning while retries remain, error once
+    // terminal) and handed to the onJobFailure hook. The hook runs isolated:
+    // whatever it does, job processing proceeds.
+    const reportFailure = (failure: JobFailure, retryDelayMs: number | undefined) =>
+      Effect.gen(function*() {
+        yield* (failure.willRetry
+          ? Effect.logWarning(
+            `effect-mq: job "${failure.name}" failed (attempt ${failure.attempt}/${failure.attemptsMax}); ` +
+              `retrying in ${retryDelayMs ?? 0}ms`,
+            failure.cause
+          )
+          : Effect.logError(
+            `effect-mq: job "${failure.name}" failed terminally ` +
+              `(attempt ${failure.attempt}/${failure.attemptsMax})`,
+            failure.cause
+          )).pipe(Effect.annotateLogs({
+            effectMqJobId: failure.jobId,
+            effectMqQueue: failure.queue,
+            effectMqAttempt: failure.attempt
+          }))
+        const hook = options?.onJobFailure
+        if (hook !== undefined) {
+          yield* hook(failure).pipe(
+            Effect.catchCause((cause) => Effect.logError("effect-mq: onJobFailure hook failed", cause))
+          )
+        }
+      })
+
     const routeFailure = (record: JobRecord, exit: JobRecord["exit"]): AckOutcome => {
       const attempt = record.attemptsMade + 1
       if (attempt >= record.attemptsMax) {
@@ -471,6 +528,22 @@ export const make = <StoreId = JobStore>(
             ? { _tag: "Fail", exit: exitValue }
             : routeFailure(record, exitValue)
           yield* ackSafely(store.ack(record.id, token, outcome), "ack")
+          if (outcome._tag === "Fail" || outcome._tag === "Retry") {
+            const cause = Exit.isFailure(effective)
+              ? effective.cause
+              : Cause.die(
+                new Error(`effect-mq: success value for job "${record.name}" could not be encoded`)
+              )
+            yield* reportFailure({
+              jobId: record.id,
+              name: record.name,
+              queue: record.queue,
+              attempt: context.attempt,
+              attemptsMax: record.attemptsMax,
+              willRetry: outcome._tag === "Retry",
+              cause
+            }, outcome._tag === "Retry" ? outcome.delayMs : undefined)
+          }
           yield* recordRun(
             outcome._tag === "Complete"
               ? "completed"
@@ -627,6 +700,25 @@ export const make = <StoreId = JobStore>(
           )
         }
         yield* Effect.logWarning("effect-mq: recovered stalled jobs", recovered)
+        // Stall exhaustion lands jobs in terminal `failed` without an ack, so
+        // report those here like any other terminal failure (whichever
+        // worker's sweep recovered them reports them, exactly once).
+        for (const entry of recovered) {
+          if (!entry.failed) continue
+          const job = yield* retryStore(store.getJob(entry.id))
+          if (Option.isNone(job)) continue
+          yield* reportFailure({
+            jobId: job.value.id,
+            name: job.value.name,
+            queue: job.value.queue,
+            attempt: job.value.attemptsMade + 1,
+            attemptsMax: job.value.attemptsMax,
+            willRetry: false,
+            cause: Cause.die(
+              new Error(job.value.failedReason ?? "effect-mq: job stalled past maxStalledCount")
+            )
+          }, undefined)
+        }
       }
     }).pipe(
       Effect.catchCause((cause) => Effect.logError("effect-mq: stalled sweep failed", cause)),

package/src/drizzle-postgres/DrizzleJobStore.ts

@@ -136,6 +136,7 @@ type ScheduleRow = {
   readonly backoff: JobStore.BackoffPolicy | null
   readonly keep: JobStore.KeepPolicy | null
   readonly timeoutMs: number | string | null
+  readonly group: string | null
   readonly nextRunAt: Date
 }
 
@@ -153,6 +154,7 @@ const toSchedule = (row: ScheduleRow): JobStore.ScheduleRecord => ({
   backoff: row.backoff ?? undefined,
   keep: row.keep ?? undefined,
   timeoutMs: row.timeoutMs === null ? undefined : Number(row.timeoutMs),
+  group: row.group ?? undefined,
   nextRunAt: row.nextRunAt.getTime()
 })
 
@@ -1340,20 +1342,21 @@ export const make = (
       upsertSchedule: (schedule) =>
         db.execute(sql`
           INSERT INTO ${schedules} (key, job_name, queue, cron, tz, every_ms, payload, metadata,
-            priority, attempts_max, backoff, keep, timeout_ms, next_run_at)
+            priority, attempts_max, backoff, keep, timeout_ms, group_name, next_run_at)
           VALUES (${schedule.key}, ${schedule.jobName}, ${schedule.queue},
             ${schedule.cron ?? null}, ${schedule.tz ?? null}, ${schedule.everyMs ?? null},
             ${JSON.stringify(schedule.payload ?? null)}::jsonb, ${JSON.stringify(schedule.metadata)}::jsonb,
             ${schedule.priority}, ${schedule.attemptsMax},
             ${schedule.backoff === undefined ? null : JSON.stringify(schedule.backoff)}::jsonb,
             ${schedule.keep === undefined ? null : JSON.stringify(schedule.keep)}::jsonb,
-            ${schedule.timeoutMs ?? null}, ${new Date(schedule.nextRunAt)})
+            ${schedule.timeoutMs ?? null}, ${schedule.group ?? null}, ${new Date(schedule.nextRunAt)})
           ON CONFLICT (key) DO UPDATE SET
             job_name = EXCLUDED.job_name, queue = EXCLUDED.queue, cron = EXCLUDED.cron,
             tz = EXCLUDED.tz, every_ms = EXCLUDED.every_ms, payload = EXCLUDED.payload,
             metadata = EXCLUDED.metadata, priority = EXCLUDED.priority,
             attempts_max = EXCLUDED.attempts_max, backoff = EXCLUDED.backoff,
             keep = EXCLUDED.keep, timeout_ms = EXCLUDED.timeout_ms,
+            group_name = EXCLUDED.group_name,
             next_run_at = CASE
               WHEN ${schedules.cron} IS NOT DISTINCT FROM EXCLUDED.cron
                 AND ${schedules.tz} IS NOT DISTINCT FROM EXCLUDED.tz
@@ -1383,6 +1386,9 @@ export const make = (
           if (listOptions?.queue !== undefined) {
             conditions.push(sql`${schedules.queue} = ${listOptions.queue}`)
           }
+          if (listOptions?.group !== undefined) {
+            conditions.push(sql`${schedules.group} = ${listOptions.group}`)
+          }
           const rows = rowsOf(yield* db.execute<ScheduleRow>(sql`
             SELECT ${schedules.key} AS "key", ${schedules.jobName} AS "jobName",
               ${schedules.queue} AS "queue", ${schedules.cron} AS "cron", ${schedules.tz} AS "tz",
@@ -1390,7 +1396,7 @@ export const make = (
               ${schedules.metadata} AS "metadata", ${schedules.priority} AS "priority",
               ${schedules.attemptsMax} AS "attemptsMax", ${schedules.backoff} AS "backoff",
               ${schedules.keep} AS "keep", ${schedules.timeoutMs} AS "timeoutMs",
-              ${schedules.nextRunAt} AS "nextRunAt"
+              ${schedules.group} AS "group", ${schedules.nextRunAt} AS "nextRunAt"
             FROM ${schedules}
             WHERE ${sql.join(conditions, sql` AND `)}
             ORDER BY ${schedules.key}
@@ -1408,7 +1414,7 @@ export const make = (
               ${schedules.metadata} AS "metadata", ${schedules.priority} AS "priority",
               ${schedules.attemptsMax} AS "attemptsMax", ${schedules.backoff} AS "backoff",
               ${schedules.keep} AS "keep", ${schedules.timeoutMs} AS "timeoutMs",
-              ${schedules.nextRunAt} AS "nextRunAt"
+              ${schedules.group} AS "group", ${schedules.nextRunAt} AS "nextRunAt"
             FROM ${schedules}
             WHERE ${schedules.nextRunAt} <= ${now}
             ORDER BY ${schedules.nextRunAt} ASC

package/src/drizzle-postgres/schema.ts

@@ -201,6 +201,8 @@ const schedulesColumns = <JobName extends string, Queue extends string>() => ({
   backoff: jsonb("backoff").$type<BackoffPolicy>(),
   keep: jsonb("keep").$type<KeepPolicy>(),
   timeoutMs: bigint("timeout_ms", { mode: "number" }),
+  /** Ownership label for declarative reconciliation; NULL = never pruned. */
+  group: text("group_name"),
   nextRunAt: timestamp("next_run_at", { withTimezone: true, mode: "date" }).notNull()
 })
 

package/src/index.ts

@@ -11,6 +11,14 @@
  */
 export * as Job from "./Job.ts"
 
+/**
+ * Declarative schedule reconciliation: declare a service's full schedule
+ * set as a layer; startup upserts it and detects deletion drift.
+ *
+ * @since 0.5.0
+ */
+export * as JobSchedules from "./JobSchedules.ts"
+
 /**
  * The storage seam: the `JobStore` service, job records and typed errors.
  *

package/src/redis/RedisJobStore.ts

@@ -107,6 +107,7 @@ const toSchedule = (hash: ReadonlyMap<string, string>): JobStore.ScheduleRecord
   backoff: optionalJson<JobStore.BackoffPolicy>(hash.get("backoff")),
   keep: optionalJson<JobStore.KeepPolicy>(hash.get("keep")),
   timeoutMs: optionalNumber(hash.get("timeoutMs")),
+  group: optionalString(hash.get("group")),
   nextRunAt: Number(hash.get("nextRunAt") ?? 0)
 })
 
@@ -746,6 +747,7 @@ export const make = (
           schedule.backoff === undefined ? "" : JSON.stringify(schedule.backoff),
           schedule.keep === undefined ? "" : JSON.stringify(schedule.keep),
           schedule.timeoutMs === undefined ? "" : String(schedule.timeoutMs),
+          schedule.group ?? "",
           schedule.nextRunAt
         ).pipe(
           Effect.mapError(storeError("upsertSchedule failed")),

package/src/redis/scripts.ts

@@ -833,6 +833,7 @@ export const upsertSchedule = Redis.script(
     backoffJson: string,
     keepJson: string,
     timeoutMs: string,
+    group: string,
     nextRunAt: number
   ) => [
     prefix,
@@ -849,6 +850,7 @@ export const upsertSchedule = Redis.script(
     backoffJson,
     keepJson,
     timeoutMs,
+    group,
     nextRunAt
   ],
   {
@@ -856,7 +858,7 @@ export const upsertSchedule = Redis.script(
     lua: `${HELPERS}
 local key = ARGV[2]
 local sk = prefix .. ":schedule:" .. key
-local nextRunAt = tonumber(ARGV[15])
+local nextRunAt = tonumber(ARGV[16])
 local prevCron = redis.call("HGET", sk, "cron")
 if prevCron ~= false
   and prevCron == ARGV[5]
@@ -872,7 +874,7 @@ redis.call("HSET", sk,
   "payload", ARGV[8], "metadata", ARGV[9],
   "priority", ARGV[10], "attemptsMax", ARGV[11],
   "backoff", ARGV[12], "keep", ARGV[13], "timeoutMs", ARGV[14],
-  "nextRunAt", fmt(nextRunAt))
+  "group", ARGV[15], "nextRunAt", fmt(nextRunAt))
 redis.call("ZADD", prefix .. ":schedules", nextRunAt, key)
 return '{"ok":true}'
 `
@@ -908,6 +910,7 @@ for _, key in ipairs(keys) do
   local matches = true
   if filters.jobName ~= nil and byName.jobName ~= filters.jobName then matches = false end
   if matches and filters.queue ~= nil and byName.queue ~= filters.queue then matches = false end
+  if matches and filters.group ~= nil and byName.group ~= filters.group then matches = false end
   if matches then out[#out + 1] = record end
 end
 if #out == 0 then return "[]" end