flow_chat 0.8.2 → 0.10.0

data/CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing to Plutonium
+
+## Commit Message Convention
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/) for automated changelog generation and versioning.
+
+### Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+- **feat**: A new feature (triggers MINOR version bump)
+- **fix**: A bug fix (triggers PATCH version bump)
+- **docs**: Documentation only changes
+- **style**: Changes that don't affect code meaning (formatting, etc)
+- **refactor**: Code change that neither fixes a bug nor adds a feature
+- **perf**: Performance improvement
+- **test**: Adding or updating tests
+- **chore**: Maintenance tasks (dependencies, tooling, etc)
+
+### Breaking Changes
+
+Add `BREAKING CHANGE:` in the footer or `!` after type to trigger a MAJOR version bump:
+
+```
+feat!: remove deprecated API
+
+BREAKING CHANGE: The old API has been removed. Use new API instead.
+```
+
+### Examples
+
+```bash
+# Feature (bumps 0.26.11 -> 0.27.0)
+git commit -m "feat: add field-level options support for input definitions"
+
+# Bug fix (bumps 0.26.11 -> 0.26.12)
+git commit -m "fix: resolve inheritance issue with controller_for"
+
+# Breaking change (bumps 0.26.11 -> 1.0.0)
+git commit -m "feat!: redesign definition DSL
+
+BREAKING CHANGE: The definition DSL has been completely redesigned.
+See migration guide for details."
+
+# With scope
+git commit -m "feat(ui): add new table component"
+git commit -m "fix(forms): correct hint display on validation errors"
+
+# Documentation
+git commit -m "docs: update definition structure guide"
+```
+
+## Release Process
+
+### Option 1: Automated (Recommended)
+
+```bash
+# See what the next version should be
+rake release:next_version
+
+# Prepare a new release (updates version, generates changelog)
+rake release:prepare[0.27.0]
+
+# Review changes
+git diff
+
+# Full automated release (prepare, commit, tag, push, publish)
+rake release:full[0.27.0]
+```
+
+### Option 2: Manual
+
+```bash
+# 1. Update version in lib/plutonium/version.rb
+# 2. Generate changelog
+git-cliff --tag v0.27.0 -o CHANGELOG.md
+
+# 3. Commit and tag
+git add -A
+git commit -m "chore(release): prepare for v0.27.0"
+git tag v0.27.0
+git push origin main --tags
+
+# 4. GitHub Actions will automatically publish to RubyGems
+```
+
+## Version Bumping Rules
+
+Following semantic versioning:
+
+- **MAJOR** (X.0.0): Breaking changes
+- **MINOR** (0.X.0): New features (backwards compatible)
+- **PATCH** (0.0.X): Bug fixes (backwards compatible)
+
+The automation determines the version bump based on commits since the last tag:
+- Any commit with `BREAKING CHANGE:` or `!` after type → MAJOR
+- Any `feat:` commits → MINOR
+- Any `fix:` commits → PATCH
+
+## Development Setup
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Install git-cliff for changelog generation (optional)
+brew install git-cliff  # macOS
+# or
+cargo install git-cliff  # via Rust
+```
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Make your changes with conventional commits
+4. Run tests: `bundle exec rspec`
+5. Push and create a pull request
+6. The PR title should also follow conventional commit format
+
+## Questions?
+
+Open an issue or discussion on GitHub!

data/Gemfile

@@ -8,3 +8,4 @@ gem "minitest", "~> 5.0"
 gem "minitest-reporters", "~> 1.4"
 gem "ostruct"
 gem "webmock", "~> 3.18"
+gem "standard", "~> 1.3"

data/README.md

@@ -3,207 +3,263 @@
 [![CI](https://github.com/radioactive-labs/flow_chat/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/radioactive-labs/flow_chat/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/flow_chat.svg)](https://badge.fury.io/rb/flow_chat)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.3.0-red.svg)](https://www.ruby-lang.org/)
-[![Rails](https://img.shields.io/badge/rails-%3E%3D%206.0-red.svg)](https://rubyonrails.org/)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-red.svg)](https://www.ruby-lang.org/)
 
-FlowChat is a Rails framework for building sophisticated conversational workflows for USSD and WhatsApp messaging. Define multi-step conversations as Ruby classes with automatic session management, input validation, and cross-platform compatibility.
+**Write a conversation as an ordinary Ruby method. FlowChat runs it across stateless webhooks, on every messaging channel.**
 
-## Key Features
+A USSD or chat webhook is stateless: each message arrives as an isolated POST with no memory of the ones before it. The usual answer is a hand-rolled state machine: persist the current step, switch on it when the next message comes in, run the transition, persist the next step, repeat. FlowChat replaces that machine with a session and a replay engine, so you write the flow as a synchronous script that reads top to bottom.
 
-- 🎯 **Declarative Flow Definition** - Define conversations as Ruby classes
-- 🔄 **Automatic Session Management** - Persistent state across requests  
-- ✅ **Input Validation & Transformation** - Built-in validation and data conversion
-- 📱 **USSD & WhatsApp Support** - Single codebase, multiple platforms
-- 💬 **Rich WhatsApp Features** - Interactive buttons, lists, media support
-- 🔧 **Standalone WhatsApp Client** - Send messages outside of flows
-- 📊 **Built-in Instrumentation** - Monitoring and metrics out of the box
-- 🧪 **Testing Tools** - Built-in simulator for development and testing
+```ruby
+class RegistrationFlow < FlowChat::Flow
+  def main_page
+    name = app.screen(:name) { |prompt| prompt.ask "What's your name?" }
+
+    email = app.screen(:email) do |prompt|
+      prompt.ask "Your email?", validate: ->(input) { "Invalid email" unless input.include?("@") }
+    end
+
+    app.say "Welcome #{name}!"
+  end
+end
+```
+
+Each `screen` returns its stored answer when one exists and re-prompts when it does not. The method runs top to bottom on every turn and blocks on the first screen that has no answer yet. The same flow runs unchanged on USSD, WhatsApp, Messenger, Instagram, Telegram, and HTTP, with per-platform rendering.
+
+## How the replay engine works
+
+There is no saved program counter. On each webhook FlowChat rebuilds the app from the request and re-runs your flow method from the first line.
+
+`app.screen(key)` is the fast-forward mechanism. When the session already holds a value for `key`, `screen` returns `session.get(key)` immediately and never yields. When it does not, `screen` yields a `FlowChat::Prompt`. If that prompt calls `ask` (or `select`, `yes?`) and no input is available yet, it raises `FlowChat::Interrupt::Prompt`. The interrupt unwinds the flow back to the Executor, which turns it into a rendered prompt and returns the response to the gateway.
+
+The next webhook replays the same method from the top. Every screen that already has a stored answer is skipped in place. The screen that raised last time now sees the incoming input, runs its `validate` and `transform`, stores the accepted value with `session.set(key, value)`, and returns it, so execution falls through into the next screen. The flow advances one screen per turn without ever holding state between requests beyond the session hash.
+
+Two rules follow from this design:
+
+- One inbound message is consumed by one screen per turn. Once a screen takes the turn's input, later screens in the same run see no input and will prompt.
+- A given screen key may be presented only once per run. Re-entering a key raises `ArgumentError`; use distinct keys or `app.go_back` to revisit.
 
 ## Installation
 
-Add to your Gemfile:
+Add the gem to your Gemfile:
 
 ```ruby
