hubbado-sequence 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 225c967e73e28a28effbc26e9c3bbdfce3357932a8374046dc46056d0dd8dd7d
-  data.tar.gz: 7a446faedf4bb88018c17a6130f29ec85f1fc354929864aaa2dd55f86753ffca
+  metadata.gz: 7f708335623135a67d05ecdf13e49c97f9d0a1d1a2c21c2fda731f83c69ecc65
+  data.tar.gz: 011fcaa92a23f287b8800da473f37452c9305bd08a0e00833811817b50d858db
 SHA512:
-  metadata.gz: f5ae7e6141a9d45576b0b93a0c25ac23a63a9d3a5b4ea5ba134103a91db20633a17a1dc4e41a7a73570dc6745446d55e4e22612249dd75211d9c2be1c02a3143
-  data.tar.gz: a741030d0046941b128a18bc8bb0f58f10bdb677cd8941857d8937263e4dd2c58aaaac6fd2c816deac3f8d310a256c67af516dc7e8428aa3e5e29791cafa3676
+  metadata.gz: 440e563ba5e86174e51c186ca365d30f7160a93ca4d4d79669d23e0461acfc1030261b63d109223e5a37129cefc4c5c0cfd6433219dd0edf3be2d7c9576048e5
+  data.tar.gz: c5a884e0a781e0b9794a3997ba1eaadbd03eeceaf02289ee33cab2528686281d89016ef9f82e7e04d6b71be5ce4378dc81336c5c7e1866e32d6b0f0f01cdff54

data/CHANGELOG.md

@@ -4,6 +4,54 @@ 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.5.0] - Result vocabulary renamed: success/failure and successful_steps
+
+### Changed (breaking)
+
+- **`Result.ok` → `Result.success`** and **`Result.fail` → `Result.failure`**.
+  Aligns with the wider Ruby railway-oriented vocabulary (dry-monads,
+  dry-transaction) and replaces the asymmetric `ok`/`failure?` pair with a
+  consistent `success`/`failure` pair.
+
+  ```ruby
+  # before
+  Result.ok(ctx)
+  Result.fail(ctx, error: { code: :forbidden })
+  result.ok?
+
+  # after
+  Result.success(ctx)
+  Result.failure(ctx, error: { code: :forbidden })
+  result.success?
+  ```
+
+  `result.failure?` is unchanged.
+
+  Migration: search-and-replace `Result.ok(` → `Result.success(`,
+  `Result.fail(` → `Result.failure(`, and `.ok?` → `.success?`. RSpec
+  matchers `be_ok` become `be_success`.
+
+- **`Result#trail` → `Result#successful_steps`** (and `with_trail` →
+  `with_successful_steps`, `trail:` kwarg → `successful_steps:`). The old
+  name was confusing because the failing step is *not* in the list — it
+  lives on `error[:step]`. The new name says exactly what's there.
+
+  ```ruby
+  # before
+  result.trail               # => [:find, :build_contract]
+  result.with_trail([...])
+  Result.ok(ctx, trail: [...])
+
+  # after
+  result.successful_steps    # => [:find, :build_contract]
+  result.with_successful_steps([...])
+  Result.success(ctx, successful_steps: [...])
+  ```
+
+  Migration: search-and-replace `.trail` → `.successful_steps`,
+  `with_trail(` → `with_successful_steps(`, and the keyword argument
+  `trail:` → `successful_steps:`.
+
 ## [0.4.0] - Inline step blocks removed; Pipeline made internal
 
 ### Removed (breaking)

data/README.md

@@ -1,15 +1,23 @@
 # hubbado-sequence
 
-A small framework for orchestrating units of business behaviour. The eventual
-replacement for Trailblazer operations at Hubbado, designed to coexist with
-them during migration.
-
-A 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.
-
-The full design rationale lives in [`docs/design.md`](docs/design.md). This
-README is a quick tour.
+A small framework (about 200 lines of core code) for orchestrating the
+short sequences of common steps that controller actions usually boil
+down to — find a model, validate a contract, call a domain object, save
+something, redirect. 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.
+
+The DSL is deliberately minimal: every step is a regular method, every
+dependency is a regular Ruby object, and control flow uses regular Ruby
+(`if`, `unless`, `case`) rather than a conditional DSL. The framework
+gets out of the way once you've described the high-level sequence; the
+real work lives in the plain-Ruby objects the steps call.
+
+Built with Rails in mind but framework-agnostic — the core has no Rails
+dependency, and the included `RunSequence` mixin works in any host
+(controllers, jobs, scripts). The full design rationale lives in
+[`docs/design.md`](docs/design.md). This README is a quick tour.
 
 ## Installation
 
