railsmith 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a20ec84a09c4074cd56944e07f4ea7f14ffab15e8f9fe41d4f288ac3cc2f9ce
-  data.tar.gz: 47e886d32518f52ba779f4ce0727737653b7e719d7b266ca8a2769ab7ff2bb97
+  metadata.gz: e9b32b70ceece070f58ca5699fb4caecc906a4b3204f1fb0f898783272d396d9
+  data.tar.gz: eb1668ea34874567dec4f7a4fbdf56da93a4fad6268f15552e84ecf3fcc5fcc4
 SHA512:
-  metadata.gz: 9c6275d694e51d5bfa1d5dd5f375af5079b0fdd96bb38252f322279df514e3e1e7945840ccf9bba14495b4e55cf7c33a4dfbfefce903402e5fe1c7345cae6984
-  data.tar.gz: 909725e026330771fd81e0b5fd0077f7f92621dc017cda6b882a7e5f276db8be589edab63857823e1c604af9b58a7a968f90f825b78652022c4a90b6f86c8285
+  metadata.gz: 2797fddf8357f2fbe33ac5b99d7a2b621921c53911039b6803d941734747e4688c931328fb6bdf45c4d3b0adffe1ad69088a198b30caff670cc11e8ec2690ee6
+  data.tar.gz: 327b3adb98fafc1de6170663c5655cd18277ae262b80f02d830ebe045843c882f983211e1049d3f4280d14d0a187f85018695f769c680f9b0f5a6929f07e2547

data/CHANGELOG.md

