octorail 1.0.0

data/lib/octorail/compiler/switch_emitter.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Octorail
+  class Compiler
+    # Emits a switch as a plain `case` over the decider's result.
+    #
+    #   case __s1 = flow_for(ctx, current_user: ctx.fetch(:current_user) { ... })
+    #   when :admin
+    #     unless grant_all(ctx)
+    #       log_failure(ctx)
+    #       return Result.new(:failure, ctx, :failure, :grant_all)
+    #     end
+    #   when :guest
+    #   else
+    #     __octorail_unknown_branch(0, __s1)
+    #   end
+    class SwitchEmitter
+      def initialize(compiler)
+        @compiler = compiler
+      end
+
+      def emit(code, switch, index, scope)
+        id = @compiler.next_id
+        value = "__s#{id}"
+        trace = @compiler.start_trace(code, scope, :switch, switch.decider, id)
+        decide = @compiler.signature(switch, branches: false).expression
+        code.line("case #{value} = #{trace ? "#{trace}.taken(#{decide})" : decide}")
+        emit_branches(code, switch, index, scope, trace)
+        emit_unknown(code, switch, value)
+        @compiler.done_trace(code, scope, trace, "true")
+      end
+
+      private
+
+      def emit_branches(code, switch, index, scope, trace)
+        switch.branches.each do |branch|
+          code.line("when #{branch.keys.map(&:inspect).join(", ")}")
+          branch_scope = BranchScope.new(branch.nodes, @compiler, scope, index, trace_var: trace)
+          code.indented { @compiler.emit_nodes(code, branch_scope) }
+        end
+      end
+
+      def emit_unknown(code, switch, value)
+        code.line("else")
+        code.indented do
+          code.line("__octorail_unknown_branch(#{@compiler.method_index(switch)}, #{value})")
+        end
+        code.line("end")
+      end
+    end
+  end
+end

data/lib/octorail/compiler/tracing.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Octorail
+  class Compiler
+    # Calls of step methods, plain or traced. In the traced variant every call is wrapped into
+    # `trace.run(type, name) { call }`, which records the node (and a raise) and passes the result
+    # through; `trace` is the Ruby expression for the current container node (Scope#trace_var).
+    module Tracing
+      def traced? = @traced
+
+      # A one-line call goes straight into the condition; an if/else tree is assigned to `ok` first.
+      def condition(code, node, scope, type: node.type, **bindings)
+        sig = signature(node)
+        trace = scope.trace_var
+        run = "#{trace}.run(#{type.inspect}, #{node.name.inspect})" if trace
+        return multiline_condition(code, sig, run, bindings) unless sig.single_line?
+
+        call = sig.expression(**bindings)
+        run ? "#{run} { #{call} }" : call
+      end
+
+      def multiline_condition(code, sig, run, bindings)
+        code.line(run ? "ok = #{run} do" : "ok =")
+        code.indented { sig.emit(code, **bindings) }
+        code.line("end") if run
+        "ok"
+      end
+
+      # A call whose result is not used (pass, failure step).
+      def emit_call(code, node, scope, type: node.type, **bindings)
+        call = condition(code, node, scope, type:, **bindings)
+        code.line(call) unless call == "ok"
+      end
+
+      # `__tw1 = __t.start(:wrap, "Transaction")` before a container node; returns the new local.
+      def start_trace(code, scope, type, name, id)
+        return unless traced?
+
+        var = "__t#{type.to_s[0]}#{id}"
+        code.line("#{var} = #{scope.trace_var}.start(#{type.inspect}, #{name.inspect})")
+        var
+      end
+
+      def done_trace(code, scope, var, value)
+        code.line("#{scope.trace_var}.done(#{var}, #{value})") if var
+      end
+
+      # What a trace shows for a wrapper or a nested operation.
+      def trace_label(object)
+        return object.to_s if object.is_a?(Symbol)
+
+        (object.is_a?(Module) && object.name) || object.inspect
+      end
+    end
+  end
+end

data/lib/octorail/compiler/wrap_emitter.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Octorail
+  class Compiler
+    # Emits a wrap: the wrapper call with the inner nodes compiled into its block.
+    #
+    #   __w1_t = __w1_e = __w1_s = nil
+    #   __w1_ok = ::Transaction.call(ctx) do
+    #     __w1_t = __w1_e = __w1_s = nil
+    #     unless charge(ctx)
+    #       __w1_t = :failure; __w1_e = :failure; __w1_s = :charge
+    #       next false
+    #     end
+    #     true
+    #   end
+    #   unless __w1_ok
+    #     ...outer failure steps...
+    #     return Result.new(:failure, ctx, __w1_t ? __w1_e : :failure, __w1_t ? __w1_s : nil)
+    #   end
+    class WrapEmitter
+      def initialize(compiler)
+        @compiler = compiler
+      end
+
+      def emit(code, wrap, index, scope)
+        id = @compiler.next_id
+        trace = @compiler.start_trace(code, scope, :wrap, @compiler.trace_label(wrap.wrapper), id)
+        inner = WrapScope.new(wrap.nodes, @compiler, id, trace_var: trace)
+        emit_block(code, wrap, inner)
+        @compiler.done_trace(code, scope, trace, inner.var(:ok))
+        emit_failure(code, wrap, index, inner, scope)
+      end
+
+      private
+
+      def emit_block(code, wrap, inner)
+        reset = "#{inner.var(:t)} = #{inner.var(:e)} = #{inner.var(:s)} = nil"
+        code.line(reset)
+        code.block("#{inner.var(:ok)} = #{wrapper_call(wrap)} do") do
+          code.line(reset) # again inside: a wrapper may yield more than once (retries)
+          @compiler.emit_nodes(code, inner)
+          code.line("true")
+        end
+      end
+
+      # The wrap failed: a step inside failed (its outcome is in the locals) or the wrapper itself
+      # returned falsy (no locals set, so the wrap's own error / name apply).
+      # A fail_fast inside keeps its meaning outside: the outer failure steps are skipped too.
+      def emit_failure(code, wrap, index, inner, scope)
+        error, step = outcome(wrap, inner)
+        code.block("unless #{inner.var(:ok)}") do
+          next scope.emit_failure(code, index, error, step) unless wrap.steps.any?(&:fail_fast)
+
+          code.if_else("#{inner.var(:t)} == :fail_fast", -> { scope.emit_exit(code, :fail_fast, error, step) },
+                       -> { scope.emit_failure(code, index, error, step) })
+        end
+      end
+
+      # error / failed_step expressions: what the exit inside recorded (even nil), else the wrap's own.
+      def outcome(wrap, inner)
+        exited = inner.var(:t)
+        ["#{exited} ? #{inner.var(:e)} : #{(wrap.error || :failure).inspect}",
+         "#{exited} ? #{inner.var(:s)} : #{wrap.name.inspect}"]
+      end
+
+      def wrapper_call(wrap)
+        wrapper = wrap.wrapper
+        return @compiler.signature(wrap, branches: false).expression if wrapper.is_a?(Symbol)
+
+        "#{@compiler.constant_for(wrapper)}.call(ctx)"
+      end
+    end
+  end
+end

data/lib/octorail/compiler.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "compiler/code"
+require_relative "compiler/signature"
+require_relative "compiler/scopes"
+require_relative "compiler/step_emitter"
+require_relative "compiler/wrap_emitter"
+require_relative "compiler/nested_emitter"
+require_relative "compiler/switch_emitter"
+require_relative "compiler/recovery_emitter"
+require_relative "compiler/nested_cycles"
+require_relative "compiler/tracing"
+
+module Octorail
+  # Turns an operation's nodes into Ruby source for one instance method.
+  # Walks the nodes and hands each to its emitter (compiler/*_emitter.rb); the public
+  # methods below are the toolkit emitters share.
+  class Compiler
+    METHOD_NAME = "__octorail_call"
+    # What `call` runs: METHOD_NAME itself when tracing is off, else a delegate to the traced call.
+    ENTRY_METHOD_NAME = "__octorail_entry"
+    # The traced variant (docs/tracing.md): same flow, records a Trace into `__t` (a Trace::Node).
+    TRACED_METHOD_NAME = "__octorail_traced"
+    # Per-operation Result subclass constant, defined only when the operation declares outputs.
+    RESULT_CONST = "OctorailResult"
+    # Per-operation array of objects (wrappers, nested operations) that have no constant name.
+    REFS_CONST = "OctorailRefs"
+    # Each node type is compiled by its own emitter (compiler/*_emitter.rb).
+    EMITTERS = {
+      Nodes::Step => StepEmitter,
+      Nodes::Wrap => WrapEmitter,
+      Nodes::Nested => NestedEmitter,
+      Nodes::Switch => SwitchEmitter
+    }.freeze
+
+    # Ruby expression for the operation's Result class.
+    attr_reader :result
+    # Objects to store in REFS_CONST; filled while generating the source.
+    attr_reader :anonymous_refs
+
+    include Tracing
+
+    def initialize(operation, traced: false)
+      @operation = operation
+      @traced = traced
+      @steps = operation.steps
+      @method_nodes = operation.method_nodes
+      @outputs = operation.outputs
+      @result = @outputs.empty? ? "::Octorail::Result" : RESULT_CONST
+      @signatures = {}
+      @ids = 0
+      @anonymous_refs = []
+      setup_emitters
+    end
+
+    def source
+      @method_nodes.each { |node| check_method!(node) }
+      NestedCycles.new(@operation).check!
+      code = Code.new
+      header = traced? ? "def #{TRACED_METHOD_NAME}(ctx, __t)" : "def #{METHOD_NAME}(ctx)"
+      code.block(header) do
+        emit_nodes(code, TopScope.new(@steps, self, trace_var: ("__t" if traced?)))
+        emit_success(code)
+        emit_frozen_rescue(code)
+      end
+      code.to_s
+    end
+
+    # Under a non-jumping scope (a branch inside a recovery list) an exit only sets the flag,
+    # so every node after the first runs only while the flag is unset.
+    def emit_nodes(code, scope)
+      return @recovery.emit(code, scope) if RecoveryEmitter.needed?(scope.nodes)
+
+      flag = scope.var(:t) unless scope.jumps?
+      scope.nodes.each_with_index { |node, index| emit_node(code, node, index, scope, unless_flag: flag) }
+    end
+
+    # Emits one node with its emitter; `unless_flag` guards it (except the first and failure steps,
+    # which emit nothing by themselves).
+    def emit_node(code, node, index, scope, unless_flag: nil)
+      emit = -> { @emitters.fetch(node.class).emit(code, node, index, scope) }
+      return emit.call if unless_flag.nil? || index.zero? || failure_step?(node)
+
+      code.block("unless #{unless_flag}", &emit)
+    end
+
+    def failure_step?(node) = node.is_a?(Nodes::Step) && node.failure?
+
+    # A failure step's call; it may take `error:` / `failed_step:`, filled with these expressions.
+    def emit_failure_step(code, failure, error, step, scope)
+      return signature(failure).emit(code, error:, failed_step: step) unless traced?
+
+      emit_call(code, failure, scope, type: :failure, error:, failed_step: step)
+    end
+
+    # Every declared output must be in ctx before the successful result is built.
+    def emit_success(code)
+      @outputs.each do |name|
+        code.line("__octorail_missing_output(#{name.inspect}, ctx) unless ctx.key?(#{name.inspect})")
+      end
+      code.line("#{@result}.new(:success, ctx)")
+    end
+
+    # `branches: false` keeps the call on one line (optional kwargs via ctx.slice), e.g. for a
+    # wrapper method, where an if/else tree would duplicate the whole block.
+    # Per node, not per name: the same method may be a step in two branches of a switch.
+    def signature(node, branches: true)
+      cache = @signatures[branches] ||= {}.compare_by_identity
+      cache[node] ||= Signature.new(@operation, node, method_index(node), branches:)
+    end
+
+    # The node's position in `method_nodes`, baked into the generated error calls (missing key,
+    # unknown branch), so the error names this very declaration, not another one with its name.
+    def method_index(node) = @method_nodes.index { |candidate| candidate.equal?(node) }
+
+    # Unique suffix for the locals of one wrap / nested node.
+    def next_id = @ids += 1
+
+    # A named class/module is referenced by its constant; anything else goes to REFS_CONST.
+    def constant_for(object)
+      name = constant_name(object)
+      return "::#{name}" if name
+
+      @anonymous_refs << object
+      "#{REFS_CONST}[#{@anonymous_refs.size - 1}]"
+    end
+
+    private
+
+    def setup_emitters
+      @emitters = EMITTERS.transform_values { |emitter| emitter.new(self) }
+      @recovery = RecoveryEmitter.new(self)
+    end
+
+    def constant_name(object)
+      name = object.is_a?(Module) && object.name
+      name if name && Object.const_defined?(name) && Object.const_get(name).equal?(object)
+    rescue NameError # a temporary name (Module#set_temporary_name) is not a constant path
+      nil
+    end
+
+    # Free unless raised: turns "can't modify frozen Users::Create" from an ivar write into a clear error.
+    def emit_frozen_rescue(code)
+      code.dedented { code.line("rescue FrozenError => e") }
+      code.line("__octorail_frozen!(e)")
+    end
+
+    # Methods every object has (Kernel#test, Object#display, ...) don't count as a step's method.
+    def check_method!(node)
+      name = node.name
+      defined = @operation.method_defined?(name) || @operation.private_method_defined?(name)
+      owner = @operation.instance_method(name).owner if defined
+      return if defined && !(owner >= Operation)
+
+      builtin = " (only #{owner}##{name}, which is not a step)" if defined
+      raise CompileError, "#{@operation}: #{node.type} #{name.inspect} has no instance method ##{name}#{builtin}" \
+                          "#{Octorail.declared_at(node)}"
+    end
+  end
+end

data/lib/octorail/config.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Octorail
+  # Global settings (docs/configuration.md). An operation overrides them with `configure` (dsl/settings.rb).
+  class Config
+    # Settings an operation may override, with their allowed values.
+    OPERATION_SETTINGS = { trace: Trace::LEVELS }.freeze
+
+    attr_reader :trace
+
+    def initialize
+      @trace = :off
+    end
+
+    # Changes compiled code, so every compiled operation recompiles on its next call.
+    def trace=(level)
+      @trace = Config.check!(:trace, level, "Octorail.config")
+      Operation.invalidate!
+    end
+
+    def self.check!(key, value, owner)
+      allowed = OPERATION_SETTINGS.fetch(key)
+      return value if allowed.include?(value)
+
+      raise ArgumentError, "#{owner}: #{key} must be one of #{Octorail.key_list(allowed)}, got #{value.inspect}"
+    end
+  end
+
+  def self.config = @config ||= Config.new
+
+  def self.configure
+    yield config
+    config
+  end
+end

data/lib/octorail/dsl/nested.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Octorail
+  module DSL
+    # nested: run another operation as a step, on the same ctx.
+    module Nested
+      def nested(operation, error: nil, fail_fast: false)
+        check_not_abstract!("nested #{operation}")
+        check_nested!(operation, error, fail_fast)
+        current_nodes << Nodes::Nested.new(operation:, error:, fail_fast:, location: declaration_location)
+        invalidate!
+        nil
+      end
+
+      private
+
+      def check_nested!(operation, error, fail_fast)
+        unless operation.is_a?(Class) && operation < Operation
+          raise ArgumentError, "#{self}: nested: expected an Octorail::Operation subclass, got #{operation.inspect}"
+        end
+
+        check_not_recursive!(operation)
+        unless error.nil? || error.is_a?(Symbol)
+          raise ArgumentError, "#{self}: nested #{operation}: error: must be a Symbol, got #{error.inspect}"
+        end
+        return if [true, false].include?(fail_fast)
+
+        raise ArgumentError, "#{self}: nested #{operation}: fail_fast: must be true or false, got #{fail_fast.inspect}"
+      end
+
+      # A subclass inherits this very nested step, so nesting it would recurse forever too.
+      def check_not_recursive!(operation)
+        return unless operation <= self
+
+        what = operation.equal?(self) ? "itself" : "its own subclass"
+        raise ArgumentError, "#{self}: nested #{operation}: an operation can't nest #{what}"
+      end
+    end
+  end
+end

data/lib/octorail/dsl/outputs.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Octorail
+  module DSL
+    # output: the operation's declared public result keys.
+    module Outputs
+      def output(*names)
+        check_not_abstract!("output #{names.map(&:inspect).join(", ")}")
+        names.each do |name|
+          check_output!(name)
+          own_outputs << name unless outputs.include?(name)
+          # A subclass that declared it already now inherits it instead.
+          descendants.each { |subclass| subclass.__send__(:own_outputs).delete(name) }
+        end
+        invalidate!
+        nil
+      end
+
+      def outputs
+        parent = superclass.respond_to?(:outputs) ? superclass.outputs : []
+        parent + own_outputs
+      end
+
+      private
+
+      def own_outputs = @own_outputs ||= []
+
+      def check_output!(name)
+        check_name!(name, "output")
+        return unless Result::BUILTIN_KEYS.include?(name) || Result.method_defined?(name) ||
+                      Result.private_method_defined?(name)
+
+        raise ArgumentError, "#{self}: output #{name.inspect} collides with a Result field or method"
+      end
+    end
+  end
+end

data/lib/octorail/dsl/settings.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Octorail
+  module DSL
+    # configure: per-operation settings over the global Octorail.config (docs/configuration.md).
+    # Allowed in an abstract! base too: these are settings, not flow.
+    module Settings
+      def configure(**settings)
+        settings.each do |key, value|
+          unless Config::OPERATION_SETTINGS.key?(key)
+            raise ArgumentError, "#{self}: configure: unknown setting #{key.inspect}, " \
+                                 "allowed: #{Octorail.key_list(Config::OPERATION_SETTINGS.keys)}"
+          end
+
+          own_settings[key] = Config.check!(key, value, "#{self}: configure")
+        end
+        invalidate!
+        nil
+      end
+
+      # The operation's own value, else the nearest ancestor's, else the global one.
+      def setting(key)
+        return own_settings[key] if own_settings.key?(key)
+        return superclass.setting(key) if superclass.respond_to?(:setting)
+
+        Octorail.config.public_send(key)
+      end
+
+      private
+
+      def own_settings = @own_settings ||= {}
+    end
+  end
+end

data/lib/octorail/dsl/steps.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Octorail
+  module DSL
+    # step / pass / failure.
+    module Steps
+      OPTIONS = {
+        step: %i[error fail_fast],
+        pass: [],
+        failure: %i[fail_fast recover]
+      }.freeze
+      FLAGS = %i[fail_fast recover].freeze
+      BOOLEANS = [true, false].freeze
+
+      def step(name, **options) = add_step(:step, name, options)
+      def pass(name, **options) = add_step(:pass, name, options)
+      def failure(name, **options) = add_step(:failure, name, options)
+
+      # Top-level nodes (steps, wraps, nested, switches) in execution order: inherited ones first, then own.
+      def steps
+        parent = superclass.respond_to?(:steps) ? superclass.steps : []
+        parent + own_steps
+      end
+
+      # Every step and nested operation, including the ones inside wraps and branches, in declaration order.
+      def all_steps = Nodes.leaves(steps)
+
+      # Nodes whose instance method the compiled code calls: steps, Symbol wrappers, switch deciders.
+      def method_nodes
+        Nodes.walk(steps).select do |node|
+          node.is_a?(Nodes::Step) || node.is_a?(Nodes::Switch) || (node.is_a?(Nodes::Wrap) && node.name)
+        end
+      end
+
+      def step_method_names = method_nodes.map(&:name)
+
+      private
+
+      def own_steps = @own_steps ||= []
+
+      # Where a step declared right now goes: the innermost open wrap block, or the class itself.
+      def current_nodes
+        @__octorail_nesting&.last || own_steps
+      end
+
+      # Steps of this class's whole line: ancestors, itself (with open wrap / branch blocks) and
+      # descendants, so that reopening a parent can't duplicate a step a subclass already has.
+      # Steps in other branches of a switch being declared are left out: branches never both run.
+      def related_steps
+        pending = (@__octorail_nesting || []).flatten
+        nodes = steps + pending + descendants.flat_map { |subclass| subclass.__send__(:own_steps) }
+        siblings = sibling_branch_steps
+        Nodes.leaves(nodes).grep(Nodes::Step).reject { |node| siblings.any? { |sibling| sibling.equal?(node) } }
+      end
+
+      def add_step(type, name, options)
+        check_not_abstract!("#{type} #{name.inspect}")
+        check_name!(name, type)
+        check_options!(type, name, options)
+        check_duplicate_step!(type, name)
+
+        current_nodes << Nodes::Step.new(type:, name:, location: declaration_location, **options)
+        invalidate!
+        nil
+      end
+
+      def check_duplicate_step!(type, name)
+        original = related_steps.find { |node| node.name == name }
+        if original
+          raise ArgumentError, "#{self}: #{type} #{name.inspect} is already declared " \
+                               "(#{original.type} #{name.inspect})#{Octorail.declared_at(original)}"
+        end
+
+        check_sibling_type!(type, name)
+      end
+
+      # A method reused in another branch keeps its type: a failure step's `error:` / `failed_step:`
+      # come from the failure, a step's from ctx, and one compiled method can't be both.
+      def check_sibling_type!(type, name)
+        sibling = sibling_branch_steps.find { |node| node.is_a?(Nodes::Step) && node.name == name }
+        return if sibling.nil? || sibling.type == type
+
+        raise ArgumentError, "#{self}: #{type} #{name.inspect} is #{sibling.type} #{name.inspect} in another " \
+                             "branch; a step reused across branches keeps its type#{Octorail.declared_at(sibling)}"
+      end
+
+      def check_options!(type, name, options)
+        label = "#{self}: #{type} #{name.inspect}"
+        allowed = OPTIONS.fetch(type)
+        unknown = options.keys - allowed
+        raise ArgumentError, "#{label}: unknown options #{unknown.inspect}, allowed: #{allowed.inspect}" if unknown.any?
+
+        check_option_values!(label, options)
+      end
+
+      def check_option_values!(label, options)
+        error = options[:error]
+        unless error.nil? || error.is_a?(Symbol)
+          raise ArgumentError, "#{label}: error: must be a Symbol, got #{error.inspect}"
+        end
+
+        FLAGS.each do |flag|
+          value = options.fetch(flag, false)
+          next if BOOLEANS.include?(value)
+
+          raise ArgumentError, "#{label}: #{flag}: must be true or false, got #{value.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/octorail/dsl/switches.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Octorail
+  module DSL
+    # switch / on: run one of several branches, picked by a decider method's result.
+    module Switches
+      def switch(decider, &block)
+        check_not_abstract!("switch #{decider.inspect}")
+        check_name!(decider, "switch")
+        raise ArgumentError, "#{self}: switch #{decider.inspect} needs a block with on(...) branches" unless block
+
+        location = declaration_location
+        branches = collect_branches(decider, &block)
+        raise ArgumentError, "#{self}: switch #{decider.inspect} has no on(...) branches" if branches.empty?
+
+        current_nodes << Nodes::Switch.new(decider:, branches:, location:)
+        invalidate!
+        nil
+      end
+
+      # A branch without a block is an explicit "nothing to do for these keys".
+      def on(*keys, &block)
+        switch = @__octorail_switches&.last
+        unless switch && @__octorail_nesting.size == switch[:depth]
+          raise ArgumentError, "#{self}: on(...) is only allowed directly inside a switch block"
+        end
+
+        check_branch_keys!(switch, keys)
+        switch[:branches] << Nodes::Branch.new(keys:, nodes: block ? collect_nodes(&block) : [])
+        nil
+      end
+
+      private
+
+      # Steps declared in the switch block but outside on(...) land in its own buffer: an error.
+      def collect_branches(decider, &)
+        switch = { decider:, branches: [], keys: [] }
+        (@__octorail_switches ||= []).push(switch)
+        stray = collect_nodes do
+          switch[:depth] = @__octorail_nesting.size
+          yield
+        end
+        return switch[:branches] if stray.empty?
+
+        raise ArgumentError, "#{self}: switch #{decider.inspect}: steps must be inside on(...) branches"
+      ensure
+        @__octorail_switches.pop
+      end
+
+      def check_branch_keys!(switch, keys)
+        label = "#{self}: switch #{switch[:decider].inspect}"
+        raise ArgumentError, "#{label}: on needs at least one key" if keys.empty?
+        raise ArgumentError, "#{label}: on #{keys.inspect} repeats a key" if keys.uniq.size < keys.size
+
+        keys.each { |key| check_branch_key!(label, switch, key) }
+        switch[:keys].concat(keys)
+      end
+
+      def check_branch_key!(label, switch, key)
+        raise ArgumentError, "#{label}: on keys must be Symbols, got #{key.inspect}" unless key.is_a?(Symbol)
+        raise ArgumentError, "#{label}: on #{key.inspect} is already a branch" if switch[:keys].include?(key)
+      end
+
+      # Steps of the finished branches of every switch being declared right now.
+      def sibling_branch_steps
+        branches = (@__octorail_switches || []).flat_map { |switch| switch[:branches] }
+        Nodes.leaves(branches.flat_map(&:nodes))
+      end
+    end
+  end
+end