easyop 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9157dccd94c6847b4b83c01404b64d48ffe54f1f6f51a99e0263bb718a2acdc4
-  data.tar.gz: 62bbaa697722e2b0d1979bc5a20839fb9dc765ee22d989f404591129a8a72c01
+  metadata.gz: 2b880af1b623158d3acfac130198bd96ce8c268195fd073554283738a880a45a
+  data.tar.gz: 0c4f5554b456ac252b13734d0964155e2a80909e81946e28f89c529cc60f9081
 SHA512:
-  metadata.gz: 52fc250d99c11808462344afb74603081aa2dd35ca4f4d16ec263d19b3c098bba77ddcdda7963793483a9bfc0b04bd2cf63a70700c9756e0fb6b4610229ecc9f
-  data.tar.gz: 778348d6dc863bdda5816a32738ae2262c3948eb3711090b0a4412bc0678a9dc9b7c87e48cd937c3f1842e492f5be787c252c42f8ae9955191794cc9200dfc1e
+  metadata.gz: c408d6d42a357ba1a6df4da21e13a7b0498d36fa4252e86c68aff289e8843d94d056c430f654f023e6d801ee650fc1bc4c400cb6d058a6b209129e1fbda644fd
+  data.tar.gz: e89087c84c8fbc77abe96b6713a144dd34b78c2cfd35066f28a14e37516f0e7ae8b0f0cbbcfe0ca9eb9de646c7890552b64d7d2848c9976ff6f51637531a4a8a

data/CHANGELOG.md

