dexkit 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34e5457c2e95efc96b2350babe7d7059854caa42ce6da92087e003f76acfb6d8
-  data.tar.gz: cf0466311827f2706fe883167b88d27a2571029c029777a1a5f37e0f44ae080a
+  metadata.gz: 1009624f8d508e4d6b61d76c8d54f32fc04a11f445163915c027ebc1bdd30b5e
+  data.tar.gz: 1b5a0755af0be468d67c3c5447f1322deff584364a493fb7665687d1417189b3
 SHA512:
-  metadata.gz: 3885a4464112b937aa88bd2661ad03aca35af5128ba9b292c7345fccd69bbd8c53a363d5f1805c0c2173c097ff06f8f98ec7fc657115fd530b84a910af9b5759
-  data.tar.gz: 25ce509ae466f259b102b4eedb8d828eb27435d6223bd052c87682b60b43584a6ccaf223ed0bec3f2141988fadebaac4638a204c4025554870e70c389ac9d4e2
+  metadata.gz: '08552d04b1e9ddf5991f1454f9491fcabe80047d9606f0432be411f09d7b632a797435fabf55d8e9b190ddbc1a70daa5e73c19aa08c2bde88540559c3d35275e'
+  data.tar.gz: 33d58dd5b421a1e7f41d3ab133c1800787d2d1f6c22327e7db7faf9053222d62d087c4a563105fb39075fbefc1a73f04984b45511595a0e3976eda9833de0cdf

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 ## [Unreleased]
 