-gem 'flow_chat'
+gem "flow_chat"
 ```
 
-Then run:
+Then run `bundle install`. FlowChat requires Ruby 3.0 or newer.
 
-```bash
-bundle install
+The cache-backed session store needs a cache. Set it once during boot, for example in an initializer:
+
+```ruby
+FlowChat::Config.cache = Rails.cache
 ```
 
-## Quick Start
+Without a cache configured, `FlowChat::Session::CacheSessionStore` raises when it tries to read or write a session. There are no migrations and no generators to run.
 
-### USSD Example
+## Wiring a platform
 
-Create a flow in `app/flow_chat/welcome_flow.rb`:
+Build a processor, choose a gateway and session store, and run your flow:
 
 ```ruby
-class WelcomeFlow < FlowChat::Flow
-  def main_page
-    name = app.screen(:name) do |prompt|
-      prompt.ask "What's your name?",
-        transform: ->(input) { input.strip.titleize }
-    end
-
-    language = app.screen(:language) do |prompt|
-      prompt.select "Choose language:", ["English", "French", "Spanish"]
-    end
-
-    app.say "Hello #{name}! Language set to #{language}."
-  end
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
 end
+
+processor.run RegistrationFlow, :main_page
 ```
 
-Create a controller:
+Point your controller's webhook action at this code (`self` is the controller). Each platform has its own gateway class:
 
