dexkit 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41c8e4455fb4a4cca73b1d12da366b53bdbbada2cbae773917a12d344a150dd4
-  data.tar.gz: 86c4e76004df8b968c094b7b252a988eafe2f7aee035505ddb7bbeae1f25e04a
+  metadata.gz: 0201163b689acfc7c65709eb96174e81dacd9f090f573d4cc2ba2f15c6362c2b
+  data.tar.gz: cedf548f898ccc821262adec828613848572bfd02dbd0667001a1f9f1669c5bb
 SHA512:
-  metadata.gz: 89a9f6075f3955300dbe3944a9adc9b80ab56c3b4dc60d9458ea370f68c5c83ab5b3f2daad26c6f852d6f423a498ccf068914853e9866c05442765539ac6ac91
-  data.tar.gz: cd541ee35700cf9aa877b3630d66f0b9580263d0fddc7f381200afe32c638f832d941112387f646fa59500c26bb552461ad5bf0f0ec79dcf7bb97d76ebcbfb86
+  metadata.gz: 318363e15f2b2ebb3846125d5785562f114f3941e29a577e721b72ff6101c6d30171771c7998dac253e7e91f31a9727d5e318f62df172c78233a067a45d6413b
+  data.tar.gz: a982874d3377ebec37bfe9a9528b505150a31b83298594827cbb7d3d0e9d9679635a48b6068a02c4d0ed6e1ba53764471f1534d5f28209b8e2fadfc062a4f64d

data/CHANGELOG.md

@@ -1,12 +1,68 @@
 ## [Unreleased]
 