+## [0.8.0] - 2026-03-09
+
+### Added
+
+- **Registry** — `Dex::Operation.registry`, `Dex::Event.registry`, and `Dex::Event::Handler.registry` return frozen Sets of all named subclasses. Populated automatically via `inherited`; anonymous and stale (unreachable after code reload) classes are excluded. `deregister(klass)` removes entries. `clear!` empties the registry. Zeitwerk-compatible — registries reflect loaded classes; eager-load to get the full list
+- **Description & prop descriptions** — `description "text"` class-level DSL for operations and events. `desc:` keyword on `prop`/`prop?` for per-property descriptions (validated as String). Both appear in `contract.to_h`, `to_json_schema`, and `explain` output. Optional — no error or warning when omitted
+- **`contract.to_h` export** — serializes the full operation contract to a plain Ruby Hash: `name`, `description`, `params` (with typed strings and `desc`), `success`, `errors`, `guards`, `context`, `pipeline`, `settings`. Types are human-readable strings (`"String"`, `"Integer(1..)"`, `"Ref(Product)"`, `"Nilable(String)"`). Omits nil/empty fields
+- **`contract.to_json_schema` export** — generates JSON Schema (Draft 2020-12) from the operation contract. Default section is `:params` (input schema for LLM tools, form generation, API validation). Also supports `:success`, `:errors`, and `:full` sections
+- **Event export** — `Event.to_h` and `Event.to_json_schema` class methods for serializing event definitions. Same type serialization as operations
+- **Handler export** — `Handler.to_h` returns name, events (array), retries, transaction, and pipeline metadata. `handled_events` returns all subscribed event classes
+- **Bulk export** — `Dex::Operation.export(format: :hash|:json_schema)`, `Dex::Event.export(format: :hash|:json_schema)`, `Dex::Event::Handler.export(format: :hash)`. Returns arrays sorted by name — directly serializable with `JSON.generate`
+- **`Dex::Tool` — ruby-llm integration** — bridges dexkit operations to [ruby-llm](https://rubyllm.com/) tools. `Dex::Tool.from(Op)` generates a `RubyLLM::Tool` from an operation's contract. `Dex::Tool.all` converts all registered operations. `Dex::Tool.from_namespace("Order")` filters by namespace. `Dex::Tool.explain_tool` provides a built-in preflight check tool. Lazy-loaded — ruby-llm is only required when you call `Dex::Tool`
+- **`Dex::TypeSerializer`** — converts Literal types to human-readable strings and JSON Schema. Handles `String`, `Integer`, `Float`, `Boolean`, `Symbol`, `Hash`, `Date`, `Time`, `DateTime`, `BigDecimal`, `_Nilable`, `_Array`, `_Union`, `_Ref`, and range-constrained types (`_Integer(1..)`)
+- **Rake task `dex:export`** — `rake dex:export` with `FORMAT=hash|json_schema`, `SECTION=operations|events|handlers`, `FILE=path` environment variables. Auto-loaded via Railtie in Rails apps
+- **Rake task `dex:guides`** — `rake dex:guides` installs LLM-optimized guides as `AGENTS.md` files in app directories (`app/operations/`, `app/events/`, `app/event_handlers/`, `app/forms/`, `app/queries/`). Only writes to directories that exist. Stamps each file with the installed dexkit version. The event guide is installed to both `app/events/` and `app/event_handlers/` when either exists. Existing hand-written `AGENTS.md` files are detected and skipped (`FORCE=1` to overwrite). Override paths with `OPERATIONS_PATH`, `EVENTS_PATH`, `EVENT_HANDLERS_PATH`, `FORMS_PATH`, `QUERIES_PATH` environment variables
+- **`explain` includes `description`** — `explain` output now contains `:description` when set on the operation
+- **`explain` class method for operations** — `MyOp.explain(**kwargs)` returns a frozen Hash with the full preflight state: resolved props, context source tracking (`:explicit`/`:ambient`/`:default`), per-guard pass/fail results with messages, once key and status (`:fresh`/`:exists`/`:expired`/`:pending`/`:invalid`/`:misconfigured`/`:unavailable`), advisory lock key, record/transaction/rescue/callback settings, pipeline steps, and overall `callable` verdict (accounts for both guard failures and once blocking statuses). No side effects — `perform` is never called. Gracefully handles invalid props — returns partial results with `error` key instead of raising, class-level information always available. Respects pipeline customization — removed steps report inactive. Custom middleware can contribute via `_name_explain` class methods
+
+### Breaking
+
+- **`contract.to_h` returns rich format** — `contract.to_h` now returns a comprehensive serialized Hash with string-typed params, description, context, pipeline, and settings instead of the raw `Data#to_h` shape. Before: `contract.to_h[:success]` returned `String` (the class). After: it returns `"String"` (a string). Code doing type comparisons like `contract.to_h[:success] == String` must update to use `contract.success` (which still returns raw types) or compare against `"String"`. The raw Ruby types remain accessible via `contract.params`, `contract.success`, `contract.errors`, `contract.guards`
+- **`_Ref` JSON Schema type changed from `"integer"` to `"string"`** — `_Ref(Model)` now serializes as `{ type: "string" }` in JSON Schema. IDs are treated as opaque strings to support Mongoid BSON::ObjectId, UUIDs, and other non-integer primary key formats. Code that relied on `type: "integer"` for Ref params must update
+
+### Fixed
+
+- **`Handler.deregister` now unsubscribes from Bus** — `Dex::Event::Handler.deregister(klass)` removes the handler from both the registry and the event Bus. Previously, deregistered handlers remained subscribed and would still fire on published events
+- **Registry prunes stale entries** — `registry` now removes unreachable class references from the backing Set during each call, preventing memory leaks from code reload cycles
+- **`description(false)` and `desc: false` now raise `ArgumentError`** — previously accepted as "missing" values due to falsey evaluation. Both DSL methods now validate with `!text.nil?` / `!desc.nil?` to enforce the String requirement, matching the library's fail-fast convention
+- **`prop_descriptions` no longer leaks parent descriptions for redeclared props** — when a child class redefines a prop without `desc:`, the parent's description is cleared instead of being inherited. Providing a new `desc:` on the child works as before
+- **Rake task validates handler format** — `rake dex:export SECTION=handlers FORMAT=json_schema` now raises a clear error instead of hitting `Handler.export`'s `ArgumentError`
+
 ## [0.7.0] - 2026-03-08
 
 ### Breaking

data/README.md

@@ -132,6 +132,30 @@ end
 Order::Place.call(product: product, customer: customer)
 ```
 
+**Explain** – full preflight check in one call. Context, guards, idempotency, locks, settings – everything the operation would do, without doing it:
+
+```ruby
+info = Order::Place.explain(product: product, customer: customer, quantity: 2)
+info[:callable]            # => true (all guards pass)
+info[:once][:status]       # => :fresh (would execute, not replay)
+info[:context][:source]    # => { customer: :ambient }
+```
+
+**Registry & Export** — list all operations, export contracts as JSON or JSON Schema, and bridge to LLM function-calling via [ruby-llm](https://rubyllm.com/):
+
+```ruby
+# List all operations
+Dex::Operation.registry  # => #<Set: {Order::Place, Order::Cancel, ...}>
+
+# Export contracts
+Dex::Operation.export(format: :json_schema)
+
+# LLM tools (requires ruby-llm gem)
+chat = RubyLLM.chat
+chat.with_tools(*Dex::Tool.all)
+chat.ask("Place an order for 2 units of product #42")
+```
+
 **Transactions** on by default, **advisory locking**, **recording** to database, **callbacks**, and a customizable **pipeline** – all composable, all optional.
 
 ### Testing
@@ -326,13 +350,18 @@ Full documentation at **[dex.razorjack.net](https://dex.razorjack.net)**.
 
 ## AI Coding Assistant Setup
 
-dexkit ships LLM-optimized guides. Copy them into your project so AI agents automatically know the API:
+dexkit ships LLM-optimized guides. Install them as `AGENTS.md` files in your app directories so AI coding agents automatically know the API:
+
+```bash
+rake dex:guides
+```
+
+This copies guides into directories that exist (`app/operations/`, `app/events/`, `app/event_handlers/`, `app/forms/`, `app/queries/`), stamped with the installed dexkit version. Re-run after upgrading dexkit to sync. Existing hand-written `AGENTS.md` files are never overwritten (use `FORCE=1` to override).
+
+Override paths for non-standard directory names:
 
 ```bash
-cp $(bundle show dexkit)/guides/llm/OPERATION.md app/operations/CLAUDE.md
-cp $(bundle show dexkit)/guides/llm/EVENT.md app/event_handlers/CLAUDE.md
-cp $(bundle show dexkit)/guides/llm/FORM.md app/forms/CLAUDE.md
-cp $(bundle show dexkit)/guides/llm/QUERY.md app/queries/CLAUDE.md
+rake dex:guides OPERATIONS_PATH=app/services
 ```
 
 ## License

data/guides/llm/EVENT.md

@@ -1,6 +1,6 @@
 # Dex::Event — LLM Reference
 
-Copy this to your app's event handlers directory (e.g., `app/event_handlers/AGENTS.md`) so coding agents know the full API when implementing and testing events.
+Install with `rake dex:guides` or copy manually to `app/events/AGENTS.md`.
 
 ---
 
@@ -383,4 +383,46 @@ end
 
 ---
 
+## Registry, Export & Description
+
+### Description
+
+Events can declare a human-readable description. Props can include `desc:`:
+
+```ruby
+class Order::Placed < Dex::Event
+  description "Emitted after an order is successfully placed"
+
+  prop :order_id, Integer, desc: "The placed order"
+  prop :total, BigDecimal, desc: "Order total"
+end
+```
+
+### Registry
+
+```ruby
+Dex::Event.registry            # => #<Set: {Order::Placed, Order::Cancelled, ...}>
+Dex::Event::Handler.registry   # => #<Set: {NotifyWarehouse, SendConfirmation, ...}>
+Dex::Event.deregister(klass)
+Dex::Event::Handler.deregister(klass)
+```
+
+### Export
+
+```ruby
+Order::Placed.to_h
+# => { name: "Order::Placed", description: "...", props: { order_id: { type: "Integer", ... } } }
+
+Order::Placed.to_json_schema   # JSON Schema (Draft 2020-12)
+
+NotifyWarehouse.to_h
+# => { name: "NotifyWarehouse", events: ["Order::Placed"], retries: 3, ... }
+
+Dex::Event.export                         # all events as hashes
+Dex::Event.export(format: :json_schema)   # all as JSON Schema
+Dex::Event::Handler.export                # all handlers as hashes
+```
+
+---
+
 **End of reference.**

data/guides/llm/FORM.md

@@ -1,6 +1,6 @@
 # Dex::Form — LLM Reference
 
-Copy this to your app's forms directory (e.g., `app/forms/AGENTS.md`) so coding agents know the full API when implementing and testing forms.
+Install with `rake dex:guides` or copy manually to `app/forms/AGENTS.md`.
 
 ---
 

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). Instances pass through without re-locking. In serialization (recording, async), stores model ID only. 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).
@@ -780,4 +825,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`.
 
 ---
 

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.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/operation/explain.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    module Explain
+      def explain(**kwargs)
+        error = nil
+        instance = begin
+          new(**kwargs)
+        rescue Literal::TypeError, ArgumentError => e
+          error = e
+          nil
+        end
+
+        info = {}
+        active = pipeline.steps.map(&:name).to_set
+
+        info[:operation] = name || "(anonymous)"
+        desc = description
+        info[:description] = desc if desc
+        info[:error] = "#{error.class}: #{error.message}" if error
+        info[:props] = _explain_props(instance)
+        info[:context] = _explain_context(instance, kwargs)
+        info[:guards] = active.include?(:guard) ? _explain_guards(instance) : { passed: true, results: [] }
+        info[:once] = active.include?(:once) ? _explain_once(instance) : { active: false }
+        info[:lock] = active.include?(:lock) ? _explain_lock(instance) : { active: false }
+        info[:record] = active.include?(:record) ? _explain_record : { enabled: false }
+        info[:transaction] = active.include?(:transaction) ? _explain_transaction : { enabled: false }
+        info[:rescue_from] = active.include?(:rescue) ? _explain_rescue : {}
+        info[:callbacks] = active.include?(:callback) ? _explain_callbacks : { before: 0, after: 0, around: 0 }
+
+        if instance
+          pipeline.steps.each do |step|
+            method_name = :"_#{step.name}_explain"
+            send(method_name, instance, info) if respond_to?(method_name, true)
+          end
+        end
+
+        info[:pipeline] = pipeline.steps.map(&:name)
+        info[:callable] = instance ? _explain_callable?(info) : false
+        info.freeze
+      end
+
+      private
+
+      def _explain_callable?(info)
+        return false unless info[:guards][:passed]
+
+        if info[:once][:active]
+          return false if ONCE_BLOCKING_STATUSES.include?(info[:once][:status])
+        end
+
+        true
+      end
+
+      ONCE_BLOCKING_STATUSES = %i[invalid pending misconfigured unavailable].freeze
+
+      def _explain_props(instance)
+        return {} unless respond_to?(:literal_properties)
+        return {} unless instance
+
+        literal_properties.each_with_object({}) do |prop, hash|
+          hash[prop.name] = instance.public_send(prop.name)
+        end
+      end
+
+      def _explain_context(instance, explicit_kwargs)
+        mappings = respond_to?(:context_mappings) ? context_mappings : {}
+        return { resolved: {}, mappings: {}, source: {} } if mappings.empty?
+
+        ambient = Dex.context
+        resolved = {}
+        source = {}
+
+        mappings.each do |prop_name, context_key|
+          resolved[prop_name] = instance.public_send(prop_name) if instance
+          source[prop_name] = if explicit_kwargs.key?(prop_name)
+            :explicit
+          elsif ambient.key?(context_key)
+            :ambient
+          elsif instance || _explain_prop_has_default?(prop_name)
+            :default
+          else
+            :missing
+          end
+        end
+
+        { resolved: resolved, mappings: mappings, source: source }
+      end
+
+      def _explain_guards(instance)
+        return { passed: false, results: [] } unless instance
+
+        all_results = instance.send(:_guard_evaluate_all)
+        results = all_results.map do |r|
+          entry = { name: r[:name], passed: r[:passed] }
+          entry[:message] = r[:message] if r[:message]
+          entry[:skipped] = true if r[:skipped]
+          entry
+        end
+        { passed: results.all? { |r| r[:passed] }, results: results }
+      end
+
+      def _explain_once(instance)
+        settings = settings_for(:once)
+        return { active: false } unless settings.fetch(:defined, false)
+
+        key = instance&.send(:_once_derive_key)
+        {
+          active: true,
+          key: key,
+          status: _explain_once_status(key),
+          expires_in: settings[:expires_in]
+        }
+      end
+
+      def _explain_once_status(key)
+        return :invalid if key.nil?
+        return :misconfigured if name.nil?
+        return :misconfigured unless pipeline.steps.any? { |s| s.name == :record }
+        return :unavailable unless Dex.record_backend
+        return :misconfigured unless Dex.record_backend.has_field?("once_key")
+
+        settings = settings_for(:once)
+        if settings[:expires_in] && !Dex.record_backend.has_field?("once_key_expires_at")
+          return :misconfigured
+        end
+
+        existing = Dex.record_backend.find_by_once_key(key)
+        return :exists if existing
+
+        if Dex.record_backend.has_field?("once_key_expires_at")
+          expired = Dex.record_backend.find_expired_once_key(key)
+          return :expired if expired
+        end
+
+        pending = Dex.record_backend.find_pending_once_key(key)
+        return :pending if pending
+
+        :fresh
+      end
+
+      def _explain_lock(instance)
+        settings = settings_for(:advisory_lock)
+        return { active: false } unless settings.fetch(:enabled, false)
+
+        key = if instance
+          instance.send(:_lock_key)
+        else
+          case settings[:key]
+          when String then settings[:key]
+          when nil then name
+          end
+        end
+
+        { active: true, key: key, timeout: settings[:timeout] }
+      end
+
+      def _explain_prop_has_default?(prop_name)
+        return false unless respond_to?(:literal_properties)
+
+        literal_properties.any? { |p| p.name == prop_name && p.default? }
+      end
+
+      def _explain_record
+        settings = settings_for(:record)
+        enabled = settings.fetch(:enabled, true) && !!Dex.record_backend && !!name
+        return { enabled: false } unless enabled
+
+        {
+          enabled: true,
+          params: settings.fetch(:params, true),
+          result: settings.fetch(:result, true)
+        }
+      end
+
+      def _explain_transaction
+        settings = settings_for(:transaction)
+        return { enabled: false } unless settings.fetch(:enabled, true)
+
+        adapter_name = settings.fetch(:adapter, Dex.transaction_adapter)
+        adapter = Operation::TransactionAdapter.for(adapter_name)
+        { enabled: !adapter.nil? }
+      end
+
+      def _explain_rescue
+        handlers = respond_to?(:_rescue_handlers) ? _rescue_handlers : []
+        handlers.each_with_object({}) do |h, hash|
+          hash[h[:exception_class].name] = h[:code]
+        end
+      end
+
+      def _explain_callbacks
+        return { before: 0, after: 0, around: 0 } unless respond_to?(:_callback_list)
+
+        {
+          before: _callback_list(:before).size,
+          after: _callback_list(:after).size,
+          around: _callback_list(:around).size
+        }
+      end
+    end
+  end
+end