ratatui_ruby-tea 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1bf31fb6ff8bacdcd6f9c54e794e0c769f5c52afde2c5e4d78cbee48be36b12
-  data.tar.gz: 1bd65539c4eace89fc1d58d857d81fb9cc03187ea7ae770d4b5c4a051ae407a0
+  metadata.gz: c83e509aceb1826713abd9e4835055c1d28397627438d3041783564195b1821b
+  data.tar.gz: d452ab612362d0d3216101ab9d454c950a8af07afcd913c3fa8627e69eb09887
 SHA512:
-  metadata.gz: 413f42942963ef06433b683b2cf3820db1a8cd679fcf263aaccc4cbd3780fa01b7bcc66842aeaad7606377380530215a9b6a07a145d6df56ecf34a5053c998cb
-  data.tar.gz: 8edaf06fbf149723ca70b2f27157c8c2d22536f060c94facfb6d904223b48dc21613daa0a130237548a40d705074ec22f90403e27855b1b578bad0e770f27040
+  metadata.gz: 6c211329907d95912192da187769d97ef56142cb4b1abe87ed2ed38c61b519d31f6823ab7f1154bc930e430b5fb19f1301c9497a9c68856c3c136c1ec0f6b962
+  data.tar.gz: 12b22830443dcc0783323bcccb8f2c1337a416cfe0cebaf89b0988d949f68e3ab73c4fbc37a6c140bc8b103465c8e467dad443654259961987dd91de7fa95767

data/AGENTS.md

@@ -31,6 +31,13 @@ Description: Part of the RatatuiRuby ecosystem.
 - **Setup:** `bin/setup` must handle Bundler dependencies.
 - **Git:** ALWAYS set `PAGER=cat` with `git`. **THIS IS CRITICAL!**
 
+### Tea-Specific Vocabulary
+
+- **BANNED WORD: "component"** — Reserved for Kit.
+- **Avoid "widget" for Tea units** — "Widget" refers to Engine/Ratatui render primitives. In Tea, call them **bags**.
+- **Bag:** A module containing `Model`, `INITIAL`, `UPDATE`, and `VIEW` constants. Bags compose: parent bags delegate to child bags.
+- Use "model", "update", "view" for the MVU pattern. Use "message" (not "msg") and "command" (not "cmd").
+
 ### Ruby Standards
 
 - Use `Data.define` for all value objects (Ruby 3.2+).
@@ -48,9 +55,14 @@ Description: Part of the RatatuiRuby ecosystem.
 
 ## 3. Definition of Done (DoD)
 
