hubbado-sequence 0.4.0 → 0.6.0

data/hubbado-sequence.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
 Gem::Specification.new do |s|
   s.name = "hubbado-sequence"
-  s.version = "0.4.0"
-  s.summary = "A small framework for orchestrating units of business behaviour"
-  s.description = "Sequencer takes input, runs a sequence of steps, and returns a Result indicating success or failure plus the working context that was built up during execution."
+  s.version = "0.6.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."
 
   s.authors = ["Hubbado Devs"]
   s.email = ["devs@hubbado.com"]

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

@@ -13,7 +13,7 @@ module Hubbado
           def call(ctx, contract_class, attr_name = nil)
             model = attr_name && Path.resolve(ctx, attr_name)
             ctx[:contract] = contract_class.new(model)
-            Result.ok(ctx)
+            Result.success(ctx)
           end
 
           module Substitute
@@ -31,10 +31,10 @@ module Hubbado
             end
 
             record def call(ctx, contract_class, attr_name = nil)
-              return Result.fail(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
               ctx[:contract] = @return_value if @configured_success
-              Result.ok(ctx)
+              Result.success(ctx)
             end
 
             def built?(**kwargs)

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

@@ -15,7 +15,7 @@ module Hubbado
 
             ctx[:contract].deserialize(params) if params
 
-            Result.ok(ctx)
+            Result.success(ctx)
           end
 
           module Substitute
@@ -27,9 +27,9 @@ module Hubbado
             end
 
             record def call(ctx, from:)
-              return Result.fail(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
-              Result.ok(ctx)
+              Result.success(ctx)
             end
 
             def deserialized?(**kwargs)

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

@@ -14,9 +14,9 @@ module Hubbado
             contract = ctx[:contract]
 
             if contract.save
-              Result.ok(ctx)
+              Result.success(ctx)
             else
-              Result.fail(ctx, error: { code: :persist_failed })
+              Result.failure(ctx, code: :persist_failed)
             end
           end
 
@@ -34,9 +34,9 @@ module Hubbado
             end
 
             record def call(ctx)
-              return Result.fail(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
-              Result.ok(ctx)
+              Result.success(ctx)
             end
 
             def persisted?(**kwargs)

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

@@ -17,9 +17,9 @@ module Hubbado
             contract.validate(params)
 
             if contract.errors.empty?
-              Result.ok(ctx)
+              Result.success(ctx)
             else
-              Result.fail(ctx, error: { code: :validation_failed })
+              Result.failure(ctx, code: :validation_failed)
             end
           end
 
@@ -37,9 +37,9 @@ module Hubbado
             end
 
             record def call(ctx, from: nil)
-              return Result.fail(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
-              Result.ok(ctx)
+              Result.success(ctx)
             end
 
             def validated?(**kwargs)

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

@@ -17,7 +17,7 @@ module Hubbado
               else
                 model.new(attributes)
               end
-            Result.ok(ctx)
+            Result.success(ctx)
           end
 
           module Substitute
@@ -40,10 +40,10 @@ module Hubbado
                   "Macros::Model::Build substitute: #{model} does not respond to :new"
               end
 
-              return Result.fail(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
               ctx[as] = @return_value if @configured_success
-              Result.ok(ctx)
+              Result.success(ctx)
             end
 
             def built?(**kwargs)

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

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

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

@@ -18,14 +18,12 @@ module Hubbado
             policy_result = policy_instance.public_send(action)
 
             if policy_result.permitted?
-              Result.ok(ctx)
+              Result.success(ctx)
             else
-              Result.fail(
+              Result.failure(
                 ctx,
-                error: {
-                  code: :forbidden,
-                  data: { policy: policy_instance, policy_result: policy_result }
-                }
+                code: :forbidden,
+                data: { policy: policy_instance, policy_result: policy_result }
               )
             end
           end
@@ -49,9 +47,9 @@ module Hubbado
                   "Macros::Policy::Check substitute: #{policy} does not declare action :#{action}"
               end
 
-              return Result.fail(ctx, error: @configured_error) if @configured_error
+              return Result.failure(ctx, **@configured_error) if @configured_error
 
-              Result.ok(ctx)
+              Result.success(ctx)
             end
 
             def checked?(**kwargs)

data/lib/hubbado/sequence/pipeline.rb

@@ -6,15 +6,15 @@ module Hubbado
     class Pipeline
       def initialize(ctx, dispatcher:)
         @ctx = ctx
-        @trail = []
+        @successful_steps = []
         @failed_result = nil
         @dispatcher = dispatcher
       end
 
       # `step(:name)` dispatches to `dispatcher.send(name, ctx)`. The method
       # is treated as successful unless it explicitly returns a failed
-      # `Result`; any other return value (nil, false, a model, `Result.ok`)
-      # continues the pipeline with the same ctx. Only `Result.fail(...)` /
+      # `Result`; any other return value (nil, false, a model, `Result.success`)
+      # continues the pipeline with the same ctx. Only `Result.failure(...)` /
       # `failure(ctx, code: ...)` short-circuits.
       def step(name)
         return self if @failed_result
@@ -25,7 +25,7 @@ module Hubbado
 
       # `invoke(:name, *args, **kwargs)` calls a declared dependency on the
       # dispatcher: gets it via `dispatcher.send(name)` (the reader), then
-      # invokes it with `(ctx, *args, **kwargs)`. Same trail recording,
+      # invokes it with `(ctx, *args, **kwargs)`. Same step recording,
       # failure short-circuiting, and lenient return convention as `step`.
       #
       # Use this for any declared dependency — macros
@@ -58,7 +58,7 @@ module Hubbado
         if @failed_result
           @failed_result
         else
-          Result.ok(@ctx, trail: @trail.dup)
+          Result.success(@ctx, successful_steps: @successful_steps.dup)
         end
       end
 
@@ -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
-          @trail << name
+          @successful_steps << name
         end
       end
-
-      def tag_failure(result, step_name)
-        tagged_error = result.error.merge(step: step_name)
-        Result.fail(result.ctx, error: tagged_error, trail: @trail.dup, i18n_scope: result.i18n_scope)
-      end
     end
   end
 end

data/lib/hubbado/sequence/result.rb

@@ -4,68 +4,107 @@ module Hubbado
       FRAMEWORK_I18N_SCOPE = "sequence.errors".freeze
 
       attr_reader :ctx
-      attr_reader :error
-      attr_reader :trail
+      attr_reader :code
+      attr_reader :data
+      attr_reader :step
+      attr_reader :successful_steps
       attr_reader :i18n_scope
-
-      def self.ok(ctx, trail: [], i18n_scope: nil)
-        new(:ok, ctx, error: nil, trail: trail, i18n_scope: i18n_scope)
+      attr_reader :i18n_key
+      attr_reader :i18n_args
+
+      def self.success(ctx, successful_steps: [], i18n_scope: nil)
+        new(
+          :success,
+          ctx: ctx,
+          successful_steps: successful_steps,
+          i18n_scope: i18n_scope
+        )
       end
 
-      def self.fail(ctx, error:, trail: [], i18n_scope: nil)
-        unless error.is_a?(Hash) && error[:code]
-          raise ArgumentError, "Result.fail requires error: { code: ... }"
-        end
-
-        new(:fail, ctx, error: error, trail: trail, 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:, trail:, 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
-        @trail = trail
+        @code = code
+        @data = data
+        @step = step
+        @successful_steps = successful_steps
         @i18n_scope = i18n_scope
+        @i18n_key = i18n_key
+        @i18n_args = i18n_args
       end
 
-      def ok?
-        @status == :ok
+      def success?
+        @status == :success
       end
 
       def failure?
-        @status == :fail
+        @status == :failure
       end
 
-      def with_trail(trail)
-        self.class.new(@status, @ctx, error: @error, trail: trail, i18n_scope: @i18n_scope)
+      def with_successful_steps(successful_steps)
+        copy(successful_steps: successful_steps)
       end
 
       def with_i18n_scope(scope)
         return self unless @i18n_scope.nil?
 
-        self.class.new(@status, @ctx, error: @error, trail: @trail, i18n_scope: scope)
+        copy(i18n_scope: scope)
       end
 
-      def message
-        return nil if ok?
+      def with_step(step)
+        copy(step: step)
+      end
 
-        translation = translate_with_chain
-        return translation if translation
+      def message
+        return nil if success?
 
-        @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,48 +33,73 @@ 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.ok?
+          return unless @result.success?
           execute { yield(@result.ctx) }
-          logger.info("Sequencer #{@sequencer_class.name} succeeded: #{trail_summary}")
+          logger.info("Sequencer #{@sequencer_class.name} succeeded: #{steps_summary}")
         end
 
         def policy_failed
           return unless code == :forbidden
           execute { yield(@result.ctx) }
-          logger.info("Sequencer #{@sequencer_class.name} policy failed at #{step_label} (#{code}): #{trail_summary}")
+          logger.info("Sequencer #{@sequencer_class.name} policy failed at #{step_label} (#{code}): #{steps_summary}")
         end
 
         def not_found
           return unless code == :not_found
           execute { yield(@result.ctx) }
-          logger.info("Sequencer #{@sequencer_class.name} not found at #{step_label}: #{trail_summary}")
+          logger.info("Sequencer #{@sequencer_class.name} not found at #{step_label}: #{steps_summary}")
         end
 
         def validation_failed
           return unless code == :validation_failed
           execute { yield(@result.ctx) }
-          logger.info("Sequencer #{@sequencer_class.name} validation failed at #{step_label}: #{trail_summary}")
+          logger.info("Sequencer #{@sequencer_class.name} validation failed at #{step_label}: #{steps_summary}")
         end
 
         # otherwise deliberately does not catch policy denials or not_found —
         # those have their own required handlers.
         def otherwise
-          return if @result.ok?
+          return if @result.success?
           return if code == :forbidden
           return if code == :not_found
           return if @handled
 
           execute { yield(@result.ctx) }
-          logger.info("Sequencer #{@sequencer_class.name} failed at #{step_label} (#{code}): #{trail_summary}")
+          logger.info("Sequencer #{@sequencer_class.name} failed at #{step_label} (#{code}): #{steps_summary}")
         end
 
-        def code
-          @result.error&.[](:code)
+        def handled?
+          @result.success? || @handled
         end
 
-        def handled?
-          @result.ok? || @handled
+        # 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!
@@ -83,20 +108,14 @@ module Hubbado
           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
 
         def log_unhandled
-          logger.error("Sequencer #{@sequencer_class.name} failed unhandled at #{step_label} (#{code}): #{trail_summary}")
+          logger.error("Sequencer #{@sequencer_class.name} failed unhandled at #{step_label} (#{code}): #{steps_summary}")
         end
 
         private
@@ -106,12 +125,11 @@ module Hubbado
           @returned = yield
         end
 
-        def trail_summary
-          @result.trail.empty? ? "(no steps)" : @result.trail.map(&:to_s).join(" → ")
+        def steps_summary
+          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
@@ -173,9 +192,9 @@ module Hubbado
 
           if outcome[:kind] == :success
             outcome[:ctx_writes].each { |key, value| ctx[key] = value }
-            Hubbado::Sequence::Result.ok(ctx)
+            Hubbado::Sequence::Result.success(ctx)
           else
-            Hubbado::Sequence::Result.fail(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,12 +34,12 @@ module Hubbado
           end
 
           record def call(ctx)
-            return ::Hubbado::Sequence::Result.fail(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 }
             end
-            ::Hubbado::Sequence::Result.ok(ctx)
+            ::Hubbado::Sequence::Result.success(ctx)
           end
 
           def called?(**kwargs)
@@ -83,7 +83,8 @@ module Hubbado
       end
 
       def failure(ctx, **error_attrs)
-        Result.fail(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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hubbado-sequence
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Hubbado Devs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-15 00:00:00.000000000 Z
+date: 2026-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: evt-casing
@@ -164,9 +164,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Sequencer takes input, runs a sequence of steps, and returns a Result
-  indicating success or failure plus the working context that was built up during
-  execution.
+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.
 email:
 - devs@hubbado.com
 executables: []
@@ -223,5 +223,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: A small framework for orchestrating units of business behaviour
+summary: A small framework for the short sequences of common steps that controller
+  actions usually boil down to
 test_files: []