dexkit 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a120052500fd0c1889117f87d0d4260b40eecbc82b31ad50b9e6fc97f99efd9
-  data.tar.gz: f140a685dd0825fbd675f5575d1a44d5679598ad7a2d302a65a3f22bae268ce0
+  metadata.gz: 34e5457c2e95efc96b2350babe7d7059854caa42ce6da92087e003f76acfb6d8
+  data.tar.gz: cf0466311827f2706fe883167b88d27a2571029c029777a1a5f37e0f44ae080a
 SHA512:
-  metadata.gz: f2186829d67bb0c19d71e9a81021a94efc56cb90dc943d11ad62a9306833ed08183691eb3196fc8dec950dcd3e7a624be5e67eda00abb3e74a444404b7947267
-  data.tar.gz: 5314488039b706abbbf68bc3ca7fb3e2445718286a2b21ce7346dfae60f8cdb5ca68f89369b3b54fe1a756826e95a76f22bac973d75494a10c4605e8210e1d94
+  metadata.gz: 3885a4464112b937aa88bd2661ad03aca35af5128ba9b292c7345fccd69bbd8c53a363d5f1805c0c2173c097ff06f8f98ec7fc657115fd530b84a910af9b5759
+  data.tar.gz: 25ce509ae466f259b102b4eedb8d828eb27435d6223bd052c87682b60b43584a6ccaf223ed0bec3f2141988fadebaac4638a204c4025554870e70c389ac9d4e2

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 ## [Unreleased]
 
+## [0.7.0] - 2026-03-08
+
+### Breaking
+
+- **Operation record schema refactored** — the `response` column is renamed to `result`, the `error` column is split into `error_code`, `error_message`, and `error_details`, `params` no longer has `default: {}` (nil means "not captured"), and `status` is now `null: false`. The `record response: false` DSL option is now `record result: false`. Status value `done` is renamed to `completed`, and a new `error` status represents business errors via `error!`
+- **All outcomes now recorded** — previously, only successful operations were recorded in the sync path. Now business errors (`error!`) record with status `error` and populate `error_code`/`error_message`/`error_details`, and unhandled exceptions record with status `failed`
+- **Recording moved outside transaction** — operation records are now persisted outside the database transaction, so error and failure records survive rollbacks. Previously, records were created inside the transaction and would be rolled back alongside the operation's side effects
+- **Pipeline order changed** — `RecordWrapper` now runs before `TransactionWrapper` (was after). The pipeline order is now: result → once → lock → record → transaction → rescue → guard → callback
+- **`Operation.contract` shape changed** — `Contract` gains a fourth field `:guards`. Code using positional destructuring (`in Contract[params, success, errors]`) must be updated to include the new field. Keyword-based access (`.params`, `.errors`, etc.) is unaffected
+
+### Added
+
+- **Ambient context** — `Dex.with_context(current_user: user) { ... }` sets fiber-local ambient state. The `context` DSL on operations and events maps props to ambient keys, auto-filling them when not passed explicitly. Explicit kwargs always win. Works with guards (`callable?`), events (captured at publish time), and nested operations. Introspection via `context_mappings`
+- **`guard` DSL for precondition checks** — named, inline preconditions that detect threats (conditions under which the operation should not proceed). Guards auto-declare error codes, support dependencies (`requires:`), collect all independent failures, and skip dependent guards when a dependency fails. `callable?` and `callable` class methods check guards without running `perform` – useful for UI show/hide, disabled buttons with reasons, and API pre-validation. Contract introspection via `contract.guards`. Test helpers: `assert_callable`, `refute_callable`
+- **`once` DSL for operation idempotency** — ensures an operation executes at most once for a given key, replaying stored results on subsequent calls. Supports prop-based keys (`once :order_id`), composite keys, block-based custom keys, call-site keys (`.once("key")`), optional expiry (`expires_in:`), and `clear_once!` for key management. Business errors are replayed; exceptions release the key for retry. Works with `.safe.call` and `.async.call`
+- **`error_code`, `error_message`, `error_details` columns** — structured error recording replaces the single `error` string column
+- **Recommended indexes** — `name`, `status`, `[:name, :status]` composite index, and unique partial index on `once_key` in the migration schema
+
+## [0.6.0] - 2026-03-07
+
+### Added
+
+- **Handler callbacks** — `Dex::Event::Handler` now supports `before`, `after`, and `around` callbacks, same DSL as operations
+- **Handler transactions** — `Dex::Event::Handler` supports `transaction` and `after_commit` DSL. Transactions are disabled by default on handlers (opt in with `transaction`)
+- **Handler pipeline** — `Dex::Event::Handler` supports `use` for adding custom wrapper modules, same as operations
+- **`Dex::Executable`** — shared execution skeleton (Settings, Pipeline, `use` DSL) extracted from Operation and used by both Operation and Handler
+
+### Breaking
+
+- **`transaction false` fully opts out** — operations with `transaction false` no longer route `after_commit` through the database adapter. Previously, `after_commit` on a non-transactional operation would still detect and defer to ambient database transactions (e.g., `ActiveRecord::Base.transaction { op.call }`); now it fires callbacks directly after the pipeline completes. To restore ambient transaction awareness, remove `transaction false` or use `transaction` (enabled)
+
 ## 0.5.0 - 2026-03-05
 
 ### Added

