hubbado-sequence 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f708335623135a67d05ecdf13e49c97f9d0a1d1a2c21c2fda731f83c69ecc65
-  data.tar.gz: 011fcaa92a23f287b8800da473f37452c9305bd08a0e00833811817b50d858db
+  metadata.gz: 4c072f343cb764529d76c7babb7824217546cadeaf4cab59c305b40b0b1f7647
+  data.tar.gz: 15c860841338562d2ba8b39c8d49d1a95959345eec316489878676a0b9f4a3e4
 SHA512:
-  metadata.gz: 440e563ba5e86174e51c186ca365d30f7160a93ca4d4d79669d23e0461acfc1030261b63d109223e5a37129cefc4c5c0cfd6433219dd0edf3be2d7c9576048e5
-  data.tar.gz: c5a884e0a781e0b9794a3997ba1eaadbd03eeceaf02289ee33cab2528686281d89016ef9f82e7e04d6b71be5ce4378dc81336c5c7e1866e32d6b0f0f01cdff54
+  metadata.gz: 414d6011c8b468686ba3fe6f93adfa119d16196b25cc3313073463a56673aaf5a51100cb2b21ecd96e471511b4954cff6bbfd7e14806fc2c9370ac7c40a40020
+  data.tar.gz: df9d8e8d1c8ce2715f7b8582de9ed6a51106f5ff0f6c99caf596d9fb0f8b4ec5dc0818fecf01cb92149aa13f9813c40b7221b4cdcb1604d9a8ef3b0f43e037db

data/CHANGELOG.md

