dexkit 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1009624f8d508e4d6b61d76c8d54f32fc04a11f445163915c027ebc1bdd30b5e
-  data.tar.gz: 1b5a0755af0be468d67c3c5447f1322deff584364a493fb7665687d1417189b3
+  metadata.gz: 41c8e4455fb4a4cca73b1d12da366b53bdbbada2cbae773917a12d344a150dd4
+  data.tar.gz: 86c4e76004df8b968c094b7b252a988eafe2f7aee035505ddb7bbeae1f25e04a
 SHA512:
-  metadata.gz: '08552d04b1e9ddf5991f1454f9491fcabe80047d9606f0432be411f09d7b632a797435fabf55d8e9b190ddbc1a70daa5e73c19aa08c2bde88540559c3d35275e'
-  data.tar.gz: 33d58dd5b421a1e7f41d3ab133c1800787d2d1f6c22327e7db7faf9053222d62d087c4a563105fb39075fbefc1a73f04984b45511595a0e3976eda9833de0cdf
+  metadata.gz: 89a9f6075f3955300dbe3944a9adc9b80ab56c3b4dc60d9458ea370f68c5c83ab5b3f2daad26c6f852d6f423a498ccf068914853e9866c05442765539ac6ac91
+  data.tar.gz: cd541ee35700cf9aa877b3630d66f0b9580263d0fddc7f381200afe32c638f832d941112387f646fa59500c26bb552461ad5bf0f0ec79dcf7bb97d76ebcbfb86

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.9.0] - 2026-03-09
+
+### Breaking
+
+- **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
+
+### 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)
@@ -204,7 +208,7 @@ 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`:
 
@@ -297,7 +301,7 @@ 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

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.8.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.8.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

@@ -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.
 
 ---
 
@@ -109,7 +109,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 +157,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
 
@@ -231,6 +231,19 @@ create_table :event_records do |t|
 end
 ```
 
+Mongoid stores work too:
+
+```ruby
+class EventRecord
+  include Mongoid::Document
+  include Mongoid::Timestamps
+
+  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 +307,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

data/guides/llm/FORM.md

@@ -224,7 +224,7 @@ validates :email, uniqueness: true
 | `model:` | Explicit model class | `uniqueness: { model: User }` |
 | `attribute:` | Column name if different | `uniqueness: { attribute: :email }` |
 | `scope:` | Scoped uniqueness | `uniqueness: { scope: :tenant_id }` |
-| `case_sensitive:` | Case-insensitive check | `uniqueness: { case_sensitive: false }` |
+| `case_sensitive:` | Case-insensitive check (`LOWER()` on ActiveRecord, case-insensitive regex on Mongoid) | `uniqueness: { case_sensitive: false }` |
 | `conditions:` | Extra query conditions | `uniqueness: { conditions: -> { where(active: true) } }` |
 | `message:` | Custom error message | `uniqueness: { message: "already registered" }` |
 
@@ -237,7 +237,7 @@ validates :email, uniqueness: true
 
 ### Record exclusion
 
-When `form.record` is persisted, the current record is excluded from the uniqueness check (for updates).
+When `form.record` is persisted, the current record is excluded from the uniqueness check (for updates) on both ActiveRecord and Mongoid-backed forms.
 
 ---
 

data/guides/llm/OPERATION.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. IDs are treated as strings in JSON Schema – this supports integer PKs, UUIDs, and Mongoid BSON::ObjectId equally.
+Accepts model instances or IDs, coerces IDs via `Model.find(id)`. With `lock: true`, uses `Model.lock.find(id)` (SELECT FOR UPDATE) – requires a model that responds to `.lock` (ActiveRecord). Mongoid documents do not support row locks and raise `ArgumentError` at declaration time. Instances pass through without re-locking. In serialization (recording, async), stores model ID only via `id.as_json`, so Mongoid BSON::ObjectId values are safe in ActiveJob payloads too. IDs are treated as strings in JSON Schema – this supports integer PKs, UUIDs, and Mongoid BSON::ObjectId equally.
 
 Outside the class body (e.g., in tests), use `Dex::RefType.new(Model)` instead of `_Ref(Model)`.
 
@@ -408,11 +408,11 @@ end
 
 ## Transactions
 
-Operations run inside database transactions by default. All changes roll back on error. Nested operations share the outer transaction.
+Operations run inside database transactions when Dex has an active transaction adapter. ActiveRecord is auto-detected. In Mongoid-only apps, no adapter is active, so transactions are automatically disabled – but `after_commit` still works (callbacks fire immediately after success). If you need Mongoid transactions, use `Mongoid.transaction` directly inside `perform`.
 
 ```ruby
 transaction false        # disable
