dexkit 0.6.0 → 0.8.0

data/guides/llm/OPERATION.md

@@ -1,6 +1,6 @@
 # Dex::Operation — LLM Reference
 
-Copy this to your app's operations directory (e.g., `app/operations/AGENTS.md`) so coding agents know the full API when implementing and testing operations.
+Install with `rake dex:guides` or copy manually to `app/operations/AGENTS.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,38 +64,38 @@ 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)
 
-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.
+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.
 
 Outside the class body (e.g., in tests), use `Dex::RefType.new(Model)` instead of `_Ref(Model)`.
 
@@ -118,7 +119,163 @@ 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`.
+
+---
+
+## Explain
+
+Full preflight check — resolves context, coerces props, evaluates guards, computes derived keys, reports settings. No side effects, `perform` never runs.
+
+```ruby
+info = Order::Place.explain(product: product, customer: customer, quantity: 2)
+```
+
+Returns a frozen Hash:
+
+```ruby
+info = Order::Place.explain(product: product, customer: customer, quantity: 2)
+# => {
+#   operation: "Order::Place",
+#   props: { product: #<Product>, customer: #<Customer>, quantity: 2 },
+#   context: {
+#     resolved: { customer: #<Customer> },
+#     mappings: { customer: :current_customer },
+#     source: { customer: :ambient }   # :ambient, :explicit, or :default
+#   },
+#   guards: {
+#     passed: true,
+#     results: [{ name: :out_of_stock, passed: true }, ...]
+#   },
+#   once: { active: true, key: "Order::Place/product_id=7", status: :fresh, expires_in: nil },
+#   lock: { active: true, key: "order:7", timeout: nil },
+#   record: { enabled: true, params: true, result: true },
+#   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],
+#   callable: true
+# }
+```
+
+- Invalid props (`Literal::TypeError`, `ArgumentError`) return a partial result with `info[:error]` — class-level info still available, instance-dependent sections degrade to empty/nil. Static lock keys preserved. Context source uses `:missing` for props without defaults. Other errors propagate normally
+- `info[:callable]` is a full preflight verdict — checks guards AND once blocking statuses; always `false` when props are invalid
+- Once status: `:fresh` (new), `:exists` (would replay), `:expired`, `:pending` (in-flight), `:invalid` (nil key), `:misconfigured` (anonymous op, missing record step, missing column), `:unavailable` (no backend)
+- Guard results include `message:` on failures and `skipped: true` when a guard was skipped via `requires:` dependency
+- Custom middleware can contribute via `_name_explain(instance, info)` class methods
+
+**Use cases:** console debugging, admin tooling, LLM agent preflight, test assertions.
 
 ---
 
@@ -154,13 +311,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 +344,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 +359,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 +383,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 +484,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.
+
+---
+
+## 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.
 
