dexkit 0.9.0 → 0.11.0

data/lib/dex/trace.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Dex
+  module Trace
+    FIBER_KEY = :_dex_trace
+    FRAME_TYPES = %i[actor operation handler].freeze
+
+    class << self
+      def start(actor: nil, trace_id: nil)
+        previous = _dump_state
+        _set_state(trace_id: (trace_id || Dex::Id.generate("tr_")).to_s, frames: [], event_context: nil)
+        _state[:frames] << _normalize_actor(actor) if actor
+        yield
+      ensure
+        _restore_state(previous)
+      end
+
+      def ensure_started!(trace_id: nil)
+        return false if active?
+
+        _state[:trace_id] = (trace_id || Dex::Id.generate("tr_")).to_s
+        true
+      end
+
+      def active?
+        !trace_id.nil?
+      end
+
+      def with_frame(frame)
+        auto_started = ensure_started!
+        pushed = false
+        push(frame)
+        pushed = true
+        yield
+      ensure
+        pop if pushed
+        stop! if auto_started
+      end
+
+      def with_event_context(event)
+        auto_started = ensure_started!(trace_id: event.trace_id)
+        previous = _state[:event_context]
+        _state[:event_context] = _build_event_context(event)
+        yield
+      ensure
+        _state[:event_context] = previous
+        stop! if auto_started
+      end
+
+      def restore_event_context(event_id:, trace_id:, event_class: nil, event_ancestry: [])
+        previous = _dump_state
+        effective_trace_id = trace_id&.to_s || _state[:trace_id]
+        _set_state(
+          trace_id: effective_trace_id,
+          frames: _normalize_frames(_state[:frames]),
+          event_context: {
+            id: event_id&.to_s,
+            trace_id: effective_trace_id,
+            event_class: event_class,
+            event_ancestry: Array(event_ancestry).compact.map(&:to_s)
+          }
+        )
+        yield
+      ensure
+        _restore_state(previous)
+      end
+
+      def push(frame)
+        _state[:frames] << _normalize_frame(frame)
+      end
+
+      def pop
+        _state[:frames].pop
+      end
+
+      def current
+        _deep_copy(_state[:frames])
+      end
+
+      def trace_id
+        _state[:trace_id]
+      end
+
+      def current_id
+        _state[:frames].last&.dig(:id)
+      end
+
+      def actor
+        frame = _state[:frames].find { |entry| entry[:type] == :actor }
+        frame ? _deep_copy(frame) : nil
+      end
+
+      def current_event_id
+        current_event_context&.dig(:id)
+      end
+
+      def current_event_context
+        context = _state[:event_context]
+        return _deep_copy(context) if context
+
+        handler = _state[:frames].reverse.find { |frame| frame[:type] == :handler && frame[:event_id] }
+        return nil unless handler
+
+        {
+          id: handler[:event_id],
+          trace_id: trace_id,
+          event_class: handler[:event_class],
+          event_ancestry: _deep_copy(Array(handler[:event_ancestry]))
+        }
+      end
+
+      def dump
+        return nil unless active?
+
+        data = {
+          trace_id: trace_id,
+          frames: current
+        }
+        data[:event_context] = _deep_copy(_state[:event_context]) if _state[:event_context]
+        data
+      end
+
+      def restore(data)
+        return yield unless data
+
+        previous = _dump_state
+        _set_state(
+          trace_id: _fetch(data, :trace_id)&.to_s,
+          frames: _normalize_frames(_fetch(data, :frames)),
+          event_context: _normalize_event_context(_fetch(data, :event_context))
+        )
+        yield
+      ensure
+        _restore_state(previous)
+      end
+
+      def to_s
+        current.filter_map { |frame| _format_frame(frame) }.join(" > ")
+      end
+
+      def clear!
+        Fiber[FIBER_KEY] = nil
+      end
+      alias_method :stop!, :clear!
+
+      private
+
+      def _state
+        Fiber[FIBER_KEY] ||= { trace_id: nil, frames: [], event_context: nil }
+      end
+
+      def _set_state(trace_id:, frames:, event_context:)
+        Fiber[FIBER_KEY] = {
+          trace_id: trace_id,
+          frames: frames,
+          event_context: event_context
+        }
+      end
+
+      def _dump_state
+        state = _state
+        return nil unless state[:trace_id] || !state[:frames].empty? || state[:event_context]
+
+        {
+          trace_id: state[:trace_id],
+          frames: _deep_copy(state[:frames]),
+          event_context: _deep_copy(state[:event_context])
+        }
+      end
+
+      def _restore_state(state)
+        if state
+          _set_state(
+            trace_id: state[:trace_id],
+            frames: _normalize_frames(state[:frames]),
+            event_context: _normalize_event_context(state[:event_context])
+          )
+        else
+          clear!
+        end
+      end
+
+      def _normalize_frames(frames)
+        Array(frames).map { |frame| _normalize_frame(frame) }
+      end
+
+      def _normalize_actor(actor)
+        raise ArgumentError, "actor must be a Hash" unless actor.is_a?(Hash)
+
+        normalized = _symbolize(actor)
+        actor_type = normalized[:type]
+        raise ArgumentError, "actor must include :type" if actor_type.nil? || actor_type.to_s.strip.empty?
+
+        frame = { type: :actor, actor_type: actor_type.to_s }
+        frame[:id] = normalized[:id].to_s if normalized.key?(:id) && !normalized[:id].nil?
+
+        normalized.each do |key, value|
+          next if %i[type id].include?(key)
+
+          frame[key] = _deep_copy(value)
+        end
+
+        frame
+      end
+
+      def _normalize_frame(frame)
+        raise ArgumentError, "trace frame must be a Hash" unless frame.is_a?(Hash)
+
+        normalized = _symbolize(frame)
+        type = normalized[:type]&.to_sym
+        raise ArgumentError, "trace frame type is required" unless type
+        raise ArgumentError, "unknown trace frame type: #{type.inspect}" unless FRAME_TYPES.include?(type)
+
+        normalized[:type] = type
+        normalized[:id] = normalized[:id].to_s if normalized.key?(:id) && !normalized[:id].nil?
+        normalized[:actor_type] = normalized[:actor_type].to_s if normalized.key?(:actor_type) && !normalized[:actor_type].nil?
+        normalized[:event_id] = normalized[:event_id].to_s if normalized.key?(:event_id) && !normalized[:event_id].nil?
+        normalized[:event_ancestry] = Array(normalized[:event_ancestry]).compact.map(&:to_s) if normalized.key?(:event_ancestry)
+        normalized
+      end
+
+      def _normalize_event_context(context)
+        return nil unless context
+
+        {
+          id: _fetch(context, :id)&.to_s,
+          trace_id: _fetch(context, :trace_id)&.to_s,
+          event_class: _fetch(context, :event_class),
+          event_ancestry: Array(_fetch(context, :event_ancestry)).compact.map(&:to_s)
+        }
+      end
+
+      def _build_event_context(event)
+        {
+          id: event.id.to_s,
+          trace_id: event.trace_id.to_s,
+          event_class: event.class.name,
+          event_ancestry: Array(event.metadata.event_ancestry).compact.map(&:to_s)
+        }
+      end
+
+      def _symbolize(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key.respond_to?(:to_sym) ? key.to_sym : key] = _deep_copy(value)
+        end
+      end
+
+      def _deep_copy(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, nested), result| result[key] = _deep_copy(nested) }
+        when Array
+          value.map { |nested| _deep_copy(nested) }
+        else
+          value
+        end
+      end
+
+      def _fetch(hash, key)
+        hash[key] || hash[key.to_s]
+      end
+
+      def _format_frame(frame)
+        case frame[:type]
+        when :actor
+          return nil unless frame[:actor_type]
+
+          frame[:id] ? "#{frame[:actor_type]}:#{frame[:id]}" : frame[:actor_type]
+        when :operation
+          name = frame[:class] || "Operation"
+          id = _display_id(frame[:id])
+          id ? "#{name}(#{id})" : name
+        when :handler
+          event_class = frame[:event_class] || "Event"
+          handler_name = frame[:class] || "Handler"
+          id = _display_id(frame[:id])
+          id ? "[#{event_class}] #{handler_name}(#{id})" : "[#{event_class}] #{handler_name}"
+        end
+      end
+
+      def _display_id(id)
+        return nil unless id
+
+        prefix, suffix = id.split("_", 2)
+        return id[0, 10] unless suffix
+
+        "#{prefix}_#{suffix[0, 7]}"
+      end
+    end
+  end
+end