@@ -7,6 +7,199 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.4] — 2026-04-14
+
+### Added
+
+- **Flow-tracing forwarding in `Easyop::Flow`** — `CallBehavior#call` now automatically sets the `__recording_parent_*` ctx keys before running steps, so every child operation's log entry carries the flow class as its `parent_operation_name` and `parent_reference_id`. This works even when Recording is not installed on the flow class itself (bare `include Easyop::Flow`). When Recording IS installed (recommended: inherit from ApplicationOperation and add `transactional false`), the flow appears in the log as the root entry and RunWrapper handles the ctx setup — no double-setup occurs.
+
+  ```ruby
+  # Bare flow — Recording on steps only; flow itself is not recorded but
+  # steps correctly show parent_operation_name: "Flows::Checkout"
+  class Flows::Checkout
+    include Easyop::Flow
+    flow Orders::CreateOrder, Orders::ProcessPayment
+  end
+
+  # Recommended — flow is recorded as root, steps as children:
+  class Flows::Checkout < ApplicationOperation
+    include Easyop::Flow
+    transactional false   # steps manage their own transactions
+    flow Orders::CreateOrder, Orders::ProcessPayment
+  end
+  ```
+
+  Result in operation_logs:
+  ```
+  Flows::Checkout         root=aaa  ref=bbb  parent=nil
+    Orders::CreateOrder   root=aaa  ref=ccc  parent=Flows::Checkout/bbb
+    Orders::ProcessPayment root=aaa  ref=ddd  parent=Flows::Checkout/bbb
+  ```
+
+- **`record_result` DSL for `Easyop::Plugins::Recording`** — selectively persist ctx output data into a new optional `result_data :text` column (stored as JSON). Supports three forms:
+
+  ```ruby
+  # Attrs form — one or more ctx keys
+  record_result attrs: :invoice_id
+  record_result attrs: [:invoice_id, :total]
+
+  # Block form — custom extraction
+  record_result { |ctx| { total: ctx.total, items: ctx.items.count } }
+
+  # Symbol form — delegates to a private instance method
+  record_result :build_result
+  ```
+
+  Plugin-level default (inherited by all subclasses):
+  ```ruby
+  plugin Easyop::Plugins::Recording, model: OperationLog, record_result: { attrs: :metadata }
+  ```
+
+  Class-level `record_result` overrides the plugin-level default. Missing ctx keys produce `nil` (no error). ActiveRecord objects are serialized as `{ id:, class: }`. Serialization errors are swallowed. The `result_data` column is silently skipped when absent from the model table — fully backward-compatible.
+
+### Fixed
+
+- **`Easyop::Schema` type-mismatch warning suppressed when `$VERBOSE` is `nil`** — `warn` is a no-op in Ruby when `$VERBOSE` is `nil` (e.g. when running under certain test setups or with `-W0`). Changed to `$stderr.puts` so the `[EasyOp]` type-mismatch message always reaches stderr regardless of Ruby's verbosity flag.
+
+- **`Easyop::Schema` spec `strict_types` contamination across examples** — Setting `strict_types = true` inside an example without a corresponding teardown left the global config dirty for later examples. Added `after(:each) { Easyop.reset_config! }` at the top-level `RSpec.describe` so every example begins with a clean configuration.
+
+- **`Easyop::Plugins::Instrumentation` flaky duration assertion** — The `:duration` payload is computed as `(elapsed_ms).round(2)`, which rounds to `0.0` for operations completing in under 0.005 ms. Relaxed the spec assertion from `be > 0` to `be >= 0` to reflect that a rounded-to-zero duration is a valid measurement, not an error.
+
+## [0.1.3] — 2026-04-14
+
+### Added
+
+- **Minitest test suite** — a full parallel test suite covering all 21 modules in the gem. Tests live in `test/` and run via `bundle exec rake test` (or `bundle exec ruby -Ilib:test ...`). The suite complements the existing RSpec specs and is tracked as a separate SimpleCov report (command name `'Minitest'`).
+
+  Coverage across 258 tests, 360 assertions:
+
+  | Area | Files |
+  |------|-------|
+  | Core | `ctx_test`, `operation_test`, `hooks_test`, `rescuable_test`, `schema_test`, `skip_test`, `flow_test`, `flow_builder_test` |
+  | Events infrastructure | `events/event_test`, `events/registry_test`, `events/bus/memory_test`, `events/bus/adapter_test`, `events/bus/custom_test`, `events/bus/active_support_notifications_test` |
+  | Plugins | `plugins/base_test`, `plugins/recording_test`, `plugins/instrumentation_test`, `plugins/async_test`, `plugins/transactional_test`, `plugins/events_test`, `plugins/event_handlers_test` |
+
+  Key test patterns: anonymous `Class.new` operations, `set_const` helper for named-constant scenarios (Recording, Async), shared stubs for `ActiveSupport::Notifications`, `ActiveRecord::Base`, `ActiveJob::Base`, and `String#constantize` — all in `test/test_helper.rb` so individual files stay focused.
+
+- **`Rakefile`** — adds a `test` task (Minitest) as the default Rake task:
+
+  ```ruby
+  bundle exec rake test
+  # or simply:
+  bundle exec rake
+  ```
+
+- **`rake` gem** added to the `development/test` group in `Gemfile`.
+
+- **`Easyop::Events::Bus::Adapter`** — a new inheritable base class for custom bus implementations. Subclass this instead of `Bus::Base` when building a transport adapter (RabbitMQ, Kafka, Redis, etc.). Provides two protected utilities on top of `Bus::Base`:
+
+  - `_safe_invoke(handler, event)` — calls `handler.call(event)` and rescues `StandardError`, so one broken subscriber never prevents others from running
+  - `_compile_pattern(pattern)` — converts a glob string or exact string to a `Regexp`, memoized per unique pattern per bus instance (glob→Regexp conversion happens only once regardless of publish volume)
+
+  ```ruby
+  require "easyop/events/bus/adapter"
+
+  # Decorator: wrap any inner bus and add structured logging
+  class LoggingBus < Easyop::Events::Bus::Adapter
+    def initialize(inner = Easyop::Events::Bus::Memory.new)
+      super(); @inner = inner
+    end
+
+    def publish(event)
+      Rails.logger.info "[bus] #{event.name} payload=#{event.payload}"
+      @inner.publish(event)
+    end
+
+    def subscribe(pattern, &block) = @inner.subscribe(pattern, &block)
+    def unsubscribe(handle)        = @inner.unsubscribe(handle)
+  end
+
+  Easyop::Events::Registry.bus = LoggingBus.new
+
+  # Full external broker example — RabbitMQ via Bunny gem:
+  class RabbitBus < Easyop::Events::Bus::Adapter
+    EXCHANGE_NAME = "easyop.events"
+    def initialize(url = ENV.fetch("AMQP_URL")) = (super(); @url = url)
+    def publish(event)
+      exchange.publish(event.to_h.to_json, routing_key: event.name)
+    end
+    def subscribe(pattern, &block)
+      q = channel.queue("", exclusive: true, auto_delete: true)
+      q.bind(exchange, routing_key: pattern.gsub("**", "#"))
+      q.subscribe { |_, _, body| _safe_invoke(block, decode(body)) }
+    end
+    private
+    def decode(body) = Easyop::Events::Event.new(**JSON.parse(body, symbolize_names: true))
+    def connection   = @conn ||= Bunny.new(@url).tap(&:start)
+    def channel      = @ch   ||= connection.create_channel
+    def exchange     = @exch ||= channel.topic(EXCHANGE_NAME, durable: true)
+  end
+  ```
+
+- **`Plugins::Events`** — a new producer plugin that emits domain events after an operation completes. Install on any operation class and declare events with the `emits` DSL:
+
+  ```ruby
+  class PlaceOrder < ApplicationOperation
+    plugin Easyop::Plugins::Events
+
+    emits "order.placed", on: :success, payload: [:order_id, :total]
+    emits "order.failed", on: :failure, payload: ->(ctx) { { error: ctx.error } }
+    emits "order.attempted", on: :always
+  end
+  ```
+
+  Options for `emits`: `on:` (`:success` / `:failure` / `:always`), `payload:` (Proc, Array of ctx keys, or nil for full ctx), `guard:` (optional Proc condition). Events fire in an `ensure` block so they are published even when `call!` raises `Ctx::Failure`. Individual publish failures are swallowed and never crash the operation. Subclasses inherit parent declarations.
+
+- **`Plugins::EventHandlers`** — a new subscriber plugin that wires an operation as a domain event handler:
+
+  ```ruby
+  class SendConfirmation < ApplicationOperation
+    plugin Easyop::Plugins::EventHandlers
+
+    on "order.placed"
+
+    def call
+      OrderMailer.confirm(ctx.order_id).deliver_later
+    end
+  end
+
+  # Async dispatch (requires Plugins::Async also installed):
+  class IndexOrder < ApplicationOperation
+    plugin Easyop::Plugins::Async, queue: "indexing"
+    plugin Easyop::Plugins::EventHandlers
+
+    on "order.*",      async: true
+    on "inventory.**", async: true, queue: "low"
+
+    def call
+      SearchIndex.reindex(ctx.order_id)
+    end
+  end
+  ```
+
+  Supports glob patterns: `"order.*"` matches within one segment; `"order.**"` matches across segments. Registration happens at class-load time. Handler operations receive `ctx.event` (the `Easyop::Events::Event` object) and payload keys merged into ctx.
+
+- **`Easyop::Events::Event`** — immutable, frozen domain event value object. Carries `name`, `payload`, `source` (emitting class name), `metadata`, and `timestamp`. Serializable to a plain Hash via `#to_h`.
+
+- **`Easyop::Events::Bus`** — pluggable bus adapter system with three built-in adapters:
+  - `Bus::Memory` — in-process synchronous bus (default). Thread-safe via Mutex. Supports glob patterns and Regexp subscriptions. Test-friendly: `clear!`, `subscriber_count`.
+  - `Bus::ActiveSupportNotifications` — wraps `ActiveSupport::Notifications`. Lazy-checks for the library.
+  - `Bus::Custom` — wraps any user object responding to `#publish` and `#subscribe`. Validates the interface at construction time.
+
+- **`Easyop::Events::Registry`** — thread-safe global coordination point. Configure once at boot; handler subscriptions are registered against it at class-load time:
+
+  ```ruby
+  # Globally:
+  Easyop::Events::Registry.bus = :memory           # default
+  Easyop::Events::Registry.bus = :active_support
+  Easyop::Events::Registry.bus = MyRabbitBus.new   # custom adapter
+
+  # Or via config:
+  Easyop.configure { |c| c.event_bus = :active_support }
+  ```
+
+- **`Easyop::Configuration#event_bus`** — new configuration key. Accepts `:memory`, `:active_support`, or a bus adapter instance.
+
 ## [0.1.2] — 2026-04-13
 
 ### Added