data/README.md

@@ -1,4 +1,4 @@
-# Dexkit
+# dexkit
 
 Rails patterns toolbelt. Equip to gain +4 DEX.
 
@@ -69,6 +69,69 @@ end
 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:
+
+```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
+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)
+```
+
+**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)
+```
+
 **Transactions** on by default, **advisory locking**, **recording** to database, **callbacks**, and a customizable **pipeline** – all composable, all optional.
 
 ### Testing
@@ -127,6 +190,10 @@ order_placed.trace do
 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
@@ -259,7 +326,7 @@ Full documentation at **[dex.razorjack.net](https://dex.razorjack.net)**.
 
 ## AI Coding Assistant Setup
 
-Dexkit ships LLM-optimized guides. Copy them into your project so AI agents automatically know the API:
+dexkit ships LLM-optimized guides. Copy them into your project so AI agents automatically know the API:
 
 ```bash
 cp $(bundle show dexkit)/guides/llm/OPERATION.md app/operations/CLAUDE.md

data/guides/llm/EVENT.md

@@ -111,6 +111,70 @@ end
 
 When retries exhausted, exception propagates normally.
 
+### Callbacks
+
+Same `before`/`after`/`around` DSL as operations:
+
+```ruby
+class ProcessPayment < Dex::Event::Handler
+  on PaymentReceived
+
+  before :log_start
+  after :log_end
+
+  around ->(cont) {
+    Instrumentation.measure("payment") { cont.call }
+  }
+
+  def perform
+    PaymentGateway.charge(event.amount)
+  end
+
+  private
+
+  def log_start = Rails.logger.info("Processing payment...")
+  def log_end = Rails.logger.info("Payment processed")
+end
+```
+
+Callbacks are inherited. Child handlers run parent callbacks first.
+
+### Transactions
+
+Handlers can opt into database transactions and deferred `after_commit`:
+
+```ruby
+class FulfillOrder < Dex::Event::Handler
+  on OrderPlaced
+  transaction
+
+  def perform
+    order = Order.find(event.order_id)
+    order.update!(status: "fulfilled")
+
+    after_commit { Shipment::Ship.new(order_id: order.id).async.call }
+  end
+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.
+
+### Custom Pipeline
+
+Handlers support the same `use` DSL as operations for adding custom wrappers:
+
+```ruby
+class Monitored < Dex::Event::Handler
+  use MetricsWrapper, as: :metrics
+
+  def perform
+    # ...
+  end
+end
+```
+
+Default handler pipeline: `[:transaction, :callback]`.
+
 ---
 
 ## Tracing (Causality)
@@ -171,21 +235,43 @@ Persistence failures are silently rescued — they never halt event publishing.
 
 ---
 
-## Context (Optional)
+## Ambient Context
 
-Capture ambient context (current user, tenant, etc.) at publish time:
+Events use the same `context` DSL as operations. Context-mapped props are captured at **publish time** and stored as regular props on the event — handlers don't need ambient context, they read from the event.
 
 ```ruby