-```ruby
-class UssdController < ApplicationController
-  skip_forgery_protection
+| Platform | Gateway class | Platform symbol | Rendering |
+|---|---|---|---|
+| USSD | `FlowChat::Ussd::Gateway::Nalo` | `:ussd` | Numbered text menus, pagination, media as URL text |
+| WhatsApp | `FlowChat::Whatsapp::Gateway::CloudApi` | `:whatsapp` | Reply buttons (<=3 choices), lists (>3), rich media |
+| Messenger | `FlowChat::Messenger::Gateway::SendApi` | `:messenger` | Quick replies, carousel, numbered text |
+| Instagram | `FlowChat::Instagram::Gateway::SendApi` | `:instagram` | Quick replies, carousel, always numbered |
+| Telegram | `FlowChat::Telegram::Gateway::BotApi` | `:telegram` | Inline keyboards, rich media, HTML |
+| HTTP | `FlowChat::Http::Gateway::Simple` | `:http` | JSON responses (testing, custom clients) |
+| Intercom | `FlowChat::Intercom::Gateway::IntercomApi` | `:intercom` | Live-chat replies |
 
-  def process_request
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Ussd::Gateway::Nalo
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
+The same `RegistrationFlow` runs on any row by changing only `config.use_gateway`. To build a gateway for a platform not listed here, see [docs/gateway-development.md](docs/gateway-development.md).
 
-    processor.run WelcomeFlow, :main_page
-  end
-end
-```
+## Building flows
 
-Add route in `config/routes.rb`:
+A flow is a class that inherits `FlowChat::Flow` and reads and writes the conversation through `app`. Each unit of interaction is a screen:
 
 ```ruby
-  post 'ussd' => 'ussd#process_request'
+value = app.screen(:key) { |prompt| prompt.ask "..." }
 ```
 
-### WhatsApp Example
+The block receives a `FlowChat::Prompt`. Its methods:
 
-Configure credentials in `config/credentials.yml.enc`:
+| Method | Signature | Behavior |
+|---|---|---|
+| `ask` | `ask(msg, choices: nil, transform: nil, validate: nil, media: nil)` | Prompt for free input; validate, then transform, then return the value |
+| `select` | `select(msg, choices, media: nil, error_message: "Invalid selection:")` | Prompt for one of `choices`; returns the chosen key |
+| `yes?` | `yes?(msg)` | A `select` over Yes/No; returns `true` or `false` |
+| `say` | `say(msg, media: nil)` | Send a terminal message and end the flow |
 
-```yaml
-whatsapp:
-  access_token: "your_access_token"
-  phone_number_id: "your_phone_number_id"
-  verify_token: "your_verify_token"
-  app_secret: "your_app_secret"
-```
+Details:
+
+- `validate` is a callable that returns an error string when the input is rejected and `nil` when it passes. The received argument behaves like the input text (`input.include?("@")`, `input.to_i`, `input.strip`), and also exposes `media`, `location`, and `contact` for attachment-carrying turns.
+- `transform` is a callable that maps the accepted input to the value `screen` stores and returns.
+- `choices` may be an Array (`["Yes", "No"]`) or a Hash (`{ "1" => "Account", "2" => "Support" }`). With a Hash, `select` returns the key.
+- Passing `media:` together with more than 3 `choices` raises `ArgumentError`. Use media or a longer choice list, not both.
 
