dexkit 0.7.0 → 0.9.0

data/guides/llm/OPERATION.md

@@ -1,6 +1,6 @@
 # Dex::Operation — LLM Reference
 
-Copy this to your app's operations directory (e.g., `app/operations/AGENTS.md`) so coding agents know the full API when implementing and testing operations.
+Install with `rake dex:guides` or copy manually to `app/operations/AGENTS.md`.
 
 ---
 
@@ -95,7 +95,7 @@ prop? :note, String                       # optional (nilable, default: nil)
 
 ### _Ref(Model)
 
-Accepts model instances or IDs, coerces IDs via `Model.find(id)`. With `lock: true`, uses `Model.lock.find(id)` (SELECT FOR UPDATE). Instances pass through without re-locking. In serialization (recording, async), stores model ID only.
+Accepts model instances or IDs, coerces IDs via `Model.find(id)`. With `lock: true`, uses `Model.lock.find(id)` (SELECT FOR UPDATE) – requires a model that responds to `.lock` (ActiveRecord). Mongoid documents do not support row locks and raise `ArgumentError` at declaration time. Instances pass through without re-locking. In serialization (recording, async), stores model ID only via `id.as_json`, so Mongoid BSON::ObjectId values are safe in ActiveJob payloads too. IDs are treated as strings in JSON Schema – this supports integer PKs, UUIDs, and Mongoid BSON::ObjectId equally.
 
 Outside the class body (e.g., in tests), use `Dex::RefType.new(Model)` instead of `_Ref(Model)`.
 
@@ -234,6 +234,51 @@ result.details  # => [{ guard: :unauthorized, message: "..." }, ...]
 
 ---
 
+## Explain
+
+Full preflight check — resolves context, coerces props, evaluates guards, computes derived keys, reports settings. No side effects, `perform` never runs.
+
+```ruby
+info = Order::Place.explain(product: product, customer: customer, quantity: 2)
+```
+
+Returns a frozen Hash:
+
+```ruby
+info = Order::Place.explain(product: product, customer: customer, quantity: 2)
+# => {
+#   operation: "Order::Place",
+#   props: { product: #<Product>, customer: #<Customer>, quantity: 2 },
+#   context: {
+#     resolved: { customer: #<Customer> },
+#     mappings: { customer: :current_customer },
+#     source: { customer: :ambient }   # :ambient, :explicit, or :default
+#   },
+#   guards: {
+#     passed: true,
+#     results: [{ name: :out_of_stock, passed: true }, ...]
+#   },
+#   once: { active: true, key: "Order::Place/product_id=7", status: :fresh, expires_in: nil },
+#   lock: { active: true, key: "order:7", timeout: nil },
+#   record: { enabled: true, params: true, result: true },
+#   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],
+#   callable: true
+# }
+```
+
+- Invalid props (`Literal::TypeError`, `ArgumentError`) return a partial result with `info[:error]` — class-level info still available, instance-dependent sections degrade to empty/nil. Static lock keys preserved. Context source uses `:missing` for props without defaults. Other errors propagate normally
+- `info[:callable]` is a full preflight verdict — checks guards AND once blocking statuses; always `false` when props are invalid
+- Once status: `:fresh` (new), `:exists` (would replay), `:expired`, `:pending` (in-flight), `:invalid` (nil key), `:misconfigured` (anonymous op, missing record step, missing column), `:unavailable` (no backend)
+- Guard results include `message:` on failures and `skipped: true` when a guard was skipped via `requires:` dependency
+- Custom middleware can contribute via `_name_explain(instance, info)` class methods
+
+**Use cases:** console debugging, admin tooling, LLM agent preflight, test assertions.
+
+---
+
 ## Flow Control
 
 All three halt execution immediately via non-local exit (work from `perform`, helpers, and callbacks).
@@ -363,11 +408,11 @@ end
 
 ## Transactions
 
