easyop 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c77d9aa5925ea30b3de85fc74618f355ee3498223f79d6184cda21e95574b8d
-  data.tar.gz: 8bd775d8fa095a50b46aafeedec78f2046d54005b6316a1f22ae02b5657c361c
+  metadata.gz: c649ea27731299fcf70421b41e0a19cca45612aa621310bf1bb87a70f5100da6
+  data.tar.gz: 7589af6ce926df84ccafb1df8b705430aaabc82b0929a0b9d8ed9bb4b7db818d
 SHA512:
-  metadata.gz: a01be26e27050c1569f85ee610043ca42268c75054355c4faf230b65599354d9a824b07955f4f13cda25672681d1c934bbeaec15d89be2cfd8ad55681dd29511
-  data.tar.gz: 41d8d5bf9ca01e02146764678c343eac787c2d5445670caa9e8c1a0f0b60ff26b57906f2fb4abd16b7e59d05b05fe65a1400cff4458934df0110bf1af10f5d3a
+  metadata.gz: fc1a7e1c0427da2abb6588c61ece675431708b3b2a2bb623e62356ebfb6edf69025f6c13004ef6967d62f9381cb6c003793958f1c98326c34ba6266a9a56f774
+  data.tar.gz: d40f2a49035f449f95bfcefaae66dacc6c4d2e015d03d66c88f5f74e1680f8d7713d3f079ece4011d77ea238fc6181cf7072fbfe651a4be9be0876e5c8839eb2

data/CHANGELOG.md

@@ -7,6 +7,101 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.5] — 2026-04-14
+
+### Added
+
+- **`scrub_params` DSL for `Easyop::Plugins::Recording`** — declare additional params keys/patterns to scrub from `params_data` on a per-class basis. Accepts `Symbol`, `String`, or `Regexp`. Additive with `SCRUBBED_KEYS` and never replaces the built-in list. Inherited by subclasses; any level of the hierarchy can override.
+
+  ```ruby
+  class ApplicationOperation < ...
+    scrub_params :api_token, /access.?key/i
+  end
+
+  class Orders::CreateOrder < ApplicationOperation
+    scrub_params :card_number   # stacks on top of parent's scrub list
+  end
+  ```
+
+- **`scrub_keys:` option on `plugin Easyop::Plugins::Recording`** — supply a list of extra keys/patterns to scrub at plugin install time. Inherited by all classes that share the same `plugin` declaration.
+
+  ```ruby
+  plugin Easyop::Plugins::Recording,
+         model: OperationLog,
+         scrub_keys: [:stripe_token, /secret/i]
+  ```
+
+- **`Easyop::Configuration#recording_scrub_keys`** — new global config key. Set once at boot and every recorded operation will scrub these keys in addition to `SCRUBBED_KEYS` and any class-level declarations. Accepts `Symbol`, `String`, or `Regexp`.
+
+  ```ruby
+  Easyop.configure do |c|
+    c.recording_scrub_keys = [:api_token, /token/i]
+  end
+  ```
+
+  **Scrub precedence (all layers are additive):**
+  1. `SCRUBBED_KEYS` — always applied (built-in list)
+  2. `Easyop.config.recording_scrub_keys` — global config
+  3. `scrub_keys:` plugin option + `scrub_params` DSL — class hierarchy
+
+## [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
@@ -200,5 +295,7 @@ 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
+[Unreleased]: https://github.com/pniemczyk/easyop/compare/v0.1.5...HEAD
+[0.1.5]: https://github.com/pniemczyk/easyop/compare/v0.1.4...v0.1.5
+[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,8 @@ 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) |
+| `scrub_keys:` | `[]` | Extra keys/patterns to scrub from `params_data` (Symbol, String, Regexp) — additive with built-in list |
 
 **Required model columns:**
 