-Before considering a task complete:
+Before considering a task complete and returning control to the user, you **MUST** ensure:
+
+0. **Production Ready:** RBS types are complete and accurate (no `untyped`), errors are handled with good DX, documentation follows guidelines, high code quality (no "pre-existing debt" excuses).
+1.  **Default Rake Task Passes:** Run `bundle exec agent_rake` (no args). Confirm it passes with ZERO errors **or warnings**.
+  - You will save time if you run `bundle exec agent_rake rubocop:autocorrect` first.
+  - If you think the rake is looking for deleted files, STOP EVERYTHING and tell the user.
+2.  **Documentation Updated:** If public APIs or observable behavior changed, update relevant RDoc, rustdoc, `doc/` files, `README.md`, and/or `ratatui_ruby-wiki` files.
+3.  **Changelog Updated:** If public APIs, observable behavior, or gemspec dependencies have changed, update [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section.
+4.  **Commit Message Suggested:** You **MUST** ensure the final message to the user includes a suggested commit message block. This is NOT optional.
+  - You MUST also check `git log -n1` to see the current standard AI footer ("Generated  with" and "Co-Authored-By") and include it in your suggested message.
 
-1. **Default Rake Task Passes:** Run `bundle exec agent_rake` (no args). Confirm it passes with ZERO errors.
-2. **Documentation Updated:** If public APIs changed, update relevant docs.
-3. **Changelog Updated:** If public APIs changed, update CHANGELOG.md's **Unreleased** section.
-4. **Commit Message Suggested:** Include a suggested commit message block.

data/CHANGELOG.md

@@ -21,6 +21,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.3.1] - 2026-01-11
+
+### Added
+
+- **CancellationToken**: Cooperative cancellation mechanism for long-running custom commands. Commands check `cancelled?` periodically and stop gracefully when `cancel!` is called. Includes `CancellationToken::NONE` null object for commands that ignore cancellation.
+
+- **Command::Custom Mixin**: Include in your class to mark it as a custom command. Provides `tea_command?` brand predicate and `tea_cancellation_grace_period` (default 2.0 seconds) for configuring cleanup time after cancellation.
+
+- **Command::Outlet**: Messaging gateway for custom commands. Use `put(tag, *payload)` to send results back to the update function. Validates Ractor-shareability in debug mode.
+
+- **Custom Command Dispatch**: Runtime now dispatches custom commands (objects with `tea_command?` returning true) in background threads. Commands receive an `Outlet` for messaging and a `CancellationToken` for cooperative shutdown.
+
+- **Command.custom Factory**: Wraps lambdas/procs to give them unique identity for dispatch tracking. Each `Command.custom(callable)` call produces a distinct wrapper, enabling targeted cancellation. Accepts optional `grace_period:` to override the default 2.0 second cleanup window.
+
+- **Command.cancel Factory**: Request cancellation of a running command. Returns a `Command::Cancel` sentinel that the runtime routes to the appropriate command's CancellationToken.
+
+- **Runtime Cancellation Dispatch**: The runtime now handles `Command::Cancel` by signaling the target command's `CancellationToken`, enabling cooperative cancellation of long-running commands. Respects `tea_cancellation_grace_period`: waits for the grace period, then force-kills unresponsive threads. Use `Float::INFINITY` to never force-kill.
+
+- **Graceful Shutdown**: On exit, runtime signals all active commands then respects each command's grace period. Commands with `Float::INFINITY` grace are waited on indefinitely (user has SIGKILL). Final queue messages are processed before returning.
+
+- **Automatic Error Propagation**: Custom commands that raise unhandled exceptions now produce a `Command::Error` message instead of corrupting the TUI display. The runtime catches exceptions and pushes `Command::Error.new(command:, exception:)` to the queue. Pattern match on `Command::Error` in your update function to handle failures uniformly. Factory method `Command.error(command, exception)` is available for testing.
+
+- **Command::System Cancellation**: Streaming shell commands now respect cooperative cancellation. When cancelled, sends `SIGTERM` for graceful shutdown, then `SIGKILL` if the child process doesn't exit. Prevents orphaned child processes from lingering after app exit.
+
+### Changed
+
+### Fixed
+
+- **Ractor Enforcement is Debug-Only**: The Ractor-shareability check now only runs in debug mode (and automated tests). Production skips this check for performance, matching the original specification. Previously, the check ran unconditionally.
+
+### Removed
+
+## [0.3.0] - 2026-01-08
+
+### Added
+
+- **Router DSL**: New `Tea::Router` module provides declarative routing for Fractal Architecture:
+  - `route :prefix, to: ChildBag` — declares a child bag route
+  - `keymap { key "q", -> { Command.exit } }` — declares keyboard handlers
+  - `keymap { key "x", handler, when: -> (m) { m.ready? } }` — guards (also: `if:`, `only:`, `guard:`, `unless:`, `except:`, `skip:`)
+  - `keymap { only when: guard do ... end }` — nested guard blocks apply to all keys within (also: `skip when: ...`)
+  - `mousemap { click -> (x, y) { ... } }` — declares mouse handlers
+  - `action :name, handler` — declares reusable actions for key/mouse handlers
+  - `from_router` — generates an UPDATE lambda from routes and handlers
+
+- **Composition Helpers**: New helper methods for Fractal Architecture reduce boilerplate:
+  - `Tea.route(command, :prefix)` — wraps a command to route results to a child bag
+  - `Tea.delegate(message, :prefix, child_update, child_model)` — dispatches prefixed messages to child bags
+
+- **Command Mapping**: `Command.map(inner_command, &mapper)` wraps a child command and transforms its result message. Essential for parent bags routing child command results.
+
+- **Shortcuts Module**: `require "ratatui_ruby/tea/shortcuts"` and `include Tea::Shortcuts` for short aliases:
+  - `Cmd.exit` — alias for `Command.exit`
+  - `Cmd.sh(command, tag)` — alias for `Command.system`
+  - `Cmd.map(command, &block)` — alias for `Command.map`
+
+- **Sync Event Integration**: Runtime now handles `Event::Sync` from `RatatuiRuby::SyntheticEvents`. When a Sync event is received, the runtime waits for all pending async threads and processes their results before continuing. Use `inject_sync` in tests for deterministic async verification.
+
+- **Streaming Command Output**: `Command.system` now accepts a `stream:` keyword argument. When `stream: true`, the runtime sends incremental messages (`[:tag, :stdout, line]`, `[:tag, :stderr, line]`) as output arrives, followed by `[:tag, :complete, {status:}]` when the command finishes. Invalid commands send `[:tag, :error, {message:}]`. Default behavior (`stream: false`) remains unchanged.
+
+- **Custom Shell Modal Example**: Added `examples/app_fractal_dashboard/bags/custom_shell_modal.rb` demonstrating a 3-bag fractal architecture for a modal that runs arbitrary shell commands with streaming output. Features interleaved stdout/stderr, exit status indication, and Ractor-safe implementation using `tui.overlay` for opaque rendering.
+
+### Changed
+
+- **Command Module Rename (Breaking)**: The `Cmd` module is now `Command` with Rubyish naming:
+  - `Cmd::Quit` → `Command::Exit` (use `Command.exit` factory)
+  - `Cmd::Exec` → `Command::System` (use `Command.system(cmd, tag)` factory)
+
+### Fixed
+
+### Removed
+
 ## [0.2.0] - 2026-01-08
 
 ### Added
