dexkit 0.9.0 → 0.11.0

data/guides/llm/FORM.md

@@ -10,58 +10,80 @@ All examples below build on this form unless noted otherwise:
 
 ```ruby
 class OnboardingForm < Dex::Form
+  description "Employee onboarding"
   model User
 
-  attribute :first_name, :string
-  attribute :last_name, :string
-  attribute :email, :string
-  attribute :department, :string
-  attribute :start_date, :date
+  field :first_name, :string
+  field :last_name, :string
+  field :email, :string
+  field :department, :string
+  field :start_date, :date
+  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, :department, presence: true
-  validates :start_date, presence: true
+  validates :email, uniqueness: true
 
   nested_one :address do
-    attribute :street, :string
-    attribute :city, :string
-    attribute :postal_code, :string
-    attribute :country, :string
-
-    validates :street, :city, :country, presence: true
+    field :street, :string
+    field :city, :string
+    field :postal_code, :string
+    field :country, :string
+    field? :apartment, :string
   end
 
   nested_many :documents do
-    attribute :document_type, :string
-    attribute :document_number, :string
-
-    validates :document_type, :document_number, presence: true
+    field :document_type, :string
+    field :document_number, :string
   end
 end
 ```
 
 ---
 
-## Defining Forms
+## Declaring Fields
 
-Forms use ActiveModel under the hood. Attributes are declared with `attribute` (same as ActiveModel::Attributes).
+### `field` — required
+
+Declares a required field. Auto-adds presence validation. Unconditional `validates :attr, presence: true` deduplicates with it; scoped or conditional presence validators do not make the field optional outside those cases.
 
 ```ruby
-class ProfileForm < Dex::Form
-  attribute :name, :string
-  attribute :age, :integer
-  attribute :bio, :string
-  attribute :active, :boolean, default: true
-  attribute :born_on, :date
-end
+field :name, :string
+field :email, :string, desc: "Work email"
+field :currency, :string, default: "USD"
+```
+
+### `field?` — optional
+
+Declares an optional field. Defaults to `nil` unless overridden.
+
+```ruby
+field? :notes, :string
+field? :priority, :integer, default: 0
 ```
 
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `desc:` | Human-readable description (for introspection and JSON Schema) |
+| `default:` | Default value (forwarded to ActiveModel) |
+
 ### Available types
 
 `:string`, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`, `:time`.
 
+### `attribute` escape hatch
+
+Raw ActiveModel `attribute` is still available. Not tracked in field registry, no auto-presence, not in exports.
+
+### Boolean fields
+
+`field :active, :boolean` checks for `nil` (not `blank?`), so `false` is valid.
+
 ### `model(klass)`
 
 Declares the backing model class. Used by:
@@ -93,11 +115,11 @@ normalizes :name, :email, with: -> { _1&.strip.presence }   # multiple attrs
 
 ## Validation
 
-Full ActiveModel validation DSL:
+Full ActiveModel validation DSL. Required fields auto-validate presence — no need to add `validates :name, presence: true` when using `field :name, :string`.
 
 ```ruby
-validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
-validates :name, presence: true, length: { minimum: 2, maximum: 100 }
+validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+validates :name, length: { minimum: 2, maximum: 100 }
 validates :role, inclusion: { in: %w[admin user] }
 validates :email, uniqueness: true                    # checks database
 validate :custom_validation_method
@@ -111,6 +133,15 @@ form.errors[:email]      # => ["can't be blank"]
 form.errors.full_messages # => ["Email can't be blank"]
 ```
 
+### Contextual requirements
+
+Use `field?` with an explicit validation context:
+
+```ruby
+field? :published_at, :datetime
+validates :published_at, presence: true, on: :publish
+```
+
 ### ValidationError
 
 ```ruby
@@ -121,6 +152,94 @@ error.form     # => the form instance
 
 ---
 
+## Ambient Context
+
+Auto-fill fields from `Dex.context` – same DSL as Operation and Event:
+
+```ruby
+class Order::Form < Dex::Form
+  field :locale, :string
+  field :currency, :string
+
+  context :locale                       # shorthand: field name = context key
+  context currency: :default_currency   # explicit: field name → context key
+end
+
+Dex.with_context(locale: "en", default_currency: "USD") do
+  form = Order::Form.new
+  form.locale    # => "en"
+  form.currency  # => "USD"
+end
+```
+
+Explicit values always win. Context references must point to declared fields or attributes.
+
+---
+
+## Registry & Export
+
+### Description
+
+```ruby
+class OnboardingForm < Dex::Form
+  description "Employee onboarding"
+end
+
+OnboardingForm.description  # => "Employee onboarding"
+```
+
+### Registry
+
+```ruby
+Dex::Form.registry  # => #<Set: {OnboardingForm, ...}>
+```
+
+### Class-level `to_h`
+
+```ruby
+OnboardingForm.to_h
+# => {
+#   name: "OnboardingForm",
+#   description: "Employee onboarding",
+#   fields: {
+#     first_name: { type: :string, required: true },
+#     email: { type: :string, required: true },
+#     notes: { type: :string, required: false },
+#     ...
+#   },
+#   nested: {
+#     address: { type: :one, fields: { ... }, nested: { ... } },
+#     documents: { type: :many, fields: { ... } }
+#   }
+# }
+```
+
+### `to_json_schema`
+
+```ruby
+OnboardingForm.to_json_schema
+# => {
+#   "$schema": "https://json-schema.org/draft/2020-12/schema",
+#   type: "object",
+#   title: "OnboardingForm",
+#   description: "Employee onboarding",
+#   properties: { email: { type: "string" }, ... },
+#   required: ["first_name", "last_name", "email", ...],
+#   additionalProperties: false
+# }
+```
+
+### Global export
+
+```ruby
+Dex::Form.export(format: :json_schema)
+# => [{ ... OnboardingForm schema ... }, ...]
+```
+
+Bulk export returns top-level named forms only. Nested helper classes generated by `nested_one` and `nested_many` stay embedded in their parent export instead of appearing as separate entries.
+
+---
+
 ## Nested Forms
 
 ### `nested_one`
