action_figure 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c29461ca24fe48d0143c6c861a738e37fa04fa9954b0fcc3336f8154dc16a30
-  data.tar.gz: 93e527838e129363aafbba74751660831a54084cb159571fa71f0b9ef11322fc
+  metadata.gz: f2f1def52c6601cb91ff3b2cd2fc366efeef932c1fba3072932f674cbf1748af
+  data.tar.gz: da5c9b0ab274f7e6f1512560af168d4d44c21dc3875ac85c0f79998902fa5df1
 SHA512:
-  metadata.gz: 311b1a051ee7caec1aece62143607ed2484720ab6a04398b66f091087a0febccacc91e1478c438bbca98b93d0d13cf57da6f12d8ae3caf47dd8bbb0b642c7994
-  data.tar.gz: 4bd0d145727af9f7373301ad26abc7b65a08041071c07317cf3fb88a818961be09e834de1b857a5256c6012b2965e0aa2bf1da24943cd2219689416d14be5a22
+  metadata.gz: 1ebdc99c40beb7e461eab4022825efd657f15c29fc01a84d432f253928040ad1191057ed7c6b5845670d34af2963e56c9760aec613b590e577d81bae60da2233
+  data.tar.gz: d6b1112c59d61637c9e45e8f84b94ef25b75372e899b7f86e88ee0fc66d932325f567913ed75b47eb8283bde0a9d4e67935cbeac751665010b73cd56f1946cb9

data/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to ActionFigure will be documented in this file.
+
+## [0.6.2] - 2026-06-25
+
+### Fixed
+
+- Without a **`params_schema`**, params now pass through **untouched** — **`to_unsafe_h`** is only called when there is a schema to validate against. Previously an **`ActionController::Parameters`** (or any object responding to **`to_unsafe_h`**) was unwrapped into a plain hash even with no schema, contradicting the 0.6.0 "no schema → params pass through unvalidated" contract. **Breaking** for code that relied on the implicit unwrap; such actions should unwrap (e.g. via strong params) themselves.
+
+### Documentation
+
+- **`README.md`**: simplify the before/after hint that prompts readers to spot the incorrect render response.
+
+## [0.6.1] - 2026-05-23
+
+### Added
+
+- **`have_action_json`** RSpec matcher (partial match on **`result[:json]`** via **`a_hash_including`**).
+- Notifications payload **`entry_point`** (Symbol) alongside **`action`** for **`process.action_figure`**.
+- **`InitializationNotSupportedError`** when an action class defines **`initialize`** (instances are built with arity-zero **`new`**).
+- CI job running **`bundle exec rbs validate`**.
+- Regression test asserting built-in formatters expose **`Formatter::REQUIRED_METHODS`** (+ **`NoContent`**).
+
+### Changed
+
+- Renamed `IndeterminantEntryPointError` → **`IndeterminateEntryPointError`** (raised when multiple public entry methods exist without `entry_point`). The old constant remains as a deprecated alias (`Module#deprecate_constant`) for one release; update any `rescue` clauses to the new spelling.
+- **`params_schema`** may only be called once per action class; a duplicate call raises **`ArgumentError`** (previously enforced only when a **`rules`** block was already present).
+
+### Documentation
+
+- Load-order semantics for **`ActionFigure.configure`** (default **`format`** and **`activesupport_notifications`** latch when each class **`include`** runs).
+- Testing guide: matchers/assertions inspect **`[:status]`** only; RSpec **`require`** order.
+- Actions guide: mermaid overview of **`method_added`** / **`entry_point`** discovery.
+- Actions guide: do not define **`initialize`** on actions (arity-zero **`new`**); use **`InitializationNotSupportedError`** when violated.
+- Actions guide: **`api_version`** — clarify global (**`configure`**) vs class macro (**no fallback**).
+- **`README.md`**: `:unprocessable_entity` vs ActionFigure **`result[:status]`** symbol **`:unprocessable_content`**.
+- Configuration guide: **thread safety** / singleton **`ActionFigure.configuration`** semantics.
+- ActiveSupport Notifications: payload documents **`entry_point`**; subscriber examples reference it.
+- Testing guide: **`have_action_json`** RSpec matcher.
+
+## [0.6.0] - 2026-03-30
+
+### Added
+
+- `Conflict` (409) and `PaymentRequired` (402) response helpers across all formatters
+- Automatic entry point discovery via `method_added` — single public method is detected without needing `entry_point`
+- `IndeterminantEntryPointError` raised when multiple public methods exist without an explicit `entry_point`
+- Status codes documentation (`docs/status-codes.md`)
+
+### Changed
+
+- `params_schema` is now optional — actions without a schema pass `params:` through unvalidated
+
+## [0.5.0] - 2026-03-25
+
+### Added
+
+- Thread-safe format registry using `Concurrent::Map`
+- RBS type signatures for the full public API (`sig/action_figure.rbs`)
+- Integration test suite (`test/integration/full_pipeline_test.rb`)
+
+### Fixed
+
+- Schema guard: redefining `params_schema` after `rules` now raises instead of silently dropping rules
+- Keyword argument safety: non-params kwargs pass through untouched
+- Consistent envelope: `Accepted` without a resource uses `nil` data (not omitted key) in Default and Wrapped formatters
+- RSpec negated matcher failure message now shows actual status
+
+## [0.4.0] - 2026-03-21
+
+### Added
+
+- Wrapped formatter (`ActionFigure::Formatters::Wrapped`) with uniform `{ data:, errors:, status: }` envelope
+- Default formatter (`ActionFigure::Formatters::Default`) with `{ data: }` envelope
+- `ActiveSupport::Notifications` instrumentation (opt-in via `activesupport_notifications` config)
+- Cross-parameter rule helpers: `exclusive_rule`, `any_rule`, `one_rule`, `all_rule`
+- `meta:` keyword on success response helpers (`Ok`, `Created`, `Accepted`)
+- `.contract` accessor for standalone schema/rules introspection
+- `api_version` class-level macro for per-action version tagging
+- `whiny_extra_params` configuration option
+- Minitest assertions (`assert_Ok`, `assert_Created`, etc.) and RSpec matchers (`be_Ok`, `be_Created`, etc.)
+- JSON:API formatter with `Resource` serializer for ActiveRecord objects
+- Custom formatter registration with load-time validation
+- User-facing documentation for all features
+
+### Changed
+
+- `UnprocessableEntity` renamed to `UnprocessableContent` to match Rails 7.1+ naming
+
+## [0.1.0] - 2026-03-20
+
+### Added
+
+- Initial release
+- Core validation pipeline powered by dry-validation
+- JSend response formatter
+- `params_schema` and `rules` DSL
+- `ActionController::Parameters` support via `to_unsafe_h`
+- `NoContent` response helper