-Dex.configure do |c|
-  c.event_context = -> { { user_id: Current.user&.id, tenant: Current.tenant } }
-  c.restore_event_context = ->(ctx) {
-    Current.user = User.find(ctx["user_id"]) if ctx["user_id"]
-    Current.tenant = ctx["tenant"]
-  }
+class Order::Placed < Dex::Event
+  prop :order_id, Integer
+  prop :customer, _Ref(Customer)
+  context customer: :current_customer   # resolved at publish time
+end
+
+# In a controller with Dex.with_context(current_customer: customer):
+Order::Placed.publish(order_id: 1)   # customer auto-filled from context
+
+# Or pass explicitly:
+Order::Placed.publish(order_id: 1, customer: customer)
+```
+
+Handlers receive the event with everything already set — no `context` needed on handlers:
+
+```ruby
+class AuditTrail < Dex::Event::Handler
+  on Order::Placed
+
+  def perform
+    AuditLog.create!(customer: event.customer, action: "placed", order_id: event.order_id)
+  end
 end
 ```
 
-Context is stored in event metadata and restored before async handler execution.
+**Resolution order:** explicit kwarg → ambient context → prop default → TypeError.
+
+**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.
 
 ---
 

data/guides/llm/OPERATION.md

@@ -11,7 +11,7 @@ All examples below build on this operation unless noted otherwise:
 ```ruby
 class CreateUser < Dex::Operation
   prop :email, String
-  prop :name,  String
+  prop :name, String
   prop? :role, _Union("admin", "member"), default: "member"
 
   success _Ref(User)
@@ -36,9 +36,10 @@ end
 CreateUser.call(email: "a@b.com", name: "Alice")            # shorthand for new(...).call
 CreateUser.new(email: "a@b.com", name: "Alice").safe.call    # Ok/Err wrapper
 CreateUser.new(email: "a@b.com", name: "Alice").async.call   # background job
+CreateUser.new(email: "a@b.com", name: "Alice").once("key").call  # call-site idempotency
 ```
 
-Use `new(...)` form when chaining modifiers (`.safe`, `.async`).
+Use `new(...)` form when chaining modifiers (`.safe`, `.async`, `.once`).
 
 ---
 
@@ -63,33 +64,33 @@ Types use `===` for validation. All constructors available in the operation clas
 | `_Ref(Model)` | Model reference | `_Ref(User)`, `_Ref(Account, lock: true)` |
 
 ```ruby
-prop :name,     String                       # any String
-prop :count,    Integer                      # any Integer
-prop :amount,   Float                        # any Float
-prop :amount,   BigDecimal                   # any BigDecimal
-prop :data,     Hash                         # any Hash
-prop :items,    Array                        # any Array
-prop :active,   _Boolean                     # true or false
-prop :role,     Symbol                       # any Symbol
-prop :count,    _Integer(1..)                # Integer >= 1
-prop :count,    _Integer(0..100)             # Integer 0–100
-prop :name,     _String(length: 1..255)      # String with length constraint
-prop :score,    _Float(0.0..1.0)             # Float in range
-prop :tags,     _Array(String)               # Array of Strings
-prop :ids,      _Array(Integer)              # Array of Integers
-prop :matrix,   _Array(_Array(Integer))      # nested typed arrays
+prop :name, String                       # any String
+prop :count, Integer                      # any Integer
+prop :amount, Float                        # any Float
+prop :amount, BigDecimal                   # any BigDecimal
+prop :data, Hash                         # any Hash
+prop :items, Array                        # any Array
+prop :active, _Boolean                     # true or false
+prop :role, Symbol                       # any Symbol
+prop :count, _Integer(1..)                # Integer >= 1
+prop :count, _Integer(0..100)             # Integer 0–100
+prop :name, _String(length: 1..255)      # String with length constraint
+prop :score, _Float(0.0..1.0)             # Float in range
+prop :tags, _Array(String)               # Array of Strings
+prop :ids, _Array(Integer)              # Array of Integers
+prop :matrix, _Array(_Array(Integer))      # nested typed arrays
 prop :currency, _Union("USD", "EUR", "GBP")  # enum of values
