axn 0.1.0.pre.alpha.4.2 → 0.1.0.pre.alpha.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbed8a136915346d270fb287bd513684ddfd9b70692fa8a06384924a34198d6b
-  data.tar.gz: a9f8bb70324642e6da0ecba6522eaa8587f53259ad3488ddc72ed20927a73ad3
+  metadata.gz: a911da94d085860df8fc6aed9bbe869edae27c2ff0e5821b2c07a043644c4fb5
+  data.tar.gz: 0d56247c256cc52efc8258a1716b0c4274114411948b084fe872fc63285907c3
 SHA512:
-  metadata.gz: 260b77024b257ad90ac69ae67deb6468a6c30d4bd47d877eefb709879e8e1a16a6f0cf519607951f3de3d9fe2663bb84cab37a58383846f495ddc17eed053614
-  data.tar.gz: 583c4c638a5bdc2c9d5686551e305972756d7737450c3ec8a02f3a5b236582a59e41e2290532ed8d69b9fc4c145364db0ac8f0a4a8cbda83736bf10cd7a5093f
+  metadata.gz: d39402f76d8df64e831007e046f0d5c8ac7fcd009246bbee9e7296db789b3afa270f5e63987eb23c88821f3f0ee2fecf3e7ec576b5dc9ce0f9e0972ba1811f93
+  data.tar.gz: 2347b225abbab7c3e705ca071b661e104c18c4d6333d5eb8563eadf26559035485f79682f4e4a23f3c6e3dabf30209475570fd07ab511a9b75f9d5537d320f41

data/CHANGELOG.md

@@ -1,7 +1,18 @@
 # Changelog
 
