dexkit 0.9.0 → 0.10.0

data/guides/llm/OPERATION.md

@@ -264,7 +264,7 @@ info = Order::Place.explain(product: product, customer: customer, quantity: 2)
 #   transaction: { enabled: true },
 #   rescue_from: { "Stripe::CardError" => :card_declined },
 #   callbacks: { before: 1, after: 2, around: 0 },
-#   pipeline: [:result, :guard, :once, :lock, :record, :transaction, :rescue, :callback],
+#   pipeline: [:trace, :result, :guard, :once, :lock, :record, :transaction, :rescue, :callback],
 #   callable: true
 # }
 ```
@@ -481,8 +481,12 @@ Props serialize/deserialize automatically (Date, Time, BigDecimal, Symbol, `_Ref
 Record execution to database. Requires `Dex.configure { |c| c.record_class = OperationRecord }`.
 
 ```ruby
-create_table :operation_records do |t|
+create_table :operation_records, id: :string do |t|
   t.string :name, null: false  # operation class name
+  t.string :trace_id           # shared trace / correlation ID
+  t.string :actor_type         # root actor type
+  t.string :actor_id           # root actor ID
+  t.jsonb :trace               # full trace snapshot
   t.jsonb :params              # serialized props (nil = not captured)
   t.jsonb :result              # serialized return value
   t.string :status, null: false # pending/running/completed/error/failed
@@ -498,6 +502,8 @@ end
 add_index :operation_records, :name
 add_index :operation_records, :status
 add_index :operation_records, [:name, :status]
+add_index :operation_records, :trace_id
+add_index :operation_records, [:actor_type, :actor_id]
 ```
 
 Control per-operation:
@@ -518,12 +524,30 @@ Required attributes by feature:
 - Async record jobs: `params`
 - `once`: `once_key`, plus `once_key_expires_at` when `expires_in:` is used
 
+Trace columns (`id`, `trace_id`, `actor_type`, `actor_id`, `trace`) are recommended for tracing. Dex persists them when present, omits them when missing.
+
 Untyped results are sanitized to JSON-safe values before persistence: Hash keys round-trip as strings, and objects fall back to `as_json`/`to_s` under `"_dex_value"`.
 
 Status values: `pending` (async enqueued), `running` (async executing), `completed` (success), `error` (business error via `error!`), `failed` (unhandled exception).
 
 When both async and recording are enabled, dexkit automatically stores only the record ID in the job payload instead of full params.
 
+## Execution tracing
+
+Every operation call gets an `op_...` execution ID and joins a fiber-local trace shared across operations, handlers, and async jobs.
+
+```ruby
+Dex::Trace.start(actor: { type: :user, id: current_user.id }) do
+  Order::Place.call(product: product, customer: customer, quantity: 2)
+end
+
+Dex::Trace.trace_id   # => "tr_..."
+Dex::Trace.current    # => [{ type: :actor, ... }, { type: :operation, ... }]
+Dex::Trace.to_s       # => "user:42 > Order::Place(op_2nFg7K)"
+```
+
+Tracing is always on – no opt-in needed. Async operations serialize and restore the trace automatically. When recording is enabled, `trace_id`, `actor_type`, `actor_id`, and `trace` are persisted alongside the usual record fields.
+
 ---
 
 ## Idempotency (once)
@@ -577,7 +601,7 @@ ChargeOrder.clear_once!("webhook-123")    # by raw string key
 
 Clearing is idempotent — clearing a non-existent key is a no-op. After clearing, the next call executes normally.
 
-**Pipeline position:** result → **once** → lock → record → transaction → rescue → guard → callback. The once check runs before locking and recording, so duplicate calls short-circuit early.
+**Pipeline position:** trace → result → guard → **once** → lock → record → transaction → rescue → callback. The once check runs before locking and recording, so duplicate calls short-circuit early.
 
 **Requirements:**
 

data/guides/llm/QUERY.md

