dexkit 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1009624f8d508e4d6b61d76c8d54f32fc04a11f445163915c027ebc1bdd30b5e
-  data.tar.gz: 1b5a0755af0be468d67c3c5447f1322deff584364a493fb7665687d1417189b3
+  metadata.gz: 493f1873cf71e1f8e2348f4f15e3e508962d9ae310b85f7b4aac8a756396de05
+  data.tar.gz: ad50fd8349a45e4c4bc536f68bb2c74ee10b59e8b80856fca2823bb9f9a998cf
 SHA512:
-  metadata.gz: '08552d04b1e9ddf5991f1454f9491fcabe80047d9606f0432be411f09d7b632a797435fabf55d8e9b190ddbc1a70daa5e73c19aa08c2bde88540559c3d35275e'
-  data.tar.gz: 33d58dd5b421a1e7f41d3ab133c1800787d2d1f6c22327e7db7faf9053222d62d087c4a563105fb39075fbefc1a73f04984b45511595a0e3976eda9833de0cdf
+  metadata.gz: 18ca385b0d66155e35c3f08164d3b558e85f3f29a586b492d664c72c24f746e6e70c0d6692faedb348e7c849096eb0f3ddfd98a5515e2de5b5ce05084cab3d5e
+  data.tar.gz: 2e7c2e59443b2dff7fb3a9de4c3296ce1b71c4f870bf47d2ce503f5d5c23105a1cee5549618451741a21fb6d0c8fcb0eba53b94d4edcf8e999e1164e9eabf96f

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 ## [Unreleased]
 
+## [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. `Dex::Event::Trace` remains as a thin delegation layer
+- **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`
+- **ActiveRecord transaction auto-detection is stricter** — Dex now enables the ActiveRecord transaction adapter only when an ActiveRecord connection pool actually exists. Before: merely loading `activerecord` could make Mongoid-backed operations try to open an ActiveRecord transaction and fail with `ActiveRecord::ConnectionNotDefined`. After: unconfigured ActiveRecord no longer activates transactions implicitly
+- **Mongoid async/recording serialization** — `_Ref(Model)` serializes IDs via `id.as_json`, so `BSON::ObjectId` values round-trip through async operations, async events, and recording without `ActiveJob::SerializationError`. Recording and `once` sanitize untyped Mongoid document results to JSON-safe payloads
+- **Mongoid query and form parity** — query adapter detection and scope merging normalize Mongoid association scopes to `Mongoid::Criteria`, uniqueness validation excludes persisted Mongoid records correctly and uses a case-insensitive regex path for `case_sensitive: false`, and `_Ref(lock: true)` fails fast for model classes that do not support `.lock`
+
 ## [0.8.0] - 2026-03-09
 
 ### Added

data/README.md

@@ -2,12 +2,16 @@
 
 Rails patterns toolbelt. 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)**
 
 ## Operations
 
 Service objects with typed properties, transactions, error handling, and more.
 
+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.
+
 ```ruby
 class Order::Place < Dex::Operation
   prop :customer, _Ref(Customer)
@@ -69,6 +73,17 @@ end
 Order::Fulfill.new(order_id: 123).async(queue: "fulfillment").call
 ```
 
+**Execution tracing** – every operation gets a prefixed ID and joins a unified trace across operations, events, and handlers:
+
+```ruby
+Dex::Trace.start(actor: { type: :user, id: current_user.id }) do
+  Order::Place.call(customer: 42, product: 7, quantity: 2)
+end
+
+Dex::Trace.trace_id   # => "tr_..."
+Dex::Trace.current    # => [{ type: :actor, ... }, { type: :operation, ... }]
+```
+
 **Idempotency** with `once` — run an operation at most once for a given key. Results are replayed on duplicates:
 
 ```ruby
@@ -204,13 +219,14 @@ Order::Placed.publish(order_id: 1, total: 99.99)
 
 **Zero-config pub/sub** — define events and handlers, publish. No bus setup needed.
 
-**Async by default** — handlers dispatched via ActiveJob. `sync: true` for inline.
+**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`:
+**Causality tracing** – events join the unified execution trace, and child events link to their cause:
 
 ```ruby