-Operations run inside database transactions by default. All changes roll back on error. Nested operations share the outer transaction.
+Operations run inside database transactions when Dex has an active transaction adapter. ActiveRecord is auto-detected. In Mongoid-only apps, no adapter is active, so transactions are automatically disabled – but `after_commit` still works (callbacks fire immediately after success). If you need Mongoid transactions, use `Mongoid.transaction` directly inside `perform`.
 
 ```ruby
 transaction false        # disable
-transaction :mongoid     # adapter override (default: auto-detect AR → Mongoid)
+transaction :active_record  # explicit adapter
 ```
 
 Child classes can re-enable: `transaction true`.
@@ -388,7 +433,7 @@ end
 Callbacks are always deferred — they run after the outermost operation boundary succeeds:
 
 - **Transactional operations:** deferred until the DB transaction commits.
-- **Non-transactional operations:** queued in memory, flushed after the operation pipeline completes successfully.
+- **Non-transactional operations (including Mongoid-only):** queued in memory, flushed after the operation pipeline completes successfully.
 - **Nested operations:** callbacks queue up and flush once at the outermost successful boundary.
 - **On error (`error!` or exception):** queued callbacks are discarded.
 
@@ -396,13 +441,11 @@ Multiple blocks run in registration order.
 
 **ActiveRecord:** requires Rails 7.2+ (`after_all_transactions_commit`).
 
-**Mongoid:** deferred across nested Dex operations. Ambient `Mongoid.transaction` blocks opened outside Dex are not detected — callbacks will fire immediately in that case.
-
 ---
 
 ## Advisory Locking
 
-Mutual exclusion via database advisory locks (requires `with_advisory_lock` gem). Wraps **outside** the transaction.
+Mutual exclusion via database advisory locks (requires `with_advisory_lock` gem). Wraps **outside** the transaction. ActiveRecord-only; Mongoid-only apps get a clear `LoadError`.
 
 ```ruby
 advisory_lock { "pay:#{charge_id}" }    # dynamic key from props
@@ -465,7 +508,17 @@ record result: false      # params only
 record params: false      # result only
 ```
 
-All outcomes are recorded — success (`completed`), business errors (`error`), and exceptions (`failed`). Recording runs outside the operation's own transaction so error records survive its rollbacks. Records still participate in ambient transactions (e.g., an outer operation's transaction). Missing columns silently skipped.
+All outcomes are recorded — success (`completed`), business errors (`error`), and exceptions (`failed`). Recording runs outside the operation's own transaction so error records survive its rollbacks. Records still participate in ambient transactions (e.g., an outer operation's transaction). Dex validates the configured record model before use and raises if required attributes are missing.
+
+Required attributes by feature:
+
+- Core recording: `name`, `status`, `error_code`, `error_message`, `error_details`, `performed_at`
+- Params capture: `params` unless `record params: false`
+- Result capture: `result` unless `record result: false`
+- Async record jobs: `params`
+- `once`: `once_key`, plus `once_key_expires_at` when `expires_in:` is used
+
+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).
 
@@ -529,7 +582,7 @@ Clearing is idempotent — clearing a non-existent key is a no-op. After clearin
 **Requirements:**
 
 - Record backend must be configured (`Dex.configure { |c| c.record_class = OperationRecord }`)
-- The record table must have `once_key` and `once_key_expires_at` columns (see Recording schema above)
+- The record backend must satisfy the Recording requirements above, and `once` additionally requires `once_key` plus `once_key_expires_at` when `expires_in:` is used
 - `once` cannot be declared with `record false` — raises `ArgumentError`
 - Only one `once` declaration per operation
 
@@ -541,11 +594,10 @@ Clearing is idempotent — clearing a non-existent key is a no-op. After clearin
 # config/initializers/dexkit.rb
 Dex.configure do |config|
   config.record_class = OperationRecord  # model for recording (default: nil)