-prop :id,       _Union(String, Integer)      # union of types
-prop :label,    _Nilable(String)             # String or nil
-prop :meta,     _Hash(Symbol, String)        # Hash with typed keys+values
-prop :pair,     _Tuple(String, Integer)      # fixed-size typed array
-prop :name,     _Frozen(String)              # must be frozen
-prop :handler,  _Callable                    # anything responding to .call
-prop :handler,  _Interface(:call, :arity)    # responds to listed methods
-prop :user,     _Ref(User)                   # Dex-specific: model by instance or ID
-prop :account,  _Ref(Account, lock: true)    # Dex-specific: with row lock
-prop :title,    String, default: "Untitled"  # default value
-prop? :note,    String                       # optional (nilable, default: nil)
+prop :id, _Union(String, Integer)      # union of types
+prop :label, _Nilable(String)             # String or nil
+prop :meta, _Hash(Symbol, String)        # Hash with typed keys+values
+prop :pair, _Tuple(String, Integer)      # fixed-size typed array
+prop :name, _Frozen(String)              # must be frozen
+prop :handler, _Callable                    # anything responding to .call
+prop :handler, _Interface(:call, :arity)    # responds to listed methods
+prop :user, _Ref(User)                   # Dex-specific: model by instance or ID
+prop :account, _Ref(Account, lock: true)    # Dex-specific: with row lock
+prop :title, String, default: "Untitled"  # default value
+prop? :note, String                       # optional (nilable, default: nil)
 ```
 
 ### _Ref(Model)
@@ -118,7 +119,118 @@ error :email_taken, :invalid_email
 
 Both inherit from parent class. Without `error` declaration, any code is accepted.
 
-**Introspection:** `MyOp.contract` returns a frozen `Data` with `params`, `success`, `errors` fields. Supports pattern matching and `to_h`.
+**Introspection:** `MyOp.contract` returns a frozen `Data` with `params`, `success`, `errors`, `guards` fields. Supports pattern matching and `to_h`.
+
+---
+
+## Ambient Context
+
+Map props to ambient context keys so they auto-fill from `Dex.with_context` when not passed explicitly. Explicit kwargs always win.
+
+```ruby
+class Order::Place < Dex::Operation
+  prop :product, _Ref(Product)
+  prop :customer, _Ref(Customer)
+  prop :locale, Symbol
+
+  context customer: :current_customer   # prop :customer ← Dex.context[:current_customer]
+  context :locale                       # shorthand: prop :locale ← Dex.context[:locale]
+end
+```
+
+**Setting context** (controller, middleware):
+
+```ruby
+Dex.with_context(current_customer: customer, locale: I18n.locale) do
+  Order::Place.call(product: product)   # customer + locale auto-filled
+end
+```
+
+**Resolution order:** explicit kwarg → ambient context → prop default → TypeError (if required).
+
+**In tests** — just pass everything explicitly. No `Dex.with_context` needed:
+
+```ruby
+Order::Place.call(product: product, customer: customer, locale: :en)
+```
+
+**Nesting** supported — inner blocks merge with outer, restore on exit. Nested operations inherit the same ambient context.
+
+**Works with guards** — context-mapped props are available in guard blocks and `callable?`:
+
+```ruby
+Dex.with_context(current_customer: customer) do
+  Order::Place.callable?(product: product)
+end
+```
+
+**Works with optional props** (`prop?`) — if ambient context has the key, it fills in. If not, the prop is nil.
+
+**Introspection:** `MyOp.context_mappings` returns `{ customer: :current_customer, locale: :locale }`.
+
+**DSL validation:** `context user: :current_user` raises `ArgumentError` if no `prop :user` has been declared. Context declarations must come after the props they reference.
+
+---
+
+## Guards
+
+Inline precondition checks. The guard name is the error code, the block detects the **threat** (truthy = threat detected = operation fails):
+
+```ruby
+class PublishPost < Dex::Operation
+  prop :post, _Ref(Post)
+  prop :user, _Ref(User)
+
+  guard :unauthorized, "Only the author or admins can publish" do
+    !user.admin? && post.author != user
+  end
+
+  guard :already_published, "Post must be in draft state" do
+    post.published?
+  end
+
+  def perform
+    post.update!(published_at: Time.current)
+    post
+  end
+end
+```
+
+- Guards run in declaration order, before `perform`, after `rescue`
+- All independent guards run – failures are collected, not short-circuited
+- Guard names are auto-declared as error codes (no separate `error :unauthorized` needed)
+- Same error code usable with `error!` in `perform`
+
+**Dependencies:** skip dependent guards when a dependency fails:
+
+```ruby
+guard :missing_author, "Author must be present" do
+  author.blank?
+end
+
+guard :unpaid_author, "Author must be a paid subscriber", requires: :missing_author do
+  author.free_plan?
+end
+```
+
+If author is nil: only `:missing_author` is reported. `:unpaid_author` is skipped.
+
+**Introspection** – check guards without running `perform`:
+
+```ruby
+PublishPost.callable?(post: post, user: user)           # => true/false
+PublishPost.callable?(:unauthorized, post: post, user: user) # check specific guard
+result = PublishPost.callable(post: post, user: user)   # => Ok or Err with details
+result.details  # => [{ guard: :unauthorized, message: "..." }, ...]
+```
+
+`callable` bypasses the pipeline – no locks, transactions, recording, or callbacks. Cheap and side-effect-free.
+
+**Contract:** `contract.guards` returns guard metadata. `contract.errors` includes guard codes.
+
+**Inheritance:** parent guards run first, child guards appended.
+
+**DSL validation:** code must be Symbol, block required, `requires:` must reference previously declared guards, duplicates raise `ArgumentError`.
 
 ---
 
@@ -154,13 +266,13 @@ begin
   CreateUser.call(email: "bad", name: "A")
 rescue Dex::Error => e
   case e
-  in {code: :not_found} then handle_not_found
-  in {code: :validation_failed, details: {field:}} then handle_field(field)
+  in { code: :not_found } then handle_not_found
+  in { code: :validation_failed, details: { field: } } then handle_field(field)
   end
 end
 ```
 