@@ -7,7 +7,241 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
-## [Unreleased]
+## [1.2.0] — 2026-04-08
+
+### Added — Declarative Inputs & Type Coercion
+
+- **`input` DSL** — declare expected parameters with types, defaults, and constraints directly on any `BaseService` subclass:
+
+  ```ruby
+  class UserService < Railsmith::BaseService
+    model User
+    domain :identity
+
+    input :email,    String,   required: true
+    input :age,      Integer,  default: nil
+    input :role,     String,   in: %w[admin member guest], default: "member"
+    input :active,   :boolean, default: true
+    input :metadata, Hash,     default: -> { {} }
+  end
+  ```
+
+- **`Railsmith::BaseService::InputDefinition`** — frozen value object storing each input's `name`, `type`, `required`, `default` (static value or zero-arg lambda), `in_values`, and `transform`.
+
+- **`Railsmith::BaseService::InputRegistry`** — ordered collection of `InputDefinition`s attached to a service class; deep-duped on inheritance so subclasses can extend or override without affecting the parent.
+
+- **`Railsmith::BaseService::TypeCoercion`** — automatic type conversion before validation. Supported target types and strategies:
+
+  | Type | Behaviour |
+  |------|-----------|
+  | `String` | `value.to_s` |
+  | `Integer` | `Integer(value)` — strict; non-numeric strings produce `validation_error` |
+  | `Float` | `Float(value)` — strict |
+  | `BigDecimal` | `BigDecimal(value.to_s)` |
+  | `:boolean` | `"true"/"1"/true → true`, `"false"/"0"/false → false`; other values error |
+  | `Date` | `Date.parse(value.to_s)` |
+  | `DateTime` | `DateTime.parse(value.to_s)` |
+  | `Time` | `Time.parse(value.to_s)` |
+  | `Symbol` | `value.to_sym` |
+  | `Array` | `Array(value)` — wraps scalars |
+  | `Hash` | passthrough; non-hash values produce `validation_error` |
+
+- **`Railsmith::BaseService::InputResolver`** — single-pass pipeline that runs on every `call` when inputs are declared:
+  1. Apply defaults for missing keys
+  2. Coerce types
+  3. Validate required fields
+  4. Validate `in:` constraints
+  5. Apply `transform:` procs
+  6. Filter undeclared keys (security: prevents mass-assignment of unexpected fields)
+
+- **`filter_inputs false`** class-level opt-out — disables undeclared key filtering when needed. Inherited by subclasses.
+
+- **`transform:` option on `input`** — optional zero-arg Proc applied after coercion (e.g. `transform: ->(v) { v.strip.downcase }`).
+
+- **Custom coercions** — register arbitrary type coercers globally:
+
+  ```ruby
+  Railsmith.configure do |c|
+    c.register_coercion(:money, ->(v) { Money.new(v) })
+  end
+  ```
+
+- **`Configuration#register_coercion` / `#custom_coercions`** — storage and lookup for custom type coercers.
+
+- **Input scoping** — when a `model` is declared, inputs describe `params[:attributes]`; for custom (non-model) actions, inputs describe the top-level `params` hash.
+
+- **Inheritance** — subclasses inherit all parent inputs and can add or override them independently.
+
+### Added — `call!` Variant & Error Enhancements
+
+- **`BaseService.call!`** — raising variant of `call`. Identical signature; raises `Railsmith::Failure` instead of returning a failure `Result`. Intended for controller contexts that use `rescue_from`:
+
+  ```ruby
+  # Raises on any failure result; returns the Result on success.
+  UserService.call!(action: :create, params: params, context: ctx)
+  ```
+
+- **`Railsmith::Failure`** — `StandardError` subclass wrapping a failure `Result`. Carries the original structured error so `rescue` / `rescue_from` handlers can inspect it without parsing a string:
+
+  ```ruby
+  rescue Railsmith::Failure => e
+    e.result   # => Railsmith::Result (failure)
+    e.code     # => "validation_error"
+    e.error    # => Railsmith::Errors::ErrorPayload
+    e.meta     # => {}
+    e.message  # => human-readable error message from the payload
+  end
+  ```
+
+- **`Railsmith::ControllerHelpers`** — `ActiveSupport::Concern` for Rails controllers. Include it once in `ApplicationController` to get automatic JSON error responses mapped to standard HTTP statuses:
+
+  ```ruby
+  class ApplicationController < ActionController::API
+    include Railsmith::ControllerHelpers
+  end
+  ```
+
+  Status mapping:
+
+  | Error code | HTTP status |
+  |---|---|
+  | `validation_error` | 422 Unprocessable Entity |
+  | `not_found` | 404 Not Found |
+  | `conflict` | 409 Conflict |
+  | `unauthorized` | 401 Unauthorized |
+  | `unexpected` | 500 Internal Server Error |
+  | _(unknown)_ | 500 Internal Server Error |
+
+  The rendered JSON body is `result.to_h` — same shape as every other Railsmith failure response.
+
+### Added — Association Support
+
+- **`has_many` / `has_one` / `belongs_to` DSL** — declare associations directly on a service class:
+
+  ```ruby
+  class OrderService < Railsmith::BaseService
+    model Order
+    domain :commerce
+
+    has_many   :line_items,       service: LineItemService, dependent: :destroy
+    has_one    :shipping_address, service: AddressService,  dependent: :nullify
+    belongs_to :customer,         service: CustomerService, optional: true
+  end
+  ```
+
+- **`Railsmith::BaseService::AssociationDefinition`** — frozen value object per association, storing `name`, `kind` (`:has_many`, `:has_one`, `:belongs_to`), `service_class`, `foreign_key`, `dependent`, `optional`, and `validate`.
+
+- **`Railsmith::BaseService::AssociationRegistry`** — ordered collection of `AssociationDefinition`s; deep-duped on inheritance so subclasses extend associations without affecting parents.
+
+- **`Railsmith::BaseService::AssociationDsl`** — provides the `has_many`, `has_one`, and `belongs_to` class macros. Foreign keys are auto-inferred when not given:
+  - `has_many` / `has_one`: FK is `"#{parent_model_name.underscore}_id"` on the child (e.g. `order_id`)
+  - `belongs_to`: FK is `"#{association_name}_id"` on this record (e.g. `customer_id`)
+
+- **`includes` DSL** (`Railsmith::BaseService::EagerLoading`) — declare eager loads at the class level; multiple calls are additive:
+
+  ```ruby
+  class OrderService < Railsmith::BaseService
+    model Order
+
+    includes :line_items, :customer
+    includes line_items: [:product, :variant]
+  end
+  ```
+
+  Declared loads are applied automatically in `find` and `list` (via the `base_scope` helper). Custom action overrides are unaffected.
+
+- **`Railsmith::BaseService::NestedWriter`** — handles nested association writes within the parent's open transaction:
+
+  - **Nested create** — pass nested records under the association key in `params`; the FK is injected automatically:
+
+    ```ruby
+    OrderService.call(
+      action: :create,
+      params: {
+        attributes: { total: 99.99, customer_id: 7 },
+        line_items: [
+          { attributes: { product_id: 1, qty: 2, price: 29.99 } },
+          { attributes: { product_id: 5, qty: 1, price: 39.99 } }
+        ],
+        shipping_address: { attributes: { street: "123 Main St", city: "Portland" } }
+      },
+      context: ctx
+    )
+    ```
+
+  - **Nested update** — per-item semantics driven by the presence of `id` and `_destroy`:
+
+    | Item shape | Action |
+    |---|---|
+    | `{ id:, attributes: }` | update via child service |
+    | `{ attributes: }` (no `id`) | create via child service (FK injected) |
+    | `{ id:, _destroy: true }` | destroy via child service |
+
+  - **Cascading destroy** — controlled by the `dependent:` option on the association:
+
+    | Option | Behaviour |
+    |---|---|
+    | `:destroy` | calls child service `destroy` for each associated record |
+    | `:nullify` | calls child service `update` with FK set to `nil` |
+    | `:restrict` | returns `validation_error` failure if any children exist |
+    | `:ignore` | does nothing (default; relies on DB-level constraints) |
+
+  All nested operations run within the parent's transaction — any failure triggers a full rollback of both parent and nested writes.
+
+- **Association-aware `bulk_create`** — bulk items now support the nested format alongside the existing flat format:
+
+  ```ruby
+  # Flat (existing, unchanged)
+  items: [{ name: "A" }, { name: "B" }]
+
+  # Nested (new)
+  items: [
+    { attributes: { total: 50.00 }, line_items: [{ attributes: { product_id: 1, qty: 1 } }] },
+    { attributes: { total: 75.00 }, line_items: [{ attributes: { product_id: 2, qty: 1 } }] }
+  ]
+  ```
+
+  When no associations are declared the bulk format and behavior are identical to 1.1.0.
+
+### Added — Generator Updates
+
+- **`--inputs` flag on `railsmith:model_service`** — generates `input` DSL declarations in the scaffolded service. Two modes:
+
+  - **Auto-introspect** (`--inputs` with no values): reads `Model.columns_hash` and emits one `input` declaration per non-system column (`id`, `created_at`, `updated_at` are excluded). Requires the model to be loaded at generation time; prints a warning and skips gracefully when it isn't.
+  - **Explicit** (`--inputs=email:string:required name:string age:integer`): generates the listed inputs without touching the model. Format per spec: `name:type[:required]`.
+
+  Supported type tokens and their mapped Ruby types:
+
+  | Token | Ruby type |
+  |---|---|
+  | `string`, `text` | `String` |
+  | `integer`, `bigint` | `Integer` |
+  | `float` | `Float` |
+  | `decimal` | `BigDecimal` |
+  | `boolean` | `:boolean` |
+  | `date` | `Date` |
+  | `datetime`, `timestamp` | `DateTime` |
+  | `time` | `Time` |
+  | `json`, `jsonb`, `hstore` | `Hash` |
+  | _(unknown)_ | `String` |
+
+- **`--associations` flag on `railsmith:model_service`** — introspects `Model.reflect_on_all_associations` and emits `has_many`, `has_one`, and `belongs_to` declarations plus an `includes` line covering all associations. Prints a warning and skips when the model can't be loaded. Adds `# TODO: Define XxxService` comments for associated service classes that are not yet defined.
+
+- **Updated `model_service.rb.tt` template** — renders optional `# -- Inputs --` and `# -- Associations --` sections when the respective flags are used. Sections are omitted entirely when the flags are absent, preserving the existing output for services generated without them.
+
+### Deprecated
+
+- `required_keys:` keyword on `validate()` — emits a deprecation warning at runtime. Migrate to the `input` DSL with `required: true`. The parameter continues to work for services that do not use the `input` DSL.
+
+### Fixed
+
+- Architecture checker `MissingServiceUsageChecker` recognizes flat domain operation calls (e.g. `Billing::Invoices::Create.call`) without an `Operations::` segment, matching the 1.1.0 generator defaults.
+- `ArchReport` text footer and JSON summary reflect fail-on vs warn-only mode (`fail_on_arch_violations`).
+
+### Changed
+
+- `railsmith:install` creates `app/services` only (no empty `app/services/operations/`).
+- Cross-domain warning payloads include `log_json_line` and `log_kv_line` from `CrossDomainWarningFormatter`.
 
 ---
 