-  config.transaction_adapter = nil        # auto-detect (default); or :active_record / :mongoid
 end
 ```
 
-All DSL methods validate arguments at declaration time — typos and wrong types raise `ArgumentError` immediately (e.g., `error "string"`, `async priority: 5`, `transaction :redis`).
+All DSL methods validate arguments at declaration time — typos and wrong types raise `ArgumentError` immediately (e.g., `error "string"`, `async priority: 5`, `transaction :redis`). Only `:active_record` is a valid transaction adapter.
 
 ---
 
@@ -553,22 +605,20 @@ All DSL methods validate arguments at declaration time — typos and wrong types
 
 ```ruby
 # test/test_helper.rb
-require "dex/test_helpers"
+require "dex/operation/test_helpers"
 
 class Minitest::Test
-  include Dex::TestHelpers
+  include Dex::Operation::TestHelpers
 end
 ```
 
 Not autoloaded — stays out of production. TestLog and stubs are auto-cleared in `setup`.
 
-For Mongoid-backed operation tests, run against a MongoDB replica set (MongoDB transactions require it).
-
 ### Subject & Execution
 
 ```ruby
 class CreateUserTest < Minitest::Test
-  include Dex::TestHelpers
+  include Dex::Operation::TestHelpers
 
   testing CreateUser  # default for all helpers
 
@@ -733,7 +783,7 @@ Each entry has: `name`, `operation_class`, `params`, `result` (Ok/Err), `duratio
 
 ```ruby
 class CreateUserTest < Minitest::Test
-  include Dex::TestHelpers
+  include Dex::Operation::TestHelpers
 
   testing CreateUser
 
@@ -780,4 +830,63 @@ end
 
 ---
 
+## Registry, Export & Description
+
+### Description
+
+Operations can declare a human-readable description. Props can include `desc:`:
+
+```ruby
+class Order::Place < Dex::Operation
+  description "Places a new order, charges payment, and schedules fulfillment"
+
+  prop :product, _Ref(Product), desc: "Product to order"
+  prop :quantity, _Integer(1..), desc: "Number of units"
+end
+```
+
+Descriptions appear in `contract.to_h`, `to_json_schema`, `explain`, and LLM tool definitions.
+
+### Registry
+
+```ruby
+Dex::Operation.registry          # => #<Set: {Order::Place, Order::Cancel, ...}>
+Dex::Operation.deregister(klass) # remove from registry (useful in tests)
+Dex::Operation.clear!            # empty the registry
+```
+
+Only named, reachable classes are included. Anonymous classes and stale objects from code reloads are excluded. Populates lazily via `inherited` — in Rails, `eager_load!` to get the full list.
+
+### Export
+
+```ruby
+Order::Place.contract.to_h
+# => { name: "Order::Place", description: "...", params: { product: { type: "Ref(Product)", required: true, desc: "..." } }, ... }
+
+Order::Place.contract.to_json_schema                    # params input schema (default)
+Order::Place.contract.to_json_schema(section: :success) # success return schema
+Order::Place.contract.to_json_schema(section: :errors)  # error catalog schema
+Order::Place.contract.to_json_schema(section: :full)    # everything
+
+Dex::Operation.export                          # all operations as hashes
+Dex::Operation.export(format: :json_schema)    # all as JSON Schema
+```
+
+### LLM Tools (ruby-llm integration)
+
+```ruby
+chat = RubyLLM.chat
+chat.with_tools(*Dex::Tool.all)                     # all operations as tools
+chat.with_tools(*Dex::Tool.from_namespace("Order")) # namespace filter
+chat.with_tools(Dex::Tool.explain_tool)              # preflight check tool
+
+Dex.with_context(current_user: user) do
+  chat.ask("Place an order for 2 units of product #42")
+end
+```
+
+Requires `gem 'ruby_llm'` in your Gemfile. Lazy-loaded — ruby-llm is only required when you call `Dex::Tool`.
+
+---
+
 **End of reference.**

data/guides/llm/QUERY.md

@@ -1,6 +1,6 @@
 # Dex::Query — LLM Reference
 
-Copy this to your app's queries directory (e.g., `app/queries/AGENTS.md`) so coding agents know the full API when implementing and testing queries.
+Install with `rake dex:guides` or copy manually to `app/queries/AGENTS.md`.
 
 ---
 
