u-case 5.3.1 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 936bb237d3decf217151d48e7f32339ac698d65bde22930a05e4b90e92d760ea
-  data.tar.gz: e9ecc10a25c778a1393f803bd32ad6ebf7481c1a9144a4d0ac0fce843aed53d2
+  metadata.gz: 4e57208798d170fbccde7b54f5beb6220cecbfd70c3983fedcb701070a73c7bc
+  data.tar.gz: e4a0c472d1fd6edacf6ac3495d902ca851a88f5420360b708bdf2f204818cc1a
 SHA512:
-  metadata.gz: 5a17f2832229d00b96976ebd9d75053b2a0790625ebc8323e2d2def3d7f90d8aa78a255c834a53e7dcf88b578c9c7ba294a1097b317d0a0f74a579f1c29986a4
-  data.tar.gz: 5a357a9a1cbcd6487c62259f85316304348171de648d1bdf35193b92a2952bfc9a51d98d4e16f0572eb7d4e64e12d1c511e161235b3a092176712abcc5e87157
+  metadata.gz: 154ce36f3efefa81e8e0dcc191cfd25396a7ad0b431f6d2a8190974036ed21f70faa617cc6834569f7fe02855b712abb33dca1da44285913c578ff73cc7cdfcc
+  data.tar.gz: 20f5e74caf9b58ae935bb39dc9780fd7bcfe21e68f4adbec162cff797284939067b2e254e790a2eb17ac8de3ce7a30460af5908170ba136730fa94b784f84a87

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 > **Note:** This gem was originally published as `u-service` (versions 0.1.0 – 1.0.0) and renamed to `u-case` starting with `u-case 1.0.0` on 2019-09-15.
 