data/README.md

@@ -7,122 +7,107 @@ Fully-articulated controller actions.
 > [Installation](#installation)<br>
 > [How It Works](#how-it-works)<br>
 > [Features](#features)<br>
-> [Quick Start](#quick-start)<br>
 > [Design Philosophy](#design-philosophy)<br>
+> [Examples](#examples)<br>
 > [Requirements](#requirements)<br>
 > [License](#license)
 ---
 
-**ActionFigure** extracts controller actions into classes that validate params, orchestrate work, and return render-ready responses. Your controller becomes:
+**ActionFigure** makes your controller actions more usable and understandable. It turns this:
 
 ```ruby
-class OrdersController < ApplicationController
+class ProjectsController < ApplicationController
   def create
-    render Orders::CreateAction.create(params:, current_user:)
-  end
-end
-```
-
-The action class owns everything that used to be scattered across the controller method, strong params, model callbacks, and ad-hoc response building:
+    permitted = params.require(:project).permit(
+      :name, :description, settings: [:visibility, :notify_on_mention]
+    )
 
-```ruby
-class Orders::CreateAction
-  include ActionFigure[:wrapped]
+    if permitted[:name].blank?
+      render json: { status: "fail", data: { name: ["is required"] } },
+             status: :unprocessable_entity
+      return
+    end
 
-  params_schema do
-    required(:item_id).filled(:integer)
-    required(:quantity).filled(:integer)
-    optional(:coupon_code).filled(:string)
-    optional(:gift_message).filled(:string)
-    optional(:gift_recipient_email).filled(:string)
-  end
+    if permitted.dig(:settings, :visibility).present? &&
+       !%w[public private].include?(permitted[:settings][:visibility])
+      render json: { status: "fail", data: { settings: { visibility: ["must be public or private"] } } },
+             status: :unprocessable_entity
+      return
+    end
 
-  rules do
-    all_rule(:gift_message, :gift_recipient_email,
-             "gift fields must be provided together or not at all")
-  end
+    unless current_user.member_of?(current_workspace)
+      render json: { status: "fail", data: { base: ["must be a workspace member"] } },
+             status: :forbidden
+      return
+    end
 
-  def create(params:, current_user:)
-    if current_user.unpaid_balance?
-      return Forbidden(errors: { base: ["unpaid balance on account"] })
+    if current_workspace.projects.exists?(name: permitted[:name])
+      render json: { status: "fail", data: { name: ["already exists in this workspace"] } },
+             status: :conflict
+      return
     end
 
-    item = Item.find_by(id: params[:item_id])
-    return NotFound(errors: { item_id: ["item not found"] }) unless item
+    project = CreateProject.run(permitted, workspace: current_workspace, creator: current_user)
 
-    order = current_user.orders.create(
-      item: item,
-      quantity: params[:quantity],
-      coupon_code: params[:coupon_code]
-    )
-    return UnprocessableContent(errors: order.errors.messages) if order.errors.any?
+    if project.errors.any?
+      render json: { status: "fail", data: project.errors.messages },
+             status: :unprocessable_entity
+      return
+    end
 
-    resource = OrderBlueprint.render_as_hash(order, view: :confirmation)
-    Created(resource:)
+    render json: { status: "success", data: ProjectBlueprint.render_as_hash(project) }
   end
 end
 ```
 
-Param validation, cross-field rules, authorization, error handling, and response formatting — all in one place, all testable without a request:
+into this:
 
 ```ruby
-class Orders::CreateActionTest < Minitest::Test
-  include ActionFigure::Testing::Minitest
-
-  def test_creates_an_order
-    user = User.create!(name: "Tad")
-    item = Item.create!(name: "Widget", price: 29.00)
-
-    result = Orders::CreateAction.create(
-      params: { item_id: item.id, quantity: 2 },
-      current_user: user
-    )
-
-    assert_Created(result)
-    assert_equal item.id, result[:json][:data]["item_id"]
+class ProjectsController < ApplicationController
+  def create
+    render Projects::CreateAction.create(params:, current_user:, current_workspace:)
   end
+end
+```
 
-  def test_forbidden_with_unpaid_balance
-    user = User.create!(name: "Tad", balance: -1)
-
-    result = Orders::CreateAction.create(
-      params: { item_id: 1, quantity: 1 },
-      current_user: user
-    )
+```ruby
+class Projects::CreateAction
+  include ActionFigure[:jsend]
 
-    assert_Forbidden(result)
-    assert_includes result[:json][:errors][:base], "unpaid balance on account"
+  params_schema do
+    required(:project).hash do
+      required(:name).filled(:string)
+      optional(:description).filled(:string)
+      optional(:settings).hash do
+        optional(:visibility).filled(:string, included_in?: %w[public private])
+        optional(:notify_on_mention).filled(:bool)
+      end
+    end
   end
 
-  def test_not_found_when_item_missing
-    user = User.create!(name: "Tad")
-
-    result = Orders::CreateAction.create(
-      params: { item_id: 999, quantity: 1 },
-      current_user: user
-    )
-
-    assert_NotFound(result)
-    assert_includes result[:json][:errors][:item_id], "item not found"
-  end
+  def create(params:, current_user:, current_workspace:)
+    unless current_user.member_of?(current_workspace)
+      return Forbidden(errors: { base: ["must be a workspace member"] })
+    end
 
-  def test_rejects_partial_gift_fields
-    user = User.create!(name: "Tad")
-    item = Item.create!(name: "Widget", price: 29.00)
+    if current_workspace.projects.exists?(name: params[:project][:name])
+      return Conflict(errors: { name: ["already exists in this workspace"] })
+    end
 
-    result = Orders::CreateAction.create(
-      params: { item_id: item.id, quantity: 1, gift_message: "Enjoy!" },
-      current_user: user
-    )
+    project = CreateProject.run(params[:project], workspace: current_workspace, creator: current_user)
+    return UnprocessableContent(errors: project.errors.messages) if project.errors.any?
 
-    assert_UnprocessableContent(result)
-    assert_includes result[:json][:errors][:gift_message],
-                    "gift fields must be provided together or not at all"
+    Created(resource: ProjectBlueprint.render_as_hash(project))
   end
 end
 ```
 
-This isn't for everybody. If your controllers are already thin, or you validate through OpenAPI middleware like [committee](https://github.com/interagent/committee), you probably don't need this. ActionFigure is for teams whose controller actions have grown into tangled mixes of param wrangling, authorization checks, error handling, and response building.
+- The shape and types of your params are obvious
+- The structure is clear
+- The tests are easy (and 10x faster)
+- The responses are uniform and render-ready
+
+(Look closely, one of the responses in the first example is wrong. Can you spot it?)
 
 ## Installation
 
@@ -137,7 +122,7 @@ gem "action_figure"
 Every action class has three responsibilities:
 
 1. **Check params** (optional) — when a `params_schema` is defined, it validates structure and types; `rules` enforces validation rules. If either fails, the formatter returns an error response and your action method is never invoked. Actions without a schema receive `params:` as-is.
-2. **Orchestrate** — your action method coordinates the work: creating records, calling service objects, enqueuing jobs, or anything else the action requires. The action is the entry point, not necessarily where all the logic lives.
+2. **Orchestrate** — your action method coordinates the work: creating records, coordinating collaborators, enqueuing jobs, or anything else the action requires. The action is the entry point, not necessarily where all the logic lives.
 3. **Return a formatted response** — response helpers like `Created(resource:)` and `NotFound(errors:)` return render-ready hashes that go straight to `render` in your controller.
 
 ## Features
@@ -154,87 +139,111 @@ Every action class has three responsibilities:
 | [Testing](docs/testing.md) | Minitest assertions (`assert_Ok`, `assert_Created`, ...) and RSpec matchers (`be_Ok`, `be_Created`, ...) for expressive status checks. |
 | [Integration Patterns](docs/integration-patterns.md) | Recipes for serializers (Blueprinter, Alba, Oj Serializers), authorization (Pundit, CanCanCan), and pagination (cursor, Pagy). |
 
-## Quick Start
+## Design Philosophy
+
+ActionFigure is scoped to controller actions — it validates params, runs your logic, and returns a hash you pass directly to `render`.
+
+- **Purpose over convention** — each class does one thing and names it clearly
+- **Explicit over implicit** — no magic method resolution, no inherited callbacks
+- **Actions own their lifecycle** — validation, execution, and response formatting live together
+- **Controllers become boring** — one-line `render` calls that delegate to action classes
+- **Separate domain tests from perimeter tests** — keep your controller tests for perimeter checks, but now your domain logic lives in plain method calls. Faster tests, clearer failures.
+
+## Examples
+
+### Validation Rules
 
-**1. Define the action class.**
+Cross-parameter helpers make multi-field constraints declarative:
 
 ```ruby
-# app/actions/users/create_action.rb
-class Users::CreateAction
+class Search::LookupAction
   include ActionFigure[:jsend]
 
   params_schema do
-    required(:user).hash do
-      required(:name).filled(:string)
-      required(:email).filled(:string)
-    end
+    optional(:user_id).filled(:integer)
+    optional(:email).filled(:string)
   end
 
-  def create(params:, company:)
-    user = company.users.create(params[:user])
-    return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
+  rules do
+    exclusive_rule(:user_id, :email, "provide one, not both")
+  end
+
+  def lookup(params:)
+    user = params[:user_id] ? User.find_by(id: params[:user_id]) : User.find_by(email: params[:email])
 
-    Created(resource: user.as_json(only: %i[id name email]))
+    Ok(resource: user.as_json)
   end
 end
 ```
 
-**2. Call it from your controller.**
+### Response Formatters
+
+Choose a response envelope by name. The same helpers return different shapes:
 
 ```ruby
-class UsersController < ApplicationController
-  def create
-    render Users::CreateAction.create(params:, company: current_company)
-  end
-end
+# Default
+Created(resource: user)
+# => { json: { data: user }, status: :created }
+
+# JSend
+Created(resource: user)
+# => { json: { status: "success", data: user }, status: :created }
+
+# JSON:API
+Created(resource: user)
+# => { json: { data: { type: "users", id: "1", attributes: user } }, status: :created }
+
+# Wrapped
+Created(resource: user)
+# => { json: { data: user, errors: nil, status: "success" }, status: :created }
 ```
 
-**3. Test it directly.**
+### Testing
+
+Action classes are plain method calls — no request setup needed:
 
 ```ruby
-class Users::CreateActionTest < Minitest::Test
+class Search::LookupActionTest < Minitest::Test
   include ActionFigure::Testing::Minitest
 
-  def test_creates_a_user
-    company = Company.create!(name: "Acme")
-
-    result = Users::CreateAction.create(
-      params: { user: { name: "Tad", email: "tad@example.com" } },
-      company: company
+  def test_finds_by_email
+    result = Search::LookupAction.lookup(
+      params: { email: "tad@example.com" }
     )
 
-    assert_Created(result)
-    assert_equal "Tad", result[:json][:data]["name"]
+    assert_Ok(result)
   end
 
-  def test_fails_when_name_is_missing
-    company = Company.create!(name: "Acme")
-
-    result = Users::CreateAction.create(
-      params: { user: { email: "tad@example.com" } },
-      company: company
+  def test_rejects_both_user_id_and_email
+    result = Search::LookupAction.lookup(
+      params: { user_id: 1, email: "tad@example.com" }
     )
 
     assert_UnprocessableContent(result)
-    assert_includes result[:json][:data][:user][:name], "is missing"
+    assert_includes result[:json][:data][:user_id], "provide one, not both"
   end
 end
 ```
 
-## Design Philosophy
+### Actions Without a Schema
 
-Unlike general-purpose service object libraries, ActionFigure is scoped to controller actions — it validates params, runs your logic, and returns a hash you pass directly to `render`.
+Not every action needs parameter validation:
 
-- **Purpose over convention** — each class does one thing and names it clearly
-- **Explicit over implicit** — no magic method resolution, no inherited callbacks
-- **Actions own their lifecycle** — validation, execution, and response formatting live together
-- **Controllers become boring** — one-line `render` calls that delegate to action classes
-- **Models and Controllers stay thin** — business logic moves to purpose-built action classes
+```ruby
+class HealthCheckAction
+  # Uses the globally-configured format
+  include ActionFigure
+
+  def check(current_user:)
+    Ok(resource: { status: "healthy", user: current_user.name })
+  end
+end
+```
 
 ## Requirements
 
 - Ruby >= 3.2
-- [dry-validation](https://dry-rb.org/gems/dry-validation/) ~> 1.10 — ActionFigure uses dry-validation for schema validation because it's the best tool for the job. There's no dependency injection container, no monads, no functional pipeline. Just a focused layer for controller actions.
+- [dry-validation](https://dry-rb.org/gems/dry-validation/) ~> 1.10 — ActionFigure uses dry-validation for schema validation. However, there's no dependency injection container, monads, or functional pipeline. Just a focused layer for controller actions.
 - Rails is not required, but ActionFigure is designed for Rails controller patterns
 
 ## License

data/docs/actions.md

@@ -44,12 +44,28 @@ end
 
 ActionFigure uses a `method_added` hook to watch for public instance methods defined on the class. The first public method defined becomes the registered entry point and a matching class-level method is created for it. The full validation pipeline (`params_schema` and `rules`) still runs through the discovered entry point before your method is invoked.
 
+Do not define **`initialize`** on action classes: ActionFigure calls **`new`** with no arguments each time work runs. A custom initializer raises **`InitializationNotSupportedError`** (even if `initialize` is private or you used **`entry_point`**). Prefer keyword arguments on the entry method or class-level collaborators for dependencies instead.
+
+Overview of discovery (**`entry_point`** sidesteps ambiguity by wiring the singleton up front):
+
+```mermaid
+flowchart TD
+  A[include mixes Core + formatter] --> B["method_added fires for each new method"]
+  B --> C{"`entry_point` macro already declared?"}
+  C -->|"yes"| D[Skip auto-discovery;\nsingleton was defined by the macro]
+  C -->|"no"| E{"Public instance method owned by\nthis action class?"}
+  E -->|"no"| B
+  E -->|"yes"| F{"First discovered entry?"}
+  F -->|"yes"| G["Remember name;\ndefine .name(**kwargs) -> validated_call"]
+  F -->|"no"| H["Raise IndeterminateEntryPointError"]
+```
+
 ### Disambiguation with `entry_point`
 
-If a class ends up with more than one public instance method, ActionFigure cannot determine which one to use and raises an `IndeterminantEntryPointError`:
+If a class ends up with more than one public instance method, ActionFigure cannot determine which one to use and raises an `IndeterminateEntryPointError`:
 
 ```
-ActionFigure::IndeterminantEntryPointError: Multiple public methods defined in Orders::SearchAction:
+ActionFigure::IndeterminateEntryPointError: Multiple public methods defined in Orders::SearchAction:
 :search and :format_results. Either make one private or declare
 `entry_point :search` to disambiguate.
 ```
@@ -444,7 +460,7 @@ ActionFigure.configure do |config|
 end
 ```
 
-The global version is accessible via `ActionFigure.configuration.api_version` but is not used as an automatic fallback for class-level `api_version`. Version values are independent per class -- they are not inherited by subclasses because version state is stored in class-level instance variables.
+The global value reads from **`ActionFigure.configuration.api_version`**. It never acts as an automatic fallback for **`api_version` on the class**: the two strings are intentionally separate. Use **`config.api_version`** for **infra-wide defaults** — release dashboards, outbound headers assembled in middleware, initializer documentation — without forcing each action constant to duplicate the same value. Put **`api_version "2.0"`** on classes when that action participates in explicit version branching. Versions are independent per class and **not inherited** by subclasses (state lives in class-level instance variables).
 
 ---
 

data/docs/activesupport-notifications.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-ActionFigure can provide notifications in action execution via `ActiveSupport::Notifications`. When enabled, every `.call` (or custom entry point) emits a `process.action_figure` event with the action class name, outcome status, and timing.
+ActionFigure can provide notifications in action execution via `ActiveSupport::Notifications`. When enabled, every class-level trigger (`:call`, `:create`, `:search`, etc.) emits a `process.action_figure` event with the action class name, entry-point symbol, outcome status, and timing.
 
 Notifications are **off by default** and requires both ActiveSupport and an explicit opt-in.
 
@@ -30,10 +30,11 @@ process.action_figure
 
 ## Payload
 
-| Key      | Type   | Description |
-|----------|--------|-------------|
-| `action` | String | The action class name, e.g. `"Users::CreateAction"` |
-| `status` | Symbol | The outcome status, e.g. `:ok`, `:created` |
+| Key           | Type   | Description |
+|---------------|--------|-------------|
+| `action`      | String | The action class name, e.g. `"Users::CreateAction"` |
+| `entry_point` | Symbol | The dispatched instance method (`:call`, `:create`, `:search`, etc.). Always set when the event is emitted — events are only instrumented from the singleton method created during entry-point discovery, so `nil` is not observable in subscribers even though `ClassMethods#entry_point_name` is nullable internally (pre-discovery). |
+| `status`      | Symbol | The outcome status (set after completion), e.g. `:ok`, `:created` |
 
 Timing (duration, start, end) is provided automatically by `ActiveSupport::Notifications`.
 
@@ -44,7 +45,7 @@ Timing (duration, start, end) is provided automatically by `ActiveSupport::Notif
 ```ruby
 ActiveSupport::Notifications.subscribe("process.action_figure") do |event|
   Rails.logger.info(
-    "#{event.payload[:action]} => #{event.payload[:status]} (#{event.duration.round(1)}ms)"
+    "#{event.payload[:action]}##{event.payload[:entry_point]} => #{event.payload[:status]} (#{event.duration.round(1)}ms)"
   )
 end
 ```
@@ -52,16 +53,16 @@ end
 Output:
 
 ```
-Users::CreateAction => :created (12.3ms)
-Orders::SearchAction => :ok (45.7ms)
-Users::CreateAction => :unprocessable_content (1.1ms)
+Users::CreateAction#call => :created (12.3ms)
+Orders::SearchAction#search => :ok (45.7ms)
+Users::CreateAction#call => :unprocessable_content (1.1ms)
 ```
 
 ---
 
 ## What Gets Instrumented
 
-The event wraps the entire action lifecycle -- validation, the `#call` method, and the formatted response. Both successful and failed outcomes are captured:
+The event wraps the entire action lifecycle — validation, the entry-point instance method, and the formatted response. Both successful and failed outcomes are captured:
 
 - Validation failures (e.g. missing required params) produce events with status `:unprocessable_content`
 - Successful calls produce events with whatever status the action returns (`:ok`, `:created`, etc.)
@@ -90,6 +91,7 @@ ActiveSupport::Notifications.subscribe("process.action_figure") do |event|
     event.duration,
     tags: {
       action: event.payload[:action],
+      entry_point: event.payload[:entry_point],
       status: event.payload[:status]
     }
   )

data/docs/configuration.md

@@ -15,15 +15,29 @@ end
 
 The block yields an `ActionFigure::Configuration::Settings` instance. Call any combination of setters inside.
 
+## When configuration applies (load order)
+
+**Default formatter.** With bare `include ActionFigure`, Ruby calls **`ActionFigure.[]`** (no argument) during that line — it mixes in whichever formatter **`ActionFigure.configuration.format`** selects **in that moment**. Later calls to **`ActionFigure.configure`** (changing **`format`**) do **not** swap formatters inside classes that already finished `include`. Run **`configure`** in an initializer (or equivalent) **before** your action classes load, or skip the ambiguity altogether with **`include ActionFigure[:jsonapi]`** (or another registered name).
+
+**Notifications.** **`activesupport_notifications`** is consulted when the mixin’s **`included`** hook runs for your action class. If you turn **`c.activesupport_notifications = true`** only after constants have already loaded their `include` line, existing classes stay without the notifier extension; newly loaded classes get it.
+
+**Per-class knobs** such as **`include ActionFigure[:wrapped]`**, **`entry_point :search`**, and **`api_version "2.0"`** remain whatever you wrote in each class regardless of subsequent global **`configure`** calls.
+
 ## Settings Reference
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `format` | Symbol | `:default` | Default formatter name. Applies to any class that uses bare `include ActionFigure`. |
+| `format` | Symbol | `:default` | Formatter for bare **`include ActionFigure`**. Locked in when that line runs — see **When configuration applies (load order)** above. |
 | `whiny_extra_params` | Boolean | `false` | When `true`, returns an error response for undeclared params instead of silently stripping them. |
-| `activesupport_notifications` | Boolean | `false` | When `true`, enables `ActiveSupport::Notifications` events for action classes defined after the change. Requires ActiveSupport. |
+| `activesupport_notifications` | Boolean | `false` | When `true` and ActiveSupport is defined, emits **`process.action_figure`** for classes whose mixin runs **after** the flag was set — see load order note above. |
 | `api_version` | String or nil | `nil` | Global API version tag, readable via `ActionFigure.configuration.api_version`. |
 
+## Thread safety and global state
+
+`ActionFigure.configure` assigns to a **process-wide singleton** (`ActionFigure.configuration`). For production, set globals **once during boot**. In **multi-threaded** code or parallel test workers, flipping settings concurrently can interfere across threads — snapshot and restore in `ensure` (as the gem’s tests do with `whiny_extra_params`) or avoid mutating globals after boot.
+
+---
+
 ## Registering Formatters via Config
 
 You can register custom formatters inside the configure block with `register`:

data/docs/custom-formatters.md

@@ -50,8 +50,10 @@ module WrappedFormatter
     { json: body, status: :created }
   end
 
-  def Accepted(resource: nil)
-    { json: { data: resource, errors: nil, status: "success" }, status: :accepted }
+  def Accepted(resource: nil, meta: nil)
+    body = { data: resource, errors: nil, status: "success" }
+    body[:meta] = meta if meta
+    { json: body, status: :accepted }
   end
 
   def UnprocessableContent(errors:)

data/docs/testing.md

@@ -36,6 +36,8 @@ end
 | `assert_Conflict(result)`             | `:conflict`              |
 | `assert_PaymentRequired(result)`      | `:payment_required`      |
 
+These helpers compare **only `result[:status]`** against the Rack-style symbol Rails uses in **`render`** — they **do not** assert on **`[:json]`** keys, payloads, or error message text. Combine them with assertions on **`result[:json]`** (or matchers on the body your formatter produces) whenever shape matters.
+
 All assertions accept an optional second argument for a custom failure message:
 
 ```ruby
@@ -61,6 +63,8 @@ Require the helper in your spec support file. No `include` is needed -- the matc
 require "action_figure/testing/rspec"
 ```
 
+**Load order:** require this library **after** RSpec Core and expectations load (usual practice: append it toward the **bottom** of `spec/spec_helper.rb`, after any `require "rails_helper"` / `RSpec.configure` boilerplate from your app). ActionFigure pulls in **`rspec/matchers`**; minimalist scripts without the full **`rspec` CLI shim** must **`require "rspec/expectations"`** (and typically **`require "rspec/core"`**) *before* this file.
+
 ### Matchers
 
 | Matcher                   | Expected status          |
@@ -74,6 +78,18 @@ require "action_figure/testing/rspec"
 | `be_Forbidden`            | `:forbidden`             |
 | `be_Conflict`             | `:conflict`              |
 | `be_PaymentRequired`      | `:payment_required`      |
+| `have_action_json`        | `result[:json]` matches `a_hash_including(fragment)` |
+
+Like the Minitest helpers, each **`be_*`** matcher compares **only `result[:status]`** — **`[:json]`** is ignored unless you assert on it separately. Use **`have_action_json`** when you want a focused assertion against the **`json`** body (compose with **`a_hash_including`** for nested subsets):
+
+```ruby
+expect(result).to be_Ok
+expect(result).to have_action_json(status: "success")
+expect(result).to have_action_json(
+  status: "success",
+  data: a_hash_including(name: "Jane")
+)
+```
 
 Matchers support negation:
 

data/docs/validation.md

@@ -17,6 +17,8 @@ If no `params_schema` is defined, `params:` passes through to your `#call` metho
 
 `params_schema` accepts a block written in the [dry-schema](https://dry-rb.org/gems/dry-schema/) DSL. It defines the shape of your input: which keys are allowed, which are required, and what types they must be.
 
+Each action calls **`params_schema` at most once** — a second call raises **`ArgumentError`**.
+
 ```ruby
 class Users::CreateAction
   include ActionFigure[:jsend]
@@ -100,6 +102,8 @@ end
   ArgumentError: rules requires params_schema to be defined
   ```
 
+- `params_schema` **may only be called once per action class**. Calling it again raises **`ArgumentError`**, so your schema cannot be replaced in a way that could silently confuse or strand an existing **`rules`** block.
+
 - Inside a rule block, access validated values with `values[:field]`.
 - Add an error to a specific field with `key(:field).failure("message")`, or `key.failure("message")` when the rule is scoped to a single field via `rule(:field)`.
 - Multiple rules can target the same field. All rules run even if earlier ones fail -- errors accumulate.

data/lib/action_figure/core.rb

@@ -43,10 +43,9 @@ module ActionFigure
     # subclasses. Define each action class independently.
     module ClassMethods
       def params_schema(&block)
-        if @params_schema_block && @rules_block
+        if @params_schema_block
           raise ArgumentError,
-                "params_schema already defined with rules — " \
-                "redefining it would silently drop the existing rules block"
+                "params_schema already defined — each action class may declare only one schema"
         end
 
         @params_schema_block = block
@@ -99,12 +98,13 @@ module ActionFigure
       end
 
       def method_added(name)
-        return if @explicit_entry_point
-        return unless public_method_defined?(name)
+        disallow_action_initialize(name)
+
+        return if @explicit_entry_point || !public_method_defined?(name)
         return unless instance_method(name).owner == self
 
         if @entry_point_name
-          raise IndeterminantEntryPointError,
+          raise IndeterminateEntryPointError,
                 "Multiple public methods defined in #{self}: " \
                 ":#{@entry_point_name} and :#{name}. " \
                 "Either make one private or declare " \
@@ -119,6 +119,16 @@ module ActionFigure
         super
       end
 
+      def disallow_action_initialize(method_name)
+        return unless method_name == :initialize
+        return unless instance_method(:initialize).owner == self
+
+        raise InitializationNotSupportedError,
+              "#{self} must not define initialize — ActionFigure invokes new with no " \
+              "arguments. Pass dependencies via the entry method's keyword arguments " \
+              "or use class-level collaborators."
+      end
+
       def build_contract
         schema_block = @params_schema_block
         rules_block = @rules_block
@@ -158,7 +168,10 @@ module ActionFigure
       private
 
       def notify
-        payload = { action: name }
+        payload = {
+          action: name,
+          entry_point: entry_point_name
+        }
         ActiveSupport::Notifications.instrument("process.action_figure", payload) do
           result = yield
           payload[:status] = result[:status]
@@ -170,6 +183,8 @@ module ActionFigure
     private
 
     def normalize_params(kwargs)
+      return kwargs unless contract
+
       raw = kwargs[:params]
       return kwargs unless raw.respond_to?(:to_unsafe_h)
 
@@ -190,11 +205,31 @@ module ActionFigure
     def check_extra_params(raw_params, result)
       return unless ActionFigure.configuration.whiny_extra_params
 
-      extra_keys = raw_params.keys.map(&:to_sym) - result.to_h.keys
-      return if extra_keys.empty?
+      errors = find_extra_keys(raw_params, result.to_h)
+      return if errors.empty?
 
-      errors = extra_keys.to_h { |k| [k, ["is not allowed"]] }
       UnprocessableContent(errors: errors)
     end
+
+    def find_extra_keys(raw, validated, prefix = nil)
+      top_level = extra_keys_at_level(raw, validated, prefix)
+      nested = nested_extra_keys(raw, validated, prefix)
+      top_level.merge(nested)
+    end
+
+    def extra_keys_at_level(raw, validated, prefix)
+      (raw.keys.map(&:to_sym) - validated.keys).to_h do |k|
+        [prefix ? :"#{prefix}.#{k}" : k, ["is not allowed"]]
+      end
+    end
+
+    def nested_extra_keys(raw, validated, prefix)
+      validated.each_with_object({}) do |(key, value), errors|
+        next unless value.is_a?(Hash) && raw[key].is_a?(Hash)
+
+        nested_prefix = [prefix, key].compact.join(".")
+        errors.merge!(find_extra_keys(raw[key], value, nested_prefix))
+      end
+    end
   end
 end

data/lib/action_figure/formatter.rb

@@ -5,6 +5,8 @@ module ActionFigure
   # Include this in your formatter module to get a NoContent default
   # and to signal that your module implements the formatter interface.
   module Formatter
+    # Response helper names every formatter must define (+NoContent+ lives on +Formatter+, not required here).
+    # Update every built-in formatter when you extend this list; +register_formatter+ validates against it at load time.
     REQUIRED_METHODS = %i[Ok Created Accepted UnprocessableContent NotFound Forbidden Conflict PaymentRequired].freeze
 
     def NoContent

data/lib/action_figure/formatters/json_api/resource.rb

@@ -18,7 +18,7 @@ module ActionFigure
         def self.serialize_one(resource)
           {
             type: resource.class.model_name.element,
-            id: resource.id.to_s,
+            id: resource.id&.to_s,
             attributes: resource.attributes.except("id")
           }
         end

data/lib/action_figure/formatters/json_api.rb

@@ -48,15 +48,20 @@ module ActionFigure
 
       private
 
-      def convert_errors(errors, status)
+      def convert_errors(errors, status, prefix = "/data/attributes")
         errors.flat_map do |field, messages|
-          pointer = field.to_sym == :base ? "/data" : "/data/attributes/#{field}"
-          messages.map do |message|
-            {
-              status: status,
-              detail: message,
-              source: { pointer: pointer }
-            }
+          pointer = field.to_sym == :base ? "/data" : "#{prefix}/#{field}"
+
+          if messages.is_a?(Hash)
+            convert_errors(messages, status, pointer)
+          else
+            messages.map do |message|
+              {
+                status: status,
+                detail: message,
+                source: { pointer: pointer }
+              }
+            end
           end
         end
       end

data/lib/action_figure/testing/rspec.rb

@@ -13,6 +13,7 @@ module ActionFigure
     #   RSpec.describe Users::Create do
     #     it "returns ok" do
     #       expect(Users::Create.call(params: ...)).to be_Ok
+    #       expect(Users::Create.call(params: ...)).to have_action_json(status: "success")
     #     end
     #   end
     module RSpec
@@ -39,6 +40,33 @@ module ActionFigure
           end
         end
       end
+
+      # Asserts against +result[:json]+ using +a_hash_including+ (nested matchers allowed).
+      ::RSpec::Matchers.define :have_action_json do |expected_fragment|
+        include ::RSpec::Matchers
+
+        match do |result|
+          @inner_matcher ||= a_hash_including(expected_fragment)
+          next false unless result.is_a?(Hash) && result.key?(:json)
+
+          @inner_matcher.matches?(result[:json])
+        end
+
+        failure_message do |result|
+          if !result.is_a?(Hash)
+            "expected an ActionFigure result hash, got #{result.inspect}"
+          elsif !result.key?(:json)
+            "expected #{result.inspect} to include key :json (ActionFigure render hash)"
+          else
+            "expected result[:json] to #{@inner_matcher.description}"
+          end
+        end
+
+        failure_message_when_negated do |result|
+          @inner_matcher ||= a_hash_including(expected_fragment)
+          "#{result.inspect} was expected not to match #{@inner_matcher.description}"
+        end
+      end
     end
   end
 end

data/lib/action_figure/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActionFigure
-  VERSION = "0.6.0"
+  VERSION = "0.6.2"
 end

data/lib/action_figure.rb

@@ -15,7 +15,17 @@ module ActionFigure
   extend Configuration
   extend FormatRegistry
 
-  class IndeterminantEntryPointError < StandardError; end
+  class IndeterminateEntryPointError < StandardError; end
+
+  # Backwards-compatible alias for the misspelled constant shipped through 0.6.0.
+  # Remove in the next minor release after Unreleased.
+  IndeterminantEntryPointError = IndeterminateEntryPointError
+  deprecate_constant :IndeterminantEntryPointError
+
+  # Raised when an action class defines +initialize+. ActionFigure builds instances with
+  # +new+ and passes no constructor arguments; use keyword arguments on the entry method
+  # or class-level state instead of custom initializers.
+  class InitializationNotSupportedError < StandardError; end
 
   register_formatter(jsend: Formatters::Jsend)
   register_formatter(jsonapi: Formatters::JsonApi)

data/sig/action_figure.rbs

@@ -9,7 +9,13 @@ type ActionFigure::error_hash = Hash[Symbol, Array[String]]
 module ActionFigure
   VERSION: String
 
-  class IndeterminantEntryPointError < StandardError
+  class IndeterminateEntryPointError < StandardError
+  end
+
+  # Deprecated alias for IndeterminateEntryPointError (misspelled constant from <= 0.6.0).
+  IndeterminantEntryPointError: Class
+
+  class InitializationNotSupportedError < StandardError
   end
 
   extend Configuration
@@ -76,12 +82,15 @@ module ActionFigure
       def contract: () -> untyped
     end
 
-    def entry_point_name: () -> Symbol
+    def entry_point_name: () -> Symbol?
     def contract: () -> untyped
     def validated_call: (**untyped kwargs) -> ActionFigure::response
 
     # ActiveSupport::Notifications instrumentation
     module Notifications
+      private
+
+      def notify: () { () -> ActionFigure::response } -> ActionFigure::response
     end
   end
 
@@ -96,6 +105,8 @@ module ActionFigure
       def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
       def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
       def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
     end
 
     # JSend-formatted responses
@@ -108,6 +119,8 @@ module ActionFigure
       def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
       def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
       def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
     end
 
     # JSON:API-formatted responses
@@ -120,6 +133,8 @@ module ActionFigure
       def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
       def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
       def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
 
       # Simple resource serialization for JSON:API
       class Resource
@@ -137,6 +152,8 @@ module ActionFigure
       def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
       def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
       def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
     end
   end
 
@@ -150,6 +167,8 @@ module ActionFigure
       def assert_UnprocessableContent: (ActionFigure::response result, ?String? msg) -> void
       def assert_NotFound: (ActionFigure::response result, ?String? msg) -> void
       def assert_Forbidden: (ActionFigure::response result, ?String? msg) -> void
+      def assert_Conflict: (ActionFigure::response result, ?String? msg) -> void
+      def assert_PaymentRequired: (ActionFigure::response result, ?String? msg) -> void
     end
 
     # RSpec custom matchers (be_Ok, be_Created, etc.)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_figure
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.2
 platform: ruby
 authors:
 - Tad Thorley
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: dry-validation
   requirement: !ruby/object:Gem::Requirement
@@ -29,6 +43,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -61,6 +76,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/phaedryx/action_figure
   source_code_uri: https://github.com/phaedryx/action_figure
+  changelog_uri: https://github.com/phaedryx/action_figure/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -76,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Fully-articulated controller actions
 test_files: []