-Create a controller:
+`app.say` outside a block ends the flow from anywhere:
 
 ```ruby
-class WhatsappController < ApplicationController
-  skip_forgery_protection
+def main_page
+  confirmed = app.screen(:confirm) { |prompt| prompt.yes? "Place the order?" }
+  app.say("Cancelled.") unless confirmed
+  # ...
+end
+```
 
-  def webhook
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
+To send the user back to the previous screen, call `app.go_back`. It clears the current screen's stored answer and restarts the flow from the top, so the earlier screen prompts again. Remember that a screen key may appear only once per run: reuse of a key in a single pass raises `ArgumentError`.
+
+## Media and rich input
+
+An inbound turn is a `FlowChat::Input`. Read what the user sent through these accessors on `app`:
+
+| Accessor | Returns |
+|---|---|
+| `app.text` | The message text (`""` when the turn carries only an attachment) |
+| `app.media` | An Array of `FlowChat::Media` (empty array when none) |
+| `app.location` | The shared location payload, or `nil` |
+| `app.contact` | The shared contact card, or `nil` |
+| `app.attachment_type` | `:media`, `:location`, `:contact`, or `nil` |
+
+Reading an inbound photo:
+
+```ruby
+def main_page
+  app.screen(:photo) do |prompt|
+    prompt.ask "Send a photo of the receipt."
+  end
 
-    processor.run WelcomeFlow, :main_page
+  photo = app.media.first
+  if photo
+    photo.type       # => :image  (a Symbol; normalized across platforms)
+    photo.mime_type  # => "image/jpeg"
+    photo.caption    # => the caption text, or nil
+    bytes = photo.download   # raw bytes, or nil on failure
+    link  = photo.url        # a fetchable URL, or nil
   end
 end
 ```
 
-Add route:
+`app.media` is always an Array, so read a single item with `app.media.first` and check for `nil`; the type is a Symbol, read with `app.media.first&.type`. A caption-less photo still answers a screen: an attachment counts as submitted even when the text is blank.
+
+To send media outbound, pass `media:` to `ask` or `say`:
 
 ```ruby
-  match '/whatsapp/webhook', to: 'whatsapp#webhook', via: [:get, :post]
+app.say "Here you go", media: { type: :image, url: "https://example.com/receipt.png" }
 ```
 
-## Core Concepts
+Caveat: a `Media` object that has been deserialized from a session store or a background job has lost its live platform client, so `url` and `download` return `nil`. If you need the bytes, call `download` eagerly in the same request that received the media, before the value round-trips through a session or job.
 
-### Flows and Screens
+## Sessions
 
-**Flows** define conversation logic. **Screens** collect user input with automatic validation:
+The default session boundaries are `[:flow, :gateway, :platform]`: a session is scoped to one flow, on one gateway, on one platform. Convenience methods adjust this:
 
-```ruby
-class RegistrationFlow < FlowChat::Flow
-  def main_page
-email = app.screen(:email) do |prompt|
-      prompt.ask "Enter email:",
-        validate: ->(input) { "Invalid email" unless input.include?("@") },
-        transform: ->(input) { input.downcase.strip }
-    end
+| Method | Effect |
+|---|---|
+| `use_durable_sessions` | Key the session on a stable per-user identifier so it survives USSD session-id rotation across a conversation |
+| `use_cross_platform_sessions` | Narrow the boundary to flow only, so one session is shared across platforms (for example USSD and WhatsApp) |
+| `use_url_isolation` | Add a `:url` boundary for per-tenant or per-host isolation |
+| `use_session_config(boundaries:, identifier:, hash_identifiers:, &block)` | Set boundaries, the identifier, and identifier hashing directly for full control |
 
-confirmed = app.screen(:confirm) do |prompt|
-      prompt.yes? "Create account for #{email}?"
+```ruby
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  config.use_durable_sessions
 end