-transaction :mongoid     # adapter override (default: auto-detect AR → Mongoid)
+transaction :active_record  # explicit adapter
 ```
 
 Child classes can re-enable: `transaction true`.
@@ -433,7 +433,7 @@ end
 Callbacks are always deferred — they run after the outermost operation boundary succeeds:
 
 - **Transactional operations:** deferred until the DB transaction commits.
-- **Non-transactional operations:** queued in memory, flushed after the operation pipeline completes successfully.
+- **Non-transactional operations (including Mongoid-only):** queued in memory, flushed after the operation pipeline completes successfully.
 - **Nested operations:** callbacks queue up and flush once at the outermost successful boundary.
 - **On error (`error!` or exception):** queued callbacks are discarded.
 
@@ -441,13 +441,11 @@ Multiple blocks run in registration order.
 
 **ActiveRecord:** requires Rails 7.2+ (`after_all_transactions_commit`).
 
-**Mongoid:** deferred across nested Dex operations. Ambient `Mongoid.transaction` blocks opened outside Dex are not detected — callbacks will fire immediately in that case.
-
 ---
 
 ## Advisory Locking
 
-Mutual exclusion via database advisory locks (requires `with_advisory_lock` gem). Wraps **outside** the transaction.
+Mutual exclusion via database advisory locks (requires `with_advisory_lock` gem). Wraps **outside** the transaction. ActiveRecord-only; Mongoid-only apps get a clear `LoadError`.
 
 ```ruby
 advisory_lock { "pay:#{charge_id}" }    # dynamic key from props
@@ -510,7 +508,17 @@ record result: false      # params only
 record params: false      # result only
 ```
 
-All outcomes are recorded — success (`completed`), business errors (`error`), and exceptions (`failed`). Recording runs outside the operation's own transaction so error records survive its rollbacks. Records still participate in ambient transactions (e.g., an outer operation's transaction). Missing columns silently skipped.
+All outcomes are recorded — success (`completed`), business errors (`error`), and exceptions (`failed`). Recording runs outside the operation's own transaction so error records survive its rollbacks. Records still participate in ambient transactions (e.g., an outer operation's transaction). Dex validates the configured record model before use and raises if required attributes are missing.
+
+Required attributes by feature:
+
+- Core recording: `name`, `status`, `error_code`, `error_message`, `error_details`, `performed_at`
+- Params capture: `params` unless `record params: false`
+- Result capture: `result` unless `record result: false`
+- Async record jobs: `params`
+- `once`: `once_key`, plus `once_key_expires_at` when `expires_in:` is used
+
+Untyped results are sanitized to JSON-safe values before persistence: Hash keys round-trip as strings, and objects fall back to `as_json`/`to_s` under `"_dex_value"`.
 
 Status values: `pending` (async enqueued), `running` (async executing), `completed` (success), `error` (business error via `error!`), `failed` (unhandled exception).
 
@@ -574,7 +582,7 @@ Clearing is idempotent — clearing a non-existent key is a no-op. After clearin
 **Requirements:**
 
 - Record backend must be configured (`Dex.configure { |c| c.record_class = OperationRecord }`)
-- The record table must have `once_key` and `once_key_expires_at` columns (see Recording schema above)
+- The record backend must satisfy the Recording requirements above, and `once` additionally requires `once_key` plus `once_key_expires_at` when `expires_in:` is used
 - `once` cannot be declared with `record false` — raises `ArgumentError`
 - Only one `once` declaration per operation
 
@@ -586,11 +594,10 @@ Clearing is idempotent — clearing a non-existent key is a no-op. After clearin
 # config/initializers/dexkit.rb
 Dex.configure do |config|
   config.record_class = OperationRecord  # model for recording (default: nil)
-  config.transaction_adapter = nil        # auto-detect (default); or :active_record / :mongoid
 end
 ```
 