@@ -24,9 +32,8 @@ Then run `bundle install`.
 ## Requirements
 
 - Ruby >= 3.3
-- [evt-dependency](https://github.com/eventide-project/dependency) — powers
-  the injectable macro / nested-sequencer pattern (declared as a runtime
-  dependency of the gem).
+- [evt-dependency](https://github.com/eventide-project/dependency) —
+  dependency injection (declared as a runtime dependency of the gem).
 
 Optional, depending on which macros you use:
 
@@ -39,29 +46,59 @@ Optional, depending on which macros you use:
 
 ## Philosophy
 
-Sequencers sit at the controller boundary. They receive input from a Rails
-action, orchestrate the work, and hand a `Result` back. The sequencer's job
-is **orchestration only** — it should not contain business logic itself. Real
-behaviour lives in the models, contracts, policies, and domain objects it
-calls.
-
-Nesting is intentionally shallow. The only nesting we use in practice is a
-`Present` sequencer inside an `Update` sequencer: Present loads the record,
-builds the contract, and checks the policy; Update calls Present and then
-validates and persists. Chains longer than one level are rare enough to be a
-signal that something should be a plain Ruby object instead.
-
-The framework uses [evt-dependency](https://github.com/eventide-project/dependency),
-which means every macro and every nested sequencer is an injectable
-dependency. Calling `.new` on a sequencer installs substitutes for all of
-them, so unit tests exercise the sequencer's orchestration logic — what runs,
-in what order, what short-circuits — without hitting the database, the policy
-gem, or Reform. The substitutes default to pass-through `ok`, so a test only
-configures the outcomes that matter for the scenario it's verifying.
-
-Integration coverage (using `.build` to wire real collaborators) is reserved
-for the controller boundary — one happy-path integration test per sequencer
-is usually enough to confirm the wiring is correct.
+Sequencers sit at the controller boundary. They receive input, orchestrate
+the work, and hand a `Result` back. The sequencer's job is **orchestration
+only** — it should not contain business logic itself. Real behaviour lives
+in the models, contracts, policies, and domain objects it calls.
+
+The framework is built with Rails in mind but doesn't require it — the core
+of the gem has no Rails dependency, and `Hubbado::Sequence::RunSequence` is
+a plain mixin that works in any host that drives a sequencer from a fixed
+lifecycle (Sinatra actions, Rack handlers, Hanami actions, job workers).
+ActiveRecord and Reform are only needed if you use the macros that wrap
+them.
+
+In a Rails context the gem solves a specific pain: a controller action is
+hard to unit-test because the framework owns its lifecycle, and that gets
+worse the moment you want dependency injection. Sequencers lift the
+testable work *out* of the controller into a plain Ruby object that
+exposes its dependencies cleanly, and `run_sequence` keeps the controller
+itself thin — branching to redirect, render, or set a flash based on the
+sequencer's outcome.
+
+Most controller actions shouldn't contain much business logic anyway. They're
+a short sequence of common steps — find a model, validate a contract, save
+something, redirect. The sequencer DSL is designed to make that high-level
+sequence compact and easy to scan, without trying to be the home for the
+business logic underneath. Regular Ruby is already excellent at that.
+
+The DSL is deliberately minimal. A sequencer's `pipeline(ctx)` block is a
+small set of conventions around how `ctx` flows and what each step
+returns — nothing more. Steps are regular methods on a regular Ruby
+object, dependencies are regular Ruby objects, and the pipeline lets you
+use regular Ruby `if` / `unless` / `case` for control flow rather than
+inventing a conditional DSL. Where the framework can get out of your way,
+it does.
+
+The gem doesn't impose a nesting depth, but in practice we keep nesting
+very shallow — typically one level. The only nesting we use is a `Present`
+sequencer inside an `Update` sequencer: Present loads the record, builds
+the contract, and checks the policy; Update calls Present and then
+validates and persists. Anything deeper is a signal that a chunk of the
+work should be a plain Ruby object instead.
+
+The framework uses [evt-dependency](https://github.com/eventide-project/dependency)
+for dependency injection. Every macro and every nested sequencer is an
+injected dependency, which means calling `.new` on a sequencer installs
+substitutes for all of them. Unit tests exercise the sequencer's
+orchestration logic — what runs, in what order, what short-circuits —
+without hitting the database, the policy gem, or Reform. The substitutes
+default to pass-through success, so a test only configures the outcomes
+that matter for the scenario it's verifying.
+
+Integration coverage (using `.build` to wire real collaborators) is
+reserved for the controller boundary — one happy-path integration test
+per sequencer is usually enough to confirm the wiring is correct.
 
 ## Quick start
 
@@ -139,11 +176,14 @@ it directly.
 ## Built-in macros
 
 Each macro is a dependency declared on a sequencer with `dependency :name, Macros::...`
-and wired via `.configure(instance)` in `.build`.
+and wired via `.configure(instance)` in `.build`. The built-in macros are
+grouped by the gem they expect to be available.
 
-The model macros are designed to work with ActiveRecord models.
+### ActiveRecord macros
 
-### Model::Find
+Designed to work with [ActiveRecord](https://github.com/rails/rails) models.
+
+#### Model::Find
 
 Fetches a record using `model.find_by(id:)` and writes it to `ctx[as]`.
 
@@ -159,7 +199,7 @@ p.invoke(:find, User, as: :user, id_key: %i[params id])  # nested path (default)
 | **Writes** | `ctx[as]` — the found record |
 | **Fails** | `:not_found` when `find_by` returns nil |
 
-### Model::Build
+#### Model::Build
 
 Instantiates a new record and writes it to `ctx[as]`.
 
@@ -174,9 +214,12 @@ p.invoke(:build_record, User, as: :user, attributes: { role: :admin })
 | **Writes** | `ctx[as]` — the new instance |
 | **Fails** | never |
 
-The contract macros are designed to work with [Reform](https://github.com/trailblazer/reform) form objects.
+### Reform macros
+
+Designed to work with [Reform](https://github.com/trailblazer/reform) form
+objects (contracts).
 
-### Contract::Build
+#### Contract::Build
 
 Wraps a model in a contract and writes it to `ctx[:contract]`.
 
@@ -191,7 +234,7 @@ p.invoke(:build_contract, Contracts::CreateUser)         # no model
 | **Writes** | `ctx[:contract]` |
 | **Fails** | never |
 
-### Contract::Deserialize
+#### Contract::Deserialize
 
 Deserializes params into the contract via `contract.deserialize(params)`.
 
@@ -206,7 +249,7 @@ p.invoke(:deserialize_to_contract, from: :raw_params)
 | **Writes** | nothing (mutates the contract in place) |
 | **Fails** | never (no-op when the `from:` path is absent) |
 
-### Contract::Validate
+#### Contract::Validate
 
 Validates the contract via `contract.validate(params)` and checks `errors`.
 
@@ -221,7 +264,7 @@ p.invoke(:validate)   # contract already deserialized; passes empty params
 | **Writes** | nothing (populates `contract.errors` on invalid) |
 | **Fails** | `:validation_failed` when `contract.errors` is non-empty |
 
-### Contract::Persist
+#### Contract::Persist
 
 Saves the contract via `contract.save`.
 
@@ -235,7 +278,12 @@ p.invoke(:persist)
 | **Writes** | nothing |
 | **Fails** | `:persist_failed` when `save` returns false |
 
-### Policy::Check
+### hubbado-policy macros
+
+Designed to work with the
+[hubbado-policy](https://github.com/hubbado/hubbado-policy) gem.
+
+#### Policy::Check
 
 Builds a policy and calls the named action to authorise the operation.
 
@@ -243,9 +291,9 @@ Builds a policy and calls the named action to authorise the operation.
 p.invoke(:check_policy, Policies::User, :user, :update)
 ```
 
-Designed to work with the [hubbado-policy](https://github.com/hubbado/hubbado-policy) gem.
-The policy class must respond to `.build(current_user, record)`; the instance must
-respond to the action method and return an object with `permitted?`.
+The policy class must respond to `.build(current_user, record)`; the
+instance must respond to the action method and return an object with
+`permitted?`.
 
 | | |
 |---|---|
@@ -293,46 +341,46 @@ as part of the same pipeline.
 
 The "find the record, build the contract, check the policy" shape is shared
 between an edit form and an update action — both need exactly that, and the
-update then validates and persists. Extract the shared part as a Present
-sequencer and nest it as a dependency:
+update then validates and persists. Define Present as a nested class on the
+outer sequencer so the two stay co-located:
 
 ```ruby
-class Seqs::PresentUser
-  include Hubbado::Sequence::Sequencer
+class Seqs::UpdateUser
+  class Present
+    include Hubbado::Sequence::Sequencer
 
-  configure :present   # so a parent can use `Seqs::PresentUser.configure(instance)`
+    configure :present   # so a parent can use `Present.configure(instance)`
 
-  dependency :find,           Macros::Model::Find
-  dependency :build_contract, Macros::Contract::Build
-  dependency :check_policy,   Macros::Policy::Check
+    dependency :find,           Macros::Model::Find
+    dependency :build_contract, Macros::Contract::Build
+    dependency :check_policy,   Macros::Policy::Check
 
-  def self.build
-    new.tap do |instance|
-      Macros::Model::Find.configure(instance)
-      Macros::Contract::Build.configure(instance)
-      Macros::Policy::Check.configure(instance)
+    def self.build
+      new.tap do |instance|
+        Macros::Model::Find.configure(instance)
+        Macros::Contract::Build.configure(instance)
+        Macros::Policy::Check.configure(instance)
+      end
     end
-  end
 
-  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)
+    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)
+      end
     end
   end
-end
 
-class Seqs::UpdateUser
   include Hubbado::Sequence::Sequencer
 
-  dependency :present,  Seqs::PresentUser
+  dependency :present,  Present
   dependency :validate, Macros::Contract::Validate
   dependency :persist,  Macros::Contract::Persist
 
   def self.build
     new.tap do |instance|
-      Seqs::PresentUser.configure(instance)
+      Present.configure(instance)
       Macros::Contract::Validate.configure(instance)
       Macros::Contract::Persist.configure(instance)
     end
@@ -359,7 +407,7 @@ class UsersController < ApplicationController
   include Hubbado::Sequence::RunSequence
 
   def edit
-    run_sequence Seqs::PresentUser, params: params, current_user: current_user do |result|
+    run_sequence Seqs::UpdateUser::Present, params: params, current_user: current_user do |result|
       result.success       { |ctx| render :edit, locals: { contract: ctx[:contract] } }
       result.policy_failed { |_|   redirect_to root_path, alert: result.message }
       result.not_found     { |_|   render_404 }
@@ -379,15 +427,15 @@ end
 
 Inner writes (`ctx[:user]`, `ctx[:contract]`) are visible to outer steps —
 Present and Update share the same `Ctx`, so `:validate` and `:persist` see
-exactly what Present built. The outer trail records `:present` as a single
-step; Present's inner steps stay opaque to the parent.
+exactly what Present built. The outer pipeline records `:present` as a single
+entry in `successful_steps`; Present's inner steps stay opaque to the parent.
 
 ## Result, success, failure
 
 A step is **successful unless it explicitly returns a failed `Result`**. Any
-other return value (`nil`, `false`, a model, `Result.ok(...)`) is taken as
+other return value (`nil`, `false`, a model, `Result.success(...)`) is taken as
 success and the pipeline continues with the same `ctx`. Only
-`Result.fail(...)` or the `failure(ctx, code: ...)` helper short-circuits.
+`Result.failure(...)` or the `failure(ctx, code: ...)` helper short-circuits.
 
 ```ruby
 def call(ctx)
@@ -401,7 +449,7 @@ private
 
 def must_be_premium(ctx)
   return failure(ctx, code: :forbidden) unless ctx[:user].premium?
-  # implicit ok if we get here
+  # implicit success if we get here
 end
 ```
 
@@ -412,46 +460,65 @@ same error attrs as the underlying error hash (`code:`, `i18n_key:`,
 
 ## Testing
 
-`described_class.new` returns a sequencer with all dependencies installed as
-substitutes. Tests configure the substitutes for the scenario at hand.
-`described_class.build` runs the production wiring (the real macros).
-Substitutes default to pass-through `Result.ok(ctx)` so a test only
+The gem doesn't prescribe a testing library — sequencers, macros, and
+substitutes are plain Ruby objects that work with whatever you use.
+The examples below are written in
+[TestBench](https://github.com/test-bench/test-bench) (what we use at
+Hubbado), but the same patterns translate directly to RSpec, Minitest,
+or any other framework.
+
+`Seqs::UpdateUser.new` returns a sequencer with all dependencies installed
+as substitutes. Tests configure the substitutes for the scenario at hand.
+`Seqs::UpdateUser.build` runs the production wiring (the real macros).
+Substitutes default to pass-through `Result.success(ctx)` so a test only
 configures the ones whose return matters.
 
 ### Substituting macros directly
 
 ```ruby
-RSpec.describe Seqs::PresentUser do
-  it "loads the user, builds the contract, and passes the policy" do
-    seq = described_class.new
-    user     = User.new(id: 1, email: "old@example.com")
-    contract = Contracts::UpdateUser.new(user)
-    seq.find.succeed_with(user)
-    seq.build_contract.succeed_with(contract)
-
-    result = seq.(Hubbado::Sequence::Ctx.build(
-      params:       { id: 1 },
-      current_user: User.new
-    ))
-
-    expect(result).to be_ok
-    expect(seq.find.fetched?(as: :user)).to be true
-    expect(seq.build_contract.built?).to be true
-    expect(seq.check_policy.checked?).to be true
+context "Seqs::UpdateUser::Present happy path" do
+  user     = User.new(id: 1, email: "old@example.com")
+  contract = Contracts::UpdateUser.new(user)
+
+  seq = Seqs::UpdateUser::Present.new
+  seq.find.succeed_with(user)
+  seq.build_contract.succeed_with(contract)
+
+  result = seq.(params: { id: 1 }, current_user: User.new)
+
+  test "Is success" do
+    assert(result.success?)
   end
 
-  it "fails with :not_found when the user doesn't exist" do
-    seq = described_class.new
-    seq.find.fail_with(code: :not_found)
+  test "Fetched the user from ctx[:user]" do
+    assert(seq.find.fetched?(as: :user))
+  end
 
-    result = seq.(Hubbado::Sequence::Ctx.build(
-      params:       { id: 999 },
-      current_user: User.new
-    ))
+  test "Built the contract" do
+    assert(seq.build_contract.built?)
+  end
 
-    expect(result.error[:code]).to eq(:not_found)
-    expect(seq.build_contract.built?).to be false
-    expect(seq.check_policy.checked?).to be false
+  test "Checked the policy" do
+    assert(seq.check_policy.checked?)
+  end
+end
+
+context "Seqs::UpdateUser::Present when the user is not found" do
+  seq = Seqs::UpdateUser::Present.new
+  seq.find.fail_with(code: :not_found)
+
+  result = seq.(params: { id: 999 }, current_user: User.new)
+
+  test "Fails with :not_found" do
+    assert(result.error[:code] == :not_found)
+  end
+
+  test "Does not build the contract" do
+    refute(seq.build_contract.built?)
+  end
+
+  test "Does not check the policy" do
+    refute(seq.check_policy.checked?)
   end
 end
 ```
@@ -464,84 +531,104 @@ Every sequencer ships a default `Substitute` module (installed by
 short-circuit a nested sequencer without reaching into its inner pieces:
 
 ```ruby
-RSpec.describe Seqs::UpdateUser do
-  it "updates the user when present succeeds" do
-    seq = described_class.new
-
-    user     = User.new(id: 1, email: "old@example.com")
-    contract = Contracts::UpdateUser.new(user)
-    seq.present.succeed_with(user: user, contract: contract)
-
-    result = seq.(Hubbado::Sequence::Ctx.build(
-      params:       { user: { email: "new@example.com" } },
-      current_user: User.new
-    ))
-
-    expect(result).to be_ok
-    expect(seq.present.called?).to be true
-    expect(seq.persist.persisted?).to be true
+context "Seqs::UpdateUser happy path" do
+  user     = User.new(id: 1, email: "old@example.com")
+  contract = Contracts::UpdateUser.new(user)
+
+  seq = Seqs::UpdateUser.new
+  seq.present.succeed_with(user: user, contract: contract)
+
+  result = seq.(
+    params:       { user: { email: "new@example.com" } },
+    current_user: User.new
+  )
+
+  test "Is success" do
+    assert(result.success?)
   end
 
-  it "stops when present denies access" do
-    seq = described_class.new
-    seq.present.fail_with(code: :forbidden)
+  test "Calls Present" do
+    assert(seq.present.called?)
+  end
 
-    result = seq.(Hubbado::Sequence::Ctx.build(
-      params:       { user: {} },
-      current_user: User.new
-    ))
+  test "Persists the contract" do
+    assert(seq.persist.persisted?)
+  end
+end
+
+context "Seqs::UpdateUser when Present denies access" do
+  seq = Seqs::UpdateUser.new
+  seq.present.fail_with(code: :forbidden)
+
+  result = seq.(params: { user: {} }, current_user: User.new)
+
+  test "Fails" do
+    assert(result.failure?)
+  end
+
+  test "Fails with :forbidden" do
+    assert(result.error[:code] == :forbidden)
+  end
 
-    expect(result.failure?).to be true
-    expect(result.error[:code]).to eq(:forbidden)
-    expect(seq.validate.validated?).to be false
-    expect(seq.persist.persisted?).to be false
+  test "Does not validate" do
+    refute(seq.validate.validated?)
   end
 
-  it "stops when present cannot find the record" do
-    seq = described_class.new
-    seq.present.fail_with(code: :not_found)
+  test "Does not persist" do
+    refute(seq.persist.persisted?)
+  end
+end
+
+context "Seqs::UpdateUser when Present cannot find the record" do
+  seq = Seqs::UpdateUser.new
+  seq.present.fail_with(code: :not_found)
+
+  result = seq.(params: { id: 999, user: {} }, current_user: User.new)
 
-    result = seq.(Hubbado::Sequence::Ctx.build(
-      params:       { id: 999, user: {} },
-      current_user: User.new
-    ))
+  test "Fails with :not_found" do
+    assert(result.error[:code] == :not_found)
+  end
+
+  test "Does not validate" do
+    refute(seq.validate.validated?)
+  end
 
-    expect(result.error[:code]).to eq(:not_found)
-    expect(seq.validate.validated?).to be false
-    expect(seq.persist.persisted?).to be false
+  test "Does not persist" do
+    refute(seq.persist.persisted?)
   end
 end
 ```
 
 `succeed_with(**ctx_writes)` writes the given keys into `ctx` and returns
-`Result.ok(ctx)`, so the outer steps see what the real Present would have
+`Result.success(ctx)`, so the outer steps see what the real Present would have
 left behind. `fail_with(**error)` returns a failed `Result` with the given
 error, short-circuiting the outer pipeline. The Update spec doesn't need
 to exercise Find / Build / Policy::Check directly — those live in
-PresentUser's spec, where they belong.
+`Seqs::UpdateUser::Present`'s spec, where they belong.
 
 ## Observability
 
-Every `Result` carries a **trail** — the list of step names that completed
-successfully, in order. On failure, the failing step is *not* in the trail;
-it's tagged on `error[:step]` instead.
+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.
 
 ```ruby
-result.trail         # => [:find, :build_contract, :check_policy, :validate, :persist]  # success
-result.trail         # => [:find, :build_contract]                                       # failed at :check_policy
-result.error[:step]  # => :check_policy
+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
 ```
 
 When invoked via `run_sequence`, the dispatcher logs a single line per
-invocation summarising the trail and (on failure) where it stopped:
+invocation summarising the successful steps and (on failure) where it
+stopped:
 
 ```
 Sequencer Seqs::UpdateUser succeeded: find → build_contract → check_policy → validate → persist
 Sequencer Seqs::UpdateUser failed at :check_policy (forbidden): find → build_contract
 ```
 
-Nested sequencer trails are opaque to the parent: a parent's trail shows
-`:present` as a single step, not the sub-steps inside Present.
+Nested sequencer steps are opaque to the parent: a parent's `successful_steps`
+lists `:present` once, not Present's inner sub-steps.
 `error[:step]` carries the inner step name when a nested sequencer fails.
 
 ## Standard error codes
@@ -563,4 +650,4 @@ Sequencers can mint their own codes for domain-specific failures
 
 ## License
 
-Internal Hubbado gem.
+Released under the [MIT License](LICENSE).

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.5.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, error: @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, error: @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, error: { 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, error: @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, error: { 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, error: @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, error: @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, error: { 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, error: @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,9 +18,9 @@ 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,
@@ -49,9 +49,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, error: @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
 
@@ -86,13 +86,13 @@ module Hubbado
         if return_value.is_a?(Result) && return_value.failure?
           @failed_result = tag_failure(return_value, name)
         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)
+        Result.failure(result.ctx, error: tagged_error, successful_steps: @successful_steps.dup, i18n_scope: result.i18n_scope)
       end
     end
   end

data/lib/hubbado/sequence/result.rb

@@ -5,49 +5,49 @@ module Hubbado
 
       attr_reader :ctx
       attr_reader :error
-      attr_reader :trail
+      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)
+      def self.success(ctx, successful_steps: [], i18n_scope: nil)
+        new(:success, ctx, error: nil, successful_steps: successful_steps, i18n_scope: i18n_scope)
       end
 
-      def self.fail(ctx, error:, trail: [], i18n_scope: nil)
+      def self.failure(ctx, error:, successful_steps: [], i18n_scope: nil)
         unless error.is_a?(Hash) && error[:code]
-          raise ArgumentError, "Result.fail requires error: { code: ... }"
+          raise ArgumentError, "Result.failure requires error: { code: ... }"
         end
 
-        new(:fail, ctx, error: error, trail: trail, i18n_scope: i18n_scope)
+        new(:failure, ctx, error: error, successful_steps: successful_steps, i18n_scope: i18n_scope)
       end
 
-      def initialize(status, ctx, error:, trail:, i18n_scope:)
+      def initialize(status, ctx, error:, successful_steps:, i18n_scope:)
         @status = status
         @ctx = ctx
         @error = error
-        @trail = trail
+        @successful_steps = successful_steps
         @i18n_scope = i18n_scope
       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)
+        self.class.new(@status, @ctx, error: @error, successful_steps: successful_steps, i18n_scope: @i18n_scope)
       end
 
       def with_i18n_scope(scope)
         return self unless @i18n_scope.nil?
 
-        self.class.new(@status, @ctx, error: @error, trail: @trail, i18n_scope: scope)
+        self.class.new(@status, @ctx, error: @error, successful_steps: @successful_steps, i18n_scope: scope)
       end
 
       def message
-        return nil if ok?
+        return nil if success?
 
         translation = translate_with_chain
         return translation if translation

data/lib/hubbado/sequence/runner.rb

@@ -34,39 +34,39 @@ module Hubbado
         end
 
         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
@@ -74,7 +74,7 @@ module Hubbado
         end
 
         def handled?
-          @result.ok? || @handled
+          @result.success? || @handled
         end
 
         def enforce_safety_nets!
@@ -96,7 +96,7 @@ module Hubbado
         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,8 +106,8 @@ module Hubbado
           @returned = yield
         end
 
-        def trail_summary
-          @result.trail.empty? ? "(no steps)" : @result.trail.map(&:to_s).join(" → ")
+        def steps_summary
+          @result.successful_steps.empty? ? "(no steps)" : @result.successful_steps.map(&:to_s).join(" → ")
         end
 
         def step_label
@@ -173,9 +173,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, error: outcome[:error])
           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, error: @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,7 @@ module Hubbado
       end
 
       def failure(ctx, **error_attrs)
-        Result.fail(ctx, error: error_attrs, i18n_scope: i18n_scope)
+        Result.failure(ctx, error: error_attrs, i18n_scope: i18n_scope)
       end
 
       # Builds a Pipeline that auto-dispatches blockless `step(:foo)` calls to

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hubbado-sequence
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Hubbado Devs
@@ -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: []