@@ -65,7 +258,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `examples/easyop_test_app/` — full Rails 8 blog application demonstrating all features in real-world code
 - `examples/usage.rb` — 13 runnable plain-Ruby examples
 
-[Unreleased]: https://github.com/pniemczyk/easyop/compare/v0.1.2...HEAD
-[0.1.2]: https://github.com/pniemczyk/easyop/compare/v0.1.1...v0.1.2
-[0.1.1]: https://github.com/pniemczyk/easyop/compare/v0.1.0...v0.1.1
-[0.1.0]: https://github.com/pniemczyk/easyop/releases/tag/v0.1.0
+[Unreleased]: https://github.com/pniemczyk/easyop/compare/v0.1.4...HEAD
+[0.1.4]: https://github.com/pniemczyk/easyop/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/pniemczyk/easyop/compare/v0.1.2...v0.1.3

data/README.md

@@ -428,6 +428,39 @@ class FullCheckout
 end
 ```
 
+### Recording plugin integration — full call-tree tracing
+
+When step operations have the Recording plugin installed, `Easyop::Flow` automatically forwards the parent-tracing ctx so every step's log entry shows the flow as its `parent_operation_name`. All steps and the flow share the same `root_reference_id`.
+
+**Bare flow** (Recording only on steps — flow is NOT recorded itself, but steps carry correct parent info):
+
+```ruby
+class ProcessCheckout
+  include Easyop::Flow
+  flow ValidateCart, ChargePayment, CreateOrder
+end
+```
+
+**Recommended** — inherit from your recorded base class so the **flow itself appears in operation_logs** as the tree root. Add `transactional false` so step-level transactions aren't shadowed by an outer one:
+
+```ruby
+class ProcessCheckout < ApplicationOperation
+  include Easyop::Flow
+  transactional false   # EasyOp handles rollback; each step owns its transaction
+
+  flow ValidateCart, ChargePayment, CreateOrder
+end
+```
+
+Result in `operation_logs`:
+
+```
+ProcessCheckout    root=aaa  ref=bbb  parent=nil
+  ValidateCart     root=aaa  ref=ccc  parent=ProcessCheckout/bbb
+  ChargePayment    root=aaa  ref=ddd  parent=ProcessCheckout/bbb
+  CreateOrder      root=aaa  ref=eee  parent=ProcessCheckout/bbb
+```
+
 ---
 
 ## `prepare` — Pre-registered Callbacks
@@ -613,6 +646,7 @@ end
 |---|---|---|
 | `model:` | required | ActiveRecord class to write logs into |
 | `record_params:` | `true` | Set `false` to skip serializing ctx params |
+| `record_result:` | `nil` | Plugin-level default for result capture (Hash/Proc/Symbol — see below) |
 
 **Required model columns:**
 
@@ -627,8 +661,91 @@ create_table :operation_logs do |t|
 end
 ```
 