-All DSL methods validate arguments at declaration time — typos and wrong types raise `ArgumentError` immediately (e.g., `error "string"`, `async priority: 5`, `transaction :redis`).
+All DSL methods validate arguments at declaration time — typos and wrong types raise `ArgumentError` immediately (e.g., `error "string"`, `async priority: 5`, `transaction :redis`). Only `:active_record` is a valid transaction adapter.
 
 ---
 
@@ -598,22 +605,20 @@ All DSL methods validate arguments at declaration time — typos and wrong types
 
 ```ruby
 # test/test_helper.rb
-require "dex/test_helpers"
+require "dex/operation/test_helpers"
 
 class Minitest::Test
-  include Dex::TestHelpers
+  include Dex::Operation::TestHelpers
 end
 ```
 
 Not autoloaded — stays out of production. TestLog and stubs are auto-cleared in `setup`.
 
-For Mongoid-backed operation tests, run against a MongoDB replica set (MongoDB transactions require it).
-
 ### Subject & Execution
 
 ```ruby
 class CreateUserTest < Minitest::Test
-  include Dex::TestHelpers
+  include Dex::Operation::TestHelpers
 
   testing CreateUser  # default for all helpers
 
@@ -778,7 +783,7 @@ Each entry has: `name`, `operation_class`, `params`, `result` (Ok/Err), `duratio
 
 ```ruby
 class CreateUserTest < Minitest::Test
-  include Dex::TestHelpers
+  include Dex::Operation::TestHelpers
 
   testing CreateUser
 

data/guides/llm/QUERY.md

@@ -91,7 +91,7 @@ Reserved prop names: `scope`, `sort`, `resolve`, `call`, `from_params`, `to_para
 | `:in` | `IN (values)` | `filter :roles, :in, column: :role` |
 | `:not_in` | `NOT IN (values)` | `filter :roles, :not_in, column: :role` |
 
-String strategies (`:contains`, `:starts_with`, `:ends_with`) use case-insensitive matching. With ActiveRecord, this uses Arel `matches` (LIKE); with Mongoid, case-insensitive regex. Wildcards in values are auto-sanitized. The adapter is auto-detected from the scope.
+String strategies (`:contains`, `:starts_with`, `:ends_with`) use case-insensitive matching. With ActiveRecord, this uses Arel `matches` (LIKE); with Mongoid, case-insensitive regex. Wildcards in values are auto-sanitized. The adapter is auto-detected from the scope, and Mongoid association scopes/proxies are normalized to `Mongoid::Criteria` automatically.
 
 ### Column Mapping
 
@@ -159,7 +159,7 @@ Only one default per class. Applied when no sort is provided.
 
 ### `.call`
 
-Returns a queryable scope (`ActiveRecord::Relation` or `Mongoid::Criteria`):
+Returns a queryable scope (`ActiveRecord::Relation` or `Mongoid::Criteria`). Association scopes like `current_user.posts` work too:
 
 ```ruby
 users = UserSearch.call(name: "ali", role: %w[admin], sort: "-name")

data/lib/dex/event/bus.rb

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

data/lib/dex/event/test_helpers.rb

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