data/lib/dex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dex
-  VERSION = "0.9.0"
+  VERSION = "0.11.0"
 end

data/lib/dexkit.rb

@@ -10,13 +10,18 @@ require_relative "dex/concern"
 require_relative "dex/ref_type"
 require_relative "dex/type_coercion"
 require_relative "dex/props_setup"
+require_relative "dex/context_dsl"
 require_relative "dex/context_setup"
 require_relative "dex/error"
+require_relative "dex/operation_failed"
+require_relative "dex/timeout"
 require_relative "dex/settings"
 require_relative "dex/pipeline"
 require_relative "dex/executable"
 require_relative "dex/registry"
 require_relative "dex/type_serializer"
+require_relative "dex/id"
+require_relative "dex/trace"
 require_relative "dex/operation"
 require_relative "dex/event"
 require_relative "dex/tool"
@@ -25,15 +30,13 @@ require_relative "dex/query"
 
 module Dex
   class Configuration
-    attr_accessor :record_class, :event_store, :event_context, :restore_event_context
+    attr_accessor :record_class, :event_store
     attr_reader :transaction_adapter
 
     def initialize
       @record_class = nil
       @transaction_adapter = nil
       @event_store = nil
-      @event_context = nil
-      @restore_event_context = nil
     end
 
     def transaction_adapter=(adapter)
