effect-mq 0.2.0 → 0.3.0

package/src/drizzle-postgres/DrizzleJobStore.ts

@@ -18,11 +18,11 @@
  */
 import * as JobStore from "../JobStore.ts"
 import type { PgClient } from "@effect/sql-pg"
-import { asc, eq, sql } from "drizzle-orm"
+import { asc, eq, getTableColumns, sql } from "drizzle-orm"
 import * as PgDrizzle from "drizzle-orm/effect-postgres"
 import { getTableConfig } from "drizzle-orm/pg-core"
 import { Clock, type Context, Deferred, Duration, Effect, Layer, Option, type Scope, Stream } from "effect"
-import type { MqJobAttemptsTable, MqJobsTable, MqQueueControlTable, MqSchedulesTable } from "./schema.ts"
+import type { MqDedupeTable, MqJobAttemptsTable, MqJobsTable, MqQueueControlTable, MqSchedulesTable } from "./schema.ts"
 
 const { JobId } = JobStore
 
@@ -38,13 +38,26 @@ export interface DrizzleJobStoreOptions<StoreId = JobStore.JobStore> {
   readonly schedules: MqSchedulesTable
   /** The queue pause/resume flags table (from `mqQueueControl`). */
   readonly queues: MqQueueControlTable
+  /** The dedup-key registry table (from `mqDedupe`). */
+  readonly dedupe: MqDedupeTable
+  /**
+   * Values for columns added via `mqJobs({ extend })`, evaluated at enqueue
+   * (and on dedupe `replace`). Keys are the extended columns' TS names.
+   * Default: each extended column fills from `request.metadata[<TS name>]`,
+   * NULL when absent.
+   */
+  readonly extraValues?:
+    | ((request: JobStore.EnqueueRequest) => Readonly<Record<string, ExtraColumnValue>>)
+    | undefined
   /** Bind to a `JobStore.named(...)` key; default: the default `JobStore`. */
   readonly store?: Context.Key<StoreId, JobStore.Service> | undefined
   /**
    * Store-level retention ceiling: terminal records older than this are
-   * removed by a periodic sweep. Per-job `keep` may only be stricter.
+   * removed by a periodic sweep — one duration for all terminal states or a
+   * per-state split (`{ completed: "1 day", failed: "30 days" }`). The sweep
+   * also honours stricter per-job `keep.age` rules.
    */
-  readonly historyTtl?: Duration.Input | undefined
+  readonly historyTtl?: JobStore.HistoryTtlInput | undefined
   /** History sweep cadence (default 1 minute). */
   readonly historySweepInterval?: Duration.Input | undefined
   /**
@@ -61,6 +74,13 @@ export interface DrizzleJobStoreOptions<StoreId = JobStore.JobStore> {
 
 type Db = PgDrizzle.EffectPgDatabase & { readonly $client: PgClient.PgClient }
 
+/**
+ * A value the driver can bind directly into an extended column.
+ *
+ * @since 0.3.0
+ */
+export type ExtraColumnValue = string | number | boolean | Date | null
+
 const storeError = (message: string) => (cause: unknown) =>
   new JobStore.JobStoreError({ message, cause })
 
@@ -92,6 +112,7 @@ type JobRow = {
   readonly keep: JobStore.KeepPolicy | null
   readonly timeoutMs: number | string | null
   readonly cancelRequested: boolean
+  readonly dedupeKey: string | null
   readonly runAt: Date
   readonly enqueuedAt: Date
   readonly processedAt: Date | null
@@ -149,6 +170,7 @@ const toRecord = (row: JobRow): JobStore.JobRecord => ({
   keep: row.keep ?? undefined,
   timeoutMs: row.timeoutMs === null || row.timeoutMs === undefined ? undefined : Number(row.timeoutMs),
   cancelRequested: row.cancelRequested,
+  dedupeKey: row.dedupeKey ?? undefined,
   runAt: row.runAt.getTime(),
   enqueuedAt: row.enqueuedAt.getTime(),
   processedAt: row.processedAt?.getTime(),
@@ -173,16 +195,70 @@ export const make = (
     const attempts = options.attempts
     const schedules = options.schedules
     const queues = options.queues
+    const dedupe = options.dedupe
     const jobsName = getTableConfig(jobs).name
     const attemptsName = getTableConfig(attempts).name
     const wakeChannel = `effect_mq_wake_${jobsName}`
 
+    // Columns the user added via `mqJobs({ extend })`: everything beyond the
+    // factory's own set. They are written at enqueue (and on dedupe replace)
+    // from `extraValues` or the metadata entry with the same TS key.
+    const BASE_JOB_COLUMNS = new Set([
+      "id",
+      "name",
+      "queue",
+      "state",
+      "priority",
+      "seq",
+      "payload",
+      "metadata",
+      "attemptsMax",
+      "attemptsMade",
+      "stalledCount",
+      "backoff",
+      "keep",
+      "timeoutMs",
+      "cancelRequested",
+      "dedupeKey",
+      "runAt",
+      "enqueuedAt",
+      "processedAt",
+      "finishedAt",
+      "exit",
+      "failedReason",
+      "lockToken",
+      "lockExpiresAt"
+    ])
+    const extendedColumns = Object.entries(getTableColumns(jobs))
+      .filter(([key]) => !BASE_JOB_COLUMNS.has(key))
+      .map(([key, column]) => ({ key, name: column.name }))
+    const extraColumnNames = extendedColumns.length === 0
+      ? sql``
+      : sql.join(extendedColumns.map((column) => sql`, ${sql.identifier(column.name)}`))
+    const extraColumnValues = (request: JobStore.EnqueueRequest) => {
+      if (extendedColumns.length === 0) return sql``
+      const mapped = options.extraValues?.(request) ?? {}
+      return sql.join(extendedColumns.map((column) =>
+        sql`, ${Object.hasOwn(mapped, column.key) ? mapped[column.key] : request.metadata[column.key] ?? null}`
+      ))
+    }
+    const extraColumnAssignments = (request: JobStore.EnqueueRequest) => {
+      if (extendedColumns.length === 0) return sql``
+      const mapped = options.extraValues?.(request) ?? {}
+      return sql.join(extendedColumns.map((column) =>
+        sql`, ${sql.identifier(column.name)} = ${
+          Object.hasOwn(mapped, column.key) ? mapped[column.key] : request.metadata[column.key] ?? null
+        }`
+      ))
+    }
+
     if (options.validate ?? true) {
       yield* Effect.all([
         db.select({ id: jobs.id }).from(jobs).limit(0),
         db.select({ jobId: attempts.jobId }).from(attempts).limit(0),
         db.select({ key: schedules.key }).from(schedules).limit(0),
-        db.select({ queue: queues.queue }).from(queues).limit(0)
+        db.select({ queue: queues.queue }).from(queues).limit(0),
+        db.select({ key: dedupe.key }).from(dedupe).limit(0)
       ]).pipe(
         Effect.mapError(storeError(
           `effect-mq: tables "${jobsName}"/"${attemptsName}" are missing or mismatched — ` +
@@ -191,21 +267,48 @@ export const make = (
       )
     }
 
-    // Wake plumbing: a local version + deferred chain (same protocol as the
+    // Wake plumbing: a queue-filtered waiter registry (same protocol as the
     // memory driver), fed by (a) local store operations and (b) cross-process
-    // LISTEN notifications.
+    // LISTEN notifications whose payload names the queue ("*" broadcasts).
+    // Filtering matters at scale: without it every enqueue wakes every idle
+    // taker of every queue on the store.
     let wakeVersion = 0
-    let wake = Deferred.makeUnsafe<void>()
-    const signalWake = () => {
+    let lastBroadcast = 0
+    const lastWake = new Map<JobStore.QueueName, number>()
+    interface Waiter {
+      readonly queues: ReadonlySet<JobStore.QueueName>
+      readonly deferred: Deferred.Deferred<void>
+    }
+    const waiters = new Set<Waiter>()
+    const lastWakeFor = (queue: JobStore.QueueName) => Math.max(lastWake.get(queue) ?? 0, lastBroadcast)
+    const signalWake = (queue?: JobStore.QueueName) => {
       wakeVersion += 1
-      const current = wake
-      wake = Deferred.makeUnsafe<void>()
-      Deferred.doneUnsafe(current, Effect.void)
+      if (queue === undefined) {
+        lastBroadcast = wakeVersion
+      } else {
+        lastWake.set(queue, wakeVersion)
+      }
+      // Snapshot-and-clear BEFORE resolving: doneUnsafe resumes waiting
+      // fibers synchronously, and a woken taker that re-parks registers a
+      // NEW waiter — resolving inside the live Set iteration would visit it
+      // and livelock.
+      const toWake: Array<Waiter> = []
+      for (const waiter of waiters) {
+        if (queue === undefined || waiter.queues.has(queue)) {
+          waiters.delete(waiter)
+          toWake.push(waiter)
+        }
+      }
+      for (const waiter of toWake) {
+        Deferred.doneUnsafe(waiter.deferred, Effect.void)
+      }
     }
     // Resubscribe forever: if the LISTEN stream ends or fails, wake-ups
     // degrade to the worker's pollInterval until the next attempt succeeds.
     yield* client.listen(wakeChannel).pipe(
-      Stream.runForEach(() => Effect.sync(signalWake)),
+      Stream.runForEach((payload) =>
+        Effect.sync(() => signalWake(payload === "*" ? undefined : JobStore.QueueName(payload)))
+      ),
       Effect.catchCause((cause) =>
         Effect.logWarning(
           "effect-mq: LISTEN subscription failed; wake-ups degraded to polling until resubscribe",
@@ -217,15 +320,42 @@ export const make = (
       Effect.forkScoped
     )
     if (options.historyTtl !== undefined) {
-      const ttlMs = Duration.toMillis(options.historyTtl)
+      const ttlByState = JobStore.normalizeHistoryTtl(options.historyTtl)
       const sweepMs = Duration.toMillis(options.historySweepInterval ?? "1 minute")
       yield* Effect.gen(function*() {
         yield* Effect.sleep(sweepMs)
         const now = yield* nowDate
+        // Per-state ceilings, refined by stricter per-row keep ages — a quiet
+        // job name is pruned on the timer, not only when its group is acked.
+        for (const state of ["completed", "failed", "cancelled"] as const) {
+          const ttl = ttlByState[state]
+          yield* db.execute(sql`
+            DELETE FROM ${jobs}
+            WHERE ${jobs.state} = ${state} AND (
+              ${ttl !== undefined ? sql`${jobs.finishedAt} <= ${new Date(now.getTime() - ttl)}` : sql`FALSE`}
+              OR (
+                COALESCE(
+                  ${jobs.keep}->${state}->>'ageMs',
+                  CASE WHEN ${jobs.keep} ?| array['completed', 'failed', 'cancelled'] THEN NULL
+                    ELSE ${jobs.keep}->>'ageMs' END
+                ) IS NOT NULL
+                AND ${jobs.finishedAt} <= ${now}::timestamptz
+                  - make_interval(secs => (COALESCE(
+                      ${jobs.keep}->${state}->>'ageMs',
+                      CASE WHEN ${jobs.keep} ?| array['completed', 'failed', 'cancelled'] THEN NULL
+                        ELSE ${jobs.keep}->>'ageMs' END
+                    )::double precision) / 1000.0))
+            )
+          `)
+        }
+        // Dead dedup rows: expired windows, or pointers at vanished jobs.
         yield* db.execute(sql`
-          DELETE FROM ${jobs}
-          WHERE ${jobs.state} IN ('completed', 'failed', 'cancelled')
-            AND ${jobs.finishedAt} <= ${new Date(now.getTime() - ttlMs)}
+          DELETE FROM ${dedupe}
+          WHERE (${dedupe.windowExpiresAt} IS NOT NULL AND ${dedupe.windowExpiresAt} <= ${now})
+             OR (${dedupe.windowExpiresAt} IS NULL AND NOT EXISTS (
+               SELECT 1 FROM ${jobs} WHERE ${jobs.id} = ${dedupe.jobId}
+                 AND ${jobs.state} IN ('waiting', 'delayed', 'active')
+             ))
         `)
       }).pipe(
         Effect.catchCause((cause) => Effect.logWarning("effect-mq: history sweep failed", cause)),
@@ -235,12 +365,13 @@ export const make = (
     }
 
     // Local mutation wake-up: bump synchronously, then best-effort NOTIFY so
-    // workers in other processes wake promptly too.
-    const wakeUp: Effect.Effect<void> = Effect.suspend(() => {
-      signalWake()
-      // The payload must be non-empty: @effect/sql-pg drops falsy payloads.
-      return client.notify(wakeChannel, "1").pipe(Effect.ignore)
-    })
+    // workers in other processes wake promptly too. The payload names the
+    // queue (and must be non-empty: @effect/sql-pg drops falsy payloads).
+    const wakeUp = (queue?: JobStore.QueueName): Effect.Effect<void> =>
+      Effect.suspend(() => {
+        signalWake(queue)
+        return client.notify(wakeChannel, queue !== undefined && queue.length > 0 ? queue : "*").pipe(Effect.ignore)
+      })
 
     const nowDate = Effect.map(Clock.currentTimeMillis, (ms) => new Date(ms))
 
@@ -263,14 +394,39 @@ export const make = (
       `)
 
     // Retention: drop terminal peers (same name + state) beyond count/age.
+    const keepPolicyFor = (
+      keep: JobStore.KeepPolicy | null | undefined,
+      state: string
+    ): JobStore.KeepStatePolicy | undefined => {
+      if (keep === null || keep === undefined) return undefined
+      const policy = state === "completed"
+        ? keep.completed
+        : state === "failed"
+        ? keep.failed
+        : state === "cancelled"
+        ? keep.cancelled
+        : undefined
+      if (policy !== undefined) return policy
+      // Rows persisted by 0.2.x carry the flat {count, ageMs} shape — honour
+      // it as an all-states policy so upgrades keep pruning.
+      if (
+        keep.completed === undefined && keep.failed === undefined && keep.cancelled === undefined &&
+        ("count" in keep || "ageMs" in keep)
+      ) {
+        // SAFETY: the flat legacy shape carries KeepStatePolicy fields.
+        return keep as JobStore.KeepStatePolicy
+      }
+      return undefined
+    }
+
     const applyKeep = (
       tx: Pick<Db, "execute">,
       row: { name: string; state: string; keep: JobStore.KeepPolicy | null },
       now: Date
     ) =>
       Effect.gen(function*() {
-        const keep = row.keep
-        if (keep === null || keep === undefined) return
+        const keep = keepPolicyFor(row.keep, row.state)
+        if (keep === undefined) return
         if (keep.ageMs !== undefined) {
           yield* tx.execute(sql`
             DELETE FROM ${jobs}
@@ -307,53 +463,209 @@ export const make = (
         )
       )
 
-    const store: JobStore.Service = {
-      enqueue: (request) =>
+    // The shared INSERT: store-assigned ids come from the configured
+    // generator (or the seq sequence); loop on the (unlikely) collision with
+    // an existing id — ON CONFLICT DO NOTHING makes the retry safe. Returns
+    // the result or undefined when the caller-supplied id already exists.
+    const insertJob = (
+      exec: Pick<Db, "execute">,
+      request: JobStore.EnqueueRequest,
+      now: Date
+    ) =>
+      Effect.gen(function*() {
+        const runAt = new Date(now.getTime() + Math.max(0, request.delayMs))
+        const state = request.delayMs > 0 ? "delayed" : "waiting"
+        const generate = options.idGenerator
+        for (let i = 0; i < 5; i++) {
+          const generated = request.id === undefined && generate !== undefined
+            ? yield* Effect.suspend(() => {
+              const raw = generate(request)
+              return Effect.isEffect(raw) ? raw : Effect.succeed(raw)
+            })
+            : undefined
+          const idExpr = request.id !== undefined
+            ? sql`${request.id}`
+            : generated !== undefined
+            ? sql`${generated}`
+            : sql`'j-' || ${seqExpr}::text`
+          const rows = rowsOf(yield* exec.execute<{ id: string }>(sql`
+            INSERT INTO ${jobs} (id, name, queue, state, priority, payload, metadata,
+              attempts_max, backoff, keep, timeout_ms, dedupe_key, run_at, enqueued_at${extraColumnNames})
+            VALUES (${idExpr}, ${request.name}, ${request.queue}, ${state}, ${request.priority},
+              ${JSON.stringify(request.payload ?? null)}::jsonb, ${JSON.stringify(request.metadata)}::jsonb,
+              ${request.attemptsMax},
+              ${request.backoff === undefined ? null : JSON.stringify(request.backoff)}::jsonb,
+              ${request.keep === undefined ? null : JSON.stringify(request.keep)}::jsonb,
+              ${request.timeoutMs ?? null}, ${request.dedupe?.key ?? null}, ${runAt}, ${now}${extraColumnValues(request)})
+            ON CONFLICT (id) DO NOTHING
+            RETURNING ${jobs.id} AS id
+          `).pipe(Effect.mapError(storeError("enqueue failed"))))
+          const inserted = rows[0]
+          if (inserted !== undefined) {
+            return { id: JobId(inserted.id), duplicate: false }
+          }
+          if (request.id !== undefined) {
+            return { id: request.id, duplicate: true }
+          }
+          // generated id collided with an existing user id; try again
+        }
+        return yield* new JobStore.JobStoreError({
+          message: "enqueue failed: could not generate a unique job id"
+        })
+      })
+
+    // Enqueue with a dedup policy: one transaction locks the (name, key) row
+    // and applies the decision tree (replace-while-delayed, throttle window,
+    // pending dedup) before falling through to a fresh insert.
+    const enqueueDeduped = (request: JobStore.EnqueueRequest, policy: JobStore.DedupePolicy) =>
+      db.transaction((tx) =>
         Effect.gen(function*() {
           const now = yield* nowDate
-          const runAt = new Date(now.getTime() + Math.max(0, request.delayMs))
-          const state = request.delayMs > 0 ? "delayed" : "waiting"
-          // Store-assigned ids come from the configured generator (or the
-          // seq sequence); loop on the (unlikely) collision with an existing
-          // id — ON CONFLICT DO NOTHING makes the retry safe.
-          const generate = options.idGenerator
-          for (let i = 0; i < 5; i++) {
-            const generated = request.id === undefined && generate !== undefined
-              ? yield* Effect.suspend(() => {
-                const raw = generate(request)
-                return Effect.isEffect(raw) ? raw : Effect.succeed(raw)
-              })
-              : undefined
-            const idExpr = request.id !== undefined
-              ? sql`${request.id}`
-              : generated !== undefined
-              ? sql`${generated}`
-              : sql`'j-' || ${seqExpr}::text`
-            const rows = rowsOf(yield* db.execute<{ id: string }>(sql`
-              INSERT INTO ${jobs} (id, name, queue, state, priority, payload, metadata,
-                attempts_max, backoff, keep, timeout_ms, run_at, enqueued_at)
-              VALUES (${idExpr}, ${request.name}, ${request.queue}, ${state}, ${request.priority},
-                ${JSON.stringify(request.payload ?? null)}::jsonb, ${JSON.stringify(request.metadata)}::jsonb,
-                ${request.attemptsMax},
-                ${request.backoff === undefined ? null : JSON.stringify(request.backoff)}::jsonb,
-                ${request.keep === undefined ? null : JSON.stringify(request.keep)}::jsonb,
-                ${request.timeoutMs ?? null}, ${runAt}, ${now})
-              ON CONFLICT (id) DO NOTHING
-              RETURNING ${jobs.id} AS id
-            `).pipe(Effect.mapError(storeError("enqueue failed"))))
-            const inserted = rows[0]
-            if (inserted !== undefined) {
-              yield* wakeUp
-              return { id: JobId(inserted.id), duplicate: false }
+          // The explicit-id duplicate check precedes the dedup tree, matching
+          // the memory and redis drivers.
+          if (request.id !== undefined) {
+            const existing = rowsOf(yield* tx.execute<{ id: string }>(sql`
+              SELECT ${jobs.id} AS id FROM ${jobs} WHERE ${jobs.id} = ${request.id}
+            `))
+            if (existing.length > 0) {
+              return { id: request.id, duplicate: true, wake: false }
             }
-            if (request.id !== undefined) {
-              return { id: request.id, duplicate: true }
+          }
+          // A SELECT FOR UPDATE on a missing row locks nothing, so two
+          // concurrent first-enqueues would both insert. The no-op upsert
+          // always takes the row lock: a fresh placeholder (job_id = '')
+          // reads as "no entry" and falls through to the insert below.
+          const rows = rowsOf(yield* tx.execute<{ jobId: string; windowExpiresAt: Date | null }>(sql`
+            INSERT INTO ${dedupe} (name, key, job_id, window_expires_at)
+            VALUES (${request.name}, ${policy.key}, '', NULL)
+            ON CONFLICT (name, key) DO UPDATE SET name = EXCLUDED.name
+            RETURNING ${dedupe.jobId} AS "jobId", ${dedupe.windowExpiresAt} AS "windowExpiresAt"
+          `))
+          const entry = rows[0]
+          if (entry !== undefined && entry.jobId !== "") {
+            // Plain read (no FOR UPDATE): locking the job row here would
+            // invert the jobs-then-dedupe lock order every terminal
+            // transition uses and deadlock under load. The replace branch
+            // compensates with a state-conditional UPDATE.
+            const keyed = rowsOf(yield* tx.execute<{ state: JobStore.JobState }>(sql`
+              SELECT ${jobs.state} AS state FROM ${jobs} WHERE ${jobs.id} = ${entry.jobId}
+            `))
+            const keyedState = keyed[0]?.state
+            const windowLive = entry.windowExpiresAt !== null &&
+              entry.windowExpiresAt.getTime() > now.getTime()
+            const bumpWindow = policy.extend && policy.ttlMs !== undefined
+              ? tx.execute(sql`
+                UPDATE ${dedupe} SET window_expires_at = ${new Date(now.getTime() + policy.ttlMs)}
+                WHERE ${dedupe.name} = ${request.name} AND ${dedupe.key} = ${policy.key}
+              `).pipe(Effect.asVoid)
+              : Effect.void
+            // Latest-wins while the keyed job is still delayed. The UPDATE
+            // re-checks the state so a concurrent claim degrades this to a
+            // plain dedup instead of rewriting an active job.
+            if (policy.replace && keyedState === "delayed") {
+              const replaced = rowsOf(yield* tx.execute<{ id: string; queue: string }>(sql`
+                UPDATE ${jobs} SET
+                  payload = ${JSON.stringify(request.payload ?? null)}::jsonb,
+                  metadata = ${JSON.stringify(request.metadata)}::jsonb,
+                  priority = ${request.priority},
+                  attempts_max = ${request.attemptsMax},
+                  backoff = ${request.backoff === undefined ? null : JSON.stringify(request.backoff)}::jsonb,
+                  keep = ${request.keep === undefined ? null : JSON.stringify(request.keep)}::jsonb,
+                  timeout_ms = ${request.timeoutMs ?? null},
+                  run_at = ${new Date(now.getTime() + Math.max(0, request.delayMs))}${extraColumnAssignments(request)}
+                WHERE ${jobs.id} = ${entry.jobId} AND ${jobs.state} = 'delayed'
+                RETURNING ${jobs.id} AS id, ${jobs.queue} AS "queue"
+              `))
+              if (replaced.length > 0) {
+                // A landed replace re-arms the ttl window (the entry must
+                // outlive the chain it is deduplicating).
+                if (policy.ttlMs !== undefined) {
+                  yield* tx.execute(sql`
+                    UPDATE ${dedupe} SET window_expires_at = ${new Date(now.getTime() + policy.ttlMs)}
+                    WHERE ${dedupe.name} = ${request.name} AND ${dedupe.key} = ${policy.key}
+                  `)
+                }
+                // The replace does not move the job between queues — wake
+                // the queue that actually holds the now-rescheduled job.
+                return {
+                  id: JobId(entry.jobId),
+                  duplicate: true,
+                  wake: true,
+                  wakeQueue: JobStore.QueueName(replaced[0]?.queue ?? request.queue)
+                }
+              }
+              return { id: JobId(entry.jobId), duplicate: true, wake: false }
+            }
+            if (windowLive) {
+              yield* bumpWindow
+              return { id: JobId(entry.jobId), duplicate: true, wake: false }
+            }
+            const pending = keyedState !== undefined && keyedState !== "completed" &&
+              keyedState !== "failed" && keyedState !== "cancelled"
+            if (entry.windowExpiresAt === null && pending) {
+              return { id: JobId(entry.jobId), duplicate: true, wake: false }
             }
-            // generated id collided with an existing user id; try again
+            // Dead entry: the new job takes over the key below.
           }
-          return yield* new JobStore.JobStoreError({
-            message: "enqueue failed: could not generate a unique job id"
-          })
+          const result = yield* insertJob(tx, request, now)
+          if (!result.duplicate) {
+            yield* tx.execute(sql`
+              INSERT INTO ${dedupe} (name, key, job_id, window_expires_at)
+              VALUES (${request.name}, ${policy.key}, ${result.id},
+                ${policy.ttlMs === undefined ? null : new Date(now.getTime() + policy.ttlMs)})
+              ON CONFLICT (name, key) DO UPDATE SET
+                job_id = EXCLUDED.job_id, window_expires_at = EXCLUDED.window_expires_at
+            `)
+          }
+          return { ...result, wake: !result.duplicate }
+        })
+      ).pipe(
+        // Residual lock-order inversions (replace vs cancel of the same
+        // delayed job) surface as Postgres deadlocks (40P01); one side is
+        // killed and safe to retry.
+        Effect.retry({
+          times: 3,
+          while: (error) => String(error).includes("40P01") || String(error).includes("deadlock detected")
+        }),
+        Effect.mapError((error) =>
+          error instanceof JobStore.JobStoreError ? error : storeError("enqueue failed")(error)
+        )
+      )
+
+    // A job leaving the pending states frees its pending-mode dedup row; live
+    // throttle windows deliberately outlast the job.
+    const releaseDedupe = (
+      exec: Pick<Db, "execute">,
+      name: string,
+      dedupeKey: string | null,
+      jobId: string,
+      now: Date
+    ) =>
+      dedupeKey === null
+        ? Effect.void
+        : exec.execute(sql`
+          DELETE FROM ${dedupe}
+          WHERE ${dedupe.name} = ${name} AND ${dedupe.key} = ${dedupeKey}
+            AND ${dedupe.jobId} = ${jobId}
+            AND (${dedupe.windowExpiresAt} IS NULL OR ${dedupe.windowExpiresAt} <= ${now})
+        `).pipe(Effect.asVoid)
+
+    const store: JobStore.Service = {
+      enqueue: (request) =>
+        Effect.gen(function*() {
+          if (request.dedupe !== undefined) {
+            const result = yield* enqueueDeduped(request, request.dedupe)
+            if (result.wake) {
+              yield* wakeUp("wakeQueue" in result && result.wakeQueue !== undefined ? result.wakeQueue : request.queue)
+            }
+            return { id: result.id, duplicate: result.duplicate }
+          }
+          const now = yield* nowDate
+          const result = yield* insertJob(db, request, now)
+          if (!result.duplicate) {
+            yield* wakeUp(request.queue)
+          }
+          return result
         }),
 
       claim: (claimOptions) =>
@@ -396,7 +708,7 @@ export const make = (
                 ${jobs.attemptsMax} AS "attemptsMax", ${jobs.attemptsMade} AS "attemptsMade",
                 ${jobs.stalledCount} AS "stalledCount", ${jobs.backoff} AS "backoff",
                 ${jobs.keep} AS "keep", ${jobs.timeoutMs} AS "timeoutMs",
-                ${jobs.cancelRequested} AS "cancelRequested",
+                ${jobs.cancelRequested} AS "cancelRequested", ${jobs.dedupeKey} AS "dedupeKey",
                 ${jobs.runAt} AS "runAt", ${jobs.enqueuedAt} AS "enqueuedAt",
                 ${jobs.processedAt} AS "processedAt", ${jobs.finishedAt} AS "finishedAt",
                 ${jobs.exit} AS "exit", ${jobs.failedReason} AS "failedReason"
@@ -443,13 +755,21 @@ export const make = (
                   seq = CASE WHEN ${jobs.cancelRequested} THEN ${jobs.seq} ELSE ${seqExpr} END,
                   cancel_requested = FALSE`
             const rows = rowsOf(yield* tx.execute<
-              { processedAt: Date | null; name: string; state: string; keep: JobStore.KeepPolicy | null }
+              {
+                processedAt: Date | null
+                name: string
+                state: string
+                keep: JobStore.KeepPolicy | null
+                dedupeKey: string | null
+                queue: string
+              }
             >(sql`
               UPDATE ${jobs} SET ${update},
                 attempts_made = ${jobs.attemptsMade} + 1, lock_token = NULL, lock_expires_at = NULL
               WHERE ${jobs.id} = ${id} AND ${jobs.state} = 'active' AND ${jobs.lockToken} = ${token}
               RETURNING ${jobs.processedAt} AS "processedAt", ${jobs.name} AS "name",
-                ${jobs.state} AS "state", ${jobs.keep} AS "keep"
+                ${jobs.state} AS "state", ${jobs.keep} AS "keep", ${jobs.dedupeKey} AS "dedupeKey",
+                ${jobs.queue} AS "queue"
             `))
             const row = rows[0]
             if (row === undefined) {
@@ -472,8 +792,12 @@ export const make = (
               outcome._tag === "Cancelled" || cancelledRetry ? undefined : outcome.exit
             )
             if (outcome._tag !== "Retry" || cancelledRetry) {
+              yield* releaseDedupe(tx, row.name, row.dedupeKey, id, now)
               yield* applyKeep(tx, row, now)
             }
+            return outcome._tag === "Retry" && !cancelledRetry
+              ? JobStore.QueueName(row.queue)
+              : undefined
           })
         ).pipe(
           Effect.mapError((error) =>
@@ -482,12 +806,13 @@ export const make = (
               ? error
               : storeError("ack failed")(error)
           ),
-          Effect.tap(() => outcome._tag === "Retry" ? wakeUp : Effect.void)
+          Effect.tap((queue) => queue !== undefined ? wakeUp(queue) : Effect.void),
+          Effect.asVoid
         ),
 
       release: (id, token) =>
         Effect.gen(function*() {
-          const cancelled = yield* db.transaction((tx) =>
+          const released = yield* db.transaction((tx) =>
             Effect.gen(function*() {
               const now = yield* nowDate
               // A cancel that arrived while the worker was shutting down is
@@ -499,6 +824,8 @@ export const make = (
                   processedAt: Date | null
                   name: string
                   keep: JobStore.KeepPolicy | null
+                  dedupeKey: string | null
+                  queue: string
                 }
               >(sql`
                 UPDATE ${jobs} SET
@@ -508,24 +835,26 @@ export const make = (
                   lock_token = NULL, lock_expires_at = NULL
                 WHERE ${jobs.id} = ${id} AND ${jobs.state} = 'active' AND ${jobs.lockToken} = ${token}
                 RETURNING ${jobs.id} AS id, (${jobs.state} = 'cancelled') AS cancelled,
-                  ${jobs.processedAt} AS "processedAt", ${jobs.name} AS "name", ${jobs.keep} AS "keep"
+                  ${jobs.processedAt} AS "processedAt", ${jobs.name} AS "name", ${jobs.keep} AS "keep",
+                  ${jobs.dedupeKey} AS "dedupeKey", ${jobs.queue} AS "queue"
               `))
               const row = rows[0]
               if (row === undefined) return undefined
               if (row.cancelled) {
                 yield* insertAttempt(tx, id, "cancelled", row.processedAt, now, undefined)
+                yield* releaseDedupe(tx, row.name, row.dedupeKey, id, now)
                 yield* applyKeep(tx, { name: row.name, state: "cancelled", keep: row.keep }, now)
               }
-              return row.cancelled
+              return { cancelled: row.cancelled, queue: JobStore.QueueName(row.queue) }
             })
           ).pipe(Effect.mapError((error) =>
             error instanceof JobStore.JobStoreError ? error : storeError("release failed")(error)
           ))
-          if (cancelled === undefined) {
+          if (released === undefined) {
             return yield* explainMiss(id)
           }
-          if (!cancelled) {
-            yield* wakeUp
+          if (!released.cancelled) {
+            yield* wakeUp(released.queue)
           }
         }),
 
@@ -578,6 +907,7 @@ export const make = (
                 processedAt: Date | null
                 name: string
                 keep: JobStore.KeepPolicy | null
+                dedupeKey: string | null
               }
             >(sql`
               UPDATE ${jobs} SET
@@ -598,7 +928,7 @@ export const make = (
                 cancel_requested = FALSE
               WHERE ${jobs.state} = 'active' AND ${jobs.lockExpiresAt} <= ${now}::timestamptz
               RETURNING ${jobs.id} AS "id", ${jobs.state} AS "state", ${jobs.processedAt} AS "processedAt",
-                ${jobs.name} AS "name", ${jobs.keep} AS "keep"
+                ${jobs.name} AS "name", ${jobs.keep} AS "keep", ${jobs.dedupeKey} AS "dedupeKey"
             `))
             const recovered: Array<{ id: JobStore.JobId; failed: boolean }> = []
             for (const row of rows) {
@@ -610,6 +940,9 @@ export const make = (
                 now,
                 undefined
               )
+              if (row.state === "cancelled" || row.state === "failed") {
+                yield* releaseDedupe(tx, row.name, row.dedupeKey, row.id, now)
+              }
               if (row.state === "cancelled") {
                 yield* applyKeep(tx, { name: row.name, state: "cancelled", keep: row.keep }, now)
               } else {
@@ -623,14 +956,18 @@ export const make = (
             error instanceof JobStore.JobStoreError ? error : storeError("recoverStalled failed")(error)
           ),
           Effect.tap((recovered) =>
-            recovered.some((entry) => !entry.failed) ? wakeUp : Effect.void
+            recovered.some((entry) => !entry.failed) ? wakeUp() : Effect.void
           )
         ),
 
-      awaitWake: (_queues, wakeToken) =>
+      awaitWake: (queues, wakeToken) =>
         Effect.suspend(() => {
-          if (wakeVersion > wakeToken) return Effect.void
-          return Deferred.await(wake)
+          if (queues.some((queue) => lastWakeFor(queue) > wakeToken)) return Effect.void
+          const waiter: Waiter = { queues: new Set(queues), deferred: Deferred.makeUnsafe<void>() }
+          waiters.add(waiter)
+          return Deferred.await(waiter.deferred).pipe(
+            Effect.ensuring(Effect.sync(() => waiters.delete(waiter)))
+          )
         }),
 
       getJob: (id) =>
@@ -707,13 +1044,13 @@ export const make = (
       retry: (id) =>
         Effect.gen(function*() {
           const now = yield* nowDate
-          const rows = rowsOf(yield* db.execute<{ id: string }>(sql`
+          const rows = rowsOf(yield* db.execute<{ id: string; queue: string }>(sql`
             UPDATE ${jobs} SET state = 'waiting', attempts_made = 0, stalled_count = 0,
               cancel_requested = FALSE,
               exit = NULL, failed_reason = NULL, finished_at = NULL, processed_at = NULL,
               run_at = ${now}, seq = ${seqExpr}
             WHERE ${jobs.id} = ${id} AND ${jobs.state} = 'failed'
-            RETURNING ${jobs.id} AS id
+            RETURNING ${jobs.id} AS id, ${jobs.queue} AS "queue"
           `).pipe(Effect.mapError(storeError("retry failed"))))
           if (rows.length === 0) {
             const existing = yield* db.select({ state: jobs.state }).from(jobs)
@@ -724,7 +1061,7 @@ export const make = (
             }
             return yield* new JobStore.JobNotRetryableError({ jobId: id, state: found.state })
           }
-          yield* wakeUp
+          yield* wakeUp(JobStore.QueueName(rows[0]?.queue ?? ""))
         }),
 
       cancel: (id) =>
@@ -740,6 +1077,7 @@ export const make = (
                 processedAt: Date | null
                 name: string
                 keep: JobStore.KeepPolicy | null
+                dedupeKey: string | null
               }
             >(sql`
               UPDATE ${jobs} SET
@@ -748,7 +1086,8 @@ export const make = (
                 cancel_requested = CASE WHEN ${jobs.state} = 'active' THEN TRUE ELSE ${jobs.cancelRequested} END
               WHERE ${jobs.id} = ${id} AND ${jobs.state} IN ('waiting', 'delayed', 'active')
               RETURNING ${jobs.id} AS id, ${jobs.state} AS state,
-                ${jobs.processedAt} AS "processedAt", ${jobs.name} AS "name", ${jobs.keep} AS "keep"
+                ${jobs.processedAt} AS "processedAt", ${jobs.name} AS "name", ${jobs.keep} AS "keep",
+                ${jobs.dedupeKey} AS "dedupeKey"
             `))
             const row = rows[0]
             if (row === undefined) {
@@ -763,6 +1102,7 @@ export const make = (
             }
             if (row.state === "cancelled") {
               yield* insertAttempt(tx, id, "cancelled", row.processedAt, now, undefined)
+              yield* releaseDedupe(tx, row.name, row.dedupeKey, id, now)
               yield* applyKeep(tx, { name: row.name, state: "cancelled", keep: row.keep }, now)
             }
           })
@@ -780,10 +1120,10 @@ export const make = (
       promote: (id) =>
         Effect.gen(function*() {
           const now = yield* nowDate
-          const rows = rowsOf(yield* db.execute<{ id: string }>(sql`
+          const rows = rowsOf(yield* db.execute<{ id: string; queue: string }>(sql`
             UPDATE ${jobs} SET state = 'waiting', run_at = ${now}
             WHERE ${jobs.id} = ${id} AND ${jobs.state} = 'delayed'
-            RETURNING ${jobs.id} AS id
+            RETURNING ${jobs.id} AS id, ${jobs.queue} AS "queue"
           `).pipe(Effect.mapError(storeError("promote failed"))))
           if (rows.length === 0) {
             const existing = rowsOf(yield* db.execute<{ state: JobStore.JobState }>(sql`
@@ -795,7 +1135,7 @@ export const make = (
             }
             return yield* new JobStore.JobNotPromotableError({ jobId: id, state: found.state })
           }
-          yield* wakeUp
+          yield* wakeUp(JobStore.QueueName(rows[0]?.queue ?? ""))
         }),
 
       pause: (queue) =>
@@ -812,7 +1152,7 @@ export const make = (
           UPDATE ${queues} SET paused = FALSE WHERE ${queues.queue} = ${queue}
         `).pipe(
           Effect.mapError(storeError("resume failed")),
-          Effect.andThen(wakeUp)
+          Effect.andThen(wakeUp(queue))
         ),
 
       pausedQueues: () =>
@@ -848,7 +1188,7 @@ export const make = (
               ELSE EXCLUDED.next_run_at END
         `).pipe(
           Effect.mapError(storeError("upsertSchedule failed")),
-          Effect.asVoid
+          Effect.andThen(wakeUp(schedule.queue))
         ),
 
       removeSchedule: (key) =>