+```
 
-if confirmed
-      create_account(email)
-      app.say "Account created successfully!"
-    else
-      app.say "Registration cancelled."
-    end
+See [docs/configuration.md](docs/configuration.md) for the full set of session options.
+
+## Platform differences
+
+The flow code is the same everywhere, but each platform imposes limits that the rendering respects and that you should keep in mind:
+
+| Platform | Limits and behavior |
+|---|---|
+| USSD | Pages are split at 140 characters by default; media is rendered as a text line containing a URL, not an inline attachment; async processing is not available. |
+| WhatsApp | Reply-button titles are truncated near 20 characters and list titles near 24; a list section holds at most 10 rows. WhatsApp's 24-hour customer-service window and its template requirement are not abstracted away: you manage message templates yourself. |
+| Messenger | Up to 13 choices render as quick replies, up to 30 as a carousel (10 elements, 3 buttons each), and above that as numbered text. Neither platform abstracts the 24-hour messaging window; a send outside it is attempted and Meta's rejection surfaces as an API error. |
+| Instagram | Same quick-reply and carousel caps as Messenger (13, then 30), but both surfaces render on the mobile app only, not desktop or web, so Instagram always lists the options as numbered text as well. Text is capped at 1000 bytes UTF-8, not characters. |
+| Telegram | Choice taps arrive as callback queries; choices render as inline keyboards; message text supports HTML formatting. |
+| HTTP | Requests and responses are JSON; each request must supply `session_id` and `user_id`. |
+
+Platform guides: [docs/platforms/ussd.md](docs/platforms/ussd.md), [docs/platforms/whatsapp.md](docs/platforms/whatsapp.md), [docs/platforms/messenger.md](docs/platforms/messenger.md), [docs/platforms/instagram.md](docs/platforms/instagram.md), [docs/platforms/telegram.md](docs/platforms/telegram.md).
+
+## Background processing
+
+For platforms with an outbound API, you can acknowledge the webhook immediately and run the flow in a background job. Register a factory once, then call it from the webhook:
+
+```ruby
+# config/initializers/flow_chat.rb
+FlowChat::Factory.register(:whatsapp) do |controller|
+  processor = FlowChat::Processor.new(controller) do |config|
+    config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+    config.use_session_store FlowChat::Session::CacheSessionStore
+    config.use_async(factory: :whatsapp)
   end