-**Key differences:** `error!`/`assert!` roll back transaction, skip `after` callbacks and recording. `success!` commits, runs `after` callbacks, records normally.
+**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`).
 
 ---
 
@@ -187,7 +299,7 @@ result.value!  # re-raises Dex::Error
 
 ```ruby
 case CreateUser.new(email: "a@b.com", name: "Alice").safe.call
-in Dex::Ok(name:)               then puts "Created #{name}"
+in Dex::Ok(name:) then puts "Created #{name}"
 in Dex::Err(code: :email_taken) then puts "Already exists"
 end
 ```
@@ -202,10 +314,10 @@ Map exceptions to structured `Dex::Error` codes — eliminates begin/rescue boil
 
 ```ruby
 class ChargeCard < Dex::Operation
-  rescue_from Stripe::CardError,                  as: :card_declined
-  rescue_from Stripe::RateLimitError,             as: :rate_limited
+  rescue_from Stripe::CardError, as: :card_declined
+  rescue_from Stripe::RateLimitError, as: :rate_limited
   rescue_from Net::OpenTimeout, Net::ReadTimeout, as: :timeout
-  rescue_from Stripe::APIError,                   as: :provider_error, message: "Stripe is down"
+  rescue_from Stripe::APIError, as: :provider_error, message: "Stripe is down"
 
   def perform
     Stripe::Charge.create(amount: amount, source: token)
@@ -226,7 +338,7 @@ end
 class ProcessOrder < Dex::Operation
   before :validate_stock            # symbol → instance method
   before -> { log("starting") }     # lambda (instance_exec'd)
-  after  :send_confirmation         # runs after successful perform
+  after :send_confirmation         # runs after successful perform
   around :with_timing               # wraps everything, must yield
 
   def validate_stock
@@ -327,27 +439,99 @@ Record execution to database. Requires `Dex.configure { |c| c.record_class = Ope
 
 ```ruby
 create_table :operation_records do |t|
-  t.string   :name           # Required: operation class name
-  t.jsonb    :params         # Optional: serialized props
-  t.jsonb    :response       # Optional: serialized result
-  t.string   :status         # Optional: pending/running/done/failed (for async)
-  t.string   :error          # Optional: error code on failure
-  t.datetime :performed_at   # Optional
+  t.string :name, null: false  # operation class name
+  t.jsonb :params              # serialized props (nil = not captured)
+  t.jsonb :result              # serialized return value
+  t.string :status, null: false # pending/running/completed/error/failed
+  t.string :error_code          # Dex::Error code or exception class
+  t.string :error_message       # human-readable message
+  t.jsonb :error_details       # structured details hash
+  t.string :once_key            # idempotency key (used by `once`)
+  t.datetime :once_key_expires_at # key expiry (used by `once`)
+  t.datetime :performed_at        # execution completion timestamp
   t.timestamps
 end