@@ -4,6 +4,185 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.7.0] - Macros::Policy::Check record-less policies; Sequencer i18n_scope applied at boundary
+
+### Changed (breaking)
+
+- **`Macros::Policy::Check#call` signature changed** from `(ctx, policy,
+  record_key, action)` to `(ctx, policy, action, record_key = nil)`.
+  `record_key` is now a trailing optional positional; omitting it
+  builds the policy with `nil` as the record, the shape required by
+  plural / collection policies (e.g. `Policies::Jobs`) that authorise
+  on a non-record subject rather than gating on a specific record:
+
+  ```ruby
+  # before
+  p.invoke(:check_policy, Policies::User, :user, :update)
+
+  # after
+  p.invoke(:check_policy, Policies::User, :update, :user)  # singular
+  p.invoke(:check_policy, Policies::Jobs, :list)           # record-less
+  ```
+
+  Migration: at every `p.invoke(:check_policy, ...)` call site, swap
+  the third and fourth positional arguments. Substitutes and the
+  underlying `policy.method_defined?(action)` typo-catch are
+  unchanged in behaviour; the parameter order on the substitute's
+  `call` is migrated to match.
+
+  See `docs/design.md` "Resolved Through Iteration" for the rationale
+  and the alternatives considered.
+
+### Added
+
+- **`Macros::Policy::Check.failure(ctx, policy, policy_result)`** class
+  helper. Returns `Result.failure(ctx, code: :forbidden, data: { policy:,
+  policy_result: })` — the same failure shape the macro produces. Lets
+  hand-rolled policy-check steps (for policy actions that take arguments,
+  or for compound logic the macro doesn't cover) produce the standard
+  failure shape without duplicating framework knowledge.
+
+- **`Macros::Policy::Check` now stores the built policy on `ctx[:policy]`.**
+  After building the policy instance and before invoking the action, the
+  macro writes it to ctx under `:policy` by default. Downstream steps (e.g.
+  contract construction that needs the policy injected) can read it
+  directly without re-building. Pass `as:` to store under a different key
+  when a sequencer runs multiple policy checks:
+
+  ```ruby
+  p.invoke(:check_policy, Policies::Document, :update, :document)
+  # ctx[:policy] is now the built Policies::Document instance
+
+  p.invoke(:check_policy, Policies::User, :show, :user, as: :user_policy)
+  # ctx[:user_policy] is the built Policies::User instance
+  ```
+
+  The substitute's `succeed_with` now accepts an optional policy instance;
+  passing one mirrors the production write to `ctx[as]` so substituted
+  specs can drive the same downstream paths.
+
+### Changed
+
+- **`Macros::Contract::Build`'s second parameter renamed** from
+  `attr_name` to `model`. The positional shape is unchanged — this is
+  an internal rename only — and the name now describes what the
+  parameter is (the ctx key/path for the model the contract wraps)
+  rather than what it isn't (an "attribute name" on anything). Callers
+  passing the value positionally (the only in-tree shape) are
+  unaffected.
+
+### Fixed
+
+- **`Sequencer#pipeline` and `Sequencer.()` now apply the sequencer's
+  auto-derived `i18n_scope` to the returned Result.** Closes a
+  documented-but-unimplemented step in the `Result#message`
+  translation fallback chain. Previously only `Sequencer#failure` (the
+  explicit helper) tagged a result with the sequencer's scope; macros
+  call `Result.failure` directly with no scope, so a sequencer body
+  that returned a macro's failure unchanged produced an unscoped
+  Result and `Result#message` fell through to the framework default
+  (`sequence.errors.<code>`) instead of the per-sequencer scoped
+  translation. Pure-macro sequencers (e.g. a body that's just
+  `pipeline(ctx) { |p| p.invoke(:check_policy, ...) }`) could never
+  produce a message translated under their own namespace. Tagging at
+  the boundary (`pipeline.result` and `Sequencer.()`) via
+  `Result#with_i18n_scope` preserves nested-sequencer "innermost scope
+  wins" semantics — `with_i18n_scope` is a no-op when the scope is
+  already set, so an inner sequencer's scope survives the outer
+  wrapper. See `docs/design.md` "Resolved Through Iteration" for the
+  rationale.
+
+## [0.6.0] - Result.failure flat kwargs; Dispatch delegates reads and exposes raise helpers
+
+### Changed (breaking)
+
+- **`Result.failure` takes flat kwargs; the `error:` hash wrapper is
+  gone.** The previous shape — `Result.failure(ctx, error: { code:,
+  data:, ... })` — wrapped its keys in an `error:` hash for no reason
+  beyond convention. The fields are now first-class kwargs on
+  `Result.failure` and first-class attrs on `Result`:
+
+  ```ruby
+  # before
+  Result.failure(ctx, error: { code: :forbidden, data: { policy_result: pr } })
+  result.error[:code]                # => :forbidden
+  result.error[:data][:policy_result]
+
+  # after
+  Result.failure(ctx, code: :forbidden, data: { policy_result: pr })
+  result.code                        # => :forbidden
+  result.data[:policy_result]
+  ```
+
+  `Result` exposes `code`, `data`, `step`, `message_override`,
+  `i18n_scope`, `i18n_key`, `i18n_args` as readers. `Result#error`
+  is removed.
+
+  Migration: in callers, replace `Result.failure(ctx, error: { code:
+  :X })` with `Result.failure(ctx, code: :X)`. Replace `result.error[:X]`
+  reads with `result.X`. The `Sequencer#failure(ctx, **error_attrs)`
+  helper is unchanged at the call site (it always took flat kwargs).
+  Macro substitutes' `fail_with(**error_attrs)` is unchanged at the call
+  site; arbitrary extra attrs that used to live in the error hash should
+  move into `data:` (`fail_with(code: :forbidden, data: { reason:
+  :not_owner })`).
+
+- **The per-error `i18n_scope` override path is removed.** Previously a
+  caller could put `i18n_scope:` inside the `error:` hash *and* pass a
+  separate `i18n_scope:` to the surrounding wrapper, with the per-error
+  one winning. With flat kwargs there is one `i18n_scope` slot. The
+  `Sequencer#failure` helper still applies the sequencer's auto-derived
+  scope when the caller doesn't pass one (`error_attrs[:i18n_scope] ||=
+  i18n_scope`), preserving the "caller wins" semantics where it matters
+  in practice. `Result#with_i18n_scope` (used to apply a scope to an
+  already-built Result) is unchanged.
+
+- **`Runner::Dispatch#result` is removed.** Master exposed the wrapped
+  Result via `attr_reader :result`, which was the source of the
+  `result.result.error.dig(...)` four-hop pattern. With the new
+  read-through delegations (`code`, `data`, `step`, `message`,
+  `successful_steps`, `ctx`) there's no reason for outcome blocks to
+  reach into the inner Result. Any caller still doing
+  `result.result.X` from inside a `run_sequence` block will now raise
+  `NoMethodError`; replace with the matching delegation on the
+  dispatch object itself.
+
+- **The `message:` kwarg on `Result.failure` is removed.** It set a
+  literal-string fallback returned by `Result#message` when no
+  translation matched. No in-tree caller used it (the
+  i18n-translation chain plus `humanize_code` fallback covered every
+  real case), and the path was test-only. If a caller needs a custom
+  message they can supply `i18n_key:` and a matching translation, or
+  pass a humanizable `code:` symbol.
+
+### Added
+
+- **`Runner::Dispatch` delegates reads to its wrapped `Result`.** Outcome
+  blocks can call `result.code`, `result.data`, `result.message`,
+  `result.step`, `result.successful_steps`, `result.ctx` on the
+  `Dispatch` object (the block argument) without hopping through an
+  inner `.result.` reference. The previous `result.result.error.dig(...)`
+  pattern collapses to one read.
+
+  ```ruby
+  result.policy_failed do |ctx|
+    if result.data[:policy_result].reason == :not_open
+      redirect_to public_path(ctx[:job])
+    else
+      result.raise_policy_failed
+    end
+  end
+  ```
+
+- **Public raise helpers on `Runner::Dispatch`:** `raise_policy_failed`,
+  `raise_not_found`, and `raise_failed`. They produce the same exceptions
+  the safety net would raise, but can be called explicitly from inside an
+  outcome block — useful when a caller handles some failure cases inline
+  and wants the framework's standard escalation for the rest.
+  `enforce_safety_nets!` now delegates to the same helpers, so the
+  exception shapes stay aligned whether the caller invokes them directly
+  or the runner does it automatically.
+
 ## [0.5.0] - Result vocabulary renamed: success/failure and successful_steps
 
 ### Changed (breaking)