@@ -117,6 +351,6 @@ First stable release. Public DSL and result contract are now frozen.
 
 Internal bootstrap release. Gem skeleton, CI baseline, and initial service scaffolding. Not intended for production use.
 
-[Unreleased]: https://github.com/samaswin/railsmith/compare/v1.1.0...HEAD
+[1.2.0]: https://github.com/samaswin/railsmith/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/samaswin/railsmith/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/samaswin/railsmith/releases/tag/v1.0.0

data/MIGRATION.md

@@ -1,5 +1,245 @@
 # Migration Guide
 
+## Upgrading from 1.1.0 to 1.2.0
+
+All changes in 1.2.0 are **additive and backward-compatible**. Every service written for 1.1.0 continues to work without modification.
+
+---
+
+### Input DSL (additive, replaces `required_keys:`)
+
+The `input` class macro declares expected parameters with types, defaults, and constraints. It is entirely opt-in — services without `input` declarations behave identically to 1.1.0.
+
+```ruby
+class UserService < Railsmith::BaseService
+  model User
+  domain :identity
+
+  input :email,    String,   required: true
+  input :age,      Integer,  default: nil
+  input :role,     String,   in: %w[admin member guest], default: "member"
+  input :active,   :boolean, default: true
+  input :metadata, Hash,     default: -> { {} }
+end
+```
+
+When inputs are declared:
+
+- Types are coerced automatically (string `"42"` → integer `42`, etc.)
+- Required fields that are missing or `nil` return a `validation_error` result
+- Only declared keys are forwarded to the action (undeclared keys are silently dropped)
+- Defaults are applied before the action runs
+
+**`required_keys:` is deprecated.** If you currently use `validate(params, required_keys: [:email])`, migrate to `input :email, String, required: true`. The `required_keys:` keyword continues to work but emits a deprecation warning. It will be removed in a future major release.
+
+```ruby
+# Before (deprecated, still works with warning)
+def create
+  val = validate(params, required_keys: [:email, :name])
+  return val if val.failure?
+  super
+end
+
+# After
+input :email, String, required: true
+input :name,  String, required: true
+```
+
+**No migration required.** Existing services are unaffected.
+
+---
+
+### `call!` and `ControllerHelpers` (additive)
+
+`BaseService.call!` is a new class method with the same signature as `call`. It raises `Railsmith::Failure` instead of returning a failure result, for use in controllers that prefer `rescue_from`.
+
+```ruby
+# Raises Railsmith::Failure on any failure; returns Result on success
+UserService.call!(action: :create, params: { attributes: user_params }, context: ctx)
+```
+
+`Railsmith::ControllerHelpers` is a new `ActiveSupport::Concern` for Rails controllers. Include it once in `ApplicationController` to handle all `Railsmith::Failure` exceptions with standard JSON responses and HTTP status codes:
+
+```ruby
+class ApplicationController < ActionController::API
+  include Railsmith::ControllerHelpers
+end
+```
+
+| Error code | HTTP status |
+|------------|-------------|
+| `validation_error` | 422 Unprocessable Entity |
+| `not_found` | 404 Not Found |
+| `conflict` | 409 Conflict |
+| `unauthorized` | 401 Unauthorized |
+| `unexpected` | 500 Internal Server Error |
+
+Both `call!` and `ControllerHelpers` are entirely opt-in. All existing `call` usage is unaffected.
+
+See [docs/call-bang.md](docs/call-bang.md) for detailed usage.
+
+---
+
+### Association DSL (additive)
+
+`has_many`, `has_one`, and `belongs_to` are new class-level macros for declaring associations on a service. They are entirely opt-in — services without association declarations behave identically to 1.1.0.
+
+```ruby
+class OrderService < Railsmith::BaseService
+  model Order
+  domain :commerce
+
+  has_many   :line_items,       service: LineItemService, dependent: :destroy
+  has_one    :shipping_address, service: AddressService,  dependent: :nullify
+  belongs_to :customer,         service: CustomerService, optional: true
+end
+```
+
+**Options for `has_many` and `has_one`:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `service:` | Class | required | service class for the associated records |
+| `foreign_key:` | Symbol | inferred | FK column on the child; inferred as `#{parent_model}_id` |
+| `dependent:` | Symbol | `:ignore` | cascade behaviour on parent destroy (see Cascading Destroy below) |
+| `validate:` | Boolean | `true` | validate nested records |
+
+**Options for `belongs_to`:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `service:` | Class | required | service class for the parent record |
+| `foreign_key:` | Symbol | inferred | FK column on this record; inferred as `#{association_name}_id` |
+| `optional:` | Boolean | `false` | skip presence validation |
+
+**No migration required.** Existing services are unaffected.
+
+---
+
+### Eager Loading DSL (additive)
+
+The `includes` class macro declares eager loads applied automatically to `find` and `list`. Multiple calls are additive.
+
+```ruby
+class OrderService < Railsmith::BaseService
+  model Order
+
+  includes :line_items, :customer
+  includes line_items: [:product, :variant]   # merged with the call above
+end
+```
+
+Before adding `includes`, if you had a custom `find_record` override or a `list` override that applied its own `model_class.includes(...)`, those overrides are **unaffected** — the default `base_scope` applies only to the built-in `find` and `list` actions.
+
+If your custom action already calls `find_record(model_klass, id)` it will now benefit from declared eager loads automatically. If this is unwanted, keep calling `model_klass.find_by(id:)` directly.
+
+**No migration required.** Opt-in at your own pace.
+
+---
+
+### Nested Writes (additive)
+
+When associations are declared, the `create` and `update` actions accept nested records under the association key in `params`. No change is required in services that do not pass nested params — the guards check `params` for association keys and skip silently when none are present.
+
+#### Nested create
+
+```ruby
+OrderService.call(
+  action: :create,
+  params: {
+    attributes: { total: 99.99, customer_id: 7 },
+    line_items: [
+      { attributes: { product_id: 1, qty: 2, price: 29.99 } },
+      { attributes: { product_id: 5, qty: 1, price: 39.99 } }
+    ],
+    shipping_address: { attributes: { street: "123 Main St", city: "Portland" } }
+  },
+  context: ctx
+)
+```
+
+The parent FK (`order_id`) is injected into each child's attributes automatically — you do not pass it.
+
+All child writes run inside the parent's open transaction. Any failure rolls back the entire operation including the parent record.
+
+#### Nested update
+
+Pass nested items under the association key in `update` params. Per-item semantics:
+
+| Item shape | Action taken |
+|---|---|
+| `{ id:, attributes: }` | update the existing child record |
+| `{ attributes: }` (no `id`) | create a new child record (FK injected) |
+| `{ id:, _destroy: true }` | destroy the child record |
+
+```ruby
+OrderService.call(
+  action: :update,
+  params: {
+    id: 42,
+    attributes: { total: 109.99 },
+    line_items: [
+      { id: 1, attributes: { qty: 3 } },        # update
+      { attributes: { product_id: 9, qty: 1 } }, # create
+      { id: 2, _destroy: true }                  # destroy
+    ]
+  },
+  context: ctx
+)
+```
+
+**No migration required.** Existing `update` calls without nested keys work exactly as before.
+
+---
+
+### Cascading Destroy (additive)
+
+When `has_many` or `has_one` is declared with a `dependent:` option other than `:ignore`, the `destroy` action handles associated records through their service before deleting the parent.
+
+| `dependent:` | Behaviour |
+|---|---|
+| `:destroy` | calls child service `destroy` for each associated record |
+| `:nullify` | calls child service `update` with FK set to `nil` |
+| `:restrict` | returns `validation_error` failure if any children exist (parent is not deleted) |
+| `:ignore` | does nothing — default, matches 1.1.0 behaviour |
+
+The default is `:ignore` so no existing `destroy` call changes behaviour unless you explicitly add a `dependent:` option to an association.
+
+All cascading operations run inside the parent's transaction. Any failure rolls back the entire destroy.
+
+---
+
+### `bulk_create` — extended item format (backward-compatible)
+
+`bulk_create` now accepts items in either the existing flat format or a new nested format when associations are declared.
+
+```ruby
+# Flat format — unchanged, still works exactly as before
+items: [{ name: "A" }, { name: "B" }]
+
+# Nested format — new, used when associations are declared
+items: [
+  { attributes: { total: 50.00 }, line_items: [{ attributes: { product_id: 1, qty: 1 } }] },
+  { attributes: { total: 75.00 }, line_items: [{ attributes: { product_id: 2, qty: 1 } }] }
+]
+```
+
+The two formats are detected automatically by the presence of an `attributes:` key in the item hash. Existing bulk calls using the flat format continue to work without any change.
+
+---
+
+### Upgrade steps for 1.1.0 → 1.2.0
+
+1. Update `Gemfile`: `gem "railsmith", "~> 1.2"`
+2. Run `bundle install`.
+3. Run `bundle exec rspec` — all existing specs should pass with zero changes.
+4. Opt-in to the `input` DSL on services where you want type coercion and validation (Phase 1, already available since the unreleased branch).
+5. Opt-in to `has_many` / `has_one` / `belongs_to` on services that need nested writes or cascading destroy.
+6. Opt-in to `includes` on services that need eager loading on `find` and `list`.
+7. Deploy.
+
+---
+
 ## Upgrading from 1.0.0 to 1.1.0
 
 ### Ruby >= 3.1 (non-breaking)
