octorail 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a292913a9530a1fa803b554fc6d2263532d083cfa7cb82e73a467368861e4a9
+  data.tar.gz: 7fb841e132dca2d0ac965070ce67a42c73685c58c416c4a891fd8e26789622f5
+SHA512:
+  metadata.gz: 6965c6a4f8a96ad6883b0e6b409fb609ea27619331dd6d4112e5f115fc10b454641b5709b30cee91311001ef3534c1aa7e34f79e52c9e7e96908dd0ba8b1f72d
+  data.tar.gz: 2cbf04c2cdd038721f7959df8ae112a28e89a080b9f40a908323833785c0964880bb445cf3a35117dca1868631d3ee0b7c4f9952808e02f7ab5936c33bfe128f

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-28
+
+### Added
+
+- `step`, `pass` and `failure` steps as instance methods, compiled into one plain
+  Ruby method on first call, or all at once with `Octorail.compile_all!`.
+- Step signatures `(ctx)` or `(ctx, key:, ...)`: keyword arguments are read from
+  ctx, and a missing key raises `Octorail::MissingKeyError` before the step runs.
+- `error:` on steps; `result.error` and `result.failed_step` on failure.
+- `output` declarations: a result exposes only declared keys.
+- `fail_fast: true` on `step` and `failure` to end with the `:fail_fast` terminus.
+- `failure ..., recover: true` to return to the success track.
+- `wrap` to run a group of steps inside a block (transaction, lock, ...).
+- `nested` to call another operation with the shared ctx, and `nested_call(ctx)`
+  as its entry point.
+- `switch` / `on` to pick a branch by a decider method's Symbol;
+  an unknown value raises `Octorail::UnknownBranchError`.
+- `abstract!` base operations that hold shared methods and settings, but no steps.
+- `Octorail.configure` and per-operation `configure`.
+- Tracing at `:path` or `:profile` level, `call_traced`, `result.trace`, and
+  `exception.octorail_trace`, rendered as a tree (`to_s`) or a hash (`to_h`).
+- `to_ruby` to print the generated source.
+- Compile-time errors (`Octorail::CompileError` and friends, all `< ScriptError`)
+  that point at the declaration line.
+
+[Unreleased]: https://github.com/Octorail-team/octorail/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/Octorail-team/octorail/releases/tag/v1.0.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dmytro Bereza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,144 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Octorail-team/octorail/main/.github/assets/banner.png" alt="Octorail: railway-oriented operations for Ruby, compiled to plain Ruby" width="100%">
+</p>
+
+# Octorail
+
+[![CI](https://img.shields.io/github/actions/workflow/status/Octorail-team/octorail/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI)](https://github.com/Octorail-team/octorail/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FOctorail-team%2Foctorail%2Fbadges%2Fcoverage.json&style=flat-square&cacheSeconds=300)](https://github.com/Octorail-team/octorail/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-3.3%20%7C%203.4%20%7C%204.0-blue?style=flat-square&logo=ruby&logoColor=white)](https://www.ruby-lang.org)
+[![YJIT](https://img.shields.io/badge/YJIT-tested-blue?style=flat-square&logo=ruby&logoColor=white)](https://github.com/Octorail-team/octorail/blob/main/docs/performance.md)
+[![Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen?style=flat-square)](https://github.com/Octorail-team/octorail/blob/main/octorail.gemspec)
+[![RuboCop](https://img.shields.io/github/actions/workflow/status/Octorail-team/octorail/lint.yml?branch=main&style=flat-square&logo=rubocop&logoColor=white&label=rubocop)](https://github.com/Octorail-team/octorail/actions/workflows/lint.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/Octorail-team/octorail/blob/main/LICENSE.txt)
+
+Railway-oriented operations for Ruby, in the spirit of Trailblazer, compiled to
+plain Ruby. You declare steps; on first use Octorail turns them into one
+ordinary method of `if`s and `return`s, so a call costs about what
+hand-written code costs and allocates no more.
+
+It is deliberately strict: steps are instance methods, ctx is a Hash, the
+railway is linear, and anything ambiguous is an error at load time with the
+line that caused it.
+
+Requires Ruby >= 3.3. No dependencies.
+
+```ruby
+gem "octorail"
+```
+
+## Example
+
+```ruby
+class Orders::Checkout < Octorail::Operation
+  output :order
+
+  nested Orders::Validate
+  wrap :transaction do
+    step :create_order
+    nested Payments::Charge
+  end
+  switch :delivery_for do
+    on(:pickup)
+    on(:courier) { step :book_courier }
+  end
+  pass :send_receipt
+  failure :log_failure
+
+  def transaction(_ctx, &) = ActiveRecord::Base.transaction(requires_new: true) { yield || raise(ActiveRecord::Rollback) }
+  def create_order(ctx, user:, total:) = ctx[:order] = user.orders.create!(total:)
+  def delivery_for(_ctx, delivery: :courier) = delivery
+  def book_courier(ctx, order:, address:) = Couriers.book(order, address)
+  def send_receipt(_ctx, order:) = ReceiptMailer.with(order:).deliver_later
+  def log_failure(_ctx, error:, failed_step:) = Rails.logger.warn("checkout: #{error} at #{failed_step}")
+end
+
+result = Orders::Checkout.call(user:, total: 42, address: "Kyiv")
+result.success?     # => false
+result.error        # => :declined      (from inside Payments::Charge)
+result.failed_step  # => :charge
+
+case result
+in { success: true, order: } then redirect_to order
+in { error: :declined }      then render :card_declined
+end
+```
+
+And when you need to know why:
+
+```text
+Orders::Checkout  4.874 ms
+├── ✓ nested Orders::Validate  0.636 ms
+│   └── ✓ check  0.002 ms
+├── wrap transaction → false  4.176 ms
+│   ├── ✓ create_order  0.001 ms
+│   └── ✗ nested Payments::Charge  4.171 ms
+│       ├── ✓ authorize  0.001 ms
+│       └── ✗ charge  2.993 ms
+├── · failure log_failure  0.001 ms
+└── failure error=:declined failed_step=:charge
+```
+
+## What you get
+
+- `step` / `pass` / `failure`, with keyword arguments read from ctx and a
+  clear error when a required key is missing.
+- `wrap` for transactions, locks, retries; `nested` to compose operations;
+  `switch` to branch on a value.
+- `fail_fast:` and `failure ..., recover: true` to leave or rejoin the success track.
+- Results with `error`, `failed_step`, declared outputs and pattern matching.
+- Tracing on demand (`call_traced`), per operation or globally, attached to
+  results and to exceptions.
+- Errors at load time that point at the declaration line.
+
+## Speed
+
+Ten trivial steps, Ruby 4.0 with YJIT: Octorail 416 ns, a hand-written PORO
+425 ns, Yaso 897 ns, Decouplio 1.1 µs, Trailblazer 25.2 µs. Allocations equal
+the PORO's. Averaged over 36 benchmarks (3 Rubies, with and without YJIT):
+1.7× faster than Yaso, 1.9× than Decouplio, 38× than Trailblazer. Full tables
+and caveats in [performance](https://github.com/Octorail-team/octorail/blob/main/docs/performance.md).
+
+## Documentation
+
+- [Guide](https://github.com/Octorail-team/octorail/blob/main/docs/guide.md): one operation built end to end
+- [Steps](https://github.com/Octorail-team/octorail/blob/main/docs/steps.md) · [Result](https://github.com/Octorail-team/octorail/blob/main/docs/result.md) ·
+  [Fail fast and recover](https://github.com/Octorail-team/octorail/blob/main/docs/fail-fast-and-recover.md)
+- [Wrap](https://github.com/Octorail-team/octorail/blob/main/docs/wrap.md) · [Nested](https://github.com/Octorail-team/octorail/blob/main/docs/nested.md) · [Switch](https://github.com/Octorail-team/octorail/blob/main/docs/switch.md) ·
+  [Inheritance and macros](https://github.com/Octorail-team/octorail/blob/main/docs/inheritance.md)
+- [Compilation](https://github.com/Octorail-team/octorail/blob/main/docs/compilation.md) · [Tracing](https://github.com/Octorail-team/octorail/blob/main/docs/tracing.md) ·
+  [Configuration](https://github.com/Octorail-team/octorail/blob/main/docs/configuration.md) · [Errors](https://github.com/Octorail-team/octorail/blob/main/docs/errors.md)
+- [Testing](https://github.com/Octorail-team/octorail/blob/main/docs/testing.md) · [Performance](https://github.com/Octorail-team/octorail/blob/main/docs/performance.md)
+
+Each page ends with **Limits**: what the gem forbids around that feature, why,
+and what to do instead.
+
+## Rails
+
+Octorail itself doesn't depend on Rails. To compile every operation at boot, so
+a broken one fails the deploy instead of the first request, add an initializer:
+
+```ruby
+# config/initializers/octorail.rb
+Rails.application.config.after_initialize do
+  Octorail.compile_all! if Rails.configuration.eager_load
+end
+```
+
+## Development
+
+Everything runs in Docker; no local Ruby needed.
+
+```sh
+make build              # build images for Ruby 3.3 / 3.4 / 4.0
+make test               # rspec on Ruby 3.3
+make test RUBY=ruby40   # rspec on a specific Ruby
+make test-all           # rspec on every supported Ruby
+make lint               # rubocop
+make bench RUBY=ruby34  # benchmarks against Yaso, Decouplio, Trailblazer
+make console            # IRB with the gem loaded
+```
+
+## License
+
+MIT, see [LICENSE.txt](https://github.com/Octorail-team/octorail/blob/main/LICENSE.txt).

data/lib/octorail/compiler/code.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Octorail
+  class Compiler
+    # Collects generated source line by line and keeps track of indentation.
+    class Code
+      def initialize
+        @lines = []
+        @depth = 0
+      end
+
+      def line(text)
+        @lines << "#{"  " * @depth}#{text}"
+        self
+      end
+
+      def indented
+        @depth += 1
+        yield
+        self
+      ensure
+        @depth -= 1
+      end
+
+      # For `rescue` / `else` lines that sit one level out from the body.
+      def dedented
+        @depth -= 1
+        yield
+        self
+      ensure
+        @depth += 1
+      end
+
+      # header ... end
+      def block(header, &)
+        line(header)
+        indented(&)
+        line("end")
+      end
+
+      # if condition ... else ... end
+      def if_else(condition, on_true, on_false)
+        line("if #{condition}")
+        indented(&on_true)
+        line("else")
+        indented(&on_false)
+        line("end")
+      end
+
+      def to_s
+        "#{@lines.join("\n")}\n"
+      end
+    end
+  end
+end

data/lib/octorail/compiler/nested_cycles.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Octorail
+  class Compiler
+    # A nested operation that leads back to one on the current path would recurse until
+    # SystemStackError; this walks the nested graph (through wraps, branches and inherited steps).
+    class NestedCycles
+      def initialize(operation)
+        @operation = operation
+        @done = Set.new # operations already known to be cycle-free
+      end
+
+      def check! = walk(@operation, [@operation])
+
+      private
+
+      def walk(operation, path)
+        operation.all_steps.grep(Nodes::Nested).each do |node|
+          target = node.operation
+          next if @done.include?(target)
+
+          cycle!(path.drop(path.index(target)) << target, node) if path.include?(target)
+          walk(target, path + [target])
+        end
+        @done << operation
+      end
+
+      def cycle!(cycle, node)
+        raise CompileError, "#{@operation}: nested operations form a cycle: #{cycle.join(" → ")}" \
+                            "#{Octorail.declared_at(node)}"
+      end
+    end
+  end
+end

data/lib/octorail/compiler/nested_emitter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Octorail
+  class Compiler
+    # Emits a nested operation: called with the same ctx, its Result decides like a step's return value.
+    #
+    #   __n1 = ::Billing::Charge.nested_call(ctx)
+    #   unless __n1.success?
+    #     log_failure(ctx)
+    #     return Result.new(:failure, ctx, __n1.error, __n1.failed_step)
+    #   end
+    #
+    # The inner error / failed_step show through (error: replaces the error); the inner terminus
+    # doesn't: only the node's own fail_fast skips the outer failure steps.
+    class NestedEmitter
+      def initialize(compiler)
+        @compiler = compiler
+      end
+
+      def emit(code, nested, index, scope)
+        id = @compiler.next_id
+        result = "__n#{id}"
+        trace = @compiler.start_trace(code, scope, :nested, @compiler.trace_label(nested.operation), id)
+        code.line("#{result} = #{@compiler.constant_for(nested.operation)}.nested_call(ctx#{", #{trace}" if trace})")
+        @compiler.done_trace(code, scope, trace, "#{result}.success?")
+        error = nested.error ? nested.error.inspect : "#{result}.error"
+        code.block("unless #{result}.success?") do
+          scope.emit_failure(code, index, error, "#{result}.failed_step", fail_fast: nested.fail_fast)
+        end
+      end
+    end
+  end
+end

data/lib/octorail/compiler/recovery_emitter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Octorail
+  class Compiler
+    # Emits a list that has a `failure ..., recover: true` step (see RecoveryScope):
+    #
+    #   __r1_t = __r1_e = __r1_s = nil
+    #   unless charge_card(ctx)
+    #     __r1_t = :failure; __r1_e = :declined; __r1_s = :charge_card
+    #   end
+    #   if __r1_t == :failure
+    #     if charge_wallet(ctx, failed_step: __r1_s)
+    #       __r1_t = nil
+    #     end
+    #   end
+    #   unless __r1_t
+    #     ...next steps...
+    #   end
+    #   if __r1_t
+    #     ...leave through the list's own scope (return / next / outer failure track)...
+    #   end
+    class RecoveryEmitter
+      def self.needed?(nodes) = nodes.any? { |node| node.is_a?(Nodes::Step) && node.recover }
+
+      def initialize(compiler)
+        @compiler = compiler
+      end
+
+      def emit(code, base)
+        scope = RecoveryScope.new(base, @compiler, @compiler.next_id)
+        flag = scope.var(:t)
+        code.line("#{flag} = #{scope.var(:e)} = #{scope.var(:s)} = nil")
+        base.nodes.each_with_index do |node, index|
+          next emit_failure_step(code, scope, node) if @compiler.failure_step?(node)
+
+          @compiler.emit_node(code, node, index, scope, unless_flag: flag)
+        end
+        emit_exit(code, scope)
+      end
+
+      private
+
+      # Runs only on the failure track; a recovering one that returns truthy clears the flag;
+      # a fail_fast one (that didn't recover) cuts the track.
+      def emit_failure_step(code, scope, failure)
+        flag = scope.var(:t)
+        code.block("if #{flag} == :failure") do
+          next emit_plain(code, scope, failure) unless failure.recover
+
+          recovered = @compiler.condition(code, failure, scope, type: :recover,
+                                                                error: scope.var(:e), failed_step: scope.var(:s))
+          next code.block("if #{recovered}") { code.line("#{flag} = nil") } unless failure.fail_fast
+
+          code.if_else(recovered, -> { code.line("#{flag} = nil") }, -> { code.line("#{flag} = :fail_fast") })
+        end
+      end
+
+      def emit_plain(code, scope, failure)
+        @compiler.emit_failure_step(code, failure, scope.var(:e), scope.var(:s), scope)
+        code.line("#{scope.var(:t)} = :fail_fast") if failure.fail_fast
+      end
+
+      def emit_exit(code, scope)
+        flag = scope.var(:t)
+        exit = ->(terminus) { -> { scope.base.emit_exit(code, terminus, scope.var(:e), scope.var(:s)) } }
+        code.block("if #{flag}") { code.if_else("#{flag} == :fail_fast", exit.call(:fail_fast), exit.call(:failure)) }
+      end
+    end
+  end
+end

data/lib/octorail/compiler/scopes.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Octorail
+  class Compiler
+    # Where a failure leads from a list of nodes. Emitters ask the scope instead of hard-coding
+    # `return`, so the same step code works at the top level, in a wrap, in a branch and around recovery.
+    class Scope
+      # trace_var: in the traced variant, the local holding the Trace::Node the nodes record into.
+      attr_reader :nodes, :trace_var
+
+      def initialize(nodes, compiler, trace_var: nil)
+        @nodes = nodes
+        @compiler = compiler
+        @trace_var = trace_var
+      end
+
+      # Failure steps are positional: they handle failures of the nodes declared before them.
+      def failure_steps_after(index)
+        @nodes.drop(index + 1).select { |node| node.is_a?(Nodes::Step) && node.failure? }
+      end
+
+      # After the node at `index` failed: its failure steps (up to and including a fail_fast one, which
+      # cuts the track), then the exit. The failed node's own fail_fast skips the failure track.
+      # `error` / `step` are Ruby expressions (literals or locals).
+      def emit_failure(code, index, error, step, fail_fast: false)
+        return emit_exit(code, :fail_fast, error, step) if fail_fast
+
+        failures = failure_steps_after(index)
+        cut = failures.index(&:fail_fast)
+        failures.take(cut ? cut + 1 : failures.size).each do |failure|
+          @compiler.emit_failure_step(code, failure, error, step, self)
+        end
+        emit_exit(code, cut ? :fail_fast : :failure, error, step)
+      end
+
+      # Whether an exit leaves the list (return / next). False under recovery, where an exit only
+      # records the outcome, so the nodes after it are guarded by the flag.
+      def jumps? = true
+    end
+
+    # The operation's own nodes: exits return the Result.
+    class TopScope < Scope
+      def emit_exit(code, terminus, error, step)
+        code.line("return #{@compiler.result}.new(#{terminus.inspect}, ctx, #{error}, #{step})")
+      end
+    end
+
+    # Inside a wrap block `return` would skip the wrapper (and commit an ActiveRecord transaction),
+    # so exits record the outcome in locals and leave the block with `next`.
+    class WrapScope < Scope
+      def initialize(nodes, compiler, id, trace_var: nil)
+        super(nodes, compiler, trace_var:)
+        @id = id
+      end
+
+      def var(name) = "__w#{@id}_#{name}"
+
+      def emit_exit(code, terminus, error, step)
+        code.line("#{var(:t)} = #{terminus.inspect}")
+        code.line("#{var(:e)} = #{error}")
+        code.line("#{var(:s)} = #{step}")
+        code.line("next false")
+      end
+    end
+
+    # A switch branch: no block around it, so a failure inside continues straight into the failure
+    # track after the switch in the enclosing list (unless fail_fast cut it).
+    class BranchScope < Scope
+      def initialize(nodes, compiler, parent, index, trace_var: nil)
+        super(nodes, compiler, trace_var:)
+        @parent = parent
+        @index = index
+      end
+
+      def emit_exit(code, terminus, error, step)
+        return @parent.emit_exit(code, :fail_fast, error, step) if terminus == :fail_fast
+
+        @parent.emit_failure(code, @index, error, step)
+      end
+
+      def jumps? = @parent.jumps?
+
+      def var(name) = @parent.var(name)
+    end
+
+    # A list with a `failure ..., recover: true` step. The railway runs as a flat sequence over a
+    # failure flag: a failure records terminus / error / step in locals; success nodes run only while
+    # the flag is unset, failure steps only while it is :failure; a recovering step that returns truthy
+    # clears it. At the end, a set flag leaves through the scope the list belongs to (`base`).
+    class RecoveryScope < Scope
+      attr_reader :base
+
+      def initialize(base, compiler, id)
+        super(base.nodes, compiler, trace_var: base.trace_var)
+        @base = base
+        @id = id
+      end
+
+      def var(name) = "__r#{@id}_#{name}"
+
+      # Failure steps are separate statements here, run in order under the flag.
+      def failure_steps_after(_index) = []
+
+      def emit_exit(code, terminus, error, step)
+        code.line("#{var(:t)} = #{terminus.inspect}")
+        code.line("#{var(:e)} = #{error}")
+        code.line("#{var(:s)} = #{step}")
+      end
+
+      def jumps? = false
+    end
+  end
+end

data/lib/octorail/compiler/signature.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Octorail
+  class Compiler
+    # Reads a step method's parameters and emits the Ruby code that calls it.
+    class Signature
+      # Up to this many optional kwargs compile to `ctx.key?` branches; more use `ctx.slice`.
+      MAX_OPTIONAL_BRANCHES = 2
+      NON_POSITIONAL = %i[key keyreq keyrest nokey block].freeze
+      # Keywords a failure step may take that come from the failure itself, not from ctx.
+      BOUND = %i[error failed_step].freeze
+
+      def initialize(operation, step, index, branches: true)
+        @operation = operation
+        @step = step
+        @index = index
+        @branches = branches
+        @required = []
+        @optional = []
+        @bound = []
+        parse(operation.instance_method(step.name).parameters)
+      end
+
+      # False when optional kwargs need an if/else tree of `ctx.key?` checks.
+      def single_line?
+        @optional.empty? || !@branches || @optional.size > MAX_OPTIONAL_BRANCHES
+      end
+
+      # `bindings`: Ruby expressions for the bound keywords (error:, failed_step:) of a failure step.
+      def expression(**bindings)
+        @optional.empty? ? call_with([], bindings) : sliced_call(bindings)
+      end
+
+      def emit(code, **bindings)
+        single_line? ? code.line(expression(**bindings)) : emit_branches(code, [], @optional, bindings)
+      end
+
+      private
+
+      def parse(parameters)
+        check_positional!(parameters)
+        parameters.each do |type, name|
+          next @bound << name if bound?(type, name)
+
+          check_not_bound!(type, name)
+
+          case type
+          when :keyreq then @required << name
+          when :key then @optional << name
+          when :keyrest then error!("uses ** in its signature; declare the keys it needs as keyword arguments")
+          end
+        end
+      end
+
+      def bound?(type, name)
+        %i[keyreq key].include?(type) && BOUND.include?(name) && @step.is_a?(Nodes::Step) && @step.failure?
+      end
+
+      # Read from ctx these would be reserved keys (Result::RESERVED_CTX_KEYS): the step could never run.
+      def check_not_bound!(type, name)
+        return unless %i[keyreq key].include?(type) && BOUND.include?(name)
+
+        error!("takes #{name}:, which only failure steps get (it's a reserved key, never in ctx)")
+      end
+
+      def check_positional!(parameters)
+        positional = parameters.map(&:first) - NON_POSITIONAL
+        return if positional == [:req]
+
+        error!("must take ctx as its only positional argument: def #{@step.name}(ctx, ...)")
+      end
+
+      # Pass each optional key only when ctx has it, so the method default applies otherwise.
+      def emit_branches(code, present, rest, bindings)
+        return code.line(call_with(present, bindings)) if rest.empty?
+
+        key, *tail = rest
+        code.if_else(
+          "ctx.key?(#{key.inspect})",
+          -> { emit_branches(code, present + [key], tail, bindings) },
+          -> { emit_branches(code, present, tail, bindings) }
+        )
+      end
+
+      def call_with(optional, bindings)
+        render(base_args(bindings) + optional.map { |key| "#{key}: ctx[#{key.inspect}]" })
+      end
+
+      # ctx.slice keeps only present keys, so absent ones fall back to the method defaults.
+      def sliced_call(bindings)
+        render(base_args(bindings) + ["**ctx.slice(#{@optional.map(&:inspect).join(", ")})"])
+      end
+
+      def base_args(bindings)
+        required = @required.map do |key|
+          missing = "__octorail_missing_key(#{@index}, #{key.inspect}, ctx, #{@step.name.inspect})"
+          "#{key}: ctx.fetch(#{key.inspect}) { #{missing} }"
+        end
+        ["ctx", *required, *@bound.map { |key| "#{key}: #{bindings.fetch(key)}" }]
+      end
+
+      def render(args)
+        "#{@step.name}(#{args.join(", ")})"
+      end
+
+      def error!(message)
+        raise CompileError, "#{@operation}: #{@step.type} #{@step.name.inspect} #{message}" \
+                            "#{Octorail.declared_at(@step)}"
+      end
+    end
+  end
+end

data/lib/octorail/compiler/step_emitter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Octorail
+  class Compiler
+    # Emits step / pass nodes. :failure steps are emitted inside the failure branches of the steps
+    # before them (see Scope#emit_failure), or as guarded statements under recovery.
+    class StepEmitter
+      def initialize(compiler)
+        @compiler = compiler
+      end
+
+      def emit(code, step, index, scope)
+        case step.type
+        when :step then emit_railway(code, step, index, scope)
+        when :pass then emit_pass(code, step, scope)
+        end
+      end
+
+      private
+
+      def emit_pass(code, step, scope)
+        return @compiler.signature(step).emit(code) unless @compiler.traced?
+
+        @compiler.emit_call(code, step, scope)
+      end
+
+      def emit_railway(code, step, index, scope)
+        error = (step.error || :failure).inspect
+        code.block("unless #{@compiler.condition(code, step, scope)}") do
+          scope.emit_failure(code, index, error, step.name.inspect, fail_fast: step.fail_fast)
+        end
+      end
+    end
+  end
+end