effect-mq 0.1.0 → 0.3.0

package/src/testing/conformance.ts

@@ -35,6 +35,8 @@ const baseRequest = (
   attemptsMax: 1,
   backoff: undefined,
   keep: undefined,
+  timeoutMs: undefined,
+  dedupe: undefined,
   delayMs: 0,
   ...overrides
 })
@@ -320,11 +322,12 @@ export const jobStoreConformance = (
           )
           assert(claim._tag === "Claimed")
 
-          const lost = yield* store.extendLocks(
+          const result = yield* store.extendLocks(
             [{ id, token: "t-1" }, { id: JobId("ghost"), token: "t-9" }],
             20_000
           )
-          expect(lost).toEqual(["ghost"])
+          expect(result.lost).toEqual(["ghost"])
+          expect(result.cancelRequested).toEqual([])
 
           // The extension outlives the original lock duration.
           yield* TestClock.adjust(15_000)
@@ -470,7 +473,7 @@ export const jobStoreConformance = (
         Effect.gen(function*() {
           for (let i = 0; i < 4; i++) {
             const { id } = yield* store.enqueue(
-              baseRequest({ payload: { n: i }, keep: { count: 2, ageMs: undefined } })
+              baseRequest({ payload: { n: i }, keep: { completed: { count: 2, ageMs: undefined } } })
             )
             const claim = yield* store.claim(claimOptions({ token: `t-${i}` }))
             assert(claim._tag === "Claimed")
@@ -486,7 +489,7 @@ export const jobStoreConformance = (
     it.effect("keep age prunes terminal records older than the window", () =>
       withStore((store) =>
         Effect.gen(function*() {
-          const keep = { count: undefined, ageMs: 10_000 }
+          const keep = { completed: { count: undefined, ageMs: 10_000 } }
           const first = yield* store.enqueue(baseRequest({ payload: { n: 1 }, keep }))
           const claim1 = yield* store.claim(claimOptions())
           assert(claim1._tag === "Claimed")
@@ -541,10 +544,10 @@ export const jobStoreConformance = (
           // Two jobs acked at the SAME TestClock instant: the tie must break
           // on enqueue/seq order identically in every driver.
           const first = yield* store.enqueue(
-            baseRequest({ payload: { n: 1 }, keep: { count: 1, ageMs: undefined } })
+            baseRequest({ payload: { n: 1 }, keep: { completed: { count: 1, ageMs: undefined } } })
           )
           const second = yield* store.enqueue(
-            baseRequest({ payload: { n: 2 }, keep: { count: 1, ageMs: undefined } })
+            baseRequest({ payload: { n: 2 }, keep: { completed: { count: 1, ageMs: undefined } } })
           )
           const claimA = yield* store.claim(claimOptions({ token: "t-a" }))
           const claimB = yield* store.claim(claimOptions({ token: "t-b" }))
@@ -560,7 +563,7 @@ export const jobStoreConformance = (
     it.effect("keep applies count and age together", () =>
       withStore((store) =>
         Effect.gen(function*() {
-          const keep = { count: 2, ageMs: 10_000 }
+          const keep = { completed: { count: 2, ageMs: 10_000 } }
           const ids: Array<JobStore.JobId> = []
           for (let i = 0; i < 3; i++) {
             const { id } = yield* store.enqueue(baseRequest({ payload: { n: i }, keep }))
@@ -620,7 +623,8 @@ export const jobStoreConformance = (
             delayed: 1,
             active: 1,
             completed: 0,
-            failed: 0
+            failed: 0,
+            cancelled: 0
           })
           const other = yield* store.counts(QueueName("other"))
           expect(other.waiting).toBe(1)
@@ -650,5 +654,658 @@ export const jobStoreConformance = (
           expect(yield* store.getAttempts(JobId("nope"))).toEqual([])
         })
       ))
+
+    it.effect("cancel makes waiting and delayed jobs terminal with a ledger entry", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const waiting = yield* store.enqueue(baseRequest())
+          const delayed = yield* store.enqueue(baseRequest({ delayMs: 60_000 }))
+          yield* store.cancel(waiting.id)
+          yield* store.cancel(delayed.id)
+
+          for (const id of [waiting.id, delayed.id]) {
+            const job = yield* store.getJob(id)
+            assert(Option.isSome(job))
+            expect(job.value.state).toBe("cancelled")
+            expect(job.value.finishedAt).toBeDefined()
+            const attempts = yield* store.getAttempts(id)
+            expect(attempts.map((attempt) => attempt.outcome)).toEqual(["cancelled"])
+          }
+          const claim = yield* store.claim(claimOptions())
+          assert(claim._tag === "Empty")
+
+          // Terminal jobs cannot be cancelled again; unknown ids are reported.
+          const again = yield* Effect.flip(store.cancel(waiting.id))
+          expect(again._tag).toBe("JobNotCancellableError")
+          const missing = yield* Effect.flip(store.cancel(JobId("nope")))
+          expect(missing._tag).toBe("JobNotFoundError")
+        })
+      ))
+
+    it.effect("cancel on an active job flags it; the heartbeat reports it; ack Cancelled finishes it", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const { id } = yield* store.enqueue(baseRequest())
+          const claim = yield* store.claim(claimOptions())
+          assert(claim._tag === "Claimed")
+
+          yield* store.cancel(id)
+          const flagged = yield* store.getJob(id)
+          assert(Option.isSome(flagged))
+          expect(flagged.value.state).toBe("active")
+          expect(flagged.value.cancelRequested).toBe(true)
+
+          // The heartbeat surfaces the request instead of extending the lock.
+          const heartbeat = yield* store.extendLocks([{ id, token: "t-1" }], 20_000)
+          expect(heartbeat.cancelRequested).toEqual([id])
+          expect(heartbeat.lost).toEqual([])
+
+          yield* store.ack(id, "t-1", { _tag: "Cancelled" })
+          const done = yield* store.getJob(id)
+          assert(Option.isSome(done))
+          expect(done.value.state).toBe("cancelled")
+          expect(done.value.cancelRequested).toBe(false)
+          const attempts = yield* store.getAttempts(id)
+          expect(attempts.map((attempt) => attempt.outcome)).toEqual(["cancelled"])
+        })
+      ))
+
+    it.effect("release and stall recovery honour a pending cancel request", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          // release path
+          const first = yield* store.enqueue(baseRequest())
+          const claimA = yield* store.claim(claimOptions())
+          assert(claimA._tag === "Claimed")
+          yield* store.cancel(first.id)
+          yield* store.release(first.id, "t-1")
+          const released = yield* store.getJob(first.id)
+          assert(Option.isSome(released))
+          expect(released.value.state).toBe("cancelled")
+
+          // stall path
+          const second = yield* store.enqueue(baseRequest({ payload: { n: 2 } }))
+          const claimB = yield* store.claim(claimOptions({ token: "t-2", lockDurationMs: 1_000 }))
+          assert(claimB._tag === "Claimed")
+          yield* store.cancel(second.id)
+          yield* TestClock.adjust(1_000)
+          const recovered = yield* store.recoverStalled({ maxStalledCount: 5 })
+          // Cancelled-by-recovery jobs are not reported as stalled recoveries.
+          expect(recovered).toEqual([])
+          const swept = yield* store.getJob(second.id)
+          assert(Option.isSome(swept))
+          expect(swept.value.state).toBe("cancelled")
+        })
+      ))
+
+    it.effect("promote runs a delayed job now and rejects other states", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const { id } = yield* store.enqueue(baseRequest({ delayMs: 60_000 }))
+          const early = yield* store.claim(claimOptions())
+          assert(early._tag === "Empty")
+
+          yield* store.promote(id)
+          const claim = yield* store.claim(claimOptions({ token: "t-2" }))
+          assert(claim._tag === "Claimed")
+          expect(claim.job.id).toBe(id)
+
+          const wrongState = yield* Effect.flip(store.promote(id))
+          expect(wrongState._tag).toBe("JobNotPromotableError")
+          const missing = yield* Effect.flip(store.promote(JobId("nope")))
+          expect(missing._tag).toBe("JobNotFoundError")
+        })
+      ))
+
+    it.effect("pause stops claims for a queue until resume", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          yield* store.enqueue(baseRequest())
+          yield* store.pause(QueueName("default"))
+          expect(yield* store.pausedQueues()).toEqual(["default"])
+
+          const paused = yield* store.claim(claimOptions())
+          assert(paused._tag === "Empty")
+
+          // Other queues are unaffected.
+          yield* store.enqueue(baseRequest({ queue: QueueName("other") }))
+          const other = yield* store.claim(claimOptions({ queue: QueueName("other"), token: "t-2" }))
+          assert(other._tag === "Claimed")
+
+          // Resume wakes idle workers and claims flow again.
+          const empty = yield* store.claim(claimOptions({ token: "t-3" }))
+          assert(empty._tag === "Empty")
+          const waiter = yield* Effect.forkChild(
+            store.awaitWake([QueueName("default")], empty.wakeToken)
+          )
+          yield* Effect.yieldNow
+          yield* store.resume(QueueName("default"))
+          yield* Fiber.join(waiter)
+          expect(yield* store.pausedQueues()).toEqual([])
+          const resumed = yield* store.claim(claimOptions({ token: "t-4" }))
+          assert(resumed._tag === "Claimed")
+        })
+      ))
+
+    it.effect("schedules: upsert, list, due, conditional advance, remove", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const schedule: JobStore.ScheduleRecord = {
+            key: JobStore.ScheduleKey("TestJob/hourly"),
+            jobName: "TestJob",
+            queue: QueueName("default"),
+            cron: "0 * * * *",
+            tz: undefined,
+            everyMs: undefined,
+            payload: { n: 1 },
+            metadata: { source: "conformance" },
+            priority: 2,
+            attemptsMax: 3,
+            backoff: { _tag: "fixed", delayMs: 1_000 },
+            keep: undefined,
+            timeoutMs: 5_000,
+            nextRunAt: 60_000
+          }
+          yield* store.upsertSchedule(schedule)
+          expect(yield* store.listSchedules()).toEqual([schedule])
+          expect(yield* store.listSchedules({ jobName: "OtherJob" })).toEqual([])
+
+          // Not due yet (TestClock starts at 0).
+          expect(yield* store.dueSchedules()).toEqual([])
+          yield* TestClock.adjust(60_000)
+          expect(yield* store.dueSchedules()).toEqual([schedule])
+
+          // Upsert replaces in place.
+          yield* store.upsertSchedule({ ...schedule, priority: 9 })
+          expect((yield* store.listSchedules())[0]?.priority).toBe(9)
+
+          // Conditional advance: a stale expectation is a no-op.
+          yield* store.advanceSchedule(schedule.key, 999, 120_000)
+          expect((yield* store.listSchedules())[0]?.nextRunAt).toBe(60_000)
+          yield* store.advanceSchedule(schedule.key, 60_000, 120_000)
+          expect((yield* store.listSchedules())[0]?.nextRunAt).toBe(120_000)
+          expect(yield* store.dueSchedules()).toEqual([])
+
+          expect(yield* store.removeSchedule(schedule.key)).toBe(true)
+          expect(yield* store.removeSchedule(schedule.key)).toBe(false)
+          expect(yield* store.listSchedules()).toEqual([])
+        })
+      ))
+
+    it.effect("completion wins over a pending cancel request", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const { id } = yield* store.enqueue(baseRequest())
+          const claim = yield* store.claim(claimOptions())
+          assert(claim._tag === "Claimed")
+          yield* store.cancel(id)
+
+          yield* store.ack(id, "t-1", { _tag: "Complete", exit: { ok: true } })
+          const job = yield* store.getJob(id)
+          assert(Option.isSome(job))
+          expect(job.value.state).toBe("completed")
+          expect(job.value.cancelRequested).toBe(false)
+        })
+      ))
+
+    it.effect("a natural failure racing a cancel is cancelled, not revived", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const { id } = yield* store.enqueue(baseRequest({ attemptsMax: 5 }))
+          const claim = yield* store.claim(claimOptions())
+          assert(claim._tag === "Claimed")
+          yield* store.cancel(id)
+
+          // The handler failed on its own before the heartbeat could
+          // interrupt it; the retry ack must honour the pending cancel.
+          yield* store.ack(id, "t-1", { _tag: "Retry", exit: { boom: 1 }, delayMs: 1_000 })
+          const job = yield* store.getJob(id)
+          assert(Option.isSome(job))
+          expect(job.value.state).toBe("cancelled")
+          expect(job.value.cancelRequested).toBe(false)
+          const attempts = yield* store.getAttempts(id)
+          expect(attempts.map((attempt) => attempt.outcome)).toEqual(["cancelled"])
+          const nothing = yield* store.claim(claimOptions({ token: "t-2" }))
+          assert(nothing._tag === "Empty")
+        })
+      ))
+
+    it.effect("ack Cancelled with a wrong token fails with LockLostError", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const { id } = yield* store.enqueue(baseRequest())
+          const claim = yield* store.claim(claimOptions())
+          assert(claim._tag === "Claimed")
+          yield* store.cancel(id)
+
+          const wrong = yield* Effect.flip(store.ack(id, "not-mine", { _tag: "Cancelled" }))
+          expect(wrong._tag).toBe("LockLostError")
+          const job = yield* store.getJob(id)
+          assert(Option.isSome(job))
+          expect(job.value.state).toBe("active")
+          expect(job.value.cancelRequested).toBe(true)
+        })
+      ))
+
+    it.effect("cancel applies the keep retention policy", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const keep = { cancelled: { count: 1 } }
+          const ids: Array<JobStore.JobId> = []
+          for (let i = 0; i < 3; i++) {
+            const { id } = yield* store.enqueue(baseRequest({ payload: { n: i }, keep }))
+            ids.push(id)
+            yield* store.cancel(id)
+            yield* TestClock.adjust(10)
+          }
+          const listed = yield* store.list({ states: ["cancelled"] })
+          expect(listed.items).toHaveLength(1)
+          expect(listed.items[0]?.id).toBe(ids[2])
+        })
+      ))
+
+    it.effect("upserting an unchanged cadence preserves the next occurrence; a changed one resets it", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const base: JobStore.ScheduleRecord = {
+            key: JobStore.ScheduleKey("TestJob/pulse"),
+            jobName: "TestJob",
+            queue: QueueName("default"),
+            cron: undefined,
+            tz: undefined,
+            everyMs: 60_000,
+            payload: {},
+            metadata: {},
+            priority: 0,
+            attemptsMax: 1,
+            backoff: undefined,
+            keep: undefined,
+            timeoutMs: undefined,
+            nextRunAt: 60_000
+          }
+          yield* store.upsertSchedule(base)
+
+          // A deploy-time re-registration recomputes nextRunAt from "now" —
+          // the store must keep the original grid point.
+          yield* TestClock.adjust(30_000)
+          yield* store.upsertSchedule({ ...base, priority: 5, nextRunAt: 90_000 })
+          const preserved = (yield* store.listSchedules())[0]
+          expect(preserved?.nextRunAt).toBe(60_000)
+          expect(preserved?.priority).toBe(5)
+
+          // Changing the cadence takes the caller's fresh nextRunAt.
+          yield* store.upsertSchedule({ ...base, everyMs: 120_000, nextRunAt: 150_000 })
+          expect((yield* store.listSchedules())[0]?.nextRunAt).toBe(150_000)
+        })
+      ))
+
+    it.effect("schedule records round-trip every/tz fields; due order is by nextRunAt; list filters by queue", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const everySchedule: JobStore.ScheduleRecord = {
+            key: JobStore.ScheduleKey("TestJob/every"),
+            jobName: "TestJob",
+            queue: QueueName("default"),
+            cron: undefined,
+            tz: undefined,
+            everyMs: 90_000,
+            payload: { n: 1 },
+            metadata: {},
+            priority: 0,
+            attemptsMax: 1,
+            backoff: undefined,
+            keep: undefined,
+            timeoutMs: undefined,
+            nextRunAt: 90_000
+          }
+          const cronSchedule: JobStore.ScheduleRecord = {
+            ...everySchedule,
+            key: JobStore.ScheduleKey("TestJob/tz"),
+            queue: QueueName("other"),
+            cron: "0 9 * * *",
+            tz: "America/New_York",
+            everyMs: undefined,
+            nextRunAt: 30_000
+          }
+          yield* store.upsertSchedule(everySchedule)
+          yield* store.upsertSchedule(cronSchedule)
+
+          const byQueue = yield* store.listSchedules({ queue: QueueName("other") })
+          expect(byQueue).toEqual([cronSchedule])
+          expect(byQueue[0]?.tz).toBe("America/New_York")
+          const roundTripped = (yield* store.listSchedules({ queue: QueueName("default") }))[0]
+          expect(roundTripped?.everyMs).toBe(90_000)
+
+          // Both due: ordered by nextRunAt ascending.
+          yield* TestClock.adjust(90_000)
+          const due = yield* store.dueSchedules()
+          expect(due.map((schedule) => schedule.key)).toEqual([
+            "TestJob/tz",
+            "TestJob/every"
+          ])
+        })
+      ))
+
+    it.effect("counts stay consistent across cancel, retry, keep pruning, and remove", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          // Three completions with keep {count: 1}: two get pruned.
+          for (let i = 0; i < 3; i++) {
+            const { id } = yield* store.enqueue(baseRequest({ payload: { n: i }, keep: { completed: { count: 1 } } }))
+            const claim = yield* store.claim(claimOptions({ token: `t-${i}` }))
+            assert(claim._tag === "Claimed")
+            yield* store.ack(id, `t-${i}`, { _tag: "Complete", exit: undefined })
+            yield* TestClock.adjust(10)
+          }
+          expect((yield* store.counts()).completed).toBe(1)
+
+          // Cancel a waiting job.
+          const doomed = yield* store.enqueue(baseRequest({ name: "Doomed" }))
+          yield* store.cancel(doomed.id)
+          expect((yield* store.counts()).cancelled).toBe(1)
+
+          // Fail a job, then admin-retry it: failed -> waiting.
+          const flaky = yield* store.enqueue(baseRequest())
+          const claim = yield* store.claim(claimOptions({ token: "t-f" }))
+          assert(claim._tag === "Claimed")
+          yield* store.ack(flaky.id, "t-f", { _tag: "Fail", exit: undefined })
+          expect((yield* store.counts()).failed).toBe(1)
+          yield* store.retry(flaky.id)
+
+          // Remove the surviving completed record.
+          const completed = yield* store.list({ states: ["completed"] })
+          const survivor = completed.items[0]
+          assert(survivor !== undefined)
+          expect(yield* store.remove(survivor.id)).toBe(true)
+
+          expect(yield* store.counts()).toEqual({
+            waiting: 1,
+            delayed: 0,
+            active: 0,
+            completed: 0,
+            failed: 0,
+            cancelled: 1
+          })
+        })
+      ))
+
+    it.effect("schedule payloads round-trip high-precision numbers and empty arrays exactly", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const payload = { big: 1234567890123456, third: 1 / 3, empty: [] }
+          const schedule: JobStore.ScheduleRecord = {
+            key: JobStore.ScheduleKey("TestJob/precise"),
+            jobName: "TestJob",
+            queue: QueueName("default"),
+            cron: undefined,
+            tz: undefined,
+            everyMs: 60_000,
+            payload,
+            metadata: {},
+            priority: 0,
+            attemptsMax: 1,
+            backoff: undefined,
+            keep: undefined,
+            timeoutMs: undefined,
+            nextRunAt: 60_000
+          }
+          yield* store.upsertSchedule(schedule)
+          const stored = (yield* store.listSchedules())[0]
+          expect(stored?.payload).toEqual(payload)
+        })
+      ))
+
+    it.effect("dedupe never changes the job id, and keys are scoped per name", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const dedupe = { key: "emp-1", ttlMs: undefined, extend: false, replace: false }
+          const first = yield* store.enqueue(baseRequest({ id: JobId("my-ulid-1"), dedupe }))
+          expect(first).toEqual({ id: "my-ulid-1", duplicate: false })
+          const job = yield* store.getJob(first.id)
+          assert(Option.isSome(job))
+          expect(job.value.dedupeKey).toBe("emp-1")
+
+          // Same key, same name: deduplicated to the FIRST job's id.
+          const second = yield* store.enqueue(baseRequest({ id: JobId("my-ulid-2"), dedupe }))
+          expect(second).toEqual({ id: "my-ulid-1", duplicate: true })
+          expect(Option.isNone(yield* store.getJob(JobId("my-ulid-2")))).toBe(true)
+
+          // Same key, different name: no interference.
+          const other = yield* store.enqueue(baseRequest({ name: "OtherJob", dedupe }))
+          expect(other.duplicate).toBe(false)
+        })
+      ))
+
+    it.effect("pending dedupe holds while the keyed job is unfinished and frees on completion", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const dedupe = { key: "k", ttlMs: undefined, extend: false, replace: false }
+          const first = yield* store.enqueue(baseRequest({ dedupe }))
+          expect((yield* store.enqueue(baseRequest({ dedupe }))).duplicate).toBe(true)
+
+          // Still deduped while active.
+          const claim = yield* store.claim(claimOptions())
+          assert(claim._tag === "Claimed")
+          expect((yield* store.enqueue(baseRequest({ dedupe }))).duplicate).toBe(true)
+
+          // A terminal ack frees the key immediately.
+          yield* store.ack(first.id, "t-1", { _tag: "Complete", exit: undefined })
+          const fresh = yield* store.enqueue(baseRequest({ dedupe }))
+          expect(fresh.duplicate).toBe(false)
+          expect(fresh.id).not.toBe(first.id)
+        })
+      ))
+
+    it.effect("cancellation also frees a pending dedupe key", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const dedupe = { key: "k", ttlMs: undefined, extend: false, replace: false }
+          const first = yield* store.enqueue(baseRequest({ dedupe }))
+          yield* store.cancel(first.id)
+          expect((yield* store.enqueue(baseRequest({ dedupe }))).duplicate).toBe(false)
+        })
+      ))
+
+    it.effect("a ttl dedupe window throttles even past completion, then expires", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const dedupe = { key: "k", ttlMs: 60_000, extend: false, replace: false }
+          const first = yield* store.enqueue(baseRequest({ dedupe }))
+          const claim = yield* store.claim(claimOptions())
+          assert(claim._tag === "Claimed")
+          yield* store.ack(first.id, "t-1", { _tag: "Complete", exit: undefined })
+
+          // Completed, but the window still throttles...
+          yield* TestClock.adjust(30_000)
+          expect((yield* store.enqueue(baseRequest({ dedupe }))).duplicate).toBe(true)
+
+          // ...and a plain (non-extend) window is NOT pushed out by drops.
+          yield* TestClock.adjust(30_000)
+          const fresh = yield* store.enqueue(baseRequest({ dedupe }))
+          expect(fresh.duplicate).toBe(false)
+          expect(fresh.id).not.toBe(first.id)
+        })
+      ))
+
+    it.effect("an extend dedupe window is pushed out by each deduplicated enqueue", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const dedupe = { key: "k", ttlMs: 60_000, extend: true, replace: false }
+          yield* store.enqueue(baseRequest({ dedupe }))
+
+          yield* TestClock.adjust(45_000)
+          expect((yield* store.enqueue(baseRequest({ dedupe }))).duplicate).toBe(true)
+
+          // 75s after the FIRST enqueue — past the original window, inside
+          // the extended one.
+          yield* TestClock.adjust(30_000)
+          expect((yield* store.enqueue(baseRequest({ dedupe }))).duplicate).toBe(true)
+
+          // Past the latest extension: free again.
+          yield* TestClock.adjust(60_001)
+          expect((yield* store.enqueue(baseRequest({ dedupe }))).duplicate).toBe(false)
+        })
+      ))
+
+    it.effect("replace dedupe rewrites a still-delayed job in place, latest content wins", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const dedupe = { key: "k", ttlMs: undefined, extend: false, replace: true }
+          const first = yield* store.enqueue(
+            baseRequest({ dedupe, payload: { n: 1 }, priority: 1, delayMs: 60_000 })
+          )
+
+          const replaced = yield* store.enqueue(
+            baseRequest({ dedupe, payload: { n: 2 }, priority: 7, delayMs: 5_000 })
+          )
+          expect(replaced).toEqual({ id: first.id, duplicate: true })
+          const job = yield* store.getJob(first.id)
+          assert(Option.isSome(job))
+          expect(job.value.payload).toEqual({ n: 2 })
+          expect(job.value.priority).toBe(7)
+          expect(job.value.state).toBe("delayed")
+
+          // The rewritten delay is live: due after 5s, not the original 60s.
+          yield* TestClock.adjust(5_000)
+          const claim = yield* store.claim(claimOptions())
+          assert(claim._tag === "Claimed")
+          expect(claim.job.id).toBe(first.id)
+          expect(claim.job.payload).toEqual({ n: 2 })
+
+          // Once claimed (active), replace degrades to plain dedup.
+          const during = yield* store.enqueue(baseRequest({ dedupe, payload: { n: 3 } }))
+          expect(during).toEqual({ id: first.id, duplicate: true })
+          const active = yield* store.getJob(first.id)
+          assert(Option.isSome(active))
+          expect(active.value.payload).toEqual({ n: 2 })
+        })
+      ))
+
+    it.effect("an existing explicit id wins over the dedup tree in every driver", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const key = { key: "k", ttlMs: undefined, extend: false, replace: false }
+          // X runs under key k and completes, freeing the key but staying in
+          // history.
+          const x = yield* store.enqueue(baseRequest({ id: JobId("X"), dedupe: key }))
+          const claim = yield* store.claim(claimOptions())
+          assert(claim._tag === "Claimed")
+          yield* store.ack(x.id, "t-1", { _tag: "Complete", exit: undefined })
+
+          // J takes over the key, delayed.
+          const j = yield* store.enqueue(
+            baseRequest({ dedupe: key, payload: { n: 9 }, delayMs: 60_000 })
+          )
+
+          // A retried enqueue of X (id exists) must return X untouched — the
+          // id check precedes the dedup tree, so J is neither returned nor
+          // replaced.
+          const retried = yield* store.enqueue(baseRequest({
+            id: JobId("X"),
+            payload: { n: 1 },
+            dedupe: { ...key, replace: true }
+          }))
+          expect(retried).toEqual({ id: "X", duplicate: true })
+          const job = yield* store.getJob(j.id)
+          assert(Option.isSome(job))
+          expect(job.value.payload).toEqual({ n: 9 })
+          expect(job.value.state).toBe("delayed")
+        })
+      ))
+
+    it.effect("a landed replace re-arms the ttl window", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const dedupe = { key: "k", ttlMs: 60_000, extend: false, replace: true }
+          const first = yield* store.enqueue(baseRequest({ dedupe, delayMs: 300_000 }))
+
+          // 50s in: replace lands; the window restarts from here.
+          yield* TestClock.adjust(50_000)
+          const replaced = yield* store.enqueue(
+            baseRequest({ dedupe, payload: { n: 2 }, delayMs: 300_000 })
+          )
+          expect(replaced).toEqual({ id: first.id, duplicate: true })
+
+          // 100s after the FIRST enqueue — past the original window, inside
+          // the re-armed one: still the same job.
+          yield* TestClock.adjust(50_000)
+          const again = yield* store.enqueue(
+            baseRequest({ dedupe, payload: { n: 3 }, delayMs: 300_000 })
+          )
+          expect(again).toEqual({ id: first.id, duplicate: true })
+        })
+      ))
+
+    it.effect("keep policies are independent per terminal state", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          // Completed records keep only the newest 1; failed keep everything.
+          const keep = { completed: { count: 1 } }
+          const completed: Array<JobStore.JobId> = []
+          const failed: Array<JobStore.JobId> = []
+          for (let i = 0; i < 2; i++) {
+            const done = yield* store.enqueue(baseRequest({ payload: { n: i }, keep }))
+            const claimA = yield* store.claim(claimOptions({ token: `tc-${i}` }))
+            assert(claimA._tag === "Claimed")
+            yield* store.ack(done.id, `tc-${i}`, { _tag: "Complete", exit: undefined })
+            completed.push(done.id)
+
+            const bad = yield* store.enqueue(baseRequest({ payload: { n: 10 + i }, keep }))
+            const claimB = yield* store.claim(claimOptions({ token: `tf-${i}` }))
+            assert(claimB._tag === "Claimed")
+            yield* store.ack(bad.id, `tf-${i}`, { _tag: "Fail", exit: undefined })
+            failed.push(bad.id)
+            yield* TestClock.adjust(10)
+          }
+          const counts = yield* store.counts()
+          expect(counts.completed).toBe(1)
+          expect(counts.failed).toBe(2)
+          expect(Option.isNone(yield* store.getJob(completed[0] ?? JobId("?")))).toBe(true)
+          expect(Option.isSome(yield* store.getJob(failed[0] ?? JobId("?")))).toBe(true)
+        })
+      ))
+
+    it.effect("an enqueue wakes only waiters watching its queue", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const empty = yield* store.claim(claimOptions())
+          assert(empty._tag === "Empty")
+
+          let woke = false
+          const waiter = yield* Effect.forkChild(
+            store.awaitWake([QueueName("default")], empty.wakeToken).pipe(
+              Effect.tap(() => Effect.sync(() => void (woke = true)))
+            )
+          )
+          yield* Effect.yieldNow
+
+          // Work on ANOTHER queue must not wake the default-queue waiter.
+          yield* store.enqueue(baseRequest({ queue: QueueName("other") }))
+          for (let i = 0; i < 10; i++) {
+            yield* Effect.yieldNow
+          }
+          expect(woke).toBe(false)
+
+          // Matching-queue work does.
+          yield* store.enqueue(baseRequest())
+          yield* Fiber.join(waiter)
+          expect(woke).toBe(true)
+        })
+      ))
+
+    it.effect("delayed jobs still promote to waiting while their queue is paused", () =>
+      withStore((store) =>
+        Effect.gen(function*() {
+          const { id } = yield* store.enqueue(baseRequest({ delayMs: 1_000 }))
+          yield* store.pause(QueueName("default"))
+          yield* TestClock.adjust(1_000)
+
+          const claim = yield* store.claim(claimOptions())
+          assert(claim._tag === "Empty")
+          const job = yield* store.getJob(id)
+          assert(Option.isSome(job))
+          expect(job.value.state).toBe("waiting")
+        })
+      ))
   })
 }