@@ -91,7 +91,7 @@ Reserved prop names: `scope`, `sort`, `resolve`, `call`, `from_params`, `to_para
 | `:in` | `IN (values)` | `filter :roles, :in, column: :role` |
 | `:not_in` | `NOT IN (values)` | `filter :roles, :not_in, column: :role` |
 
-String strategies (`:contains`, `:starts_with`, `:ends_with`) use case-insensitive matching. With ActiveRecord, this uses Arel `matches` (LIKE); with Mongoid, case-insensitive regex. Wildcards in values are auto-sanitized. The adapter is auto-detected from the scope.
+String strategies (`:contains`, `:starts_with`, `:ends_with`) use case-insensitive matching. With ActiveRecord, this uses Arel `matches` (LIKE); with Mongoid, case-insensitive regex. Wildcards in values are auto-sanitized. The adapter is auto-detected from the scope, and Mongoid association scopes/proxies are normalized to `Mongoid::Criteria` automatically.
 
 ### Column Mapping
 
@@ -159,7 +159,7 @@ Only one default per class. Applied when no sort is provided.
 
 ### `.call`
 
-Returns a queryable scope (`ActiveRecord::Relation` or `Mongoid::Criteria`):
+Returns a queryable scope (`ActiveRecord::Relation` or `Mongoid::Criteria`). Association scopes like `current_user.posts` work too:
 
 ```ruby
 users = UserSearch.call(name: "ali", role: %w[admin], sort: "-name")

data/lib/dex/event/bus.rb

@@ -81,6 +81,7 @@ module Dex
         end
 
         def enqueue(handler_class, event, trace_data)
+          ensure_active_job_loaded!
           ctx = event.context
 
           Dex::Event::Processor.perform_later(
@@ -92,6 +93,12 @@ module Dex
             context: ctx
           )
         end
+
+        def ensure_active_job_loaded!
+          return if defined?(ActiveJob::Base)
+
+          raise LoadError, "ActiveJob is required for async event handlers. Add 'activejob' to your Gemfile."
+        end
       end
     end
   end

data/lib/dex/event/export.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    module Export
+      module_function
+
+      def build_hash(source)
+        h = {}
+        h[:name] = source.name if source.name
+        desc = source.description
+        h[:description] = desc if desc
+        h[:props] = _serialize_props(source)
+        h
+      end
+
+      def build_json_schema(source)
+        descs = source.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        properties = {}
+        required = []
+
+        if source.respond_to?(:literal_properties)
+          source.literal_properties.each do |prop|
+            prop_desc = descs[prop.name]
+            schema = TypeSerializer.to_json_schema(prop.type, desc: prop_desc)
+            properties[prop.name.to_s] = schema
+            required << prop.name.to_s if prop.required?
+          end
+        end
+
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+        result[:title] = source.name if source.name
+        desc = source.description
+        result[:description] = desc if desc
+        result[:type] = "object"
+        result[:properties] = properties unless properties.empty?
+        result[:required] = required unless required.empty?
+        result[:additionalProperties] = false
+        result
+      end
+
+      def _serialize_props(source)
+        return {} unless source.respond_to?(:literal_properties)
+
+        descs = source.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        source.literal_properties.each_with_object({}) do |prop, hash|
+          entry = { type: TypeSerializer.to_string(prop.type), required: prop.required? }
+          entry[:desc] = descs[prop.name] if descs[prop.name]
+          hash[prop.name] = entry
+        end
+      end
+
+      private_class_method :_serialize_props
+    end
+  end
+end

data/lib/dex/event/handler.rb

@@ -5,15 +5,48 @@ module Dex
     class Handler
       include Dex::Executable
 
+      extend Registry
+
+      def self.deregister(klass)
+        if klass.respond_to?(:handled_events)
+          klass.handled_events.each { |ec| Bus.unsubscribe(ec, klass) }
+        end
+        super
+      end
+
       attr_reader :event
 
       def self.on(*event_classes)
         event_classes.each do |ec|
           Event.validate_event_class!(ec)
           Bus.subscribe(ec, self)
