actionable-rb 1.9.0

data/sig/actionable.rbs

@@ -0,0 +1,2593 @@
+# Actionable: typed, composable Ruby service objects.
+# 
+# This is the core entry point. Per decision D14, every core file gets an
+# explicit +require_relative+ here — no autoload, no Zeitwerk. The optional
+# adapters (+actionable/rails+, +actionable/rspec+) are separate requires and
+# are deliberately NOT loaded here, keeping the core Rails-free.
+module Actionable
+  HALT: Symbol
+  VERSION: String
+
+  # Turn the first-run verb-position check (owner rulings R5, R10) on or
+  # off for the whole process. Off, {Action.run} never parses a method's
+  # source and never loads Prism; the per-call code check in +fail+ / +skip+
+  # stays on. Meant as an escape hatch while upgrading (set it in an
+  # initializer), with the +Actionable/VerbNotLast+ cop as the only guard
+  # left. A class first run while off is checked on its first run after the
+  # check is turned back on.
+  # 
+  #   Actionable.verb_position_check = false
+  # 
+  # _@param_ `enabled` — +false+ to skip the check
+  # 
+  # _@return_ — whether the check is now on
+  def self.verb_position_check=: (bool enabled) -> bool
+
+  # Whether {Action.run} checks where each step and hook method places its
+  # plain recording verbs on an action's first run. On by default.
+  def self.verb_position_check?: () -> bool
+
+  # Run +block+ inside the halt catch point.
+  # 
+  # Returns the block's value when nothing is thrown, or the value passed with
+  # +throw Actionable::HALT, value+ when the pipeline halts (+nil+ for a bare
+  # +throw Actionable::HALT+). A raised StandardError is deliberately NOT
+  # caught — it propagates to the caller (decision D4).
+  # 
+  # _@return_ — the block's value, or the thrown halt value
+  def catch_halt: () ?{ () -> Object } -> Object
+
+  # Run +block+ inside the halt catch point.
+  # 
+  # Returns the block's value when nothing is thrown, or the value passed with
+  # +throw Actionable::HALT, value+ when the pipeline halts (+nil+ for a bare
+  # +throw Actionable::HALT+). A raised StandardError is deliberately NOT
+  # caught — it propagates to the caller (decision D4).
+  # 
+  # _@return_ — the block's value, or the thrown halt value
+  def self.catch_halt: () ?{ () -> Object } -> Object
+
+  # _@return_ — the process-wide action registry
+  def self.registry: () -> Registry
+
+  # Runs an action inside a background job and maps its result to a queue
+  # disposition: a success or skip is done (+:ack+); a failure either retries
+  # (transient) or is discarded (permanent). Genuine exceptions are never
+  # swallowed — they propagate so the queue's own retry/backoff handles them
+  # (invariant 2).
+  module Job
+    DEFAULT_PERMANENT_CODES: ::Array[Symbol]
+
+    # Map a result to a queue disposition.
+    # 
+    # With +honor_retry: true+, a failure or skip whose metadata has a +retry:+
+    # key is decided by it instead: truthy is +:retry+, falsy is +:discard+ for
+    # a failure and +:ack+ for a skip. Results without the key, and successes,
+    # map as usual.
+    # 
+    # _@param_ `result` — the action's result
+    # 
+    # _@param_ `permanent` — failure codes treated as non-retryable
+    # 
+    # _@param_ `honor_retry` — act on the result's +retry:+ metadata
+    # 
+    # _@return_ — +:ack+ for a success or skip; +:discard+
+    # for a failure whose code is +permanent+; +:retry+ for any other failure
+    def disposition: (Result result, ?permanent: ::Array[Symbol], ?honor_retry: bool) -> Symbol
+
+    # Map a result to a queue disposition.
+    # 
+    # With +honor_retry: true+, a failure or skip whose metadata has a +retry:+
+    # key is decided by it instead: truthy is +:retry+, falsy is +:discard+ for
+    # a failure and +:ack+ for a skip. Results without the key, and successes,
+    # map as usual.
+    # 
+    # _@param_ `result` — the action's result
+    # 
+    # _@param_ `permanent` — failure codes treated as non-retryable
+    # 
+    # _@param_ `honor_retry` — act on the result's +retry:+ metadata
+    # 
+    # _@return_ — +:ack+ for a success or skip; +:discard+
+    # for a failure whose code is +permanent+; +:retry+ for any other failure
+    def self.disposition: (Result result, ?permanent: ::Array[Symbol], ?honor_retry: bool) -> Symbol
+
+    # _@param_ `result`
+    # 
+    # _@return_ — whether the result carries +retry:+ metadata
+    def retry_declared?: (Result result) -> bool
+
+    # _@param_ `result`
+    # 
+    # _@return_ — whether the result carries +retry:+ metadata
+    def self.retry_declared?: (Result result) -> bool
+
+    # _@param_ `result` — a result whose metadata has +retry:+
+    def metadata_disposition: ((Failure | Skipped) result) -> Symbol
+
+    # _@param_ `result` — a result whose metadata has +retry:+
+    def self.metadata_disposition: ((Failure | Skipped) result) -> Symbol
+
+    # Raised by {Mixin#run_actionable} for a retryable failure, so the host
+    # queue (Sidekiq / ActiveJob) sees a raised error and applies its retry
+    # policy. Carries the offending result.
+    class RetryableFailure < StandardError
+      # _@param_ `result` — a {Failure}, or a {Skipped} retried because its metadata says +retry: true+ (see {RetryMetadata#honor_retry_metadata})
+      def initialize: (Result result) -> void
+
+      # _@return_ — the failed result that triggered the retry
+      attr_reader result: Result
+    end
+
+    # The +honor_retry_metadata+ class macro (owner ruling P10). Extended onto
+    # {Actionable::Action} by +actionable/job+, so an action can opt in to having
+    # {Mixin#run_actionable} act on the +retry:+ metadata of its declared codes.
+    # Metadata stays neutral by default (decisions D20/D21).
+    module RetryMetadata
+      # Opt this action in (or, with +enabled: false+, back out) to {Job}
+      # honoring the +retry:+ metadata of its declared failures and skips:
+      # +retry: true+ retries the job, +retry: false+ does not. A code with no
+      # +retry:+ key keeps the default mapping. Inherited; a subclass can turn
+      # it off.
+      # 
+      #   class Reindex < Actionable::Action
+      #     honor_retry_metadata
+      #     skips :not_ready, retry: true # the job retries until the index is ready
+      #   end
+      # 
+      # _@param_ `enabled`
+      def honor_retry_metadata: (?enabled: bool) -> void
+
+      # Whether {Job} honors this action's +retry:+ metadata, inherited from
+      # ancestors when not set locally. +false+ unless an ancestor opted in.
+      def honor_retry_metadata?: () -> bool
+    end
+
+    # Mix into a Sidekiq worker or ActiveJob job. Call {#run_actionable} from
+    # +perform+; it runs the action, records the result on {#actionable_result},
+    # and raises {RetryableFailure} for a retryable failure (so the queue
+    # retries) — returning normally for +:ack+ and +:discard+.
+    # 
+    #   class ProjectEventJob
+    #     include Sidekiq::Job
+    #     include Actionable::Job::Mixin
+    #     def perform(event_id) = run_actionable(ProjectApiEvent, event_id: event_id)
+    #   end
+    module Mixin
+      # Run +action_class+ with the given arguments, map the outcome, and either
+      # return the result (+:ack+ / +:discard+) or raise {RetryableFailure}
+      # (+:retry+). A genuine exception inside the action propagates unchanged.
+      # When the action opted in with +honor_retry_metadata+, its declared
+      # +retry:+ metadata decides (see {Job.disposition}).
+      # 
+      # _@param_ `action_class`
+      # 
+      # _@param_ `args` — positional arguments, forwarded to +.run+
+      # 
+      # _@param_ `kwargs` — keyword arguments, forwarded to +.run+
+      # 
+      # _@return_ — the run's result (for an ack/discard outcome)
+      def run_actionable: (singleton(Actionable::Action) action_class, *Object args, **Object kwargs) -> Result
+
+      # _@return_ — failure codes this job treats as non-retryable;
+      # override to customize. Defaults to {DEFAULT_PERMANENT_CODES}.
+      def actionable_permanent_codes: () -> ::Array[Symbol]
+
+      # _@return_ — the result of the most recent {#run_actionable}
+      attr_reader actionable_result: Result?
+    end
+  end
+
+  # Generates RBS for a *user* action class — track 2 of the RBS strategy
+  # (decision D13). Sord covers the library's static classes, but it can't see
+  # +CreateInvoice.run(amount:)+ or +result.invoice+: those depend on the
+  # action's declared +input+/+output+ schemas. This walks those schemas (via
+  # FieldStruct's metadata and +FieldStruct::RBS.type_for+) and emits:
+  # 
+  # * a typed +.run+ signature from the input schema (or +(*untyped)+ when
+  #   free-form), with an overload taking a built input struct;
+  # * for a fixed +input+ schema, a nested +InputSchema+ struct and a typed
+  #   +#input+ reader returning it. Like +Output+ and +Result+ it exists only
+  #   in RBS, so generation raises +ArgumentError+ when Ruby already resolves
+  #   +Action::InputSchema+;
+  # * a nullable instance variable per output field (+@total: ::Integer?+),
+  #   so steps that assign it type-check. The generated RBS owns these: a
+  #   host sig must not declare them again, since RBS rejects an instance
+  #   variable declared twice;
+  # * a nested +Output+ struct with a typed accessor per output field;
+  # * a nested +Result+ with +output+ and the convenience-delegation readers,
+  #   which +.run+ returns;
+  # * when the action declares failures with +fails+, a +failure_code+ type
+  #   alias listing every code it can fail with: the declared ones, then the
+  #   {Action::GEM_FAILURE_CODES} (decision D20);
+  # * when the action declares skips with +skips+, a +skip_code+ type alias
+  #   listing every code it can skip with (decision D21). The gem emits no skip
+  #   codes of its own, so the alias holds the declared ones only.
+  # 
+  # Under typed outcomes (decision D23) +.run+ returns the action's own
+  # +Success | Skipped | Failure+ instead, each typed with its +code+ and an
+  # +output+ that names what the outcome can carry: a nested class per code
+  # that declares an output schema (+AlreadyActiveSkipOutput+,
+  # +InvalidFailureOutput+), and a Hash for a code without one. A failure's
+  # output also admits every skip schema and +Output+, since a broken one ends
+  # the run as +invalid_output+ carrying it.
+  # 
+  #   class CreateInvoice < Actionable::Action
+  #     input  { required :amount, :integer }
+  #     output { required :invoice, :string }
+  #   end
+  # 
+  #   puts Actionable::RBS.generate(CreateInvoice)
+  #   # class CreateInvoice < ::Actionable::Action
+  #   #   def self.run: (amount: ::Integer) -> Result
+  #   #               | (InputSchema input) -> Result
+  #   #   def input: () -> InputSchema
+  #   #   @invoice: ::String?
+  #   #   class InputSchema < ::FieldStruct::Base ... end
+  #   #   class Output < ::FieldStruct::Base ... end
+  #   #   class Result < ::Actionable::Result ... end
+  #   # end
+  # 
+  # The action names its real superclass, and every named ancestor up to
+  # {Actionable::Action} is declared before it, member-less, so the output
+  # resolves without the host generating its abstract bases.
+  # 
+  # The emitted +Result+/+Output+/+InputSchema+ are generated type aids: at
+  # runtime +.run+ returns a {Success}/{Failure}/{Skipped} that responds to
+  # these via output delegation, and the schemas are anonymous classes. Field
+  # types come from +FieldStruct::RBS.type_for+, so they match FieldStruct's own
+  # generator, and describe a valid instance. Referenced field types appear as
+  # qualified names (+::Invoice+) — generate RBS for those (e.g. via
+  # +FieldStruct::RBS+) so they resolve.
+  module RBS
+
+    # Generate RBS source for a user action class.
+    # 
+    # _@param_ `klass`
+    # 
+    # _@return_ — RBS for the action, wrapped in its module nesting
+    def self.generate: (singleton(Actionable::Action) klass) -> String
+
+    # The generated input type is named +InputSchema+, nested in the action.
+    # It exists only in RBS, so a Ruby constant that +klass::InputSchema+
+    # already resolves to (on the action, an ancestor class or an included
+    # module; +Object+'s top-level constants don't resolve through +klass::+)
+    # would make the RBS name lie.
+    # 
+    # _@param_ `klass`
+    def self.check_input_schema_name!: (singleton(Actionable::Action) klass) -> void
+
+    # _@param_ `klass`
+    # 
+    # _@return_ — whether the generated RBS declares +InputSchema+: for a
+    # fixed +input+ schema, not a discriminated +input_for+ one
+    def self.input_schema_class?: (singleton(Actionable::Action) klass) -> bool
+
+    # Declares every named ancestor between +klass+ and {Actionable::Action},
+    # so the action's superclass resolves on its own: a host often never
+    # generates its abstract base actions. Each is member-less, except that a
+    # typed ancestor also declares its result classes empty, for a typed
+    # subclass's result classes to subclass. Being empty, each declaration
+    # merges with the ancestor's full signature when that is generated too, and
+    # repeats byte-identically across the subclasses of one base, which RBS
+    # accepts across files.
+    # 
+    # _@param_ `klass`
+    # 
+    # _@return_ — one namespaced block per ancestor, outermost first
+    def self.ancestor_blocks: (singleton(Actionable::Action) klass) -> String
+
+    # _@param_ `ancestor`
+    # 
+    # _@return_ — the ancestor's member-less class block
+    def self.ancestor_block: (singleton(Actionable::Action) ancestor) -> String
+
+    # _@param_ `klass`
+    # 
+    # _@return_ — the named classes strictly
+    # between +klass+ and {Actionable::Action}, nearest first
+    def self.named_ancestors: (singleton(Actionable::Action) klass) -> ::Array[singleton(Actionable::Action)]
+
+    # _@param_ `klass`
+    # 
+    # _@return_ — +class Name < ::Superclass+, naming the nearest named
+    # superclass (anonymous ones have no RBS name)
+    def self.class_head: (singleton(Actionable::Action) klass) -> String
+
+    # _@param_ `parent`
+    # 
+    # _@return_ — whether a subclass's result classes subclass +parent+'s
+    def self.typed_parent?: (Class parent) -> bool
+
+    # _@param_ `klass`
+    def self.class_block: (singleton(Actionable::Action) klass) -> String
+
+    # The class block of an action with typed outcomes (decision D23).
+    # 
+    # _@param_ `klass`
+    def self.typed_class_block: (singleton(Actionable::Action) klass) -> String
+
+    # The sections every action's class block opens with: the code aliases,
+    # +.run+, the typed +#input+ reader, the output instance variables, and the
+    # +InputSchema+ class.
+    # 
+    # _@param_ `klass`
+    # 
+    # _@param_ `return_type` — what +.run+ returns
+    def self.leading_sections: (singleton(Actionable::Action) klass, String return_type) -> ::Array[String]
+
+    # One instance variable per output field, which steps assign and the
+    # {Runner} captures into the output. Each is nullable: it is unset until a
+    # step assigns it. The generator owns these declarations, since RBS rejects
+    # the same instance variable declared in two files.
+    # 
+    # _@param_ `schema` — the success output schema
+    def self.output_ivar_lines: (singleton(FieldStruct::Base) schema) -> ::Array[String]
+
+    # The nested output class of every skip, then every failure, code that
+    # declares an output schema, named after the code.
+    # 
+    # _@param_ `klass`
+    # 
+    # _@return_ — name, schema
+    def self.outcome_schemas: (singleton(Actionable::Action) klass) -> ::Array[[String, singleton(FieldStruct::Base)]]
+
+    # Every output class name must be an RBS class name, and unique: two codes
+    # that camelize alike (+:ready+ / +:ready_+, +:expired?+ /
+    # +:expired_predicate+) would otherwise emit one class for two schemas.
+    # 
+    # _@param_ `klass`
+    # 
+    # _@param_ `kind` — +skip+ or +failure+
+    # 
+    # _@param_ `entries` — code, class name, schema
+    def self.check_outcome_names!: (singleton(Actionable::Action) klass, String kind, ::Array[[Symbol, String, singleton(FieldStruct::Base)]] entries) -> void
+
+    # The +Success+, +Skipped+ and +Failure+ blocks of a typed action.
+    # 
+    # _@param_ `klass`
+    def self.outcome_blocks: (singleton(Actionable::Action) klass) -> ::Array[String]
+
+    # The readers a result delegates to its output struct, one per field any
+    # of +schemas+ declares. A field several declare types as the union of
+    # their types, nullable when any declares it optional, or when +nullable+.
+    # A failure's readers are all nullable: an +invalid_output+ failure carries
+    # the output that broke its schema, so a required field can be missing.
+    # 
+    # _@param_ `schemas`
+    # 
+    # _@param_ `nullable` — make every reader nullable
+    def self.delegator_lines: (::Array[singleton(FieldStruct::Base)] schemas, ?nullable: bool) -> ::Array[String]
+
+    # _@param_ `klass`
+    # 
+    # _@return_ — the +Success+ block's signatures
+    def self.success_lines: (singleton(Actionable::Action) klass) -> ::Array[String]
+
+    # _@param_ `declared` — the declared codes
+    # 
+    # _@param_ `name` — the alias naming them
+    # 
+    # _@return_ — the alias, or +::Symbol+ when none are declared
+    def self.code_type: (::Hash[untyped, untyped] declared, String name) -> String
+
+    # _@param_ `types` — the output classes an outcome can carry
+    # 
+    # _@return_ — them and a Hash, as one RBS type
+    def self.union: (::Array[String] types) -> String
+
+    # _@param_ `klass`
+    # 
+    # _@param_ `name` — +Success+, +Skipped+ or +Failure+
+    # 
+    # _@param_ `lines` — the block's method signatures
+    # 
+    # _@return_ — the class block, subclassing the parent action's own
+    # result class when the parent has typed outcomes, else the gem's
+    def self.outcome_block: (singleton(Actionable::Action) klass, String name, ::Array[String] lines) -> String
+
+    # _@param_ `parent` — the superclass of the action being generated
+    # 
+    # _@param_ `name` — +Success+, +Skipped+ or +Failure+
+    # 
+    # _@return_ — the parent's result class when it has typed outcomes,
+    # else the gem's
+    def self.outcome_base: (Class parent, String name) -> String
+
+    # A code's trailing +?+ / +!+ becomes +Predicate+ / +Bang+, since neither
+    # may appear in a constant; +:x+ and +:x?+ get different names.
+    # 
+    # _@param_ `code`
+    # 
+    # _@return_ — +:already_active+ as +AlreadyActive+, +:expired?+ as
+    # +ExpiredPredicate+, +:done!+ as +DoneBang+
+    def self.camelize: (Symbol code) -> String
+
+    # _@param_ `klass`
+    # 
+    # _@param_ `return_type` — what +.run+ returns
+    # 
+    # _@return_ — the +.run+ signature: typed kwargs from the input schema
+    # (or +(*untyped)+ free-form), plus an overload taking a built
+    # +InputSchema+ instance, which +.run+ passes through
+    def self.run_signature: (singleton(Actionable::Action) klass, return_type: String) -> String
+
+    # _@param_ `klass` — an action that declares failures
+    # 
+    # _@return_ — the +failure_code+ alias: a union of the declared codes
+    # and the codes the gem emits itself, as Symbol literal types
+    def self.failure_code_alias: (singleton(Actionable::Action) klass) -> String
+
+    # _@param_ `klass` — an action that declares skips
+    # 
+    # _@return_ — the +skip_code+ alias: a union of the declared skip codes
+    # as Symbol literal types
+    def self.skip_code_alias: (singleton(Actionable::Action) klass) -> String
+
+    # _@param_ `field`
+    # 
+    # _@return_ — +name: Type+ (required), +?name: Type+ (required with a
+    # default, so it may be omitted) or +?name: Type?+ (optional: it may be
+    # omitted or passed +nil+; +run(note: nil)+ succeeds).
+    def self.run_param: (FieldStruct::Field field) -> String
+
+    # A nested struct class with FieldStruct's reader and writer shape: the
+    # reader nullable when optional, the writer +(T? value) -> T?+.
+    # 
+    # _@param_ `schema` — an output or input schema
+    # 
+    # _@param_ `name` — the nested class name
+    # 
+    # _@return_ — the nested class block
+    def self.output_block: (singleton(FieldStruct::Base) schema, ?String name) -> String
+
+    # _@param_ `schema` — the output schema
+    # 
+    # _@return_ — the nested +Result+ class block with output delegation
+    def self.result_block: (singleton(FieldStruct::Base) schema) -> String
+
+    # The field's RBS type, as FieldStruct's own generator emits it: made
+    # nullable when optional, or as +nullable+ says (D13).
+    # 
+    # _@param_ `field`
+    # 
+    # _@param_ `nullable` — +nil+ follows the field's optionality
+    def self.rbs_type: (FieldStruct::Field field, ?nullable: bool?) -> String
+
+    # _@param_ `type` — an RBS type expression
+    # 
+    # _@return_ — +type+ made nullable, unless it already admits +nil+
+    def self.nullable: (String _type) -> String
+
+    # Wrap a class block in the nesting implied by its qualified name,
+    # indenting two spaces per level. A namespace that is a class opens as
+    # +class+ (no superclass, so it merges with the class's own declaration),
+    # since RBS rejects a class and a module of the same name.
+    # 
+    # _@param_ `full_name`
+    # 
+    # _@param_ `inner`
+    # 
+    # _@return_ — RBS source ending in a trailing newline
+    def self.wrap_namespace: (String full_name, String inner) -> String
+
+    # _@param_ `text`
+    # 
+    # _@return_ — +text+ with every non-blank line indented two spaces
+    def self.indent: (String text) -> String
+  end
+
+  # RSpec matchers and stubs for actions (decision D12).
+  module RSpec
+    # The refusal for a stub, +and_fail+ or +and_skip+ naming a code an action
+    # that declares failures (decision D20) or skips (decision D21) doesn't
+    # declare.
+    # 
+    # _@param_ `action_class`
+    # 
+    # _@param_ `code`
+    # 
+    # _@param_ `outcome` — which declarations the code was checked against
+    def self.undeclared_code_message: (singleton(Actionable::Action) action_class, (Symbol | String) code, ?outcome: Symbol) -> String
+
+    # Helpers mixed into example groups by +actionable/rspec+ that stub an
+    # action's +.run+ to return a real {Success} / {Failure} built from a hash,
+    # so callers can assert on +result.code+/+output+/+errors+ without executing
+    # the action (decision D12).
+    # 
+    # +allow_*+ permits the call (a stub); +stub_*+ also sets a call expectation
+    # (a mock, verified on the example) — mirroring RSpec's allow/expect split.
+    # 
+    # A stubbed failure of an action that declares failures with
+    # {Actionable::Action.fails} carries the declared metadata (and message,
+    # when none is given) for its code, and a code the action doesn't declare
+    # raises +ArgumentError+, so a stub can't return what the action never
+    # could (decision D20). A stubbed skip follows {Actionable::Action.skips}
+    # the same way (decision D21), the default +:skipped+ included.
+    module Stubs
+      # _@param_ `action_class` — the action whose +.run+ is stubbed
+      # 
+      # _@param_ `opts` — {#actionable_success_result}'s keywords (+message:+, +output:+, +errors:+)
+      # 
+      # _@return_ — the stubbed result
+      def allow_actionable_success: (singleton(Actionable::Action) action_class, **Object opts) -> Success
+
+      # _@param_ `action_class` — the action whose +.run+ is stubbed
+      # 
+      # _@param_ `opts` — {#actionable_success_result}'s keywords (+message:+, +output:+, +errors:+)
+      # 
+      # _@return_ — the stubbed result
+      def stub_actionable_success: (singleton(Actionable::Action) action_class, **Object opts) -> Success
+
+      # _@param_ `action_class` — the action whose +.run+ is stubbed
+      # 
+      # _@param_ `opts` — {#actionable_failure_result}'s keywords; +code:+ defaults to +:error+
+      # 
+      # _@return_ — the stubbed result
+      def allow_actionable_failure: (singleton(Actionable::Action) action_class, **Object opts) -> Failure
+
+      # _@param_ `action_class` — the action whose +.run+ is stubbed
+      # 
+      # _@param_ `opts` — {#actionable_failure_result}'s keywords; +code:+ defaults to +:error+
+      # 
+      # _@return_ — the stubbed result
+      def stub_actionable_failure: (singleton(Actionable::Action) action_class, **Object opts) -> Failure
+
+      # _@param_ `action_class` — the action whose +.run+ is stubbed
+      # 
+      # _@param_ `opts` — {#actionable_skip_result}'s keywords; +code:+ defaults to +:skipped+
+      # 
+      # _@return_ — the stubbed result
+      def allow_actionable_skip: (singleton(Actionable::Action) action_class, **Object opts) -> Skipped
+
+      # _@param_ `action_class` — the action whose +.run+ is stubbed
+      # 
+      # _@param_ `opts` — {#actionable_skip_result}'s keywords; +code:+ defaults to +:skipped+
+      # 
+      # _@return_ — the stubbed result
+      def stub_actionable_skip: (singleton(Actionable::Action) action_class, **Object opts) -> Skipped
+
+      # Build a real {Success} from a hash (no stubbing).
+      # 
+      # _@param_ `message`
+      # 
+      # _@param_ `output`
+      # 
+      # _@param_ `errors`
+      def actionable_success_result: (?message: String?, ?output: (::Hash[Symbol, Object] | FieldStruct::Base), ?errors: ::Hash[Symbol, (String | ::Array[String])]) -> Success
+
+      # Build a real {Failure} from a hash (no stubbing).
+      # 
+      # _@param_ `code`
+      # 
+      # _@param_ `message`
+      # 
+      # _@param_ `output`
+      # 
+      # _@param_ `errors`
+      # 
+      # _@param_ `metadata` — the failure's per-code metadata
+      def actionable_failure_result: (
+                                       ?code: Symbol,
+                                       ?message: String?,
+                                       ?output: (::Hash[Symbol, Object] | FieldStruct::Base),
+                                       ?errors: ::Hash[Symbol, (String | ::Array[String])],
+                                       ?metadata: ::Hash[Symbol, Object]
+                                     ) -> Failure
+
+      # Build a real {Skipped} from a hash (no stubbing).
+      # 
+      # _@param_ `code`
+      # 
+      # _@param_ `message`
+      # 
+      # _@param_ `output`
+      # 
+      # _@param_ `metadata` — the skip's per-code metadata
+      def actionable_skip_result: (
+                                    ?code: Symbol,
+                                    ?message: String?,
+                                    ?output: (::Hash[Symbol, Object] | FieldStruct::Base),
+                                    ?metadata: ::Hash[Symbol, Object]
+                                  ) -> Skipped
+
+      # A {Failure} for +action_class+: the declared metadata and message for
+      # its code, or a refusal when the action declares failures but not it.
+      # 
+      # _@param_ `action_class`
+      # 
+      # _@param_ `code`
+      # 
+      # _@param_ `opts` — the rest of {#actionable_failure_result}'s keywords
+      def declared_failure_result: (singleton(Actionable::Action) action_class, ?code: (Symbol | String), **Object opts) -> Failure
+
+      # A {Skipped} for +action_class+: the declared metadata and message for
+      # its code, or a refusal when the action declares skips but not it.
+      # 
+      # _@param_ `action_class`
+      # 
+      # _@param_ `code`
+      # 
+      # _@param_ `opts` — the rest of {#actionable_skip_result}'s keywords
+      def declared_skip_result: (singleton(Actionable::Action) action_class, ?code: (Symbol | String), **Object opts) -> Skipped
+
+      # Permit +action_class.run+, answering +result+ as a real run would.
+      # 
+      # _@param_ `action_class`
+      # 
+      # _@param_ `result`
+      # 
+      # _@return_ — the result the stub answers
+      def allow_run: (singleton(Actionable::Action) action_class, Result result) -> Result
+
+      # Expect +action_class.run+ (verified on the example), answering +result+
+      # as a real run would.
+      # 
+      # _@param_ `action_class`
+      # 
+      # _@param_ `result`
+      # 
+      # _@return_ — the result the stub answers
+      def expect_run: (singleton(Actionable::Action) action_class, Result result) -> Result
+
+      # The stubbed result as a real run would return it (decision D23): its
+      # output shaped by the schema it is held to, then as the action's own
+      # result class when it has typed outcomes.
+      # 
+      # _@param_ `action_class`
+      # 
+      # _@param_ `result`
+      def as_action_result: (singleton(Actionable::Action) action_class, Result result) -> Result
+
+      # Mirror the runner: output for a code with a schema becomes that schema
+      # (refused when it breaks it, since a real run would end as
+      # +invalid_output+ instead), and under typed outcomes a code without one
+      # carries an empty output (refused when output is given, as a real run
+      # refuses it). The gem's own failure codes keep what they are given.
+      # 
+      # _@param_ `action_class`
+      # 
+      # _@param_ `result` — updated in place
+      def shape_output: (singleton(Actionable::Action) action_class, Result result) -> void
+
+      # _@param_ `action_class`
+      # 
+      # _@param_ `result`
+      # 
+      # _@return_ — the schema the result's output
+      # is held to: its code's, or the success schema under typed outcomes
+      def stubbed_output_schema: (singleton(Actionable::Action) action_class, Result result) -> singleton(FieldStruct::Base)?
+
+      # The stub's output as an instance of +schema+, built from the fields of
+      # +result+'s output that the schema declares.
+      # 
+      # _@param_ `action_class`
+      # 
+      # _@param_ `result`
+      # 
+      # _@param_ `schema`
+      def build_stubbed_output: (singleton(Actionable::Action) action_class, Result result, singleton(FieldStruct::Base) schema) -> FieldStruct::Base
+
+      # The stub's response: +result+, noted as a stubbed run when outcome
+      # coverage is loaded (decision D22), so a report can tell an outcome
+      # only ever stubbed from one never reached at all.
+      # 
+      # _@param_ `action_class`
+      # 
+      # _@param_ `result`
+      # 
+      # _@return_ — +result+
+      def stubbed_run: (singleton(Actionable::Action) action_class, Result result) -> Result
+
+      # Add +errors+ to +result+'s errors.
+      # 
+      # _@param_ `result`
+      # 
+      # _@param_ `errors`
+      # 
+      # _@return_ — +result+
+      def apply_errors: (Result result, ::Hash[Symbol, (String | ::Array[String])] errors) -> Result
+    end
+
+    # RSpec matcher methods mixed into example groups by +actionable/rspec+.
+    module Matchers
+      # Run an action and assert on its outcome.
+      # 
+      #   expect(CreateInvoice).to perform_actionable(amount: 5).and_succeed
+      #   expect(CreateInvoice).to perform_actionable(bad).and_fail(:invalid_input)
+      #   expect(Boom).to          perform_actionable.and_raise(RuntimeError)
+      # 
+      # _@param_ `args` — positional args forwarded to +.run+
+      # 
+      # _@param_ `kwargs` — keyword args forwarded to +.run+
+      def perform_actionable: (*Object args, **Object kwargs) ?{ (Result? result, StandardError? exception) -> Object } -> PerformActionable
+    end
+
+    # The matcher object returned by {Matchers#perform_actionable}. Runs the
+    # action under test and checks the configured outcome (decision D12). Bare
+    # +perform_actionable+ expects a success; chain +and_succeed+ / +and_fail+ /
+    # +and_raise+ to be explicit. Code and message expectations match with +===+,
+    # so exact values, Regexps, and classes all work.
+    class PerformActionable
+      DEFAULT_BACKTRACE_QTY: Integer
+
+      # _@param_ `args` — positional args forwarded to +.run+
+      # 
+      # _@param_ `kwargs` — keyword args forwarded to +.run+
+      # 
+      # _@param_ `block` — extra assertions, called with the result and exception
+      def initialize: (::Array[Object] args, ::Hash[Symbol, Object] kwargs, Proc? block) -> void
+
+      # Expect a successful result, optionally matching +message+.
+      # 
+      # _@param_ `message` — matched against the result's message with +===+
+      def and_succeed: (?Object? message) ?{ (Result? result, StandardError? exception) -> Object } -> self
+
+      # Expect a failed result, optionally matching +code+ and +message+. On an
+      # action that declares failures, a Symbol +code+ it doesn't declare raises
+      # +ArgumentError+ (decision D20).
+      # 
+      # _@param_ `code` — matched against the result's code with +==+
+      # 
+      # _@param_ `message` — matched against the result's message with +===+
+      def and_fail: (?Object? code, ?Object? message) ?{ (Result? result, StandardError? exception) -> Object } -> self
+
+      # Expect a skipped result, optionally matching the reason +code+ and
+      # +message+ (decision D17). On an action that declares skips, a Symbol
+      # +code+ it doesn't declare raises +ArgumentError+ (decision D21).
+      # 
+      # _@param_ `code` — matched against the result's code with +==+
+      # 
+      # _@param_ `message` — matched against the result's message with +===+
+      def and_skip: (?Object? code, ?Object? message) ?{ (Result? result, StandardError? exception) -> Object } -> self
+
+      # Expect the run to raise +error_class+, optionally matching +message+.
+      # 
+      # _@param_ `error_class`
+      # 
+      # _@param_ `message` — matched against the exception's message with +===+
+      def and_raise: (?singleton(Exception) error_class, ?Object? message) ?{ (Result? result, StandardError? exception) -> Object } -> self
+
+      # _@param_ `action_class`
+      def matches?: (singleton(Actionable::Action) action_class) -> bool
+
+      # _@param_ `action_class`
+      def does_not_match?: (singleton(Actionable::Action) action_class) -> bool
+
+      def failure_message: () -> String
+
+      def failure_message_when_negated: () -> String
+
+      def description: () -> String
+
+      # _@param_ `outcome` — +:success+, +:failure+, +:skip+ or +:raise+
+      # 
+      # _@param_ `message`
+      def configure: (Symbol outcome, Object? message) ?{ (Result? result, StandardError? exception) -> Object } -> self
+
+      # An +and_fail+ or +and_skip+ code the action could never end with is a
+      # broken spec, not a failed expectation, so it raises rather than not
+      # matching.
+      def ensure_code_declared!: () -> void
+
+      # Run the action, keeping its result or the error it raised.
+      def perform: () -> void
+
+      def primary_match?: () -> bool?
+
+      def succeeded?: () -> bool?
+
+      def failed?: () -> bool?
+
+      def skipped?: () -> bool?
+
+      def raised?: () -> bool
+
+      # _@param_ `actual`
+      def message_matches?: (String? actual) -> bool
+
+      def block_match?: () -> bool
+
+      def expectation_phrase: () -> String?
+
+      def code_suffix: () -> String
+
+      def message_suffix: () -> String
+
+      def actual_phrase: () -> String
+
+      def formatted_backtrace: () -> String
+
+      def short_backtrace?: () -> bool
+
+      def backtrace_qty: () -> Integer
+    end
+  end
+
+  # Namespace for the concrete step types an action's pipeline is built from
+  # (decision D3): {Steps::Method} now, {Steps::Action} and {Steps::Case} later.
+  module Steps
+    # Build the right step type from a +step+ declaration's target, inferring
+    # the type from the argument (decision D2): a Symbol/String becomes a
+    # {Steps::Method}, an action +Class+ becomes a {Steps::Action}. The case
+    # block type ({Steps::Case}) joins in a later slice.
+    # 
+    # _@param_ `target` — the step target
+    # 
+    # _@param_ `options` — step options (e.g. +:if+, +:unless+, and for action steps +:input+ / +:expose+)
+    # 
+    # _@return_ — the constructed step
+    def self.build: ((Symbol | String | singleton(Actionable::Action)) target, **Object options) -> Steps::Base
+
+    # Shared behavior for every step: a +name+, an +options+ hash, value
+    # identity for Set deduplication (keyed by +[type, name]+, decision D2),
+    # and the +:if+ / +:unless+ skip logic. Subclasses implement {#call}.
+    # 
+    # @abstract Subclass and implement {#call}.
+    class Base
+      # _@param_ `name` — the step name (see {#name})
+      # 
+      # _@param_ `options` — step options
+      def initialize: (Object name, **Object options) -> void
+
+      # Run the step against an action instance.
+      # 
+      # _@param_ `_instance` — the action instance the step runs against
+      def call: (Object _instance) -> void
+
+      # Instance method names this step needs the action to implement, used by
+      # the run-start definition guard (decision D18). None for the base; concrete
+      # types that call instance methods override this.
+      def required_methods: () -> ::Array[Symbol]
+
+      # Instance methods whose bodies run as this step, for the recording-verb
+      # position check (owner ruling R5): not guards, not a case step's value
+      # source. None for the base; a nested action is checked on its own run.
+      def body_methods: () -> ::Array[Symbol]
+
+      # _@return_ — a short tag identifying the step type, for introspection
+      # (+Actionable::Action.describe+). Concrete types override it.
+      def kind: () -> Symbol
+
+      # Whether this step should be skipped for the given instance, per its
+      # +:if+ / +:unless+ guards. A guard is a Symbol naming a (possibly
+      # private) instance method, or a callable invoked with the instance.
+      # When both guards are present, either one asking to skip wins.
+      # 
+      # _@param_ `instance` — the action instance to evaluate guards against
+      def skip?: (Object _instance) -> bool
+
+      # Value identity: same concrete class AND same name. This keys steps in
+      # the per-action Set so a redeclared step dedups (decision D2).
+      # 
+      # _@param_ `other`
+      def ==: (Object other) -> bool
+
+      # _@return_ — consistent with {#==}, so steps work as Set members
+      def hash: () -> Integer
+
+      # Resolve a guard against the instance. A Symbol/String names an instance
+      # method (called via +__send__+, so private predicates work); anything
+      # else is treated as a callable receiving the instance.
+      # 
+      # _@param_ `guard`
+      # 
+      # _@param_ `instance`
+      def evaluate_guard: ((Symbol | String | untyped) guard, Object _instance) -> bool
+
+      # _@return_ — the step's name — a Symbol for a {Steps::Method},
+      # an action Class for a {Steps::Action}
+      attr_reader name: Object
+
+      # _@return_ — the declared step options (e.g. +:if+,
+      # +:unless+, and step-type-specific keys)
+      attr_reader options: ::Hash[Symbol, Object]
+    end
+
+    # A step that branches to one of several targets based on a value
+    # (decision D3, declared with +case_step+). The switch value is read from
+    # the action via the named method; each branch's target is an ordinary step
+    # (a method or a nested action), so branches compose like any other step.
+    # 
+    #   case_step :status do
+    #     on 'active',          :handle_active
+    #     on %w[trial grace],   :handle_trial      # Array membership
+    #     on(/\A4\d\d\z/,       :handle_client_err # Regexp
+    #     default               :handle_unknown
+    #   end
+    class Case < Actionable::Steps::Base
+      # Build a case step from a +case_step+ declaration.
+      # 
+      # _@param_ `value_source` — the method whose value is switched on
+      # 
+      # _@param_ `options` — step options (e.g. +:if+, +:unless+)
+      def self.define: ((Symbol | String) value_source, **Object options) -> Case
+
+      # _@param_ `value_source` — the method whose value is switched on
+      # 
+      # _@param_ `branches` — ordered [match, step] pairs
+      # 
+      # _@param_ `default_step` — the fallback step
+      # 
+      # _@param_ `options` — step options
+      def initialize: (
+                        (Symbol | String) value_source,
+                        ::Array[[Object, Steps::Base]] branches,
+                        Steps::Base? default_step,
+                        **Object options
+                      ) -> void
+
+      # Evaluate the switch value and run the first matching branch (or the
+      # default). No-op when nothing matches and no default was declared.
+      # 
+      # The branch is chosen by value alone; its +:if+ / +:unless+ guards then
+      # decide whether its target runs, exactly as for a plain step. A matched
+      # branch whose guard opts out is a no-op: it does not fall through to a
+      # later branch or to the default.
+      # 
+      # _@param_ `instance`
+      def call: (Actionable::Action _instance) -> void
+
+      # _@return_ — the switch-value method plus every branch
+      # target's required methods
+      def required_methods: () -> ::Array[Symbol]
+
+      # _@return_ — every branch target's body methods (never the
+      # switch-value method, which only returns the value)
+      def body_methods: () -> ::Array[Symbol]
+
+      def kind: () -> Symbol
+
+      # _@return_ — every branch's step, the default included
+      def branch_steps: () -> ::Array[Steps::Base]
+
+      # _@param_ `value` — the switch value
+      # 
+      # _@return_ — the first matching branch's step
+      def match: (Object value) -> Steps::Base?
+
+      # Collects +on+/+default+ branch declarations inside a +case_step+ block.
+      class Builder
+        def initialize: () -> void
+
+        # Register a branch. +value+ matches the switch value by +==+, by
+        # +Regexp#match?+ when it is a Regexp, or by membership when it is an
+        # Array. +target+ is any step target (method name or nested action).
+        # 
+        # _@param_ `value`
+        # 
+        # _@param_ `target`
+        # 
+        # _@param_ `options` — step options for the target (+:if+ / +:unless+ guard the branch: a matched branch whose guard opts out does nothing)
+        def on: ((Object | Regexp | ::Array[untyped]) value, (Symbol | String | singleton(Actionable::Action)) target, **Object options) -> void
+
+        # Register the fallback branch, run when no +on+ branch matches.
+        # 
+        # _@param_ `target`
+        # 
+        # _@param_ `options` — step options for the target
+        def default: ((Symbol | String | singleton(Actionable::Action)) target, **Object options) -> void
+
+        # _@return_ — ordered [match, step] pairs
+        attr_reader branches: ::Array[[Object, Steps::Base]]
+
+        # _@return_ — the fallback step, if +default+ was declared
+        attr_reader default_step: Steps::Base?
+      end
+    end
+
+    # A step that runs another action as part of this one (decision D3,
+    # triggered by an action +Class+ step argument).
+    # 
+    # +:input+ threads named parent instance variables into the child's +.run+;
+    # +:expose+ limits which of the child's outputs are absorbed back as parent
+    # instance variables (default: all). A child failure fails the parent with
+    # the child's code, message, errors and metadata, and halts the remaining
+    # steps.
+    class Action < Actionable::Steps::Base
+      # Run the nested action, threading input in and absorbing output back.
+      # 
+      # _@param_ `instance` — the parent action instance
+      def call: (Actionable::Action _instance) -> void
+
+      def kind: () -> Symbol
+
+      # _@param_ `instance`
+      # 
+      # _@return_ — +{ name => @name }+ for each +:input+ name
+      def input_kwargs: (Actionable::Action _instance) -> ::Hash[Symbol, Object]
+
+      # Copy the child's exposed output fields onto the parent as instance
+      # variables, so the parent's later steps and output capture see them.
+      # Only fields the child actually set are copied: a field it left nil or
+      # at its default must not overwrite the parent's value.
+      # 
+      # _@param_ `instance`
+      # 
+      # _@param_ `child`
+      def absorb: (Actionable::Action _instance, Result child) -> void
+
+      # _@param_ `output`
+      # 
+      # _@return_ — the child output as a plain hash
+      def output_hash: ((FieldStruct::Base | ::Hash[untyped, untyped] | Object) output) -> ::Hash[Symbol, Object]
+    end
+
+    # A step that calls an instance method on the action (decision D3,
+    # triggered by a Symbol/String step argument).
+    class Method < Actionable::Steps::Base
+      # _@param_ `name` — the instance method to call; normalized to a Symbol
+      # 
+      # _@param_ `options` — step options (e.g. +:if+, +:unless+)
+      def initialize: ((Symbol | String) name, **Object options) -> void
+
+      # Invoke the named method on the instance.
+      # 
+      # _@param_ `instance` — the action instance
+      # 
+      # _@return_ — the method's return value
+      def call: (Object _instance) -> Object
+
+      # _@return_ — the instance method this step calls
+      def required_methods: () -> ::Array[Symbol]
+
+      # _@return_ — the instance method whose body is this step
+      def body_methods: () -> ::Array[Symbol]
+
+      def kind: () -> Symbol
+    end
+  end
+
+  # 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
+    extend Actionable::Rails::Transactions
+    extend Actionable::Job::RetryMetadata
+    GEM_FAILURE_CODES: ::Array[Symbol]
+    CORE_METHOD_OWNERS: ::Array[Module]
+    CODE_FORMAT: Regexp
+
+    # 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}).
+    def self.steps: () -> ::Set[Steps::Base]
+
+    # 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
+    # 
+    # _@return_ — the output schema, or +nil+ when
+    # none has been declared (the free-form path)
+    def self.output: () -> singleton(FieldStruct::Base)?
+
+    # 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.
+    # 
+    # _@return_ — the input schema, or +nil+ when
+    # none has been declared
+    def self.input: () -> singleton(FieldStruct::Base)?
+
+    # 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` — the kwarg whose value selects the schema
+    # 
+    # _@return_ — the stored dispatch
+    def self.input_for: ((Symbol | String) discriminator) -> InputDispatch
+
+    # 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` — the failure code
+    # 
+    # _@param_ `message` — the default message for this code
+    # 
+    # _@param_ `metadata` — per-code metadata, passed through
+    # 
+    # _@return_ — {.declared_failures}
+    def self.fails: ((Symbol | String) code, ?String? message, **Object metadata) -> ::Hash[Symbol, ::Hash[Symbol, Object]]
+
+    # The output schema declared for failure +code+ with a {.fails} block, or
+    # +nil+ when the code has none (decision D23).
+    # 
+    # _@param_ `code`
+    def self.failure_output_schema: ((Symbol | String) code) -> singleton(FieldStruct::Base)?
+
+    # The failure codes this action declares with {.fails}, each mapped to its
+    # metadata (decision D20). Empty when the action declares none.
+    def self.declared_failures: () -> ::Hash[Symbol, ::Hash[Symbol, Object]]
+
+    # 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`
+    def self.allows_failure_code?: ((Symbol | String) code) -> bool
+
+    # Every {.fails} declaration, keyed by code, as +{message:, metadata:}+.
+    def self.failure_declarations: () -> ::Hash[Symbol, ::Hash[Symbol, Object]]
+
+    # 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` — the skip code
+    # 
+    # _@param_ `message` — the default message for this code
+    # 
+    # _@param_ `metadata` — per-code metadata, passed through
+    # 
+    # _@return_ — {.declared_skips}
+    def self.skips: ((Symbol | String) code, ?String? message, **Object metadata) -> ::Hash[Symbol, ::Hash[Symbol, Object]]
+
+    # The output schema declared for skip +code+ with a {.skips} block, or
+    # +nil+ when the code has none (decision D23).
+    # 
+    # _@param_ `code`
+    def self.skip_output_schema: ((Symbol | String) code) -> singleton(FieldStruct::Base)?
+
+    # 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`
+    # 
+    # _@return_ — the new setting
+    def self.typed_outcomes: (?enabled: bool) -> bool
+
+    # _@return_ — whether typed outcomes are on (decision D23)
+    def self.typed_outcomes?: () -> bool
+
+    # The skip codes this action declares with {.skips}, each mapped to its
+    # metadata (decision D21). Empty when the action declares none.
+    def self.declared_skips: () -> ::Hash[Symbol, ::Hash[Symbol, Object]]
+
+    # 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`
+    def self.allows_skip_code?: ((Symbol | String) code) -> bool
+
+    # Every {.skips} declaration, keyed by code, as +{message:, metadata:}+
+    # (decision D21).
+    def self.skip_declarations: () -> ::Hash[Symbol, ::Hash[Symbol, Object]]
+
+    # 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` — the step target
+    # 
+    # _@param_ `options` — step options (e.g. +:if+, +:unless+)
+    # 
+    # _@return_ — the updated step set
+    def self.step: ((Symbol | String) target, **Object options) -> ::Set[Steps::Base]
+
+    # Lifecycle hooks that run after the main steps when the run succeeds.
+    def self.success_hooks: () -> ::Set[Steps::Base]
+
+    # Lifecycle hooks that run after the main steps when the run fails.
+    def self.failure_hooks: () -> ::Set[Steps::Base]
+
+    # Lifecycle hooks that run after the main steps when the run was skipped.
+    def self.skip_hooks: () -> ::Set[Steps::Base]
+
+    # Lifecycle hooks that run after the main steps regardless of outcome.
+    def self.always_hooks: () -> ::Set[Steps::Base]
+
+    # Declare a hook that runs at the end of a run iff it succeeded (D2).
+    # 
+    # _@param_ `target` — the instance method to run
+    # 
+    # _@param_ `options` — step options (e.g. +:if+)
+    def self.on_success: ((Symbol | String) target, **Object options) -> ::Set[Steps::Base]
+
+    # Declare a hook that runs at the end of a run iff it failed (D2).
+    # 
+    # _@param_ `target` — the instance method to run
+    # 
+    # _@param_ `options` — step options (e.g. +:if+)
+    def self.on_failure: ((Symbol | String) target, **Object options) -> ::Set[Steps::Base]
+
+    # Declare a hook that runs at the end of a run iff it was skipped (D17).
+    # 
+    # _@param_ `target` — the instance method to run
+    # 
+    # _@param_ `options` — step options (e.g. +:if+)
+    def self.on_skip: ((Symbol | String) target, **Object options) -> ::Set[Steps::Base]
+
+    # Declare a hook that runs at the end of a run regardless of outcome (D2).
+    # 
+    # _@param_ `target` — the instance method to run
+    # 
+    # _@param_ `options` — step options (e.g. +:if+)
+    def self.always: ((Symbol | String) target, **Object options) -> ::Set[Steps::Base]
+
+    # 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` — the method whose value is switched on
+    # 
+    # _@param_ `options` — step options (e.g. +:if+, +:unless+)
+    # 
+    # _@return_ — the updated step set
+    def self.case_step: ((Symbol | String) value_source, **Object options) -> ::Set[Steps::Base]
+
+    # 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` — the mode to set; omit to read
+    # 
+    # _@param_ `rate` — required for +:sampled+ — the probability (0..1) that a given run is measured
+    # 
+    # _@return_ — the resolved mode
+    def self.measure: (?Symbol? mode, ?rate: Numeric?) -> Symbol
+
+    # _@return_ — whether this action always records history
+    def self.measure_all?: () -> bool
+
+    # _@return_ — whether this action samples history
+    def self.measure_sampled?: () -> bool
+
+    # The per-run sampling decision: true with probability {.measure_rate} when
+    # in +:sampled+ mode, false otherwise. Rolled once per run by the {Runner}.
+    def self.measure_sample_hit?: () -> bool
+
+    # 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.
+    def self.describe: () -> ::Hash[Symbol, Object]
+
+    # 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  ..."
+    def self.describe_text: () -> String
+
+    # 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` — positional arguments: a single input-schema instance, or (free-form) whatever the constructor takes
+    # 
+    # _@param_ `kwargs` — keyword arguments: the input fields, or (free-form) whatever the constructor takes
+    # 
+    # _@return_ — the run's {Success} or {Failure}
+    def self.run: (*Object args, **Object kwargs) -> Result
+
+    # 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` — the items to run
+    # 
+    # _@return_ — the per-item results
+    def self.run_each: (::Enumerable[untyped] enumerable) ?{ (Object item) -> (::Hash[untyped, untyped] | ::Array[untyped] | Object) } -> BatchResult
+
+    # The body of {.run}: build the input, then run the steps.
+    # 
+    # _@param_ `args`
+    # 
+    # _@param_ `kwargs`
+    def self.run_untyped: (::Array[Object] args, ::Hash[Symbol, Object] kwargs) -> Result
+
+    # 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.
+    # 
+    # _@return_ — status => result class
+    def self.define_outcome_classes: () -> ::Hash[Symbol, singleton(Result)]
+
+    # _@param_ `const` — the constant to define
+    # 
+    # _@param_ `status` — the outcome {Result#status}
+    # 
+    # _@param_ `base` — the gem result class
+    def self.define_outcome_class: (Symbol const, Symbol status, singleton(Result) base) -> singleton(Result)
+
+    # 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`
+    def self.typed_result: (Result result) -> Result
+
+    # Build an output schema from a FieldStruct DSL block, refusing a field
+    # named like a result attribute (decisions D6/D18/D23).
+    # 
+    # _@param_ `block` — the FieldStruct field declarations
+    def self.build_output_schema: (Proc block) -> singleton(FieldStruct::Base)
+
+    # One {.fails} / {.skips} declaration: the default message, the frozen
+    # metadata, and the output schema when a block declares one (D20/D21/D23).
+    # 
+    # _@param_ `message`
+    # 
+    # _@param_ `metadata`
+    # 
+    # _@param_ `block`
+    def self.declaration: (String? message, ::Hash[Symbol, Object] metadata, Proc? block) -> ::Hash[Symbol, Object]
+
+    # {.describe}'s view of the declarations: each code's message and
+    # metadata, plus its output fields when it declares an output schema.
+    # 
+    # _@param_ `declarations`
+    def self.describe_declarations: (::Hash[Symbol, ::Hash[Symbol, Object]] declarations) -> ::Hash[Symbol, ::Hash[Symbol, Object]]
+
+    # 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`
+    def self.schema_summary: (singleton(FieldStruct::Base)? schema) -> String
+
+    # 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` — the section heading
+    # 
+    # _@param_ `declarations` — code => {message:, metadata:}
+    def self.declarations_summary: (String heading, ::Hash[Symbol, ::Hash[Symbol, Object]] declarations) -> ::Array[String]
+
+    # 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.
+    def self.input_descriptor: () -> ::Hash[untyped, untyped]?
+
+    # The +Input:+ block for {.describe_text}: the fixed-schema field lines, a
+    # one-line discriminated-input summary, or +" (free-form)"+.
+    def self.input_summary: () -> String
+
+    # 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`
+    def self.ensure_steps_implemented!: (Action _instance) -> void
+
+    # 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.
+    def self.ensure_verbs_last!: () -> void
+
+    # The steps and hooks whose methods {.ensure_verbs_last!} checks. The
+    # Rails adapter adds its +after_commit+ hooks.
+    def self.verb_checked_steps: () -> ::Array[Steps::Base]
+
+    # 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`
+    # 
+    # _@param_ `method`
+    def self.implements?: (Action _instance, Symbol method) -> bool
+
+    # 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` — the positional arguments given to {.run}
+    # 
+    # _@param_ `kwargs` — the keyword arguments given to {.run}
+    def self.build_input: (::Array[Object] args, ::Hash[Symbol, Object] kwargs) -> (FieldStruct::Base | Failure)
+
+    # 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` — the positional arguments given to {.run}
+    # 
+    # _@param_ `kwargs` — the keyword arguments given to {.run}
+    def self.build_dispatched_input: (::Array[Object] args, ::Hash[Symbol, Object] kwargs) -> (FieldStruct::Base | Failure)
+
+    # _@param_ `value` — the unmatched discriminator value
+    # 
+    # _@return_ — code +:invalid_input+, naming the discriminator
+    def self.unmatched_discriminator_failure: (Object value) -> Failure
+
+    # _@param_ `input` — the invalid input struct
+    # 
+    # _@return_ — code +:invalid_input+, carrying the input's errors
+    def self.invalid_input_failure: (FieldStruct::Base input) -> Failure
+
+    # 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`
+    # 
+    # _@param_ `step`
+    # 
+    # _@return_ — +list+
+    def self.declare: (::Set[Steps::Base] list, Steps::Base step) -> ::Set[Steps::Base]
+
+    # 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`
+    def self.inherited: (Class subclass) -> void
+
+    # 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` — ignored
+    # 
+    # _@param_ `_kwargs` — ignored
+    def initialize: (*Object _args, **Object _kwargs) -> void
+
+    # 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` — the error code
+    # 
+    # _@param_ `message` — human-readable description
+    # 
+    # _@param_ `errors` — 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_ — so a step can branch on the call
+    def fail: (Symbol code, ?String? message, **(String | ::Array[String] | ::Hash[Symbol, Object] | FieldStruct::Base) errors) -> bool
+
+    # 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` — any object exposing a FieldStruct-style +errors+ collection (typically a +FieldStruct::Base+ instance)
+    # 
+    # _@param_ `code` — the error code; defaults to +:invalid+
+    # 
+    # _@param_ `message` — human-readable description
+    # 
+    # _@param_ `output` — the failure's output, held to the schema its code declares; typed outcomes only (decision D23)
+    # 
+    # _@return_ — so a step can branch on the call
+    def fail_with: (
+                     untyped source,
+                     ?code: Symbol,
+                     ?message: String?,
+                     ?output: ::Hash[Symbol, Object]?
+                   ) -> bool
+
+    # Record a {Failure} absorbing +source+'s errors and halt the run
+    # (decision D19). The halting companion to {#fail_with}.
+    # 
+    # _@param_ `source` — see {#fail_with}
+    # 
+    # _@param_ `code` — the error code; defaults to +:invalid+
+    # 
+    # _@param_ `message` — human-readable description
+    # 
+    # _@param_ `output` — see {#fail_with}
+    def fail_with!: (
+                      untyped source,
+                      ?code: Symbol,
+                      ?message: String?,
+                      ?output: ::Hash[Symbol, Object]?
+                    ) -> void
+
+    # Record a {Success} as the run's result without halting (decision D4).
+    # 
+    # _@param_ `message` — human-readable description
+    # 
+    # _@param_ `output` — the success output payload
+    # 
+    # _@return_ — so a step can branch on the call
+    def succeed: (?String? message, **Object output) -> bool
+
+    # Record a {Failure} and halt the run, skipping the remaining steps
+    # (decision D4).
+    # 
+    # _@param_ `code` — the error code
+    # 
+    # _@param_ `message` — human-readable description
+    # 
+    # _@param_ `errors` — see {#fail}
+    def fail!: (Symbol code, ?String? message, **(String | ::Array[String] | ::Hash[Symbol, Object] | FieldStruct::Base) errors) -> void
+
+    # Record a {Success} and halt the run, skipping the remaining steps
+    # (decision D4).
+    # 
+    # _@param_ `message` — human-readable description
+    # 
+    # _@param_ `output` — the success output payload
+    def succeed!: (?String? message, **Object output) -> void
+
+    # 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` — the skip reason; defaults to +:skipped+
+    # 
+    # _@param_ `message` — human-readable description
+    # 
+    # _@param_ `output` — 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.
+    # 
+    # _@return_ — so a step can branch on the call (the run did not succeed here)
+    def skip: (?Symbol code, ?String? message, **Object output) -> bool
+
+    # Record a {Skipped} and halt the run, skipping the remaining steps — the
+    # common "nothing to do, stop here" case (decision D17).
+    # 
+    # _@param_ `code` — the skip reason; defaults to +:skipped+
+    # 
+    # _@param_ `message` — human-readable description
+    # 
+    # _@param_ `output` — the skip output payload (see {#skip})
+    def skip!: (?Symbol code, ?String? message, **Object output) -> void
+
+    # 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` — the error code
+    # 
+    # _@param_ `message` — the message given at the call
+    def declared_failure: ((Symbol | String) code, String? message) -> Failure
+
+    # 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` — the nested action's failure
+    def adopt_failure!: (Failure child) -> void
+
+    # 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`
+    def adopted_failure_class: (Result child) -> singleton(Failure)
+
+    # 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`
+    def crosses_output?: (Failure child) -> bool
+
+    # _@param_ `output` — a nested failure's output
+    # 
+    # _@return_ — its fields, for this action's schema
+    def crossing_output: ((FieldStruct::Base | ::Hash[untyped, untyped] | Object) output) -> ::Hash[Symbol, Object]
+
+    # 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`
+    # 
+    # _@param_ `code`
+    def ensure_code_identifier!: (Symbol kind, Object code) -> void
+
+    # 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`
+    def ensure_failure_declared!: (Symbol code) -> void
+
+    # 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` — the declaration that would add the schema
+    # 
+    # _@param_ `code`
+    # 
+    # _@param_ `output` — the output given, if any
+    def ensure_output_declared!: (Symbol verb, Symbol code, (::Hash[untyped, untyped] | FieldStruct::Base)? output) -> void
+
+    # 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`
+    def ensure_skip_declared!: (Symbol code) -> void
+
+    # 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).
+    def halt!: () -> void
+
+    # Wrap this action's run in +model.transaction(**options)+.
+    # 
+    #   transactional model: :invoice
+    #   transactional model: Invoice, requires_new: false # join an outer one
+    # 
+    # Run inside a transaction that is already open, the action gets its own
+    # savepoint (+requires_new: true+) unless +requires_new:+ is given, so a
+    # recorded +Failure+ rolls back its own writes rather than leaving them for
+    # the outer transaction to commit.
+    # 
+    # _@param_ `model` — the model whose +transaction+ is used; a Symbol is resolved to a constant (+:invoice+ → +Invoice+)
+    # 
+    # _@param_ `options` — options forwarded to +transaction+
+    def self.transactional: (model: (Symbol | Class), **Object options) -> void
+
+    # The transaction config for this action, inherited from ancestors when
+    # not set locally (decision D9: inherited, overridable).
+    # 
+    # _@return_ — +{model:, options:}+, or +nil+ when
+    # neither this action nor an ancestor is +transactional+
+    def self.transaction_config: () -> ::Hash[Symbol, Object]?
+
+    # Opt this action in (or, with +enabled: false+, back out) to {Job}
+    # honoring the +retry:+ metadata of its declared failures and skips:
+    # +retry: true+ retries the job, +retry: false+ does not. A code with no
+    # +retry:+ key keeps the default mapping. Inherited; a subclass can turn
+    # it off.
+    # 
+    #   class Reindex < Actionable::Action
+    #     honor_retry_metadata
+    #     skips :not_ready, retry: true # the job retries until the index is ready
+    #   end
+    # 
+    # _@param_ `enabled`
+    def self.honor_retry_metadata: (?enabled: bool) -> void
+
+    # Whether {Job} honors this action's +retry:+ metadata, inherited from
+    # ancestors when not set locally. +false+ unless an ancestor opted in.
+    def self.honor_retry_metadata?: () -> bool
+
+    # _@return_ — the declared output schema, or
+    # +nil+ for a free-form action
+    def self.output_schema: () -> singleton(FieldStruct::Base)?
+
+    # _@return_ — the declared input schema, or
+    # +nil+ for a free-form action
+    def self.input_schema: () -> singleton(FieldStruct::Base)?
+
+    # _@return_ — the discriminated-input dispatch, or +nil+
+    # when input isn't discriminated
+    def self.input_dispatch: () -> InputDispatch?
+
+    # _@return_ — the sampling rate for +:sampled+ mode, else +nil+
+    def self.measure_rate: () -> Float?
+
+    # 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}.
+    attr_reader result: 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+.
+    attr_reader input: FieldStruct::Base?
+  end
+
+  # Base class for every error this gem raises. Rescue +Actionable::Error+ to
+  # catch the whole family. Genuine errors are never caught by the runner for
+  # control flow — they propagate to the caller (decision D4).
+  class Error < StandardError
+  end
+
+  # Raised when an action is misconfigured — a reserved output field name, or a
+  # declared step whose method isn't implemented. Surfaced early and clearly so
+  # humans and agents get an actionable message instead of a deep +NoMethodError+
+  # (decision D18).
+  class DefinitionError < Actionable::Error
+  end
+
+  # The single value object a run returns. {Success} and {Failure} are the
+  # concrete subclasses; +Result+ itself is abstract and defines the shared,
+  # FieldStruct-backed shape (decision D5).
+  # 
+  # @abstract Instantiate {Success} or {Failure}, not +Result+ directly.
+  class Result < FieldStruct::Base
+    # _@return_ — +:success+ for a {Success}; the error symbol for a {Failure}
+    def code: () -> Symbol
+
+    # _@return_ — human-readable description of the outcome
+    def message: () -> String?
+
+    # _@return_ — the run's declared, typed output payload (empty by default).
+    # Firms up into an output FieldStruct once output schemas land (D6).
+    def output: () -> Object
+
+    # _@return_ — the run's execution history (empty by default).
+    # Firms up into a +History+ once measurement lands (D10).
+    def history: () -> Object
+
+    # _@return_ — whether the run succeeded. Abstract here; each
+    # subclass flips the predicate that applies to it.
+    def success?: () -> bool
+
+    # _@return_ — whether the run failed.
+    def failure?: () -> bool
+
+    # _@return_ — whether the run was skipped — nothing to do, neither a
+    # success nor a failure (decision D17). Abstract here; {Skipped} flips it.
+    def skipped?: () -> bool
+
+    # _@return_ — alias of {#success?}
+    def successful?: () -> bool
+
+    # _@return_ — alias of {#failure?}
+    def failed?: () -> bool
+
+    # _@return_ — whether the run did not fail — true for both a
+    # {Success} and a {Skipped}. The "happy path didn't error" check.
+    def ok?: () -> bool
+
+    # _@return_ — a compact, field-sorted, deterministic representation —
+    # the declared attributes plus the +errors+ collection, sorted by name,
+    # so equal results always render identically.
+    def inspect: () -> String
+
+    # _@return_ — same deterministic representation as {#inspect}
+    def to_s: () -> String
+
+    # _@return_ — the outcome as a single symbol — +:success+, +:failure+,
+    # or +:skipped+. The coarse-grained companion to the specific {#code}.
+    def status: () -> Symbol
+
+    # A plain-Hash view of the result — +code+, +message+, the +output+ and
+    # +history+ rendered to primitives, and the +errors+ collection as a Hash
+    # (decision D19). The serializable companion to {#inspect}.
+    def to_h: () -> ::Hash[Symbol, Object]
+
+    # A compact element for an HTTP/batch response: the item's position, its
+    # {#status}, the id read off the typed output, and its errors (decision
+    # D19). Lets a controller map a batch of results without hand-rolling the
+    # shape.
+    # 
+    #   results.each_with_index.map { |r, i| r.to_api_h(index: i) }
+    # 
+    # _@param_ `index` — the element's position in a batch
+    # 
+    # _@param_ `id_field` — the output field to surface as +:id+ (default +:id+)
+    def to_api_h: (?index: Integer?, ?id_field: Symbol) -> ::Hash[Symbol, Object]
+
+    # Convenience delegation: a declared output field is readable straight off
+    # the result (+result.invoice+ → +result.output.invoice+). Only fields
+    # declared on a typed output schema delegate; incidental data never does
+    # (decision D6).
+    # 
+    # _@param_ `name` — the method name asked about (Ruby passes a Symbol)
+    # 
+    # _@param_ `include_private` — whether private methods count
+    def respond_to_missing?: (Symbol name, ?bool include_private) -> bool
+
+    # _@param_ `name` — the method called
+    # 
+    # _@param_ `args` — its arguments, forwarded to the output
+    # 
+    # _@return_ — the output field's value: left untyped on purpose,
+    # like any field reader whose type the schema decides
+    # 
+    # _@see_ `#respond_to_missing?`
+    def method_missing: (Symbol name, *Object args) -> untyped
+
+    # _@param_ `name`
+    # 
+    # _@return_ — whether +name+ is a declared field on a typed output
+    def delegates_to_output?: (Symbol name) -> bool
+
+    # Read +name+ off the output — a declared field on a typed output, a key on
+    # a Hash output, or +nil+ when absent.
+    # 
+    # _@param_ `name`
+    def output_field: (Symbol name) -> Object?
+
+    # The output fields the run actually set (captured instance variables and
+    # +succeed+/+skip+ kwargs), as opposed to fields left nil or at their
+    # default. A parent absorbing a nested action's output copies only these
+    # (decision D3). +nil+ when unknown, e.g. a hand-built result.
+    attr_accessor output_fields_set: ::Array[Symbol]?
+  end
+
+  # Executes an action instance's steps and produces the {Result}.
+  # 
+  # The main loop runs inside {Actionable.catch_halt}, so a halting step
+  # (+throw Actionable::HALT+) unwinds out of the loop without running the
+  # remaining steps. Genuine exceptions are not caught — they propagate to the
+  # caller (decision D4). When no step recorded a result, the run auto-succeeds.
+  # 
+  # After the main steps the runner picks the lifecycle hook category from the
+  # outcome (+on_success+ vs +on_failure+) and runs it, then the +always+ hooks
+  # (decision D2). Hooks are ordinary methods: they may record via the
+  # control-flow verbs, and a halting verb (+fail!+ / +skip!+ / +succeed!+ /
+  # +halt!+) has its result adopted, then stops the remaining hooks of its own
+  # phase: a halt in an outcome hook skips the rest of that category but the
+  # +always+ hooks still run (seeing the adopted result), and a halt in an
+  # +always+ hook skips the remaining +always+ hooks. The output is refreshed
+  # (re-captured and re-validated) after the main steps and after each hook
+  # (decision D6).
+  # 
+  # When the action (or an enclosing measuring run) enables measurement, the
+  # runner records a {History} of every step — section, name, timing, result
+  # code, and nested child history (decision D10).
+  class Runner
+    include Actionable::Rails::RunnerAfterCommit
+    include Actionable::Rails::RunnerTransaction
+
+    # _@param_ `instance` — the action instance to run
+    def initialize: (Action _instance) -> void
+
+    # Run the action's steps and lifecycle hooks, returning the finalized result.
+    # 
+    # _@return_ — the recorded result (or a fresh {Success} if none was
+    # set), with its typed output and (when measuring) history assigned
+    def run: () -> Result
+
+    # Run the body, marking measurement active so nested runs cascade.
+    # 
+    # _@return_ — the block's value
+    def measured: () ?{ () -> Object } -> Object
+
+    # The main steps, then the outcome and always lifecycle hooks.
+    def perform: () -> void
+
+    # Run each declared step in order, skipping any whose guard opts out.
+    def run_steps: () -> void
+
+    # Run the outcome-appropriate hooks then the +always+ hooks, each phase in
+    # its own halt catch: a hook's halt stops the remaining hooks of its phase
+    # only, so +always+ hooks run even after an outcome hook halts. The
+    # category is fixed by the post-main-steps outcome — it does not re-dispatch
+    # if a hook later flips the result.
+    def run_lifecycle: () -> void
+
+    # Run one hook, then adopt any result it recorded and refresh the output.
+    # A hook that halts is caught here first so its result is adopted too, then
+    # the halt is re-thrown to stop the remaining hooks of the phase.
+    # 
+    # _@param_ `section`
+    # 
+    # _@param_ `hook`
+    def run_hook: (Symbol section, Steps::Base hook) -> void
+
+    # Run one main step, skipping it when its guard opts out.
+    # 
+    # _@param_ `section`
+    # 
+    # _@param_ `step`
+    def call_step: (Symbol section, Steps::Base step) -> void
+
+    # Time and record a step into the history when measuring; otherwise just run
+    # it. The result code is recorded only when the step changed the recorded
+    # result, so steps that merely set ivars carry a nil code.
+    # 
+    # _@param_ `section`
+    # 
+    # _@param_ `step`
+    def record: (Symbol section, Steps::Base step) -> void
+
+    # Capture, coerce, and attach the typed output (decision D6). Free-form
+    # actions (no schema) keep whatever output was recorded. With a schema,
+    # capture the declared-field ivars overlaid with any +succeed+ kwargs
+    # (kwargs win) and coerce them. Only a strict {Success} is validated — its
+    # output failing validation means it can't really have succeeded, so
+    # +@result+ becomes a +Failure(:invalid_output)+.
+    # 
+    # A {Failure} or {Skipped} whose code declares its own output schema
+    # (decision D23) is built from its kwargs alone and validated the same way.
+    # Without one it carries an empty output under typed outcomes, and
+    # otherwise a best-effort, unvalidated capture into the success schema
+    # (decisions D6/D17). The failures the gem builds keep their output.
+    def refresh_output: () -> void
+
+    def refresh_success_output: () -> void
+
+    # Build the output struct and note on the result which fields the run
+    # actually set, so a parent absorbing this run copies only those (D3).
+    # 
+    # _@param_ `schema`
+    # 
+    # _@param_ `attrs`
+    def build_output: (singleton(FieldStruct::Base) schema, ::Hash[Symbol, Object] attrs) -> FieldStruct::Base
+
+    # The result the action instance recorded, refusing anything else stored
+    # in the reserved +@result+ ivar with a clear error instead of a deep
+    # +NoMethodError+.
+    def instance_result: () -> Result?
+
+    # Attach +output+ when it is valid; otherwise the run ends as a
+    # +Failure(:invalid_output)+ carrying it.
+    # 
+    # _@param_ `output`
+    def attach_validated: (FieldStruct::Base output) -> void
+
+    # Attach a best-effort output to a failure or skip without validating it
+    # (decisions D6/D17). Assigning a struct makes the result validate it, which
+    # would add an +output+ error, so only the errors the result already had
+    # are kept.
+    # 
+    # _@param_ `output`
+    def attach_unvalidated: (FieldStruct::Base output) -> void
+
+    # _@return_ — the output schema the skip or
+    # failure's code declares (decision D23), if any
+    def outcome_schema: () -> singleton(FieldStruct::Base)?
+
+    # A skip or failure's output fields, from the kwargs it was recorded with,
+    # never from instance variables (decision D23). After a hook refresh the
+    # output is already the struct, so its own attributes are reused, limited
+    # to the fields the kwargs set so the set-fields marker stays true.
+    # 
+    # _@param_ `schema`
+    def outcome_attributes: (singleton(FieldStruct::Base) schema) -> ::Hash[Symbol, Object]
+
+    # _@return_ — whether the result is a failure the gem itself built
+    # ({Action::GEM_FAILURE_CODES}), whose output is left as it is
+    def gem_failure?: () -> bool
+
+    # Declared-field ivars from the action instance, overlaid with the recorded
+    # +succeed+ / +skip+ kwargs, kwargs winning on conflict.
+    # 
+    # _@param_ `schema`
+    def captured_attributes: (singleton(FieldStruct::Base) schema) -> ::Hash[Symbol, Object]
+
+    # The +succeed+ / +skip+ kwargs recorded with the current result. They sit
+    # on +@result.output+ as a Hash only until the first refresh replaces it
+    # with the struct, so they are kept here to overlay every later refresh
+    # (after each hook) as well.
+    def recorded_overrides: () -> ::Hash[Symbol, Object]
+
+    # _@param_ `output` — the invalid output struct
+    # 
+    # _@return_ — code +:invalid_output+, with the output's validation
+    # errors copied onto the failure and the (invalid) output attached
+    def invalid_output_failure: (FieldStruct::Base output) -> Failure
+
+    # _@return_ — the running action's transaction config
+    def transaction_config: () -> ::Hash[Symbol, Object]?
+
+    # The configured options, plus +requires_new: true+ when a transaction is
+    # already open and the action did not say otherwise. Joining the outer
+    # transaction would swallow this run's rollback, so a recorded failure's
+    # writes would commit with it (decision D9).
+    # 
+    # _@param_ `model`
+    # 
+    # _@param_ `options`
+    def transaction_options: (Class model, ::Hash[Symbol, Object] options) -> ::Hash[Symbol, Object]
+
+    # _@param_ `model`
+    # 
+    # _@return_ — the resolved model class
+    def resolve_model: ((Symbol | Class) model) -> Class
+
+    def schedule_after_commit: () -> void
+
+    # Run the hooks in order. A halt stops the remaining ones; nothing they
+    # record reaches the already-returned result.
+    # 
+    # _@param_ `hooks`
+    def run_after_commit_hooks: (::Array[Steps::Base] hooks) -> void
+  end
+
+  # An ordered record of the steps a run executed, when measurement is enabled
+  # (decision D10). Each entry is a {History::Step}; nested action steps carry
+  # their child's +History+.
+  class History
+    def initialize: () -> void
+
+    # Append a recorded step.
+    # 
+    # _@param_ `step`
+    def <<: (Step step) -> self
+
+    # _@return_ — whether any step has been recorded
+    def empty?: () -> bool
+
+    # _@return_ — the summed duration of every recorded step
+    def took: () -> Float
+
+    # _@return_ — each step as a JSON-ready hash
+    def as_json: () -> ::Array[::Hash[untyped, untyped]]
+
+    # _@return_ — the history serialized to JSON via Oj (decision D15).
+    # +:compat+ mode emits plain JSON (string keys, symbols as strings) rather
+    # than Oj's default object-marker encoding.
+    def to_json: () -> String
+
+    # _@return_ — the recorded steps, in execution order
+    attr_reader steps: ::Array[Step]
+
+    # One recorded step: which section it ran in, its name, when it started, how
+    # long it took, the result code it produced (if any), and — for action
+    # steps — the nested child {History}.
+    class Step
+      # _@param_ `section`
+      # 
+      # _@param_ `name`
+      # 
+      # _@param_ `started_at`
+      def initialize: (section: Symbol, name: (Symbol | String | Class), started_at: Time) -> void
+
+      # _@return_ — a JSON-ready hash (nested history recurses)
+      def as_json: () -> ::Hash[Symbol, Object]
+
+      # _@return_ — +:main+, +:success+, +:failure+, or +:always+
+      attr_reader section: Symbol
+
+      # _@return_ — the step's name
+      attr_reader name: (Symbol | String | Class)
+
+      # _@return_ — wall-clock start time
+      attr_reader started_at: Time
+
+      # _@return_ — elapsed seconds (monotonic)
+      attr_accessor duration: Float
+
+      # _@return_ — the result code this step recorded, if it set one
+      attr_accessor code: Symbol?
+
+      # _@return_ — the nested action's history, for action steps
+      attr_accessor nested: History?
+    end
+  end
+
+  # A read-only map of every named action class, keyed by class name (decision
+  # D11). {Action} registers each subclass through its +inherited+ hook;
+  # anonymous subclasses (which have no name) are skipped. Used for discovery
+  # and tooling — e.g. sweeping all actions to generate RBS.
+  class Registry
+    def initialize: () -> void
+
+    # Register an action class under its name. No-op for anonymous classes.
+    # 
+    # _@param_ `klass` — the action subclass
+    def register: (Class klass) -> self
+
+    # _@param_ `name` — an action class name
+    # 
+    # _@return_ — the registered class, or +nil+
+    def []: ((String | Symbol) name) -> Class?
+
+    def each: () ?{ (String name, Class klass) -> void } -> (::Enumerator[untyped] | self)
+
+    # _@return_ — the registered class names
+    def keys: () -> ::Array[String]
+
+    # _@return_ — the registered classes
+    def values: () -> ::Array[Class]
+
+    # _@return_ — the number of registered classes
+    def size: () -> Integer
+
+    # _@return_ — whether nothing is registered
+    def empty?: () -> bool
+  end
+
+  # Thread-local measurement context (decision D10). It lets a measuring run
+  # cascade into the nested actions it invokes, and lets an action step attach
+  # its child's history to the step record currently open in the parent runner.
+  # 
+  # All state is per-thread and saved/restored around each scope, so concurrent
+  # runs on different threads never interfere.
+  module Measurement
+    # _@return_ — whether the current thread is inside a measuring run
+    def self.active?: () -> bool
+
+    # _@return_ — the step record nested history attaches to
+    def self.open_step: () -> History::Step?
+
+    # Mark measurement active for the block, so nested runs measure too.
+    # 
+    # _@return_ — the block's value
+    def self.measuring: () ?{ () -> Object } -> Object
+
+    # Make +record+ the open step for the block, so a nested action step can
+    # attach its child's history to it.
+    # 
+    # _@param_ `record`
+    # 
+    # _@return_ — the block's value
+    def self.recording: (History::Step record) ?{ () -> Object } -> Object
+
+    # This thread's measurement state: +:active+ and +:open_step+.
+    def self.store: () -> ::Hash[Symbol, Object]
+
+    # Merge +changes+ into the state for the block, restoring it afterwards.
+    # 
+    # _@param_ `changes` — the keys to override
+    # 
+    # _@return_ — the block's value
+    def self.with: (::Hash[Symbol, Object] changes) ?{ () -> Object } -> Object
+  end
+
+  # Shared branch-value matching for the two places Actionable dispatches on a
+  # value: case steps (decision D3) and discriminated input (decision D19). A
+  # branch value matches by Array membership, by +Regexp#match?+ against the
+  # value's string form, or by +==+.
+  module ValueMatch
+    # _@param_ `branch_value` — the declared branch matcher
+    # 
+    # _@param_ `value` — the runtime value being dispatched on
+    # 
+    # _@return_ — whether +value+ matches +branch_value+
+    def matches?: ((Object | ::Array[untyped] | Regexp) branch_value, Object value) -> bool
+
+    # _@param_ `branch_value` — the declared branch matcher
+    # 
+    # _@param_ `value` — the runtime value being dispatched on
+    # 
+    # _@return_ — whether +value+ matches +branch_value+
+    def self.matches?: ((Object | ::Array[untyped] | Regexp) branch_value, Object value) -> bool
+  end
+
+  # The value object returned by {Action.run_each}: an ordered, +Enumerable+
+  # collection of the per-item {Result}s, plus aggregate predicates over them
+  # (decision D19). Each item ran independently — one {Result} per element, in
+  # input order — so a failure in one never affects another.
+  # 
+  #   batch = ImportRow.run_each(rows) { |row| {row: row} }
+  #   batch.all_ok?            # => false
+  #   batch.failures.size      # => 2
+  #   batch.to_api_h           # => [{index: 0, status: :success, ...}, ...]
+  class BatchResult
+    include ::Enumerable[Result]
+
+    # _@param_ `results`
+    def initialize: (::Array[Result] results) -> void
+
+    def each: () ?{ (Result result) -> void } -> (::Enumerator[untyped] | self)
+
+    # _@param_ `index`
+    # 
+    # _@return_ — the result at +index+
+    def []: (Integer index) -> Result?
+
+    # _@return_ — the number of results
+    def size: () -> Integer
+
+    # _@return_ — whether the batch ran no items
+    def empty?: () -> bool
+
+    # _@return_ — whether every result is +ok?+ (success or skip);
+    # vacuously true for an empty batch
+    def all_ok?: () -> bool
+
+    # _@return_ — whether any result is a failure
+    def any_failure?: () -> bool
+
+    # _@return_ — whether the batch is mixed — at least one failure and at
+    # least one +ok?+ result
+    def partial?: () -> bool
+
+    # _@return_ — the successful results
+    def successes: () -> ::Array[Result]
+
+    # _@return_ — the failed results
+    def failures: () -> ::Array[Result]
+
+    # _@return_ — the skipped results
+    def skips: () -> ::Array[Result]
+
+    # The batch as an array of API elements, each tagged with its position
+    # (see {Result#to_api_h}). Ready to render as a JSON array of per-item
+    # statuses.
+    # 
+    # _@param_ `id_field` — the output field to surface as +:id+
+    def to_api_h: (?id_field: Symbol) -> ::Array[::Hash[Symbol, Object]]
+
+    # _@return_ — the per-item results, in input order
+    attr_reader results: ::Array[Result]
+  end
+
+  # Runtime selection of an input schema from a discriminator value (decision
+  # D19, declared with +input_for+). Each branch maps a match value to a
+  # FieldStruct schema; an optional +default+ catches the rest. Lets a
+  # polymorphic payload (e.g. +event_type+ → shape) use typed, validated input.
+  # 
+  #   input_for :event_type do
+  #     on 'sale',   SaleShape
+  #     on 'refund', RefundShape
+  #     default      UnknownShape
+  #   end
+  class InputDispatch
+    # Build a dispatch from an +input_for+ declaration.
+    # 
+    # _@param_ `discriminator` — the kwarg whose value selects the schema
+    def self.define: ((Symbol | String) discriminator) -> InputDispatch
+
+    # _@param_ `discriminator`
+    # 
+    # _@param_ `branches`
+    # 
+    # _@param_ `default_schema`
+    def initialize: (Symbol discriminator, ::Array[[Object, singleton(FieldStruct::Base)]] branches, singleton(FieldStruct::Base)? default_schema) -> void
+
+    # The schema for a discriminator value: the first matching branch, else the
+    # default, else +nil+ (no match and no default).
+    # 
+    # _@param_ `value` — the discriminator value
+    def schema_for: (Object value) -> singleton(FieldStruct::Base)?
+
+    # _@return_ — every distinct schema reachable
+    # through this dispatch (branches plus default)
+    def schemas: () -> ::Array[singleton(FieldStruct::Base)]
+
+    # _@return_ — the branch match values, in declaration order
+    def variants: () -> ::Array[Object]
+
+    # _@return_ — the discriminator field read from +.run+'s kwargs
+    attr_reader discriminator: Symbol
+
+    # _@return_ — ordered [match, schema] pairs
+    attr_reader branches: ::Array[[Object, singleton(FieldStruct::Base)]]
+
+    # _@return_ — the fallback schema
+    attr_reader default_schema: singleton(FieldStruct::Base)?
+
+    # Collects +on+/+default+ branch declarations inside an +input_for+ block.
+    class Builder
+      def initialize: () -> void
+
+      # Register a branch. +value+ matches the discriminator by +==+, by
+      # Array membership, or by +Regexp#match?+ (see {ValueMatch}).
+      # 
+      # _@param_ `value`
+      # 
+      # _@param_ `schema`
+      def on: ((Object | ::Array[untyped] | Regexp) value, singleton(FieldStruct::Base) schema) -> void
+
+      # Register the fallback schema, used when no +on+ branch matches.
+      # 
+      # _@param_ `schema`
+      def default: (singleton(FieldStruct::Base) schema) -> void
+
+      # _@return_ — ordered [match, schema] pairs
+      attr_reader branches: ::Array[[Object, singleton(FieldStruct::Base)]]
+
+      # _@return_ — the fallback schema, if declared
+      attr_reader default_schema: singleton(FieldStruct::Base)?
+    end
+  end
+
+  # A failed run's result. Its +code+ is the error symbol describing why the
+  # run failed (e.g. +:not_found+, +:invalid_input+), defaulting to +:error+.
+  class Failure < Actionable::Result
+    # _@return_ — the error code; defaults to +:error+
+    def code: () -> Symbol
+
+    # _@return_ — the metadata the action declared for this
+    # code with {Action.fails} (decision D20), so an adapter can read it off the
+    # result without the action class. Empty when the code isn't declared.
+    # The gem stores and passes it through but never interprets it.
+    def metadata: () -> ::Hash[Symbol, Object]
+
+    def failure?: () -> bool
+
+    # A plain-Hash view of the failure: {Result#to_h} plus its declared
+    # +metadata+ (decision D20).
+    def to_h: () -> ::Hash[Symbol, Object]
+
+    # Copy another object's FieldStruct-style errors onto this failure's own
+    # errors collection. The shared mechanism behind +Failure(:invalid_input)+,
+    # +Failure(:invalid_output)+, and the {Action#fail_with} verb (decision D19).
+    # 
+    # _@param_ `source` — any object whose +errors+ responds to +to_h+ (a +FieldStruct::Base+ instance, or another result)
+    # 
+    # _@return_ — so callers can build-and-absorb in one expression
+    def absorb_errors_from: (untyped source) -> self
+  end
+
+  # A skipped run's result (decision D17): the action had nothing to do — not a
+  # success (no real work), but not a failure either. Its +code+ is the skip
+  # reason (e.g. +:not_ready+), defaulting to +:skipped+.
+  class Skipped < Actionable::Result
+    # _@return_ — the skip reason; defaults to +:skipped+
+    def code: () -> Symbol
+
+    # _@return_ — the metadata the action declared for this
+    # code with {Action.skips} (decision D21), so an adapter can read it off the
+    # result without the action class. Empty when the code isn't declared.
+    # The gem stores and passes it through but never interprets it.
+    def metadata: () -> ::Hash[Symbol, Object]
+
+    def skipped?: () -> bool
+
+    # A plain-Hash view of the skip: {Result#to_h} plus its declared +metadata+
+    # (decision D21).
+    def to_h: () -> ::Hash[Symbol, Object]
+  end
+
+  # A successful run's result. Its +code+ defaults to +:success+.
+  class Success < Actionable::Result
+    # _@return_ — always +:success+ unless explicitly overridden
+    def code: () -> Symbol
+
+    def success?: () -> bool
+  end
+
+  module Rails
+    # The +after_commit+ hook kind. Prepended onto {Actionable::Action}'s
+    # singleton class by +actionable/rails+, so the core never knows about it
+    # (decision D8).
+    # 
+    # An +after_commit+ hook runs once, after the database work of a
+    # successful run has really committed: it is registered with
+    # +ActiveRecord.after_all_transactions_commit+ when the run ends, so it
+    # waits for the outermost open transaction (not the action's own
+    # savepoint), runs immediately when none is open, and never runs if any
+    # enclosing transaction rolls back.
+    module AfterCommit
+      MINIMUM_ACTIVE_RECORD: String
+
+      # Declare a hook that runs after the outermost database transaction
+      # commits, iff the run's final result is a {Success}.
+      # 
+      #   after_commit :send_receipt
+      #   after_commit NotifyWarehouse, input: %i[order]
+      # 
+      # The run is over by then: the result has been returned (or is about to
+      # be, when no transaction is open), so the hook cannot change it, a
+      # halting verb only stops the remaining +after_commit+ hooks, and the
+      # hook is not recorded in the history. An exception it raises propagates
+      # from wherever the commit happens: the outer +transaction+ call, or
+      # +.run+ itself when no transaction was open.
+      # 
+      # _@param_ `target` — the instance method or nested action to run
+      # 
+      # _@param_ `options` — step options (+:if+, +:unless+, and for a nested action +:input+)
+      def after_commit: ((Symbol | String | singleton(Actionable::Action)) target, **Object options) -> ::Set[Steps::Base]
+
+      # Hooks that run after the outermost transaction commits a successful run.
+      def after_commit_hooks: () -> ::Set[Steps::Base]
+
+      # {Actionable::Action.describe}, with the +after_commit+ hooks listed as
+      # one more +:hooks+ section, so {Actionable::Action.describe_text} shows
+      # them too (only when there are any, like the core sections).
+      def describe: () -> ::Hash[Symbol, Object]
+
+      # Give each subclass its own copy of the inherited +after_commit+ hooks.
+      # 
+      # _@param_ `subclass`
+      def inherited: (Class subclass) -> void
+
+      # Extend the run-start guard (decision D18) to the +after_commit+ hooks.
+      # 
+      # _@param_ `instance`
+      def ensure_steps_implemented!: (Action _instance) -> void
+
+      # Extend the recording-verb position check (owner ruling R5) to the
+      # +after_commit+ hooks.
+      def verb_checked_steps: () -> ::Array[Steps::Base]
+
+      def ensure_after_commit_supported!: () -> void
+    end
+
+    # Prepended onto {Actionable::Runner} (outside {RunnerTransaction}) to
+    # register a successful run's +after_commit+ hooks once the run, and its
+    # own transaction, are over.
+    module RunnerAfterCommit
+      def run: () -> Result
+
+      def schedule_after_commit: () -> void
+
+      # Run the hooks in order. A halt stops the remaining ones; nothing they
+      # record reaches the already-returned result.
+      # 
+      # _@param_ `hooks`
+      def run_after_commit_hooks: (::Array[Steps::Base] hooks) -> void
+    end
+
+    # Internal signal raised inside a transaction block to trigger a rollback
+    # without surfacing as a genuine error. The runner wrapper swallows it; a
+    # real ActiveRecord transaction rolls back and re-raises it (as it does for
+    # any exception), and the wrapper catches it outside the block.
+    class Rollback < StandardError
+    end
+
+    # The +transactional+ class macro (decision D9). Extended onto
+    # {Actionable::Action} by +actionable/rails+.
+    module Transactions
+      # Wrap this action's run in +model.transaction(**options)+.
+      # 
+      #   transactional model: :invoice
+      #   transactional model: Invoice, requires_new: false # join an outer one
+      # 
+      # Run inside a transaction that is already open, the action gets its own
+      # savepoint (+requires_new: true+) unless +requires_new:+ is given, so a
+      # recorded +Failure+ rolls back its own writes rather than leaving them for
+      # the outer transaction to commit.
+      # 
+      # _@param_ `model` — the model whose +transaction+ is used; a Symbol is resolved to a constant (+:invoice+ → +Invoice+)
+      # 
+      # _@param_ `options` — options forwarded to +transaction+
+      def transactional: (model: (Symbol | Class), **Object options) -> void
+
+      # The transaction config for this action, inherited from ancestors when
+      # not set locally (decision D9: inherited, overridable).
+      # 
+      # _@return_ — +{model:, options:}+, or +nil+ when
+      # neither this action nor an ancestor is +transactional+
+      def transaction_config: () -> ::Hash[Symbol, Object]?
+    end
+
+    # Prepended onto {Actionable::Runner} so a +transactional+ action runs its
+    # whole pipeline inside a transaction. A raised exception or a recorded
+    # +Failure+ rolls everything back; a +Success+ commits (decision D9).
+    module RunnerTransaction
+      def run: () -> Result
+
+      # _@return_ — the running action's transaction config
+      def transaction_config: () -> ::Hash[Symbol, Object]?
+
+      # The configured options, plus +requires_new: true+ when a transaction is
+      # already open and the action did not say otherwise. Joining the outer
+      # transaction would swallow this run's rollback, so a recorded failure's
+      # writes would commit with it (decision D9).
+      # 
+      # _@param_ `model`
+      # 
+      # _@param_ `options`
+      def transaction_options: (Class model, ::Hash[Symbol, Object] options) -> ::Hash[Symbol, Object]
+
+      # _@param_ `model`
+      # 
+      # _@return_ — the resolved model class
+      def resolve_model: ((Symbol | Class) model) -> Class
+    end
+  end
+end