ruby_reactor 0.7.1 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abde4c2dc313b2e5d4a74873f1fc337743e6847e8f47fcbd121fd1a72be1d557
-  data.tar.gz: defd25588b78022c339ffd105d4e304d80e676498272c887cafecb60f100dc7e
+  metadata.gz: 0d5c03b684aeac0b3d682581e9746e59219622f07752a5b5e30b5381582c09c9
+  data.tar.gz: bccbbdf3eec2187481fba0c5d724b1b2b61d96a32c93139dcf5fcd20e42ff491
 SHA512:
-  metadata.gz: 595c701f476086c166d0e157c062e0bea0e6fb243b1c5466017bf488461b987b44c70b56e081770c586a1d83519311c58da9769ae83e302fb7d17d1cdc8f37fb
-  data.tar.gz: 7dadad987df2ec6d9c1b44e93ed328f07d77660310726dceeb1ee8957cc9e63b73bd3c2338792280bfc780a95650bcac12b384af3d2aad83b3309aa4896f6d0d
+  metadata.gz: ab06166bc3462aa2cf8f4569015575feb7c37ae025022ae84b886dcc171040c2a89a88dbc69208c8b1ec84be6dd19c08c418915856a510506402e7ab72f26044
+  data.tar.gz: cfb0973443827d2d50572f834b1d9d2760464eab4290097b38c73465fcb7268f9e381d211b4a2fe1815f6bb410ac56ffa64c4f61ed17f0a765966392c50494a4

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.7.1"
+  ".": "0.8.1"
 }

data/.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/001-reactor-signal-semantics"
+  "feature_directory": "specs/004-inheritable-step-class"
 }

data/.specify/memory/constitution.md

@@ -1,25 +1,27 @@
 <!--
 SYNC IMPACT REPORT
 ==================
-Version change: 1.1.0 → 1.2.0 (MINOR: Principle VI expanded with a 4th requirement —
-  docker-compose.yml currency + docker-run acceptance tests)
+Version change: 1.2.1 → 1.3.0 (MINOR: Development Workflow now REQUIRES every generated
+  plan.md and tasks.md to carry an explicit documentation-update task/gate, with the
+  requirement propagated into both templates — a new enforcement mechanism, not just
+  wording)
 
-Modified principles:
-  - Principle VI: Demo-App Proof of Feature — added requirement 4, "Docker acceptance
-    run" (docker-compose.yml MUST track demo_app's services; demo: rake tasks are the
-    project's acceptance suite, runnable via `docker compose run`)
+Modified principles: none (Development Workflow section, not a Core Principle)
 
-Added sections: none (existing Principle VI section extended)
+Added sections: none
 
 Removed sections: none
 
 Templates checked:
-  - .specify/templates/plan-template.md   ✅ Constitution Check gate is generic ("Gates determined
-                                             based on constitution file") — no edit required
-  - .specify/templates/spec-template.md   ✅ No principle-specific content — no edit required
-  - .specify/templates/tasks-template.md  ✅ Already covers demo-app polish tasks — no edit required
+  - .specify/templates/plan-template.md      ✅ Added Constitution Check checklist item:
+                                                 identify README.md/./documentation impact
+  - .specify/templates/spec-template.md      ✅ No principle-specific content — no edit required
+  - .specify/templates/tasks-template.md     ✅ Polish-phase doc task now explicit and marked
+                                                 REQUIRED, citing README.md + ./documentation
   - .specify/templates/checklist-template.md ✅ Generic — no edit required
-  - .specify/extensions.yml               ✅ No before/after_constitution hooks registered
+  - .specify/extensions.yml                  ✅ No before/after_constitution hooks registered
+  - README.md                                ✅ No principle-specific claims to update
+  - documentation/*.md                       ✅ No principle-specific claims to update
 
 Deferred TODOs: none
 -->
@@ -164,9 +166,17 @@ gaps in the matcher library surface as work instead of as workarounds.
 - Feature branches target `main`. PRs MUST pass CI (RSpec + RuboCop) before merge.
 - Releases are managed by release-please. Version bump lives in
   `lib/ruby_reactor/version.rb`. Do not manually edit the version in gemspec.
-- New features MUST update `README.md` documentation and add entries to
-  `CHANGELOG.md` under the correct semantic heading (`Features`, `Bug Fixes`,
-  `documentation`).
+- Every task MUST update documentation as part of its own change, not as a
+  follow-up: `README.md` and any affected file under `./documentation` MUST be
+  kept current with the behavior the task introduces, changes, or removes. A
+  task that alters observable behavior without a matching documentation update
+  is incomplete. New features additionally MUST add entries to `CHANGELOG.md`
+  under the correct semantic heading (`Features`, `Bug Fixes`, `documentation`).
+- Every `plan.md` produced by `/speckit-plan` and every `tasks.md` produced by
+  `/speckit-tasks` MUST include at least one explicit task or checklist item to
+  update `README.md` and the relevant file(s) under `./documentation` for the
+  feature's behavior. A plan or task list that omits a documentation-update
+  task is incomplete and MUST be rejected in review.
 - Class-based step definitions are the preferred authoring style (not inline
   lambdas). Documentation and examples MUST reflect this.
 - The `demo_app/` directory serves as a living integration example. Changes to
@@ -198,4 +208,4 @@ justified in the `Complexity Tracking` table of the plan.
 Compliance review: at each MINOR or MAJOR gem release, confirm this constitution
 still accurately reflects the codebase and update as needed.
 
-**Version**: 1.2.0 | **Ratified**: 2025-10-02 | **Last Amended**: 2026-09-09
+**Version**: 1.3.0 | **Ratified**: 2025-10-02 | **Last Amended**: 2026-09-11

data/.specify/templates/plan-template.md

@@ -42,6 +42,10 @@
 
 [Gates determined based on constitution file]
 
+- [ ] Documentation impact identified: which `README.md` sections and which
+      file(s) under `./documentation` this feature will require updating
+      (Constitution Development Workflow — carried into tasks.md as a required task)
+
 ## Project Structure
 
 ### Documentation (this feature)

data/.specify/templates/tasks-template.md

@@ -151,7 +151,7 @@ Examples of foundational tasks (adjust based on your project):
 
 **Purpose**: Improvements that affect multiple user stories
 
-- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX [P] Update `README.md` and affected file(s) under `./documentation` for this feature (REQUIRED — Constitution Development Workflow)
 - [ ] TXXX Code cleanup and refactoring
 - [ ] TXXX Performance optimization across all stories
 - [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/

data/CHANGELOG.md

@@ -1,5 +1,152 @@
 # Changelog
 
+## Unreleased
+
+### ⚠ BREAKING CHANGES
+
+* **`RubyReactor::Step` is now a base class, not a mixin.** `include RubyReactor::Step` on a
+  plain class with `def self.run(arguments, context)` is gone — no compatibility shim, no dual
+  authoring style. A step subclasses `RubyReactor::Step` and writes `run` (and optionally
+  `compensate`/`undo`) as **instance** methods reading the validated arguments and the context
+  through `inputs`/`context` accessors instead of parameters. Every instance is built fresh for
+  its one action (`run`, `undo`, or `compensate`) from the stored arguments/result/reason alone —
+  nothing an author sets in `run` is visible in a later `undo`/`compensate`, which is exactly what
+  makes rollback behave identically whether it lands in the same process as `run` or, as with an
+  `async_step`, in a separate later one. `inputs` holds the same values in all three actions: the
+  arguments with the contract's defaults applied. Only `run` enforces the contract; `undo` and
+  `compensate` never do, so rollback cannot fail on the inputs that caused the failure.
+
+  ```ruby
+  # Before
+  class ChargeStep
+    include RubyReactor::Step
+
+    input :amount, :integer, gteq?: 1
+
+    def self.run(arguments, context)
+      Success(charge!(arguments[:amount]))
+    end
+
+    def self.undo(result, arguments, context)
+      refund!(result[:charge_id])
+      Success()
+    end
+  end
+
+  # After
+  class ChargeStep < RubyReactor::Step
+    input :amount, :integer, gteq?: 1
+
+    def run
+      Success(charge!(inputs[:amount]))
+    end
+
+    def undo
+      refund!(result[:charge_id])
+      Success()
+    end
+  end
+  ```
+
+  **Migration:** for every class step, replace `include RubyReactor::Step` with
+  `< RubyReactor::Step`, turn `def self.run(args, ctx)` into `def run` reading `inputs`/`context`,
+  and likewise for `def self.undo(result, args, ctx)` / `def self.compensate(reason, args, ctx)` →
+  `def undo` / `def compensate` reading `result`/`reason`/`inputs`/`context`. The class-level
+  `MyStep.run(arguments, context)` / `.call` / `.undo(result, arguments, context)` /
+  `.compensate(reason, arguments, context)` entry points every caller (executor, worker, a direct
+  unit-test call) already used are unchanged. Inline `step { run { |args, ctx| ... } }` blocks are
+  untouched by this change.
+
+* **A class step's signal helpers (`success!`/`fail!`/`skip!`/`halt!`) now translate correctly on
+  every execution path, including the `async_step`/`background` worker.** Previously the worker had
+  no `catch` of its own, so a signal thrown from a class step running there escaped as an
+  `UncaughtThrowError` instead of the intended `Success`/`Failure`/`Skipped`/`Halt` — the base
+  class's class-level `run`/`undo`/`compensate` now own that translation, so every caller gets it
+  for free with no worker change. Known remaining gap, unchanged by this release: an **inline**
+  `run`/`compensate`/`undo` block's signals are still uncaught on the worker path.
+
+* **A step's own input-validation failure is now guaranteed non-retryable on every path.**
+  `result.retryable?` is `false` whether the violation happened synchronously, inside an
+  `async_step`/`background` worker, or inside a `compose`d child's own step — previously only the
+  async worker path got this right; the synchronous path and a validation failure surfacing
+  through `compose` both defaulted to `retryable? == true`.
+
+* **`Failure(...)` takes the same arguments everywhere.** Inside a class step and inside an inline
+  `run`/`compensate`/`undo` block, `Failure` now forwards every argument to `RubyReactor.Failure`,
+  so options such as `Failure("declined", retryable: false)` work instead of raising
+  `ArgumentError`. A bare `Failure()` with no error is no longer accepted, matching
+  `RubyReactor.Failure`, and a hash error needs braces, `Failure({ code: 1 })`, because a braceless
+  `Failure(code: 1)` is now read as options.
+
+### Features
+
+* **Step input contracts.** A step class declares its own inputs with `input :name, :type, **predicates`
+  (plus `optional:`, `default:`, `redact:`, the `do |i| ... end` macro block and `validate:`) and
+  cross-field rules with `validate_inputs`. The contract is enforced before `run` on every path
+  (inline, retries, `async_step` and `background` workers, resume, `map`, and a direct
+  `Step.run(args, context)` call), and a violation fails with `validation_errors` and the step's
+  name after completed steps are rolled back. Subclasses inherit and extend the contract.
+  Introspection: `input_contract`, `declared_inputs`, `required_input_names`, `declares_inputs?`.
+* **Inline step contracts.** `inputs do ... end` inside a `step` block takes the same `input` /
+  `validate_inputs` lines as a step class and is enforced the same way.
+* **Wiring by name.** A declared input with no `argument` resolves from the reactor input of the
+  same name (never from a step result). A required input that is neither wired nor a reactor input
+  raises `Error::ValidationError` before any step runs. `Reactor.validate_definition!` runs that
+  check on demand, e.g. from an initializer or CI.
+* For a step that owns a contract, a type or predicate on `argument`, `validate_args`, or an
+  `argument` for an undeclared input raises `Error::ValidationError` when the `step` line is
+  evaluated.
+* `have_validation_error` now also matches validation failures raised at a step, not only
+  reactor-input failures.
+* `Failure#to_h` includes `retryable`, so a non-retryable failure stays non-retryable after it
+  crosses a worker boundary.
+* A step that returns another unit's validation failure (e.g. an `async_step` reader propagating
+  the worker's `Failure`) keeps its `validation_errors` on the reactor's final failure.
+
+### Deprecations
+
+* Rules on `argument` (`argument :x, src, :type, **predicates`) and `validate_args` keep working
+  for steps without a contract, and print one deprecation notice per declaration site. Move them
+  to `input` / `validate_inputs` on the step class, or into an `inputs do ... end` block for an
+  inline step, and keep `argument :x, src` for wiring. Removal is no earlier than the next major
+  version. See "Step Input Contracts" in the README for the migration.
+
+### Bug Fixes
+
+* A supplied `false` reactor input or step result no longer resolves to `nil`.
+  `Context#get_input`, `Context#get_result` and `Template::Result#fetch` now check whether the key
+  exists instead of whether the value is truthy. Code that relied on `false` arriving as `nil`
+  will now see `false`.
+* An input-validation `Failure` stays non-retryable across serialization. `Failure`'s
+  hash extractor and the reactor's stored `failure_reason` both dropped a `retryable: false`
+  (`||` swallowed the `false`, and the reactor never stored the flag at all), so a failure
+  rebuilt from JSON or reloaded with `Reactor.find` reported `retryable? == true`.
+* A step-contract violation inside `compose` now reaches the parent with its `validation_errors`
+  and retryability intact, instead of being rebuilt from the child's error message alone.
+* A reactor reopened after its first run is re-checked: `validate_definition!` no longer memoizes,
+  so a step declared later can no longer reach execution with a required input unwired.
+* A class step that calls `halt!` under `async_step` is recorded as a halt rather than an
+  ordinary `nil` success, and `result(:step)` hands the reader the `Halt` — the same way it
+  already hands over a `Failure`.
+
+## [0.8.1](https://github.com/arturictus/ruby_reactor/compare/v0.8.0...v0.8.1) (2026-09-22)
+
+
+### Miscellaneous Chores
+
+* Update documentation clarifying background and async concepts ([#55](https://github.com/arturictus/ruby_reactor/issues/55)) ([968e32b](https://github.com/arturictus/ruby_reactor/commit/968e32bbc695e45471d04b7630d8cd437ff41624))
+
+## [0.8.0](https://github.com/arturictus/ruby_reactor/compare/v0.7.1...v0.8.0) (2026-09-21)
+
+
+### ⚠ BREAKING CHANGES
+
+* Step Instance and input validations per step  ([#51](https://github.com/arturictus/ruby_reactor/issues/51))
+
+### Features
+
+* Step Instance and input validations per step  ([#51](https://github.com/arturictus/ruby_reactor/issues/51)) ([4a20583](https://github.com/arturictus/ruby_reactor/commit/4a2058399d73e9b3bf767659dd5ba080537dc291))
+
 ## [0.7.1](https://github.com/arturictus/ruby_reactor/compare/v0.7.0...v0.7.1) (2026-09-14)
 
 
@@ -58,9 +205,9 @@
   point (`:x` stays in the calling process); the two coincide in a linear chain
   but pin different steps in a DAG.
 
-  Not affected: the map-internal `async` element dispatch option
-  (`map :items do async true, batch_size: 2 end`) — a different mechanism that
-  keeps working unchanged.
+  Also affected: the map-internal element dispatch option was renamed from
+  `async true` to `fan_out`, so `map :items do async true, batch_size: 2 end`
+  now raises and should become `map :items do fan_out batch_size: 2 end`.
 
   One behavior change falls out of "exactly one hand-off point per reactor":
   resuming a reactor past its hand-off point now finishes in the resuming

data/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
 shell commands, and other important information, read the current plan:
-`specs/001-reactor-signal-semantics/plan.md`
+`specs/004-inheritable-step-class/plan.md`
 <!-- SPECKIT END -->