dexkit 0.10.0 → 0.11.0

data/guides/llm/OPERATION.md

@@ -111,7 +111,7 @@ Optional declarations documenting intent and catching mistakes at runtime.
 success _Ref(User)   # perform must return a User (or nil)
 ```
 
-**`error(*codes)`** — restricts which codes `error!`/`assert!` accept (raises `ArgumentError` on undeclared):
+**`error(*codes)`** — restricts which codes `error!` accepts (raises `ArgumentError` on undeclared):
 
 ```ruby
 error :email_taken, :invalid_email
@@ -297,13 +297,6 @@ success!(user)                      # return value early
 success!(name: "John", age: 30)    # kwargs become Hash
 ```
 
-**`assert!(code, &block)` / `assert!(value, code)`** — returns value if truthy, otherwise `error!(code)`:
-
-```ruby
-user = assert!(:not_found) { User.find_by(id: id) }
-assert!(user.active?, :inactive)
-```
-
 **Dex::Error** has `code` (Symbol), `message` (String, defaults to code.to_s), `details` (any). Pattern matching:
 
 ```ruby
@@ -317,7 +310,7 @@ rescue Dex::Error => e
 end
 ```
 
-**Key differences:** `error!`/`assert!` roll back transaction, skip `after` callbacks, but are still recorded (status `error`). `success!` commits, runs `after` callbacks, records normally (status `completed`).
+**Key differences:** `error!` rolls back transaction, skips `after` callbacks, but is still recorded (status `error`). `success!` commits, runs `after` callbacks, records normally (status `completed`).
 
 ---
 
@@ -351,6 +344,10 @@ end
 
 `Ok`/`Err` are available inside operations without prefix. In other contexts (controllers, POROs), use `Dex::Ok`/`Dex::Err` or `include Dex::Match`.
 
+**Deconstruct forms:**
+- Hash: `in Dex::Ok(key:)` — destructures value's keys. `in Dex::Err(code:, message:)` — named error fields.
+- Array: `in Dex::Ok[value]` — binds entire value. `in Dex::Err[error]` — binds the `Dex::Error` instance.
+
 ---
 
 ## Rescue Mapping
@@ -464,16 +461,82 @@ On timeout: raises `Dex::Error(code: :lock_timeout)`. Works with `.safe`.
 Enqueue as background jobs (requires ActiveJob):
 
 ```ruby