@@ -77,6 +80,22 @@ module Dex
       configuration.transaction_adapter = adapter
     end
 
+    def actor
+      frame = Dex::Trace.actor
+      return nil unless frame
+
+      payload = frame.dup
+      payload.delete(:type)
+      payload[:type] = payload.delete(:actor_type) if payload.key?(:actor_type)
+      payload
+    end
+
+    def system(name = nil)
+      h = { type: :system }
+      h[:name] = name.to_s if name
+      h.freeze
+    end
+
     CONTEXT_KEY = :_dex_context
     EMPTY_CONTEXT = {}.freeze
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexkit
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Jacek Galanciak
@@ -167,7 +167,9 @@ files:
 - guides/llm/FORM.md
 - guides/llm/OPERATION.md
 - guides/llm/QUERY.md
+- guides/llm/TOOL.md
 - lib/dex/concern.rb
+- lib/dex/context_dsl.rb
 - lib/dex/context_setup.rb
 - lib/dex/error.rb
 - lib/dex/event.rb
@@ -180,12 +182,13 @@ files:
 - lib/dex/event/suppression.rb
 - lib/dex/event/test_helpers.rb
 - lib/dex/event/test_helpers/assertions.rb
-- lib/dex/event/trace.rb
-- lib/dex/event_test_helpers.rb
 - lib/dex/executable.rb
 - lib/dex/form.rb
+- lib/dex/form/context.rb
+- lib/dex/form/export.rb
 - lib/dex/form/nesting.rb
 - lib/dex/form/uniqueness_validator.rb
+- lib/dex/id.rb
 - lib/dex/match.rb
 - lib/dex/operation.rb
 - lib/dex/operation/async_proxy.rb
@@ -207,12 +210,16 @@ files:
 - lib/dex/operation/test_helpers/assertions.rb
 - lib/dex/operation/test_helpers/execution.rb
 - lib/dex/operation/test_helpers/stubbing.rb
+- lib/dex/operation/ticket.rb
+- lib/dex/operation/trace_wrapper.rb
 - lib/dex/operation/transaction_adapter.rb
 - lib/dex/operation/transaction_wrapper.rb
+- lib/dex/operation_failed.rb
 - lib/dex/pipeline.rb
 - lib/dex/props_setup.rb
 - lib/dex/query.rb
 - lib/dex/query/backend.rb
+- lib/dex/query/export.rb
 - lib/dex/query/filtering.rb
 - lib/dex/query/sorting.rb
 - lib/dex/railtie.rb
@@ -221,7 +228,9 @@ files:
 - lib/dex/settings.rb
 - lib/dex/test_helpers.rb
 - lib/dex/test_log.rb
+- lib/dex/timeout.rb
 - lib/dex/tool.rb
+- lib/dex/trace.rb
 - lib/dex/type_coercion.rb
 - lib/dex/type_serializer.rb
 - lib/dex/version.rb

data/lib/dex/event/trace.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-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
-        end
-
-        def current_event_id
-          _stack.last&.dig(:id)
-        end
-
-        def current_trace_id
-          _stack.last&.dig(:trace_id)
-        end
-
-        def dump
-          frame = _stack.last
-          return nil unless frame
-
-          { id: frame[:id], trace_id: frame[:trace_id] }
-        end
-
-        def restore(data, &block)
-          return yield unless data
-
-          stack = _stack
-          stack.push(data)
-          yield
-        ensure
-          stack.pop if data
-        end
-
-        def clear!
-          _execution_state[STACK_KEY] = []
-        end
-
-        private
-
-        def _stack
-          _execution_state[STACK_KEY] ||= []
-        end
-      end
-    end
-  end
-end

data/lib/dex/event_test_helpers.rb

@@ -1,3 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "event/test_helpers"