+**Optional flow-tracing columns:**
+
+Add these columns to reconstruct the full call tree when nested flows run. They are populated automatically when present — missing columns are silently skipped (backward-compatible):
+
+```ruby
+add_column :operation_logs, :root_reference_id,     :string
+add_column :operation_logs, :reference_id,          :string
+add_column :operation_logs, :parent_operation_name, :string
+add_column :operation_logs, :parent_reference_id,   :string
+
+add_index :operation_logs, :root_reference_id
+add_index :operation_logs, :reference_id, unique: true
+add_index :operation_logs, :parent_reference_id
+```
+
+All operations triggered by a single top-level call share the same `root_reference_id`. The `parent_operation_name` and `parent_reference_id` columns link each operation to its direct caller. `Easyop::Flow` automatically forwards these ctx keys to child steps — see the [Flow section](#flow--composing-operations) for how to make the flow itself appear as the tree root. Example (flow with nested steps):
+
+```
+FullCheckout      root=aaa  ref=bbb  parent=nil
+  AuthAndValidate root=aaa  ref=ccc  parent=FullCheckout/bbb
+    AuthUser      root=aaa  ref=ddd  parent=AuthAndValidate/ccc
+  ProcessPayment  root=aaa  ref=eee  parent=FullCheckout/bbb
+```
+
+Useful model helpers:
+
+```ruby
+scope :for_tree, ->(id) { where(root_reference_id: id).order(:performed_at) }
+def root?; parent_reference_id.nil?; end
+
+# Fetch the entire execution tree for one top-level call:
+root_log = OperationLog.find_by(operation_name: "FullCheckout", parent_reference_id: nil)
+OperationLog.for_tree(root_log.root_reference_id)
+```
+
 The plugin automatically scrubs these keys from `params_data` before persisting: `:password`, `:password_confirmation`, `:token`, `:secret`, `:api_key`. ActiveRecord objects are serialized as `{ id:, class: }` rather than their full representation.
 
+**`record_result` DSL — capture output data:**
+
+Add an optional `result_data :text` column to persist selected ctx values after the operation runs:
+
+```ruby
+add_column :operation_logs, :result_data, :text  # stored as JSON
+```
+
+Then declare what to record using the `record_result` DSL (three forms):
+
+```ruby
+# Attrs form — one or more ctx keys
+class PlaceOrder < ApplicationOperation
+  record_result attrs: :order_id
+end
+
+class ProcessPayment < ApplicationOperation
+  record_result attrs: [:charge_id, :amount_cents]
+end
+
+# Block form — custom extraction
+class GenerateReport < ApplicationOperation
+  record_result { |ctx| { rows: ctx.rows.count, format: ctx.format } }
+end
+
+# Symbol form — delegates to a private instance method
+class BuildInvoice < ApplicationOperation
+  record_result :build_result
+
+  private
+
+  def build_result
+    { invoice_id: ctx.invoice.id, total: ctx.total }
+  end
+end
+```
+
+Set a plugin-level default inherited by all subclasses:
+
+```ruby
+plugin Easyop::Plugins::Recording, model: OperationLog,
+       record_result: { attrs: :metadata }
+# or: record_result: ->(ctx) { { id: ctx.record_id } }
+# or: record_result: :build_result
+```
+
+Class-level `record_result` overrides the plugin-level default. Missing ctx keys produce `nil` — no error. The `result_data` column is silently skipped when absent from the model table — fully backward-compatible.
+
 **Opt out per class:**
 
 ```ruby
@@ -699,6 +816,198 @@ The plugin defines `Easyop::Plugins::Async::Job` lazily (on first call to `.call
 
 ---
 
+### Plugin: Events
+
+Emits domain events after an operation completes. Unlike the Instrumentation plugin (which is for operation-level tracing), Events carries business domain events through a configurable bus.
+
+```ruby
+require "easyop/events/event"
+require "easyop/events/bus"
+require "easyop/events/bus/memory"
+require "easyop/events/registry"
+require "easyop/plugins/events"
+require "easyop/plugins/event_handlers"
+
+class PlaceOrder < ApplicationOperation
+  plugin Easyop::Plugins::Events
+
+  emits "order.placed", on: :success, payload: [:order_id, :total]
+  emits "order.failed", on: :failure, payload: ->(ctx) { { error: ctx.error } }
+  emits "order.attempted", on: :always
+
+  def call
+    ctx.order_id = Order.create!(ctx.to_h).id
+  end
+end
+```
+
+**`emits` DSL options:**
+
+| Option | Values | Default | Description |
+|---|---|---|---|
+| `on:` | `:success`, `:failure`, `:always` | `:success` | When to fire |
+| `payload:` | `Proc`, `Array`, `nil` | `nil` (full ctx) | Proc receives ctx; Array slices ctx keys |
+| `guard:` | `Proc`, `nil` | `nil` | Extra condition — fires only when truthy |
+
+Events fire in an `ensure` block and are emitted even when `call!` raises. Individual publish failures are swallowed and never crash the operation. `emits` declarations are inherited by subclasses.
+
+---
+
+### Plugin: EventHandlers
+
+Wires an operation class as a domain event handler. Handler operations receive `ctx.event` (the `Easyop::Events::Event` object) and all payload keys merged into ctx.
+
+```ruby
+class SendConfirmation < ApplicationOperation
+  plugin Easyop::Plugins::EventHandlers
+
+  on "order.placed"
+
+  def call
+    event    = ctx.event      # Easyop::Events::Event
+    order_id = ctx.order_id   # payload keys merged into ctx
+    OrderMailer.confirm(order_id).deliver_later
+  end
+end
+```
+
+**Async dispatch** (requires `Plugins::Async` also installed):
+
+```ruby
+class IndexOrder < ApplicationOperation
+  plugin Easyop::Plugins::Async, queue: "indexing"
+  plugin Easyop::Plugins::EventHandlers
+
+  on "order.*",      async: true
+  on "inventory.**", async: true, queue: "low"
+
+  def call
+    # ctx.event_data is a Hash when dispatched async (serializable for ActiveJob)
+    SearchIndex.reindex(ctx.order_id)
+  end
+end
+```
+
+**Glob patterns:**
+- `"order.*"` — matches within one dot-segment (`order.placed`, `order.shipped`)
+- `"warehouse.**"` — matches across segments (`warehouse.stock.updated`, `warehouse.zone.moved`)
+- Plain strings match exactly; `Regexp` is also accepted
+
+Registration happens at class-load time. Configure the bus **before** loading handler classes.
+
+---
+
+### Events Bus — Configurable Transport
+
+The bus adapter controls how events are delivered. Configure it once at boot:
+
+```ruby
+# Default — in-process synchronous (great for tests and simple setups)
+Easyop::Events::Registry.bus = :memory
+
+# ActiveSupport::Notifications (integrates with Rails instrumentation)
+Easyop::Events::Registry.bus = :active_support
+
+# Any custom adapter (RabbitMQ, Kafka, Redis Pub/Sub…)
+Easyop::Events::Registry.bus = MyRabbitBus.new
+
+# Or via config block:
+Easyop.configure { |c| c.event_bus = :active_support }
+```
+
+**Built-in adapters:**
+
+| Adapter | Class | Notes |
+|---|---|---|
+| Memory | `Easyop::Events::Bus::Memory` | Default. Thread-safe, in-process, synchronous. |
+| ActiveSupport | `Easyop::Events::Bus::ActiveSupportNotifications` | Wraps `AS::Notifications`. Requires `activesupport`. |
+| Custom | `Easyop::Events::Bus::Custom` | Wraps any object with `#publish` and `#subscribe`. |
+
+**Building a custom bus — two approaches:**
+
+**Option A — subclass `Bus::Adapter`** (recommended for real transports). Inherits glob helpers, `_safe_invoke`, and `_compile_pattern`:
+
+```ruby
+require "easyop/events/bus/adapter"
+
+# Decorator: wraps any inner bus and adds structured logging
+class LoggingBus < Easyop::Events::Bus::Adapter
+  def initialize(inner = Easyop::Events::Bus::Memory.new)
+    super()
+    @inner = inner
+  end
+
+  def publish(event)
+    Rails.logger.info "[bus:publish] #{event.name} payload=#{event.payload}"
+    @inner.publish(event)
+  end
+
+  def subscribe(pattern, &block) = @inner.subscribe(pattern, &block)
+  def unsubscribe(handle)        = @inner.unsubscribe(handle)
+end
+
+Easyop::Events::Registry.bus = LoggingBus.new
+
+# Full RabbitMQ example (Bunny gem) — uses _safe_invoke for handler safety:
+class RabbitBus < Easyop::Events::Bus::Adapter
+  EXCHANGE_NAME = "easyop.events"
+
+  def initialize(url = ENV.fetch("AMQP_URL", "amqp://localhost"))
+    super()
+    @url = url; @mutex = Mutex.new; @handles = {}
+  end
+
+  def publish(event)
+    exchange.publish(event.to_h.to_json,
+                     routing_key: event.name, content_type: "application/json")
+  end
+
+  def subscribe(pattern, &block)
+    q = channel.queue("", exclusive: true, auto_delete: true)
+    q.bind(exchange, routing_key: _to_amqp(pattern))
+    consumer = q.subscribe { |_, _, body| _safe_invoke(block, decode(body)) }
+    handle = Object.new
+    @mutex.synchronize { @handles[handle.object_id] = { queue: q, consumer: consumer } }
+    handle
+  end
+
+  def unsubscribe(handle)
+    @mutex.synchronize do
+      e = @handles.delete(handle.object_id); return unless e
+      e[:consumer].cancel; e[:queue].delete
+    end
+  end
+
+  def disconnect
+    @mutex.synchronize { @connection&.close; @connection = @channel = @exchange = nil }
+  end
+
+  private
+
+  def _to_amqp(p)  = p.is_a?(Regexp) ? p.source : p.gsub("**", "#")
+  def decode(body) = Easyop::Events::Event.new(**JSON.parse(body, symbolize_names: true))
+  def connection   = @connection ||= Bunny.new(@url, recover_from_connection_close: true).tap(&:start)
+  def channel      = @channel    ||= connection.create_channel
+  def exchange     = @exchange   ||= channel.topic(EXCHANGE_NAME, durable: true)
+end
+
+Easyop::Events::Registry.bus = RabbitBus.new
+at_exit { Easyop::Events::Registry.bus.disconnect }
+```
+
+**Option B — duck-typed object** (no subclassing). Pass any object with `#publish` and `#subscribe`; Registry auto-wraps it in `Bus::Custom`:
+
+```ruby
+class MyKafkaBus
+  def publish(event) = Kafka.produce(event.name, event.to_h.to_json)
+  def subscribe(pattern, &block) = Kafka.subscribe(pattern) { |msg| block.call(decode(msg)) }
+end
+
+Easyop::Events::Registry.bus = MyKafkaBus.new
+```
+
+---
+
 ### Plugin: Transactional
 
 Wraps every operation call in a database transaction. On `ctx.fail!` or any unhandled exception the transaction is rolled back. Supports **ActiveRecord** and **Sequel**.
@@ -1122,3 +1431,84 @@ See the **[AI Tools docs page](https://pniemczyk.github.io/easyop/ai-tools.html)
 | `Easyop::Plugins::Async` | `easyop/plugins/async` | Adds `.call_async` via ActiveJob with AR object serialization |
 | `Easyop::Plugins::Async::Job` | (created lazily) | The ActiveJob class that deserializes and runs the operation |
 | `Easyop::Plugins::Transactional` | `easyop/plugins/transactional` | Wraps operation in an AR/Sequel transaction; `transactional false` to opt out |
+| `Easyop::Plugins::Events` | `easyop/plugins/events` | Emits domain events after execution; `emits` DSL with `on:`, `payload:`, `guard:` |
+| `Easyop::Plugins::EventHandlers` | `easyop/plugins/event_handlers` | Subscribes an operation to handle domain events; `on` DSL with glob patterns |
+
+### Domain Events Infrastructure
+
+| Class/Module | Require | Description |
+|---|---|---|
+| `Easyop::Events::Event` | `easyop/events/event` | Immutable frozen value object: `name`, `payload`, `metadata`, `timestamp`, `source` |
+| `Easyop::Events::Bus::Base` | `easyop/events/bus` | Abstract adapter interface (`publish`, `subscribe`, `unsubscribe`) and glob helpers |
+| `Easyop::Events::Bus::Adapter` | `easyop/events/bus/adapter` | **Inheritable base for custom buses.** Adds `_safe_invoke` + `_compile_pattern` (memoized). Subclass this. |
+| `Easyop::Events::Bus::Memory` | `easyop/events/bus/memory` | In-process synchronous bus (default). Thread-safe. |
+| `Easyop::Events::Bus::ActiveSupportNotifications` | `easyop/events/bus/active_support_notifications` | `ActiveSupport::Notifications` adapter |
+| `Easyop::Events::Bus::Custom` | `easyop/events/bus/custom` | Wraps any user-provided bus object (duck-typed, no subclassing needed) |
+| `Easyop::Events::Registry` | `easyop/events/registry` | Global bus holder + handler subscription registry |
+
+---
+
+## Releasing a New Version
+
+Follow these steps to bump the version, update the changelog, and publish a tagged release.
+
+### 1. Bump the version number
+
+Edit `lib/easyop/version.rb` and increment the version string following [Semantic Versioning](https://semver.org/):
+
+```ruby
+# lib/easyop/version.rb
+module Easyop
+  VERSION = "0.1.4"   # was 0.1.3
+end
+```
+
+### 2. Update the changelog
+
+In `CHANGELOG.md`, move everything under `[Unreleased]` into a new versioned section:
+
+```markdown
+## [Unreleased]
+
+## [0.1.4] — YYYY-MM-DD   # ← new section
+
+### Added
+- …
+
+## [0.1.3] — 2026-04-14
+```
+
+Add a comparison link at the bottom of the file:
+
+```markdown
+[Unreleased]: https://github.com/pniemczyk/easyop/compare/v0.1.4...HEAD
+[0.1.4]: https://github.com/pniemczyk/easyop/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/pniemczyk/easyop/compare/v0.1.2...v0.1.3
+```
+
+### 3. Commit the release changes
+
+```bash
+git add lib/easyop/version.rb CHANGELOG.md
+git commit -m "Release v0.1.4"
+```
+
+### 4. Tag the commit
+
+```bash
+git tag -a v0.1.4 -m "Release v0.1.4"
+```
+
+### 5. Push the commit and tag
+
+```bash
+git push origin master
+git push origin v0.1.4
+```
+
+### 6. Build and push the gem (optional)
+
+```bash
+gem build easyop.gemspec
+gem push easyop-0.1.4.gem
+```

data/lib/easyop/configuration.rb

@@ -8,9 +8,17 @@ module Easyop
     # When false (default), mismatches emit a warning and execution continues.
     attr_accessor :strict_types
 
+    # Bus adapter for domain events (Easyop::Plugins::Events / EventHandlers).
+    # Options: :memory (default), :active_support, or a bus adapter instance.
+    #
+    # @example
+    #   Easyop.configure { |c| c.event_bus = :active_support }
+    attr_accessor :event_bus
+
     def initialize
       @type_adapter = :native
       @strict_types = false
+      @event_bus    = nil  # nil = Memory bus (see Easyop::Events::Registry)
     end
   end