data/README.md

@@ -126,7 +126,7 @@ class Seqs::UpdateUser
     pipeline(ctx) do |p|
       p.invoke(:find,           User,                  as: :user)
       p.invoke(:build_contract, Contracts::UpdateUser, :user)
-      p.invoke(:check_policy,   Policies::User,        :user, :update)
+      p.invoke(:check_policy,   Policies::User,        :update, :user)
 
       p.transaction do |t|
         t.invoke(:validate, from: %i[params user])
@@ -230,7 +230,7 @@ p.invoke(:build_contract, Contracts::CreateUser)         # no model
 
 | | |
 |---|---|
-| **Reads** | `ctx[attr_name]` for the model (optional) |
+| **Reads** | `ctx` at `model` for the model (optional) |
 | **Writes** | `ctx[:contract]` |
 | **Fails** | never |
 
@@ -288,18 +288,64 @@ Designed to work with the
 Builds a policy and calls the named action to authorise the operation.
 
 ```ruby
-p.invoke(:check_policy, Policies::User, :user, :update)
+p.invoke(:check_policy, Policies::User, :update, :user)  # policy on a record
+p.invoke(:check_policy, Policies::Jobs,  :list)          # plural / record-less
 ```
 
 The policy class must respond to `.build(current_user, record)`; the
-instance must respond to the action method and return an object with
-`permitted?`.
+instance must respond to the action method and return a
+`Hubbado::Policy::Result`-shaped object (`permitted?`, `denied?`,
+`reason`, `message`). When `record_key` is omitted the policy is built
+with `nil` as the record — the shape for plural / collection policies
+that authorise against a non-record subject (e.g. a company id read
+from `current_user`).
+
+The built policy instance is written to `ctx[:policy]` so downstream
+steps (e.g. contract construction that needs the policy injected) can
+read it directly. Pass `as:` to store under a different key when a
+sequencer runs more than one policy check:
+
+```ruby
+p.invoke(:check_policy, Policies::User, :show, :user, as: :user_policy)
+# ctx[:user_policy] — the built Policies::User instance
+```
 
 | | |
 |---|---|
