feat: implement job model and lifecycle management - #403
Conversation
- Added Job and JobLifecycle classes to manage job states and transitions. - Introduced error handling for invalid job attributes and transitions. - Created tests for job lifecycle validation and transitions. - Updated documentation to reflect new job lifecycle states and behaviors. closes: #12
There was a problem hiding this comment.
Pull request overview
Implements the canonical queued-job primitive and lifecycle rules in core/karya, plus accompanying unit tests and documentation updates to establish shared runtime vocabulary (Issue #12).
Changes:
- Added
Karya::Jobimmutable value object with attribute normalization, validation, and state transition helpers. - Added
Karya::JobLifecyclewith canonical states, transition table, and terminal-state helpers. - Updated runtime/reliability docs to describe lifecycle states and align worker/control surfaces with the canonical model.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/pages/runtime/workers.md | Clarifies workers must use canonical lifecycle transitions (queued → reserved → running). |
| docs/pages/runtime/job-model.md | Documents canonical job shape, lifecycle states, invariants, and boundaries. |
| docs/pages/runtime/index.md | Notes runtime docs are source of truth for lifecycle vocabulary. |
| docs/pages/runtime/controls.md | Aligns control surface terminology with canonical lifecycle vocabulary. |
| docs/pages/reliability/retries.md | Updates retry operator vocabulary to retry_pending. |
| core/karya/spec/karya/job_spec.rb | Unit tests for job immutability, normalization, validation, and transitions. |
| core/karya/spec/karya/job_lifecycle_spec.rb | Unit tests for lifecycle normalization, transitions, and terminal checks. |
| core/karya/lib/karya/job_lifecycle.rb | Canonical lifecycle states, transitions, validation, and terminal helpers. |
| core/karya/lib/karya/job.rb | Canonical job model with validation, immutability, and lifecycle integration. |
| core/karya/lib/karya.rb | Requires new lifecycle and job primitives from the gem entrypoint. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Added validation to ensure job arguments are a Hash. - Introduced checks for blank argument keys in job normalization. - Implemented state presence validation in job lifecycle normalization. - Updated tests to cover new validation scenarios for job arguments and states.
- Added support for registering and managing extension states and transitions in the JobLifecycle class. - Implemented methods to normalize state values and validate transitions, improving lifecycle management. - Updated tests to cover new functionality for state registration and transition validation. - Enhanced the Job class to ensure caller-owned scalar argument values are not frozen, maintaining immutability.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.
Comments suppressed due to low confidence (1)
docs/pages/reliability/retries.md:34
- The example shows
next_retry_atin the past while the status isretry_pendingand the field is namednext_retry_at, which can be confusing for readers. Consider using a clearly future timestamp (relative to the example) or replacing it with a relative placeholder (e.g.,<timestamp>), to keep the example semantically consistent.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Introduced Karya::Base module to encapsulate common functionality. - Refactored job lifecycle management to improve state validation and transitions. - Added normalization for job attributes using dedicated normalizer classes. - Enhanced job model to ensure immutability of attributes. - Updated documentation to reflect new job API usage and lifecycle extensions.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Added 'created_at' parameter to job initialization for better tracking of job creation time. - Enhances the job model by ensuring that the creation timestamp is explicitly set during job instantiation.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Added comprehensive PR review instructions to replace outdated copilot instructions, ensuring clarity and consistency in the review process. - Introduced EMPTY_TRANSITIONS constant in job lifecycle to handle states without outgoing transitions. - Updated job normalization to freeze normalized keys for better performance and immutability. - Enhanced tests to verify the inclusion of empty transition arrays and the encapsulation of state normalization methods.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Added error handling for unknown job states in `can_transition_to?` method to return false instead of raising an error. - Updated state normalization methods to improve clarity and consistency. - Enhanced tests to verify behavior for unknown states and ensure proper handling of normalized arguments during transitions.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Introduced NormalizedGraph class for validating job argument structures. - Updated job lifecycle methods to utilize normalized state names. - Improved state normalization to handle punctuation and spacing. - Added tests for new normalization features and state transitions. - Updated documentation to clarify job lifecycle states and transitions.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Improved the `valid?` method in the Job model to ensure keys are not only frozen but also stripped of whitespace. - Updated job lifecycle methods to use public state names instead of symbols for better consistency. - Enhanced error handling for state normalization to reject invalid formats and ensure compliance with maximum length. - Added tests for normalizing frozen argument hashes in the Job spec to ensure proper handling of untrimmed keys. - Updated documentation to clarify the normalization of extension state names.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Implemented recursive structure checks for job arguments to prevent stack overflow issues. - Added tests to ensure that recursive hash and array structures are rejected during job initialization. - Updated documentation to clarify the handling of extension state names and their normalization.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
closes: #12