-CreateUser.new(email: "a@b.com", name: "Alice").async.call
-CreateUser.new(email: "a@b.com", name: "Alice").async(queue: "urgent").call
-CreateUser.new(email: "a@b.com", name: "Alice").async(in: 5.minutes).call
-CreateUser.new(email: "a@b.com", name: "Alice").async(at: 1.hour.from_now).call
+ticket = CreateUser.new(email: "a@b.com", name: "Alice").async.call
+ticket = CreateUser.new(email: "a@b.com", name: "Alice").async(queue: "urgent").call
+ticket = CreateUser.new(email: "a@b.com", name: "Alice").async(in: 5.minutes).call
+ticket = CreateUser.new(email: "a@b.com", name: "Alice").async(at: 1.hour.from_now).call
 ```
 
 Class-level defaults: `async queue: "mailers"`. Runtime options override.
 
 Props serialize/deserialize automatically (Date, Time, BigDecimal, Symbol, `_Ref` — all handled). Non-serializable props raise `ArgumentError` at enqueue time.
 
+### Ticket
+
+`async.call` returns a `Dex::Operation::Ticket` with `record` (operation record if recording enabled) and `job` (the enqueued job).
+
+```ruby
+ticket.id              # record ID
+ticket.operation_name  # operation class name
+ticket.status          # "pending"/"running"/"completed"/"error"/"failed"
+ticket.recorded?       # true if record strategy was used
+ticket.pending?        # status predicates
+ticket.terminal?       # completed? || error? || failed?
+ticket.reload          # refresh from DB, returns self
+ticket.to_param        # id.to_s (Rails path helpers)
+ticket.as_json         # { "id": ..., "name": ..., "status": ..., "result"?: ..., "error"?: ... }
+```
+
+`Ticket.from_record(record)` constructs from any operation record (for polling endpoints/dashboards).
+
+Record-dependent methods raise `ArgumentError` when `record` is nil (direct strategy without recording).
+
+### Outcome Reconstruction
+
+`ticket.outcome` reconstructs `Ok`/`Err` from the record — same types as `.safe.call`:
+
+- `completed` → `Ok(result)` with deep-symbolized keys
+- `error` → `Err(Dex::Error)` with symbolized code/details
+- `failed`/`pending`/`running` → `nil`
+
+Never raises, never reloads. Call `reload` first for fresh data.
+
+### wait / wait!
+
+Speculative sync — poll until terminal or timeout:
+
+```ruby
+# Safe mode (Ok/Err/nil)
+case ticket.wait(3.seconds)
+in Dex::Ok(url:)
+  redirect_to url
+in Dex::Err(code:, message:)
+  flash[:error] = message
+  redirect_to fallback_path
+else
+  redirect_to pending_path(ticket)
+end
+
+# Strict mode (value or exception)
+result = ticket.wait!(3.seconds)
+redirect_to result[:url]
+```
+
+| | Success | Business Error | Infra Crash | Timeout |
+|---|---|---|---|---|
+| `call` | value | `Dex::Error` | exception | n/a |
+| `safe.call` | `Ok` | `Err` | exception | n/a |
+| `wait!(t)` | value | `Dex::Error` | `OperationFailed` | `Dex::Timeout` |
+| `wait(t)` | `Ok` | `Err` | `OperationFailed` | `nil` |
+
+Options: `wait(timeout, interval: 0.2)`. Interval accepts a number or callable (`->(n) { ... }`).
+
+`Dex::OperationFailed` (inherits `StandardError`): `operation_name`, `exception_class`, `exception_message`.
+`Dex::Timeout` (inherits `StandardError`): `timeout`, `ticket_id`, `operation_name`.
+Neither inherits `Dex::Error` — `rescue Dex::Error` never catches them.
+
+`safe` and `async` are non-composable — `op.safe.async` and `op.async.safe` raise `NoMethodError` with prescriptive messages.
+
 ---
 
 ## Recording
@@ -544,10 +607,17 @@ end
 Dex::Trace.trace_id   # => "tr_..."
 Dex::Trace.current    # => [{ type: :actor, ... }, { type: :operation, ... }]
 Dex::Trace.to_s       # => "user:42 > Order::Place(op_2nFg7K)"
+Dex.actor             # => { type: "user", id: "123" } or nil
 ```
 
+`Dex.actor` returns the actor hash (reconstituted to the shape you passed in), or `nil`. Use it in `perform` when you need to write actor info into domain models.
+
+`Dex.system(name = nil)` is a convenience for background jobs: `Dex::Trace.start(actor: Dex.system("payroll")) { ... }`.
+
 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.
 
+IDs are generated by `Dex::Id` – a general-purpose Stripe-style ID generator. Use it for your own models: `Dex::Id.generate("ord_")`. Parse with `Dex::Id.parse(id)` to extract prefix, timestamp, and random components.
+
 ---
 
 ## Idempotency (once)
@@ -673,19 +743,6 @@ refute_err result
 refute_err result, :not_found           # Ok OR different code
 ```
 
-### One-Liner Assertions
-
-Call + assert in one step:
-
-```ruby
-assert_operation(email: "a@b.com", name: "Alice")                # Ok
-assert_operation(CreateUser, email: "a@b.com", name: "Alice")    # explicit class
-assert_operation(email: "a@b.com", name: "Alice", returns: user) # check value
-
-assert_operation_error(:invalid_email, email: "bad", name: "A")
-assert_operation_error(CreateUser, :email_taken, email: "taken@b.com", name: "A")
-```
-
 ### Contract Assertions
 
 ```ruby