-| **Reads** | `ctx[:current_user]`, `ctx[record_key]` |
-| **Writes** | nothing |
-| **Fails** | `:forbidden` when `permitted?` is false; `error[:data]` carries `{ policy:, policy_result: }` |
+| **Reads** | `ctx[:current_user]`, `ctx[record_key]` when `record_key` is supplied |
+| **Writes** | `ctx[as]` — the built policy instance (`as:` defaults to `:policy`) |
+| **Fails** | `:forbidden` when `permitted?` is false; `result.data` carries `{ policy:, policy_result: }` |
+
+The macro only covers zero-arg policy actions. For actions that take
+arguments (e.g. `Policies::Jobs#create(company_id)`), hand-roll a step
+and use `Macros::Policy::Check.failure(ctx, policy, policy_result)` to
+produce the standard failure shape:
+
+```ruby
+def check_create_policy(ctx)
+  policy = Policies::Jobs.build(ctx[:current_user], nil)
+  result = policy.create(ctx[:company_id])
+
+  return Macros::Policy::Check.failure(ctx, policy, result) unless result.permitted?
+
+  Result.success(ctx)
+end
+```
+
+A controller can branch on the denial reason via `data`:
+
+```ruby
+result.policy_failed do |ctx|
+  if result.data[:policy_result].reason == :not_open
+    redirect_to public_path(ctx[:job])
+  else
+    result.raise_policy_failed
+  end
+end
+```
+
+See [Handling specific failure reasons inside an outcome block](#handling-specific-failure-reasons-inside-an-outcome-block)
+for when `raise_policy_failed` and its siblings come in handy.
 
 ## Transactions
 
@@ -312,7 +358,7 @@ def call(ctx)
   pipeline(ctx) do |p|
     p.invoke(:find,           User,                  as: :user)
     p.invoke(:build_contract, Contracts::UpdateUser, :user)
-    p.invoke(:check_policy,   Policies::User,        :user, :update)
+    p.invoke(:check_policy,   Policies::User,        :update, :user)
 
     p.transaction do |t|
       t.invoke(:validate, from: %i[params user])
@@ -367,7 +413,7 @@ class Seqs::UpdateUser
       pipeline(ctx) do |p|
         p.invoke(:find,           User,                  as: :user)
         p.invoke(:build_contract, Contracts::UpdateUser, :user)
-        p.invoke(:check_policy,   Policies::User,        :user, :update)
+        p.invoke(:check_policy,   Policies::User,        :update, :user)
       end
     end
   end
@@ -454,9 +500,118 @@ end
 ```
 
 `failure(ctx, ...)` is a sequencer helper that builds a failed `Result`
-with the sequencer's auto-derived i18n scope already applied. It takes the
-same error attrs as the underlying error hash (`code:`, `i18n_key:`,
-`i18n_args:`, `data:`, `message:`).
+with the sequencer's auto-derived i18n scope already applied. It takes
+the same kwargs as `Result.failure` (`code:`, `data:`, `step:`,
+`i18n_scope:`, `i18n_key:`, `i18n_args:`).
+
+## Translations
+
+`Result#message` translates the failure `code` through a fallback chain:
+
+1. **Per-error scope** — whatever the failure set as `i18n_scope:` (or
+   `i18n_key:` for an explicit key override).
+2. **Sequencer's auto-derived scope** — the class name underscored, with
+   `/` → `.`. `Seqs::UpdateUser` becomes `seqs.update_user`;
+   `Jobadder::Seqs::AuthorizationCallback` becomes
+   `jobadder.seqs.authorization_callback`.
+3. **Framework default** — `sequence.errors.<code>` (the gem ships
+   translations for the standard codes; see "Standard error codes" below).
+4. **Humanized code** — `:not_found` → `"Not found"`.
+
+The sequencer's scope is applied automatically. Both the `failure(ctx, ...)`
+helper *and* the boundary itself (`Sequencer#pipeline` and `Sequencer.()`)
+tag the returned `Result` with `i18n_scope` via `Result#with_i18n_scope`.
+That means an unscoped failure produced inside a macro, a hand-rolled
+step, or anywhere else in the sequencer body picks up the sequencer's
+scope when the Result bubbles out — no `failure` call required.
+
+### Defining translations for a sequencer
+
+Drop translations under the sequencer's auto-derived scope in your locale
+file:
+
+```yaml
+en:
+  jobadder:
+    seqs:
+      authorization_callback:
+        forbidden: "You are not allowed to connect this company to JobAdder"
+        authorization_failed: "Could not authorize with JobAdder"
+```
+
+Now `result.message` returns the scoped string when the sequencer fails
+with `code: :forbidden` or `code: :authorization_failed`. Missing
+translations fall through to the framework default, then to the humanized
+code — so a fresh app gets sensible behaviour with zero config.
+
+### Per-error overrides
+
+A specific failure can override the scope or key. The error's own scope
+beats the sequencer's:
+
+```ruby
+failure(
+  ctx,
+  code: :not_shippable,
+  i18n_scope: "checkout.errors",  # used instead of seqs.place_order
+  i18n_key: :address_invalid,     # used instead of :not_shippable
+  i18n_args: { region: ctx[:country] }
+)
+```
+
+Resolves `checkout.errors.address_invalid` with the `%{region}`
+interpolation supplied.
+
+### Nested sequencers: innermost scope wins
+
+`Result#with_i18n_scope` is a no-op when the scope is already set, so a
+nested sequencer's scope sticks. If `UpdateUser` calls `Present` and
+Present's `Model::Find` macro fails, the failure is tagged with
+`seqs.present` first (Present's boundary); `UpdateUser`'s boundary tries
+to retag with `seqs.update_user` but the no-op preserves the inner scope.
+Messages resolve under the namespace of the sequencer that actually
+produced the failure, not the outermost wrapper.
+
+## Outcome blocks and safety nets
+
+`run_sequence` enforces that serious failures are addressed. Forgetting to
+handle them raises rather than silently swallowing:
+
+- An unhandled `:forbidden` raises `Hubbado::Sequence::Errors::Unauthorized`.
+- An unhandled `:not_found` raises `Hubbado::Sequence::Errors::NotFound`.
+- An unhandled non-policy / non-not-found failure (and an `otherwise` block
+  isn't given) raises `Hubbado::Sequence::Errors::Failed`.
+
+`otherwise` deliberately does *not* catch `:forbidden` or `:not_found` —
+that's what prevents a generic `otherwise` accidentally rendering a form
+when the policy denied access.
+
+### Handling specific failure reasons inside an outcome block
+
+The dispatch object exposes the standard escalation paths as public
+methods, so an outcome block can handle some cases inline and fall back to
+the framework's exception for the rest:
+
+```ruby
+result.policy_failed do |ctx|
+  if result.data[:policy_result].reason == :not_open
+    redirect_to public_path(ctx[:job])
+  else
+    result.raise_policy_failed
+  end
+end
+```
+
+The available helpers mirror the safety nets:
+
+- `result.raise_policy_failed` — raises `Errors::Unauthorized` with the
+  standard message.
+- `result.raise_not_found` — raises `Errors::NotFound`.
+- `result.raise_failed` — raises `Errors::Failed`.
+
+Use them when you genuinely want the framework's default escalation;
+prefer plain Ruby control flow (`return`, `if`/`else`) for ordinary
+branching.
 
 ## Testing
 
@@ -510,7 +665,7 @@ context "Seqs::UpdateUser::Present when the user is not found" do
   result = seq.(params: { id: 999 }, current_user: User.new)
 
   test "Fails with :not_found" do
-    assert(result.error[:code] == :not_found)
+    assert(result.code == :not_found)
   end
 
   test "Does not build the contract" do
@@ -523,6 +678,15 @@ context "Seqs::UpdateUser::Present when the user is not found" do
 end
 ```
 
+The `Policy::Check` substitute's `fail_with(**error)` accepts the same
+attributes `Result.failure` does, so a test that needs an outcome block
+to branch on `result.data[:policy_result].reason` can configure the data
+payload directly:
+
+```ruby
+seq.check_policy.fail_with(code: :forbidden, data: { policy_result: DeniedResult.new(:not_open) })
+```
+
 ### Substituting a nested sequencer
 
 Every sequencer ships a default `Substitute` module (installed by
@@ -567,7 +731,7 @@ context "Seqs::UpdateUser when Present denies access" do
   end
 
   test "Fails with :forbidden" do
-    assert(result.error[:code] == :forbidden)
+    assert(result.code == :forbidden)
   end
 
   test "Does not validate" do
@@ -586,7 +750,7 @@ context "Seqs::UpdateUser when Present cannot find the record" do
   result = seq.(params: { id: 999, user: {} }, current_user: User.new)
 
   test "Fails with :not_found" do
-    assert(result.error[:code] == :not_found)
+    assert(result.code == :not_found)
   end
 
   test "Does not validate" do
@@ -610,12 +774,12 @@ to exercise Find / Build / Policy::Check directly — those live in
 
 Every `Result` carries **successful_steps** — the list of step names that
 completed successfully, in order. On failure, the failing step is *not* in
-`successful_steps`; it's tagged on `error[:step]` instead.
+`successful_steps`; it's tagged on `step` instead.
 
 ```ruby
 result.successful_steps  # => [:find, :build_contract, :check_policy, :validate, :persist]  # success
 result.successful_steps  # => [:find, :build_contract]                                       # failed at :check_policy
-result.error[:step]      # => :check_policy
+result.step              # => :check_policy
 ```
 
 When invoked via `run_sequence`, the dispatcher logs a single line per

data/hubbado-sequence.gemspec

@@ -1,7 +1,7 @@
 # -*- encoding: utf-8 -*-
 Gem::Specification.new do |s|
   s.name = "hubbado-sequence"
-  s.version = "0.5.0"
+  s.version = "0.7.0"
   s.summary = "A small framework for the short sequences of common steps that controller actions usually boil down to"
   s.description = "A sequencer takes input, runs an ordered sequence of steps, and returns a Result carrying a success-or-failure flag, a structured error, and the working context that was built up during execution. Built with Rails in mind but framework-agnostic."
 

data/lib/hubbado/sequence/macros/contract/build.rb

@@ -10,9 +10,9 @@ module Hubbado
             new
           end
 
-          def call(ctx, contract_class, attr_name = nil)
-            model = attr_name && Path.resolve(ctx, attr_name)
-            ctx[:contract] = contract_class.new(model)
+          def call(ctx, contract_class, model = nil)
+            resolved_model = model && Path.resolve(ctx, model)
+            ctx[:contract] = contract_class.new(resolved_model)
             Result.success(ctx)
           end
 
@@ -30,8 +30,8 @@ module Hubbado
               self
             end
 
-            record def call(ctx, contract_class, attr_name = nil)
-              return Result.failure(ctx, error: @configured_error) if @configured_error
+            record def call(ctx, contract_class, model = nil)
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
               ctx[:contract] = @return_value if @configured_success
               Result.success(ctx)

data/lib/hubbado/sequence/macros/contract/deserialize.rb

@@ -27,7 +27,7 @@ module Hubbado
             end
 
             record def call(ctx, from:)
-              return Result.failure(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
               Result.success(ctx)
             end

data/lib/hubbado/sequence/macros/contract/persist.rb

@@ -16,7 +16,7 @@ module Hubbado
             if contract.save
               Result.success(ctx)
             else
-              Result.failure(ctx, error: { code: :persist_failed })
+              Result.failure(ctx, code: :persist_failed)
             end
           end
 
@@ -34,7 +34,7 @@ module Hubbado
             end
 
             record def call(ctx)
-              return Result.failure(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
               Result.success(ctx)
             end

data/lib/hubbado/sequence/macros/contract/validate.rb

@@ -19,7 +19,7 @@ module Hubbado
             if contract.errors.empty?
               Result.success(ctx)
             else
-              Result.failure(ctx, error: { code: :validation_failed })
+              Result.failure(ctx, code: :validation_failed)
             end
           end
 
@@ -37,7 +37,7 @@ module Hubbado
             end
 
             record def call(ctx, from: nil)
-              return Result.failure(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
               Result.success(ctx)
             end

data/lib/hubbado/sequence/macros/model/build.rb

@@ -40,7 +40,7 @@ module Hubbado
                   "Macros::Model::Build substitute: #{model} does not respond to :new"
               end
 
-              return Result.failure(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
               ctx[as] = @return_value if @configured_success
               Result.success(ctx)

data/lib/hubbado/sequence/macros/model/find.rb

@@ -18,7 +18,7 @@ module Hubbado
               ctx[as] = record
               Result.success(ctx)
             else
-              Result.failure(ctx, error: { code: :not_found })
+              Result.failure(ctx, code: :not_found)
             end
           end
 
@@ -42,7 +42,7 @@ module Hubbado
                   "Macros::Model::Find substitute: #{model} does not respond to :find_by"
               end
 
-              return Result.failure(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
               ctx[as] = @return_value if @configured_success
               Result.success(ctx)

data/lib/hubbado/sequence/macros/policy/check.rb

@@ -10,31 +10,36 @@ module Hubbado
             new
           end
 
-          def call(ctx, policy, record_key, action)
+          def self.failure(ctx, policy, policy_result)
+            Result.failure(
+              ctx,
+              code: :forbidden,
+              data: { policy: policy, policy_result: policy_result }
+            )
+          end
+
+          def call(ctx, policy, action, record_key = nil, as: nil)
+            as ||= :policy
             current_user = ctx[:current_user]
-            record = ctx[record_key]
+            record = record_key && ctx[record_key]
 
             policy_instance = policy.build(current_user, record)
+            ctx[as] = policy_instance
             policy_result = policy_instance.public_send(action)
 
             if policy_result.permitted?
               Result.success(ctx)
             else
-              Result.failure(
-                ctx,
-                error: {
-                  code: :forbidden,
-                  data: { policy: policy_instance, policy_result: policy_result }
-                }
-              )
+              self.class.failure(ctx, policy_instance, policy_result)
             end
           end
 
           module Substitute
             include ::RecordInvocation
 
-            def succeed_with
+            def succeed_with(policy_instance = nil)
               @configured_success = true
+              @return_policy = policy_instance
               self
             end
 
@@ -43,14 +48,17 @@ module Hubbado
               self
             end
 
-            record def call(ctx, policy, record_key, action)
+            record def call(ctx, policy, action, record_key = nil, as: nil)
+              as ||= :policy
+
               unless policy.method_defined?(action)
                 raise ArgumentError,
                   "Macros::Policy::Check substitute: #{policy} does not declare action :#{action}"
               end
 
-              return Result.failure(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
+              ctx[as] = @return_policy if @return_policy
               Result.success(ctx)
             end
 

data/lib/hubbado/sequence/pipeline.rb

@@ -84,16 +84,13 @@ module Hubbado
 
       def record(name, return_value)
         if return_value.is_a?(Result) && return_value.failure?
-          @failed_result = tag_failure(return_value, name)
+          @failed_result = return_value
+            .with_step(name)
+            .with_successful_steps(@successful_steps.dup)
         else
           @successful_steps << name
         end
       end
-
-      def tag_failure(result, step_name)
-        tagged_error = result.error.merge(step: step_name)
-        Result.failure(result.ctx, error: tagged_error, successful_steps: @successful_steps.dup, i18n_scope: result.i18n_scope)
-      end
     end
   end
 end

data/lib/hubbado/sequence/result.rb

@@ -4,28 +4,52 @@ module Hubbado
       FRAMEWORK_I18N_SCOPE = "sequence.errors".freeze
 
       attr_reader :ctx
-      attr_reader :error
+      attr_reader :code
+      attr_reader :data
+      attr_reader :step
       attr_reader :successful_steps
       attr_reader :i18n_scope
+      attr_reader :i18n_key
+      attr_reader :i18n_args
 
       def self.success(ctx, successful_steps: [], i18n_scope: nil)
-        new(:success, ctx, error: nil, successful_steps: successful_steps, i18n_scope: i18n_scope)
+        new(
+          :success,
+          ctx: ctx,
+          successful_steps: successful_steps,
+          i18n_scope: i18n_scope
+        )
       end
 
-      def self.failure(ctx, error:, successful_steps: [], i18n_scope: nil)
-        unless error.is_a?(Hash) && error[:code]
-          raise ArgumentError, "Result.failure requires error: { code: ... }"
-        end
-
-        new(:failure, ctx, error: error, successful_steps: successful_steps, i18n_scope: i18n_scope)
+      def self.failure(ctx, code:, data: nil, step: nil,
+        i18n_scope: nil, i18n_key: nil, i18n_args: nil, successful_steps: [])
+        raise ArgumentError, "Result.failure requires code:" unless code
+
+        new(
+          :failure,
+          ctx: ctx,
+          code: code,
+          data: data,
+          step: step,
+          successful_steps: successful_steps,
+          i18n_scope: i18n_scope,
+          i18n_key: i18n_key,
+          i18n_args: i18n_args
+        )
       end
 
-      def initialize(status, ctx, error:, successful_steps:, i18n_scope:)
+      def initialize(status, ctx:, successful_steps:, i18n_scope:,
+        code: nil, data: nil, step: nil,
+        i18n_key: nil, i18n_args: nil)
         @status = status
         @ctx = ctx
-        @error = error
+        @code = code
+        @data = data
+        @step = step
         @successful_steps = successful_steps
         @i18n_scope = i18n_scope
+        @i18n_key = i18n_key
+        @i18n_args = i18n_args
       end
 
       def success?
@@ -37,35 +61,50 @@ module Hubbado
       end
 
       def with_successful_steps(successful_steps)
-        self.class.new(@status, @ctx, error: @error, successful_steps: successful_steps, i18n_scope: @i18n_scope)
+        copy(successful_steps: successful_steps)
       end
 
       def with_i18n_scope(scope)
         return self unless @i18n_scope.nil?
 
-        self.class.new(@status, @ctx, error: @error, successful_steps: @successful_steps, i18n_scope: scope)
+        copy(i18n_scope: scope)
+      end
+
+      def with_step(step)
+        copy(step: step)
       end
 
       def message
         return nil if success?
 
-        translation = translate_with_chain
-        return translation if translation
-
-        @error[:message] || humanize_code
+        translate_with_chain || humanize_code
       end
 
       private
 
+      def copy(**overrides)
+        self.class.new(
+          @status,
+          ctx: @ctx,
+          code: @code,
+          data: @data,
+          step: @step,
+          successful_steps: @successful_steps,
+          i18n_scope: @i18n_scope,
+          i18n_key: @i18n_key,
+          i18n_args: @i18n_args,
+          **overrides
+        )
+      end
+
       def translate_with_chain
         scopes = []
-        scopes << @error[:i18n_scope] if @error[:i18n_scope]
         scopes << @i18n_scope if @i18n_scope
         scopes << FRAMEWORK_I18N_SCOPE
         scopes.uniq!
 
-        key = @error[:i18n_key] || @error[:code]
-        args = @error[:i18n_args] || {}
+        key = @i18n_key || @code
+        args = @i18n_args || {}
 
         scopes.each do |scope|
           translated = ::I18n.t("#{scope}.#{key}", default: nil, **args)
@@ -76,7 +115,7 @@ module Hubbado
       end
 
       def humanize_code
-        @error[:code].to_s.tr("_", " ").capitalize
+        @code.to_s.tr("_", " ").capitalize
       end
     end
   end

data/lib/hubbado/sequence/runner.rb

@@ -25,7 +25,7 @@ module Hubbado
       class Dispatch
         include Hubbado::Log::Dependency
 
-        attr_reader :returned, :result, :sequencer_class
+        attr_reader :returned, :sequencer_class
 
         def initialize(sequencer_class, result)
           @sequencer_class = sequencer_class
@@ -33,6 +33,16 @@ module Hubbado
           @handled = false
         end
 
+        # Read-throughs to the wrapped Result. Outcome blocks read these on
+        # the Dispatch object (the block argument) without hopping through
+        # an inner Result reference.
+        def code             = @result.code
+        def data             = @result.data
+        def step             = @result.step
+        def message          = @result.message
+        def successful_steps = @result.successful_steps
+        def ctx              = @result.ctx
+
         def success
           return unless @result.success?
           execute { yield(@result.ctx) }
@@ -69,29 +79,38 @@ module Hubbado
           logger.info("Sequencer #{@sequencer_class.name} failed at #{step_label} (#{code}): #{steps_summary}")
         end
 
-        def code
-          @result.error&.[](:code)
-        end
-
         def handled?
           @result.success? || @handled
         end
 
+        # Raise the standard policy-denial exception. Available inside an
+        # outcome block (e.g. for callers that handle some policy reasons
+        # inline and want the framework's standard escalation for the rest)
+        # and used internally by enforce_safety_nets! when no handler ran.
+        def raise_policy_failed
+          raise Errors::Unauthorized.new(
+            "#{@sequencer_class.name} denied: #{@result.message}",
+            @result
+          )
+        end
+
+        def raise_not_found
+          raise Errors::NotFound, "#{@sequencer_class.name} reported not_found"
+        end
+
+        def raise_failed
+          raise Errors::Failed, "#{@sequencer_class.name} failed (#{code}): #{@result.message}"
+        end
+
         def enforce_safety_nets!
           return if handled?
 
           log_unhandled
 
           case code
-          when :forbidden
-            raise Errors::Unauthorized.new(
-              "#{@sequencer_class.name} denied: #{@result.message}",
-              @result
-            )
-          when :not_found
-            raise Errors::NotFound, "#{@sequencer_class.name} reported not_found"
-          else
-            raise Errors::Failed, "#{@sequencer_class.name} failed (#{code}): #{@result.message}"
+          when :forbidden then raise_policy_failed
+          when :not_found then raise_not_found
+          else raise_failed
           end
         end
 
@@ -107,11 +126,10 @@ module Hubbado
         end
 
         def steps_summary
-          @result.successful_steps.empty? ? "(no steps)" : @result.successful_steps.map(&:to_s).join(" → ")
+          successful_steps.empty? ? "(no steps)" : successful_steps.map(&:to_s).join(" → ")
         end
 
         def step_label
-          step = @result.error && @result.error[:step]
           step ? step.inspect : "(unknown step)"
         end
       end
@@ -162,7 +180,8 @@ module Hubbado
         def configure_failure(code, error_attrs)
           @configured_outcome = {
             kind: :failure,
-            error: { code: code, **error_attrs }
+            code: code,
+            error_attrs: error_attrs
           }
           self
         end
@@ -175,7 +194,7 @@ module Hubbado
             outcome[:ctx_writes].each { |key, value| ctx[key] = value }
             Hubbado::Sequence::Result.success(ctx)
           else
-            Hubbado::Sequence::Result.failure(ctx, error: outcome[:error])
+            Hubbado::Sequence::Result.failure(ctx, code: outcome[:code], **outcome[:error_attrs])
           end
         end
       end

data/lib/hubbado/sequence/sequencer.rb

@@ -34,7 +34,7 @@ module Hubbado
           end
 
           record def call(ctx)
-            return ::Hubbado::Sequence::Result.failure(ctx, error: @configured_error) if @configured_error
+            return ::Hubbado::Sequence::Result.failure(ctx, **@configured_error) if @configured_error
 
             if @configured_writes
               @configured_writes.each { |k, v| ctx[k] = v }
@@ -62,7 +62,7 @@ module Hubbado
             ctx = Ctx.build(ctx)
           end
 
-          build.call(ctx)
+          build.call(ctx).with_i18n_scope(i18n_scope)
         end
 
         # Default factory: a sequencer with no configurable dependencies needs
@@ -83,7 +83,8 @@ module Hubbado
       end
 
       def failure(ctx, **error_attrs)
-        Result.failure(ctx, error: error_attrs, i18n_scope: i18n_scope)
+        error_attrs[:i18n_scope] ||= i18n_scope
+        Result.failure(ctx, **error_attrs)
       end
 
       # Builds a Pipeline that auto-dispatches blockless `step(:foo)` calls to
@@ -99,7 +100,7 @@ module Hubbado
 
         if block
           block.call(pipe)
-          pipe.result
+          pipe.result.with_i18n_scope(i18n_scope)
         else
           pipe
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hubbado-sequence
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Hubbado Devs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-15 00:00:00.000000000 Z
+date: 2026-05-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: evt-casing