@@ -10,12 +10,17 @@ All examples below build on this query unless noted otherwise:
 
 ```ruby
 class UserSearch < Dex::Query
+  description "Search and filter users"
+
   scope { User.all }
 
   prop? :name,   String
   prop? :role,   _Array(String)
   prop? :age_min, Integer
   prop? :status, String
+  prop? :tenant, String
+
+  context tenant: :current_tenant
 
   filter :name,    :contains
   filter :role,    :in
@@ -71,6 +76,51 @@ prop? :age_min, Integer              # optional integer
 
 Reserved prop names: `scope`, `sort`, `resolve`, `call`, `from_params`, `to_params`, `param_key`.
 
+### Description
+
+```ruby
+class UserSearch < Dex::Query
+  description "Search and filter users"
+end
+```
+
+### Context
+
+Same `context` DSL as Operation and Event. Auto-fills props from `Dex.with_context`:
+
+```ruby
+class UserSearch < Dex::Query
+  prop? :tenant, String
+  context tenant: :current_tenant
+end
+
+# In a controller around_action:
+Dex.with_context(current_tenant: current_tenant) do
+  UserSearch.call(name: "ali")  # tenant auto-filled
+end
+```
+
+Identity shorthand: `context :locale` maps prop `:locale` to context key `:locale`.
+
+Explicit values always win over ambient context. Inheritance merges parent + child mappings.
+
+---
+
+## Registry & Export
+
+Queries extend `Registry` — same API as Operation, Event, and Form:
+
+```ruby
+Dex::Query.registry                     # => Set of all named Query subclasses
+UserSearch.description                   # => "Search and filter users"
+
+UserSearch.to_h                          # => { name:, description:, props:, filters:, sorts:, context: }
+UserSearch.to_json_schema                # => JSON Schema (Draft 2020-12)
+
+Dex::Query.export(format: :hash)         # => sorted array of all query to_h
+Dex::Query.export(format: :json_schema)  # => sorted array of all query to_json_schema
+```
+
 ---
 
 ## Filters

data/lib/dex/context_dsl.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Dex
+  # Shared context DSL extracted from ContextSetup.
+  #
+  # Provides the `context` class method, `context_mappings` inheritance,
+  # and `_context_own` storage.  Includers must implement:
+  #   _context_prop_declared?(name) → true/false
+  # and may override:
+  #   _context_field_label → "prop" | "field" (used in error messages)
+  module ContextDSL
+    def context(*names, **mappings)
+      names.each do |name|
+        unless name.is_a?(Symbol)
+          raise ArgumentError, "context shorthand must be a Symbol, got: #{name.inspect}"
+        end
+        mappings[name] = name
+      end
+
+      raise ArgumentError, "context requires at least one mapping" if mappings.empty?
+
+      label = _context_field_label
+      mappings.each do |prop_name, context_key|
+        unless _context_prop_declared?(prop_name)
+          raise ArgumentError,
+            "context references undeclared #{label} :#{prop_name}. Declare the #{label} before calling context."
+        end
+        unless context_key.is_a?(Symbol)
+          raise ArgumentError,
+            "context key must be a Symbol, got: #{context_key.inspect} for #{label} :#{prop_name}"
+        end
+      end
+
+      _context_own.merge!(mappings)
+    end
+
+    def context_mappings
+      parent = superclass.respond_to?(:context_mappings) ? superclass.context_mappings : {}
+      parent.merge(_context_own)
+    end
+
+    private
+
+    def _context_own
+      @_context_own_mappings ||= {}
+    end
+
+    def _context_prop_declared?(_name)
+      raise NotImplementedError, "#{self} must implement _context_prop_declared?"
+    end
+
+    def _context_field_label
+      "prop"
+    end
+  end
+end

data/lib/dex/context_setup.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Dex
-  # Shared context DSL for Operation and Event.
+  # Context DSL for Operation and Event (Literal::Properties-backed).
   #
   # Maps declared props to ambient context keys so they can be auto-filled
   # from Dex.context when not passed explicitly as kwargs.
@@ -9,34 +9,7 @@ module Dex
     extend Dex::Concern
 
     module ClassMethods
-      def context(*names, **mappings)
-        names.each do |name|
-          unless name.is_a?(Symbol)
-            raise ArgumentError, "context shorthand must be a Symbol, got: #{name.inspect}"
-          end
-          mappings[name] = name
-        end
-
-        raise ArgumentError, "context requires at least one mapping" if mappings.empty?
-
-        mappings.each do |prop_name, context_key|
-          unless _context_prop_declared?(prop_name)
-            raise ArgumentError,
-              "context references undeclared prop :#{prop_name}. Declare the prop before calling context."
-          end
-          unless context_key.is_a?(Symbol)
-            raise ArgumentError,
-              "context key must be a Symbol, got: #{context_key.inspect} for prop :#{prop_name}"
-          end
-        end
-
-        _context_own.merge!(mappings)
-      end
-
-      def context_mappings
-        parent = superclass.respond_to?(:context_mappings) ? superclass.context_mappings : {}
-        parent.merge(_context_own)
-      end
+      include ContextDSL
 
       def new(**kwargs)
         mappings = context_mappings
@@ -52,10 +25,6 @@ module Dex
 
       private
 
-      def _context_own
-        @_context_own_mappings ||= {}
-      end
-
       def _context_prop_declared?(name)
         respond_to?(:literal_properties) && literal_properties.any? { |p| p.name == name }
       end

data/lib/dex/event/bus.rb

@@ -44,19 +44,18 @@ module Dex
         def publish(event, sync:)
           return if Suppression.suppressed?(event.class)
 
-          persist(event)
+          trace_data = trace_data_for(event)
+          persist(event, trace_data)
           handlers = subscribers_for(event.class)
           return if handlers.empty?
 
-          event_frame = event.trace_frame
-
           handlers.each do |handler_class|
             if sync
-              Trace.restore(event_frame) do
+              Dex::Trace.restore(trace_data) do
                 handler_class._event_handle(event)
               end
             else
-              enqueue(handler_class, event, event_frame)
+              enqueue(handler_class, event, trace_data)
             end
           end
         end
@@ -67,15 +66,23 @@ module Dex
 
         private
 
-        def persist(event)
+        def persist(event, trace_data)
           store = Dex.configuration.event_store
           return unless store
 
-          store.create!(
+          actor = actor_from_trace(trace_data[:frames])
+          attrs = safe_store_attributes(store, {
+            id: event.id,
+            trace_id: event.trace_id,
+            actor_type: actor&.dig(:actor_type),
+            actor_id: actor&.dig(:id),
+            trace: trace_data[:frames],
             event_type: event.class.name,
             payload: event._props_as_json,
             metadata: event.metadata.as_json
-          )
+          })
+
+          store.create!(**attrs)
         rescue => e
           Event._warn("Failed to persist event: #{e.message}")
         end
@@ -94,6 +101,69 @@ module Dex
           )
         end
 
+        def trace_data_for(event)
+          ambient = Dex::Trace.dump
+          frames = if ambient && trace_matches_event?(ambient, event)
+            trace_frames(ambient)
+          elsif ambient
+            actor_frames(trace_frames(ambient))
+          else
+            []
+          end
+
+          {
+            trace_id: event.trace_id,
+            frames: frames,
+            event_context: event_context_for(event)
+          }
+        end
+
+        def actor_from_trace(frames)
+          Array(frames).find do |frame|
+            frame_type = frame[:type] || frame["type"]
+            frame_type && frame_type.to_sym == :actor
+          end
+        end
+
+        def actor_frames(frames)
+          Array(frames).select do |frame|
+            frame_type = frame[:type] || frame["type"]
+            frame_type && frame_type.to_sym == :actor
+          end
+        end
+
+        def trace_frames(trace_data)
+          Array(trace_data[:frames] || trace_data["frames"])
+        end
+
+        def trace_matches_event?(trace_data, event)
+          trace_id = trace_data[:trace_id] || trace_data["trace_id"]
+          trace_id.to_s == event.trace_id.to_s
+        end
+
+        def event_context_for(event)
+          {
+            id: event.id,
+            trace_id: event.trace_id,
+            event_class: event.class.name,
+            event_ancestry: event.event_ancestry
+          }
+        end
+
+        def safe_store_attributes(store, attributes)
+          if store.respond_to?(:column_names)
+            allowed = store.column_names.to_set
+            attributes.select { |key, _| allowed.include?(key.to_s) }
+          elsif store.respond_to?(:fields)
+            attributes.select do |key, _|
+              field_name = key.to_s
+              store.fields.key?(field_name) || (field_name == "id" && store.fields.key?("_id"))
+            end
+          else
+            attributes
+          end
+        end
+
         def ensure_active_job_loaded!
           return if defined?(ActiveJob::Base)
 

data/lib/dex/event/handler.rb

@@ -69,9 +69,26 @@ module Dex
       end
 
       def self._event_handle(event)
+        execution_id = Dex::Id.generate("hd_")
+        auto_started = Dex::Trace.ensure_started!(trace_id: event.trace_id)
+        pushed = false
+        Dex::Trace.push(
+          type: :handler,
+          id: execution_id,
+          class: name,
+          event_class: event.class.name,
+          event_id: event.id,
+          event_ancestry: event.metadata.event_ancestry
+        )
+        pushed = true
+
         instance = new
         instance.instance_variable_set(:@event, event)
+        instance.instance_variable_set(:@_dex_execution_id, execution_id)
         instance.send(:call)
+      ensure
+        Dex::Trace.pop if pushed
+        Dex::Trace.stop! if auto_started
       end
 
       def self._event_handle_from_payload(event_class_name, payload, metadata_hash)
@@ -96,6 +113,7 @@ module Dex
             timestamp: Time.parse(metadata_hash["timestamp"]),
             trace_id: metadata_hash["trace_id"],
             caused_by_id: metadata_hash["caused_by_id"],
+            event_ancestry: metadata_hash["event_ancestry"] || [],
             context: metadata_hash["context"]
           )
           instance.instance_variable_set(:@metadata, metadata)

data/lib/dex/event/metadata.rb

@@ -1,25 +1,30 @@
 # frozen_string_literal: true
 
-require "securerandom"
-
 module Dex
   class Event
     class Metadata
-      attr_reader :id, :timestamp, :trace_id, :caused_by_id, :context
+      attr_reader :id, :timestamp, :trace_id, :caused_by_id, :event_ancestry, :context
 
-      def initialize(id:, timestamp:, trace_id:, caused_by_id:, context:)
+      def initialize(id:, timestamp:, trace_id:, caused_by_id:, event_ancestry:, context:)
         @id = id
         @timestamp = timestamp
         @trace_id = trace_id
         @caused_by_id = caused_by_id
+        @event_ancestry = event_ancestry
         @context = context
         freeze
       end
 
-      def self.build(caused_by_id: nil)
-        id = SecureRandom.uuid
-        trace_id = Trace.current_trace_id || id
-        caused = caused_by_id || Trace.current_event_id
+      def self.build
+        id = Dex::Id.generate("ev_")
+        trace_id = Dex::Trace.trace_id || Dex::Id.generate("tr_")
+        current_event = Dex::Trace.current_event_context
+        caused = current_event&.dig(:id)
+        ancestry = if current_event
+          Array(current_event[:event_ancestry]) + [caused].compact
+        else
+          []
+        end
 
         ctx = if Dex.configuration.event_context
           begin
@@ -35,6 +40,7 @@ module Dex
           timestamp: Time.now.utc,
           trace_id: trace_id,
           caused_by_id: caused,
+          event_ancestry: ancestry,
           context: ctx
         )
       end
@@ -43,7 +49,8 @@ module Dex
         h = {
           "id" => @id,
           "timestamp" => @timestamp.iso8601(6),
-          "trace_id" => @trace_id
+          "trace_id" => @trace_id,
+          "event_ancestry" => @event_ancestry
         }
         h["caused_by_id"] = @caused_by_id if @caused_by_id
         h["context"] = @context if @context

data/lib/dex/event/processor.rb

@@ -13,7 +13,7 @@ module Dex
           handler = Object.const_get(handler_class)
           retry_config = handler._event_handler_retry_config
 
-          Dex::Event::Trace.restore(trace) do
+          Dex::Trace.restore(trace) do
             handler._event_handle_from_payload(event_class, payload, metadata)
           end
         rescue => _e

data/lib/dex/event/test_helpers.rb

@@ -65,7 +65,7 @@ module Dex
       def setup
         super
         EventTestWrapper.clear_published!
-        Dex::Event::Trace.clear!
+        Dex::Trace.clear!
         Dex::Event::Suppression.clear!
       end
 

data/lib/dex/event/trace.rb

@@ -3,52 +3,39 @@
 module Dex
   class Event
     module Trace
-      STACK_KEY = :_dex_event_trace_stack
-
       class << self
-        include ExecutionState
-
         def with_event(event, &block)
-          stack = _stack
-          stack.push(event.trace_frame)
-          yield
-        ensure
-          stack.pop
+          Dex::Trace.with_event_context(event, &block)
         end
 
         def current_event_id
-          _stack.last&.dig(:id)
+          Dex::Trace.current_event_id
         end
 
         def current_trace_id
-          _stack.last&.dig(:trace_id)
+          Dex::Trace.trace_id
         end
 
         def dump
-          frame = _stack.last
-          return nil unless frame
-
-          { id: frame[:id], trace_id: frame[:trace_id] }
+          Dex::Trace.dump
         end
 
         def restore(data, &block)
           return yield unless data
 
-          stack = _stack
-          stack.push(data)
-          yield
-        ensure
-          stack.pop if data
+          if data.is_a?(Hash) && (data.key?(:frames) || data.key?("frames"))
+            Dex::Trace.restore(data, &block)
+          else
+            Dex::Trace.restore_event_context(
+              event_id: data[:id] || data["id"],
+              trace_id: data[:trace_id] || data["trace_id"],
+              &block
+            )
+          end
         end
 
         def clear!
-          _execution_state[STACK_KEY] = []
-        end
-
-        private
-
-        def _stack
-          _execution_state[STACK_KEY] ||= []
+          Dex::Trace.clear!
         end
       end
     end

data/lib/dex/event.rb

@@ -9,7 +9,7 @@ require_relative "event/suppression"
 module Dex
   class Event
     RESERVED_PROP_NAMES = %i[
-      id timestamp trace_id caused_by_id caused_by
+      id timestamp trace_id caused_by_id caused_by event_ancestry
       context publish metadata sync
     ].to_set.freeze
 
@@ -67,8 +67,8 @@ module Dex
     def timestamp = metadata.timestamp
     def trace_id = metadata.trace_id
     def caused_by_id = metadata.caused_by_id
+    def event_ancestry = metadata.event_ancestry
     def context = metadata.context
-    def trace_frame = { id: id, trace_id: trace_id }
 
     # Publishing
     def publish(sync: false)
@@ -85,11 +85,6 @@ module Dex
       end
     end
 
-    # Tracing
-    def trace(&block)
-      Trace.with_event(self, &block)
-    end
-
     # Suppression
     def self.suppress(*classes, &block)
       Suppression.suppress(*classes, &block)

data/lib/dex/form/context.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Dex
+  class Form
+    # Context DSL for Form (ActiveModel::Attributes-backed).
+    #
+    # Same DSL as Operation/Event context, but checks attribute_names
+    # instead of literal_properties. Injection happens in Form#initialize.
+    module Context
+      extend Dex::Concern
+
+      module ClassMethods
+        include ContextDSL
+
+        private
+
+        def _context_prop_declared?(name)
+          attribute_names.include?(name.to_s)
+        end
+
+        def _context_field_label
+          "field"
+        end
+      end
+    end
+  end
+end