Summary

Adds ctx.reschedule({ delay, at }) for handler-initiated continuation — the poll-until-done pattern (Replicate predictions, OpenAI batch jobs, Mux transcodes, etc.). Inside a handler, calling reschedule(...) records intent for after the run; on successful return the row transitions running → pending with the new scheduledFor instead of running → completed.

dk.handle("check-replicate", async ({ key, reschedule }) => {
  const p = await replicate.predictions.get(key);
  if (terminal(p.status)) return;
  reschedule({ delay: "2m" });
});

What changed

• Store.rescheduleJob(id, version, scheduledFor) — new store primitive backing the API. running → pending CAS, attempt resets to 0, clears prior-run error state and scheduler_ref, bumps version so stale wakes lose CAS. Memory + Postgres + SQLite + Postgres concurrency tests.
• ctx.reschedule({ delay | at }) — synchronous void method on HandlerContext. Last call wins; throwing discards intent. Validates the same way as dk.schedule (parsable duration, valid Date, capped at 10 years). Currently scoped to kind="once" jobs — pattern handlers throw (their requeue happens via wait/maxWait). New handler_rescheduled execution result + result-handler branch.
• job:rescheduled event — fires per rescheduled cycle with scheduledFor and durationMs. Distinct from job:scheduled so observers counting fresh schedules don't overcount poll cycles.
• dk.schedule returns a discriminated union — { created: true; job } or { created: false; job; skippedReason } where skippedReason is "pending", "running", or "race_lost". Existing destructuring ({ job, created }) keeps working. The new field nudges callers toward ctx.reschedule when they hit the "running" case (the silent self-rescheduling footgun). Exported as ScheduleResult and SkippedReason.

Why

The website's poll-until-done pattern showed dk.schedule(...) being called from inside a handler, but dk.schedule is idempotent — it skips when an active row exists, including the row currently being executed by the handler. So the pattern was silently broken. Adding ctx.reschedule is the right primitive (the row is being rescheduled, not duplicated), and the discriminated-union return on dk.schedule surfaces the footgun in the moment.

Test plan

• npm run typecheck
• npm test — 604 passed (16 new in test/reschedule.test.ts, 4 new in test/delaykit.test.ts)
• npm run test:postgres — 156 passed (1 new concurrency test, 4 new contract tests)
• Smoke test the example flow manually against a Posthook deployment
• Update the website's poll-until-done pattern in delaykit-website/lib/patterns.ts:582 to use ctx.reschedule({ delay: "2m" }) after this lands in npm

Notes

• Pre-existing latent bug: Store.retryJob has the same shape as rescheduleJob (running → pending CAS) but does not bump version. By the same argument used here for rescheduleJob (stale wakes from the prior run cycle should lose CAS), retryJob arguably should bump too. Not changed in this PR — separate concern.
• Website example fix is intentionally left to a follow-up PR on the website repo so the npm release lands first.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Handlers can now reschedule jobs mid-execution via ctx.reschedule({ delay, at })
  • Enhanced schedule() method returns reason when duplicate jobs are skipped ("pending", "running", or "race_lost")
  • New job:rescheduled event for observability when handlers trigger reschedules

• Documentation

  • Added "Poll-until-done" pattern guide for managing long-running async workflows