Add Micro::Case::Result#then_expose for boundary projection + re-tagging

[serradura]

Summary

• Adds a new public Micro::Case::Result#then_expose (alias #then_return) — projects a successful result's accumulated data down to a named subset of keys and re-tags it with a domain-meaningful type, in one call. Useful at the boundary of a flow where you hand a result back to a controller / worker / outer flow. On a Failure result it's a no-op (returns self unchanged); on Success, lookup runs against the merged accessible_attributes + accumulated_data map (accumulated wins on collisions) and the exposed slice is merged back into accumulated data so subsequent .then-chained use cases still see it.
• Adds Micro::Case::Error::InvalidResultExposure (subclass of ::KeyError) for missing-key errors, with a message that lists the keys that were available.
• Strictly additive — no existing public API behavior changes (per the gem's no-breaking-changes Golden rule in CLAUDE.md). No version bump.

Design notes

Inspired by solid-result's Solid::Output::Success#and_expose, adapted to u-case's Micro::Case::Result state-transition primitive (__set__).

Three call shapes:

result.then_expose(:user_created, [:user, :token])  # type + Array of keys
result.then_expose(:user_created, :user)            # type + single Symbol key (normalized to [:user])
result.then_expose([:user, :token])                 # Array-only — type defaults to :data_exposed

A bare Symbol (then_expose(:user)) is rejected with ArgumentError because a lone Symbol is ambiguous between "type with no keys" and "key with no type". Empty / non-Symbol keys and non-Symbol types in the two-arg form likewise raise ArgumentError up-front.

then_expose deliberately bypasses the producing use case's results { ... } contract — the exposed shape is the seam's decision, not the producer's declaration. The contract check runs only when the use case calls Success(...) / Failure(...) inside call!. This is implementation-evident (calling __set__ directly) and documented in both READMEs.

Argument validation stays inline in __resolve_then_expose_args rather than routing through Micro::Case::Check, matching the existing "local validity check stays local" pattern (cf. the then method's inline INVALID_INVOCATION_OF_THE_THEN_METHOD).

Docs

• CHANGELOG.md — new [Unreleased] Added section.
• README.md + README.pt-BR.md — new Projecting and re-tagging with Result#then_expose section under Working with results, plus a TOC entry. Both READMEs updated in lockstep (per CLAUDE.md). The new section covers all three call shapes, the then_return alias, the failure short-circuit, the missing-key error, and an explicit note about the producer-side contract bypass.

Test plan

• bundle exec rake test TEST=test/micro/case/result/then_expose_test.rb → 25 tests, 117 assertions, 0 failures (1 skip is the transitions-disabled branch when env defaults to enabled).
• bundle exec rake test (default suite) → 820 runs, 8309 assertions, 0 failures, 0 errors.
• bundle exec rake matrix on Ruby 4.0.1 → green across all 4 runs: rails-8-1 and rails-edge, each with ENABLE_TRANSITIONS=true and =false. 0 failures total.
• Verified Micro::Case::Error::InvalidResultExposure < ::KeyError so existing rescue KeyError clauses keep working unchanged.
• Verified the alias then_return produces identical behavior across all three call shapes.

Files changed

• lib/micro/case/result.rb — public #then_expose, alias then_return then_expose, private helpers __resolve_then_expose_args and __fetch_values_to_expose.
• lib/micro/case/error.rb — new InvalidResultExposure class.
• test/micro/case/result/then_expose_test.rb — new test file covering all behaviors above (call shapes, argument validation, failure short-circuit, source/precedence semantics, missing-key error and ::KeyError rescue, then_return alias parity, transitions enabled/disabled, accumulated-data threading, disable_runtime_checks path, contract bypass).
• CHANGELOG.md, README.md, README.pt-BR.md — Added entry + new docs section in lockstep.

🤖 Generated with Claude Code