+
+add_index :operation_records, :name
+add_index :operation_records, :status
+add_index :operation_records, [:name, :status]
 ```
 
 Control per-operation:
 
 ```ruby
 record false              # disable entirely
-record response: false    # params only
-record params: false      # response only
+record result: false      # params only
+record params: false      # result only
 ```
 
-Recording happens inside the transaction — rolled back on `error!`/`assert!`. 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). Missing columns silently skipped.
+
+Status values: `pending` (async enqueued), `running` (async executing), `completed` (success), `error` (business error via `error!`), `failed` (unhandled exception).
 
-When both async and recording are enabled, Dexkit automatically stores only the record ID in the job payload instead of full params. The record tracks `status` (pending → running → done/failed) and `error` (code or exception class name).
+When both async and recording are enabled, dexkit automatically stores only the record ID in the job payload instead of full params.
+
+---
+
+## Idempotency (once)
+
+Prevent duplicate execution with `once`. Requires recording to be configured (uses the record backend to store and look up idempotency keys).
+
+**Class-level declaration:**
+
+```ruby
+class ChargeOrder < Dex::Operation
+  prop :order_id, Integer
+  once :order_id                              # key: "ChargeOrder/order_id=123"
+
+  def perform
+    Stripe::Charge.create(amount: order.total)
+  end
+end
+```
+
+Key forms:
+
+```ruby
+once :order_id                                # single prop → "ClassName/order_id=1"
+once :merchant_id, :plan_id                   # composite  → "ClassName/merchant_id=1/plan_id=2" (sorted)
+once                                          # bare — all props as key
+once { "payment-#{order_id}" }                # block — custom key (no auto scoping)
+once :user_id, expires_in: 24.hours           # key expires after duration
+```
+
+**Call-site key** — override or add idempotency at the call site:
+
+```ruby
+MyOp.new(payload: "data").once("webhook-123").call   # explicit key
+MyOp.new(order_id: 1).once(nil).call                 # bypass once guard entirely
+```
+
+Works without a class-level `once` declaration — useful for one-off idempotency from controllers or jobs.
+
+**Replay behavior:**
+
+- Success results and business errors (`error!`) are replayed from the stored record. The operation does not re-execute.
+- Unhandled exceptions release the key — the next call retries normally.
+- Works with `.safe.call` (replays as `Ok`/`Err`) and `.async.call`.
+
+**Clearing keys:**
+
+```ruby
+ChargeOrder.clear_once!(order_id: 1)      # by prop values (builds scoped key)
+ChargeOrder.clear_once!("webhook-123")    # by raw string key
+```
+
+Clearing is idempotent — clearing a non-existent key is a no-op. After clearing, the next call executes normally.
+
+**Pipeline position:** result → **once** → lock → record → transaction → rescue → guard → callback. The once check runs before locking and recording, so duplicate calls short-circuit early.
+
+**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)
+- `once` cannot be declared with `record false` — raises `ArgumentError`
+- Only one `once` declaration per operation
 
 ---
 
@@ -390,7 +574,7 @@ class CreateUserTest < Minitest::Test
 
   def test_example
     result = call_operation(email: "a@b.com", name: "Alice")   # => Ok or Err (safe)
-    value  = call_operation!(email: "a@b.com", name: "Alice")  # => raw value or raises
+    value = call_operation!(email: "a@b.com", name: "Alice")  # => raw value or raises
   end
 end
 ```
@@ -445,6 +629,17 @@ assert_contract(
 )
 ```
 
+### Guard Assertions
+
+```ruby
+assert_callable(post: post, user: user)                          # all guards pass
+assert_callable(PublishPost, post: post, user: user)             # explicit class
+refute_callable(:unauthorized, post: post, user: user)           # specific guard fails
+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.
+
 ### Param Validation
 
 ```ruby
@@ -526,7 +721,9 @@ Global log of all operation calls:
 Dex::TestLog.calls                               # all entries
 Dex::TestLog.find(CreateUser)                    # filter by class
 Dex::TestLog.find(CreateUser, email: "a@b.com")  # filter by class + params
-Dex::TestLog.size; Dex::TestLog.empty?; Dex::TestLog.clear!
+Dex::TestLog.size
+Dex::TestLog.empty?
+Dex::TestLog.clear!
 Dex::TestLog.summary                             # human-readable for failure messages
 ```