@@ -363,7 +603,7 @@ Add any missing keys to `config/initializers/railsmith.rb`. All keys have safe d
 ```ruby
 Railsmith.configure do |config|
   config.warn_on_cross_domain_calls = true   # default: true
-  config.strict_mode = false                  # default: false (reserved for v1.2)
+  config.strict_mode = false                  # default: false; when true, +on_cross_domain_violation+ runs on each cross-domain call
   config.fail_on_arch_violations = false      # default: false
   config.cross_domain_allowlist = []          # default: []
   config.on_cross_domain_violation = nil      # default: nil (no-op)

data/README.md

@@ -72,6 +72,101 @@ result.error.to_h      # => { code: "not_found", message: "User not found", deta
 
 ---
 
+## Declarative Inputs
+
+Declare expected parameters with types, defaults, and constraints using the `input` DSL. Railsmith coerces, validates, and filters params automatically before the action runs.
+
+```ruby
+class UserService < Railsmith::BaseService
+  model User
+  domain :identity
+
+  input :email,    String,   required: true, transform: ->(v) { v.strip.downcase }
+  input :age,      Integer,  default: nil
+  input :role,     String,   in: %w[admin member guest], default: "member"
+  input :active,   :boolean, default: true
+  input :metadata, Hash,     default: -> { {} }
+end
+```
+
+- **Type coercion** — strings to integers, booleans, dates, and more
+- **Validation** — required fields, allowed value lists, coercion failures all return structured `validation_error` results
+- **Input filtering** — only declared keys reach the action (mass-assignment protection)
+- **Inheritance** — subclasses inherit parent inputs and can extend or override independently
+
+See [docs/inputs.md](docs/inputs.md) for the full reference.
+
+---
+
+## Association Support
+
+Declare associations at the service level for eager loading, nested CRUD, and cascading destroy.
+
+```ruby
+class OrderService < Railsmith::BaseService
+  model Order
+  domain :commerce
+
+  has_many   :line_items,       service: LineItemService, dependent: :destroy
+  has_one    :shipping_address, service: AddressService,  dependent: :nullify
+  belongs_to :customer,         service: CustomerService, optional: true
+
+  includes :line_items, :customer
+end
+```
+
+**Nested create** — pass associated records in `params`; the foreign key is injected automatically:
+
+```ruby
+OrderService.call(
+  action: :create,
+  params: {
+    attributes: { total: 99.99, customer_id: 7 },
+    line_items: [
+      { attributes: { product_id: 1, qty: 2, price: 29.99 } }
+    ]
+  },
+  context: ctx
+)
+```
+
+All nested writes run in the parent's transaction. Any failure rolls back everything.
+
+See [docs/associations.md](docs/associations.md) for the full reference.
+
+---
+
+## `call!` — Raising Variant
+
+`call!` raises `Railsmith::Failure` instead of returning a failure result. Use it in controllers with `rescue_from`:
+
+```ruby
+class ApplicationController < ActionController::API
+  include Railsmith::ControllerHelpers
+  # Catches Railsmith::Failure and renders JSON with the correct HTTP status
+end
+
+class UsersController < ApplicationController
+  def create
+    result = UserService.call!(action: :create, params: { attributes: user_params }, context: ctx)
+    render json: result.value, status: :created
+  end
+end
+```
+
+`Railsmith::Failure` carries the full structured result for inspection in rescue handlers:
+
+```ruby
+rescue Railsmith::Failure => e
+  e.code    # => "validation_error"
+  e.result  # => Railsmith::Result (failure)
+end
+```
+
+See [docs/call-bang.md](docs/call-bang.md) for the full reference.
+
+---
+
 ## Generators
 
 | Command | Output |
@@ -79,6 +174,8 @@ result.error.to_h      # => { code: "not_found", message: "User not found", deta
 | `rails g railsmith:install` | Initializer + service directories |
 | `rails g railsmith:domain Billing` | `app/domains/billing.rb` + subdirectories |
 | `rails g railsmith:model_service User` | `app/services/user_service.rb` |
+| `rails g railsmith:model_service User --inputs` | Service with `input` DSL (introspects model columns) |
+| `rails g railsmith:model_service Order --associations` | Service with association DSL (introspects model associations) |
 | `rails g railsmith:model_service Billing::Invoice --domain=Billing` | `app/domains/billing/services/invoice_service.rb` |
 | `rails g railsmith:operation Billing::Invoices::Create` | `app/domains/billing/invoices/create.rb` |
 
@@ -164,7 +261,7 @@ ctx = Railsmith::Context.new(domain: :billing, request_id: "req-abc")
 Billing::Services::InvoiceService.call(action: :create, params: { ... }, context: ctx)
 ```
 