+## [5.5.0] - 2026-05-24
+### Added
+- `Micro::Case.results { |on| ... }` macro to declare a results contract — the allowed `Success`/`Failure` types and the result keys each one requires. `Success(...)` / `Failure(...)` calls that use an undeclared type now raise `Micro::Case::Error::UnexpectedResultType`; calls missing a declared required key raise `Micro::Case::Error::MissingResultKeys`. Use cases without a `results` block keep their previous unrestricted behavior. The check routes through `Micro::Case::Check#results_contract!`, so it is also bypassed when `config.disable_runtime_checks = true` (closes #22). Carve-outs so contracts don't break neighbouring features:
+  - Framework-generated `__failure_from_attributes_errors` (the auto-failure produced when `accept:`/`reject:` or ActiveModel validation rejects an input) bypasses the contract — it goes directly to `__set__` rather than through `Failure(...)` — so combining `results` with attribute validation no longer requires declaring `:invalid_attributes`.
+  - Rescued exceptions in `Micro::Case::Safe` (which produce `Failure(result: exception)`) bypass the contract.
+  - Result hashes with `String` keys are matched against the contract's symbolised required keys — `Success(result: { 'value' => 1 })` satisfies `result: [:value]`, mirroring `Result`'s own tolerance for either key type.
+  - Non-`Hash` / non-`Symbol` `result:` arguments fall through to the existing `Micro::Case::Error::InvalidResult` ("must be a Hash") instead of being misreported as missing keys.
+  - Non-`Symbol` `type` arguments fall through to `Micro::Case::Error::InvalidResultType` instead of being misreported as undeclared.
+  - `Micro::Case.results` raises `ArgumentError` when called on the abstract base class itself, so a stray declaration cannot leak a contract to every subclass in the process.
+
+## [5.4.0] - 2026-05-24
+### Added
+- `Micro::Case.config.disable_runtime_checks` config (default `false`) to skip the gem's internal argument/contract checks for better performance in production. All checks are consolidated in `Micro::Case::Check::Enabled` (the default) and `Micro::Case::Check::Disabled` (no-ops with the same signature); the active module is swapped via `Micro::Case.check`. Measured throughput win is JIT-dependent: within noise on stock Ruby (no JIT), ~3–5% on Ruby 3.2 +YJIT, ~4–7% on Ruby 4.0 +PRISM (see `benchmarks/perfomance/runtime_checks/compare.rb`). Closes #45.
+- `benchmarks/perfomance/runtime_checks/` — per-mode subprocess benchmark (`checks_enabled.rb`, `checks_disabled.rb`, `compare.rb`) demonstrating the toggle's perf effect across Ruby versions and JIT modes.
+
 ## [5.3.1] - 2026-05-23
 ### Added
 - This `CHANGELOG.md`, covering the full history of the gem (from `u-service 0.1.0` through `u-case 5.3.1`) following the [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) spec.
@@ -463,6 +478,8 @@ First release under the `u-case` name (renamed from `u-service`).
 - `Micro::Service::Result` with `Success`/`Failure` factories and helper methods for returning typed results from services.
 - Runtime dependency on `u-attributes` for service input declaration.
 
+[5.5.0]: https://github.com/serradura/u-case/compare/v5.4.0...v5.5.0
+[5.4.0]: https://github.com/serradura/u-case/compare/v5.3.1...v5.4.0
 [5.3.1]: https://github.com/serradura/u-case/compare/v5.3.0...v5.3.1
 [5.3.0]: https://github.com/serradura/u-case/compare/v5.2.1...v5.3.0
 [5.2.1]: https://github.com/serradura/u-case/compare/v5.2.0...v5.2.1

data/CLAUDE.md

@@ -90,8 +90,55 @@ Both files are user-facing — keep them in sync with the code:
 - **`README.md` and `README.pt-BR.md`**: the **Documentation** table and the
   **Compatibility** table at the top reference the latest released version
   and its dependency bounds. Update both files together — they are
-  translations of each other and must stay in lockstep. If you change a
-  documented API, update both READMEs in the same commit.
+  translations of each other and must stay in lockstep. Any user-visible
+  API change requires a README update in the same commit:
+  - **New public API** (new macro, new module-level method, new public
+    instance method, new error class users can rescue, new config option) —
+    add or extend the relevant section in both READMEs with an example.
+  - **Changed documented API** — update the existing section in both
+    READMEs to match the new behavior.
+  - **Removed/deprecated API** — remove or mark the section in both
+    READMEs.
+  - Pure internal refactors, CI tweaks, and test-only changes don't need
+    README updates.
+
+## Internal argument checks live in `Micro::Case::Check`
+
+Every internal argument/contract check that runs inside the gem (type
+guards, "is this a `Micro::Case`?", "is this a `Symbol`?", "are these
+flow args valid?", etc.) lives in `lib/micro/case/check.rb`, split across
+two modules with **identical method signatures**:
+
+- `Micro::Case::Check::Enabled` — the default; raises the curated
+  `Micro::Case::Error::*` exceptions.
+- `Micro::Case::Check::Disabled` — no-ops (the matching method just
+  `return`s; passthrough methods return their input unchanged).
+
+The active one is referenced as `Micro::Case.check`, swapped by
+`config.disable_runtime_checks = true/false` (see PR #145 / issue #45).
+
+### When you add a new internal check, you must:
+
+1. **Add the method to BOTH modules.** Keep the signature identical.
+   The `Enabled` side does the real work; the `Disabled` side is a
+   no-op (or passthrough for `hash!`-style coercions).
+2. **Route the call site through `Micro::Case.check.<method>!(...)`.**
+   Don't `raise ... unless ...` inline — that bypasses the toggle and
+   leaks the check into the disabled-path performance budget.
+3. **Cover both modes in a test.** Mirror the pattern in
+   `test/micro/case/disable_runtime_checks_test.rb`: one test that the
+   `Enabled` side raises, one that the `Disabled` side does not.
+4. **Avoid extra allocation on the call site.** If the curated
+   exception needs dynamic params (a class name, a context string),
+   pass the raw strings/values into the check method and construct the
+   exception inside `Enabled` (only on the raise path). Don't build the
+   exception before calling — that defeats the perf rationale of the
+   `Disabled` side.
+
+This is the only place where new gem-internal checks belong. Inline
+`raise … unless …` inside the runtime call path is a regression of
+this design — flag it during review and move the check into
+`Micro::Case::Check`.
 
 ## Bumping the version
 

data/README.md

@@ -27,7 +27,7 @@ The main project goals are:
 Version   | Documentation
 --------- | -------------
 unreleased| https://github.com/serradura/u-case/blob/main/README.md
-5.3.1     | https://github.com/serradura/u-case/blob/v5.x/README.md
+5.5.0     | https://github.com/serradura/u-case/blob/v5.x/README.md
 4.5.1     | https://github.com/serradura/u-case/blob/v4.x/README.md
 
 > **Note:** Você entende português? 🇧🇷 🇵🇹 Verifique o [README traduzido em pt-BR](https://github.com/serradura/u-case/blob/main/README.pt-BR.md).
@@ -42,6 +42,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
     - [What are the default result types?](#what-are-the-default-result-types)
     - [How to define custom result types?](#how-to-define-custom-result-types)
     - [Is it possible to define a custom type without a result data?](#is-it-possible-to-define-a-custom-type-without-a-result-data)
+    - [How to declare a results contract?](#how-to-declare-a-results-contract)
     - [How to use the result hooks?](#how-to-use-the-result-hooks)
     - [Why the hook usage without a defined type exposes the result itself?](#why-the-hook-usage-without-a-defined-type-exposes-the-result-itself)
       - [Using decomposition to access the result data and type](#using-decomposition-to-access-the-result-data-and-type)
@@ -90,7 +91,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
 | u-case           | branch | ruby     | activemodel    | u-attributes   |
 | ---------------- | ------ | -------- | -------------- | -------------- |
 | unreleased       | main   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
-| 5.3.1            | v5.x   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
+| 5.5.0            | v5.x   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
 | 5.1.0            | v5.x   | >= 2.7   | >= 6.0         | >= 2.7, < 4.0  |
 | 4.5.1            | v4.x   | >= 2.2.0 | >= 3.2, <= 8.1 | >= 2.7, < 3.0  |
 
@@ -335,6 +336,58 @@ result.use_case.attributes # {"a"=>2, "b"=>"2"}
 
 [⬆️ Back to Top](#table-of-contents-)
 
+#### How to declare a results contract?
+
+Answer: Use the `results do |on| ... end` macro to declare which result types your use case can return, and which keys each one requires. When a contract is declared, `Success(...)` / `Failure(...)` calls that use an undeclared type raise `Micro::Case::Error::UnexpectedResultType`, and calls that omit a declared required key raise `Micro::Case::Error::MissingResultKeys`.
+
+```ruby
+class Divide < Micro::Case
+  attributes :a, :b
+
+  results do |on|
+    on.failure(:attributes_must_be_numbers)
+    on.failure(:division_by_zero)
+
+    on.success(result: [:division])
+  end
+
+  def call!
+    return Failure(:attributes_must_be_numbers) unless Kind.of?(Numeric, a, b)
+    return Failure(:division_by_zero) if b == 0
+
+    Success result: { division: a / b }
+  end
+end
+
+Divide.call(a: 10, b: 2).data # => { division: 5 }
+Divide.call(a: 10, b: 0).type # => :division_by_zero
+Divide.call(a: 'x', b: 2).type # => :attributes_must_be_numbers
+```
+
+A type passed to `on.success` / `on.failure` without a `result:` argument declares the type with no required keys (any payload — including the implicit `{ type => true }` from `Failure(:my_type)` — is accepted). When `result: [:key1, :key2]` is given, those keys must be present in the result hash; extra keys are allowed.
+
+```ruby
+class Wrong < Micro::Case
+  results do |on|
+    on.success(result: [:value])
+    on.failure(:known)
+  end
+
+  def call!
+    Success(:other, result: { value: 1 })   # raises Micro::Case::Error::UnexpectedResultType
+    # Success(result: { wrong: 1 })         # raises Micro::Case::Error::MissingResultKeys
+    # Failure(:other)                       # raises Micro::Case::Error::UnexpectedResultType
+  end
+end
+```
+
+Notes:
+- Use cases without a `results` block keep their previous unrestricted behavior — the contract is opt-in.
+- Subclasses inherit the parent's contract.
+- Rescued exceptions in `Micro::Case::Safe` (which produce `Failure(result: exception)` automatically) bypass the contract.
+
+[⬆️ Back to Top](#table-of-contents-)
+
 #### How to use the result hooks?
 
 As [mentioned earlier](#microcaseresult---what-is-a-use-case-result), the `Micro::Case::Result` has two methods to improve the application flow control. They are: `#on_success`, `on_failure`.
@@ -1256,9 +1309,22 @@ Micro::Case.config do |config|
   #   - Calling `Micro::Cases.safe_flow(...)`
   #   - Calling `Micro::Case::Result#on_exception`
   config.disable_safe_features = false
+
+  # Use to skip the gem's internal argument/contract checks (e.g., "is this a
+  # Micro::Case?", "is the result type a Symbol?", "is the use case a kind of
+  # Micro::Case?"). Set to `true` in production for a small performance boost
+  # once your code paths are exercised by your test suite. The trade-off is that
+  # incorrect usage will surface as confusing downstream errors instead of the
+  # gem's curated ones (e.g. `Micro::Case::Error::InvalidUseCase`).
+  config.disable_runtime_checks = false
 end
 ```
 
+All checks are consolidated in `Micro::Case::Check::Enabled` (the default).
+Toggling `disable_runtime_checks = true` swaps `Micro::Case.check` to
+`Micro::Case::Check::Disabled` — a module with the same signature whose
+methods are no-ops — so the validations themselves are not run on each call.
+
 [⬆️ Back to Top](#table-of-contents-)
 
 ## Benchmarks

data/README.pt-BR.md

@@ -27,7 +27,7 @@ Principais objetivos deste projeto:
 Versão    | Documentação
 --------- | -------------
 unreleased| https://github.com/serradura/u-case/blob/main/README.md
-5.3.1     | https://github.com/serradura/u-case/blob/v5.x/README.md
+5.5.0     | https://github.com/serradura/u-case/blob/v5.x/README.md
 4.5.1     | https://github.com/serradura/u-case/blob/v4.x/README.md
 
 ## Índice <!-- omit in toc -->
@@ -40,6 +40,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
     - [O que são os tipos de resultados?](#o-que-são-os-tipos-de-resultados)
     - [Como definir tipos customizados de resultados?](#como-definir-tipos-customizados-de-resultados)
     - [É possível definir um tipo sem definir os dados do resultado?](#é-possível-definir-um-tipo-sem-definir-os-dados-do-resultado)
+    - [Como declarar um contrato de resultados?](#como-declarar-um-contrato-de-resultados)
     - [Como utilizar os hooks dos resultados?](#como-utilizar-os-hooks-dos-resultados)
     - [Por que o hook sem um tipo definido expõe o próprio resultado?](#por-que-o-hook-sem-um-tipo-definido-expõe-o-próprio-resultado)
       - [Usando decomposição para acessar os dados e tipo do resultado](#usando-decomposição-para-acessar-os-dados-e-tipo-do-resultado)
@@ -88,7 +89,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
 | u-case           | branch | ruby     | activemodel    | u-attributes   |
 | ---------------- | ------ | -------- | -------------- | -------------- |
 | unreleased       | main   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
-| 5.3.1            | v5.x   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
+| 5.5.0            | v5.x   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
 | 5.1.0            | v5.x   | >= 2.7   | >= 6.0         | >= 2.7, < 4.0  |
 | 4.5.1            | v4.x   | >= 2.2.0 | >= 3.2, <= 8.1 | >= 2.7, < 3.0  |
 
@@ -333,6 +334,58 @@ result.use_case.attributes # {"a"=>2, "b"=>"2"}
 
 [⬆️ Voltar para o índice](#índice-)
 
+#### Como declarar um contrato de resultados?
+
+Resposta: Utilize a macro `results do |on| ... end` para declarar quais tipos de resultado o caso de uso pode retornar e quais chaves cada um exige. Quando há um contrato declarado, chamadas a `Success(...)` / `Failure(...)` que usem um tipo não declarado levantam `Micro::Case::Error::UnexpectedResultType`, e chamadas que omitam uma chave obrigatória declarada levantam `Micro::Case::Error::MissingResultKeys`.
+
+```ruby
+class Divide < Micro::Case
+  attributes :a, :b
+
+  results do |on|
+    on.failure(:attributes_must_be_numbers)
+    on.failure(:division_by_zero)
+
+    on.success(result: [:division])
+  end
+
+  def call!
+    return Failure(:attributes_must_be_numbers) unless Kind.of?(Numeric, a, b)
+    return Failure(:division_by_zero) if b == 0
+
+    Success result: { division: a / b }
+  end
+end
+
+Divide.call(a: 10, b: 2).data # => { division: 5 }
+Divide.call(a: 10, b: 0).type # => :division_by_zero
+Divide.call(a: 'x', b: 2).type # => :attributes_must_be_numbers
+```
+
+Um tipo declarado em `on.success` / `on.failure` sem o argumento `result:` é aceito sem chaves obrigatórias (qualquer payload — inclusive o implícito `{ tipo => true }` de `Failure(:meu_tipo)` — é aceito). Quando `result: [:chave_1, :chave_2]` é informado, essas chaves precisam estar presentes no hash de resultado; chaves extras são permitidas.
+
+```ruby
+class Wrong < Micro::Case
+  results do |on|
+    on.success(result: [:value])
+    on.failure(:known)
+  end
+
+  def call!
+    Success(:other, result: { value: 1 })   # levanta Micro::Case::Error::UnexpectedResultType
+    # Success(result: { wrong: 1 })         # levanta Micro::Case::Error::MissingResultKeys
+    # Failure(:other)                       # levanta Micro::Case::Error::UnexpectedResultType
+  end
+end
+```
+
+Notas:
+- Casos de uso sem o bloco `results` mantêm o comportamento anterior sem restrições — o contrato é opt-in.
+- Subclasses herdam o contrato declarado na classe pai.
+- Exceções capturadas em `Micro::Case::Safe` (que geram `Failure(result: exception)` automaticamente) são exemptas do contrato.
+
+[⬆️ Voltar para o índice](#índice-)
+
 #### Como utilizar os hooks dos resultados?
 
 Como [mencionando anteriormente](#microcaseresult---o-que-é-o-resultado-de-um-caso-de-uso), o `Micro::Case::Result` tem dois métodos para melhorar o controle do fluxo da aplicação. São eles:
@@ -1257,9 +1310,24 @@ Micro::Case.config do |config|
   #   - Chamar `Micro::Cases.safe_flow(...)`
   #   - Chamar `Micro::Case::Result#on_exception`
   config.disable_safe_features = false
+
+  # Use para pular as verificações internas de argumento/contrato da gem (por
+  # exemplo, "isto é um Micro::Case?", "o tipo do resultado é um Symbol?",
+  # "o use case é um tipo de Micro::Case?"). Defina `true` em produção para
+  # um pequeno ganho de performance depois que seus caminhos de código já
+  # estiverem cobertos pela sua suíte de testes. O custo é que usos
+  # incorretos vão aparecer como erros confusos mais à frente, em vez dos
+  # erros curados pela gem (ex.: `Micro::Case::Error::InvalidUseCase`).
+  config.disable_runtime_checks = false
 end
 ```
 
+Todas as verificações estão consolidadas em `Micro::Case::Check::Enabled` (o
+padrão). Definir `disable_runtime_checks = true` troca `Micro::Case.check` por
+`Micro::Case::Check::Disabled` — um módulo com a mesma assinatura cujos
+métodos não fazem nada — de forma que as validações não são executadas a
+cada chamada.
+
 [⬆️ Voltar para o índice](#índice-)
 
 ## Benchmarks

data/lib/micro/case/check.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Micro
+  class Case
+    module Check
+      module Enabled
+        extend self
+
+        def use_case_or_flow!(arg)
+          raise Error::InvalidUseCase unless ::Micro.case_or_flow?(arg)
+        end
+
+        def micro_case_instance!(arg)
+          raise Error::InvalidUseCase unless arg.is_a?(::Micro::Case)
+        end
+
+        def result_instance!(arg)
+          raise Error::InvalidResultInstance unless arg.is_a?(::Micro::Case::Result)
+        end
+
+        def result_not_defined!(is_defined)
+          raise Error::ResultIsAlreadyDefined if is_defined
+        end
+
+        def result_type!(type)
+          raise Error::InvalidResultType unless type.is_a?(Symbol)
+        end
+
+        def result_data!(data, is_success, type, use_case)
+          raise Error::InvalidResult.new(is_success, type, use_case) unless data
+        end
+
+        def expected_result!(result, context)
+          return if result.is_a?(::Micro::Case::Result)
+
+          raise Error::UnexpectedResult.new(context)
+        end
+
+        def expected_self_result!(actual, expected, context)
+          return if actual.equal?(expected)
+
+          raise Error::UnexpectedResult.new(context)
+        end
+
+        def then_use_case_or_flow!(arg, owner_label)
+          return if ::Micro.case_or_flow?(arg)
+
+          raise Error::InvalidInvocationOfTheThenMethod.new(owner_label)
+        end
+
+        def flow_use_cases!(use_cases)
+          raise Cases::Error::InvalidUseCases if use_cases.none?(&::Micro::Cases::Flow::IsAValidUseCase)
+        end
+
+        def map_args!(args)
+          raise Cases::Error::InvalidUseCases unless ::Micro::Cases::Map.const_get(:HasValidArgs, false)[args]
+        end
+
+        def hash!(arg)
+          Kind::Hash[arg]
+        end
+
+        def results_contract!(use_case_class, kind, type, value)
+          contract = use_case_class.__results_contract__
+          return unless contract
+          return unless type.is_a?(Symbol)
+          return if value.is_a?(Exception)
+
+          if kind == :success
+            declared = contract.success_declared?(type)
+            declared_types = contract.successes.keys
+            required = contract.success_keys(type) if declared
+          else
+            declared = contract.failure_declared?(type)
+            declared_types = contract.failures.keys
+            required = contract.failure_keys(type) if declared
+          end
+
+          raise Error::UnexpectedResultType.new(use_case_class, kind, type, declared_types) unless declared
+          return if required.nil? || required.empty?
+
+          if value.is_a?(Hash)
+            data_keys = value.keys.map { |k| k.is_a?(String) ? k.to_sym : k }
+          elsif value.is_a?(Symbol)
+            data_keys = [type]
+          else
+            return
+          end
+
+          missing = required - data_keys
+
+          raise Error::MissingResultKeys.new(use_case_class, kind, type, missing) unless missing.empty?
+        end
+      end
+
+      module Disabled
+        extend self
+
+        def use_case_or_flow!(_arg); end
+        def micro_case_instance!(_arg); end
+        def result_instance!(_arg); end
+        def result_not_defined!(_is_defined); end
+        def result_type!(_type); end
+        def result_data!(_data, _is_success, _type, _use_case); end
+        def expected_result!(_result, _context); end
+        def expected_self_result!(_actual, _expected, _context); end
+        def then_use_case_or_flow!(_arg, _owner_label); end
+        def flow_use_cases!(_use_cases); end
+        def map_args!(_args); end
+        def hash!(arg); arg; end
+        def results_contract!(_use_case_class, _kind, _type, _value); end
+      end
+    end
+  end
+end

data/lib/micro/case/config.rb

@@ -23,6 +23,18 @@ module Micro
         @disable_safe_features = false
       end
 
+      def disable_runtime_checks=(value)
+        @disable_runtime_checks = Kind::Boolean[value]
+
+        ::Micro::Case.check = @disable_runtime_checks ? ::Micro::Case::Check::Disabled : ::Micro::Case::Check::Enabled
+      end
+
+      def disable_runtime_checks
+        return @disable_runtime_checks if defined?(@disable_runtime_checks)
+
+        @disable_runtime_checks = false
+      end
+
       def enable_activemodel_validation=(value)
         return unless Kind::Boolean[value]
 

data/lib/micro/case/error.rb

@@ -60,9 +60,32 @@ module Micro
         end
       end
 
+      class UnexpectedResultType < TypeError
+        def initialize(use_case_class, kind, type, declared_types)
+          declared_list = declared_types.map { |t| ":#{t}" }.join(', ')
+          declared_list = '(none)' if declared_list.empty?
+
+          super(
+            "#{use_case_class.name} declared a results contract — " \
+            "#{kind} type :#{type} is not declared. Declared #{kind} types: #{declared_list}."
+          )
+        end
+      end
+
+      class MissingResultKeys < ArgumentError
+        def initialize(use_case_class, kind, type, missing_keys)
+          missing_list = missing_keys.map { |k| ":#{k}" }.join(', ')
+
+          super(
+            "#{use_case_class.name} declared a results contract — " \
+            "#{kind} :#{type} is missing required result keys: #{missing_list}."
+          )
+        end
+      end
+
       def self.by_wrong_usage?(exception)
         case exception
-        when Kind::Error, ArgumentError, InvalidResult, UnexpectedResult then true
+        when Kind::Error, ArgumentError, InvalidResult, UnexpectedResult, UnexpectedResultType then true
         else false
         end
       end

data/lib/micro/case/result/contract.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Micro
+  class Case
+    class Result
+      class Contract
+        attr_reader :successes, :failures
+
+        def self.define(&block)
+          contract = new
+          block.call(Definition.new(contract))
+          contract
+        end
+
+        def initialize
+          @successes = {}
+          @failures = {}
+        end
+
+        def add_success(type, keys)
+          @successes[type] = Array(keys).map(&:to_sym)
+        end
+
+        def add_failure(type, keys)
+          @failures[type] = Array(keys).map(&:to_sym)
+        end
+
+        def success_declared?(type)
+          @successes.key?(type)
+        end
+
+        def failure_declared?(type)
+          @failures.key?(type)
+        end
+
+        def success_keys(type)
+          @successes[type]
+        end
+
+        def failure_keys(type)
+          @failures[type]
+        end
+
+        class Definition
+          def initialize(contract)
+            @contract = contract
+          end
+
+          def success(type = :ok, result: nil)
+            @contract.add_success(Kind::Symbol[type], result)
+          end
+
+          def failure(type = :error, result: nil)
+            @contract.add_failure(Kind::Symbol[type], result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/micro/case/result.rb

@@ -174,14 +174,14 @@ module Micro
       end
 
       def __set__(is_success, data, type, use_case)
-        raise Error::InvalidResultType unless type.is_a?(Symbol)
-        raise Error::InvalidUseCase unless use_case.is_a?(::Micro::Case)
+        ::Micro::Case.check.result_type!(type)
+        ::Micro::Case.check.micro_case_instance!(use_case)
 
         @__success, @type, @use_case = is_success, type, use_case
 
         @data = FetchData.call(data).freeze
 
-        raise Micro::Case::Error::InvalidResult.new(is_success, type, use_case) unless @data
+        ::Micro::Case.check.result_data!(@data, is_success, type, use_case)
 
         @__accumulated_data.merge!(@data)
 
@@ -227,7 +227,7 @@ module Micro
             use_case_method = self.use_case.method(use_case)
             __call_method(use_case_method, attributes)
           else
-            raise INVALID_INVOCATION_OF_THE_THEN_METHOD unless ::Micro.case_or_flow?(use_case)
+            ::Micro::Case.check.then_use_case_or_flow!(use_case, 'Micro::Case::Result#')
 
             input = attributes.is_a?(Hash) ? self.data.merge(attributes) : self.data
 
@@ -244,9 +244,9 @@ module Micro
 
           result = fn.arity.zero? ? fn.call : fn.call(__fetch_accessible_attributes)
 
-          return self if result === self
+          ::Micro::Case.check.expected_self_result!(result, self, "#{Result.name}##{expected}")
 
-          raise Error::UnexpectedResult.new("#{Result.name}##{expected}")
+          self
         end
 
         def __call_method(methd, attributes = nil)
@@ -254,9 +254,9 @@ module Micro
 
           result = methd.arity.zero? ? methd.call : methd.call(**__fetch_accessible_attributes)
 
-          return self if result === self
+          ::Micro::Case.check.expected_self_result!(result, self, "#{use_case.class.name}#method(:#{methd.name})")
 
-          raise Error::UnexpectedResult.new("#{use_case.class.name}#method(:#{methd.name})")
+          self
         end
 
         def __success_type?(expected_type)

data/lib/micro/case/version.rb

@@ -2,6 +2,6 @@
 
 module Micro
   class Case
-    VERSION = '5.3.1'.freeze
+    VERSION = '5.5.0'.freeze
   end
 end

data/lib/micro/case.rb

@@ -11,12 +11,19 @@ module Micro
     require 'micro/case/utils'
     require 'micro/case/error'
     require 'micro/case/result'
+    require 'micro/case/result/contract'
+    require 'micro/case/check'
     require 'micro/case/config'
     require 'micro/case/safe'
     require 'micro/case/strict'
 
     require 'micro/cases'
 
+    class << self
+      attr_accessor :check
+    end
+    self.check = Check::Enabled
+
     include Micro::Attributes
     include Micro::Attributes::Features::Accept
 
@@ -46,7 +53,7 @@ module Micro
       else
         return yield_self if !use_case && can_yield_self
 
-        raise INVALID_INVOCATION_OF_THE_THEN_METHOD unless ::Micro.case_or_flow?(use_case)
+        ::Micro::Case.check.then_use_case_or_flow!(use_case, 'Micro::Case.')
 
         self.call.then(use_case)
       end
@@ -60,6 +67,20 @@ module Micro
       @__flow_use_cases = Cases::Utils.map_use_cases(args)
     end
 
+    def self.results(&block)
+      raise ArgumentError, 'a block is required'.freeze unless block
+      raise ArgumentError, 'must be called on a Micro::Case subclass, not on Micro::Case itself'.freeze if self == ::Micro::Case
+
+      @__results_contract = Result::Contract.define(&block)
+    end
+
+    def self.__results_contract__
+      return @__results_contract if defined?(@__results_contract)
+
+      parent = superclass
+      parent.respond_to?(:__results_contract__) ? parent.__results_contract__ : nil
+    end
+
     class << self
       alias __call__ call
 
@@ -169,8 +190,8 @@ module Micro
     end
 
     def __set_result__(result)
-      raise Error::InvalidResultInstance unless result.is_a?(Result)
-      raise Error::ResultIsAlreadyDefined if defined?(@__result)
+      ::Micro::Case.check.result_instance!(result)
+      ::Micro::Case.check.result_not_defined!(defined?(@__result))
 
       @__result = result
 
@@ -180,7 +201,7 @@ module Micro
     private
 
       def call(use_case, defaults = Kind::Empty::HASH)
-        raise Error::InvalidUseCase unless ::Micro.case_or_flow?(use_case)
+        ::Micro::Case.check.use_case_or_flow!(use_case)
 
         input =
           defaults.empty? ? attributes : attributes.merge(Utils::Hashes.stringify_keys(defaults))
@@ -211,9 +232,9 @@ module Micro
 
         result = call!
 
-        return result if result.is_a?(Result)
+        ::Micro::Case.check.expected_result!(result, "#{self.class.name}#call!")
 
-        raise Error::UnexpectedResult.new("#{self.class.name}#call!")
+        result
       end
 
       def __attributes_errors_present?
@@ -221,9 +242,10 @@ module Micro
       end
 
       def __failure_from_attributes_errors
-        Failure(
-          Config.instance.activemodel_validation_errors_failure,
-          result: { errors: attributes_errors }
+        __get_result(
+          false,
+          { errors: attributes_errors },
+          Config.instance.activemodel_validation_errors_failure
         )
       end
 
@@ -238,6 +260,8 @@ module Micro
       def Success(type = :ok, result: nil)
         value = result || type
 
+        ::Micro::Case.check.results_contract!(self.class, :success, type, value)
+
         __get_result(true, value, type)
       end
 
@@ -254,10 +278,11 @@ module Micro
 
         type = MapFailureType.call(value, type)
 
+        ::Micro::Case.check.results_contract!(self.class, :failure, type, value)
+
         __get_result(false, value, type)
       end
 
-
       def Check(type = nil, result: nil, on: Kind::Empty::HASH)
         result_key = type || :check
 

data/lib/micro/cases/flow.rb

@@ -11,7 +11,7 @@ module Micro
       def self.build(args)
         use_cases = Utils.map_use_cases(args)
 
-        raise Error::InvalidUseCases if use_cases.none?(&IsAValidUseCase)
+        ::Micro::Case.check.flow_use_cases!(use_cases)
 
         new(use_cases)
       end
@@ -63,7 +63,7 @@ module Micro
         else
           return yield_self if !use_case && can_yield_self
 
-          raise_invalid_invocation_of_the_then_method unless ::Micro.case_or_flow?(use_case)
+          ::Micro::Case.check.then_use_case_or_flow!(use_case, "#{self.class.name}#")
 
           self.call.then(use_case)
         end

data/lib/micro/cases/map.rb

@@ -10,7 +10,7 @@ module Micro
       attr_reader :use_cases
 
       def self.build(args)
-        raise Error::InvalidUseCases unless HasValidArgs[args]
+        ::Micro::Case.check.map_args!(args)
 
         new(args)
       end
@@ -30,7 +30,7 @@ module Micro
       end
 
       def call(arg = {})
-        hash = Kind::Hash[arg]
+        hash = ::Micro::Case.check.hash!(arg)
 
         use_cases.map(&GetUseCaseResult[hash])
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: u-case
 version: !ruby/object:Gem::Version
-  version: 5.3.1
+  version: 5.5.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -118,9 +118,11 @@ files:
 - gemfiles/rails_8_1.gemfile
 - gemfiles/rails_edge.gemfile
 - lib/micro/case.rb
+- lib/micro/case/check.rb
 - lib/micro/case/config.rb
 - lib/micro/case/error.rb
 - lib/micro/case/result.rb
+- lib/micro/case/result/contract.rb
 - lib/micro/case/result/transitions.rb
 - lib/micro/case/result/wrapper.rb
 - lib/micro/case/safe.rb