+### Breaking
+
+- **`Dex::Event::Trace` removed** – the shim module was a pure pass-through to `Dex::Trace`. All callers should use `Dex::Trace` directly: `Dex::Trace.with_event_context(event)`, `Dex::Trace.current_event_id`, `Dex::Trace.trace_id`, `Dex::Trace.dump`, `Dex::Trace.restore(data)`, `Dex::Trace.clear!`
+- **`event_context` / `restore_event_context` configuration removed** – the legacy dual context system for capturing arbitrary metadata at publish time and restoring ambient state in async handlers has been removed. Before: `config.event_context = -> { { user_id: Current.user&.id } }` captured an untyped hash into event metadata, and `config.restore_event_context` restored it before async handler execution. After: use `Dex.with_context` with typed event props via the `context` DSL instead — context values are captured as regular props at publish time, serialized automatically, and available on the event in handlers without ambient state restoration. `Metadata.context` field has been removed from event metadata and serialization
+- **`event.context` instance method removed** – the metadata delegate that returned the `event_context` config output is gone. Context data should be declared as typed props with the `context` DSL
+
+### Removed
+
+- **`assert!` removed from operations** — `assert!(:code) { value }` and `assert!(value, :code)` are no longer available. Use `error!(:code) unless value` instead – it's equally concise and doesn't require learning a separate method
+- **`assert_all_succeed` / `assert_all_fail` removed from test helpers** — use a simple loop with `assert_ok` / `assert_err` instead
+- **`dex/event_test_helpers` shim removed** — use `require "dex/event/test_helpers"` directly
+- **`assert_operation` / `assert_operation_error` removed from test helpers** — use `call_operation` + `assert_ok` / `assert_err` instead, which are more composable
+- **`assert_trace_includes` / `assert_trace_actor` / `assert_trace_depth` removed from test helpers** — use `Dex::Trace.current`, `Dex::Trace.actor` directly with standard Minitest assertions
+
+### Added
+
+- **`Dex::Id.parse`** – parse a Stripe-style ID back into prefix, timestamp, and random components. Returns `Dex::Id::Parsed` (a `Data.define` value object)
+- **`Dex::Id.generate` now validates prefix format** – prefix must match `/\A[a-z][a-z0-9_]*_\z/` (lowercase alphanumeric with internal underscores, ending in underscore). Internal prefixes (`op_`, `ev_`, `tr_`, `hd_`) already comply
+- **`Dex::Id.generate` accepts `random:` width option** – controls the number of random suffix characters (default 12, minimum 8). `Dex::Id.generate("ord_", random: 16)` produces a longer ID with more collision resistance
+- **`Dex::Tool.from` accepts Query classes** – `Dex::Tool.from(Order::Query, scope: -> { ... }, serialize: -> { ... })` turns a `Dex::Query` into an LLM-callable tool with mandatory scope injection, serialization, and result limiting. Supports `limit:`, `only_filters:`, `except_filters:`, and `only_sorts:` for fine-grained control. Context-mapped and `_Ref` props are auto-excluded from the tool schema. Returns paginated results with `{ records:, total:, limit:, offset: }`. All options are validated at registration time with prescriptive error messages. Excluded filters are enforced at runtime — the agent cannot bypass filter restrictions even by sending unlisted params
+- **`Dex::Operation::Ticket`** – `async.call` now returns a structured `Ticket` instead of a raw ActiveJob instance. The ticket exposes `record` (the operation record, if recording is enabled) and `job` (the enqueued job). Delegated accessors: `id`, `operation_name`, `status`, `error_code`, `error_message`, `error_details`. Predicate methods: `completed?`, `error?`, `failed?`, `pending?`, `running?`, `terminal?`, `recorded?`. `reload` refreshes from the database. `to_param` returns the ID for Rails path helpers. `as_json` provides a ready-made JSON representation for polling endpoints. `Ticket.from_record(record)` constructs a ticket from any operation record (async or sync) for status pages and admin dashboards
+- **Outcome reconstruction** – `ticket.outcome` reconstructs `Ok` or `Err` from a terminal record's business outcome. `completed` records produce `Ok(result)` with deep-symbolized keys for pattern matching, `error` records produce `Err(Dex::Error)` with symbolized code and details, and non-terminal or `failed` records return `nil`. Result hashes wrapped in `_dex_value` are transparently unwrapped
+- **`ticket.wait(timeout, interval:)` and `ticket.wait!(timeout, interval:)`** – speculative sync for async operations. `wait` polls the record until a business outcome is available or the timeout expires, returning `Ok`/`Err` or `nil` on timeout. `wait!` unwraps `Ok` and re-raises `Err`, raising `Dex::Timeout` on timeout. Both raise `Dex::OperationFailed` if the operation crashed (infrastructure failure). Interval accepts a fixed number or a callable for backoff strategies. Timeouts above 10 seconds emit a warning
+- **`Dex::OperationFailed`** – new exception class (inherits `StandardError`, not `Dex::Error`) raised by `wait`/`wait!` when an async operation crashed with an infrastructure failure (status `"failed"`). Exposes `operation_name`, `exception_class`, and `exception_message`
+- **`Dex::Timeout`** – new exception class (inherits `StandardError`, not `Dex::Error`) raised by `wait!` when the timeout expires without the operation reaching a terminal state. Exposes `timeout`, `ticket_id`, and `operation_name`
+- **`Dex.actor`** – convenience reader for the current trace actor. Returns the actor hash in the same shape you passed to `Dex::Trace.start` (e.g. `{ type: "user", id: "42" }`), or `nil` when no actor is set. Symmetric with `Dex.context`
+- **`Dex.system(name = nil)`** – convenience helper for building system actor hashes. `Dex.system` returns `{ type: :system }`, `Dex.system("payroll")` returns `{ type: :system, name: "payroll" }`. Use with `Dex::Trace.start(actor: Dex.system("nightly_cleanup"))`
+- **`Ok#deconstruct` and `Err#deconstruct`** – array deconstruct support for pattern matching. `in Dex::Ok[value]` binds the raw value; `in Dex::Err[error]` binds the `Dex::Error` instance. Complements the existing hash deconstruct (`in Dex::Ok(key:)`, `in Dex::Err(code:)`)
+
+### Changed
+
+- **`async.call` returns `Ticket` instead of ActiveJob instance** – callers that previously captured the return value of `async.call` to access the raw job must use `ticket.job` instead. The job is still accessible via the ticket. Code that ignores the return value (`op.async.call` without assignment) is unaffected
+- **`safe` and `async` are non-composable** – `op.safe.async` raises `NoMethodError` with a prescriptive message guiding toward `wait`/`wait!`. `op.async.safe` raises the same. Previously both raised generic `NoMethodError`
+
+## [0.10.0] - 2026-03-09
+
+### Added
+
+- **`field` / `field?` DSL for forms** – `field :name, :string` declares a required field with auto-presence validation; unconditional explicit presence validators deduplicate with it, while scoped/conditional validators still layer on top. `field? :notes, :string` declares an optional field (nil by default). Both support `desc:` for metadata and `default:` for defaults. Raw `attribute` remains available as an escape hatch
+- **Form registry and description** – `Dex::Form` now extends `Registry`, giving forms `description`, `Dex::Form.registry`, and `deregister` – the same ecosystem as Operation, Event, and Handler
+- **Form ambient context** – forms support the same `context` DSL as Operation and Event. `context :locale` auto-fills from `Dex.context` during initialization. Uses the same shared `ContextDSL` module with Form-specific injection
+- **Form export** – `Form.to_h` (class-level schema), `Form.to_json_schema`, and `Dex::Form.export(format:)` for bulk export. Nested forms are recursively included in both formats, and bulk export returns top-level named forms without listing nested helper classes separately
+- **Query registry, description, context, and export** – `Dex::Query` now extends `Registry` (giving `description`, `Dex::Query.registry`, `deregister`), includes `ContextSetup` (enabling `context :tenant` to auto-fill from `Dex.with_context`), and adds `Query.to_h`, `Query.to_json_schema`, `Dex::Query.export(format:)`. Query is now a full citizen alongside Operation, Event, and Form
+
+### Changed
+
+- **Shared context DSL** – extracted `Dex::ContextDSL` as a shared module used by both `ContextSetup` (Operation/Event) and `Form::Context`. No behavior change for Operation or Event
+
 ## [0.9.0] - 2026-03-09
 
 ### Breaking
 