@@ -627,7 +662,111 @@ create_table :operation_logs do |t|
 end
 ```
 
-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.
+**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)
+```
+
+**Scrubbing params** — all layers are additive (none replaces the built-in list):
+
+1. **Built-in `SCRUBBED_KEYS`** — always applied: `:password`, `:password_confirmation`, `:token`, `:secret`, `:api_key`
+2. **Global config** — applied to every recorded operation:
+   ```ruby
+   Easyop.configure { |c| c.recording_scrub_keys = [:api_token, /token/i] }
+   ```
+3. **Plugin `scrub_keys:` option** — applied to all subclasses that share the plugin install:
+   ```ruby
+   plugin Easyop::Plugins::Recording, model: OperationLog, scrub_keys: [:stripe_secret]
+   ```
+4. **`scrub_params` DSL** — per-class, inheritable, and stackable at any level of the hierarchy:
+   ```ruby
+   class ApplicationOperation < ...
+     scrub_params :internal_token, /access.?key/i
+   end
+   class Payments::ChargeCard < ApplicationOperation
+     scrub_params :card_number   # stacks on top of parent's list
+   end
+   ```
+
+Internal tracing keys (`__recording_*`) are always excluded. 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:**
 
@@ -1342,7 +1481,7 @@ Edit `lib/easyop/version.rb` and increment the version string following [Semanti
 ```ruby
 # lib/easyop/version.rb
 module Easyop
-  VERSION = "0.1.4"   # was 0.1.3
+  VERSION = "0.1.5"   # was 0.1.4
 end
 ```
 
@@ -1353,45 +1492,45 @@ In `CHANGELOG.md`, move everything under `[Unreleased]` into a new versioned sec
 ```markdown
 ## [Unreleased]
 
-## [0.1.4] — YYYY-MM-DD   # ← new section
+## [0.1.5] — YYYY-MM-DD   # ← new section
 
 ### Added
 - …
 
-## [0.1.3] — 2026-04-14
+## [0.1.4] — 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
+[Unreleased]: https://github.com/pniemczyk/easyop/compare/v0.1.5...HEAD
+[0.1.5]: https://github.com/pniemczyk/easyop/compare/v0.1.4...v0.1.5
 [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"
+git commit -m "Release v0.1.5"
 ```
 
 ### 4. Tag the commit
 
 ```bash
-git tag -a v0.1.4 -m "Release v0.1.4"
+git tag -a v0.1.5 -m "Release v0.1.5"
 ```
 
 ### 5. Push the commit and tag
 
 ```bash
 git push origin master
-git push origin v0.1.4
+git push origin v0.1.5
 ```
 
 ### 6. Build and push the gem (optional)
 
 ```bash
 gem build easyop.gemspec
-gem push easyop-0.1.4.gem
+gem push easyop-0.1.5.gem
 ```

data/lib/easyop/configuration.rb

@@ -15,10 +15,19 @@ module Easyop
     #   Easyop.configure { |c| c.event_bus = :active_support }
     attr_accessor :event_bus
 
+    # Extra keys to scrub from params_data across all recorded operations.
+    # Appended to Recording::SCRUBBED_KEYS — never replaces the built-in list.
+    # Accepts Symbol, String, or Regexp (matched against the stringified key name).
+    #
+    # @example
+    #   Easyop.configure { |c| c.recording_scrub_keys = [:api_token, /token/i] }
+    attr_accessor :recording_scrub_keys
+
     def initialize
-      @type_adapter = :native
-      @strict_types = false
-      @event_bus    = nil  # nil = Memory bus (see Easyop::Events::Registry)
+      @type_adapter         = :native
+      @strict_types         = false
+      @event_bus            = nil  # nil = Memory bus (see Easyop::Events::Registry)
+      @recording_scrub_keys = []
     end
   end
 

data/lib/easyop/flow.rb

@@ -1,3 +1,5 @@
+require 'securerandom'
+
 module Easyop
   # Compose a sequence of operations that share a single ctx.
   #
@@ -11,6 +13,27 @@ module Easyop
   #     flow ValidateCart, ChargeCard, CreateOrder, NotifyUser
   #   end
   #
+  # ## Recording plugin integration (flow tracing)
+  #
+  # When steps have the Recording plugin installed, `CallBehavior#call` forwards
+  # the parent ctx keys so every step log entry shows the flow as its parent:
+  #
+  #   # Bare flow — flow itself is not recorded but steps see it as parent:
+  #   class ProcessOrder
+  #     include Easyop::Flow
+  #     flow ValidateCart, ChargeCard
+  #   end
+  #
+  # For full tree reconstruction (flow appears in operation_logs as the root
+  # entry) inherit from your recorded base class and opt out of the transaction
+  # so step-level transactions are not shadowed by an outer one:
+  #
+  #   class ProcessOrder < ApplicationOperation
+  #     include Easyop::Flow
+  #     transactional false   # EasyOp handles rollback; steps own their transactions
+  #     flow ValidateCart, ChargeCard
+  #   end
+  #
   #   result = ProcessOrder.call(user: user, cart: cart)
   #   result.on_success { |ctx| redirect_to order_path(ctx.order) }
   #   result.on_failure { |ctx| flash[:alert] = ctx.error }
@@ -31,6 +54,25 @@ module Easyop
     # otherwise place Operation earlier in the ancestor chain than Flow itself).
     module CallBehavior
       def call
+        # ── Flow-tracing forwarding for the Recording plugin ──────────────────
+        # When Recording is NOT installed on this flow class (i.e. the flow does
+        # not inherit from a base operation that has Recording), set the
+        # __recording_parent_* ctx keys manually so every step operation knows
+        # this flow is its parent.  When Recording IS installed on the flow (its
+        # RunWrapper runs before `call` is reached), it has already set up the
+        # parent context correctly — we detect that via _recording_enabled? and
+        # skip to avoid a conflict.  If Recording is not used at all, these ctx
+        # keys are unused and ignored.
+        _flow_tracing = self.class.name &&
+                        !self.class.respond_to?(:_recording_enabled?)
+        if _flow_tracing
+          ctx[:__recording_root_reference_id]     ||= SecureRandom.uuid
+          _prev_parent_name                         = ctx[:__recording_parent_operation_name]
+          _prev_parent_id                           = ctx[:__recording_parent_reference_id]
+          ctx[:__recording_parent_operation_name]   = self.class.name
+          ctx[:__recording_parent_reference_id]     = SecureRandom.uuid
+        end
+
         pending_guard = nil
 
         self.class._flow_steps.each do |step|
@@ -56,6 +98,12 @@ module Easyop
       rescue Ctx::Failure
         ctx.rollback!
         raise
+      ensure
+        # Restore parent context so any caller above this flow sees the right parent.
+        if _flow_tracing
+          ctx[:__recording_parent_operation_name] = _prev_parent_name
+          ctx[:__recording_parent_reference_id]   = _prev_parent_id
+        end
       end
     end
 

data/lib/easyop/plugins/recording.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module Easyop
   module Plugins
     # Records operation executions to a database model.
@@ -18,6 +20,15 @@ module Easyop
     #   duration_ms     :float
     #   performed_at    :datetime, null: false
     #
+    # Optional flow-tracing columns:
+    #   root_reference_id     :string   # shared across entire execution tree
+    #   reference_id          :string   # unique to this operation execution
+    #   parent_operation_name :string   # class name of the direct parent
+    #   parent_reference_id   :string   # reference_id of the direct parent
+    #
+    # Optional result column:
+    #   result_data           :text     # stored as JSON — selected ctx keys after call
+    #
     # Opt out per operation class:
     #   class MyOp < ApplicationOperation
     #     recording false
@@ -26,15 +37,27 @@ module Easyop
     # Options:
     #   model:         (required) ActiveRecord class
     #   record_params: true       pass false to skip params serialization
+    #   record_result: nil        configure result capture at plugin level (Hash/Proc/Symbol)
+    #   scrub_keys:    []         additional keys/patterns to scrub from params_data
+    #                             (Symbol, String, or Regexp — additive with SCRUBBED_KEYS)
     module Recording
-      # Sensitive keys scrubbed from params_data before persisting.
+      # Sensitive keys always scrubbed from params_data before persisting.
       SCRUBBED_KEYS = %i[password password_confirmation token secret api_key].freeze
 
-      def self.install(base, model:, record_params: true, **_options)
+      # Internal ctx keys used for flow tracing — excluded from params_data.
+      INTERNAL_CTX_KEYS = %i[
+        __recording_root_reference_id
+        __recording_parent_operation_name
+        __recording_parent_reference_id
+      ].freeze
+
+      def self.install(base, model:, record_params: true, record_result: nil, scrub_keys: [], **_options)
         base.extend(ClassMethods)
         base.prepend(RunWrapper)
-        base.instance_variable_set(:@_recording_model,        model)
-        base.instance_variable_set(:@_recording_record_params, record_params)
+        base.instance_variable_set(:@_recording_model,         model)
+        base.instance_variable_set(:@_recording_record_params,  record_params)
+        base.instance_variable_set(:@_recording_record_result,  record_result)
+        base.instance_variable_set(:@_recording_scrub_keys,     Array(scrub_keys))
       end
 
       module ClassMethods
@@ -62,6 +85,59 @@ module Easyop
             true
           end
         end
+
+        # DSL for capturing result data after the operation runs.
+        # Three forms:
+        #   record_result attrs: :key           # one or more ctx keys
+        #   record_result { |ctx| { k: ctx.k } } # block
+        #   record_result :build_result         # private instance method name
+        def record_result(value = nil, attrs: nil, &block)
+          @_recording_record_result = if block
+            block
+          elsif attrs
+            { attrs: attrs }
+          elsif value.is_a?(Symbol)
+            value
+          else
+            value
+          end
+        end
+
+        def _recording_record_result_config
+          if instance_variable_defined?(:@_recording_record_result)
+            @_recording_record_result
+          elsif superclass.respond_to?(:_recording_record_result_config)
+            superclass._recording_record_result_config
+          else
+            nil
+          end
+        end
+
+        # DSL to declare additional keys/patterns to scrub from params_data.
+        # Accepts Symbol, String, or Regexp. Additive with SCRUBBED_KEYS and
+        # any scrub_keys declared on parent classes or at the plugin install level.
+        #
+        # @example
+        #   class ApplicationOperation < ...
+        #     scrub_params :api_token, /access.?key/i
+        #   end
+        def scrub_params(*keys)
+          @_recording_scrub_keys = _own_recording_scrub_keys + keys
+        end
+
+        # Returns the merged scrub list: parent class keys + this class's own keys.
+        # Does NOT include SCRUBBED_KEYS or the global config list — those are
+        # merged at persist time so they stay hot-reloadable.
+        def _recording_scrub_keys
+          parent = superclass.respond_to?(:_recording_scrub_keys) ? superclass._recording_scrub_keys : []
+          parent + _own_recording_scrub_keys
+        end
+
+        private
+
+        def _own_recording_scrub_keys
+          instance_variable_defined?(:@_recording_scrub_keys) ? @_recording_scrub_keys : []
+        end
       end
 
       module RunWrapper
@@ -70,6 +146,23 @@ module Easyop
           return super unless (model = self.class._recording_model)
           return super unless self.class.name # skip anonymous classes
 
+          # -- Flow tracing --
+          # Each operation gets its own reference_id. The root_reference_id is
+          # shared across the entire execution tree via ctx (set once, inherited).
+          reference_id      = SecureRandom.uuid
+          root_reference_id = ctx[:__recording_root_reference_id] ||= SecureRandom.uuid
+
+          # Read current parent context — these become THIS operation's parent fields.
+          parent_operation_name = ctx[:__recording_parent_operation_name]
+          parent_reference_id   = ctx[:__recording_parent_reference_id]
+
+          # Set THIS operation as the parent for any children that run inside super.
+          # Save the previous values so we can restore them after (for siblings).
+          prev_parent_name = parent_operation_name
+          prev_parent_id   = parent_reference_id
+          ctx[:__recording_parent_operation_name] = self.class.name
+          ctx[:__recording_parent_reference_id]   = reference_id
+
           start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           super
         ensure
@@ -78,22 +171,37 @@ module Easyop
           # branch the tap block would be skipped and failures inside flows would
           # never be persisted.
           if start
+            # Restore parent context so sibling steps see the correct parent.
+            ctx[:__recording_parent_operation_name] = prev_parent_name
+            ctx[:__recording_parent_reference_id]   = prev_parent_id
+
             ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
-            _recording_persist!(ctx, model, ms)
+            _recording_persist!(ctx, model, ms,
+              root_reference_id:     root_reference_id,
+              reference_id:          reference_id,
+              parent_operation_name: parent_operation_name,
+              parent_reference_id:   parent_reference_id)
           end
         end
 
         private
 
-        def _recording_persist!(ctx, model, duration_ms)
+        def _recording_persist!(ctx, model, duration_ms,
+                                root_reference_id: nil, reference_id: nil,
+                                parent_operation_name: nil, parent_reference_id: nil)
           attrs = {
-            operation_name: self.class.name,
-            success:        ctx.success?,
-            error_message:  ctx.error,
-            performed_at:   Time.current,
-            duration_ms:    duration_ms
+            operation_name:        self.class.name,
+            success:               ctx.success?,
+            error_message:         ctx.error,
+            performed_at:          Time.current,
+            duration_ms:           duration_ms,
+            root_reference_id:     root_reference_id,
+            reference_id:          reference_id,
+            parent_operation_name: parent_operation_name,
+            parent_reference_id:   parent_reference_id
           }
           attrs[:params_data] = _recording_safe_params(ctx) if self.class._recording_record_params?
+          attrs[:result_data] = _recording_safe_result(ctx) if self.class._recording_record_result_config
 
           # Only write columns the model actually has
           safe = attrs.select { |k, _| model.column_names.include?(k.to_s) }
@@ -103,14 +211,57 @@ module Easyop
         end
 
         def _recording_safe_params(ctx)
+          # Merge all scrub layers (additive, never replaces built-ins):
+          #   1. SCRUBBED_KEYS          — built-in sensitive keys, always applied
+          #   2. Easyop.config          — global extra keys set in an initializer
+          #   3. self.class             — plugin install scrub_keys: + class scrub_params DSL
+          extra = Easyop.config.recording_scrub_keys.to_a + self.class._recording_scrub_keys
           ctx.to_h
-             .except(*SCRUBBED_KEYS)
+             .except(*INTERNAL_CTX_KEYS)
+             .reject { |k, _| _recording_scrub_key?(k, extra) }
              .transform_values { |v| v.is_a?(ActiveRecord::Base) ? { id: v.id, class: v.class.name } : v }
              .to_json
         rescue
           nil
         end
 
+        # Returns true when +key+ matches any entry in +scrub_list+.
+        # Regexp entries match against the stringified key name (case-sensitive
+        # unless the Regexp itself uses /i). Symbol/String entries match by value.
+        def _recording_scrub_key?(key, extra_list)
+          return true if SCRUBBED_KEYS.include?(key.to_sym)
+
+          extra_list.any? do |pattern|
+            case pattern
+            when Regexp then pattern.match?(key.to_s)
+            when Symbol then pattern == key.to_sym
+            else             pattern.to_s == key.to_s
+            end
+          end
+        end
+
+        def _recording_safe_result(ctx)
+          config = self.class._recording_record_result_config
+          return nil unless config
+
+          raw = case config
+                when Hash
+                  keys = Array(config[:attrs])
+                  keys.each_with_object({}) { |k, h| h[k] = ctx[k] }
+                when Proc
+                  config.call(ctx)
+                when Symbol
+                  send(config)
+                end
+
+          return nil unless raw.is_a?(Hash)
+
+          raw.transform_values { |v| v.is_a?(ActiveRecord::Base) ? { id: v.id, class: v.class.name } : v }
+             .to_json
+        rescue
+          nil
+        end
+
         def _recording_warn(err)
           return unless defined?(Rails) && Rails.respond_to?(:logger)
           Rails.logger.warn "[EasyOp::Recording] Failed to record #{self.class.name}: #{err.message}"

data/lib/easyop/schema.rb

@@ -161,7 +161,7 @@ module Easyop
       if Easyop.config.strict_types
         ctx.fail!(error: msg, errors: ctx.errors.merge(field.name => msg))
       else
-        warn "[Easyop] #{msg}"
+        $stderr.puts "[Easyop] #{msg}"
       end
     end
   end

data/lib/easyop/version.rb

@@ -1,3 +1,3 @@
 module Easyop
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easyop
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Pawel Niemczyk