cron: durable controls and stable occurrence replay

[acastellana]

What changed

• add in-place updates for mutable cron schedule settings
• stamp every delivery with restart-stable occurrence identity
• echo bounded request ids so asynchronous object callers can correlate replies
• report durable persistence for create, update, pause, resume, and delete
• retain failed delete tombstones until the terminal write can be retried successfully

Why

Product-owned recurring workflows need cron to remain a timing primitive while still knowing whether a scheduler control was accepted durably. They also need one logical occurrence id to survive retries and a scheduler crash.

Safety

Targets, payloads, origin, creator, and dedupe keys remain immutable during updates. Request ids add no authority. A retained delete tombstone is terminal and non-runnable.

Validation

• all 24 standalone check files pass via ./checks/run.sh
• focused crash-recovery, update, request-correlation, and persistence-degradation vectors included

Summary by CodeRabbit

• New Features

  • Added in-place cron job updates with schedule recalculation.
  • Added request correlation IDs to responses.
  • Added enriched delivery metadata, including occurrence IDs, scheduled times, and attempt numbers.
  • Added persistence-status reporting for cron operations.
  • Added crash recovery that preserves occurrence identity and retry details.

• Bug Fixes

  • Improved handling of failed deletions by retaining jobs for retry.
  • Prevented caller-supplied reserved delivery metadata from overriding system values.

• Documentation

  • Updated the README, changelog, and cron protocol documentation with the new behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 463c1e6b-2640-4d5d-a515-4927611aa48b

📥 Commits

Reviewing files that changed from the base of the PR and between 34816f0 and 6b5551d.

📒 Files selected for processing (11)

• .claude/skills/genswarms-cron-use/SKILL.md
• CHANGELOG.md
• README.md
• checks/cron_job_test.exs
• checks/cron_kinds_test.exs
• checks/cron_persistence_test.exs
• checks/cron_seeds_test.exs
• checks/cron_test.exs
• packages/cron/cron.ex
• packages/cron/job.ex
• packages/cron/store.ex

---

📝 Walkthrough

Walkthrough

The cron package adds in-place job updates, request correlation IDs, persistence-status responses, scheduler-owned delivery envelopes, deterministic retry metadata, and claimed-occurrence preservation during crash recovery. Documentation and tests cover the new protocol and behavior.

Changes

Cron scheduler changes

Layer / File(s)	Summary
Job mutation and persistence responses .claude/skills/genswarms-cron-use/SKILL.md, packages/cron/cron.ex, checks/cron_test.exs, checks/cron_kinds_test.exs, checks/cron_persistence_test.exs, CHANGELOG.md	The public protocol adds update, bounded request_id echoing, mutable job-field updates, and persistence-status responses. Tests cover schedule recalculation, rejected routing changes, degraded persistence, and retryable delete tombstones.
Occurrence envelopes and retry metadata packages/cron/cron.ex, checks/cron_test.exs, checks/cron_kinds_test.exs, .claude/skills/genswarms-cron-use/SKILL.md, README.md	Deliveries include scheduler-owned job, fire, timing, attempt, and instance metadata. Creator-supplied cron metadata is rejected. Tests verify stable fire_id values and increasing attempts across retries.
Crash recovery and claimed occurrence identity packages/cron/job.ex, packages/cron/cron.ex, packages/cron/store.ex, checks/cron_job_test.exs, checks/cron_seeds_test.exs	Recovery clears claimed_due for skipped occurrences and preserves it for coalesced and one-shot recovery. Reloaded running jobs retain the timestamp for deterministic replay. Tests cover persisted crash recovery and poisoned skip expressions.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CronScheduler
  participant GenswarmsCron
  participant CronStore
  participant Sink
  CronScheduler->>GenswarmsCron: recover or dispatch claimed occurrence
  GenswarmsCron->>CronStore: load claimed_due and job state
  CronStore-->>GenswarmsCron: persisted job state
  GenswarmsCron->>Sink: deliver cron envelope
  Sink-->>GenswarmsCron: delivery result
  GenswarmsCron->>Sink: retry with same fire_id and next attempt

Loading

Possibly related PRs

• genlayerlabs/genswarms-objects#1: Introduces the scheduler, claimed_due, misfire handling, and recurring-job behavior extended here.
• genlayerlabs/genswarms-objects#12: Adds the persistence-failure handling and tests extended by this change.
• genlayerlabs/genswarms-objects#18: Defines cron behaviors implemented here, including updates, persistence, recovery, and delivery envelopes.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/cron-job-updates

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[acastellana]

Released as v0.1.21 and swarmidx:genlayerlabs/cron@0.2.8. Verified package digest: sha256:4d461756b78353d6c407c2025be29d6a3a488bfe01236eba69fb3e57ec3f5328; SwarmIDX transparency log: #118.