actionable-rb 1.9.0

data/lib/actionable/action.rb

@@ -0,0 +1,1220 @@
+# frozen_string_literal: true
+
+module Actionable
+  # Base class for service objects. Subclass it, declare an ordered list of
+  # steps with {.step}, implement each step as an instance method, and run it
+  # with {.run} (decisions D1/D2).
+  #
+  #   class Greet < Actionable::Action
+  #     step :build_message
+  #     def build_message = @message = 'hello'
+  #   end
+  #
+  #   Greet.run # => #<Actionable::Success ...>
+  class Action
+    # The failure codes the gem itself emits: +:invalid_input+ (input failed
+    # validation, or no shape matched a discriminator) and +:invalid_output+
+    # (a success's output failed validation). An action that declares failures
+    # with {.fails} may still end with these without declaring them (decision
+    # D20); declaring one only attaches metadata to it.
+    # @return [Array<Symbol>]
+    GEM_FAILURE_CODES = %i[invalid_input invalid_output].freeze
+
+    # Ruby's core classes, whose methods (+puts+, +exit+, +hash+…) never count
+    # as an action implementing a step or hook.
+    # @return [Array<Module>]
+    CORE_METHOD_OWNERS = [Kernel, Object, BasicObject].freeze
+
+    # What a +fail+ / +skip+ code must look like: a Ruby identifier (letters,
+    # digits and underscores, not starting with a digit), optionally ending
+    # in +?+ or +!+. Refuses a sentence, which is +Kernel#fail+ habit
+    # (owner ruling R5).
+    # @return [Regexp]
+    CODE_FORMAT = /\A[[:alpha:]_][[:alnum:]_]*[?!]?\z/
+
+    class << self
+      # The ordered, deduplicated set of steps declared on this action.
+      # A +Set+ keyed by step identity ([type, name]) so a redeclared step
+      # collapses to one entry; insertion order is preserved (decision D2).
+      # The last declaration of a step wins and keeps the first one's position
+      # (see {.step}).
+      #
+      # @return [Set<Steps::Base>]
+      def steps
+        @steps ||= Set.new
+      end
+
+      # Output field names that would collide with the result's own attributes
+      # (so delegation silently breaks) or with the action's reserved instance
+      # variables (+@result+ / +@input+, which the runner reads). Declaring one
+      # raises a {DefinitionError} (decisions D18/D20).
+      # @return [Array<Symbol>]
+      RESERVED_OUTPUT_FIELDS = %i[code message output history errors metadata result input].freeze
+
+      # Declare the action's typed output schema, or read it back.
+      #
+      # With a block, builds an anonymous +FieldStruct::Base+ subclass from the
+      # FieldStruct DSL (+required+/+optional+/…) and stores it as this action's
+      # output schema (decision D6). At the end of a run the {Runner} captures
+      # the instance variables whose names match declared fields, coerces them
+      # through the schema, and assigns the struct to +result.output+. Field names
+      # in {RESERVED_OUTPUT_FIELDS} raise a {DefinitionError}.
+      #
+      #   output do
+      #     required :invoice, Invoice
+      #     optional :receipt, Receipt
+      #   end
+      #
+      # @yield the FieldStruct field declarations
+      # @raise [DefinitionError] when a field name is reserved
+      # @return [Class<FieldStruct::Base>, nil] the output schema, or +nil+ when
+      #   none has been declared (the free-form path)
+      def output(&block)
+        return @output_schema unless block
+
+        @output_schema = build_output_schema(block)
+      end
+
+      # @return [Class<FieldStruct::Base>, nil] the declared output schema, or
+      #   +nil+ for a free-form action
+      attr_reader :output_schema
+
+      # Declare the action's typed input schema (decision D7). Builds an
+      # anonymous +FieldStruct::Base+ subclass from the FieldStruct DSL; +.run+
+      # then coerces its arguments into this schema, validates them, and exposes
+      # the struct to steps via the instance's +input+ reader. Declaring input
+      # takes over the constructor role — steps read +input.field+ rather than
+      # capturing positional/keyword args in a custom +initialize+.
+      #
+      #   input do
+      #     required :amount, :big_decimal
+      #     optional :name,   :string
+      #   end
+      #
+      # Called without a block it reads the declared schema, as {.output} does.
+      #
+      # @yield the FieldStruct field declarations
+      # @return [Class<FieldStruct::Base>, nil] the input schema, or +nil+ when
+      #   none has been declared
+      def input(&block)
+        return @input_schema unless block
+
+        @input_schema = Class.new(FieldStruct::Base, &block)
+      end
+
+      # @return [Class<FieldStruct::Base>, nil] the declared input schema, or
+      #   +nil+ for a free-form action
+      attr_reader :input_schema
+
+      # Declare a *discriminated* input schema (decision D19): pick the input
+      # FieldStruct at run time from a discriminator value, instead of a single
+      # fixed schema. The block declares branches with +on(value, Schema)+ and an
+      # optional +default(Schema)+; +.run+ reads the discriminator from its
+      # keyword arguments, chooses the schema, then coerces and validates exactly
+      # like a fixed +input+. An unmatched value with no +default+ short-circuits
+      # to +Failure(:invalid_input)+.
+      #
+      #   input_for :event_type do
+      #     on 'sale',   SaleShape
+      #     on 'refund', RefundShape
+      #     default      UnknownShape
+      #   end
+      #
+      # @param discriminator [Symbol, String] the kwarg whose value selects the schema
+      # @yield the branch declarations (+on+ / +default+)
+      # @return [InputDispatch] the stored dispatch
+      def input_for(discriminator, &block)
+        @input_dispatch = InputDispatch.define(discriminator, &block)
+      end
+
+      # @return [InputDispatch, nil] the discriminated-input dispatch, or +nil+
+      #   when input isn't discriminated
+      attr_reader :input_dispatch
+
+      # Declare one failure code this action can end with, and the metadata a
+      # failure with that code carries (decision D20).
+      #
+      # The metadata is neutral: arbitrary keywords the gem stores, attaches to
+      # the {Failure} as +result.metadata+, and shows in {.describe}, but never
+      # interprets. A host app gives the keys their meaning (say, +kind:+ for
+      # how an adapter answers the failure). +message+ is the default message
+      # for a +fail+ that gives none.
+      #
+      #   fails :refused, 'the card was refused', kind: :rejected
+      #   fails :not_found, kind: :not_found
+      #
+      # Declarations are inherited and a subclass can add to them; redeclaring a
+      # code replaces its message and metadata. Once an action declares any
+      # code, failing with an undeclared one raises a {DefinitionError} at the
+      # +fail+ call; the {GEM_FAILURE_CODES} are exempt.
+      #
+      # A block declares the output a failure with this code carries, in the
+      # FieldStruct DSL of {.output} (decision D23); see {.failure_output_schema}.
+      #
+      # @param code [Symbol, String] the failure code
+      # @param message [String, nil] the default message for this code
+      # @param metadata [Object] per-code metadata, passed through
+      # @yield the FieldStruct field declarations of this code's output
+      # @raise [DefinitionError] when an output field name is reserved
+      # @return [Hash{Symbol=>Hash{Symbol=>Object}}] {.declared_failures}
+      def fails(code, message = nil, **metadata, &block)
+        failure_declarations[code.to_sym] = declaration(message, metadata, block)
+        declared_failures
+      end
+
+      # The output schema declared for failure +code+ with a {.fails} block, or
+      # +nil+ when the code has none (decision D23).
+      #
+      # @param code [Symbol, String]
+      # @return [Class<FieldStruct::Base>, nil]
+      def failure_output_schema(code)
+        failure_declarations.dig(code.to_sym, :output_schema)
+      end
+
+      # The failure codes this action declares with {.fails}, each mapped to its
+      # metadata (decision D20). Empty when the action declares none.
+      #
+      # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+      def declared_failures
+        failure_declarations.transform_values { |declaration| declaration[:metadata] }
+      end
+
+      # Whether this action may end with a failure of +code+ (decision D20):
+      # always when it declares no failures, otherwise when it declares +code+
+      # or +code+ is one of the {GEM_FAILURE_CODES}. The check behind the
+      # strictness guard, the RSpec stubs and +and_fail+.
+      #
+      # @param code [Symbol, String]
+      # @return [Boolean]
+      def allows_failure_code?(code)
+        code = code.to_sym
+        failure_declarations.empty? || failure_declarations.key?(code) || GEM_FAILURE_CODES.include?(code)
+      end
+
+      # Every {.fails} declaration, keyed by code, as +{message:, metadata:}+.
+      # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+      def failure_declarations
+        @failure_declarations ||= {}
+      end
+
+      # Declare one skip code this action can end with, and the metadata a skip
+      # with that code carries (decision D21). The skip counterpart of {.fails}.
+      #
+      # The metadata is neutral: arbitrary keywords the gem stores, attaches to
+      # the {Skipped} as +result.metadata+, and shows in {.describe}, but never
+      # interprets. +message+ is the default message for a +skip+ that gives
+      # none.
+      #
+      #   skips :not_ready, 'the field is not created yet', retry: true
+      #   skips :already_synced
+      #
+      # Declarations are inherited and a subclass can add to them; redeclaring a
+      # code replaces its message and metadata. Once an action declares any
+      # skip, skipping with an undeclared code raises a {DefinitionError} at the
+      # +skip+ call, and that includes +skip+'s implicit default +:skipped+.
+      #
+      # A block declares the output a skip with this code carries, in the
+      # FieldStruct DSL of {.output} (decision D23); see {.skip_output_schema}.
+      #
+      #   skips :already_active do
+      #     required :id, :integer
+      #   end
+      #
+      # @param code [Symbol, String] the skip code
+      # @param message [String, nil] the default message for this code
+      # @param metadata [Object] per-code metadata, passed through
+      # @yield the FieldStruct field declarations of this code's output
+      # @raise [DefinitionError] when an output field name is reserved
+      # @return [Hash{Symbol=>Hash{Symbol=>Object}}] {.declared_skips}
+      def skips(code, message = nil, **metadata, &block)
+        skip_declarations[code.to_sym] = declaration(message, metadata, block)
+        declared_skips
+      end
+
+      # The output schema declared for skip +code+ with a {.skips} block, or
+      # +nil+ when the code has none (decision D23).
+      #
+      # @param code [Symbol, String]
+      # @return [Class<FieldStruct::Base>, nil]
+      def skip_output_schema(code)
+        skip_declarations.dig(code.to_sym, :output_schema)
+      end
+
+      # The gem result class each outcome {Result#status} stands for, which an
+      # action with typed outcomes subclasses once per outcome (decision D23).
+      # @return [Hash{Symbol=>Class<Result>}]
+      OUTCOME_BASES = {success: Success, failure: Failure, skipped: Skipped}.freeze
+
+      # Turn typed outcomes on (or off) for this action and its descendants
+      # (decision D23). With it on, a skip or failure whose code declares no
+      # output schema carries an empty output instead of a best-effort capture,
+      # and {.run} returns the action's own result classes: +Success+,
+      # +Failure+ and +Skipped+ defined inside it, each a subclass of the gem
+      # class (or of the parent action's own, for a subclass).
+      #
+      # @param enabled [Boolean]
+      # @raise [DefinitionError] when the action already has a constant of its
+      #   own named +Success+, +Failure+ or +Skipped+
+      # @return [Boolean] the new setting
+      def typed_outcomes(enabled: true)
+        @typed_outcomes = enabled ? true : false
+        define_outcome_classes if @typed_outcomes
+        @typed_outcomes
+      end
+
+      # @return [Boolean] whether typed outcomes are on (decision D23)
+      def typed_outcomes?
+        @typed_outcomes ? true : false
+      end
+
+      # The skip codes this action declares with {.skips}, each mapped to its
+      # metadata (decision D21). Empty when the action declares none.
+      #
+      # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+      def declared_skips
+        skip_declarations.transform_values { |declaration| declaration[:metadata] }
+      end
+
+      # Whether this action may end with a skip of +code+ (decision D21): always
+      # when it declares no skips, otherwise only when it declares +code+. The
+      # gem emits no skip codes of its own, so nothing is exempt, +skip+'s
+      # default +:skipped+ included. The check behind the strictness guard, the
+      # RSpec skip stubs and +and_skip+.
+      #
+      # @param code [Symbol, String]
+      # @return [Boolean]
+      def allows_skip_code?(code)
+        skip_declarations.empty? || skip_declarations.key?(code.to_sym)
+      end
+
+      # Every {.skips} declaration, keyed by code, as +{message:, metadata:}+
+      # (decision D21).
+      #
+      # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+      def skip_declarations
+        @skip_declarations ||= {}
+      end
+
+      # Declare a step. The step type is inferred from +target+ (a Symbol or
+      # String names an instance method — a {Steps::Method}).
+      #
+      # Redeclaring a step of the same type and name (here or in a subclass)
+      # replaces the earlier declaration's options in place: the last
+      # declaration wins and keeps the original position. A subclass's
+      # override never changes the parent's steps.
+      #
+      # @param target [Symbol, String] the step target
+      # @param options [Object] step options (e.g. +:if+, +:unless+)
+      # @return [Set<Steps::Base>] the updated step set
+      def step(target, **options)
+        declare(steps, Steps.build(target, **options))
+      end
+
+      # Lifecycle hooks that run after the main steps when the run succeeds.
+      # @return [Set<Steps::Base>]
+      def success_hooks
+        @success_hooks ||= Set.new
+      end
+
+      # Lifecycle hooks that run after the main steps when the run fails.
+      # @return [Set<Steps::Base>]
+      def failure_hooks
+        @failure_hooks ||= Set.new
+      end
+
+      # Lifecycle hooks that run after the main steps when the run was skipped.
+      # @return [Set<Steps::Base>]
+      def skip_hooks
+        @skip_hooks ||= Set.new
+      end
+
+      # Lifecycle hooks that run after the main steps regardless of outcome.
+      # @return [Set<Steps::Base>]
+      def always_hooks
+        @always_hooks ||= Set.new
+      end
+
+      # Declare a hook that runs at the end of a run iff it succeeded (D2).
+      # @param target [Symbol, String] the instance method to run
+      # @param options [Object] step options (e.g. +:if+)
+      # @return [Set<Steps::Base>]
+      def on_success(target, **options)
+        declare(success_hooks, Steps.build(target, **options))
+      end
+
+      # Declare a hook that runs at the end of a run iff it failed (D2).
+      # @param target [Symbol, String] the instance method to run
+      # @param options [Object] step options (e.g. +:if+)
+      # @return [Set<Steps::Base>]
+      def on_failure(target, **options)
+        declare(failure_hooks, Steps.build(target, **options))
+      end
+
+      # Declare a hook that runs at the end of a run iff it was skipped (D17).
+      # @param target [Symbol, String] the instance method to run
+      # @param options [Object] step options (e.g. +:if+)
+      # @return [Set<Steps::Base>]
+      def on_skip(target, **options)
+        declare(skip_hooks, Steps.build(target, **options))
+      end
+
+      # Declare a hook that runs at the end of a run regardless of outcome (D2).
+      # @param target [Symbol, String] the instance method to run
+      # @param options [Object] step options (e.g. +:if+)
+      # @return [Set<Steps::Base>]
+      def always(target, **options)
+        declare(always_hooks, Steps.build(target, **options))
+      end
+
+      # Declare a branching step (decision D3). The switch value is read from
+      # +value_source+ (an instance method); the block declares branches with
+      # +on(value, target)+ and an optional +default(target)+.
+      #
+      #   case_step :status do
+      #     on 'active', :handle_active
+      #     default :handle_unknown
+      #   end
+      #
+      # @param value_source [Symbol, String] the method whose value is switched on
+      # @param options [Object] step options (e.g. +:if+, +:unless+)
+      # @yield the branch declarations
+      # @return [Set<Steps::Base>] the updated step set
+      def case_step(value_source, **options, &block)
+        declare(steps, Steps::Case.define(value_source, **options, &block))
+      end
+
+      # Enable or read the action's measurement mode (decisions D10/D19). +:all+
+      # records an execution {History}; +:none+ (the default) records nothing for
+      # zero overhead; +:sampled+ records on a fraction of runs (+rate:+ between 0
+      # and 1) for low-overhead production observability. A measuring run cascades
+      # into the nested actions it invokes regardless of their own setting.
+      #
+      #   measure :sampled, rate: 0.1   # record ~10% of runs
+      #
+      # @param mode [:all, :none, :sampled, nil] the mode to set; omit to read
+      # @param rate [Numeric, nil] required for +:sampled+ — the probability
+      #   (0..1) that a given run is measured
+      # @raise [ArgumentError] on an unknown mode, or +:sampled+ without a valid rate
+      # @return [:all, :none, :sampled] the resolved mode
+      def measure(mode = nil, rate: nil)
+        unless mode.nil?
+          raise ArgumentError, "unknown measure mode #{mode.inspect}" unless %i[all none sampled].include?(mode)
+
+          if mode == :sampled && !(rate.is_a?(Numeric) && rate.between?(0, 1))
+            raise ArgumentError, "measure :sampled requires rate: between 0 and 1, got #{rate.inspect}"
+          end
+
+          @measure = mode
+          @measure_rate = rate if mode == :sampled
+        end
+        @measure ||= :none
+      end
+
+      # @return [Float, nil] the sampling rate for +:sampled+ mode, else +nil+
+      attr_reader :measure_rate
+
+      # @return [Boolean] whether this action always records history
+      def measure_all?
+        measure == :all
+      end
+
+      # @return [Boolean] whether this action samples history
+      def measure_sampled?
+        measure == :sampled
+      end
+
+      # The per-run sampling decision: true with probability {.measure_rate} when
+      # in +:sampled+ mode, false otherwise. Rolled once per run by the {Runner}.
+      #
+      # @return [Boolean]
+      def measure_sample_hit?
+        measure_sampled? && rand < measure_rate
+      end
+
+      # A structured, at-a-glance summary of the action — its name, input/output
+      # field metadata, ordered steps (with type), declared failures and skips
+      # (each code's message and metadata, decisions D20/D21), lifecycle hooks, measurement mode,
+      # and transaction config (decision D18). Lets humans and agents
+      # understand an action without reading its source.
+      #
+      # @return [Hash{Symbol=>Object}]
+      def describe
+        {
+          name: name,
+          input: input_descriptor,
+          output: output_schema&.metadata&.to_h,
+          steps: steps.map { |step| {type: step.kind, name: step.name, options: step.options} },
+          failures: describe_declarations(failure_declarations),
+          skips: describe_declarations(skip_declarations),
+          hooks: {
+            on_success: success_hooks.map(&:name),
+            on_failure: failure_hooks.map(&:name),
+            on_skip: skip_hooks.map(&:name),
+            always: always_hooks.map(&:name)
+          },
+          measure: measure,
+          transactional: respond_to?(:transaction_config) ? transaction_config : nil
+        }
+      end
+
+      # A human/agent-readable rendering of {.describe} — the same information as
+      # a multi-line summary instead of a Hash (decision D18). The input/output
+      # field lines reuse FieldStruct's own +Metadata#describe+ (type,
+      # required-ness, and the options each field's type accepts); declared
+      # failures, declared skips and hook sections are listed only when there are any.
+      #
+      #   Greet.describe_text
+      #   # => "Greet (measure: none)\n  Input: (free-form)\n  ..."
+      #
+      # @return [String]
+      def describe_text
+        summary = describe
+        transactional = summary[:transactional] ? ', transactional' : ''
+        lines = ["#{summary[:name] || "action"} (measure: #{summary[:measure]}#{transactional})"]
+
+        lines << "  Input:#{input_summary}"
+        lines << "  Output:#{schema_summary(output_schema)}"
+
+        lines << '  Steps:'
+        steps_summary = summary[:steps]
+        lines << '    (none)' if steps_summary.empty?
+        steps_summary.each { |step| lines << "    - #{step[:name]} (#{step[:type]})" }
+
+        lines.concat(declarations_summary('Failures', failure_declarations))
+        lines.concat(declarations_summary('Skips', skip_declarations))
+
+        present_hooks = summary[:hooks].reject { |_, names| names.empty? }
+        unless present_hooks.empty?
+          lines << '  Hooks:'
+          present_hooks.each { |section, names| lines << "    #{section}: #{names.join(", ")}" }
+        end
+
+        lines.join("\n")
+      end
+
+      # Run the action. With a declared input schema, coerce the arguments
+      # (keyword args, or a single input-schema instance) into the input struct
+      # and validate it — a required input that is missing or won't coerce
+      # short-circuits to a +Failure(:invalid_input)+ without running any steps
+      # (decision D7). Without an input schema, the arguments are forwarded
+      # verbatim to the action's constructor (the free-form path).
+      #
+      # Under typed outcomes the result is an instance of the action's own
+      # result class for its outcome (decision D23).
+      #
+      # @param args [Object] positional arguments: a single input-schema
+      #   instance, or (free-form) whatever the constructor takes
+      # @param kwargs [Object] keyword arguments: the input fields, or
+      #   (free-form) whatever the constructor takes
+      # @return [Result] the run's {Success} or {Failure}
+      def run(*args, **kwargs)
+        typed_result(run_untyped(args, kwargs))
+      end
+
+      # Run the action once per item in +enumerable+, collecting the per-item
+      # results into a {BatchResult} (decision D19). The single most common
+      # batch/ingest shape: each item runs independently (its own {.run}, its own
+      # outcome), so one item's failure never affects another, and the aggregate
+      # is inspectable via {BatchResult#all_ok?} / +#any_failure?+ / +#partial?+.
+      #
+      # The optional block maps each item to +.run+ arguments: return a Hash for
+      # keyword args, an Array for positional args, or any other value to pass as
+      # a single argument. Without a block, each item is passed to +.run+
+      # directly.
+      #
+      #   ImportRow.run_each(rows) { |row| {row: row} }
+      #   Charge.run_each(amounts) # => each amount passed to .run
+      #
+      # @param enumerable [Enumerable] the items to run
+      # @yieldparam item [Object] one element of +enumerable+
+      # @yieldreturn [Hash, Array, Object] the +.run+ arguments for that item
+      # @return [BatchResult] the per-item results
+      def run_each(enumerable, &block)
+        results = enumerable.map do |item|
+          args = block ? block.call(item) : item
+          case args
+          when Hash then run(**args)
+          when Array then run(*args)
+          else run(args)
+          end
+        end
+        BatchResult.new(results)
+      end
+
+      private
+
+      # The body of {.run}: build the input, then run the steps.
+      #
+      # @param args [Array<Object>]
+      # @param kwargs [Hash{Symbol=>Object}]
+      # @return [Result]
+      def run_untyped(args, kwargs)
+        if input_schema || input_dispatch
+          input = build_input(args, kwargs)
+          return input if input.is_a?(Failure) # unmatched discriminator
+          return invalid_input_failure(input) unless input.valid?
+
+          instance = new
+          instance.instance_variable_set(:@input, input)
+        else
+          instance = new(*args, **kwargs)
+        end
+
+        ensure_steps_implemented!(instance)
+        ensure_verbs_last! unless @verbs_checked || !Actionable.verb_position_check?
+        Runner.new(instance).run
+      end
+
+      # Define this action's own +Success+, +Failure+ and +Skipped+ (decision
+      # D23), each subclassing the parent action's own when it has them, else
+      # the gem class. Defined once; a later call is a no-op.
+      #
+      # @raise [DefinitionError] when the action has its own constant by one
+      #   of those names
+      # @return [Hash{Symbol=>Class<Result>}] status => result class
+      def define_outcome_classes
+        @define_outcome_classes ||= OUTCOME_BASES.to_h do |status, base|
+          [status, define_outcome_class(base.name.split('::').last.to_sym, status, base)]
+        end
+      end
+
+      # @param const [Symbol] the constant to define
+      # @param status [Symbol] the outcome {Result#status}
+      # @param base [Class<Result>] the gem result class
+      # @return [Class<Result>]
+      def define_outcome_class(const, status, base)
+        if const_defined?(const, false)
+          raise DefinitionError,
+            "#{name || "action"} has its own #{const}, which typed outcomes would replace; rename it"
+        end
+
+        inherited_class = superclass.instance_variable_get(:@define_outcome_classes)&.fetch(status)
+        action = self
+        outcome_class = Class.new(inherited_class || base)
+        outcome_class.define_singleton_method(:outcome_of) { action }
+        const_set(const, outcome_class)
+      end
+
+      # The result as this action's own result class for its outcome, under
+      # typed outcomes (decision D23). A result already of that class, or of a
+      # host's own result subclass, is returned as it is; a gem result, or
+      # another action's own (a nested failure that crossed), is rebuilt with
+      # its attributes and errors.
+      #
+      # @param result [Result]
+      # @return [Result]
+      def typed_result(result)
+        return result unless typed_outcomes?
+
+        target = define_outcome_classes.fetch(result.status)
+        return result if result.instance_of?(target)
+        return result unless OUTCOME_BASES.value?(result.class) || result.class.respond_to?(:outcome_of)
+
+        converted = target.new(**result.attributes)
+        converted.output_fields_set = result.output_fields_set
+        # Building it re-validates a nested output struct, which adds errors the
+        # result already has; the result's own errors are the whole truth.
+        converted.errors.to_h.each_key { |field| converted.errors.clear(field) }
+        result.errors.to_h.each { |field, messages| Array(messages).each { |m| converted.errors.add(field, m) } }
+        converted
+      end
+
+      # Build an output schema from a FieldStruct DSL block, refusing a field
+      # named like a result attribute (decisions D6/D18/D23).
+      #
+      # @param block [Proc] the FieldStruct field declarations
+      # @raise [DefinitionError] when a field name is in {RESERVED_OUTPUT_FIELDS}
+      # @return [Class<FieldStruct::Base>]
+      def build_output_schema(block)
+        schema = Class.new(FieldStruct::Base, &block)
+        conflicting = schema.attribute_names & RESERVED_OUTPUT_FIELDS
+        unless conflicting.empty?
+          raise DefinitionError,
+            "#{name || "action"}: output field(s) #{conflicting.map(&:inspect).join(", ")} " \
+            'conflict with reserved result attributes / instance variables; rename them'
+        end
+
+        schema
+      end
+
+      # One {.fails} / {.skips} declaration: the default message, the frozen
+      # metadata, and the output schema when a block declares one (D20/D21/D23).
+      #
+      # @param message [String, nil]
+      # @param metadata [Hash{Symbol=>Object}]
+      # @param block [Proc, nil]
+      # @return [Hash{Symbol=>Object}]
+      def declaration(message, metadata, block)
+        entry = {message: message, metadata: metadata.freeze}
+        entry[:output_schema] = build_output_schema(block) if block
+        entry.freeze
+      end
+
+      # {.describe}'s view of the declarations: each code's message and
+      # metadata, plus its output fields when it declares an output schema.
+      #
+      # @param declarations [Hash{Symbol=>Hash{Symbol=>Object}}]
+      # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
+      def describe_declarations(declarations)
+        declarations.transform_values do |entry|
+          described = entry.slice(:message, :metadata)
+          described[:output] = entry[:output_schema].metadata.to_h if entry[:output_schema]
+          described
+        end
+      end
+
+      # One {.describe_text} block for an input/output schema: +" (free-form)"+
+      # when none is declared, otherwise the FieldStruct +Metadata#describe+
+      # field lines indented one level under their +Input:+/+Output:+ heading.
+      #
+      # @param schema [Class<FieldStruct::Base>, nil]
+      # @return [String]
+      def schema_summary(schema)
+        return ' (free-form)' unless schema
+
+        "\n#{schema.metadata.describe.lines(chomp: true).map { |line| "  #{line}" }.join("\n")}"
+      end
+
+      # The +Failures:+ or +Skips:+ lines for {.describe_text}, one per declared
+      # code with its metadata and default message, or none when nothing is
+      # declared (decisions D20/D21).
+      #
+      # @param heading [String] the section heading
+      # @param declarations [Hash{Symbol=>Hash{Symbol=>Object}}] code => {message:, metadata:}
+      # @return [Array<String>]
+      def declarations_summary(heading, declarations)
+        return [] if declarations.empty?
+
+        lines = ["  #{heading}:"]
+        declarations.each do |code, declaration|
+          metadata = declaration[:metadata].map { |key, value| "#{key}: #{value.inspect}" }.join(', ')
+          line = "    - #{code}"
+          line += " (#{metadata})" unless metadata.empty?
+          line += ": #{declaration[:message]}" if declaration[:message]
+          lines << line
+        end
+        lines
+      end
+
+      # The +input+ value for {.describe}: a fixed schema's field metadata, a
+      # discriminated-input descriptor (+discriminated_on+ + +shapes+), or +nil+
+      # for a free-form action.
+      #
+      # @return [Hash, nil]
+      def input_descriptor
+        return input_schema.metadata.to_h if input_schema
+        return nil unless input_dispatch
+
+        {discriminated_on: input_dispatch.discriminator, shapes: input_dispatch.variants}
+      end
+
+      # The +Input:+ block for {.describe_text}: the fixed-schema field lines, a
+      # one-line discriminated-input summary, or +" (free-form)"+.
+      #
+      # @return [String]
+      def input_summary
+        return schema_summary(input_schema) if input_schema || input_dispatch.nil?
+
+        " (discriminated on #{input_dispatch.discriminator}: #{input_dispatch.variants.map(&:inspect).join(", ")})"
+      end
+
+      # Run-start guard (decision D18): every method a step needs (method steps,
+      # case value sources and method branch targets, hook steps) must exist on
+      # the instance, or raise a clear {DefinitionError} rather than a deep
+      # +NoMethodError+. This is the earliest reliable point — steps are usually
+      # declared above the methods that implement them.
+      #
+      # @param instance [Action]
+      # @return [void]
+      def ensure_steps_implemented!(instance)
+        all = steps.to_a + success_hooks.to_a + failure_hooks.to_a + skip_hooks.to_a + always_hooks.to_a
+        missing = all.flat_map(&:required_methods).uniq.reject { |method| implements?(instance, method) }
+        return if missing.empty?
+
+        raise DefinitionError,
+          "#{name || "action"} declares step(s) calling #{missing.map(&:inspect).join(", ")} " \
+          'but does not implement them'
+      end
+
+      # First-run guard (owner ruling R5): in every step and hook method, a
+      # non-bang recording verb (+fail+ / +fail_with+ / +skip+ / +succeed+) must be the
+      # method's last expression, or explicitly end it, since anything after
+      # it still runs (+VerbPosition+ has the rules). Checked once per class,
+      # by parsing each method's source with Prism; skipped where that can't
+      # be done (no Prism, no readable source), and not run at all while
+      # {Actionable.verb_position_check?} is off. A failing (or skipped) check
+      # is not cached, so it raises on every run until fixed.
+      #
+      # @raise [DefinitionError] naming each offending method, file:line and verb
+      # @return [void]
+      def ensure_verbs_last!
+        problems = verb_checked_steps.flat_map(&:body_methods).uniq.flat_map do |method_name|
+          next [] unless method_defined?(method_name) || private_method_defined?(method_name)
+
+          method = instance_method(method_name)
+          VerbPosition.method_offenses(method).map do |offense|
+            "#{name || "action"}##{method_name} (#{method.source_location&.first}:#{offense.line}) calls " \
+              "`#{offense.verb}` with more code after it, which still runs: use #{offense.verb}! to stop here, " \
+              "or make it the method's last expression"
+          end
+        end
+        raise DefinitionError, "#{problems.join("\n")}\n(see USAGE, Control flow)" unless problems.empty?
+
+        @verbs_checked = true
+      end
+
+      # The steps and hooks whose methods {.ensure_verbs_last!} checks. The
+      # Rails adapter adds its +after_commit+ hooks.
+      #
+      # @return [Array<Steps::Base>]
+      def verb_checked_steps
+        steps.to_a + success_hooks.to_a + failure_hooks.to_a + skip_hooks.to_a + always_hooks.to_a
+      end
+
+      # Whether +instance+ implements +method+ itself (public or private), not
+      # merely inherits it from Ruby's core: steps are called with +__send__+,
+      # so +step :puts+ or +always :exit+ must not reach +Kernel+.
+      #
+      # @param instance [Action]
+      # @param method [Symbol]
+      # @return [Boolean]
+      def implements?(instance, method)
+        instance.respond_to?(method, true) && !CORE_METHOD_OWNERS.include?(instance.method(method).owner)
+      end
+
+      # Coerce +.run+ arguments into the input struct: pass an existing input
+      # instance through untouched, otherwise build one from the keyword args.
+      # With discriminated input ({.input_for}), the schema is chosen from the
+      # discriminator value first; an unmatched value returns a +Failure+.
+      #
+      # @param args [Array<Object>] the positional arguments given to {.run}
+      # @param kwargs [Hash{Symbol=>Object}] the keyword arguments given to {.run}
+      # @return [FieldStruct::Base, Failure]
+      def build_input(args, kwargs)
+        return build_dispatched_input(args, kwargs) if input_dispatch
+
+        candidate = args.first
+        return candidate if args.size == 1 && candidate.is_a?(input_schema)
+
+        input_schema.new(**kwargs)
+      end
+
+      # Resolve the discriminated schema from the discriminator value, then build
+      # the input the same way {.build_input} does — or return an
+      # +:invalid_input+ {Failure} when nothing matches and there's no default.
+      #
+      # @param args [Array<Object>] the positional arguments given to {.run}
+      # @param kwargs [Hash{Symbol=>Object}] the keyword arguments given to {.run}
+      # @return [FieldStruct::Base, Failure]
+      def build_dispatched_input(args, kwargs)
+        candidate = args.first
+        return candidate if args.size == 1 && input_dispatch.schemas.any? { |schema| candidate.is_a?(schema) }
+
+        value = kwargs[input_dispatch.discriminator]
+        schema = input_dispatch.schema_for(value)
+        return unmatched_discriminator_failure(value) unless schema
+
+        schema.new(**kwargs)
+      end
+
+      # @param value [Object] the unmatched discriminator value
+      # @return [Failure] code +:invalid_input+, naming the discriminator
+      def unmatched_discriminator_failure(value)
+        Failure.new(
+          code: :invalid_input,
+          message: "no input shape for #{input_dispatch.discriminator} #{value.inspect}",
+          metadata: declared_failures.fetch(:invalid_input, {})
+        )
+      end
+
+      # @param input [FieldStruct::Base] the invalid input struct
+      # @return [Failure] code +:invalid_input+, carrying the input's errors
+      def invalid_input_failure(input)
+        Failure.new(
+          code: :invalid_input,
+          message: 'input failed validation',
+          metadata: declared_failures.fetch(:invalid_input, {})
+        ).absorb_errors_from(input)
+      end
+
+      # Add +step+ to +list+, or — when an equal step (same type and name) is
+      # already declared — swap it in at that step's position, so the last
+      # declaration wins (owner ruling P8; invariant 5). +list+ is this class's
+      # own copy (see {.inherited}), so a parent's list is never touched.
+      #
+      # @param list [Set<Steps::Base>]
+      # @param step [Steps::Base]
+      # @return [Set<Steps::Base>] +list+
+      def declare(list, step)
+        return list << step unless list.include?(step)
+
+        list.replace(list.map { |existing| existing.eql?(step) ? step : existing })
+      end
+
+      public
+
+      # Give each subclass its own copy of the inherited step set, so adding
+      # steps to a subclass never mutates the parent's (decision D2).
+      #
+      # @param subclass [Class]
+      # @return [void]
+      def inherited(subclass)
+        super
+        Actionable.registry.register(subclass)
+        subclass.instance_variable_set(:@steps, steps.dup)
+        subclass.instance_variable_set(:@output_schema, output_schema)
+        subclass.instance_variable_set(:@input_schema, input_schema)
+        subclass.instance_variable_set(:@input_dispatch, input_dispatch)
+        subclass.instance_variable_set(:@success_hooks, success_hooks.dup)
+        subclass.instance_variable_set(:@failure_hooks, failure_hooks.dup)
+        subclass.instance_variable_set(:@skip_hooks, skip_hooks.dup)
+        subclass.instance_variable_set(:@always_hooks, always_hooks.dup)
+        subclass.instance_variable_set(:@failure_declarations, failure_declarations.dup)
+        subclass.instance_variable_set(:@skip_declarations, skip_declarations.dup)
+        subclass.instance_variable_set(:@measure, measure)
+        subclass.instance_variable_set(:@measure_rate, measure_rate)
+        subclass.instance_variable_set(:@typed_outcomes, typed_outcomes?)
+        subclass.__send__(:define_outcome_classes) if typed_outcomes?
+      end
+    end
+
+    # Default free-form constructor: accept and ignore any arguments, so an
+    # action with no declared input still runs via {.run}. Subclasses override
+    # this to capture their inputs (decision D7; typed input lands in a later
+    # slice).
+    #
+    # @param _args [Object] ignored
+    # @param _kwargs [Object] ignored
+    def initialize(*_args, **_kwargs)
+    end
+
+    # The result recorded during the run, if any. The control-flow methods
+    # (+fail+/+succeed+/+fail!+/+succeed!+) write here; +nil+ means "no explicit
+    # result", which the {Runner} turns into an auto-{Success}.
+    #
+    # @return [Result, nil]
+    attr_reader :result
+
+    # The typed input struct for this run, when an +input+ schema is declared
+    # (decision D7); +nil+ for a free-form action. Steps read +input.field+.
+    #
+    # @return [FieldStruct::Base, nil]
+    attr_reader :input
+
+    private
+
+    # Record a {Failure} as the run's result without halting — later steps
+    # still run, and the final result reflects the most recent record (decision
+    # D4, "last write wins").
+    #
+    # A code declared with {Action.fails} attaches its metadata to the failure,
+    # and its declared message when +message+ is +nil+ (decision D20). Nothing
+    # but +errors+ follows the message, so an error on any field name, +kind+
+    # included, lands in +errors+.
+    #
+    # Under typed outcomes alone, +output:+ is reserved: it is the failure's
+    # output, held to the schema its code declares (decision D23).
+    #
+    #   fail!(:invalid, 'check the form', output: {form_record: record}, name: 'is blank')
+    #
+    # @param code [Symbol] the error code
+    # @param message [String, nil] human-readable description
+    # @param errors [String, Array<String>, Hash{Symbol=>Object}, FieldStruct::Base] each
+    #   keyword is a field => message(s) added to the result's errors collection;
+    #   under typed outcomes the +output:+ keyword is the failure's output instead
+    # @return [false] so a step can branch on the call
+    def fail(code, message = nil, **errors)
+      output = self.class.typed_outcomes? ? errors.delete(:output) : nil
+      failure = declared_failure(code, message)
+      ensure_output_declared!(:fails, failure.code, output)
+      errors.each { |field, messages| Array(messages).each { |m| failure.errors.add(field, m) } }
+      failure.output = output unless output.nil?
+      @result = failure
+      false
+    end
+
+    # Record a {Failure} that absorbs an arbitrary FieldStruct's validation
+    # errors, without halting (decision D19). The same machinery
+    # +Failure(:invalid_input)+ / +Failure(:invalid_output)+ use internally,
+    # exposed as a verb so a step can validate a side struct and fail with its
+    # errors directly.
+    #
+    #   def validate = fail_with(EventShape.new(payload), code: :invalid_event)
+    #
+    # @param source [#errors] any object exposing a FieldStruct-style +errors+
+    #   collection (typically a +FieldStruct::Base+ instance)
+    # @param code [Symbol] the error code; defaults to +:invalid+
+    # @param message [String, nil] human-readable description
+    # @param output [Hash{Symbol=>Object}, nil] the failure's output, held to
+    #   the schema its code declares; typed outcomes only (decision D23)
+    # @raise [ArgumentError] when +output+ is given without typed outcomes
+    # @return [false] so a step can branch on the call
+    def fail_with(source, code: :invalid, message: nil, output: nil)
+      unless output.nil? || self.class.typed_outcomes?
+        raise ArgumentError, 'fail_with takes output: only under typed_outcomes (decision D23)'
+      end
+
+      failure = declared_failure(code, message).absorb_errors_from(source)
+      ensure_output_declared!(:fails, failure.code, output)
+      failure.output = output unless output.nil?
+      @result = failure
+      false
+    end
+
+    # Record a {Failure} absorbing +source+'s errors and halt the run
+    # (decision D19). The halting companion to {#fail_with}.
+    #
+    # @param source [#errors] see {#fail_with}
+    # @param code [Symbol] the error code; defaults to +:invalid+
+    # @param message [String, nil] human-readable description
+    # @param output [Hash{Symbol=>Object}, nil] see {#fail_with}
+    # @return [void]
+    def fail_with!(source, code: :invalid, message: nil, output: nil)
+      fail_with(source, code: code, message: message, output: output)
+      halt!
+    end
+
+    # Record a {Success} as the run's result without halting (decision D4).
+    #
+    # @param message [String, nil] human-readable description
+    # @param output [Object] the success output payload
+    # @return [true] so a step can branch on the call
+    def succeed(message = nil, **output)
+      @result = Success.new(message: message, output: output)
+      true
+    end
+
+    # Record a {Failure} and halt the run, skipping the remaining steps
+    # (decision D4).
+    #
+    # @param code [Symbol] the error code
+    # @param message [String, nil] human-readable description
+    # @param errors [String, Array<String>, Hash{Symbol=>Object}, FieldStruct::Base] see {#fail}
+    # @raise [UncaughtThrowError] never escapes the {Runner}'s halt catch
+    # @return [void]
+    def fail!(code, message = nil, **errors)
+      fail(code, message, **errors)
+      halt!
+    end
+
+    # Record a {Success} and halt the run, skipping the remaining steps
+    # (decision D4).
+    #
+    # @param message [String, nil] human-readable description
+    # @param output [Object] the success output payload
+    # @return [void]
+    def succeed!(message = nil, **output)
+      succeed(message, **output)
+      halt!
+    end
+
+    # Record a {Skipped} as the run's result without halting — the action had
+    # nothing to do (decision D17). Not a failure; later steps still run and the
+    # final result reflects the most recent record (last write wins).
+    #
+    # A code declared with {Action.skips} attaches its metadata to the skip,
+    # and its declared message when +message+ is +nil+ (decision D21). Once the
+    # action declares any skip, an undeclared +code+ raises.
+    #
+    # @param code [Symbol] the skip reason; defaults to +:skipped+
+    # @param message [String, nil] human-readable description
+    # @param output [Object] the skip output payload — captured
+    #   best-effort like a {Success}'s output, but never validated (decision
+    #   D17). Lets an idempotent hit return the existing record's data.
+    # @raise [DefinitionError] when the action declares skips but not +code+
+    # @return [false] so a step can branch on the call (the run did not succeed here)
+    def skip(code = :skipped, message = nil, **output)
+      ensure_code_identifier!(:skip, code)
+      code = code.to_sym
+      ensure_skip_declared!(code)
+      ensure_output_declared!(:skips, code, output) if self.class.typed_outcomes?
+      declaration = self.class.skip_declarations.fetch(code, {message: nil, metadata: {}})
+      @result = Skipped.new(
+        code: code, message: message || declaration[:message], output: output, metadata: declaration[:metadata]
+      )
+      false
+    end
+
+    # Record a {Skipped} and halt the run, skipping the remaining steps — the
+    # common "nothing to do, stop here" case (decision D17).
+    #
+    # @param code [Symbol] the skip reason; defaults to +:skipped+
+    # @param message [String, nil] human-readable description
+    # @param output [Object] the skip output payload (see {#skip})
+    # @return [void]
+    def skip!(code = :skipped, message = nil, **output)
+      skip(code, message, **output)
+      halt!
+    end
+
+    # Build a {Failure} for +code+ carrying what {Action.fails} declared for it:
+    # its metadata, and its message when +message+ is +nil+ (decision D20).
+    #
+    # @param code [Symbol, String] the error code
+    # @param message [String, nil] the message given at the call
+    # @return [Failure]
+    # @raise [DefinitionError] when the action declares failures but not +code+
+    #   (the {GEM_FAILURE_CODES} are exempt)
+    def declared_failure(code, message)
+      ensure_code_identifier!(:failure, code)
+      code = code.to_sym
+      ensure_failure_declared!(code)
+      declaration = self.class.failure_declarations.fetch(code, {message: nil, metadata: {}})
+      Failure.new(code: code, message: message || declaration[:message], metadata: declaration[:metadata])
+    end
+
+    # Fail this run with a nested action's failure and halt (decision D20).
+    # {Steps::Action} calls it instead of +fail!+, so the child's failure
+    # crosses intact: its code, message, every error (on any field name, since
+    # no keyword list is involved), its metadata, and its result class with any
+    # extra attributes a host subclass adds. Under the child's metadata sits
+    # what this action declares for the code, so the parent's declaration fills
+    # in keys the child didn't set. The child's output and history stay on the
+    # child. A declaring parent must declare the child's code too.
+    #
+    # Under typed outcomes the child's output crosses as this action's failure
+    # output, so it is held to the schema this action declares for the code,
+    # not the child's (decision D23), and the failure becomes this action's own
+    # +Failure+ when {.run} returns.
+    #
+    # @param child [Failure] the nested action's failure
+    # @raise [DefinitionError] when this action declares failures but not the
+    #   child's code
+    # @return [void]
+    def adopt_failure!(child)
+      ensure_failure_declared!(child.code)
+      declaration = self.class.failure_declarations.fetch(child.code, {message: nil, metadata: {}})
+      failure_class = adopted_failure_class(child)
+      attributes = child.attributes.except(:output, :history)
+      @result = failure_class.new(
+        **attributes,
+        message: child.message || declaration[:message],
+        metadata: declaration[:metadata].merge(attributes.fetch(:metadata, {}))
+      ).absorb_errors_from(child)
+      @result.output = crossing_output(child.output) if crosses_output?(child)
+      halt!
+    end
+
+    # The class a nested failure crosses as: a host's own result subclass
+    # stays (D20), but a typed child's own +Failure+ becomes the gem class,
+    # since it names the child; a typed parent then makes it its own (D23).
+    #
+    # @param child [Result]
+    # @return [Class<Failure>]
+    def adopted_failure_class(child)
+      return Failure unless child.is_a?(Failure)
+
+      child.class.respond_to?(:outcome_of) ? Failure : child.class
+    end
+
+    # Whether a nested failure's output crosses into this action: under typed
+    # outcomes, for every code but those the gem builds, which keep the output
+    # they had before typed outcomes (none) (decision D23).
+    #
+    # @param child [Failure]
+    # @return [Boolean]
+    def crosses_output?(child)
+      self.class.typed_outcomes? && !GEM_FAILURE_CODES.include?(child.code)
+    end
+
+    # @param output [FieldStruct::Base, Hash, Object] a nested failure's output
+    # @return [Hash{Symbol=>Object}] its fields, for this action's schema
+    def crossing_output(output)
+      case output
+      when FieldStruct::Base then output.attributes
+      when Hash then output
+      else {}
+      end
+    end
+
+    # A +fail+ / +skip+ code must be an identifier-like Symbol or String
+    # ({CODE_FORMAT}): +fail 'card expired'+ is +Kernel#fail+ habit, and in an
+    # action it would record the sentence as a code and keep running (owner
+    # ruling R5).
+    #
+    # @param kind [:failure, :skip]
+    # @param code [Object]
+    # @raise [ArgumentError] when +code+ is not an identifier
+    # @return [void]
+    def ensure_code_identifier!(kind, code)
+      return if (code.is_a?(Symbol) || code.is_a?(String)) && CODE_FORMAT.match?(code)
+
+      raise ArgumentError,
+        "#{self.class.name || "action"}: #{kind} code #{code.inspect} is not an identifier; use a Symbol like " \
+        ':card_expired. Inside an action, fail records a failure, it is not Kernel#fail: to raise an ' \
+        'exception, use raise'
+    end
+
+    # Strictness (decision D20): once an action declares any failure, every
+    # code it fails with must be declared, so its declarations are its whole
+    # failure contract. An action that declares none is unchecked, and the
+    # {GEM_FAILURE_CODES} are always allowed.
+    #
+    # @param code [Symbol]
+    # @raise [DefinitionError] when +code+ is undeclared
+    # @return [void]
+    def ensure_failure_declared!(code)
+      return if self.class.allows_failure_code?(code)
+
+      declared = self.class.declared_failures.keys.map(&:inspect).join(', ')
+      raise DefinitionError,
+        "#{self.class.name || "action"} fails with #{code.inspect}, which it does not declare; " \
+        "declare it with `fails #{code.inspect}` (declared: #{declared})"
+    end
+
+    # Under typed outcomes, output given for a skip or failure must have a
+    # schema to go into (decision D23): output for a code with none would be
+    # dropped, so it is refused instead. The failures the gem builds keep
+    # their output, so they need none. +output:+ itself must be a Hash or a
+    # struct, which catches an old +output:+ error message.
+    #
+    # @param verb [:fails, :skips] the declaration that would add the schema
+    # @param code [Symbol]
+    # @param output [Hash, FieldStruct::Base, nil] the output given, if any
+    # @raise [ArgumentError] when +output+ is neither a Hash nor a struct
+    # @raise [DefinitionError] when +output+ is given for a code with no schema
+    # @return [void]
+    def ensure_output_declared!(verb, code, output)
+      return if output.nil?
+      unless output.is_a?(Hash) || output.is_a?(FieldStruct::Base)
+        raise ArgumentError,
+          "output: must be a Hash or a FieldStruct, got #{output.class}: under typed_outcomes it is the " \
+          'outcome\'s output, not an error'
+      end
+      return if output.is_a?(Hash) && output.empty?
+
+      klass = self.class
+      schema = verb == :skips ? klass.skip_output_schema(code) : klass.failure_output_schema(code)
+      return if schema || (verb == :fails && GEM_FAILURE_CODES.include?(code))
+
+      raise DefinitionError,
+        "#{klass.name || "action"} #{verb} with #{code.inspect} and output, but " \
+        "#{code.inspect} declares no output schema; declare one with `#{verb} #{code.inspect} do … end`"
+    end
+
+    # Strictness (decision D21): once an action declares any skip, every code
+    # it skips with must be declared, the implicit default +:skipped+ included.
+    # An action that declares none is unchecked.
+    #
+    # @param code [Symbol]
+    # @raise [DefinitionError] when +code+ is undeclared
+    # @return [void]
+    def ensure_skip_declared!(code)
+      return if self.class.allows_skip_code?(code)
+
+      declared = self.class.declared_skips.keys.map(&:inspect).join(', ')
+      raise DefinitionError,
+        "#{self.class.name || "action"} skips with #{code.inspect}, which it does not declare; " \
+        "declare it with `skips #{code.inspect}` (declared: #{declared})"
+    end
+
+    # Halt the run immediately, keeping whatever result was already recorded
+    # (a prior +fail+/+succeed+/+skip+, or auto-{Success} if none). Control flow
+    # only — not an exception (decision D4).
+    #
+    # @return [void]
+    def halt!
+      throw HALT
+    end
+  end
+end