axn 0.1.0.pre.alpha.4.1 → 0.1.0.pre.alpha.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb94e06f97e37bada60d52f5fbb6c3b733d9e8aacf3ec8104ec04b92b8a29f3b
-  data.tar.gz: 9af75de4a098a59d9f3b30bc0eb0bf50b42a4f580b52476883aa8495402ca072
+  metadata.gz: bbed8a136915346d270fb287bd513684ddfd9b70692fa8a06384924a34198d6b
+  data.tar.gz: a9f8bb70324642e6da0ecba6522eaa8587f53259ad3488ddc72ed20927a73ad3
 SHA512:
-  metadata.gz: 3ee1ed0a4f58cdde4755b65f46fcc409764a0423fcf552df9b426f882886190359fe6db3c59b63572e78b45ef305f0f810f813938a41d37da08a2df0f7a7bec4
-  data.tar.gz: 00dc6904eb6b72a4fa29b36a0adfa3531f731637bbe9425c1d17cde013d23fa6a867b79dd88bf289bd428853854bf54c9470a3971f7a22ee22f4dde600bb2453
+  metadata.gz: 260b77024b257ad90ac69ae67deb6468a6c30d4bd47d877eefb709879e8e1a16a6f0cf519607951f3de3d9fe2663bb84cab37a58383846f495ddc17eed053614
+  data.tar.gz: 583c4c638a5bdc2c9d5686551e305972756d7737450c3ec8a02f3a5b236582a59e41e2290532ed8d69b9fc4c145364db0ac8f0a4a8cbda83736bf10cd7a5093f

data/CHANGELOG.md

@@ -3,6 +3,25 @@
 ## Unreleased
 * N/A
 
+## 0.1.0-alpha.4.2
+* [FEAT] Add extensible field metadata support for `expects`/`exposes`:
+  * **New** `Axn.extension_config` registry for library-facing configuration (separate from app-facing `Axn.config`)
+  * **New** `description:` metadata option for field declarations (e.g., `expects :name, description: "The user's name"`)
+  * **New** `FieldConfig#metadata` and `SubfieldConfig#metadata` attributes with `#description` accessor
+  * **New** `Axn.extension_config.register_field_metadata_key(:key)` for wrapper gems to register custom metadata keys
+  * **New** Unknown validation keys now raise `ArgumentError` (catches typos like `nummericality:`)
+  * **New** Metadata can only be provided when declaring a single field (multi-field + metadata raises `ArgumentError`)
+* [FEAT] Add `readers:` option validation: `readers: false` now raises `ArgumentError` when used without `on:` (only valid for subfields)
+* [BUGFIX] `set_default_async(:sidekiq)` now properly triggers `AutoConfigure.register!`
+* [BREAKING] Refactored context API for exception reporting and handlers:
+  * **Removed** `context_for_logging(direction)` instance method
+  * **Added** public `execution_context` method returning structured hash: `{ inputs: {...}, outputs: {...}, **extra_keys }`
+  * **Added** private `inputs_for_logging` / `outputs_for_logging` methods for automatic pre/post logging (do NOT include extra context)
+  * **Renamed** `set_logging_context` → `set_execution_context`, `clear_logging_context` → `clear_execution_context`, hook `additional_logging_context` → `additional_execution_context`
+  * **Reserved keys:** `:inputs` and `:outputs` cannot be set via `set_execution_context` or the hook—they always come from the action's contract
+  * **Internal:** Class method `context_for_logging(data:, direction:)` renamed to `_context_slice(data:, direction:)`
+  * Exception context now includes both `inputs` and `outputs` with additional context merged at the top level (not nested inside `inputs`)
+
 ## 0.1.0-alpha.4.1
 * [BREAKING][BUGFIX] `fail!` in async jobs no longer triggers retries - business logic failures complete without retry (Sidekiq and ActiveJob adapters)
 * [FEAT] Add `async_exception_reporting` config to control when `on_exception` triggers in async context (`:every_attempt`, `:first_and_exhausted`, `:only_exhausted`)