+- **Unified execution tracing replaces event-only tracing** – `Dex::Trace` is a new fiber-local trace that spans operations, events, and handlers. Operations get `op_...` execution IDs, events get `ev_...` IDs (replacing UUIDs), handlers get `hd_...` IDs, and traces are correlated with `tr_...` IDs. `event.trace { }` is removed – use `caused_by:` for explicit event causality and `Dex::Trace.start(actor:)` at request/job boundaries
+- **Operation record primary keys are now string IDs** – records use the operation's `op_...` execution ID as a string primary key instead of auto-increment integers. The recording schema adds `trace_id`, `actor_type`, `actor_id`, and `trace` columns. Existing tables need a migration to adopt the new schema
 - **Mongoid transaction support removed** — `transaction :mongoid` and `config.transaction_adapter = :mongoid` are no longer valid. Dex no longer ships a Mongoid transaction adapter. Before: Mongoid transactions could be enabled via configuration or per-operation DSL. After: both forms raise `ArgumentError` immediately at declaration/configuration time. Mongoid-only apps continue to work — transactions are automatically disabled (no adapter detected), and `after_commit` fires immediately after success. If you need Mongoid multi-document transactions, call `Mongoid.transaction` directly inside `perform`
 - **Recording backends now validate required attributes before use** — Dex no longer silently drops missing `params`, `result`, `status`, or `once` attributes from `record_class`. Before: partial ActiveRecord/Mongoid recording models could appear to work while losing status transitions, replay data, or async params. After: Dex raises `ArgumentError` naming the missing attributes required by core recording, async record jobs, or `once`. Apps using minimal recording models must add the required columns/fields or explicitly disable the features that need them
 
+### Added
+
+- **`Dex::Trace` API** – `start(actor:, trace_id:)`, `.trace_id`, `.current`, `.current_id`, `.actor`, `.to_s`, `.dump`, `.restore`. Fiber-local, auto-starts when no trace is active, serializes across async job boundaries
+- **Trace persistence** – operation records and event stores persist `id`, `trace_id`, `actor_type`, `actor_id`, and `trace` when the columns exist. Event metadata includes `event_ancestry` for materialized-path tree queries
+- **`Dex::Id`** – Stripe-style prefixed ID generation with embedded timestamps for sortability
+
 ### Fixed
 
 - **Mongoid-only Rails compatibility** — Dex boots and runs cleanly in Mongoid-only Rails apps without `activerecord` loaded, with prescriptive `LoadError`s for unsupported paths such as `advisory_lock` and async event dispatch without `ActiveJob`