-order_placed.trace do
-  Shipment::Reserved.publish(order_id: 1)
+Dex::Trace.start(actor: { type: :user, id: 42 }) do
+  order_placed = Order::Placed.new(order_id: 1, total: 99.99)
+  Shipment::Reserved.publish(order_id: 1, caused_by: order_placed)
 end
 ```
 
@@ -237,25 +253,29 @@ end
 
 ## Forms
 
-Form objects with typed attributes, normalization, nested forms, and Rails form builder compatibility.
+Form objects with typed fields, normalization, nested forms, ambient context, JSON Schema export, and Rails form builder compatibility.
 
 ```ruby
 class Employee::Form < Dex::Form
+  description "Employee onboarding form"
   model Employee
 
-  attribute :first_name, :string
-  attribute :last_name, :string
-  attribute :email, :string
+  field :first_name, :string
+  field :last_name, :string
+  field :email, :string
+  field :locale, :string
+  field? :notes, :string
+
+  context :locale
 
   normalizes :email, with: -> { _1&.strip&.downcase.presence }
 
-  validates :email, presence: true, uniqueness: true
-  validates :first_name, :last_name, presence: true
+  validates :email, uniqueness: true
 
   nested_one :address do
-    attribute :street, :string
-    attribute :city, :string
-    validates :street, :city, presence: true
+    field :street, :string
+    field :city, :string
+    field? :apartment, :string
   end
 end
 
@@ -266,18 +286,21 @@ form.valid?
 
 ### What you get out of the box
 
-**ActiveModel attributes** with type casting, normalization, and full Rails validation DSL.
+**`field` / `field?`** — required and optional fields with auto-presence validation, `desc:` metadata, and defaults. Backed by ActiveModel attributes with type casting and normalization. Unconditional `validates :attr, presence: true` deduplicates with `field`; scoped validations still layer on top.
 
 **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
+  field :name, :string
+  field :phone, :string
 end
 ```
 
+**Ambient context** — auto-fill fields from `Dex.context`, same DSL as Operation and Event.
+
+**Registry & Export** — `description`, `to_json_schema`, class-level `to_h`, and `Dex::Form.export` for schema introspection. Nested form schemas recurse in both export formats, and bulk export includes only top-level named forms.
+
 **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.
@@ -297,15 +320,20 @@ end
 
 ## Queries
 
-Declarative query objects for filtering and sorting ActiveRecord relations and Mongoid criteria.
+Declarative query objects for filtering and sorting ActiveRecord and Mongoid scopes.
 
 ```ruby
 class Order::Query < Dex::Query
+  description "Search orders"
+
   scope { Order.all }
 
   prop? :status, String
   prop? :customer, _Ref(Customer)
   prop? :total_min, Integer
+  prop? :tenant, String
+
+  context tenant: :current_tenant
 
   filter :status
   filter :customer
@@ -319,6 +347,10 @@ orders = Order::Query.call(status: "pending", sort: "-total")
 
 ### What you get out of the box
 
+**Registry, description, and context** — same ecosystem as Operation, Event, and Form. `Dex::Query.registry` discovers all query classes, `description` documents intent, and `context` auto-fills props from `Dex.with_context`.
+
+**Export** — `Query.to_h`, `Query.to_json_schema`, `Dex::Query.export(format:)` for introspection and bulk export.
+
 **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.
 
 **Sorting** with ascending/descending column sorts, custom sort blocks, and defaults.

data/gemfiles/mongoid_no_ar.gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+gem "dexkit", path: ".."
+
+gem "activejob", ">= 6.1"
+gem "actionpack", ">= 6.1"
+gem "activesupport", ">= 6.1"
+gem "mongoid", ">= 8.0"
+gem "ostruct"
+gem "railties", ">= 6.1"

data/gemfiles/mongoid_no_ar.gemfile.lock

