docs: archive the cron v0.1 design spec - #18
Conversation
…eview) Rescued from the local-only genswarms-cron design repo (never pushed); the implementation shipped as packages/cron. Kept outside packages/cron/ so the published package digest stays code-only.
📝 WalkthroughWalkthroughAdds a Draft v2 design specification for ChangesCron Scheduler Design
Estimated code review effort: 3 (Moderate) | ~20 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/2026-07-02-genswarms-cron-design.md`:
- Around line 525-527: Update the `gsp publish` example in the release
instructions to reference the immutable `v0.1.0` tag or a specific commit SHA
instead of `@main`, while keeping the published version and endpoint unchanged.
- Around line 517-523: Update the swarmidx.json registry entry for
genswarms-cron to publish the actual code directory at packages/cron/ instead of
the repository root, preserving the code-only package digest and avoiding
reliance on publisher exclusion rules.
- Around line 344-352: Expand the authorize_run contract to define the state and
accounting effects for :ok, {:skip, reason}, {:pause, reason}, and {:cancel,
reason}, including occurrence advancement, missed/failure counters, audit or
LogStore events, notifications, and whether the job remains active, becomes
paused, completes, or is deleted. Keep the existing :pause behavior consistent
while documenting the outcomes for every result.
- Around line 90-91: Define a single canonical representation for the misfire
and overlap settings across configuration and job handling. Normalize configured
atom values at the configuration boundary to the string values consumed by the
job’s persisted-value matching, and apply the same normalization to all
documented examples, including the additional affected section. Ensure
unsupported values remain rejected rather than silently taking the default
behavior.
- Around line 335-339: Update the coalescing path in the cron job scheduling
logic around the functions covering lines 219–316 so the persisted scheduled
occurrence advances to the latest missed occurrence before dispatch, matching
the documented coalesced catch-up fire_id. Preserve :skip behavior and update
any related test vectors or contract assertions only if needed to verify the
latest occurrence is used.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: e35a297a-f76f-4c7f-9210-17f0bbcfc0a1
📒 Files selected for processing (1)
docs/2026-07-02-genswarms-cron-design.md
| misfire, # :coalesce (default) | :skip | ||
| overlap, # :skip (default; singleton per job) | :allow |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Define one canonical representation for misfire and overlap.
The spec/config uses atoms such as :skip and :coalesce, while packages/cron/job.ex:219-316 pattern-matches persisted values such as "skip". If configuration reaches the job unchanged, :skip silently behaves as coalesce. Document and enforce normalization at the boundary, or align the implementation and configuration types.
Also applies to: 461-462
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/2026-07-02-genswarms-cron-design.md` around lines 90 - 91, Define a
single canonical representation for the misfire and overlap settings across
configuration and job handling. Normalize configured atom values at the
configuration boundary to the string values consumed by the job’s
persisted-value matching, and apply the same normalization to all documented
examples, including the additional affected section. Ensure unsupported values
remain rejected rather than silently taking the default behavior.
| - **Misfire (`:coalesce` default):** occurrences missed while the scheduler | ||
| was down collapse into ONE catch-up run whose `fire_id` is the latest missed | ||
| occurrence; then normal future scheduling resumes. `:skip` advances to the | ||
| next future occurrence and counts the missed ones. Never fire-all. The same | ||
| policy applies on `resume` and on approval of stale pending jobs (§5). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Align coalescing semantics with the documented fire_id.
The spec says a coalesced catch-up uses the latest missed occurrence, but packages/cron/job.ex:219-316 leaves the old next_run_at in place for coalescing. That produces the earliest persisted due point instead. Either advance the scheduled occurrence before dispatch or change the contract and test vectors to define which missed occurrence is used.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/2026-07-02-genswarms-cron-design.md` around lines 335 - 339, Update the
coalescing path in the cron job scheduling logic around the functions covering
lines 219–316 so the persisted scheduled occurrence advances to the latest
missed occurrence before dispatch, matching the documented coalesced catch-up
fire_id. Preserve :skip behavior and update any related test vectors or contract
assertions only if needed to verify the latest occurrence is used.
| - **Fire-time authorization (deferred authority):** | ||
|
|
||
| ```elixir | ||
| authorize_run: fn job, envelope -> :ok | {:skip, reason} | {:pause, reason} | {:cancel, reason} end | ||
| ``` | ||
|
|
||
| Called before every dispatch. The host re-checks whatever "still allowed" | ||
| means to it (membership, consent, budget). `{:pause, "budget"}` parks the | ||
| job instead of burning attempts. Default: always `:ok`. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Specify the state and accounting effects of every authorize_run result.
The contract defines :skip and :cancel but only explains :pause. Clarify whether each result advances the occurrence, increments missed or failures, emits audit/LogStore events, sends notifications, and leaves the job active, paused, done, or deleted.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/2026-07-02-genswarms-cron-design.md` around lines 344 - 352, Expand the
authorize_run contract to define the state and accounting effects for :ok,
{:skip, reason}, {:pause, reason}, and {:cancel, reason}, including occurrence
advancement, missed/failure counters, audit or LogStore events, notifications,
and whether the job remains active, becomes paused, completes, or is deleted.
Keep the existing :pause behavior consistent while documenting the outcomes for
every result.
| `swarmidx.json` at repo root: | ||
|
|
||
| ```json | ||
| {"registry": {"scope": "acastellana"}, | ||
| "packages": [{"name": "genswarms-cron", "dir": ".", "kind": "handler", | ||
| "description": "Deterministic scheduler object for GenSwarms swarms"}]} | ||
| ``` |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Publish the actual package directory, not the repository root.
With "dir": ".", the publication may include docs/2026-07-02-genswarms-cron-design.md, contradicting the objective that the package digest remains code-only. Point the registry entry at packages/cron/ or explicitly configure the publisher’s exclusion rules.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/2026-07-02-genswarms-cron-design.md` around lines 517 - 523, Update the
swarmidx.json registry entry for genswarms-cron to publish the actual code
directory at packages/cron/ instead of the repository root, preserving the
code-only package digest and avoiding reliance on publisher exclusion rules.
| Tag `v0.1.0` → `gsp publish swarmidx.json --version 0.1.0 | ||
| --source github://genlayerlabs/genswarms-cron@main` against | ||
| `SWARMIDX_ENDPOINT=https://swarmidx.ygr.ai`. Consumers: |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Publish from the immutable release tag or commit.
The instructions create v0.1.0 but then publish from @main, so later changes to main can produce a different artifact under the same version. Use the release tag (for example, @v0.1.0) or an immutable commit SHA.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~527-~527: The official name of this software platform is spelled with a capital “H”.
Context: ...NT=https://swarmidx.ygr.ai`. Consumers: `{:genswarms_cron, github: "genlayerlabs/genswarms-cron", tag: "v...
(GITHUB)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/2026-07-02-genswarms-cron-design.md` around lines 525 - 527, Update the
`gsp publish` example in the release instructions to reference the immutable
`v0.1.0` tag or a specific commit SHA instead of `@main`, while keeping the
published version and endpoint unchanged.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0e6fa72cf6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ```jsonc | ||
| // create (agent follow-up tier example) | ||
| {"action":"create_job","ref":"followup-mkt3","schedule":{"run_at":"2026-07-02T18:00:00Z"}, |
There was a problem hiding this comment.
When integrators copy this create_job example to make follow-ups idempotent, the shipped scheduler ignores ref: packages/cron/cron.ex stores and dedupes only msg["dedupe_key"]. The documented idempotency path would therefore create duplicate jobs instead of deduping; use dedupe_key here or clearly mark this as a historical, non-current API.
Useful? React with 👍 / 👎.
| {"action":"approve_job","job_id":13} // approver_sources only | ||
| {"action":"reject_job","job_id":13} // approver_sources only |
There was a problem hiding this comment.
When consumers build the durable-tier approval flow from these documented actions, the current handler will route them to unknown_action: packages/cron/cron.ex only matches create_job, pause, resume, delete, tick, run_now, list, and status, and inserted jobs start as active. Since pending_approval and approver_sources are not implemented in the shipped cron object, this API should be labeled historical/deferred or removed from current docs.
Useful? React with 👍 / 👎.
| {"registry": {"scope": "acastellana"}, | ||
| "packages": [{"name": "genswarms-cron", "dir": ".", "kind": "handler", | ||
| "description": "Deterministic scheduler object for GenSwarms swarms"}]} |
There was a problem hiding this comment.
When someone follows these publication instructions from this repo, they publish/consume scope: acastellana, package genswarms-cron, and dir: ".", but the checked-in swarmidx.json publishes scope: genlayerlabs, package cron, from packages/cron in genlayerlabs/genswarms-objects. This would point users at the wrong artifact; either mark the block as historical or update it to the current coordinates.
Useful? React with 👍 / 👎.
1 participant
Archives the cron v0.1 design spec (draft v2, after the adversarial design review) from a local-only design repo that was never pushed anywhere — this was its only copy. The implementation of this design shipped as
packages/cron. Placed under rootdocs/(notpackages/cron/) so the published package digest stays code-only.Summary by CodeRabbit