@@ -43,6 +115,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **First Release**: Empty release of `ratatui_ruby-tea`, a Ruby implementation of The Elm Architecture (TEA) for `ratatui_ruby`. Scaffolding generated by `ratatui_ruby-devtools`.
 
 [Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/HEAD
+[0.3.1]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.3.1
+[0.3.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.3.0
 [0.2.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.2.0
 [0.2.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.2.0
 [0.1.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.1.0

data/README.md

@@ -26,6 +26,23 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 
 Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements. See the [`trunk` branch](https://git.sr.ht/~kerrick/ratatui_ruby-tea/tree/trunk) for pre-release updates.
 
+---
+
+## Quick Links
+
+### The Ecosystem
+
+**RatatuiRuby:** [Core engine](https://git.sr.ht/~kerrick/ratatui_ruby) • **Tea:** [MVU architecture](https://git.sr.ht/~kerrick/ratatui_ruby-tea) • **Kit:** [Component architecture](https://git.sr.ht/~kerrick/ratatui_ruby-kit) (Planned) • **DSL:** [Glimmer syntax](https://sr.ht/~kerrick/ratatui_ruby/#chapter-4-the-syntax) (Planned) • **Framework:** [Omakase framework](https://git.sr.ht/~kerrick/ratatui_ruby-framework) (Planned) • **UI:** [Polished widgets](https://git.sr.ht/~kerrick/ratatui_ruby-ui) (Planned) • **UI Pro:** [More polished widgets](https://sr.ht/~kerrick/ratatui_ruby#chapter-6-licensing) (Planned)
+
+### For App Developers
+
+**Get Started:** [Quickstart](https://git.sr.ht/~kerrick/ratatui_ruby/tree/stable/item/doc/getting_started/quickstart.md) • [Examples](https://git.sr.ht/~kerrick/ratatui_ruby/tree/stable/item/examples) ⸺ **Stay Informed:** [Announce List](https://lists.sr.ht/~kerrick/ratatui_ruby-announce) • [FAQ](https://man.sr.ht/~kerrick/ratatui_ruby/troubleshooting.md) ⸺ **Reach Out:** [Discuss List](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss) • [Bug Tracker](https://todo.sr.ht/~kerrick/ratatui_ruby)
+
+### For Contributors
+
+**Get Started:** [Contributing Guide](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md) • [Code of Conduct](https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md) ⸺ **Stay Informed:** [Announce List](https://lists.sr.ht/~kerrick/ratatui_ruby-announce) • [Project History](https://man.sr.ht/~kerrick/ratatui_ruby/history/index.md) ⸺ **Reach Out:** [Development List](https://lists.sr.ht/~kerrick/ratatui_ruby-devel) • [Bug Tracker](https://todo.sr.ht/~kerrick/ratatui_ruby)
+
+---
 
 ## Compatibility
 
@@ -106,7 +123,7 @@ end
 
 UPDATE = -> (msg, model) do
   if msg.q? || msg.ctrl_c?
-    RatatuiRuby::Tea::Cmd.quit
+    RatatuiRuby::Tea::Command.exit
   else
     model
   end

data/Rakefile

@@ -13,4 +13,4 @@ RatatuiRuby::Devtools.install!
 # Import project-specific tasks
 Dir.glob("tasks/*.rake").each { |r| import r }
 
-task default: %w[lint:fix test lint reuse]
+task default: %w[lint:fix test lint reuse steep]

data/Steepfile

@@ -7,7 +7,7 @@ target :lib do
   signature "sig"
   check "lib"
 
-  library "pathname"
-  library "fileutils"
-  library "minitest"
+  library "open3"
+
+  collection_config "rbs_collection.yaml"
 end

data/doc/concepts/application_architecture.md

@@ -5,12 +5,191 @@
 
 # Application Architecture
 
-Architect robust TUI applications using core library patterns and API best practices.
+Build robust TUI applications with Tea patterns.
 
 ## Core Concepts
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files._
+_This section is incomplete. Check the source files._
 
 ## Thread and Ractor Safety
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files._
+### The Strategic Context
+
+Ruby 4.0 introduces [Ractors](https://docs.ruby-lang.org/en/4.0/Ractor.html)—
+true parallel actors that forbid shared mutable state. Code that passes
+mutable objects between threads crashes in a Ractor world.
+
+Tea prepares you today. The runtime enforces Ractor-shareability on every
+Model and Message *now*, using standard threads. Pass a mutable object,
+and it raises an error immediately. Write Ractor-safe code today; upgrade
+to Ruby 4.0 without changes tomorrow.
+
+Enforce immutability rules before you strictly need them, and the migration
+is invisible.
+
+### The Problem
+
+Ruby's Ractor model prevents data races by forbidding shared mutable state.
+Mutable objects cause runtime errors:
+
+```
+RatatuiRuby::Error::Invariant: Model is not Ractor-shareable.
+```
+
+### The Solution
+
+Use `Ractor.make_shareable`. It recursively freezes everything:
+
+```ruby
+Ractor.make_shareable(model.with(text: "#{model.text}#{char}"))
+```
+
+For constants, wrap INITIAL:
+
+```ruby
+INITIAL = Ractor.make_shareable(
+  Model.new(text: "", running: false, chunks: [])
+)
+```
+
+For collection updates:
+
+```ruby
+new_chunks = Ractor.make_shareable([*model.chunks, new_item])
+```
+
+### The Lightweight Alternative
+
+When you know exactly what's mutable, `.freeze` is shorter:
+
+```ruby
+[model.with(text: "#{model.text}#{char}".freeze), nil]
+```
+
+### Foot-Guns
+
+#### frozen_string_literal Only Affects Literals
+
+The magic comment freezes strings that appear directly in source code.
+Computed strings are mutable.
+
+```ruby
+# frozen_string_literal: true
+
+"literal"        # frozen ✓
+"#{var}"         # mutable ✗
+str.chop         # mutable ✗
+str + other      # mutable ✗
+```
+
+#### Data.define Needs Shareable Values
+
+`Data.define` creates frozen instances. The instance is Ractor-shareable
+only when all its values are shareable.
+
+### Quick Reference
+
+| Pattern | Code |
+|---------|------|
+| Make anything shareable | `Ractor.make_shareable(obj)` |
+| Freeze a string | `str.freeze` |
+| INITIAL constant | `Ractor.make_shareable(Model.new(...))` |
+| Array update | `Ractor.make_shareable([*old, new])` |
+
+### Debugging
+
+See this error?
+
+```
+RatatuiRuby::Error::Invariant: Model is not Ractor-shareable.
+```
+
+Wrap the returned model with `Ractor.make_shareable`.
+
+## Modals and Command Result Routing
+
+Modals capture keyboard input. They overlay the main UI and intercept keypresses until dismissed. But async commands keep running in the background. When their results arrive, they look like any other message.
+
+It's tempting to intercept *all* messages when the modal is active. This swallows those command results.
+
+### The Scenario
+
+1. User presses "u" to fetch uptime. The runtime dispatches an async command.
+2. User presses "c" to open a modal dialog.
+3. The uptime command completes. It sends `[:network, :uptime, { stdout:, ... }]`.
+4. The modal intercept sees the modal is active. It routes that message to the modal.
+5. The modal ignores it.
+6. The uptime panel never updates.
+
+### The Fix
+
+Route command results before modal interception. Modals intercept user input, not async results.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+# Wrong: modal intercepts everything
+UPDATE = lambda do |message, model|
+  if Modal.active?(model.modal)
+    # Swallows command results
+    return Modal::UPDATE.call(message, model.modal)
+  end
+
+  case message
+  in [:network, *rest]
+    # Never reached while modal is open
+  end
+end
+
+# Correct: route command results first
+UPDATE = lambda do |message, model|
+  # 1. Route async command results (always)
+  case message
+  in [:network, *rest]
+    return [model.with(network: new_network), command]
+  in [:stats, *rest]
+    return [model.with(stats: new_stats), command]
+  else
+    nil
+  end
+
+  # 2. Modal intercepts user input
+  if Modal.active?(model.modal)
+    return Modal::UPDATE.call(message, model.modal)
+  end
+
+  # 3. Handle other input
+  case message
+  in _ if message.q? then Command.exit
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+### The Router DSL
+
+`Tea::Router` handles this correctly. Routes declared with `route :prefix, to: ChildModule` process before keymap handlers. Command results flow through even when guards block keyboard input.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+module Dashboard
+  include Tea::Router
+
+  route :stats, to: StatsPanel
+  route :network, to: NetworkPanel
+
+  keymap do
+    only when: MODAL_INACTIVE do
+      key "u", -> { Uptime.fetch_command }
+    end
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->

data/doc/contributors/design/commands_and_outlets.md

@@ -0,0 +1,204 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Custom Commands Design (`ratatui_ruby-tea`)
+
+This document describes the architectural design and guiding principles of custom commands in `ratatui_ruby-tea`. It is intended for contributors, architects, and AI agents working on the codebase.
+
+## Core Abstractions
+
+Custom commands extend Tea with user-defined side effects: WebSockets, gRPC, database polling, background workers. The architecture provides four key components:
+
+| Component | Purpose |
+|-----------|---------|
+| `Command::Custom` | Mixin for command identification |
+| `Command::Outlet` | Messaging gateway for result delivery |
+| `Command::CancellationToken` | Cooperative cancellation mechanism |
+| `Command.custom { ... }` | Wrapper giving callables unique identity |
+
+---
+
+## Guiding Design Principles
+
+### 1. Messaging Gateway over Raw Queue
+
+Commands produce messages. Those messages cross threads. Without abstraction, queue manipulation scatters across the codebase.
+
+The Outlet wraps the internal queue with a domain-specific API. Commands call `out.put(:tag, data)` instead of managing queue details. Debug mode validates Ractor-shareability automatically—commands cannot accidentally push unshareable data.
+
+| Aspect | Raw Queue | Outlet |
+|--------|-----------|--------|
+| Ractor safety | Manual | Automatic |
+| Error messages | Generic | Contextual |
+| API | `queue << Ractor.make_shareable([...])` | `out.put(:tag, data)` |
+| Pattern | Implementation detail | **Messaging Gateway** |
+
+This implements the **Messaging Gateway** pattern from Enterprise Integration Patterns. The Outlet is a **Facade** (Gang of Four) over the queue, and acts as a **Channel Adapter** translating command results into update function messages.
+
+### 2. Cooperative Cancellation over Thread Termination
+
+Long-running commands block the event loop. WebSocket listeners, database pollers, and streaming connections run indefinitely until stopped. Stopping them abruptly corrupts state.
+
+`Thread#kill` terminates immediately. Mutexes may deadlock. Resources may leak. Database transactions may abort mid-write.
+
+The `CancellationToken` signals cancellation requests. Commands check `token.cancelled?` periodically and stop at safe points. Cleanup code runs. Resources release. Transactions commit.
+
+| Aspect | `Thread#kill` | CancellationToken |
+|--------|---------------|------------------|
+| Cleanup | None (immediate termination) | Command controls cleanup |
+| Resource safety | May corrupt state | Clean shutdown |
+| Mutexes | May deadlock | Released properly |
+| Pattern | Forceful | **Cooperative** |
+
+**Configurable grace periods** accommodate different cleanup needs:
+
+- `0.5` seconds — Quick HTTP abort, minimal cleanup
+- `2.0` seconds — Default, suitable for most commands
+- `5.0` seconds — WebSocket close handshake with remote server
+- `Float::INFINITY` — Never force-kill (database transactions)
+
+### 3. Command Identity via Object Reference
+
+The runtime tracks active commands by their object identity. When the update function returns `Command.cancel(handle)`, the runtime looks up that exact object in its registry and signals its token.
+
+Class-based commands get unique identity automatically—each `MyCommand.new` produces a distinct object. Reusable lambdas and procs share identity. Dispatch them twice, and cancellation would affect both.
+
+`Command.custom(callable)` wraps a callable in a unique container. Each call produces a distinct handle. Store it in your model. Cancel it later by returning `Command.cancel(handle)`.
+
+### 4. Automatic Error Propagation
+
+Commands run in threads. Exceptions bubble up silently. The update function never sees them. Backtraces written to STDERR corrupt the TUI display.
+
+The runtime catches unhandled exceptions and pushes `Command::Error` to the queue. This is automatic—commands do not rescue exceptions unless they want custom handling. The update function pattern-matches on `Command::Error` and reacts appropriately.
+
+This mirrors the sentinel pattern used for `Command::Exit` and `Command::Cancel`.
+
+### 5. Ractor Readiness
+
+This design is forward-compatible with Ruby's Ractor-based parallelism.
+
+**What's already shareable:**
+
+| Pattern | Shareable? | Why |
+|---------|------------|-----|
+| Module-constant lambda | ✅ Yes | `self` is the frozen module |
+| Closure-free block | ✅ Yes | No captured variables |
+| `Data.define` command | ✅ Yes | Immutable by definition |
+| Frozen class instance | ✅ Yes | Deeply frozen |
+
+**Debug mode validation:**
+
+In debug mode, Tea validates Ractor shareability at dispatch time. `Ractor.shareable?(command)` catches most issues. The Outlet's `put` method validates messages before pushing them to the queue.
+
+**Why Thread dispatch is Ractor-safe:**
+
+Commands execute in Threads within the **main Ractor**. Only messages (via Outlet) cross the shareability boundary. The `CancellationToken` stays within its Thread—never shared across Ractors. The `@active_commands` hash is local to the Runtime (main Ractor).
+
+When Ruby evolves to true Ractor parallelism, this design upgrades transparently: commands are already validated as shareable, so they could be sent to worker Ractors without code changes.
+
+---
+
+## Pattern Lineage
+
+This design implements several established patterns from the software architecture literature.
+
+### Design Patterns (Gang of Four)
+
+| Component | Pattern |
+|-----------|---------|
+| Custom Mixin | **Command** — Encapsulates a request as an object |
+| Outlet | **Facade** — Simplified interface to a complex subsystem |
+| Runtime | **Mediator** — Coordinates command dispatch and message routing |
+| Update Function | **State** — Behavior changes based on internal state |
+
+### Enterprise Integration Patterns (Hohpe & Woolf)
+
+| Component | Pattern |
+|-----------|---------|
+| Outlet | **Messaging Gateway** — Wraps message channel access |
+| Outlet | **Channel Adapter** — Connects applications to messaging systems |
+| Queue | **Point-to-Point Channel** — Single consumer receives each message |
+
+### Cancellation Patterns
+
+| Platform | Mechanism | Relationship |
+|----------|-----------|--------------|
+| **.NET** | `CancellationToken` | Direct inspiration for API design |
+| **Go** | `context.Context` | Cooperative cancellation via `ctx.Done()` |
+| **JavaScript** | `AbortController` | Web Fetch API cancellation |
+| **Java** | `Thread.interrupt()` | Flag-based cooperative cancellation |
+| **Kotlin** | `Job.cancel()` | Coroutine cancellation |
+
+---
+
+## Prior Art
+
+### The Elm Architecture (TEA)
+
+| Framework | Language | Notes |
+|-----------|----------|-------|
+| **Elm** | Elm | Original TEA; `Cmd` + `Sub` primitives |
+| **BubbleTea** | Go | TUI implementation; "Subscriptions are Loops" philosophy |
+| **Iced** | Rust | GUI TEA with Command + Subscription |
+| **Miso** | Haskell | Web TEA with Effect + Sub |
+| **Bolero** | F# | Web TEA with Cmd + Sub |
+
+### Redux Ecosystem
+
+| Library | Pattern | Mapping |
+|---------|---------|---------|
+| **Redux Thunk** | Raw dispatch access | Direct queue access (rejected) |
+| **Redux Saga** | `put()` effect dispatches actions | **Outlet.put** ← adopted |
+| **Redux Observable** | RxJS Observables | RxRuby (rejected for complexity) |
+| **redux-loop** | Elm-style Cmd | Recursive commands |
+
+Redux Saga's `put()` is the direct inspiration for `out.put()`. The Saga pattern—long-running processes that listen for actions and dispatch new ones—maps directly to Tea's custom commands.
+
+### Ruby Ecosystem
+
+| Library | Pattern | Relationship |
+|---------|---------|--------------|
+| **Observable** (stdlib) | Observer pattern | Similar push semantics, lacks thread-safety |
+| **Concurrent Ruby** | Actor, Promises | More complex than needed |
+| **Celluloid** | Actor mailboxes | Inspiration for internal terminology |
+| **Sidekiq** | Background jobs | Similar "fire command, receive result" model |
+
+---
+
+## Key Influences Summary
+
+| Influence | What We Adopted |
+|-----------|-----------------|
+| **Elm** | MVU architecture, Cmd/Msg pattern |
+| **BubbleTea** | "Subscriptions are Loops" philosophy |
+| **Redux Saga** | `put()` for message dispatch |
+| **.NET CancellationToken** | Cooperative cancellation with grace periods |
+| **EIP Messaging Gateway** | Outlet as infrastructure abstraction |
+| **Go context.Context** | Cancellation propagation pattern |
+
+---
+
+## Further Reading
+
+### External Resources
+
+- [Elm Guide](https://guide.elm-lang.org/) — Official Elm documentation covering commands and effects
+- [BubbleTea](https://github.com/charmbracelet/bubbletea) — Go TUI framework based on The Elm Architecture
+- [Redux Saga](https://redux-saga.js.org/) — Saga pattern and `put()` effect documentation
+- [Enterprise Integration Patterns](https://www.enterpriseintegrationpatterns.com/) — Messaging patterns reference by Hohpe & Woolf
+
+### Academic References
+
+1. **Gamma, Helm, Johnson, Vlissides** (1994). *Design Patterns: Elements of Reusable Object-Oriented Software*. Addison-Wesley.
+   - Command, Facade, Mediator, State patterns
+
+2. **Fowler, M.** (2002). *Patterns of Enterprise Application Architecture*. Addison-Wesley.
+   - Gateway pattern
+
+3. **Hohpe, G. & Woolf, B.** (2003). *Enterprise Integration Patterns*. Addison-Wesley.
+   - Messaging Gateway, Message Channel, Point-to-Point Channel, Channel Adapter
+
+4. **Joshi, U.** (2023). *Patterns of Distributed Systems*. Addison-Wesley.
+   - Write-Ahead Log, Thread Pool