ruby_reactor 0.8.3 → 0.8.5

data/specs/future_improvements.md

@@ -248,3 +248,51 @@ Direction:
 
 Spec: compose → fan-out map, with and without a park after the map. The root completes either
 way.
+
+## Rollback follow-ups (008)
+
+Raised while implementing specs/008-rollback-reliability. None blocks it.
+
+- **Sweeper re-enqueues in-progress inline runs.** `RubyReactor::Sweeper` re-enqueues any
+  top-level context that is `running` with no `async:` lock. A run still executing in the
+  caller's process never holds that lock, so a sweep during it enqueues a worker that resumes the
+  same run forward. Pre-existing; 008 only keeps `aborted` runs out of it. Direction: mark
+  caller-process runs (the `inline_async_execution` inverse) so the sweeper skips them until they
+  are stale by a timestamp, or give them their own liveness lock.
+- **Map-level `undo_all` override.** Map rollback always replays each element's own step `undo`s.
+  A bulk refund API may want one call for all elements instead. Direction: an optional
+  `undo_all { |completed_results| ... }` on `map` that replaces the per-element replay.
+- **Rollback fan-out for very large maps.** Map rollback is serial, in the process that detected
+  the failure, so its time is linear in the number of completed elements (10,000 elements take
+  about a minute in the test suite). Direction: enqueue one rollback job per element (or per
+  batch) and resolve the parent's failure once they report back.
+- **A resume for a second pending interrupt while the first is executing.** A reactor paused at
+  several ready interrupts takes their resumes one at a time: each accepted resume marks the run
+  `running` (008 FR-032), and the run pauses again at the interrupts still pending. A resume that
+  arrives for another pending interrupt while the first resume is still executing is rejected
+  ("the reactor is running"). Interrupt steps have no body, so that window is short, but a caller
+  resuming two interrupts at once can hit it. Direction: accept it for an interrupt that has not
+  executed yet (store its payload and let the running resume pick it up), or return a retryable
+  error.
+- **An interrupted `compensate` of the failing step is not re-run.** An interruption (signal, exit,
+  out of memory) during the failing step's own `compensate` leaves the run `aborted`. A manual
+  `Reactor.undo(id)` undoes the completed steps but never re-runs that `compensate`, so the step
+  can stay half-compensated. Pre-existing (008 R-08). Direction: record the failing step on the
+  aborted run and have manual undo re-run its `compensate` before the undo stack.
+- **Recover a resume contended on a lock.** An inline `continue` that cannot take the reactor's
+  `with_lock` or `with_semaphore` raises its `AcquisitionError` and leaves the run `paused`; the
+  caller has to retry it (008 review, 2026-09-30). A webhook sender that does not retry loses the
+  resume. Direction:
+  - Validate the payload first, synchronously in the calling process, as `resume: :background`
+    does today. An invalid payload returns its validation failure to the caller (the webhook),
+    and nothing is stored or enqueued.
+  - Only a valid payload is stored and handed off. On contention, mark the run `running` and give
+    the resume to a worker. The worker snoozes on the contended lock without spending retries and
+    resumes once the lock is free. The deferred resume never re-validates the payload, so it
+    cannot fail on validation after the caller was told it was accepted.
+  - `continue` returns a `DispatchResult` instead of raising, and a second `continue` is rejected
+    as for any running resume.
+- **Two resumes in the same instant.** Two `continue` calls that both read `paused` before either
+  saves `running` are separated only by the per-run context lock, which inline Sidekiq testing
+  skips. Accepted for now (008 review, 2026-09-27). Direction: claim the resume with an atomic
+  status compare-and-set.

data/specs/specs-inputs-by-method-md-piped-wigderson.md