-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).
+**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 +619,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 +674,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 +766,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
 ```
 
@@ -583,4 +825,63 @@ end
 
 ---
 
+## Registry, Export & Description
+
+### Description
+
+Operations can declare a human-readable description. Props can include `desc:`:
+
+```ruby
+class Order::Place < Dex::Operation
+  description "Places a new order, charges payment, and schedules fulfillment"
+
+  prop :product, _Ref(Product), desc: "Product to order"
+  prop :quantity, _Integer(1..), desc: "Number of units"
+end
+```
+
+Descriptions appear in `contract.to_h`, `to_json_schema`, `explain`, and LLM tool definitions.
+
+### Registry
+
+```ruby
+Dex::Operation.registry          # => #<Set: {Order::Place, Order::Cancel, ...}>
+Dex::Operation.deregister(klass) # remove from registry (useful in tests)
+Dex::Operation.clear!            # empty the registry
+```
+
+Only named, reachable classes are included. Anonymous classes and stale objects from code reloads are excluded. Populates lazily via `inherited` — in Rails, `eager_load!` to get the full list.
+
+### Export
+
+```ruby
+Order::Place.contract.to_h
+# => { name: "Order::Place", description: "...", params: { product: { type: "Ref(Product)", required: true, desc: "..." } }, ... }
+
+Order::Place.contract.to_json_schema                    # params input schema (default)
+Order::Place.contract.to_json_schema(section: :success) # success return schema
+Order::Place.contract.to_json_schema(section: :errors)  # error catalog schema
+Order::Place.contract.to_json_schema(section: :full)    # everything
+
+Dex::Operation.export                          # all operations as hashes
+Dex::Operation.export(format: :json_schema)    # all as JSON Schema
+```
+
+### LLM Tools (ruby-llm integration)
+
+```ruby
+chat = RubyLLM.chat
+chat.with_tools(*Dex::Tool.all)                     # all operations as tools
+chat.with_tools(*Dex::Tool.from_namespace("Order")) # namespace filter
+chat.with_tools(Dex::Tool.explain_tool)              # preflight check tool
+
+Dex.with_context(current_user: user) do
+  chat.ask("Place an order for 2 units of product #42")
+end
+```
+
+Requires `gem 'ruby_llm'` in your Gemfile. Lazy-loaded — ruby-llm is only required when you call `Dex::Tool`.
+
+---
+
 **End of reference.**

data/guides/llm/QUERY.md

@@ -1,6 +1,6 @@
 # Dex::Query — LLM Reference
 
-Copy this to your app's queries directory (e.g., `app/queries/AGENTS.md`) so coding agents know the full API when implementing and testing queries.
+Install with `rake dex:guides` or copy manually to `app/queries/AGENTS.md`.
 
 ---
 

data/lib/dex/context_setup.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Dex
+  # Shared context DSL for Operation and Event.
+  #
+  # Maps declared props to ambient context keys so they can be auto-filled
+  # from Dex.context when not passed explicitly as kwargs.
+  module ContextSetup
+    extend Dex::Concern
+
+    module ClassMethods
+      def context(*names, **mappings)
+        names.each do |name|
+          unless name.is_a?(Symbol)
+            raise ArgumentError, "context shorthand must be a Symbol, got: #{name.inspect}"
+          end
+          mappings[name] = name
+        end
+
+        raise ArgumentError, "context requires at least one mapping" if mappings.empty?
+
+        mappings.each do |prop_name, context_key|
+          unless _context_prop_declared?(prop_name)
+            raise ArgumentError,
+              "context references undeclared prop :#{prop_name}. Declare the prop before calling context."
+          end
+          unless context_key.is_a?(Symbol)
+            raise ArgumentError,
+              "context key must be a Symbol, got: #{context_key.inspect} for prop :#{prop_name}"
+          end
+        end
+
+        _context_own.merge!(mappings)
+      end
+
+      def context_mappings
+        parent = superclass.respond_to?(:context_mappings) ? superclass.context_mappings : {}
+        parent.merge(_context_own)
+      end
+
+      def new(**kwargs)
+        mappings = context_mappings
+        unless mappings.empty?
+          ambient = Dex.context
+          mappings.each do |prop_name, context_key|
+            next if kwargs.key?(prop_name)
+            kwargs[prop_name] = ambient[context_key] if ambient.key?(context_key)
+          end
+        end
+        super
+      end
+
+      private
+
+      def _context_own
+        @_context_own_mappings ||= {}
+      end
+
+      def _context_prop_declared?(name)
+        respond_to?(:literal_properties) && literal_properties.any? { |p| p.name == name }
+      end
+    end
+  end
+end

data/lib/dex/event/export.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    module Export
+      module_function
+
+      def build_hash(source)
+        h = {}
+        h[:name] = source.name if source.name
+        desc = source.description
+        h[:description] = desc if desc
+        h[:props] = _serialize_props(source)
+        h
+      end
+
+      def build_json_schema(source)
+        descs = source.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        properties = {}
+        required = []
+
+        if source.respond_to?(:literal_properties)
+          source.literal_properties.each do |prop|
+            prop_desc = descs[prop.name]
+            schema = TypeSerializer.to_json_schema(prop.type, desc: prop_desc)
+            properties[prop.name.to_s] = schema
+            required << prop.name.to_s if prop.required?
+          end
+        end
+
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+        result[:title] = source.name if source.name
+        desc = source.description
+        result[:description] = desc if desc
+        result[:type] = "object"
+        result[:properties] = properties unless properties.empty?
+        result[:required] = required unless required.empty?
+        result[:additionalProperties] = false
+        result
+      end
+
+      def _serialize_props(source)
+        return {} unless source.respond_to?(:literal_properties)
+
+        descs = source.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        source.literal_properties.each_with_object({}) do |prop, hash|
+          entry = { type: TypeSerializer.to_string(prop.type), required: prop.required? }
+          entry[:desc] = descs[prop.name] if descs[prop.name]
+          hash[prop.name] = entry
+        end
+      end
+
+      private_class_method :_serialize_props
+    end
+  end
+end