When a running Perpetual task gets externally replaced (e.g. config change
triggers `docket.replace()`), two executions of the same key run concurrently.
Both call `Perpetual.on_complete()` → `docket.replace()` when they finish,
and the last one to complete wins unconditionally — potentially overwriting
a correctly-timed successor with stale timing data.

The race looks like this:

  1. Task A (interval=2s) is running
  2. User changes config, calls docket.replace() for immediate re-execution
  3. Task B (interval=500ms) starts and finishes first
  4. B's on_complete schedules successor at now+500ms ✓
  5. A finishes, A's on_complete schedules successor at now+2s ✗
  6. The correctly-timed successor from B is gone

The fix adds a generation counter to the scheduling system. Every call to
`schedule()` atomically increments a generation field in the runs hash
(via HINCRBY in the Lua script). Each stream message carries the generation
it was scheduled with. This gives us two layers of protection:

- **Head check** (worker, before claim): If a stale message arrives from
  the stream (redelivery after crash, pending message from a partition),
  the worker detects it's superseded and skips entirely — no claim, no
  function invocation, no state changes to the runs hash.

- **Tail check** (Perpetual.on_complete, after execution): If a task was
  already running when the replacement happened, its on_complete detects
  supersession and skips the stale reschedule. The function body ran
  (unavoidable since it was mid-execution) but the damage is contained.

Backwards compatible: old messages without generation get gen=0, HINCRBY
on a missing field creates it at 0 then increments, so first new schedule
is gen=1. Cron inherits the fix automatically through super().on_complete().

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Co-Authored-By: Claude Opus 4.6 <[email protected]>

…ments

Generation 0 (the default when a message lacks the field) is now treated
as "pre-tracking" and never considered superseded. This handles the case
where an older worker's scheduler moves a task from queue to stream
without passing through the generation field — the new worker would
otherwise see gen=0 in the message vs gen=1 in the runs hash and
incorrectly drop the task.

Two new tests cover the upgrade paths:
- Old→New: message with no generation field runs normally
- New→Old scheduler→New worker: generation mismatch is tolerated

Co-Authored-By: Claude Opus 4.6 <[email protected]>

…ce()

The generation counter closes a broader gap than just Perpetual: when
replace() runs XDEL on a stream message that a worker already read via
XREADGROUP, the head check (before claim) skips the stale message.

The test puts both gen=1 and gen=2 messages in the stream to simulate
the XREADGROUP-before-XDEL race, and verifies only gen=2 executes.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

The generation check was a separate HGET before claim(), adding a Redis
round-trip to every task execution. Since claim() already hits the same
runs hash in a Lua script, the supersession check now happens atomically
inside it — zero additional cost on the hot path.

claim() returns False if the task was superseded, True if claimed.
is_superseded() is kept for the tail check in Perpetual.on_complete().

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Replace for/if/break loop with next() to avoid untaken branches that
some Python versions flag as partial coverage.

Co-Authored-By: Claude Opus 4.6 <[email protected]>