-When the context domain differs from a service's declared `domain`, Railsmith emits a `cross_domain.warning.railsmith` instrumentation event.
+When the context domain differs from a service's declared `domain`, Railsmith emits a `cross_domain.warning.railsmith` instrumentation event. The payload includes `log_json_line` and `log_kv_line` (from `Railsmith::CrossDomainWarningFormatter`) for structured logging; when `strict_mode` is true, `on_cross_domain_violation` receives the same payload.
 
 Configure enforcement in `config/initializers/railsmith.rb`:
 
@@ -214,9 +311,12 @@ See [Migration](MIGRATION.md#embedding-architecture-checks-from-ruby) for option
 ## Documentation
 
 - [Quickstart](docs/quickstart.md) — install, generate, first call
-- [Cookbook](docs/cookbook.md) — CRUD, bulk, domain context, error mapping, observability
+- [Inputs](docs/inputs.md) — declarative input DSL, type coercion, filtering, custom coercions
+- [Associations](docs/associations.md) — association DSL, eager loading, nested CRUD, cascading destroy
+- [call!](docs/call-bang.md) — raising variant, controller integration, `ControllerHelpers`
+- [Cookbook](docs/cookbook.md) — CRUD, bulk, inputs, associations, domain context, error mapping, observability
 - [Legacy Adoption Guide](docs/legacy-adoption.md) — incremental migration strategy
-- [Migration](MIGRATION.md) — upgrading from 1.0.x to 1.1.x (and earlier releases)
+- [Migration](MIGRATION.md) — upgrading from 1.0.x to 1.2.x (and earlier releases)
 - [Changelog](CHANGELOG.md)
 
 ---