@@ -129,9 +248,9 @@ One-to-one nested form. Automatically coerces Hash input.
 
 ```ruby
 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
 ```
 
@@ -152,9 +271,8 @@ One-to-many nested form. Handles Array, Rails numbered Hash, and `_destroy`.
 
 ```ruby
 nested_many :documents do
-  attribute :document_type, :string
-  attribute :document_number, :string
-  validates :document_type, :document_number, presence: true
+  field :document_type, :string
+  field :document_number, :string
 end
 ```
 
@@ -190,7 +308,7 @@ Override the auto-generated constant name:
 
 ```ruby
 nested_one :address, class_name: "HomeAddress" do
-  attribute :street, :string
+  field :street, :string
 end
 # Creates MyForm::HomeAddress instead of MyForm::Address
 ```
@@ -306,7 +424,7 @@ form.to_hash  # alias for to_h
 
 ### Controller pattern
 
-Strong parameters (`permit`) are not required — the form's attribute declarations are the whitelist. Just `require` the top-level key:
+Strong parameters (`permit`) are not required — the form's field declarations are the whitelist. Just `require` the top-level key:
 
 ```ruby
 class OnboardingController < ApplicationController
@@ -405,33 +523,34 @@ A form spanning User, Employee, and Address — the core reason form objects exi
 
 ```ruby
 class OnboardingForm < Dex::Form
-  attribute :first_name, :string
-  attribute :last_name, :string
-  attribute :email, :string
-  attribute :department, :string
-  attribute :position, :string
-  attribute :start_date, :date
+  description "Employee onboarding"
+
+  field :first_name, :string
+  field :last_name, :string
+  field :email, :string
+  field :department, :string
+  field :position, :string
+  field :start_date, :date
+  field :locale, :string
+  field? :notes, :string
+
+  context :locale
 
   normalizes :email, with: -> { _1&.strip&.downcase.presence }
 
-  validates :email, presence: true, uniqueness: { model: User }
-  validates :first_name, :last_name, :department, :position, presence: true
-  validates :start_date, presence: true
+  validates :email, uniqueness: { model: User }
 
   nested_one :address do
-    attribute :street, :string
-    attribute :city, :string
-    attribute :postal_code, :string
-    attribute :country, :string
-
-    validates :street, :city, :country, presence: true
+    field :street, :string
+    field :city, :string
+    field :postal_code, :string
+    field :country, :string
+    field? :apartment, :string
   end
 
   nested_many :documents do
-    attribute :document_type, :string
-    attribute :document_number, :string
-
-    validates :document_type, :document_number, presence: true
+    field :document_type, :string
+    field :document_number, :string
   end
 
   def self.for(user)
@@ -484,23 +603,38 @@ Forms are standard ActiveModel objects. Test them with plain Minitest — no spe
 
 ```ruby
 class OnboardingFormTest < Minitest::Test
-  def test_validates_required_fields
+  def test_required_fields_validated
     form = OnboardingForm.new
     assert form.invalid?
     assert form.errors[:email].any?
     assert form.errors[:first_name].any?
   end
 
+  def test_optional_fields_allowed_blank
+    form = OnboardingForm.new(
+      first_name: "Alice", last_name: "Smith",
+      email: "alice@example.com", department: "Eng",
+      position: "Dev", start_date: Date.today, locale: "en"
+    )
+    assert form.valid?
+    assert_nil form.notes
+  end
+
   def test_normalizes_email
     form = OnboardingForm.new(email: "  ALICE@EXAMPLE.COM  ")
     assert_equal "alice@example.com", form.email
   end
 
+  def test_context_fills_locale
+    form = Dex.with_context(locale: "en") { OnboardingForm.new }
+    assert_equal "en", form.locale
+  end
+
   def test_nested_validation_propagation
     form = OnboardingForm.new(
       first_name: "Alice", last_name: "Smith",
       email: "alice@example.com", department: "Eng",
-      position: "Developer", start_date: Date.today,
+      position: "Developer", start_date: Date.today, locale: "en",
       address: { street: "", city: "", country: "" }
     )
     assert form.invalid?
@@ -516,5 +650,12 @@ class OnboardingFormTest < Minitest::Test
     assert_equal "Alice", h[:first_name]
     assert_equal "123 Main", h[:address][:street]
   end
+
+  def test_json_schema_export
+    schema = OnboardingForm.to_json_schema
+    assert_equal "object", schema[:type]
+    assert_includes schema[:required], "first_name"
+    refute_includes schema[:required], "notes"
+  end
 end
 ```

data/guides/llm/OPERATION.md

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