@@ -712,7 +769,7 @@ refute_callable(:unauthorized, post: post, user: user)           # specific guar
 refute_callable(PublishPost, :unauthorized, post: post, user: user)
 ```
 
-Guard failures on the normal `call` path produce `Dex::Error`, so `assert_operation_error` and `assert_err` also work.
+Guard failures on the normal `call` path produce `Dex::Error`, so `assert_err` also works.
 
 ### Param Validation
 
@@ -738,21 +795,6 @@ assert_rolls_back(User) { CreateUser.call(email: "bad", name: "A") }
 assert_commits(User) { CreateUser.call(email: "ok@b.com", name: "A") }
 ```
 
-### Batch Assertions
-
-```ruby
-assert_all_succeed(params_list: [
-  { email: "a@b.com", name: "A" },
-  { email: "b@b.com", name: "B" }
-])
-
-assert_all_fail(code: :invalid_email, params_list: [
-  { email: "", name: "A" },
-  { email: "no-at", name: "B" }
-])
-# Also supports message: and details: options
-```
-
 ### Stubbing
 
 Replace an operation within a block. Bypasses all wrappers, not recorded in TestLog:
@@ -822,19 +864,9 @@ class CreateUserTest < Minitest::Test
     assert_ok(result) { |user| assert_equal "Alice", user.name }
   end
 
-  def test_one_liner
-    assert_operation(email: "a@b.com", name: "Alice")
-  end
-
   def test_rejects_bad_email
-    assert_operation_error(:invalid_email, email: "bad", name: "A")
-  end
-
-  def test_batch_rejects
-    assert_all_fail(code: :invalid_email, params_list: [
-      { email: "", name: "A" },
-      { email: "no-at", name: "B" }
-    ])
+    result = call_operation(email: "bad", name: "A")
+    assert_err result, :invalid_email
   end
 
   def test_stubs_dependency
@@ -911,6 +943,8 @@ end
 
 Requires `gem 'ruby_llm'` in your Gemfile. Lazy-loaded — ruby-llm is only required when you call `Dex::Tool`.
 
+See `TOOL.md` for the full Tool reference including query tools.
+
 ---
 
 **End of reference.**

data/guides/llm/QUERY.md