@@ -0,0 +1,77 @@
+# Plan: `inputs.order_id` (implement specs/inputs_by_method.md)
+
+## Context
+
+`Step#inputs` is a plain Hash, so a typo like `inputs[:order_id]` (declared `:order_guid`) returns `nil` and blows up later, far from the bug — worst in `undo`/`compensate`, which skip validation. The design doc (`specs/inputs_by_method.md`) decides: step code reads inputs through a frozen read-only `Step::Inputs` object (`inputs.order_id`); any unreadable name raises `Error::UndeclaredInputError` naming the step and its declared inputs. No `[]`, no shim — every call site migrates in the same change (`feat!`). This plan implements that doc as written; deviations/additions found while reading the code are marked **(new)**.
+
+Branch: `inputs_by_method` off `main`. Test-first (Constitution III): new specs first, then lib, then migration.
+
+**Step 0 (on approval):** copy this plan to `specs/inputs_by_method_plan.md` (next to the design doc) and stop there. Implementation starts only when asked.
+
+## 1. New code (lib)
+
+**`lib/ruby_reactor/step/inputs.rb`** — `RubyReactor::Step::Inputs` (Zeitwerk picks it up).
+- `initialize(values, contract: nil, owner:)`: `@values = values.to_h` (so passing an `Inputs` or nil is safe), readable `@names` = `contract.declarations.keys` when the contract has declarations, else `@values.keys.map(&:to_sym)` **(new: a contract with only `validate_inputs` and no `input` falls back to present keys instead of making everything unreadable)**; `@redacted = contract&.redacted_names || []`; `freeze`.
+- `method_missing(name, *args)`: readable name and no args → `Utils::FetchIndifferent.call(@values, name)`; else raise `UndeclaredInputError`. `respond_to_missing?` → `@names.include?(name) || super`.
+- `to_h` → supplied readable names only, symbol keys, via FetchIndifferent (key present as sym or string). `alias to_hash to_h`.
+- `inspect` → `to_h` with redacted names replaced by `InputContract::REDACTED`.
+
+**`lib/ruby_reactor/error/undeclared_input_error.rb`** — `< NoMethodError`, `def retryable? = false`. Message: `"#{owner} has no input :#{name}. Declared inputs: :a, :b."` (`none` when empty). Retry path already honours it: `Failure#retryable?` (`lib/ruby_reactor.rb:167`) and `StepFailureError#retryable?` ask the error.
+
+**Reserved names** — `InputContract#input` (`lib/ruby_reactor/step/input_contract.rb:25`): raise `Error::ValidationError` when `Step::Inputs.public_method_defined?(name)`. Checked all 141 input names in spec/demo_app/docs: no clashes.
+
+## 2. Injection points (the only places the object is built)
+
+| Where | Change |
+|---|---|
+| `Step#initialize` (`lib/ruby_reactor/step.rb:44`) | `@inputs = Inputs.new(inputs, contract: (self.class.input_contract if self.class.declares_inputs?), owner: self.class.name)`. Covers `.run`/`.undo`/`.compensate`. Update header comment example (`step.rb:8`). |
+| `Step.enforce_contract!` / `with_defaults` (`step.rb:168-179`) | **(new)** `arguments.to_h` first, so a documented nested call `OtherStep.run(inputs, context)` from a step body, and TestSubject's `original` callable, still hand the contract a Hash. |
+| `StepConfig` (`lib/ruby_reactor/dsl/step_builder.rb`) | Add `def wrap_inputs(arguments) = Step::Inputs.new(arguments, contract: input_contract, owner: "step :#{name}")`. |
+| `StepConfig#call_body` (`step_builder.rb:367`) | `run_block.call(wrap_inputs(arguments), context)`. Duck-typed `impl.run` (line 372) unchanged. |
+| `CompensationManager#compensate_step` / `#undo_step` (`lib/ruby_reactor/executor/compensation_manager.rb:126,171`) | Wrap `arguments` with `step_config.wrap_inputs` before the inline block call only. |
+| `TestSubject#original_impl_for` duck-impl lambda (`lib/ruby_reactor/rspec/test_subject.rb:772`) | **(new)** `impl.run(args.to_h, ctx)`. Mock blocks replace `@run_block`, so they receive `Inputs` like the body they stand in for — the `Step` path is covered by the `to_h` above. |
+
+## 3. Returning inputs from a step
+
+- `RubyReactor.Success` (`lib/ruby_reactor.rb:391`): `Success.new(value.is_a?(Step::Inputs) ? value.to_h : value)`.
+- `ResultHandler#handle_unknown_result` (`lib/ruby_reactor/executor/result_handler.rb:192`): build `success_result` first, then `validate_step_output` on `success_result.value`, **and (new) `@context.set_result(..., success_result.value)`** — the doc's swap alone would still store the raw `Inputs` in context.
+
+## 4. Built-in steps
+
+Per the doc, `MapStep`, `ComposeStep`, `AsyncReactorStep` declare their keys (`input :source`, `input :fan_out, optional: true`, …, untyped → no validator, `enforce!` is a no-op) and switch `inputs[:x]` → `inputs.x` (31 sites). `fail_fast: inputs.fail_fast.nil? || inputs.fail_fast` stays.
+- **(new)** drop `inputs[:step_name] ||` in `map_step.rb:193`: `step_name` is never wired, and once declared, `validate_definition!` would wire it by name from a reactor input called `:step_name`.
+
+## 5. Migration (no shim)
+
+Counts: `inputs[` — spec 131, docs 49, README 10, demo_app 44; `args[` — spec 378, docs 157, README 54, demo_app 414 (most in inline blocks).
+- Step bodies only (class `run`/`undo`/`compensate`, inline `run`/`undo`/`compensate` blocks, TestSubject mock blocks): `x[:k]` → `x.k`. Hand edits, not a global replace — lock/semaphore/rate-limit key procs, `validate_inputs`, `where`/`guard`, `transform:` procs stay Hashes.
+- Other Hash use on inputs (`each`, `slice`, `eq(hash)` in specs) → `.to_h`. `**inputs`, `merge(inputs)`, `Success(inputs)` keep working.
+- Docs/README/`demo_app/documentation`: rename inline block param `args` → `inputs`; `documentation/core_concepts.md` step-inputs section documents reader API, `UndeclaredInputError`, reserved names, `to_h`/`**`, `Success(inputs)` conversion (nested not converted).
+- Order: lib → `spec/` → `demo_app/` → docs/README.
+
+**Silent-pass trap:** a spec that expects a step to fail still passes if an unmigrated `[]` now fails it for a different reason. So grep is the driver and the suite is the net, not the other way round.
+
+## 6. Demo (Constitution VI)
+
+Via `/speckit-demo-tests`: `demo_app/app/reactors/undeclared_input_demo_reactor.rb` (step reads a typo'd input), `demo:undeclared_input` in `demo_app/lib/tasks/demo_reactors.rake`, `demo_app/spec/reactors/undeclared_input_demo_reactor_spec.rb` asserting failure with `UndeclaredInputError` and one attempt despite `retries`.
+
+## 7. Tests (written first)
+
+`spec/ruby_reactor/step/inputs_spec.rb`:
+- reader returns value; declared-optional absent → `nil`; `false` stays `false`; string-keyed hash readable.
+- undeclared name raises `UndeclaredInputError` with exact message; `respond_to?`; clash with private Kernel name (`select`) as a declared input reads fine.
+- contract-less step reads present keys only; unwired inline step with `inputs do` reads only declared.
+- `to_h` omits unsupplied optionals; `**inputs`; `inspect` redacts; frozen, no `[]`.
+- `input :method` → `ValidationError` at class definition.
+- class `undo`/`compensate` and inline `run`/`undo`/`compensate` blocks receive `Inputs`; typo in `compensate` surfaces as rollback failure naming the input.
+- step with `retries max_attempts: 3` + typo → one attempt.
+- `Success(inputs)` sync (`result(:step, :x)` works) and async round trip (Hash, not a string); bare `run { |inputs| inputs }` stored/validated as Hash.
+- nested `OtherStep.run(inputs, context)` from a step body works; TestSubject `mock_step` with `original.call(args, ctx)` on a class step works.
+
+## Verification
+
+1. `bundle exec rspec` (real Redis) green; rerun flaky async specs alone before chasing them.
+2. `cd demo_app && bundle exec rspec` green; `bin/rails demo:undeclared_input` shows the error.
+3. `bundle exec rubocop` clean.
+4. Residual audit: `grep -rnE 'inputs\[|\bargs\[' lib spec demo_app documentation README.md` — every remaining hit is a Hash context (key procs, validators, `where`/`guard`, reactor DSL `inputs[name]` in `dsl/reactor.rb`).
+5. Commit as `feat!:` with a migration note (`inputs[:x]` → `inputs.x`, Hash methods → `inputs.to_h`).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.8.5
 platform: ruby
 authors:
 - Artur
@@ -165,9 +165,11 @@ files:
 - lib/ruby_reactor/dsl/lockable.rb
 - lib/ruby_reactor/dsl/map_builder.rb
 - lib/ruby_reactor/dsl/reactor.rb
+- lib/ruby_reactor/dsl/retryable.rb
 - lib/ruby_reactor/dsl/step_builder.rb
 - lib/ruby_reactor/dsl/template_helpers.rb
 - lib/ruby_reactor/dsl/validation_helpers.rb
+- lib/ruby_reactor/error/argument_resolution_error.rb
 - lib/ruby_reactor/error/async_result_pending.rb
 - lib/ruby_reactor/error/async_wait_timeout_error.rb
 - lib/ruby_reactor/error/base.rb
@@ -179,9 +181,11 @@ files:
 - lib/ruby_reactor/error/execution_parked.rb
 - lib/ruby_reactor/error/input_validation_error.rb
 - lib/ruby_reactor/error/reactor_contention_park.rb
+- lib/ruby_reactor/error/rescuable.rb
 - lib/ruby_reactor/error/schema_version_error.rb
 - lib/ruby_reactor/error/step_contention_park.rb
 - lib/ruby_reactor/error/step_failure_error.rb
+- lib/ruby_reactor/error/undeclared_input_error.rb
 - lib/ruby_reactor/error/undo_error.rb
 - lib/ruby_reactor/error/validation_error.rb
 - lib/ruby_reactor/executor.rb
@@ -229,6 +233,7 @@ files:
 - lib/ruby_reactor/step/async_reactor_step.rb
 - lib/ruby_reactor/step/compose_step.rb
 - lib/ruby_reactor/step/input_contract.rb
+- lib/ruby_reactor/step/inputs.rb
 - lib/ruby_reactor/step/map_step.rb
 - lib/ruby_reactor/step_signals.rb
 - lib/ruby_reactor/step_sweeper.rb
@@ -261,15 +266,55 @@ files:
 - lib/ruby_reactor/web/config.ru
 - lib/ruby_reactor/web/coordination_serializer.rb
 - lib/ruby_reactor/web/public/assets/index-BQvIWPdx.css
-- lib/ruby_reactor/web/public/assets/index-CeZU-ESu.js
+- lib/ruby_reactor/web/public/assets/index-CQbgHtd0.js
 - lib/ruby_reactor/web/public/index.html
 - lib/ruby_reactor/web/public/vite.svg
 - lib/ruby_reactor/worker.rb
 - llms-full.txt
 - llms.txt
 - sig/ruby_reactor.rbs
+- specs/006-step-retry-declarations/checklists/requirements.md
+- specs/006-step-retry-declarations/contracts/dsl-surface.md
+- specs/006-step-retry-declarations/data-model.md
+- specs/006-step-retry-declarations/plan.md
+- specs/006-step-retry-declarations/quickstart.md
+- specs/006-step-retry-declarations/research.md
+- specs/006-step-retry-declarations/spec.md
+- specs/006-step-retry-declarations/tasks.md
+- specs/007-execution-flow-analysis/analysis/README.md
+- specs/007-execution-flow-analysis/analysis/execution-order.md
+- specs/007-execution-flow-analysis/analysis/findings-and-options.md
+- specs/007-execution-flow-analysis/analysis/invariants.md
+- specs/007-execution-flow-analysis/checklists/requirements.md
+- specs/007-execution-flow-analysis/contracts/report-structure.md
+- specs/007-execution-flow-analysis/data-model.md
+- specs/007-execution-flow-analysis/evidence/harness.rb
+- specs/007-execution-flow-analysis/evidence/output.txt
+- specs/007-execution-flow-analysis/evidence/probes/01_plain.rb
+- specs/007-execution-flow-analysis/evidence/probes/02_compose.rb
+- specs/007-execution-flow-analysis/evidence/probes/03_map.rb
+- specs/007-execution-flow-analysis/evidence/probes/04_async.rb
+- specs/007-execution-flow-analysis/evidence/probes/05_background.rb
+- specs/007-execution-flow-analysis/evidence/probes/06_coordination.rb
+- specs/007-execution-flow-analysis/evidence/probes/07_interrupts_manual.rb
+- specs/007-execution-flow-analysis/evidence/run.rb
+- specs/007-execution-flow-analysis/plan.md
+- specs/007-execution-flow-analysis/quickstart.md
+- specs/007-execution-flow-analysis/research.md
+- specs/007-execution-flow-analysis/spec.md
+- specs/007-execution-flow-analysis/tasks.md
+- specs/008-rollback-reliability/checklists/requirements.md
+- specs/008-rollback-reliability/contracts/api-surface.md
+- specs/008-rollback-reliability/contracts/rollback-semantics.md
+- specs/008-rollback-reliability/data-model.md
+- specs/008-rollback-reliability/plan.md
+- specs/008-rollback-reliability/quickstart.md
+- specs/008-rollback-reliability/research.md
+- specs/008-rollback-reliability/spec.md
+- specs/008-rollback-reliability/tasks.md
 - specs/future_improvements.md
 - specs/scoped_rspec_matchers.md
+- specs/specs-inputs-by-method-md-piped-wigderson.md
 - teley/Dockerfile
 homepage: https://github.com/arturictus/ruby_reactor
 licenses: []