@@ -165,7 +221,7 @@
   - Causality tracing: `event.trace { ... }` and `caused_by:` link events into chains with shared `trace_id`
   - Block-scoped suppression: `Dex::Event.suppress(SomeEvent) { ... }`
   - Optional persistence via `event_store` configuration
-  - Context capture and restoration across async boundaries (`event_context`, `restore_event_context`)
+  - Context capture across async boundaries via `Dex.with_context` and the `context` DSL
 - **Event test helpers** — `Dex::Event::TestHelpers` module
   - `capture_events` block for inspecting published events without dispatching
   - `assert_event_published`, `refute_event_published`, `assert_event_count`

data/README.md

@@ -1,16 +1,19 @@
 # dexkit
 
-Rails patterns toolbelt. Equip to gain +4 DEX.
+Typed patterns for Rails, crafted for DX. Equip to gain +4 DEX.
 
-> **Active development.** dexkit is pre-1.0 and evolving rapidly. The public API may change between minor versions as the library matures.
+**[Documentation](https://dex.razorjack.net)** · **[Design Philosophy](https://dex.razorjack.net/guide/philosophy)** · **[DX Meets AI](https://dex.razorjack.net/guide/ai)**
 
-**[Documentation](https://dex.razorjack.net)**
+> **Pre-1.0.** Active development. The public API may change between minor versions.
 
-## Operations
+Four base classes with contracts that enforce themselves:
 
-Service objects with typed properties, transactions, error handling, and more.
+- **[Dex::Operation](https://dex.razorjack.net/operation/)** – typed service objects with structured errors, transactions, and async execution
+- **[Dex::Event](https://dex.razorjack.net/event/)** – immutable domain events with pub/sub, async handlers, and causality tracing
+- **[Dex::Query](https://dex.razorjack.net/query/)** – declarative filters and sorts for ActiveRecord and Mongoid scopes
+- **[Dex::Form](https://dex.razorjack.net/form/)** – form objects with typed fields, nested forms, and Rails form builder compatibility
 
-Mongoid-only Rails apps work too – queries, recording, events, and forms all adapt automatically. Transactions are ActiveRecord-only (Mongoid users who need transactions can call `Mongoid.transaction` inside `perform`); `advisory_lock` is also ActiveRecord-only. Operation/event store models can be Mongoid documents; recording models must define the fields required by the enabled recording features.
+## Operations
 
 ```ruby
 class Order::Place < Dex::Operation
@@ -34,29 +37,20 @@ class Order::Place < Dex::Operation
 end
 
 order = Order::Place.call(customer: 42, product: 7, quantity: 2)
-order.id  # => 1
 ```
 
-### What you get out of the box
-
-**Typed properties** – powered by [literal](https://github.com/joeldrapper/literal). Plain classes, ranges, unions, arrays, nilable, and model references with auto-find:
+Here's what you got:
 
-```ruby
-prop :quantity, _Integer(1..)
-prop :currency, _Union("USD", "EUR", "GBP")
-prop :customer, _Ref(Customer)        # accepts Customer instance or ID
-prop? :note, String                    # optional (nil by default)
-```
+- **`_Ref(Customer)`** accepts a Customer instance or an ID – the record is auto-fetched
+- **`_Integer(1..)`** guarantees a positive integer before `perform` runs
+- **`prop?`** marks optional inputs (nil by default)
+- **`success` / `error`** declare the contract – typos in error codes raise `ArgumentError`
+- **`error!`** halts execution, rolls back the transaction, returns a structured error
+- **`after_commit`** fires only after the transaction succeeds – safe for emails, webhooks, events
 
-**Structured errors** with `error!`, `assert!`, and `rescue_from`:
-
-```ruby
-product = assert!(:not_found) { Product.find_by(id: product_id) }
-
-rescue_from Stripe::CardError, as: :payment_declined
-```
+### Pattern matching
 
-**Ok / Err** – pattern match on operation outcomes with `.safe.call`:
+`.safe.call` returns `Ok` or `Err` instead of raising:
 
 ```ruby
 case Order::Place.new(customer: 42, product: 7, quantity: 2).safe.call
@@ -64,132 +58,50 @@ in Ok => result
   redirect_to order_path(result.id)
 in Err(code: :out_of_stock)
   flash[:error] = "Product is out of stock"
+  render :new
 end
 ```
 
-**Async execution** via ActiveJob:
+### Guards
 
-```ruby
-Order::Fulfill.new(order_id: 123).async(queue: "fulfillment").call
-```
-
-**Idempotency** with `once` — run an operation at most once for a given key. Results are replayed on duplicates:
+Inline precondition checks with introspection — ask "can this run?" from views and controllers:
 
 ```ruby
-class Payment::Charge < Dex::Operation
-  prop :order_id, Integer
-  prop :amount, Integer
-
-  once :order_id                          # key from prop
-  # once :order_id, :merchant_id          # composite key
-  # once                                  # all props as key
-  # once { "custom-#{order_id}" }         # block-based key
-  # once :order_id, expires_in: 24.hours  # expiring key
-
-  def perform
-    Gateway.charge!(order_id, amount)
-  end
+guard :active_customer, "Customer account must be active" do
+  !customer.suspended?
 end
 
-# Call-site key (overrides class-level declaration)
-Payment::Charge.new(order_id: 1, amount: 500).once("ext-key-123").call
-
-# Bypass once guard for a single call
-Payment::Charge.new(order_id: 1, amount: 500).once(nil).call
-
-# Clear a stored key to allow re-execution
-Payment::Charge.clear_once!(order_id: 1)
-```
-
-Business errors are replayed; exceptions release the key so the operation can be retried. Requires the record backend (recording is enabled by default when `record_class` is configured).
-
-**Guards** – inline precondition checks with introspection. Ask "can this operation run?" from views and controllers:
-
-```ruby
-guard :out_of_stock, "Product must be in stock" do
-  !product.in_stock?
-end
-
-# In a view or controller:
 Order::Place.callable?(customer: customer, product: product, quantity: 1)
+# => true / false
 ```
 
-**Ambient context** – declare which props come from ambient state. Set once in a controller, auto-fill everywhere:
-
-```ruby
-class Order::Place < Dex::Operation
-  prop :product, _Ref(Product)
-  prop :customer, _Ref(Customer)
-  context customer: :current_customer   # filled from Dex.context[:current_customer]
-
-  def perform
-    Order.create!(product: product, customer: customer)
-  end
-end
-
-# Controller
-Dex.with_context(current_customer: current_customer) do
-  Order::Place.call(product: product)   # customer auto-filled
-end
-
-# Tests – just pass it explicitly
-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:
+### Prescriptive errors
 
-```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/):
+Every mistake tells you what went wrong, why, and what to do instead:
 
 ```ruby
-# List all operations
-Dex::Operation.registry  # => #<Set: {Order::Place, Order::Cancel, ...}>
+error!(:not_found)
+# => ArgumentError: Order::Place declares unknown error code :not_found.
+#    Declared codes: [:out_of_stock]
 
-# Export contracts
-Dex::Operation.export(format: :json_schema)
+prop :email, 123
+# => Literal::TypeError: expected a type, got 123 (Integer)
 
-# 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")
+once :nonexistent_prop
+# => ArgumentError: Order::Place.once references unknown prop :nonexistent_prop.
+#    Declared props: [:customer, :product, :quantity, :note]
 ```
 
-**Transactions** on by default, **advisory locking**, **recording** to database, **callbacks**, and a customizable **pipeline** – all composable, all optional.
-
-### Testing
+### And more
 
-First-class test helpers for Minitest:
-
-```ruby
-class PlaceOrderTest < Minitest::Test
-  testing Order::Place
-
-  def test_places_order
-    assert_operation(customer: customer.id, product: product.id, quantity: 2)
-  end
-
-  def test_rejects_out_of_stock
-    assert_operation_error(:out_of_stock, customer: customer.id,
-      product: out_of_stock_product.id, quantity: 1)
-  end
-end
-```
+[Ambient context](https://dex.razorjack.net/operation/context), [unified tracing](https://dex.razorjack.net/operation/tracing) with [Stripe-style IDs](https://dex.razorjack.net/utilities/prefixed-ids), [idempotency](https://dex.razorjack.net/operation/once), [async execution](https://dex.razorjack.net/operation/async), [advisory locks](https://dex.razorjack.net/operation/advisory-lock), [DB recording](https://dex.razorjack.net/operation/recording), [explain](https://dex.razorjack.net/operation/explain) for preflight checks, [callbacks](https://dex.razorjack.net/operation/callbacks), a [customizable pipeline](https://dex.razorjack.net/operation/pipeline), [registry & export](https://dex.razorjack.net/tooling/registry), and [LLM tool integration](https://dex.razorjack.net/tool/) for operations and queries.
 
 ## Events
 
-Typed, immutable event objects with publish/subscribe, async dispatch, and causality tracing.
-
 ```ruby
 class Order::Placed < Dex::Event
   prop :order_id, Integer
   prop :total, BigDecimal
-  prop? :coupon_code, String
 end
 
 class NotifyWarehouse < Dex::Event::Handler
@@ -197,175 +109,72 @@ class NotifyWarehouse < Dex::Event::Handler
   retries 3
 
   def perform
-    WarehouseApi.notify(event.order_id)
+    WarehouseApi.reserve(event.order_id)
   end
 end
 
 Order::Placed.publish(order_id: 1, total: 99.99)
 ```
 
-### What you get out of the box
-
-**Zero-config pub/sub** — define events and handlers, publish. No bus setup needed.
-
-**Async by default** — handlers dispatched via ActiveJob. `sync: true` for inline. If ActiveJob is not loaded, async publish raises `LoadError`.
-
-**Causality tracing** — link events in chains with shared `trace_id`:
-
-```ruby
-order_placed.trace do
-  Shipment::Reserved.publish(order_id: 1)
-end
-```
-
-**Callbacks** — `before`, `after`, `around` hooks on handlers, same DSL as operations.
-
-**Transactions** — opt-in `transaction` and `after_commit` for handlers that write to the database.
-
-**Suppression**, optional **persistence**, **context capture**, and **retries** with exponential backoff.
-
-### Testing
-
-```ruby
-class PlaceOrderTest < Minitest::Test
-  include Dex::Event::TestHelpers
-
-  def test_publishes_order_placed
-    capture_events do
-      Order::Place.call(customer: customer.id, product: product.id, quantity: 2)
-      assert_event_published(Order::Placed)
-    end
-  end
-end
-```
-
-## Forms
-
-Form objects with typed attributes, normalization, nested forms, and Rails form builder compatibility.
-
-```ruby
-class Employee::Form < Dex::Form
-  model Employee
-
-  attribute :first_name, :string
-  attribute :last_name, :string
-  attribute :email, :string
-
-  normalizes :email, with: -> { _1&.strip&.downcase.presence }
-
-  validates :email, presence: true, uniqueness: true
-  validates :first_name, :last_name, presence: true
-
-  nested_one :address do
-    attribute :street, :string
-    attribute :city, :string
-    validates :street, :city, presence: true
-  end
-end
-
-form = Employee::Form.new(email: "  ALICE@EXAMPLE.COM  ", first_name: "Alice", last_name: "Smith")
-form.email  # => "alice@example.com"
-form.valid?
-```
-
-### What you get out of the box
-
-**ActiveModel attributes** with type casting, normalization, and full Rails validation DSL.
-
-**Nested forms** — `nested_one` and `nested_many` with automatic Hash coercion, `_destroy` support, and error propagation:
-
-```ruby
-nested_many :emergency_contacts do
-  attribute :name, :string
-  attribute :phone, :string
-  validates :name, :phone, presence: true
-end
-```
-
-**Rails form compatibility** — works with `form_with`, `fields_for`, and nested attributes out of the box.
-
-**Uniqueness validation** against the database, with scope, case-sensitivity, and current-record exclusion.
-
-**Multi-model forms** — when a form spans Employee, Department, and Address, define a `.for` convention method to map records and a `#save` method that delegates to a `Dex::Operation`:
-
-```ruby
-def save
-  return false unless valid?
-
-  case operation.safe.call
-  in Ok then true
-  in Err => e then errors.add(:base, e.message) and false
-  end
-end
-```
-
 ## Queries
 
-Declarative query objects for filtering and sorting ActiveRecord and Mongoid scopes.
-
 ```ruby
 class Order::Query < Dex::Query
   scope { Order.all }
 
   prop? :status, String
-  prop? :customer, _Ref(Customer)
   prop? :total_min, Integer
 
   filter :status
-  filter :customer
   filter :total_min, :gte, column: :total
 
   sort :created_at, :total, default: "-created_at"
 end
 
-orders = Order::Query.call(status: "pending", sort: "-total")
+Order::Query.call(status: "pending", sort: "-total")
 ```
 
-### What you get out of the box
+## Forms
 
-**11 built-in filter strategies** — `:eq`, `:not_eq`, `:contains`, `:starts_with`, `:ends_with`, `:gt`, `:gte`, `:lt`, `:lte`, `:in`, `:not_in`. Custom blocks for complex logic.
+```ruby
+class Order::Form < Dex::Form
+  field :customer_email, :string
+  field? :note, :string
 
-**Sorting** with ascending/descending column sorts, custom sort blocks, and defaults.
+  nested_many :line_items do
+    field :product_id, :integer
+    field :quantity, :integer, default: 1
+  end
+end
+```
 
-**`from_params`** — HTTP boundary handling with automatic coercion, blank stripping, and invalid value fallback:
+## Testing
 
 ```ruby
-class OrdersController < ApplicationController
-  def index
-    query = Order::Query.from_params(params, scope: policy_scope(Order))
-    @orders = pagy(query.resolve)
+class PlaceOrderTest < Minitest::Test
+  testing Order::Place
+
+  def test_places_order
+    result = call_operation(customer: customer.id, product: product.id, quantity: 2)
+    assert_ok result
+  end
+
+  def test_rejects_out_of_stock
+    result = call_operation(customer: customer.id,
+      product: out_of_stock_product.id, quantity: 1)
+    assert_err result, :out_of_stock
   end
 end
 ```
 
-**Form binding** — works with `form_with` for search forms. Queries respond to `model_name`, `param_key`, `persisted?`, and `to_params`.
-
-**Scope injection** — narrow the base scope at call time without modifying the query class.
-
 ## Installation
 
 ```ruby
 gem "dexkit"
 ```
 
-## Documentation
-
-Full documentation at **[dex.razorjack.net](https://dex.razorjack.net)**.
-
-## AI Coding Assistant Setup
-
-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
-rake dex:guides OPERATIONS_PATH=app/services
+rake dex:guides  # install LLM-optimized guides as AGENTS.md in your app directories
 ```
 
 ## License

data/gemfiles/mongoid_no_ar.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    dexkit (0.8.0)
+    dexkit (0.11.0)
       activemodel (>= 6.1)
       literal (~> 1.9)
       zeitwerk (~> 2.6)
@@ -180,7 +180,7 @@ CHECKSUMS
   connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
   crass (1.0.6) sha256=dc516022a56e7b3b156099abc81b6d2b08ea1ed12676ac7a5657617f012bd45d
   date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
-  dexkit (0.8.0)
+  dexkit (0.11.0)
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   erb (6.0.2) sha256=9fe6264d44f79422c87490a1558479bd0e7dad4dd0e317656e67ea3077b5242b
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9

data/guides/llm/EVENT.md

@@ -30,9 +30,9 @@ class UserCreated < Dex::Event
 end
 ```
 
-Reserved names: `id`, `timestamp`, `trace_id`, `caused_by_id`, `caused_by`, `context`, `publish`, `metadata`, `sync`.
+Reserved names: `id`, `timestamp`, `trace_id`, `caused_by_id`, `caused_by`, `event_ancestry`, `context`, `publish`, `metadata`, `sync`.
 
-Events are frozen after creation. Each gets auto-generated `id` (UUID), `timestamp` (UTC), `trace_id`, and optional `caused_by_id`.
+Events are frozen after creation. Each gets auto-generated `id` (`ev_...`), `timestamp` (UTC), `trace_id` (`tr_...` by default), optional `caused_by_id`, and `event_ancestry` (ordered ancestor event IDs).
 
 ### Literal Types Cheatsheet
 
@@ -72,10 +72,11 @@ class NotifyWarehouse < Dex::Event::Handler
   def perform
     event                    # accessor — the event instance
     event.order_id           # typed props
-    event.id                 # UUID
+    event.id                 # prefixed event ID (ev_...)
     event.timestamp          # Time (UTC)
     event.caused_by_id       # parent event ID (if traced)
-    event.trace_id           # shared trace ID across causal chain
+    event.trace_id           # shared trace / correlation ID
+    event.event_ancestry     # ordered ancestor event IDs
   end
 end
 ```
@@ -179,22 +180,20 @@ Default handler pipeline: `[:transaction, :callback]`.
 
 ## Tracing (Causality)
 
-Link events in a causal chain. All events in a chain share the same `trace_id`.
+Events participate in the unified `Dex::Trace` used by operations and handlers. All events in a trace share the same `trace_id`.
 
 ```ruby
-order_placed = OrderPlaced.new(order_id: 1, total: 99.99)
-
-# Option 1: trace block
-order_placed.trace do
-  InventoryReserved.publish(order_id: 1)   # caused_by_id = order_placed.id
-  ShippingRequested.publish(order_id: 1)   # same trace_id
+# Start a trace at the request/job boundary
+Dex::Trace.start(actor: { type: :user, id: current_user.id }) do
+  OrderPlaced.publish(order_id: 1, total: 99.99)
 end
 
-# Option 2: caused_by keyword
+# Explicit event-to-event causality
+order_placed = OrderPlaced.new(order_id: 1, total: 99.99)
 InventoryReserved.publish(order_id: 1, caused_by: order_placed)
 ```
 
-Nesting works — each child gets the nearest parent's `id` as `caused_by_id`, and the root's `trace_id`.
+When an event is published inside a handler, the handler's event becomes the cause automatically. Explicit `caused_by:` sets `caused_by_id` and appends to `event_ancestry`.
 
 ---
 
@@ -218,12 +217,16 @@ Store events to database when configured:
 
 ```ruby
 Dex.configure do |c|
-  c.event_store = EventRecord   # any model with create!(event_type:, payload:, metadata:)
+  c.event_store = EventRecord   # Dex passes trace fields when the model supports them
 end
 ```
 
 ```ruby
-create_table :event_records do |t|
+create_table :event_records, id: :string do |t|
+  t.string :trace_id
+  t.string :actor_type
+  t.string :actor_id
+  t.jsonb  :trace
   t.string :event_type
   t.jsonb  :payload
   t.jsonb  :metadata
@@ -238,6 +241,11 @@ class EventRecord
   include Mongoid::Document
   include Mongoid::Timestamps
 
+  field :_id, type: String
+  field :trace_id, type: String
+  field :actor_type, type: String
+  field :actor_id, type: String
+  field :trace, type: Array
   field :event_type, type: String
   field :payload, type: Hash
   field :metadata, type: Hash
@@ -282,10 +290,6 @@ end
 
 **Introspection:** `MyEvent.context_mappings` returns the mapping hash.
 
-### Legacy Context (Metadata)
-
-The older `event_context` / `restore_event_context` configuration captures arbitrary metadata at publish time and restores it before async handler execution. Both mechanisms coexist.
-
 ---
 
 ## Configuration
@@ -294,12 +298,10 @@ The older `event_context` / `restore_event_context` configuration captures arbit
 # config/initializers/dexkit.rb
 Dex.configure do |config|
   config.event_store = nil               # model for persistence (default: nil)
-  config.event_context = nil             # -> { Hash } lambda (default: nil)
-  config.restore_event_context = nil     # ->(ctx) { ... } lambda (default: nil)
 end
 ```
 
-Everything works without configuration. All three settings are optional.
+Everything works without configuration.
 
 ---
 
@@ -381,10 +383,7 @@ class CreateOrderTest < Minitest::Test
   def test_trace_chain
     capture_events do
       parent = OrderPlaced.new(order_id: 1, total: 99.99)
-
-      parent.trace do
-        InventoryReserved.publish(order_id: 1)
-      end
+      InventoryReserved.publish(order_id: 1, caused_by: parent)
 
       child = _dex_published_events.last
       assert_event_trace(parent, child)