@@ -0,0 +1,232 @@
+PATH
+  remote: ..
+  specs:
+    dexkit (0.10.0)
+      activemodel (>= 6.1)
+      literal (~> 1.9)
+      zeitwerk (~> 2.6)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (8.1.2)
+      actionview (= 8.1.2)
+      activesupport (= 8.1.2)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actionview (8.1.2)
+      activesupport (= 8.1.2)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.1.2)
+      activesupport (= 8.1.2)
+      globalid (>= 0.3.6)
+    activemodel (8.1.2)
+      activesupport (= 8.1.2)
+    activesupport (8.1.2)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    bson (5.2.0)
+    builder (3.3.0)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    crass (1.0.6)
+    date (3.5.1)
+    drb (2.2.3)
+    erb (6.0.2)
+    erubi (1.13.1)
+    globalid (1.3.0)
+      activesupport (>= 6.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.2)
+    irb (1.17.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.19.1)
+    literal (1.9.0)
+      zeitwerk
+    logger (1.7.0)
+    loofah (2.25.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    minitest (6.0.2)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    mongo (2.23.0)
+      base64
+      bson (>= 4.14.1, < 6.0.0)
+    mongoid (9.0.10)
+      activemodel (>= 5.1, < 8.2, != 7.0.0)
+      concurrent-ruby (>= 1.0.5, < 2.0)
+      mongo (>= 2.18.0, < 3.0.0)
+    nokogiri (1.19.1-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.1-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.1-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.1-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.1-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.1-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.1-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.1-x86_64-linux-musl)
+      racc (~> 1.4)
+    ostruct (0.6.3)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
+      stringio
+    racc (1.8.1)
+    rack (3.2.5)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.3.1)
+      rack (>= 3)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.7.0)
+      loofah (~> 2.25)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.1.2)
+      actionpack (= 8.1.2)
+      activesupport (= 8.1.2)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      tsort (>= 0.2)
+      zeitwerk (~> 2.6)
+    rake (13.3.1)
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    reline (0.6.3)
+      io-console (~> 0.5)
+    securerandom (0.4.1)
+    stringio (3.2.0)
+    thor (1.5.0)
+    tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.1.1)
+    useragent (0.16.11)
+    zeitwerk (2.7.5)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  actionpack (>= 6.1)
+  activejob (>= 6.1)
+  activesupport (>= 6.1)
+  dexkit!
+  mongoid (>= 8.0)
+  ostruct
+  railties (>= 6.1)
+
+CHECKSUMS
+  actionpack (8.1.2) sha256=ced74147a1f0daafaa4bab7f677513fd4d3add574c7839958f7b4f1de44f8423
+  actionview (8.1.2) sha256=80455b2588911c9b72cec22d240edacb7c150e800ef2234821269b2b2c3e2e5b
+  activejob (8.1.2) sha256=908dab3713b101859536375819f4156b07bdf4c232cc645e7538adb9e302f825
+  activemodel (8.1.2) sha256=e21358c11ce68aed3f9838b7e464977bc007b4446c6e4059781e1d5c03bcf33e
+  activesupport (8.1.2) sha256=88842578ccd0d40f658289b0e8c842acfe9af751afee2e0744a7873f50b6fdae
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
+  bson (5.2.0) sha256=c468c1e8a3cfa1e80531cc519a890f85586986721d8e305f83465cc36bb82608
+  builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
+  crass (1.0.6) sha256=dc516022a56e7b3b156099abc81b6d2b08ea1ed12676ac7a5657617f012bd45d
+  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
+  dexkit (0.10.0)
+  drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
+  erb (6.0.2) sha256=9fe6264d44f79422c87490a1558479bd0e7dad4dd0e317656e67ea3077b5242b
+  erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
+  globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11
+  i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
+  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
+  irb (1.17.0) sha256=168c4ddb93d8a361a045c41d92b2952c7a118fa73f23fe14e55609eb7a863aae
+  json (2.19.1) sha256=dd94fdc59e48bff85913829a32350b3148156bc4fd2a95a2568a78b11344082d
+  literal (1.9.0) sha256=b1dfac91931e71e1c4ebfddd4b459306f2973e9f749e077a647fece6ea15414a
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  loofah (2.25.0) sha256=df5ed7ac3bac6a4ec802df3877ee5cc86d027299f8952e6243b3dac446b060e6
+  minitest (6.0.2) sha256=db6e57956f6ecc6134683b4c87467d6dd792323c7f0eea7b93f66bd284adbc3d
+  mongo (2.23.0) sha256=be2fe4cc6f7119fa6b79e82a1963b2406856b4dc92d0ccfb74db543897be3109
+  mongoid (9.0.10) sha256=351192e70027276748f3c946b8926fad9254356e36021dacb5cec08d0740f21d
+  nokogiri (1.19.1-aarch64-linux-gnu) sha256=cfdb0eafd9a554a88f12ebcc688d2b9005f9fce42b00b970e3dc199587b27f32
+  nokogiri (1.19.1-aarch64-linux-musl) sha256=1e2150ab43c3b373aba76cd1190af7b9e92103564063e48c474f7600923620b5
+  nokogiri (1.19.1-arm-linux-gnu) sha256=0a39ed59abe3bf279fab9dd4c6db6fe8af01af0608f6e1f08b8ffa4e5d407fa3
+  nokogiri (1.19.1-arm-linux-musl) sha256=3a18e559ee499b064aac6562d98daab3d39ba6cbb4074a1542781b2f556db47d
+  nokogiri (1.19.1-arm64-darwin) sha256=dfe2d337e6700eac47290407c289d56bcf85805d128c1b5a6434ddb79731cb9e
+  nokogiri (1.19.1-x86_64-darwin) sha256=7093896778cc03efb74b85f915a775862730e887f2e58d6921e3fa3d981e68bf
+  nokogiri (1.19.1-x86_64-linux-gnu) sha256=1a4902842a186b4f901078e692d12257678e6133858d0566152fe29cdb98456a
+  nokogiri (1.19.1-x86_64-linux-musl) sha256=4267f38ad4fc7e52a2e7ee28ed494e8f9d8eb4f4b3320901d55981c7b995fc23
+  ostruct (0.6.3) sha256=95a2ed4a4bd1d190784e666b47b2d3f078e4a9efda2fccf18f84ddc6538ed912
+  pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rack (3.2.5) sha256=4cbd0974c0b79f7a139b4812004a62e4c60b145cba76422e288ee670601ed6d3
+  rack-session (2.1.1) sha256=0b6dc07dea7e4b583f58a48e8b806d4c9f1c6c9214ebc202ec94562cbea2e4e9
+  rack-test (2.2.0) sha256=005a36692c306ac0b4a9350355ee080fd09ddef1148a5f8b2ac636c720f5c463
+  rackup (2.3.1) sha256=6c79c26753778e90983761d677a48937ee3192b3ffef6bc963c0950f94688868
+  rails-dom-testing (2.3.0) sha256=8acc7953a7b911ca44588bf08737bc16719f431a1cc3091a292bca7317925c1d
+  rails-html-sanitizer (1.7.0) sha256=28b145cceaf9cc214a9874feaa183c3acba036c9592b19886e0e45efc62b1e89
+  railties (8.1.2) sha256=1289ece76b4f7668fc46d07e55cc992b5b8751f2ad85548b7da351b8c59f8055
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  rdoc (7.2.0) sha256=8650f76cd4009c3b54955eb5d7e3a075c60a57276766ebf36f9085e8c9f23192
+  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
+  securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
+  stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
+  thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b
+  uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
+  useragent (0.16.11) sha256=700e6413ad4bb954bb63547fa098dddf7b0ebe75b40cc6f93b8d54255b173844
+  zeitwerk (2.7.5) sha256=d8da92128c09ea6ec62c949011b00ed4a20242b255293dd66bf41545398f73dd
+
+BUNDLED WITH
+  4.0.4

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
 