@@ -396,3 +396,9 @@ class UserSearchTest < Minitest::Test
   end
 end
 ```
+
+---
+
+## LLM Tools
+
+To expose a query as an LLM-callable tool, see `TOOL.md`.

data/guides/llm/TOOL.md

@@ -0,0 +1,308 @@
+# Dex::Tool — LLM Reference
+
+Install with `rake dex:guides` or copy manually to `AGENTS.md`.
+
+---
+
+## Overview
+
+`Dex::Tool` bridges Dex primitives to LLM tool calling via ruby-llm. It accepts Operation or Query classes and returns `RubyLLM::Tool` instances ready for `chat.with_tools(...)`.
+
+Requires `gem "ruby_llm"` in your Gemfile. Lazy-loaded — ruby-llm is only required when you call `Dex::Tool`.
+
+---
+
+## Operation Tools
+
+### Creating
+
+```ruby
+tool = Dex::Tool.from(Orders::Place)       # single operation
+tools = Dex::Tool.all                       # all registered operations
+tools = Dex::Tool.from_namespace("Orders")  # operations under Orders::
+```
+
+`from` accepts no options for Operation classes. `all` and `from_namespace` return sorted arrays.
+
+### Tool Schema
+
+The tool name is derived from the class name: `Orders::Place` becomes `dex_orders_place`.
+
+The description includes:
+- The operation's `description` (or class name if none)
+- Guard preconditions (if any)
+- Declared error codes (if any)
+
+The params schema is the operation's `contract.to_json_schema`.
+
+### Execution Flow
+
+1. Params are symbolized
+2. Operation is instantiated with params
+3. Called via `.safe.call` (returns `Ok` or `Err`, never raises)
+4. `Ok` — returns `value.as_json` (or raw value if no `as_json`)
+5. `Err` — returns `{ error:, message:, details: }`
+
+### Example
+
+```ruby
+class Orders::Place < Dex::Operation
+  description "Place a new order for a customer"
+
+  prop :customer_id, _Ref(Customer)
+  prop :product_id, _Ref(Product)
+  prop? :quantity, Integer, default: 1
+
+  error :out_of_stock, :invalid_quantity
+
+  guard :sufficient_stock, "Product must be in stock" do
+    Product.find(product_id).stock >= quantity
+  end
+
+  def perform
+    error!(:invalid_quantity) if quantity <= 0
+    Order.create!(customer_id: customer_id, product_id: product_id, quantity: quantity)
+  end
+end
+
+tool = Dex::Tool.from(Orders::Place)
+chat = RubyLLM.chat.with_tools(tool)
+chat.ask("Place an order for customer #12, product #42, quantity 3")
+```
+
+### Error Shape
+
+When an operation returns `Err`, the tool returns:
+
+```ruby
+{ error: :out_of_stock, message: "out_of_stock", details: nil }
+```
+
+---
+
+## Explain Tool
+
+A meta-tool that checks whether an operation can execute with given params, without running it:
+
+```ruby
+tool = Dex::Tool.explain_tool
+chat = RubyLLM.chat.with_tools(tool)
+chat.ask("Can I place an order for product #42?")
+```
+
+The LLM calls it with `{ operation: "Orders::Place", params: { product_id: 42 } }`. Returns:
+
+```ruby
+{ callable: true, guards: [{ name: :sufficient_stock, passed: true }], once: nil, lock: nil }
+```
+
+If the operation is not in the registry: `{ error: "unknown_operation", message: "..." }`.
+
+---
+
+## Query Tools
+
+### Creating
+
+```ruby
+tool = Dex::Tool.from(Product::Query,
+  scope: -> { Current.user.products },
+  serialize: ->(record) { record.as_json(only: %i[id name price stock]) })
+```
+
+### Required Options
+
+Both `scope:` and `serialize:` are mandatory for Query tools.
+
+**`scope:`** — a lambda returning the base relation. Called at execution time:
+
+```ruby
+Dex::Tool.from(Order::Query,
+  scope: -> { Current.user.orders },
+  serialize: ->(r) { r.as_json })
+
+Dex::Tool.from(Product::Query,
+  scope: -> { Product.where(active: true) },
+  serialize: ->(r) { r.as_json })
+```
+
+**`serialize:`** — a lambda converting each record to a hash:
+
+```ruby
+Dex::Tool.from(Product::Query,
+  scope: -> { Product.all },
+  serialize: ->(r) { r.as_json(only: %i[id name price]) })
+
+Dex::Tool.from(Order::Query,
+  scope: -> { Current.user.orders },
+  serialize: ->(r) { { id: r.id, total: r.total, status: r.status } })
+```
+
+### Optional Restrictions
+
+**`limit:`** — max results per page (default: 50). The LLM can request fewer but never more:
+
+```ruby
+Dex::Tool.from(Product::Query, scope: -> { Product.all }, serialize: ->(r) { r.as_json }, limit: 25)
+```
+
+**`only_filters:`** — allowlist of filters exposed to the LLM:
+
+```ruby
+Dex::Tool.from(Product::Query,
+  scope: -> { Product.all },
+  serialize: ->(r) { r.as_json },
+  only_filters: %i[name category])
+```
+
+**`except_filters:`** — denylist of filters hidden from the LLM (mutually exclusive with `only_filters:`):
+
+```ruby
+Dex::Tool.from(Product::Query,
+  scope: -> { Product.all },
+  serialize: ->(r) { r.as_json },
+  except_filters: %i[internal_code])
+```
+
+**`only_sorts:`** — allowlist of sort columns. Must include the query's default sort if one exists:
+
+```ruby
+Dex::Tool.from(Product::Query,
+  scope: -> { Product.all },
+  serialize: ->(r) { r.as_json },
+  only_sorts: %i[name price created_at])
+```
+
+### Auto-Exclusions
+
+These props are automatically excluded from the tool schema (the LLM never sees them):
+
+- Props mapped via `context` (filled from ambient context)
+- `_Ref` typed props (model references)
+- Props for hidden filters (via `only_filters:` / `except_filters:`)
+
+If an auto-excluded prop is required with no default and no context mapping, `from` raises `ArgumentError` at build time.
+
+### Tool Schema
+
+The tool name is `dex_query_{class_name}` (lowercased, `::` replaced with `_`).
+
+The description includes:
+- The query's `description` (or class name)
+- Available filters with type hints and enum values
+- Available sorts with default indicator
+- Max results per page
+
+The params schema includes visible filter props plus:
+
+- `sort` — enum of allowed sort values (prefix with `-` for descending; custom sorts have no `-` variant)
+- `limit` — integer, max results
+- `offset` — integer, skip N results (for pagination)
+
+### Execution Flow
+
+1. Extract `limit`, `offset`, `sort` from params
+2. Clamp `limit` to max (default 50); zero or negative resets to max
+3. Floor `offset` at 0
+4. Validate sort value against allowed sorts; drop invalid (falls back to query default)
+5. Custom sorts reject `-` prefix (direction is baked into the block)
+6. Strip context-mapped and excluded filter params
+7. Inject scope from `scope:` lambda
+8. Build query via `from_params` (coercion, blank stripping, validation)
+9. Resolve, count total, apply offset/limit
+10. Serialize each record via `serialize:` lambda
+
+### Return Shape
+
+```json
+{
+  "records": [{ "id": 1, "name": "Widget", "price": 9.99 }],
+  "total": 142,
+  "limit": 50,
+  "offset": 0
+}
+```
+
+`total` is `nil` if the count query fails (e.g., complex GROUP BY).
+
+### Error Handling
+
+Invalid params or type errors:
+
+```ruby
+{ error: "invalid_params", message: "..." }
+```
+
+Any other error:
+
+```ruby
+{ error: "query_failed", message: "..." }
+```
+
+---
+
+## Context
+
+`Dex.with_context` provides ambient values to both Operation and Query tools. Props with `context` mappings are auto-filled and hidden from the LLM:
+
+```ruby
+class Orders::Place < Dex::Operation
+  prop :customer_id, _Ref(Customer)
+  context customer_id: :current_customer_id
+  # ...
+end
+
+class Order::Query < Dex::Query
+  scope { Order.all }
+  prop? :customer_id, _Ref(Customer)
+  context customer_id: :current_customer_id
+  filter :customer_id
+  # ...
+end
+
+Dex.with_context(current_customer_id: current_user.customer_id) do
+  chat.ask("Show me my recent orders")
+end
+```
+
+The LLM never sees `customer_id` in either tool's schema — it is injected from context.
+
+---
+
+## Security Model
+
+Five layers protect against misuse:
+
+1. **Scope lambda** — called at execution time, applies authorization (`Current.user.orders`, `policy_scope(...)`)
+2. **Context injection** — security-sensitive props (tenant, user) are filled from ambient context, invisible to the LLM
+3. **Filter restrictions** — `only_filters:` / `except_filters:` control what the LLM can search on
+4. **Sort restrictions** — `only_sorts:` limits available sort columns
+5. **Limit cap** — `limit:` sets a hard ceiling on results per page; the LLM cannot exceed it
+
+---
+
+## Combining Operation + Query Tools
+
+```ruby
+order_tools = Dex::Tool.from_namespace("Orders")
+
+search_tool = Dex::Tool.from(Product::Query,
+  scope: -> { Current.user.products },
+  serialize: ->(r) { r.as_json(only: %i[id name price stock]) },
+  limit: 20,
+  only_filters: %i[name category],
+  only_sorts: %i[name price])
+
+explain = Dex::Tool.explain_tool
+
+chat = RubyLLM.chat
+chat.with_tools(*order_tools, search_tool, explain)
+
+Dex.with_context(current_customer_id: current_user.customer_id) do
+  chat.ask("Find products under $50, then place an order for the cheapest one")
+end
+```
+
+---
+
+**End of reference.**

data/lib/dex/event/bus.rb

@@ -89,15 +89,13 @@ module Dex
 
         def enqueue(handler_class, event, trace_data)
           ensure_active_job_loaded!
-          ctx = event.context
 
           Dex::Event::Processor.perform_later(
             handler_class: handler_class.name,
             event_class: event.class.name,
             payload: event._props_as_json,
             metadata: event.metadata.as_json,
-            trace: trace_data,
-            context: ctx
+            trace: trace_data
           )
         end
 

data/lib/dex/event/handler.rb

@@ -113,8 +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"]
+            event_ancestry: metadata_hash["event_ancestry"] || []
           )
           instance.instance_variable_set(:@metadata, metadata)
           instance.freeze

data/lib/dex/event/metadata.rb

@@ -3,15 +3,14 @@
 module Dex
   class Event
     class Metadata
-      attr_reader :id, :timestamp, :trace_id, :caused_by_id, :event_ancestry, :context
+      attr_reader :id, :timestamp, :trace_id, :caused_by_id, :event_ancestry
 
-      def initialize(id:, timestamp:, trace_id:, caused_by_id:, event_ancestry:, context:)
+      def initialize(id:, timestamp:, trace_id:, caused_by_id:, event_ancestry:)
         @id = id
         @timestamp = timestamp
         @trace_id = trace_id
         @caused_by_id = caused_by_id
         @event_ancestry = event_ancestry
-        @context = context
         freeze
       end
 
@@ -26,22 +25,12 @@ module Dex
           []
         end
 
-        ctx = if Dex.configuration.event_context
-          begin
-            Dex.configuration.event_context.call
-          rescue => e
-            Event._warn("event_context failed: #{e.message}")
-            nil
-          end
-        end
-
         new(
           id: id,
           timestamp: Time.now.utc,
           trace_id: trace_id,
           caused_by_id: caused,
-          event_ancestry: ancestry,
-          context: ctx
+          event_ancestry: ancestry
         )
       end
 
@@ -53,7 +42,6 @@ module Dex
           "event_ancestry" => @event_ancestry
         }
         h["caused_by_id"] = @caused_by_id if @caused_by_id
-        h["context"] = @context if @context
         h
       end
     end

data/lib/dex/event/processor.rb

@@ -7,9 +7,7 @@ module Dex
       return super unless name == :Processor && defined?(ActiveJob::Base)
 
       const_set(:Processor, Class.new(ActiveJob::Base) do
-        def perform(handler_class:, event_class:, payload:, metadata:, trace: nil, context: nil, attempt_number: 1)
-          restore_context(context)
-
+        def perform(handler_class:, event_class:, payload:, metadata:, trace: nil, attempt_number: 1)
           handler = Object.const_get(handler_class)
           retry_config = handler._event_handler_retry_config
 
@@ -25,7 +23,6 @@ module Dex
               payload: payload,
               metadata: metadata,
               trace: trace,
-              context: context,
               attempt_number: attempt_number + 1
             )
           else
@@ -35,17 +32,6 @@ module Dex
 
         private
 
-        def restore_context(context)
-          return unless context
-
-          restorer = Dex.configuration.restore_event_context
-          return unless restorer
-
-          restorer.call(context)
-        rescue => e
-          Dex::Event._warn("restore_event_context failed: #{e.message}")
-        end
-
         def compute_delay(config, attempt)
           wait = config[:wait]
           case wait

data/lib/dex/event.rb

@@ -3,7 +3,6 @@
 # Modules loaded before class body (no reference to Dex::Event needed)
 require_relative "event/execution_state"
 require_relative "event/metadata"
-require_relative "event/trace"
 require_relative "event/suppression"
 
 module Dex
@@ -68,7 +67,6 @@ module Dex
     def trace_id = metadata.trace_id
     def caused_by_id = metadata.caused_by_id
     def event_ancestry = metadata.event_ancestry
-    def context = metadata.context
 
     # Publishing
     def publish(sync: false)
@@ -77,7 +75,7 @@ module Dex
 
     def self.publish(sync: false, caused_by: nil, **kwargs)
       if caused_by
-        Trace.with_event(caused_by) do
+        Dex::Trace.with_event_context(caused_by) do
           new(**kwargs).publish(sync: sync)
         end
       else