+          (@_handled_events ||= []) << ec
         end
       end
 
+      def self.handled_events
+        defined?(@_handled_events) ? @_handled_events.dup.freeze : [].freeze
+      end
+
+      def self.to_h
+        h = {}
+        h[:name] = name if name
+        event_names = handled_events.filter_map(&:name)
+        h[:events] = event_names unless event_names.empty?
+        retry_config = _event_handler_retry_config
+        h[:retries] = retry_config[:count] if retry_config
+        tx_s = settings_for(:transaction)
+        h[:transaction] = tx_s.fetch(:enabled, false)
+        h[:pipeline] = pipeline.steps.map(&:name)
+        h
+      end
+
+      def self.export(format: :hash)
+        raise ArgumentError, "unknown format: #{format.inspect}. Known: :hash" unless format == :hash
+
+        registry.sort_by(&:name).map(&:to_h)
+      end
+
       def self.retries(count, **opts)
         raise ArgumentError, "retries count must be a positive Integer" unless count.is_a?(Integer) && count > 0
 

data/lib/dex/event/test_helpers.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    module EventTestWrapper
+      CAPTURING_KEY = :_dex_event_capturing
+      PUBLISHED_KEY = :_dex_event_published
+
+      @_installed = false
+
+      class << self
+        include ExecutionState
+
+        def install!
+          return if @_installed
+
+          Dex::Event::Bus.singleton_class.prepend(BusInterceptor)
+          @_installed = true
+        end
+
+        def installed?
+          @_installed
+        end
+
+        def capturing?
+          (_execution_state[CAPTURING_KEY] || 0) > 0
+        end
+
+        def begin_capture!
+          _execution_state[CAPTURING_KEY] = (_execution_state[CAPTURING_KEY] || 0) + 1
+        end
+
+        def end_capture!
+          depth = (_execution_state[CAPTURING_KEY] || 0) - 1
+          _execution_state[CAPTURING_KEY] = [depth, 0].max
+        end
+
+        def published_events
+          _execution_state[PUBLISHED_KEY] ||= []
+        end
+
+        def clear_published!
+          _execution_state[PUBLISHED_KEY] = []
+        end
+      end
+
+      module BusInterceptor
+        def publish(event, sync:)
+          if Dex::Event::EventTestWrapper.capturing?
+            return if Dex::Event::Suppression.suppressed?(event.class)
+
+            Dex::Event::EventTestWrapper.published_events << event
+          else
+            super(event, sync: true)
+          end
+        end
+      end
+    end
+
+    module TestHelpers
+      def self.included(base)
+        EventTestWrapper.install!
+      end
+
+      def setup
+        super
+        EventTestWrapper.clear_published!
+        Dex::Event::Trace.clear!
+        Dex::Event::Suppression.clear!
+      end
+
+      def capture_events
+        EventTestWrapper.begin_capture!
+        yield
+      ensure
+        EventTestWrapper.end_capture!
+      end
+
+      private
+
+      def _dex_published_events
+        EventTestWrapper.published_events
+      end
+    end
+  end
+end
+
+require_relative "test_helpers/assertions"

data/lib/dex/event.rb

@@ -17,6 +17,32 @@ module Dex
     include TypeCoercion
     include ContextSetup
 
+    extend Registry
+
+    class << self
+      def to_h
+        Export.build_hash(self)
+      end
+
+      def to_json_schema
+        Export.build_json_schema(self)
+      end
+
+      def export(format: :hash)
+        unless %i[hash json_schema].include?(format)
+          raise ArgumentError, "unknown format: #{format.inspect}. Known: :hash, :json_schema"
+        end
+
+        sorted = registry.sort_by(&:name)
+        sorted.map do |klass|
+          case format
+          when :hash then klass.to_h
+          when :json_schema then klass.to_json_schema
+          end
+        end
+      end
+    end
+
     def self._warn(message)
       Dex.warn("Event: #{message}")
     end