+  processor.run RegistrationFlow, :main_page
+end
+
+# app/controllers/whatsapp_controller.rb
+def webhook
+  FlowChat::Factory.execute(:whatsapp, controller: self)
 end
 ```
 
-### Input Methods
+The webhook enqueues `GenericAsyncJob` and returns; the job re-runs the same factory in the background, where the gateway detects the background context and processes the flow inline before sending the reply through the platform API. USSD does not support async, since it depends on a synchronous request-response cycle. See [docs/factory-pattern.md](docs/factory-pattern.md) and [docs/async-background-processing.md](docs/async-background-processing.md).
 
-- **`prompt.ask()`** - Free-form input with optional validation
-- **`prompt.select()`** - Force selection from predefined options  
-- **`prompt.yes?()`** - Simple yes/no questions
+## Instrumentation
 
-## WhatsApp Client
+FlowChat emits `ActiveSupport::Notifications` events for flow execution, session lifecycle, and gateway activity. `FlowChat.metrics` collects counters over those events. See [docs/instrumentation.md](docs/instrumentation.md).
 
-Send messages outside of flows:
+## Testing
 
-```ruby
-config = FlowChat::Whatsapp::Configuration.from_credentials
-client = FlowChat::Whatsapp::Client.new(config)
-
-# Send messages
-client.send_text("+1234567890", "Hello!")
-client.send_buttons("+1234567890", "Choose:", [
-  { id: 'option1', title: 'Option 1' },
-  { id: 'option2', title: 'Option 2' }
-])
-```
+FlowChat ships a web simulator for driving flows locally without a real gateway, useful during development. It requires `FlowChat::Config.simulator_secret` to be set. See [docs/testing.md](docs/testing.md).
 
-## Testing Simulator
+## Documentation
 
-FlowChat includes a powerful built-in simulator with a modern web interface for testing both USSD and WhatsApp flows:
+Guides:
 
-![FlowChat Simulator](docs/images/simulator.png)
+- [Getting started](docs/getting-started.md)
+- [Configuration](docs/configuration.md)
+- [Testing](docs/testing.md)
 
-Features:
-- 📱 **Visual Interface** - Phone-like display with real conversation flow
-- 🔄 **Environment Switching** - Toggle between USSD and WhatsApp modes
-- 📊 **Request Logging** - Real-time HTTP request/response monitoring
-- 🎯 **Interactive Testing** - Test flows with character counting and validation
-- 🛠️ **Developer Tools** - Session management and connection status
+Platforms:
 
-See the [Testing Guide](docs/testing.md) for complete setup instructions and testing strategies.
+- [USSD](docs/platforms/ussd.md)
+- [WhatsApp](docs/platforms/whatsapp.md)
+- [Messenger](docs/platforms/messenger.md)
+- [Instagram](docs/platforms/instagram.md)
+- [Telegram](docs/platforms/telegram.md)
 
+Internals and advanced:
 
-## Documentation
+- [Architecture](docs/architecture.md)
+- [Building a gateway](docs/gateway-development.md)
+- [Gateway context variables](docs/gateway-context-variables.md)
+- [Async and background processing](docs/async-background-processing.md)
+- [Factory pattern](docs/factory-pattern.md)
+- [Instrumentation](docs/instrumentation.md)
 
-- **[WhatsApp Setup](docs/whatsapp-setup.md)** - Comprehensive WhatsApp configuration
-- **[USSD Setup](docs/ussd-setup.md)** - USSD gateway configuration and examples
-- **[Flow Development](docs/flows.md)** - Advanced flow patterns and techniques
-- **[Session Management](docs/sessions.md)** - Session architecture and configuration
-- **[Media Support](docs/media.md)** - Rich media handling for WhatsApp
-- **[Testing Guide](docs/testing.md)** - Complete testing strategies
-- **[Configuration Reference](docs/configuration.md)** - All configuration options
-- **[Instrumentation](docs/instrumentation.md)** - Monitoring and metrics
-- **[Security](docs/security.md)** - Security best practices
-- **[Examples](examples/)** - Complete working examples
+## Development
 
-## Examples
+Run the test suite with `rake test`. To run a single file, use `ruby -Itest test/unit/some_test.rb`.
 
-See the [examples directory](examples/) for complete implementations:
+## Contributing
 
-- **[USSD Controller](examples/ussd_controller.rb)** - Full USSD implementation
-- **[WhatsApp Controller](examples/whatsapp_controller.rb)** - Basic WhatsApp setup
-- **[Multi-tenant WhatsApp](examples/multi_tenant_whatsapp_controller.rb)** - Advanced WhatsApp
-- **[Background Jobs](examples/whatsapp_message_job.rb)** - Async message processing
-- **[Simulator Controller](examples/simulator_controller.rb)** - Testing setup
+Bug reports and pull requests are welcome on [GitHub](https://github.com/radioactive-labs/flow_chat). Please add tests for behavior changes and keep them passing.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+FlowChat is released under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -1,10 +1,25 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "standard/rake"
+
+# Load custom rake tasks
+Dir.glob("lib/tasks/**/*.rake").each { |r| load r }
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  # test/performance holds benchmarks, which assert against wall-clock timings and
+  # so fail on a loaded machine for reasons that have nothing to do with the code
+  # under test. A suite that cries wolf is a suite people stop reading, so they
+  # run under `rake benchmark` instead of here.
+  t.test_files = FileList["test/**/*_test.rb"].exclude("test/performance/**/*_test.rb")
+end
+
+desc "Run the performance benchmarks (timing-sensitive, not part of rake test)"
+Rake::TestTask.new(:benchmark) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/performance/**/*_test.rb"]
 end
 
-task default: :test
+task default: %i[test standard]