@@ -56,7 +56,7 @@ event.publish(sync: true)        # sync
 OrderPlaced.publish(order_id: 1, total: 99.99, caused_by: parent_event)
 ```
 
-**Async** (default): handlers dispatched via ActiveJob. **Sync**: handlers called inline.
+**Async** (default): handlers dispatched via ActiveJob. If ActiveJob is not loaded, `publish(sync: false)` raises `LoadError`. **Sync**: handlers called inline.
 
 ---
 
@@ -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
 ```
@@ -109,7 +110,7 @@ class ProcessPayment < Dex::Event::Handler
 end
 ```
 
-When retries exhausted, exception propagates normally.
+When retries exhausted, exception propagates normally. Async handlers and retries require ActiveJob to be loaded.
 
 ### Callbacks
 
@@ -157,7 +158,7 @@ class FulfillOrder < Dex::Event::Handler
 end
 ```
 
-Transactions are **disabled by default** on handlers (unlike operations). Opt in with `transaction`. The `after_commit` block defers until the transaction commits; on exception, deferred blocks are discarded.
+Transactions are **disabled by default** on handlers (unlike operations). Opt in with `transaction`. The `after_commit` block defers until the transaction commits; on exception, deferred blocks are discarded. Transactions are ActiveRecord-only – in Mongoid-only apps, `after_commit` fires immediately after handler success.
 
 ### Custom Pipeline
 
@@ -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
@@ -231,6 +234,24 @@ create_table :event_records do |t|
 end
 ```
 
+Mongoid stores work too:
+
+```ruby
+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
+end
+```
+
 Persistence failures are silently rescued — they never halt event publishing.
 
 ---
@@ -294,7 +315,7 @@ Everything works without configuration. All three settings are optional.
 
 ```ruby
 # test/test_helper.rb
-require "dex/event_test_helpers"
+require "dex/event/test_helpers"
 
 class Minitest::Test
   include Dex::Event::TestHelpers
@@ -368,10 +389,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)