data/Rakefile

@@ -139,8 +139,9 @@ namespace :benchmark do
   end
 end
 
-# Require verify to pass before release
-Rake::Task["release"].enhance([:verify])
+# Require verify to pass before release. This relies on the default gem release task
+# (from bundler/gem_tasks) depending on "build"; verify runs before build, so before push.
+Rake::Task["build"].enhance([:verify])
 
 # Automatically run benchmark:release after rake release
 Rake::Task["release"].enhance do

data/docs/.vitepress/config.mjs

@@ -58,7 +58,6 @@ export default defineConfig({
           { text: 'Validating User Input', link: '/recipes/validating-user-input' },
           { text: 'Testing Actions', link: '/recipes/testing' },
           { text: 'RuboCop Integration', link: '/recipes/rubocop-integration' },
-          { text: 'Formatting Context for Error Tracking', link: '/recipes/formatting-context-for-error-tracking' },
         ]
       },
       {

data/docs/advanced/rough.md

@@ -17,14 +17,26 @@ For information about logging configuration, see the [Configuration reference](/
 - **Log levels**: [log_level](/reference/configuration#log-level)
 - **Automatic logging**: [Automatic Logging](/reference/configuration#automatic-logging)
 
-### `context_for_logging`
+### `execution_context`
 
-The `context_for_logging` method returns a hash of the action's context, with:
-- Filtering to accessible attributes
-- Sensitive values removed (fields marked with `sensitive: true`)
+The `execution_context` method returns a structured hash for exception reporting and handlers:
+
+```ruby
+{
+  inputs: { ... },   # Filtered inbound fields (sensitive values removed)
+  outputs: { ... },  # Filtered outbound fields (sensitive values removed)
+  # ... any extra keys from set_execution_context or additional_execution_context hook
+}
+```
 
 This is automatically passed to the `on_exception` hook. See [Adding Additional Context to Exception Logging](/reference/configuration#adding-additional-context-to-exception-logging) for customizing the context.
 
+**Private methods for automatic logging:**
+- `inputs_for_logging` - Returns only filtered inbound fields (used by pre-execution logs)
+- `outputs_for_logging` - Returns only filtered outbound fields (used by post-execution logs)
+
+These private methods do NOT include additional context from `set_execution_context` or the hook—they are specifically for automatic logging which only needs to show what the action was called with and what it produced.
+
 ### `#inspect` Support
 
 Action instances provide a readable `#inspect` output that shows:

data/docs/reference/class.md

@@ -101,6 +101,16 @@ end
 Defaults work the same way for subfields as they do for top-level fields - they are applied when the subfield is missing or explicitly `nil`, but not for blank values.
 :::
 
+#### Disabling subfield readers
+
+By default, subfields create top-level reader methods (e.g., `random` in the example above). You can disable this with `readers: false`:
+
+```ruby
+expects :data, type: Hash, on: :event, readers: false
+```
+
+This is useful when you have duplicate sub-keys across different parent fields, or when you want to access subfields only through the parent. Note that `readers: false` is only valid for subfields (i.e., when using `on:`) — using it on top-level fields will raise an `ArgumentError`.
+
 #### `preprocess`
 `expects` also supports a `preprocess` option that, if set to a callable, will be executed _before_ applying any defaults or validations.  This can be useful for type coercion, e.g.:
 

data/docs/reference/configuration.md

@@ -5,12 +5,13 @@ Somewhere at boot (e.g. `config/initializers/actions.rb` in Rails), you can call
 ```ruby
 Axn.configure do |c|
   c.log_level = :info
-  c.logger = ...
+  c.logger = Rails.logger
+  
   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 })
+    Honeybadger.notify(
+      "[#{action.class.name}] #{e.class.name}: #{e.message}",
+      context: context
+    )
   end
 end
 ```
@@ -22,44 +23,82 @@ 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
-  Axn.configure do |c|
-    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
+Axn.configure do |c|
+  c.on_exception = proc do |e, action:, context:|
+    Honeybadger.notify(
+      "[#{action.class.name}] #{e.class.name}: #{e.message}",
+      context: context
+    )
   end
+end
 ```
 
 **Note:** The `action:` and `context:` keyword arguments are *optional*—your proc can accept any combination of `e`, `action:`, and `context:`. Only the keyword arguments you explicitly declare will be passed to your handler. All of the following are valid:
 
 ```ruby
-  # Only exception object
-  c.on_exception = proc { |e| ... }
+# Only exception object
+c.on_exception = proc { |e| ... }
 
-  # Exception and action
-  c.on_exception = proc { |e, action:| ... }
+# Exception and action
+c.on_exception = proc { |e, action:| ... }
 
-  # Exception and context
-  c.on_exception = proc { |e, context:| ... }
+# Exception and context
+c.on_exception = proc { |e, context:| ... }
 
-  # Exception, action, and context
-  c.on_exception = proc { |e, action:, context:| ... }
+# Exception, action, and context
+c.on_exception = proc { |e, action:, context:| ... }
 ```
 
-A couple notes:
+### Context Structure
+
+The `context` hash is automatically formatted and contains:
+
+```ruby
+{
+  inputs: { ... },              # Action inputs (declared expects fields only), formatted recursively
+  outputs: { ... },             # Action outputs (declared exposes fields only), formatted recursively
+  # ... any extra keys from set_execution_context or additional_execution_context hook
+  # e.g. client_strategy__last_request: { url: ..., method: ..., status: ... }
+  current_attributes: { ... },  # Current.attributes (auto-included if defined and present)
+  async: { ... }                # Async retry info (only present in async context)
+}
+```
 
-  * `context` will contain the arguments passed to the `action`, _but_ any marked as sensitive (e.g. `expects :foo, sensitive: true`) will be filtered out in the logs.
-  * 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).
-  * The `context` hash may contain complex objects (like ActiveRecord models, `ActionController::Parameters`, or `Axn::FormObject` instances) that aren't easily serialized by error tracking systems. See [Formatting Context for Error Tracking Systems](/recipes/formatting-context-for-error-tracking) for a recipe to convert these to readable formats.
+Additional context (like `client_strategy__last_request` from the `:client` strategy) appears at the top level alongside `inputs` and `outputs`, not nested inside them. Formatting is applied recursively to nested hashes and arrays.
+
+**What gets formatted automatically:**
+- **ActiveRecord objects** → GlobalID strings (e.g., `"gid://app/User/123"`)
+- **ActionController::Parameters** → Plain hashes
+- **Axn::FormObject instances** → Hash representation
+
+**Example with all context fields:**
+
+```ruby
+Axn.configure do |c|
+  c.on_exception = proc do |e, action:, context:|
+    # context[:inputs] - Your action's inputs (formatted)
+    # context[:outputs] - Your action's outputs (formatted)
+    # context[:client_strategy__last_request] - Example extra key from :client strategy
+    # context[:current_attributes] - Rails Current.attributes (if present)
+    # context[:async] - Retry info (if in async context)
+    
+    Honeybadger.notify(e, context: context)
+  end
+end
+```
+
+### Additional Notes
+
+- Sensitive fields (marked with `expects :foo, sensitive: true`) are automatically filtered to `"[FILTERED]"`
+- If your handler raises an exception, the failure will be swallowed and logged
+- This handler is global across _all_ actions. You can also specify per-action handlers via [the class-level declaration](/reference/class#on-exception)
+- Complex objects are automatically formatted for error tracking systems
 
 ### Adding Additional Context to Exception Logging
 
 When processing records in a loop or performing batch operations, you may want to include additional context (like which record is being processed) in exception logs. You can do this in two ways:
 
-**Option 1: Explicit setter** - Call `set_logging_context` during execution:
+**Option 1: Explicit setter** - Call `set_execution_context` during execution:
 
 ```ruby
 class ProcessPendingRecords
@@ -67,14 +106,14 @@ class ProcessPendingRecords
 
   def call
     pending_records.each do |record|
-      set_logging_context(current_record_id: record.id, batch_index: @index)
+      set_execution_context(current_record_id: record.id, batch_index: @index)
       # ... process record ...
     end
   end
 end
 ```
 
-**Option 2: Hook method** - Define a private `additional_logging_context` method that returns a hash:
+**Option 2: Hook method** - Define a private `additional_execution_context` method that returns a hash:
 
 ```ruby
 class ProcessPendingRecords
@@ -89,7 +128,7 @@ class ProcessPendingRecords
 
   private
 
-  def additional_logging_context
+  def additional_execution_context
     return {} unless @current_record
 
     {
@@ -100,16 +139,19 @@ class ProcessPendingRecords
 end
 ```
 
-Both approaches can be used together - they will be merged. The additional context is **only** included in exception logging (not in normal pre/post execution logs), and is evaluated lazily (the hook method is only called when an exception occurs).
+Both approaches can be used together - they will be merged at the top level of the context hash. The additional context is **only** included in `execution_context` (used for exception reporting and handlers), not in normal pre/post execution logs, and is evaluated lazily (the hook method is only called when needed).
+
+**Reserved keys:** The keys `:inputs` and `:outputs` are reserved. If you try to set them via `set_execution_context` or the hook, they will be ignored—the actual inputs and outputs always come from the action's contract.
 
-Action-specific `on_exception` handlers can also access this context by calling `context_for_logging` directly:
+Action-specific `on_exception` handlers can access the full context by calling `execution_context`:
 
 ```ruby
 class ProcessPendingRecords
   include Axn
 
   on_exception do |exception:|
-    log "Failed with this extra context: #{context_for_logging}"
+    ctx = execution_context
+    log "Failed processing. Inputs: #{ctx[:inputs]}, Extra: #{ctx[:current_record_id]}"
     # ... handle exception with context ...
   end
 end
@@ -342,22 +384,24 @@ When `on_exception` is triggered in an async context, the `context` hash include
 ```ruby
 Axn.configure do |c|
   c.on_exception = proc do |e, action:, context:|
+    # context[:async] is automatically included when in async context
+    # Available fields:
+    # context[:async][:adapter]           # :sidekiq or :active_job
+    # context[:async][:attempt]           # Current attempt (1-indexed)
+    # context[:async][:max_retries]       # Max retry attempts
+    # context[:async][:job_id]            # Job ID (if available)
+    # context[:async][:first_attempt]     # true if first attempt
+    # context[:async][:retries_exhausted] # true if all retries exhausted
+    
     if context[:async]
-      # Available fields:
-      # context[:async][:adapter]          # :sidekiq or :active_job
-      # context[:async][:attempt]          # Current attempt (1-indexed)
-      # context[:async][:max_retries]      # Max retry attempts
-      # context[:async][:job_id]           # Job ID (if available)
-      # context[:async][:first_attempt]    # true if first attempt
-      # context[:async][:retries_exhausted] # true if all retries exhausted
-
-      Honeybadger.notify(e, context: {
-        axn_context: context,
+      # Add custom retry info to context
+      enhanced_context = context.merge(
         retry_info: "Attempt #{context[:async][:attempt]} of #{context[:async][:max_retries]}"
-      })
+      )
+      Honeybadger.notify(e, context: enhanced_context)
     else
-      # Foreground execution - no retry context
-      Honeybadger.notify(e, context: { axn_context: context })
+      # Foreground execution - context still includes inputs and current_attributes
+      Honeybadger.notify(e, context: context)
     end
   end
 end
@@ -549,9 +593,10 @@ Axn.configure do |c|
 
   # 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 })
+    Honeybadger.notify(
+      "[#{action.class.name}] #{e.class.name}: #{e.message}",
+      context: context
+    )
   end
 
   # Observability

data/docs/strategies/form.md

@@ -62,7 +62,9 @@ end
 
 ### Inline Form Definition
 
-You can define the form class inline using a block:
+You can pass the form in directly as a block instead of a separate class.
+
+**Block only** — the form class is not assigned to a constant, but it is given a `name` (default: the action’s name + `Form`, e.g. `"CreateUser::Form"`) so it shows up clearly in logging and exception reporting:
 
 ```ruby
 class CreateUser
@@ -79,7 +81,14 @@ class CreateUser
 end
 ```
 
-This creates an anonymous form class that inherits from `Axn::FormObject`.
+**Block + type string** — the form class is named using the given string (e.g. `"CreateUser::Form"`). If that constant doesn't exist yet, the block defines the class and we assign it to that name:
+
+```ruby
+use :form, type: "CreateUser::Form" do
+  validates :email, presence: true
+  validates :name, presence: true
+end
+```
 
 ### Custom Field Names
 

data/docs/strategies/transaction.md

@@ -18,12 +18,13 @@ class TransferFunds
 end
 ```
 
-**Important**: The transaction wraps the entire action execution, including:
+**Important**: The transaction wraps:
 - `before` hooks
 - The main `call` method
 - `after` hooks
-- Success/failure callbacks (`on_success`, `on_failure`, etc.)
 
-This means that if any part of the action (including hooks or callbacks) raises an exception or calls `fail!`, the entire transaction will be rolled back.
+So the transaction is still open until all of the above complete. If any of them raise or call `fail!`, the transaction is rolled back.
+
+**`on_success` runs after the transaction commits.** It is invoked only after the transaction block has finished successfully. Use `on_success` (not `after` hooks) for work that should run outside the transaction—for example, calling an external HTTP service—so the DB transaction can commit and release the connection before that work runs. Putting slow or unreliable external calls inside `call` or `after` keeps the transaction open until they complete and can block the connection.
 
 **Requirements**: Requires ActiveRecord to be available in your application.

data/lib/axn/async/adapters/sidekiq/auto_configure.rb

@@ -42,6 +42,21 @@ module Axn
               false
             end
 
+            # Ensures middleware and death handler are registered for the current
+            # Axn.config.async_exception_reporting mode. Call when the Sidekiq adapter
+            # is included (e.g. via async :sidekiq or default async) so that default
+            # mode works without the app setting async_exception_reporting explicitly.
+            # Safe to call multiple times - register! is idempotent.
+            # No-ops when Sidekiq is a minimal stub (e.g. in unit tests without full Sidekiq).
+            def ensure_registered_for_current_config!
+              return unless defined?(::Sidekiq) && ::Sidekiq.respond_to?(:configure_server)
+
+              mode = Axn.config.async_exception_reporting
+              return if mode == :every_attempt
+
+              register!
+            end
+
             # Registers both middleware and death handler.
             # Safe to call multiple times - will not duplicate registrations.
             def register!

data/lib/axn/async/adapters/sidekiq.rb

@@ -18,6 +18,10 @@ module Axn
           # Use Sidekiq::Job if available (Sidekiq 7+), otherwise error
           raise LoadError, "Sidekiq::Job is not available. Please check your Sidekiq version." unless defined?(::Sidekiq::Job)
 
+          # Ensure middleware and death handler are registered for current async_exception_reporting
+          # (e.g. when async :sidekiq is used without ever setting async_exception_reporting).
+          AutoConfigure.ensure_registered_for_current_config!
+
           include ::Sidekiq::Job
 
           # Sidekiq's processor calls .new on the worker class from outside the class hierarchy
@@ -42,7 +46,7 @@ module Axn
             normalized_options = _extract_and_normalize_async_options(kwargs)
 
             # Convert kwargs to string keys and handle GlobalID conversion
-            job_kwargs = Axn::Util::GlobalIdSerialization.serialize(kwargs)
+            job_kwargs = Axn::Internal::GlobalIdSerialization.serialize(kwargs)
 
             # Process normalized async options if present
             if normalized_options
@@ -58,7 +62,7 @@ module Axn
         end
 
         def perform(*args)
-          context = Axn::Util::GlobalIdSerialization.deserialize(args.first)
+          context = Axn::Internal::GlobalIdSerialization.deserialize(args.first)
 
           # Validate Sidekiq configuration once on first job execution in a real server context.
           # Skip validation when:

data/lib/axn/async/enqueue_all_orchestrator.rb

@@ -28,18 +28,18 @@ module Axn
         target = target_class_name.constantize
 
         # Deserialize static_args (convert GlobalID strings back to objects)
-        deserialized_static_args = Axn::Util::GlobalIdSerialization.deserialize(static_args)
+        deserialized_static_args = Axn::Internal::GlobalIdSerialization.deserialize(static_args)
 
         count = self.class.execute_iteration(
           target,
           **deserialized_static_args,
-          on_progress: method(:set_logging_context),
+          on_progress: method(:set_execution_context),
         )
 
         message_parts = ["Batch enqueued #{count} jobs for #{target.name}"]
         message_parts << "with explicit args: #{static_args.inspect}" if static_args.any?
 
-        Axn::Util::Logging.log_at_level(
+        Axn::Internal::CallLogger.log_at_level(
           self.class,
           level: :info,
           message_parts:,
@@ -77,7 +77,7 @@ module Axn
             execute_iteration_without_logging(target, **static_args)
           else
             # Serialize static_args for Sidekiq (convert GlobalID objects, stringify keys)
-            serialized_static_args = Axn::Util::GlobalIdSerialization.serialize(resolved_static)
+            serialized_static_args = Axn::Internal::GlobalIdSerialization.serialize(resolved_static)
 
             # Execute iteration in background via EnqueueAllOrchestrator
             call_async(target_class_name: target.name, static_args: serialized_static_args)
@@ -280,7 +280,7 @@ module Axn
               filter_result = begin
                 config.filter_block.call(item)
               rescue StandardError => e
-                Axn::Internal::Logging.piping_error(
+                Axn::Internal::PipingError.swallow(
                   "filter block for :#{config.field}",
                   exception: e,
                 )
@@ -294,7 +294,7 @@ module Axn
                       begin
                         item.public_send(config.via)
                       rescue StandardError => e
-                        Axn::Internal::Logging.piping_error(
+                        Axn::Internal::PipingError.swallow(
                           "via extraction (:#{config.via}) for :#{config.field}",
                           exception: e,
                         )

data/lib/axn/async/exception_reporting.rb

@@ -16,8 +16,8 @@ module Axn
         # @param extra_context [Hash] additional context to merge (e.g., discarded: true, _job_metadata)
         # @param log_prefix [String] prefix for error logging (e.g., "Sidekiq death handler")
         def trigger_on_exception(exception:, action_class:, retry_context:, job_args:, extra_context: {}, log_prefix: "async")
-          # Filter sensitive values using the action class's context_for_logging
-          filtered_context = action_class.context_for_logging(data: job_args, direction: :inbound)
+          # Filter sensitive values using the action class's internal _context_slice
+          filtered_context = action_class._context_slice(data: job_args, direction: :inbound)
 
           # Build final context with async info (avoid mutating extra_context)
           async_extra = extra_context[:async] || {}
@@ -31,7 +31,7 @@ module Axn
           # Trigger on_exception
           Axn.config.on_exception(exception, action: proxy_action, context:)
         rescue StandardError => e
-          Axn::Internal::Logging.piping_error("in #{log_prefix}", exception: e)
+          Axn::Internal::PipingError.swallow("in #{log_prefix}", exception: e)
         end
       end
 

data/lib/axn/async.rb

@@ -104,11 +104,11 @@ module Axn
         ActiveSupport::Notifications.instrument("axn.call_async", payload)
       rescue StandardError => e
         # Don't raise in notification emission to avoid interfering with async enqueueing
-        Axn::Internal::Logging.piping_error("emitting notification for axn.call_async", action_class: self, exception: e)
+        Axn::Internal::PipingError.swallow("emitting notification for axn.call_async", action_class: self, exception: e)
       end
 
       def _log_async_invocation(kwargs, adapter_name:)
-        Axn::Util::Logging.log_at_level(
+        Axn::Internal::CallLogger.log_at_level(
           self,
           level: log_calls_level,
           message_parts: ["Enqueueing async execution via #{adapter_name}"],

data/lib/axn/configuration.rb

@@ -7,7 +7,7 @@ module Axn
 
   class Configuration
     attr_accessor :emit_metrics, :raise_piping_errors_in_dev
-    attr_writer :logger, :env, :on_exception, :additional_includes, :log_level, :rails
+    attr_writer :logger, :env, :on_exception, :additional_includes, :log_level, :rails, :_include_retry_command_in_exceptions
 
     # Controls when on_exception is triggered in async context (Sidekiq/ActiveJob).
     # Options:
@@ -40,6 +40,13 @@ module Axn
 
     def additional_includes = @additional_includes ||= []
 
+    # EXPERIMENTAL: When true, automatically generates a retry command in exception context.
+    # This is marked experimental because the retry command generation may not work well
+    # for all action types (e.g., actions with complex object dependencies).
+    def _include_retry_command_in_exceptions
+      @_include_retry_command_in_exceptions.nil? ? false : @_include_retry_command_in_exceptions
+    end
+
     def _default_async_adapter = @default_async_adapter ||= false
     def _default_async_config = @default_async_config ||= {}
     def _default_async_config_block = @default_async_config_block
@@ -51,6 +58,7 @@ module Axn
       @default_async_config = config.any? ? config : {}
       @default_async_config_block = block_given? ? block : nil
 
+      _ensure_async_exception_reporting_registered_for_adapter(adapter)
       _apply_async_to_enqueue_all_orchestrator
     end
 
@@ -65,6 +73,7 @@ module Axn
       @enqueue_all_async_config = config.any? ? config : {}
       @enqueue_all_async_config_block = block_given? ? block : nil
 
+      _ensure_async_exception_reporting_registered_for_adapter(adapter)
       _apply_async_to_enqueue_all_orchestrator
     end
 
@@ -87,7 +96,7 @@ module Axn
       return unless @on_exception
 
       # Only pass the args and kwargs that the given block expects
-      Axn::Util::Callable.call_with_desired_shape(@on_exception, args: [e], kwargs: { action:, context: })
+      Axn::Internal::Callable.call_with_desired_shape(@on_exception, args: [e], kwargs: { action:, context: })
     end
 
     def logger
@@ -128,6 +137,20 @@ module Axn
       )
     end
 
+    # Ensures the given async adapter has exception-reporting components registered
+    # for the current async_exception_reporting mode (e.g. Sidekiq middleware/death handler).
+    # Called when setting default or enqueue_all async adapter so the default mode works
+    # without the app having to set async_exception_reporting explicitly.
+    def _ensure_async_exception_reporting_registered_for_adapter(adapter)
+      return if adapter.nil? || adapter == false
+
+      case adapter
+      when :sidekiq
+        _auto_configure_sidekiq_for_async_exception_reporting(async_exception_reporting)
+      end
+      # Active Job has no global registration (per-class proxy with after_discard).
+    end
+
     # Auto-configures Sidekiq middleware and death handler when async_exception_reporting
     # is set to a mode that requires them.
     #