axn 0.1.0.pre.alpha.2.6.1 → 0.1.0.pre.alpha.2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30c00229f0062bdba5979d0e69de4ffddb6bece3f31413f83b7f7778d3075ef7
-  data.tar.gz: 92d944caf300ddfc9a134d34ae2cb73e6d235e0af9f7a10a3ee93065ae834690
+  metadata.gz: 57d67670bb1cf60960aa2bb8234a5894a611801b69a89957057bfffd07ace8cd
+  data.tar.gz: 9e0025cbe4bc367e1351ea867d630b9fdb3d706547d676b9cd2162e8fda0ef38
 SHA512:
-  metadata.gz: 600b1572f324b8cbbaf2b5dd48108546db86e63e3c7d49a04e1eb9f0f2e83720eafdaabb94ccf0550ff1c0e63b3ec555950443eb5c064698dbc65cf97c2b1733
-  data.tar.gz: e9229f25cd10dcc54f1f7c5b83ff81b997d96263296818caaf2cfc245fde93ab24d7f0605700ea042c085ab7456f5fc1b20c2cc643324609bc0f4662ecbdcd21
+  metadata.gz: 70cc7c2851d95956278d43c746190dd5173ddda62a9a931ae9538374cf75b72523cc7f9b3524a6df6b8b8d57c969fb5510c07fad56b36312130ae86c59e48a15
+  data.tar.gz: f3f961781373a05284ddc54072baaf13998d235528110bf482c221e5f27d6142ab261516d8237bd0689d1161887eef6b567e8ecb4688d400a20ec32d1ae33837

data/CHANGELOG.md

@@ -1,7 +1,18 @@
 # Changelog
 
-## Unreleased
-* N/A
+## 0.1.0-alpha.2.7.1
+* [FEAT] Implemented symbol method handler support for callbacks
+
+## 0.1.0-alpha.2.7
+* [BREAKING] Replaced `messages` declaration with separate `success` and `error` calls
+* [BREAKING] Removed `rescues` method (use `error_from` for custom error messages; all exceptions now report to `on_exception` handlers)
+* [BREAKING] Replaced `error_from` with an optional `if:` argument on `error`
+  * [FEAT] Implemented conditional success message filtering as well
+* [FEAT] Added block support for `error` and `success`
+* [FEAT] `if:` now supports symbol predicates referencing instance methods (arity 0, 1, or keyword `exception:`). If the method accepts `exception:` it is passed as a keyword; else if it accepts one positional arg, it is passed positionally; otherwise it is called with no args. If the method is missing, the symbol falls back to constant lookup (e.g., `:ArgumentError`).
+* [FEAT] `success`/`error` now accept symbol method names (e.g., `success :local_method`). Handlers can receive the exception via keyword (`exception:`) or single positional argument; otherwise they are called with no args.
+* [BREAKING] Updated callback methods (`on_success`, `on_error`, `on_failure`, `on_exception`) to use consistent `if:` interface (matching messages)
+* [FEAT] Added `unless:` support to both `success`/`error` messages and callbacks (`on_success`, `on_error`, `on_failure`, `on_exception`)
 
 ## 0.1.0-alpha.2.6.1
 * [FEAT] Added `elapsed_time` and `outcome` methods to `Action::Result`

data/docs/reference/action-result.md

@@ -13,7 +13,7 @@ Every `call` invocation on an Action will return an `Action::Result` instance, w
 | `elapsed_time` | Execution time in milliseconds (Float)
 | any `expose`d values | guaranteed to be set if `ok?` (since they have outgoing presence validations by default; any missing would have failed the action)
 