@@ -84,3 +110,4 @@ end
 require_relative "event/bus"
 require_relative "event/handler"
 require_relative "event/processor"
+require_relative "event/export"

data/lib/dex/event_test_helpers.rb

@@ -1,88 +1,3 @@
 # frozen_string_literal: true
 
-module Dex
-  class Event
-    module EventTestWrapper
-      CAPTURING_KEY = :_dex_event_capturing
-      PUBLISHED_KEY = :_dex_event_published
-
-      @_installed = false
-
-      class << self
-        include ExecutionState
-
-        def install!
-          return if @_installed
-
-          Dex::Event::Bus.singleton_class.prepend(BusInterceptor)
-          @_installed = true
-        end
-
-        def installed?
-          @_installed
-        end
-
-        def capturing?
-          (_execution_state[CAPTURING_KEY] || 0) > 0
-        end
-
-        def begin_capture!
-          _execution_state[CAPTURING_KEY] = (_execution_state[CAPTURING_KEY] || 0) + 1
-        end
-
-        def end_capture!
-          depth = (_execution_state[CAPTURING_KEY] || 0) - 1
-          _execution_state[CAPTURING_KEY] = [depth, 0].max
-        end
-
-        def published_events
-          _execution_state[PUBLISHED_KEY] ||= []
-        end
-
-        def clear_published!
-          _execution_state[PUBLISHED_KEY] = []
-        end
-      end
-
-      module BusInterceptor
-        def publish(event, sync:)
-          if Dex::Event::EventTestWrapper.capturing?
-            return if Dex::Event::Suppression.suppressed?(event.class)
-
-            Dex::Event::EventTestWrapper.published_events << event
-          else
-            super(event, sync: true)
-          end
-        end
-      end
-    end
-
-    module TestHelpers
-      def self.included(base)
-        EventTestWrapper.install!
-      end
-
-      def setup
-        super
-        EventTestWrapper.clear_published!
-        Dex::Event::Trace.clear!
-        Dex::Event::Suppression.clear!
-      end
-
-      def capture_events
-        EventTestWrapper.begin_capture!
-        yield
-      ensure
-        EventTestWrapper.end_capture!
-      end
-
-      private
-
-      def _dex_published_events
-        EventTestWrapper.published_events
-      end
-    end
-  end
-end
-
-require_relative "event_test_helpers/assertions"
+require_relative "event/test_helpers"

data/lib/dex/form/uniqueness_validator.rb

@@ -50,8 +50,12 @@ module Dex
       end
 
       def _build_query(model_class, column, value)
-        if options[:case_sensitive] == false && value.is_a?(String) && model_class.respond_to?(:arel_table)
+        return model_class.where(column => value) unless options[:case_sensitive] == false && value.is_a?(String)
+
+        if model_class.respond_to?(:arel_table)
           model_class.where(model_class.arel_table[column].lower.eq(value.downcase))
+        elsif _mongoid_model_class?(model_class)
+          model_class.where(column => /\A#{Regexp.escape(value)}\z/i)
         else
           model_class.where(column => value)
         end
@@ -78,9 +82,21 @@ module Dex
       def _exclude_current_record(query, form)
         return query unless form.record&.persisted?
 
+        if _mongoid_record?(form.record)
+          return query.where(:_id.ne => form.record.id)
+        end
+
         pk = form.record.class.primary_key
         query.where.not(pk => form.record.public_send(pk))
       end
+
+      def _mongoid_model_class?(model_class)
+        defined?(Mongoid::Document) && model_class.include?(Mongoid::Document)
+      end
+
+      def _mongoid_record?(record)
+        _mongoid_model_class?(record.class)
+      end
     end
   end
 end

data/lib/dex/operation/async_proxy.rb

@@ -27,6 +27,7 @@ module Dex
       end
 
       def enqueue_record_job
+        @operation.send(:_record_validate_backend!, async: true)
         record = Dex.record_backend.create_record(
           name: operation_class_name,
           params: serialized_params,