Replace Bun cron parser with portable implementation

[aashahin]

Summary

This PR replaces the runtime-dependent Bun cron parser with a portable, self-contained cron expression parser and next/previous occurrence engine. The new implementation works across all runtimes (Bun, Cloudflare, Node.js) without external dependencies, while maintaining full cron expression compatibility and improving reliability.

Key Changes

Cron Parser Implementation

• Replaced Bun.cron.parse dependency with a custom parser that handles:

  • Standard 5-field cron expressions (minute, hour, DOM, month, DOW)
  • Optional 6-field format with seconds
  • Named months (JAN-DEC) and days (SUN-SAT)
  • Lists, ranges, and step values (e.g., */15, 10-50/20)
  • Proper DOM/DOW OR-ing semantics when both are restricted
  • Month boundary and leap-year handling

• Added next/previous occurrence computation with:

  • Timezone-aware date arithmetic using UTC getters/setters on a "cron-parser frame"
  • Strict monotonic progression (each next occurrence is strictly greater than the previous)
  • Efficient backward iteration for collecting multiple past occurrences

Missed-Run Policy Improvements

• Extracted selectDueOccurrences() function to cleanly apply missed-run policies:

  • "skip" (default): only dispatch if the most recent occurrence is within maxDelayMs (default 1 hour)
  • "catch-up-latest": always dispatch the most recent missed occurrence
  • "catch-up-all": dispatch all collected occurrences in chronological order

• Added maxDelayMs field to cron definitions for fine-grained control over stale run handling

Runtime Improvements

• Bun runtime:

  • Removed registerOsCron() (unsupported on Bun); throws clear error if mode: "os" is configured
  • Added graceful shutdown: stop() now waits for in-flight drain to settle before returning
  • Improved error isolation: cron dispatch failures no longer abort remaining due runs in a tick
  • Added stopping flag to prevent new work during shutdown

• Cloudflare runtime:

  • Deterministic envelope normalization using instanceId and timestamp from Cloudflare event
  • Wrapped ctx.dispatch() calls in uniquely-named steps for proper memoization across replays
  • Added wrapNonRetryable() to translate SDK non-retryable markers to Cloudflare's NonRetryableError
  • Improved error handling in status endpoint: transient binding failures return controlled 502 instead of crashing

Adapter Enhancements

• Redis adapter: Added configurable retention policies for terminal instances and dead letters
• SQLite adapter: Added retention configuration with opportunistic pruning in recoverStalled()
• HTTP adapters: Added instance name caching with LRU eviction to prevent unbounded memory growth
• All adapters: Improved error handling and validation

Testing & Documentation

• Comprehensive cron parser tests covering edge cases (leap years, month boundaries, DOM/DOW OR-ing, etc.)
• New runtime.test.ts for durationToMs() and dispatch client derivation
• New retry.test.ts for backoff delay computation with jitter
• Updated Cloudflare tests for deterministic envelope normalization and dispatch memoization
• Updated README with runtime support clarification (Bun native, bundler-based TypeScript toolchains)

Configuration & Build

• Updated tsconfig.json to standalone configuration (removed extends, explicit compiler options)
• Updated package.json to exclude test files from published package

Notable Implementation Details

• Timezone handling: All cron arithmetic runs on a "cron-parser frame" where UTC getters/setters represent wall-clock time in the target timezone, ensuring consistency regardless of host timezone
• Backward iteration: getPreviousCronDates() efficiently collects multiple past occurrences by

https://claude.ai/code/session_01FkcHw1PpJfVDU3VSFfGcCU