-## Unreleased
-* N/A
+## 0.1.0-alpha.4.3
+* [FEAT] Plain namespace **modules** can now host mounted actions: `include Axn::Mountable` on a module (not just a class) exposes `mount_axn` / `mount_axn_method` / `step`. Class hosts keep the existing `class_attribute` + `inherited` behavior; module hosts use singleton accessors and skip the `inherited` hook (modules have no subclasses). Also fixes a `.name` clobber so passing an already-named class to `mount_axn` preserves its original name instead of rewriting it to the `Axns` namespace path.
+* [BUGFIX] Fixed an off-by-one in `async.attempt` reported from the Sidekiq death handler: Sidekiq increments `retry_count` before invoking death handlers, so an exhausted `retry: 3` job (4 executions) reported attempt `5` instead of `4`. The bug was metadata-only — control flow (`retries_exhausted?`, `first_attempt?`, `should_trigger_on_exception?`) was unaffected. Also documents why framework-native integrations (e.g. Honeybadger's Sidekiq plugin) can produce duplicate async error reports, with a tag-and-filter suppression recipe.
+* [BUGFIX] Subfield names that collide with a method on the parent value (e.g. `zip`, `count`, `first` — any `Hash`/`Enumerable` method) are now read as keys instead of being dispatched as method calls. Previously `expects :zip, on: :address` extracted `address.zip` (`Enumerable#zip`) and failed with a bogus error; `FieldResolvers::Extract` now digs the key first for Hash-like sources and only falls back to a reader method for non-diggable objects (e.g. `Data` instances).
+* [FEAT] `expects … on:` now accepts a **dotted path** to reach a deeply-nested parent (e.g. `expects :zip, on: "address.billing", type: String` validates `address[:billing][:zip]` and defines a flat `zip` reader). The root segment must be a declared field/subfield. `default:`/`preprocess:`/`sensitive:` combined with a dotted `on:` raise `ArgumentError` (writing into — and redacting — an arbitrary nested path isn't supported yet); single-key `on:` is unchanged.
+* [FEAT] Add block syntax for declaring the per-member shape of a structured field on `expects`/`exposes`. On a `type: Array`, `type: Hash`, or class-typed field, a block declares member contracts: `expects :items, type: Array do field :status, type: String, inclusion: { in: %w[a b] } end`. Members accept the same options as top-level fields (`type`, `inclusion`, `optional`, `description`, …) and recurse via nested blocks. For arrays each element is validated with indexed errors (`element at index 2: status …`); for a single Hash/object value its members are validated directly. The block requires a single structured `type:` (raises `ArgumentError` on scalars, unions, or no type), composes with `of:` (which still checks element class), and — unlike `on:` subfields — defines **no** reader methods. Downstream tooling reads members from `config.validations[:shape][:members]`.
+* [FEAT] Add `of:` array-element validation for `expects`/`exposes`. On a `type: Array` field, `of:` validates each element: a single class (`of: String`), a union (`of: [String, Numeric]` — an element passes if it matches *any*), the `:boolean`/`:uuid`/`:params` symbols, or a `Data.define` class. Only valid alongside `type: Array` (raises `ArgumentError` otherwise, including for unions like `type: [Array, String]`). Error messages report the failing element's index (e.g. `element at index 2 is not a String`) and honor a custom `message:`. `optional`/`allow_blank`/`allow_nil` govern whether the whole field may be absent — they do not make individual elements blank-able. Downstream tooling can read the element type from `config.validations[:of][:klass]`.
+* [FEAT] `exposes`-declared fields that are also `expects`-declared are now auto-copied from the input into the result on **all** outcome paths — success, `done!`, `fail!`, and unhandled exception. Previously, the auto-copy only ran on success/`done!` paths, leaving `result.field` as `nil` after `fail!` or an exception even when the field was provided as input. This is particularly useful for re-exposing mutated ActiveRecord objects (e.g. inspecting `user.errors` after a failed save). Explicit `expose` calls before a failure continue to work and take precedence.
+* [FEAT] Execution log messages now display elapsed time in human-readable units (milliseconds, seconds, minutes, or hours) instead of always showing milliseconds
+* [BREAKING] `exposes` no longer defines a direct reader method on the action instance. Exposed fields must be accessed via `result.field` (e.g., `result.greeting`). `expects` readers are unaffected. User-defined methods with the same name as an exposed field are preserved (DefaultCall still calls them). Use `result.field` in `success`/`error` message callables and `sensitive:` procs to access output values.
+* [FEAT] Add boolean predicate readers for `expects` and `exposes`: `expects :enabled, type: :boolean` defines `enabled?` on the action instance; `exposes :enabled, type: :boolean` defines `result.enabled?`.
+* [BUGFIX] `ExceptionContext.build` no longer raises `URI::GID::MissingModelIdError` when an exposed or expected value is an unpersisted ActiveRecord record. The formatter now renders such values as `#<ClassName (unpersisted)>` and the optional retry command falls back to `inspect` instead of generating `Model.find(nil)`.
+* [FEAT] Add dynamic `sensitive:` option support for `expects` and `exposes` fields - accepts procs or symbols that are evaluated at runtime against the action instance, allowing conditional sensitivity based on input values (e.g., `exposes :data, sensitive: -> { redact_mode }`)
 
 ## 0.1.0-alpha.4.2
 * [FEAT] Add extensible field metadata support for `expects`/`exposes`:

data/Rakefile

@@ -151,3 +151,71 @@ Rake::Task["release"].enhance do
   Rake::Task["benchmark:release"].reenable
   Rake::Task["benchmark:release"].invoke
 end
+
+# Downstream gem compatibility check
+DOWNSTREAM_GEMS = {
+  "slack_sender" => File.expand_path("../slack_sender/slack_sender.gemspec", __dir__),
+  "data_shifter" => File.expand_path("../data_shifter/data_shifter.gemspec", __dir__),
+  "axn-mcp" => File.expand_path("../axn-mcp/axn-mcp.gemspec", __dir__),
+  "axn-ruby_llm" => File.expand_path("../axn-ruby_llm/axn-ruby_llm.gemspec", __dir__),
+}.freeze
+
+PARSE_AXN_REQUIREMENT = lambda { |gemspec_path|
+  content = File.read(gemspec_path)
+  match = content.match(/add_dependency\s+["']axn["']\s*,\s*(.+)$/)
+  return nil unless match
+
+  constraints = match[1].scan(/["']([^"']+)["']/).flatten
+  Gem::Requirement.new(constraints)
+}
+
+namespace :downstream do
+  desc "Check whether downstream gems support the current axn version"
+  task :check do
+    require "rubygems"
+    require_relative "lib/axn/version"
+
+    current_version = Gem::Version.new(Axn::VERSION)
+    warnings = []
+
+    puts "Downstream gem compatibility with axn #{current_version}:"
+    puts ""
+
+    DOWNSTREAM_GEMS.each do |name, gemspec_path|
+      unless File.exist?(gemspec_path)
+        puts "  #{name}: gemspec not found at #{gemspec_path}"
+        next
+      end
+
+      requirement = PARSE_AXN_REQUIREMENT.call(gemspec_path)
+
+      unless requirement
+        puts "  #{name}: no axn dependency found in gemspec"
+        next
+      end
+
+      if requirement.satisfied_by?(current_version)
+        puts "  #{name}: OK  (#{requirement})"
+      else
+        puts "  #{name}: NEEDS UPDATE  (#{requirement} excludes #{current_version})"
+        warnings << "  - #{name}: update axn constraint (currently #{requirement}) to include #{current_version}"
+      end
+    end
+
+    puts ""
+
+    if warnings.any?
+      puts "WARNING: These downstream gems need axn version constraint updates before"
+      puts "         they can use axn #{current_version}:"
+      warnings.each { |w| puts w }
+    else
+      puts "All downstream gems support axn #{current_version}."
+    end
+  end
+end
+
+# Warn (but don't block) about downstream gems that need updating before release
+Rake::Task["release"].enhance do
+  Rake::Task["downstream:check"].reenable
+  Rake::Task["downstream:check"].invoke
+end

data/docs/.vitepress/config.mjs

@@ -58,6 +58,7 @@ 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: 'Suppressing Duplicate Async Reports', link: '/recipes/suppressing-duplicate-async-reports' },
         ]
       },
       {

data/docs/advanced/mountable.md

@@ -17,6 +17,39 @@ When you attach an action to a class, you get multiple ways to access it:
 1. **Direct method calls** on the class (e.g., `SomeClass.foo`), which depend on how you told it to mount
 3. **Namespace method calls** (e.g., `SomeClass::Axns.foo`) which always call the underlying axn directly (i.e. returning Axn::Result like a normal SomeAxn.call)
 
+## Host Types
+
+### Classes (`include Axn`)
+
+The typical host is a class that also `include Axn`. It gets the full mounting DSL, inheritable descriptors (subclasses receive mounts from their parent), and the `::Axns` namespace:
+
+```ruby
+class UserService
+  include Axn
+
+  mount_axn(:create_user) { |email:| User.create!(email:) }
+end
+```
+
+### Plain namespace modules (`include Axn::Mountable`)
+
+If your host is a namespace module — not itself an action — include `Axn::Mountable` directly instead:
+
+```ruby
+module MyGem
+  include Axn::Mountable
+
+  mount_axn :process, MyGem::ProcessAction
+end
+
+MyGem.process(...)     # => Axn::Result
+MyGem.process!(...)    # raises on failure
+MyGem.process_async(...)
+MyGem::Axns.process(...)
+```
+
+Mounting an existing named class on any host preserves the class's original `.name` — it will not be overwritten with the `::Axns::` namespace path.
+
 ## Attachment Strategies
 
 ### `axn` Strategy
@@ -28,15 +61,14 @@ class UserService
   include Axn
 
   mount_axn(:create_user) do |email:, name:|
-    user = User.create!(email: email, name: name)
-    expose :user_id, user.id
+    User.create!(email: email, name: name)
   end
 end
 
 # Usage
 result = UserService.create_user(email: "user@example.com", name: "John")
 if result.ok?
-  puts "User created with ID: #{result.user_id}"
+  puts "User created: #{result.value.inspect}"
 else
   puts "Error: #{result.error}"
 end
@@ -130,8 +162,8 @@ class DataProcessor
   async :sidekiq
 
   mount_axn(:process_data, async: :sidekiq) do |data:|
-    # Processing logic
-    expose :processed_count, data.count
+    # Processing logic; return value is auto-exposed as result.value
+    data.count
   end
 end
 
@@ -185,13 +217,12 @@ class UserService
   # Inherits lifecycle (hooks, callbacks, messages, async) but not fields
   mount_axn :create_user do
     # Will run log_start before and track_success after
-    expose :user_id, 123
+    User.create!(email: "example@example.com")
   end
 
   # Completely independent - no inheritance
   step :validate_user do
     # Will NOT run log_start or track_success
-    expose :valid, true
   end
 end
 ```
@@ -427,8 +458,7 @@ class UserService
   include Axn
 
   mount_axn(:create) do |email:, name:|
-    user = User.create!(email: email, name: name)
-    expose :user_id, user.id
+    User.create!(email: email, name: name)
   end
 
   mount_axn_method(:find_by_email) do |email:|

data/docs/recipes/suppressing-duplicate-async-reports.md

@@ -0,0 +1,65 @@
+# Suppressing Duplicate Async Error Reports
+
+When an Axn async job fails, your error monitoring integration may report the exception **twice**: once via Axn's `on_exception` path, and once natively from the background job framework's own error integration.
+
+For example, with Honeybadger + Sidekiq: Honeybadger's Sidekiq plugin independently catches the re-raised exception on every execution, producing a separate raw fault in Honeybadger regardless of your `async_exception_reporting` setting. If you've configured `:first_and_exhausted`, you'll still see a raw Sidekiq `RuntimeError` fault with one notice per retry — which makes the reporting look broken.
+
+## General Approach
+
+The fix belongs in your error reporter, not in Axn. Suppress framework-native reports for Axn actions (since Axn is already handling reporting via `on_exception`) while leaving non-Axn jobs unaffected.
+
+The two signals you need:
+
+1. **Is this an Axn action?** Check whether the job class includes `Axn::Core`.
+2. **Was this notice sent by Axn or by the framework natively?** Tag Axn-authored notices in your `on_exception` handler so they can be distinguished from the native ones.
+
+Add a known key when calling your error reporter from `on_exception`:
+
+```ruby
+Axn.configure do |c|
+  c.on_exception = proc do |e, action:, context:|
+    # Tag this notice as Axn-authored so we can identify it in before_notify filters
+    Honeybadger.notify(e, context: context.merge(axn: true))
+  end
+end
+```
+
+## Honeybadger + Sidekiq Example
+
+Honeybadger's `before_notify` hook lets you inspect and halt notices before they're sent:
+
+```ruby
+# config/initializers/honeybadger.rb
+Honeybadger.configure do |config|
+  config.before_notify do |notice|
+    # Axn-authored notices (tagged via on_exception) always pass through
+    next if notice.context[:axn] || notice.context["axn"]
+
+    # Halt native Sidekiq/ActiveJob notices for Axn actions —
+    # Axn's on_exception is handling reporting for these.
+    component = notice.component.to_s
+
+    # Direct Sidekiq worker: component is the Axn action class itself
+    klass = component.safe_constantize
+    next notice.halt! if klass&.include?(Axn::Core)
+
+    # ActiveJob proxy: component is "MyAction::ActiveJobProxy"
+    if component.end_with?("::ActiveJobProxy")
+      action_klass = component.delete_suffix("::ActiveJobProxy").safe_constantize
+      next notice.halt! if action_klass&.include?(Axn::Core)
+    end
+  end
+end
+```
+
+**What this does:**
+
+- Axn-authored notices (tagged `axn: true`) pass through unchanged
+- Native Sidekiq/ActiveJob notices for Axn actions are halted
+- Notices for non-Axn workers are unaffected
+- Multiple `before_notify` hooks compose — this doesn't interfere with other app-specific filters
+
+## Notes
+
+- The exact implementation varies by error reporter and adapter. The pattern is the same: detect Axn ownership at the filter layer and suppress native reports, passing through Axn-authored ones.
+- This fix is typically applied in your application or framework layer rather than in Axn itself, since it depends on which error reporter you're using.

data/docs/reference/async/sidekiq.md

@@ -212,6 +212,14 @@ Axn::Async::Adapters::Sidekiq::AutoConfigure.death_handler_registered?
 # => should be true
 ```
 
+### Duplicate error reports from Honeybadger or other error integrations
+
+If you're seeing duplicate faults in your error tracker — for example, both an Axn-authored notice and a raw `RuntimeError` fault with one entry per retry — this is caused by your error monitoring integration reporting the re-raised exception independently of Axn's `on_exception` path.
+
+Axn re-raises unexpected exceptions after reporting so that Sidekiq can retry them. Integrations like Honeybadger's Sidekiq plugin intercept that re-raised exception directly, bypassing your `async_exception_reporting` setting entirely.
+
+See [Suppressing Duplicate Async Error Reports](/recipes/suppressing-duplicate-async-reports) for an explanation and a Honeybadger + Sidekiq filter example.
+
 ### Jobs not retrying on fail!
 
 This is expected behavior. `fail!` indicates a business decision, not a transient error. If you need retries for a specific failure case, raise an exception instead:

data/docs/reference/axn-result.md

@@ -12,7 +12,7 @@ Every `call` invocation on an Axn will return an `Axn::Result` instance, which p
 | `outcome` | The execution outcome as a string inquirer (`success?`, `failure?`, `exception?`)
 | `elapsed_time` | Execution time in milliseconds (Float)
 | `finalized?` | `true` if the result has completed execution (either successfully or with an exception), `false` if still in progress
-| 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)
+| any `expose`d values | guaranteed to be set if `ok?`; fields that are also `expects`-declared are auto-copied and available on `fail!` and exception paths too (see [Re-exposing an expected field](/usage/writing#re-exposing-an-expected-field-auto-copy))
 
 NOTE: `success` and `error` (and so implicitly `message`) can be configured per-action via [the `success` and `error` declarations](/reference/class#success-and-error).
 

data/docs/reference/class.md

@@ -20,6 +20,58 @@ Both `expects` and `exposes` support the same core options:
 | `type` | `expects :foo, type: String` | Custom type validation -- fail unless `name.is_a?(String)`
 | anything else | `expects :foo, inclusion: { in: [:apple, :peach] }` | Any other arguments will be processed [as ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html) (i.e. as if passed to `validates :foo, <...>` on an ActiveRecord model)
 
+### Dynamic `sensitive` fields
+
+The `sensitive` option can accept a proc or symbol in addition to a boolean, allowing you to conditionally filter fields based on runtime values:
+
+```ruby
+class MyAction
+  include Axn
+
+  expects :include_pii, type: :boolean
+  expects :ssn, sensitive: -> { !include_pii }
+
+  exposes :api_response, sensitive: :should_redact?
+
+  def call
+    expose api_response: fetch_data
+  end
+
+  private
+
+  def should_redact?
+    !include_pii || result.api_response[:contains_secrets]
+  end
+end
+
+# When include_pii is false, ssn is filtered
+MyAction.call(include_pii: false, ssn: "123-45-6789")
+#=> inputs: { ssn: [FILTERED], include_pii: false }
+
+# When include_pii is true, ssn is visible
+MyAction.call(include_pii: true, ssn: "123-45-6789")
+#=> inputs: { ssn: "123-45-6789", include_pii: true }
+```
+
+The callable receives no arguments and is evaluated via `instance_exec`, so it has access to:
+- All `expects` field values (via their reader methods, e.g., `include_pii`)
+- Exposed values via `result.field` (e.g., `result.api_response`) — bare field names are **not** available for `exposes`-only fields
+- Any instance methods defined on the action
+
+::: warning Timing: sensitive evaluated before defaults
+For `expects` fields, the `sensitive` callable is evaluated **before** defaults are applied. This means if your sensitivity logic depends on another field's value, that field should either be required or you should handle `nil` explicitly:
+
+```ruby
+# CAUTION: mode may be nil if caller doesn't provide it
+expects :mode, default: "public"
+expects :api_key, sensitive: -> { mode != "debug" }  # mode could be nil here!
+
+# SAFER: handle nil explicitly
+expects :api_key, sensitive: -> { mode.nil? || mode != "debug" }
+```
+
+This is because automatic logging of inputs happens before defaults are applied in the execution flow. For `exposes` fields, this is not a concern since output logging happens after the action completes.
+:::
 
 ### Validation details
 
@@ -27,11 +79,16 @@ Both `expects` and `exposes` support the same core options:
 While we _support_ complex interface validations, in practice you usually just want a `type`, if anything.  Remember this is your validation about how the action is called, _not_ pretty user-facing errors (there's [a different pattern for that](/recipes/validating-user-input)).
 :::
 
-In addition to the [standard ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html), we also support four additional custom validators:
+In addition to the [standard ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html), we also support five additional custom validators:
 * `type: Foo` - fails unless the provided value `.is_a?(Foo)`
   * Edge case: use `type: :boolean` to handle a boolean field (since ruby doesn't have a Boolean class to pass in directly)
+    * Boolean `expects` fields also define a predicate reader, so `expects :enabled, type: :boolean` provides both `enabled` and `enabled?` on the action instance. The same applies to subfield readers unless `readers: false` is set. Boolean `exposes` fields provide predicate readers on the result, so `exposes :enabled, type: :boolean` provides `result.enabled?`.
   * Edge case: use `type: :uuid` to handle a confirming given string is a UUID (with or without `-` chars)
   * Edge case: use `type: :params` to accept either a Hash or ActionController::Parameters (Rails-compatible)
+* `of: Foo` - for `type: Array` fields, validates each element (fails unless every element `.is_a?(Foo)`)
+  * Accepts the same forms as `type:`: a single class (`of: String`), a union array (`of: [String, Numeric]` — an element passes if it matches *any*), the `:boolean`/`:uuid`/`:params` symbols, or a `Data.define` class
+  * Only valid alongside `type: Array` (exactly) — using it on any other type, including a union like `type: [Array, String]`, raises `ArgumentError` at declaration time
+  * Error messages report the failing element's index (e.g. `element at index 2 is not a String`). Pass `of: { klass: Foo, message: "..." }` to override the type description while still reporting the index
 * `validate: [callable]` - Support custom validations (fails if any string is returned OR if it raises an exception)
   * Example:
     ```ruby
@@ -61,13 +118,38 @@ In addition to the [standard ActiveModel validations](https://guides.rubyonrails
     * For external APIs, you can pass a `Method` object as the finder
     :::
 
+#### Describing the shape of structured fields (block syntax)
+
+For a structured field — `type: Array`, `type: Hash`, or a class such as a `Data.define` — you can pass a block to declare per-member contracts (types, enums, descriptions, nesting). This works on both `expects` and `exposes`:
+
+```ruby
+exposes :integrations, type: Array, of: IntegrationRecord do
+  field :source, type: String
+  field :status, type: String, inclusion: { in: %w[connected connected_with_issues needs_reconnect incomplete error] }
+
+  field :config, type: Hash do                  # nested object
+    field :region, type: String
+  end
+  field :endpoints, type: Array do              # nested array of objects
+    field :url, type: String
+  end
+end
+```
+
+* The block requires a single, **structured** `type:` (Array, Hash, or a class). Declaring it on a scalar type (`String`, `Integer`, `:boolean`, …), a union (`type: [Array, String]`), or with no `type:` raises `ArgumentError` at declaration time.
+* For `type: Array`, each element is validated and errors report the element's index (e.g. `element at index 2: status is not included in the list`). For a `type: Hash`/class, the single value's members are validated directly.
+* Members accept validations (`type`, `inclusion`, …), `optional`/`allow_blank`/`allow_nil`, and `description`, and **recurse** — a member with its own block validates its nested members at any depth. Members are validation/schema-only, so `default:`, `preprocess:`, and `sensitive:` are **not** supported on a member (they raise at declaration time).
+* Unlike `expects … on:` subfields, a shape block does **not** define reader methods — there is no single value to bind (an array has many elements). It is a contract on structure only.
+* Composes with `of:`: `of:` checks each element's *class*, while the block describes the element's *fields*. `of:` is optional.
+
 #### How `optional`, `allow_blank` and `allow_nil` work with validators
 
 When you specify `optional: true`, `allow_blank: true`, or `allow_nil: true` on a field, these options are automatically passed through to **all validators** applied to that field. This means:
 
 - **ActiveModel validations** (like `inclusion`, `length`, etc.) will respect these options
-- **Custom validators** (`type`, `validate`, `model`) will also respect these options
+- **Custom validators** (`type`, `validate`, `model`, `of`) will also respect these options
 - **Type validator edge case**: Note passing `allow_blank` is nonsensical for type: :params and type: :boolean
+- **`of` validator note**: these options govern whether the whole Array field may be absent — they do **not** make individual elements optional. A `nil` (or blank) element is still validated against `of:` regardless.
 
 **Recommended approach**: Use `optional: true` instead of `allow_blank: true` for better clarity. The `optional` parameter is equivalent to `allow_blank: true` and makes the intent clearer.
 
@@ -75,7 +157,7 @@ If neither `optional`, `allow_blank` nor `allow_nil` is specified, a default pre
 
 ### Details specific to `.exposes`
 
-Remember that you'll need [a corresponding `expose` call](/reference/instance#expose) for every variable you declare via `exposes`.
+For fields you declare via `exposes`, you'll need [a corresponding `expose` call](/reference/instance#expose) — unless the field is also declared via `expects`, in which case axn auto-copies it from the input into the result on all outcome paths (success, `fail!`, and exception). See [Re-exposing an expected field](/usage/writing#re-exposing-an-expected-field-auto-copy).
 
 
 ### Details specific to `.expects`
@@ -101,6 +183,21 @@ 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.
 :::
 
+#### Reaching into nested parents
+
+`on:` accepts a **dotted path** to declare a subfield of a deeply-nested parent, with a clean flat reader named after the field:
+
+```ruby
+expects :address, type: Hash
+expects :zip, on: "address.billing", type: String  # validates address[:billing][:zip]; defines a `zip` reader
+```
+
+The **root** segment (`address`) must be a declared field (or subfield); intermediate segments are assumed to be hashes. The reader is named after the subfield (`zip`) — there's no ambiguity, since the field name itself has no dots.
+
+::: warning
+`default:`, `preprocess:`, and `sensitive:` are **not** supported on a dotted `on:` (they raise at declaration time) — `default:`/`preprocess:` write into the parent, and `sensitive:` relies on the log filter matching a top-level field, neither of which handles an arbitrary nested path yet. Use them on a single-key `on:`, or declare the intermediate levels explicitly.
+:::
+
 #### 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`:

data/docs/usage/writing.md

@@ -47,7 +47,7 @@ To abort execution with a specific error message, call `fail!`. You can also pro
 
 To complete execution early with a success result, call `done!` with an optional success message and exposures as keyword arguments.
 
-If you declare that your action `exposes` anything, you need to actually `expose` it.
+If you declare that your action `exposes` anything, you need to actually `expose` it — unless you're re-exposing a field you also `expects`, in which case axn auto-copies it for you (see below).
 
 ```ruby
 class Foo
@@ -67,6 +67,29 @@ end
 
 See [the reference doc](/reference/instance) for a few more handy helper methods (e.g. `#log`).
 
+### Re-exposing an expected field (auto-copy)
+
+When a field is declared with both `expects` and `exposes`, axn automatically copies it from the input into the result — no manual `expose` call needed. This works on **all outcome paths**: success, `done!`, `fail!`, and unhandled exceptions.
+
+This is particularly useful when an action mutates an ActiveRecord object in-place (e.g. `user.valid?` populates `user.errors`) and the caller needs to inspect the object after a failure:
+
+```ruby
+class UpdateUser
+  include Axn
+
+  expects :user, model: true
+  exposes :user               # auto-copied — no expose call needed
+
+  def call
+    user.assign_attributes(params)
+    fail! unless user.save    # user.errors is available on result.user even on failure
+  end
+end
+
+result = UpdateUser.call(user:, params:)
+result.user.errors.full_messages  # populated on both ok? and !ok?
+```
+
 ### Convenient failure with context
 
 Both `fail!` and `done!` can accept keyword arguments to expose data before halting execution:

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

@@ -27,7 +27,7 @@ module Axn
               config_mode = klass.try(:_async_exception_reporting) || Axn.config.async_exception_reporting
               return if config_mode == :every_attempt # Already reported on each attempt
 
-              retry_context = RetryHelpers.build_retry_context(job)
+              retry_context = RetryHelpers.build_retry_context(job, from_death_handler: true)
 
               # For :first_and_exhausted, we need to report now (exhausted)
               # For :only_exhausted, we need to report now (only time)

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

@@ -43,10 +43,21 @@ module Axn
 
           # Builds an Axn::Async::RetryContext from a Sidekiq job hash.
           # Used by both middleware and death handler to ensure consistent context.
-          def build_retry_context(job)
+          #
+          # @param from_death_handler [Boolean] When true, subtracts 1 from the computed attempt
+          #   because Sidekiq increments retry_count before calling death handlers, so the value
+          #   in the job hash is one higher than the retry_count present during the last execution.
+          def build_retry_context(job, from_death_handler: false)
+            attempt = extract_attempt_number(job)
+            # Sidekiq increments retry_count before calling retries_exhausted/death handlers,
+            # so the job hash has retry_count = last_execution_retry_count + 1. Subtract 1 to
+            # recover the actual last execution's attempt number. Guard on non-nil: when Sidekiq
+            # calls death handlers directly (retry: false), retry_count is absent and attempt is
+            # already correct.
+            attempt -= 1 if from_death_handler && !job["retry_count"].nil?
             RetryContext.new(
               adapter: :sidekiq,
-              attempt: extract_attempt_number(job),
+              attempt:,
               max_retries: extract_max_retries(job),
               job_id: job["jid"],
             )

data/lib/axn/core/context/facade_inspector.rb

@@ -65,19 +65,25 @@ module Axn
       inspection_filter.filter_param(field, inspected_value)
     end
 
-    def inspection_filter = action.class.inspection_filter
+    def inspection_filter
+      @inspection_filter ||= if action.class._has_dynamic_sensitive_fields?
+                               action.class._build_instance_filter(action)
+                             else
+                               action.class.inspection_filter
+                             end
+    end
 
     def sensitive_subfields?(field)
-      action.subfield_configs.any? { |config| config.on == field && config.sensitive }
+      action.subfield_configs.any? do |config|
+        config.on == field && action.class._resolve_sensitive_value(config.sensitive, action)
+      end
     end
 
     def filter_subfields(field, value)
-      # Build a nested structure with subfield paths for filtering
       nested_data = { field => value }
 
-      # Create a filter with the subfield paths
       sensitive_subfield_paths = action.subfield_configs
-                                       .select { |config| config.on == field && config.sensitive }
+                                       .select { |config| config.on == field && action.class._resolve_sensitive_value(config.sensitive, action) }
                                        .map { |config| "#{field}.#{config.field}" }
 
       return value if sensitive_subfield_paths.empty?