-NOTE: `success` and `error` (and so implicitly `message`) can be configured per-action via [the `messages` declaration](/reference/class#messages).
+NOTE: `success` and `error` (and so implicitly `message`) can be configured per-action via [the `success` and `error` declarations](/reference/class#success-and-error).
 
 ### Clarification of exposed values
 

data/docs/reference/class.md

@@ -85,48 +85,148 @@ expects :date, type: Date, preprocess: ->(d) { d.is_a?(Date) ? d : Date.parse(d)
 
 will succeed if given _either_ an actual Date object _or_ a string that Date.parse can convert into one.  If the preprocess callable raises an exception, that'll be swallowed and the action failed.
 
-## `.messages`
+## `.success` and `.error`
 
-The `messages` declaration allows you to customize the `error` and `success` messages on the returned result.
+The `success` and `error` declarations allow you to customize the `error` and `success` messages on the returned result.
 
-Accepts `error` and/or `success` keys.  Values can be a string (returned directly) or a callable (evaluated in the action's context, so can access instance methods and variables).  If `error` is provided with a callable that expects a positional argument, the exception that was raised will be passed in as that value.
+Both methods accept a string (returned directly), a symbol (resolved as a local instance method on the action), or a block (evaluated in the action's context, so can access instance methods and variables).
 
-In callables, you can access:
+When an exception is available (e.g., during `error`), handlers can receive it in either of two equivalent ways:
+- Keyword form: accept `exception:` and it will be passed as a keyword
+- Positional form: if the handler accepts a single positional argument, it will be passed positionally
+
+This applies to both blocks and symbol-backed instance methods. Choose the style that best fits your codebase (clarity vs concision).
+
+In callables and symbol-backed methods, you can access:
 - **Input data**: Use field names directly (e.g., `name`)
 - **Output data**: Use `result.field` pattern (e.g., `result.greeting`)
 - **Instance methods and variables**: Direct access
 
 ```ruby
-messages success: -> { "Hello #{name}, your greeting: #{result.greeting}" },
-         error: ->(e) { "Bad news: #{e.message}" }
+success { "Hello #{name}, your greeting: #{result.greeting}" }
+error { |e| "Bad news: #{e.message}" }
+error { |exception:| "Bad news: #{exception.message}" }
+
+# Using symbol method names
+success :build_success_message
+error :build_error_message
+
+def build_success_message
+  "Hello #{name}, your greeting: #{result.greeting}"
+end
+
+def build_error_message(e)
+  "Bad news: #{e.message}"
+end
+
+def build_error_message(exception:)
+  "Bad news: #{exception.message}"
+end
 ```
 
-## `error_from` and `rescues`
+## Conditional messages
 
-While `.messages` sets the _default_ error/success messages and is more commonly used, there are times when you want specific error messages for specific failure cases.
+While `.error` and `.success` set the default messages, you can register conditional messages using an optional `if:` or `unless:` matcher. The matcher can be:
 
-`error_from` and `rescues` both register a matcher (exception class, exception class name (string), or callable) and a message to use if the matcher succeeds.  They act exactly the same, except if a matcher registered with `rescues` succeeds, the exception _will not_ trigger the configured exception handlers (global or specific to this class).
+- an exception class (e.g., `ArgumentError`)
+- a class name string (e.g., `"Action::InboundValidationError"`)
+- a symbol referencing a local instance method predicate (arity 0 or 1, or keyword `exception:`), e.g. `:bad_input?`
+- a callable (arity 0 or 1, or keyword `exception:`)
 
-Callable matchers and messages follow the same data access patterns as other callables: input fields directly, output fields via `result.field`, instance variables, and methods.
+Symbols are resolved as methods on the action instance. If the method accepts `exception:` it will be passed as a keyword; otherwise, if it accepts one positional argument, the raised exception is passed positionally; otherwise it is called with no arguments. If the action does not respond to the symbol, we fall back to constant lookup (e.g., `if: :ArgumentError` behaves like `if: ArgumentError`). Symbols are also supported for the message itself (e.g., `success :method_name`), resolved via the same rules.
 
 ```ruby
-messages error: "bad"
+error "bad"
+
+# Custom message with exception class matcher
+error "Invalid params provided", if: ActiveRecord::InvalidRecord
+
+# Custom message with callable matcher and message
+error(if: ArgumentError) { |e| "Argument error: #{e.message}" }
+error(if: -> { name == "bad" }) { "Bad input #{name}, result: #{result.status}" }
+
+# Custom message with symbol predicate (arity 0)
+error "Transient error, please retry", if: :transient_error?
+
+def transient_error?
+  # local decision based on inputs/outputs
+  name == "temporary"
+end
+
+# Symbol predicate (arity 1), receives the exception
+error(if: :argument_error?) { |e| "Bad argument: #{e.message}" }
+
+def argument_error?(e)
+  e.is_a?(ArgumentError)
+end
+
+# Symbol predicate (keyword), receives the exception via keyword
+error(if: :argument_error_kw?) { |exception:| "Bad argument: #{exception.message}" }
+
+def argument_error_kw?(exception:)
+  exception.is_a?(ArgumentError)
+end
+
+# Lambda predicate with keyword
+error "AE", if: ->(exception:) { exception.is_a?(ArgumentError) }
+
+# Using unless: for inverse logic
+error "Custom error", unless: :should_skip?
+
+def should_skip?
+  # local decision based on inputs/outputs
+  name == "temporary"
+end
+
+::: warning
+You cannot use both `if:` and `unless:` for the same message - this will raise an `ArgumentError`.
+:::
+
+### Message ordering and inheritance
 
-# Note this will NOT trigger Action.config.on_exception
-rescues ActiveRecord::InvalidRecord => "Invalid params provided"
+Messages are evaluated in **last-defined-first** order, meaning the most recently defined message that matches its conditions will be used. This applies to both success and error messages:
 
-# These WILL trigger error handler (callable matcher + message with data access)
-error_from ArgumentError, ->(e) { "Argument error: #{e.message}" }
-error_from -> { name == "bad" }, -> { "Bad input #{name}, result: #{result.status}" }
+```ruby
+class ParentAction
+  include Action
+
+  success "Parent success message"
+  error "Parent error message"
+end
+
+class ChildAction < ParentAction
+  success "Child success message"  # This will be used when action succeeds
+  error "Child error message"      # This will be used when action fails
+end
+```
+
+Within a single class, later definitions override earlier ones:
+
+```ruby
+class MyAction
+  include Action
+
+  success "First success message"           # Ignored
+  success "Second success message"          # Ignored
+  success "Final success message"           # This will be used
+
+  error "First error message"               # Ignored
+  error "Second error message"              # Ignored
+  error "Final error message"               # This will be used
+end
+```
+
+When using conditional messages, the system evaluates handlers in the order defined above until it finds one that matches and doesn't raise an exception. If a handler raises an exception, it falls back to the next matching handler, then to static messages, and finally to the default message.
 ```
 
 ## Callbacks
 
 In addition to the [global exception handler](/reference/configuration#on-exception), a number of custom callback are available for you as well, if you want to take specific actions when a given Axn succeeds or fails.
 
-::: danger ALPHA
-* The callbacks themselves are functional. Note the ordering _between_ callbacks is not well defined (currently a side effect of the order they're defined).
-  * Ordering may change at any time so while in alpha DO NOT MAKE ASSUMPTIONS ABOUT THE ORDER OF CALLBACK EXECUTION!
+::: tip Callback Ordering
+* Callbacks are executed in **last-defined-first** order, similar to messages
+* Child class callbacks execute before parent class callbacks
+* Multiple matching callbacks of the same type will *all* execute
 :::
 
 
@@ -135,6 +235,16 @@ In addition to the [global exception handler](/reference/configuration#on-except
   * *Callbacks* (defined below) are executed _after_ the `call` -- exceptions or `fail!`s here will _not_ change `result.ok?`
 :::
 
+
+**Note:** Symbol method handlers for all callback types follow the same argument pattern as [message handlers](#conditional-messages):
+- If the method accepts `exception:` as a keyword, the exception is passed as a keyword
+- If the method accepts one positional argument, the exception is passed positionally
+- Otherwise, the method is called with no arguments
+
+::: warning
+You cannot use both `if:` and `unless:` for the same callback - this will raise an `ArgumentError`.
+:::
+
 ### `on_success`
 
 This is triggered after the Axn completes, if it was successful.  Difference from `after`: if the given block raises an error, this WILL be reported to the global exception handler, but will NOT change `ok?` to false.
@@ -161,22 +271,33 @@ class Foo
 end
 ```
 
-Note that by default the `on_exception` block will be applied to _any_ `StandardError` that is raised, but you can specify a matcher using the same logic as for [`error_from` and `rescues`](#error-for-and-rescues):
+Note that by default the `on_exception` block will be applied to _any_ `StandardError` that is raised, but you can specify a matcher using the same logic as for conditional messages (`if:` or `unless:`):
 
 ```ruby
 class Foo
   include Action
 
-  on_exception NoMethodError do |exception| # [!code focus]
+  on_exception(if: NoMethodError) do |exception| # [!code focus]
     # e.g. trigger a slack error
   end
 
-  on_exception ->(e) { e.is_a?(ZeroDivisionError) } do # [!code focus]
+on_exception(unless: :transient_error?) do |exception| # [!code focus]
+    # e.g. trigger a slack error for non-transient errors
+  end
+
+def transient_error?
+  # local decision based on inputs/outputs
+  name == "temporary"
+end
+
+  on_exception(if: ->(e) { e.is_a?(ZeroDivisionError) }) do # [!code focus]
     # e.g. trigger a slack error
   end
 end
 ```
 
+
 If multiple `on_exception` handlers are provided, ALL that match the raised exception will be triggered in the order provided.
 
 The _global_ handler will be triggered _after_ all class-specific handlers.
+

data/docs/reference/configuration.md

@@ -2,7 +2,6 @@
 
 Somewhere at boot (e.g. `config/initializers/actions.rb` in Rails), you can call `Action.configure` to adjust a few global settings.
 
-
 ```ruby
 Action.configure do |c|
   c.log_level = :info
@@ -22,7 +21,6 @@ By default any swallowed errors are noted in the logs, but it's _highly recommen
 
 For example, if you're using Honeybadger this could look something like:
 
-
 ```ruby
   Action.configure do |c|
     c.on_exception = proc do |e, action:, context:|
@@ -56,13 +54,10 @@ A couple notes:
   * If your handler raises, the failure will _also_ be swallowed and logged
   * This handler is global across _all_ Axns.  You can also specify per-Action handlers via [the class-level declaration](/reference/class#on-exception).
 
-
-## `top_level_around_hook`
+## `wrap_with_trace` and `emit_metrics`
 
 If you're using an APM provider, observability can be greatly enhanced by adding automatic _tracing_ of Action calls and/or emitting count metrics after each call completes.
 
-### Tracing and Metrics
-
 The framework provides two distinct hooks for observability:
 
 - **`wrap_with_trace`**: An around hook that wraps the entire action execution. You MUST call the provided block to execute the action.
@@ -92,7 +87,6 @@ A couple notes:
   * The `wrap_with_trace` hook is an around hook - you must call the provided block to execute the action
   * The `emit_metrics` hook is called after execution with the result - do not call any blocks
 
-
 ## `logger`
 
 Defaults to `Rails.logger`, if present, otherwise falls back to `Logger.new($stdout)`.  But can be set to a custom logger as necessary.
@@ -115,6 +109,10 @@ For a practical example of this in practice, see [our 'memoization' recipe](/rec
 
 Sets the log level used when you call `log "Some message"` in your Action.  Note this is read via a `log_level` class method, so you can easily use inheritance to support different log levels for different sets of actions.
 
+## `env`
+
+Automatically detects the environment from `RACK_ENV` or `RAILS_ENV`, defaulting to `"development"`. This is used internally for conditional behavior (e.g., more verbose logging in non-production environments).
+
 ## Automatic Logging
 
 By default, every `action.call` will emit log lines when it is called and after it completes:
@@ -148,3 +146,37 @@ end
 ```
 
 The `auto_log` method supports inheritance, so subclasses will inherit the setting from their parent class unless explicitly overridden.
+
+## Complete Configuration Example
+
+Here's a complete example showing all available configuration options:
+
+```ruby
+Action.configure do |c|
+  # Logging
+  c.log_level = :info
+  c.logger = Rails.logger
+
+  # Exception handling
+  c.on_exception = proc do |e, action:, context:|
+    message = "[#{action.class.name}] Failing due to #{e.class.name}: #{e.message}"
+    Rails.logger.warn(message)
+    Honeybadger.notify(message, context: { axn_context: context })
+  end
+
+  # Observability
+  c.wrap_with_trace = proc do |resource, &action|
+    Datadog::Tracing.trace("Action", resource:) do
+      action.call
+    end
+  end
+
+  c.emit_metrics = proc do |resource, result|
+    Datadog::Metrics.increment("action.#{resource.underscore}", tags: { outcome: result.outcome })
+    Datadog::Metrics.histogram("action.duration", result.elapsed_time, tags: { resource: })
+  end
+
+  # Global includes
+  c.additional_includes = [MyCustomModule]
+end
+```

data/docs/reference/instance.md

@@ -63,7 +63,7 @@ NOTE: expects a single action call in the block -- if there are multiple calls,
 
 ::: tip Versus `call!`
 * If you just want to make sure your action fails if the subaction fails: call subaction via `call!` (any failures will raise, which will fail the parent).
-  * Note this passes _child_ exception into _parent_ `messages :error` parsing.
+  * Note this passes _child_ exception into _parent_ `error` message parsing.
 * If you want _the child's_ `result.error` to become the _parent's_ `result.error` on failure, use `hoist_errors` + `call`
 :::
 

data/docs/usage/writing.md

@@ -68,7 +68,7 @@ See [the reference doc](/reference/instance) for a few more handy helper methods
 
 The default `error` and `success` message strings ("Something went wrong" / "Action completed successfully", respectively) _are_ technically safe to show users, but you'll often want to set them to something more useful.
 
-There's a `messages` declaration for that -- you can set strings (most common) or a callable (note for the error case, if you give it a callable that expects a single argument, the exception that was raised will be passed in).
+There are `success` and `error` declarations for that -- you can set strings (most common) or a callable (note for the error case, if you give it a callable that expects a single argument, the exception that was raised will be passed in).
 
 For instance, configuring the action like this:
 
@@ -79,8 +79,8 @@ class Foo
   expects :name, type: String
   exposes :meaning_of_life
 
-  messages success: -> { "Revealed to #{name}: #{result.meaning_of_life}" }, # [!code focus:2]
-           error: ->(e) { "No secret of life for you: #{e.message}" }
+  success { "Revealed to #{name}: #{result.meaning_of_life}" } # [!code focus:2]
+  error { |e| "No secret of life for you: #{e.message}" }
 
   def call
     fail! "Douglas already knows the meaning" if name == "Doug"

data/lib/action/core/context/facade.rb

@@ -35,35 +35,5 @@ module Action
     def action_name = @action.class.name.presence || "The action"
 
     def context_data_source = raise NotImplementedError
-
-    def determine_error_message(only_default: false)
-      return @context.error_from_user if @context.error_from_user.present?
-
-      # We need an exception for interceptors, and also in case the messages.error callable expects an argument
-      exception = @context.exception || Action::Failure.new
-
-      msg = action._error_msg
-
-      unless only_default
-        interceptor = action.class._error_interceptor_for(exception:, action:)
-        msg = interceptor.message if interceptor
-      end
-
-      stringified(msg, exception:).presence || "Something went wrong"
-    end
-
-    # Allow for callable OR string messages
-    def stringified(msg, exception: nil)
-      return msg.presence unless msg.respond_to?(:call)
-
-      # The error message callable can take the exception as an argument
-      if exception && msg.arity == 1
-        action.instance_exec(exception, &msg)
-      else
-        action.instance_exec(&msg)
-      end
-    rescue StandardError => e
-      Axn::Util.piping_error("determining message callable", action:, exception: e)
-    end
   end
 end

data/lib/action/core/context/internal.rb

@@ -5,9 +5,15 @@ require "action/core/context/facade"
 module Action
   # Inbound / Internal ContextFacade
   class InternalContext < ContextFacade
-    # So can be referenced from within e.g. rescues callables
+    # Available for use from within message callables
     def default_error
-      [@context.error_prefix, determine_error_message(only_default: true)].compact.join(" ").squeeze(" ")
+      msg = action.class._static_message_for(:error, action:, exception: @context.exception || Action::Failure.new)
+      [@context.error_prefix, msg.presence || "Something went wrong"].compact.join(" ").squeeze(" ")
+    end
+
+    def default_success
+      msg = action.class._static_message_for(:success, action:, exception: nil)
+      msg.presence || "Action completed successfully"
     end
 
     private

data/lib/action/core/flow/callbacks.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "action/core/event_handlers"
+require "action/core/flow/handlers"
 
 module Action
   module Core
@@ -8,44 +8,45 @@ module Action
       module Callbacks
         def self.included(base)
           base.class_eval do
-            class_attribute :_error_handlers, default: []
-            class_attribute :_exception_handlers, default: []
-            class_attribute :_failure_handlers, default: []
-            class_attribute :_success_handlers, default: []
+            class_attribute :_callbacks_registry, default: Action::Core::Flow::Handlers::Registry.empty
 
             extend ClassMethods
           end
         end
 
         module ClassMethods
-          # ONLY raised exceptions (i.e. NOT fail!). Skipped if exception is rescued via .rescues.
-          def on_exception(matcher = -> { true }, &handler)
-            raise ArgumentError, "on_exception must be called with a block" unless block_given?
-
-            self._exception_handlers += [Action::EventHandlers::ConditionalHandler.new(matcher:, handler:)]
+          # Internal dispatcher
+          def _dispatch_callbacks(event_type, action:, exception: nil)
+            _callbacks_registry.for(event_type).each do |handler|
+              handler.apply(action:, exception:)
+            end
           end
 
-          # ONLY raised on fail! (i.e. NOT unhandled exceptions).
-          def on_failure(matcher = -> { true }, &handler)
-            raise ArgumentError, "on_failure must be called with a block" unless block_given?
+          # ONLY raised exceptions (i.e. NOT fail!).
+          def on_exception(handler = nil, **, &block) = _add_callback(:exception, handler:, **, block:)
 
-            self._failure_handlers += [Action::EventHandlers::ConditionalHandler.new(matcher:, handler:)]
-          end
+          # ONLY raised on fail! (i.e. NOT unhandled exceptions).
+          def on_failure(handler = nil, **, &block) = _add_callback(:failure, handler:, **, block:)
 
-          # Handles both fail! and unhandled exceptions... but is NOT affected by .rescues
-          def on_error(matcher = -> { true }, &handler)
-            raise ArgumentError, "on_error must be called with a block" unless block_given?
-
-            self._error_handlers += [Action::EventHandlers::ConditionalHandler.new(matcher:, handler:)]
-          end
+          # Handles both fail! and unhandled exceptions
+          def on_error(handler = nil, **, &block) = _add_callback(:error, handler:, **, block:)
 
           # Executes when the action completes successfully (after all after hooks complete successfully)
           # Runs in child-first order (child handlers before parent handlers)
-          def on_success(&handler)
-            raise ArgumentError, "on_success must be called with a block" unless block_given?
+          def on_success(handler = nil, **, &block) = _add_callback(:success, handler:, **, block:)
+
+          private
+
+          def _add_callback(event_type, handler: nil, block: nil, **kwargs)
+            raise ArgumentError, "on_#{event_type} cannot be called with both :if and :unless" if kwargs.key?(:if) && kwargs.key?(:unless)
+
+            condition = kwargs.key?(:if) ? kwargs[:if] : kwargs[:unless]
+            raise ArgumentError, "on_#{event_type} must be called with a block or symbol" unless block || handler
 
-            # Prepend like after hooks - child handlers run before parent handlers
-            self._success_handlers = [handler] + _success_handlers
+            callback_handler = block || handler
+            matcher = condition.nil? ? nil : Action::Core::Flow::Handlers::Matcher.new(condition, invert: kwargs.key?(:unless))
+            entry = Action::Core::Flow::Handlers::CallbackHandler.new(matcher:, handler: callback_handler)
+            self._callbacks_registry = _callbacks_registry.register(event_type:, entry:)
           end
         end
       end

data/lib/action/core/flow/exception_execution.rb

@@ -9,13 +9,8 @@ module Action
             include InstanceMethods
 
             def _trigger_on_exception(exception)
-              interceptor = self.class._error_interceptor_for(exception:, action: self)
-              return if interceptor&.should_report_error == false
-
               # Call any handlers registered on *this specific action* class
-              self.class._exception_handlers.each do |handler|
-                handler.execute_if_matches(exception:, action: self)
-              end
+              self.class._dispatch_callbacks(:exception, action: self, exception:)
 
               # Call any global handlers
               Action.config.on_exception(exception, action: self, context: context_for_logging)
@@ -27,12 +22,7 @@ module Action
 
             def _trigger_on_success
               # Call success handlers in child-first order (like after hooks)
-              self.class._success_handlers.each do |handler|
-                instance_exec(&handler)
-              rescue StandardError => e
-                # Log the error but continue with other handlers
-                Axn::Util.piping_error("executing on_success hook", action: self, exception: e)
-              end
+              self.class._dispatch_callbacks(:success, action: self, exception: nil)
             end
           end
         end
@@ -44,17 +34,13 @@ module Action
             yield
           rescue StandardError => e
             # on_error handlers run for both unhandled exceptions and fail!
-            self.class._error_handlers.each do |handler|
-              handler.execute_if_matches(exception: e, action: self)
-            end
+            self.class._dispatch_callbacks(:error, action: self, exception: e)
 
             # on_failure handlers run ONLY for fail!
             if e.is_a?(Action::Failure)
-              self.class._failure_handlers.each do |handler|
-                handler.execute_if_matches(exception: e, action: self)
-              end
+              self.class._dispatch_callbacks(:failure, action: self, exception: e)
             else
-              # on_exception handlers run for ONLY for unhandled exceptions. AND NOTE: may be skipped if the exception is rescued via `rescues`.
+              # on_exception handlers run for ONLY for unhandled exceptions.
               _trigger_on_exception(e)
 
               @__context.exception = e

data/lib/action/core/flow/handlers/base_handler.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/matcher"
+
+module Action
+  module Core
+    module Flow
+      # "Handlers" doesn't feel like *quite* the right name for this, but basically things in this namespace
+      # relate to conditionally-invoked code blocks (e.g. callbacks, messages, etc.)
+      module Handlers
+        class BaseHandler
+          def initialize(matcher: nil, handler: nil)
+            @matcher = matcher
+            @handler = handler
+          end
+
+          attr_reader :handler
+
+          def static? = @matcher.nil?
+
+          def matches?(action:, exception:)
+            return true if static?
+
+            @matcher.call(exception:, action:)
+          end
+
+          # Subclasses should implement `apply(action:, exception:)`
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers/callback_handler.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/base_handler"
+require "action/core/flow/handlers/invoker"
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        class CallbackHandler < BaseHandler
+          def apply(action:, exception:)
+            return false unless matches?(action:, exception:)
+
+            Invoker.call(action:, handler:, exception:, operation: "executing handler")
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers/invoker.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        # Shared block evaluation with consistent arity handling and error piping
+        module Invoker
+          extend self
+
+          def call(action:, handler:, exception: nil, operation: "executing handler")
+            return call_symbol_handler(action:, symbol: handler, exception:) if symbol?(handler)
+            return call_callable_handler(action:, callable: handler, exception:) if callable?(handler)
+
+            literal_value(handler)
+          rescue StandardError => e
+            Axn::Util.piping_error(operation, action:, exception: e)
+          end
+
+          # Shared introspection helpers
+          def accepts_exception_keyword?(callable_or_method)
+            return false unless callable_or_method.respond_to?(:parameters)
+
+            params = callable_or_method.parameters
+            params.any? { |type, name| %i[keyreq key].include?(type) && name == :exception } ||
+              params.any? { |type, _| type == :keyrest }
+          end
+
+          def accepts_positional_exception?(callable_or_method)
+            return false unless callable_or_method.respond_to?(:arity)
+
+            arity = callable_or_method.arity
+            arity == 1 || arity.negative?
+          end
+
+          private
+
+          def symbol?(value) = value.is_a?(Symbol)
+
+          def callable?(value) = value.respond_to?(:arity)
+
+          def call_symbol_handler(action:, symbol:, exception: nil)
+            unless action.respond_to?(symbol)
+              action.warn("Ignoring apparently-invalid symbol #{symbol.inspect} -- action does not respond to method")
+              return nil
+            end
+
+            method = action.method(symbol)
+            if exception && accepts_exception_keyword?(method)
+              action.public_send(symbol, exception:)
+            elsif exception && accepts_positional_exception?(method)
+              action.public_send(symbol, exception)
+            else
+              action.public_send(symbol)
+            end
+          end
+
+          def call_callable_handler(action:, callable:, exception: nil)
+            if exception && accepts_exception_keyword?(callable)
+              action.instance_exec(exception:, &callable)
+            elsif exception && accepts_positional_exception?(callable)
+              action.instance_exec(exception, &callable)
+            else
+              action.instance_exec(&callable)
+            end
+          end
+
+          def literal_value(value) = value
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers/matcher.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/invoker"
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        class Matcher
+          def initialize(rule, invert: false)
+            @rule = rule
+            @invert = invert
+          end
+
+          def call(exception:, action:)
+            @invert ? !matches?(exception:, action:) : matches?(exception:, action:)
+          rescue StandardError => e
+            Axn::Util.piping_error("determining if handler applies to exception", action:, exception: e)
+          end
+
+          private
+
+          def matches?(exception:, action:)
+            return apply_callable(action:, exception:) if callable?
+            return apply_symbol(action:, exception:) if symbol?
+            return apply_string(exception:) if string?
+            return apply_exception_class(exception:) if exception_class?
+
+            handle_invalid(action:)
+          end
+
+          def callable? = @rule.respond_to?(:call)
+          def symbol? = @rule.is_a?(Symbol)
+          def string? = @rule.is_a?(String)
+          def exception_class? = @rule.is_a?(Class) && @rule <= Exception
+
+          def apply_callable(action:, exception:)
+            if exception && Invoker.accepts_exception_keyword?(@rule)
+              !!action.instance_exec(exception:, &@rule)
+            elsif exception && Invoker.accepts_positional_exception?(@rule)
+              !!action.instance_exec(exception, &@rule)
+            else
+              !!action.instance_exec(&@rule)
+            end
+          end
+
+          def apply_symbol(action:, exception:)
+            if action.respond_to?(@rule)
+              method = action.method(@rule)
+              if exception && Invoker.accepts_exception_keyword?(method)
+                !!action.public_send(@rule, exception:)
+              elsif exception && Invoker.accepts_positional_exception?(method)
+                !!action.public_send(@rule, exception)
+              else
+                !!action.public_send(@rule)
+              end
+            else
+              begin
+                klass = Object.const_get(@rule.to_s)
+                klass && exception.is_a?(klass)
+              rescue NameError
+                action.warn("Ignoring apparently-invalid matcher #{@rule.inspect} -- neither action method nor constant found")
+                false
+              end
+            end
+          end
+
+          def apply_string(exception:)
+            klass = Object.const_get(@rule.to_s)
+            klass && exception.is_a?(klass)
+          end
+
+          def apply_exception_class(exception:)
+            exception.is_a?(@rule)
+          end
+
+          def handle_invalid(action:)
+            action.warn("Ignoring apparently-invalid matcher #{@rule.inspect} -- could not find way to apply it")
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers/message_handler.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/base_handler"
+require "action/core/flow/handlers/invoker"
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        class MessageHandler < BaseHandler
+          # Returns a string (truthy) when it applies and yields a non-blank message; otherwise nil
+          def apply(action:, exception:)
+            return nil unless matches?(action:, exception:)
+
+            value =
+              if handler.is_a?(Symbol) || handler.respond_to?(:call)
+                Invoker.call(action:, handler:, exception:, operation: "determining message callable")
+              else
+                handler
+              end
+            value.respond_to?(:presence) ? value.presence : value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers/registry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        # Small, immutable, copy-on-write registry keyed by event_type.
+        # Stores arrays of entries (handlers/interceptors) in insertion order.
+        class Registry
+          def self.empty = new({})
+
+          def initialize(index)
+            # Freeze arrays and the index for immutability
+            @index = index.transform_values { |arr| Array(arr).freeze }.freeze
+          end
+
+          # Always register most-recent-first (last-defined wins). Simpler mental model.
+          def register(event_type:, entry:)
+            key = event_type.to_sym
+            existing = Array(@index[key])
+            updated = [entry] + existing
+            self.class.new(@index.merge(key => updated.freeze))
+          end
+
+          def for(event_type)
+            Array(@index[event_type.to_sym])
+          end
+
+          def empty?
+            @index.empty?
+          end
+
+          protected
+
+          attr_reader :index
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+      end
+    end
+  end
+end
+
+require "action/core/flow/handlers/invoker"
+require "action/core/flow/handlers/registry"
+require "action/core/flow/handlers/matcher"
+require "action/core/flow/handlers/base_handler"
+require "action/core/flow/handlers/callback_handler"
+require "action/core/flow/handlers/message_handler"

data/lib/action/core/flow/messages.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
+require "action/core/flow/handlers"
+
 module Action
   module Core
     module Flow
       module Messages
         def self.included(base)
           base.class_eval do
-            class_attribute :_success_msg, :_error_msg
-            class_attribute :_custom_error_interceptors, default: []
+            class_attribute :_messages_registry, default: Action::Core::Flow::Handlers::Registry.empty
 
             extend ClassMethods
             include InstanceMethods
@@ -15,45 +16,58 @@ module Action
         end
 
         module ClassMethods
-          def messages(success: nil, error: nil)
-            self._success_msg = success if success.present?
-            self._error_msg = error if error.present?
-
-            true
+          # Internal: resolve a message for the given event (conditional first, then static)
+          def _message_for(event_type, action:, exception: nil)
+            _conditional_message_for(event_type, action:, exception:) ||
+              _static_message_for(event_type, action:, exception:)
           end
 
-          def error_from(matcher = nil, message = nil, **match_and_messages)
-            _register_error_interceptor(matcher, message, should_report_error: true, **match_and_messages)
+          def _conditional_message_for(event_type, action:, exception: nil)
+            _messages_registry.for(event_type).each do |handler|
+              next if handler.respond_to?(:static?) && handler.static?
+
+              msg = handler.apply(action:, exception:)
+              return msg if msg.present?
+            end
+            nil
           end
 
-          def rescues(matcher = nil, message = nil, **match_and_messages)
-            _register_error_interceptor(matcher, message, should_report_error: false, **match_and_messages)
+          def _static_message_for(event_type, action:, exception: nil)
+            _messages_registry.for(event_type).each do |handler|
+              next unless handler.respond_to?(:static?) && handler.static?
+
+              msg = handler.apply(action:, exception:)
+              return msg if msg.present?
+            end
+            nil
           end
 
+          def success(message = nil, **, &) = _add_message(:success, message:, **, &)
+          def error(message = nil, **, &) = _add_message(:error, message:, **, &)
+
           def default_error = new.internal_context.default_error
+          def default_success = new.internal_context.default_success
 
-          # Private helpers
+          private
 
-          def _error_interceptor_for(exception:, action:)
-            Array(_custom_error_interceptors).detect do |int|
-              int.matches?(exception:, action:)
-            end
-          end
+          def _add_message(kind, message:, **kwargs, &block)
+            raise ArgumentError, "#{kind} cannot be called with both :if and :unless" if kwargs.key?(:if) && kwargs.key?(:unless)
 
-          def _register_error_interceptor(matcher, message, should_report_error:, **match_and_messages)
-            method_name = should_report_error ? "error_from" : "rescues"
-            raise ArgumentError, "#{method_name} must be called with a key/value pair, or else keyword args" if [matcher, message].compact.size == 1
+            condition = kwargs.key?(:if) ? kwargs[:if] : kwargs[:unless]
+            raise ArgumentError, "Provide either a message or a block, not both" if message && block_given?
+            raise ArgumentError, "Provide a message or a block" unless message || block_given?
 
-            interceptors = { matcher => message }.compact.merge(match_and_messages).map do |(matcher, message)| # rubocop:disable Lint/ShadowingOuterLocalVariable
-              Action::EventHandlers::CustomErrorInterceptor.new(matcher:, message:, should_report_error:)
-            end
+            handler = block_given? ? block : message
 
-            self._custom_error_interceptors += interceptors
+            matcher = condition.nil? ? nil : Action::Core::Flow::Handlers::Matcher.new(condition, invert: kwargs.key?(:unless))
+            entry = Action::Core::Flow::Handlers::MessageHandler.new(matcher:, handler:)
+            self._messages_registry = _messages_registry.register(event_type: kind, entry:)
+            true
           end
         end
 
         module InstanceMethods
-          delegate :default_error, to: :internal_context
+          delegate :default_error, :default_success, to: :internal_context
         end
       end
     end

data/lib/action/result.rb

@@ -11,7 +11,7 @@ module Action
       def ok(msg = nil, **exposures)
         exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
 
-        Axn::Factory.build(exposes:, messages: { success: msg }) do
+        Axn::Factory.build(exposes:, success: msg) do
           exposures.each do |key, value|
             expose(key, value)
           end
@@ -20,13 +20,19 @@ module Action
 
       def error(msg = nil, **exposures, &block)
         exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
-        rescues = [-> { true }, msg]
 
-        Axn::Factory.build(exposes:, rescues:) do
+        Axn::Factory.build(exposes:, error: msg) do
           exposures.each do |key, value|
             expose(key, value)
           end
-          block.call if block_given?
+          if block_given?
+            begin
+              block.call
+            rescue StandardError => e
+              # Set the exception directly without triggering on_exception handlers
+              @__context.exception = e
+            end
+          end
           fail!
         end.call
       end
@@ -47,7 +53,7 @@ module Action
     def success
       return unless ok?
 
-      stringified(action._success_msg).presence || "Action completed successfully"
+      determine_success_message
     end
 
     def ok = success
@@ -77,6 +83,19 @@ module Action
 
     def context_data_source = @context.exposed_data
 
+    def determine_error_message
+      return @context.error_from_user if @context.error_from_user.present?
+
+      exception = @context.exception || Action::Failure.new
+      msg = action.class._message_for(:error, action:, exception:)
+      msg.presence || "Something went wrong"
+    end
+
+    def determine_success_message
+      msg = action.class._message_for(:success, action:, exception: nil)
+      msg.presence || "Action completed successfully"
+    end
+
     def method_missing(method_name, ...) # rubocop:disable Style/MissingRespondToMissing (because we're not actually responding to anything additional)
       if @context.__combined_data.key?(method_name.to_sym)
         msg = <<~MSG

data/lib/axn/factory.rb

@@ -13,9 +13,8 @@ module Axn
         # Expose standard class-level options
         exposes: [],
         expects: [],
-        messages: {},
-        error_from: {},
-        rescues: {},
+        success: nil,
+        error: nil,
 
         # Hooks
         before: nil,
@@ -73,6 +72,17 @@ module Axn
             expose(expose_return_as => retval) if expose_return_as.present?
           end
         end.tap do |axn|
+          apply_message = lambda do |kind, value|
+            return unless value.present?
+
+            if value.is_a?(Array) && value.size == 2
+              matcher, msg = value
+              axn.public_send(kind, msg, if: matcher)
+            else
+              axn.public_send(kind, value)
+            end
+          end
+
           expects.each do |field, opts|
             axn.expects(field, **opts)
           end
@@ -81,10 +91,8 @@ module Axn
             axn.exposes(field, **opts)
           end
 
-          axn.messages(**messages) if messages.present? && messages.values.any?(&:present?)
-
-          axn.error_from(**_array_to_hash(error_from)) if error_from.present?
-          axn.rescues(**_array_to_hash(rescues)) if rescues.present?
+          apply_message.call(:success, success)
+          apply_message.call(:error, error)
 
           # Hooks
           axn.before(before) if before.present?

data/lib/axn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Axn
-  VERSION = "0.1.0-alpha.2.6.1"
+  VERSION = "0.1.0-alpha.2.7.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.2.6.1
+  version: 0.1.0.pre.alpha.2.7.1
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-12 00:00:00.000000000 Z
+date: 2025-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -86,10 +86,16 @@ files:
 - lib/action/core/contract.rb
 - lib/action/core/contract_for_subfields.rb
 - lib/action/core/contract_validation.rb
-- lib/action/core/event_handlers.rb
 - lib/action/core/flow.rb
 - lib/action/core/flow/callbacks.rb
 - lib/action/core/flow/exception_execution.rb
+- lib/action/core/flow/handlers.rb
+- lib/action/core/flow/handlers/base_handler.rb
+- lib/action/core/flow/handlers/callback_handler.rb
+- lib/action/core/flow/handlers/invoker.rb
+- lib/action/core/flow/handlers/matcher.rb
+- lib/action/core/flow/handlers/message_handler.rb
+- lib/action/core/flow/handlers/registry.rb
 - lib/action/core/flow/messages.rb
 - lib/action/core/hoist_errors.rb
 - lib/action/core/hooks.rb

data/lib/action/core/event_handlers.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-module Action
-  module EventHandlers
-    class CustomErrorInterceptor
-      def initialize(matcher:, message:, should_report_error:)
-        @matcher = Matcher.new(matcher)
-        @message = message
-        @should_report_error = should_report_error
-      end
-
-      delegate :matches?, to: :@matcher
-      attr_reader :message, :should_report_error
-    end
-
-    class ConditionalHandler
-      def initialize(matcher:, handler:)
-        @matcher = Matcher.new(matcher)
-        @handler = handler
-      end
-
-      delegate :matches?, to: :@matcher
-
-      def execute_if_matches(action:, exception:)
-        return false unless matches?(exception:, action:)
-
-        action.instance_exec(exception, &@handler)
-        true
-      rescue StandardError => e
-        Axn::Util.piping_error("executing handler", action:, exception: e)
-      end
-    end
-
-    class Matcher
-      def initialize(matcher)
-        @matcher = matcher
-      end
-
-      def matches?(exception:, action:)
-        if matcher.respond_to?(:call)
-          if matcher.arity == 1
-            !!action.instance_exec(exception, &matcher)
-          else
-            !!action.instance_exec(&matcher)
-          end
-        elsif matcher.is_a?(String) || matcher.is_a?(Symbol)
-          klass = Object.const_get(matcher.to_s)
-          klass && exception.is_a?(klass)
-        elsif matcher < Exception
-          exception.is_a?(matcher)
-        else
-          action.warn("Ignoring apparently-invalid matcher #{matcher.inspect} -- could not find way to apply it")
-          false
-        end
-      rescue StandardError => e
-        Axn::Util.piping_error("determining if handler applies to exception", action:, exception: e)
-      end
-
-      private attr_reader :matcher
-    end
-  end
-end