← Back to list
01Issue
FeatureOpenSwamp CLIPublic
AssigneesNone
Relationships
#4360 Docs: schedule catch-up and missed-fire tracking for scheduled workflows
Opened by zack · 11/3/2026
Shipping in swamp-club/swamp#3593 (swamp-club#4237): scheduled workflows can opt in to catching up a fire missed while serve was down, and serve records every missed fire. The manual does not cover it yet.
Pages to update:
content/manual/how-to/run-workflows-on-a-schedule.md
- Add a Catch up a missed fire section with the trigger.catchUp example (policy none or latest; maxDelay required with latest, at most 31d).
- Explain that serve fires only the most recent missed slot, once, if it is within maxDelay; it never replays a backlog, and a paused schedule is not caught up.
- The run carries the tags swamp.trigger.catchUp and swamp.trigger.scheduledFor, so a workflow can decline a catch-up by reading run.tags.
- Add a Missed fires section explaining lastMissed: reasons serve_down, paused and overlap; count adds up for lost fires in a row with the same reason; the next fire that starts a run clears it; a cron change drops it.
- The first start after an upgrade only starts tracking, so nothing is caught up then.
content/manual/reference/workflows.md
- Document trigger.catchUp in the trigger schema: fields, the requirement that schedule is set, the 31d cap, and the two run tags.
content/manual/reference/swamp-serve.md
- The serve.yaml triggers override accepts catchUp, and an override with catchUp must also set schedule.
- swamp workflow trigger set gains --catch-up none|latest and --catch-up-max-delay, and replaces the whole override.
- /api/v1/health schedules gain catchUp and lastMissed (fireTime, count, saturated, reason, caughtUp, detectedAt).
- The audit log records workflow.schedule.missed, and workflow.schedule.fire carries catchUp=true for a catch-up.
Behaviour notes for the docs:
- The catch-up pass runs on the leader after pending runs replay, and again when a follower is promoted.
- It reads run history only when a catch-up would fire, under one 5s budget per pass.
02Bog Flow
Open
No activity in this phase yet.
03Sludge Pulse
Sign in to post a ripple.