tungsten-runtime 0.1.2

data/lib/tungsten/runtime/descriptors.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+# SPDX-License-Identifier: Apache-2.0
+
+module Tungsten
+  module Runtime
+    # One parameter: `name` is its key in the arguments object (the SDK's
+    # argument name), `wire` its name on the wire. Parameters with the roles
+    # idempotency_key, origin, auth and constant are not arguments.
+    ParamDescriptor = Data.define(:key, :name, :wire, :location, :required, :style, :explode, :role, :constant) do
+      # Whether the caller passes it among the arguments.
+      def argument? = %w[plain dry_run].include?(role)
+    end
+
+    # The request body: with `arg` set the whole body is that argument;
+    # otherwise a JSON object of the merged `fields` ([name, wire] pairs).
+    BodyDescriptor = Data.define(:media_type, :encoding, :required, :fields, :arg)
+
+    # A declared response: `status` an Integer, `"4XX"` or `"default"`.
+    ResponseDescriptor = Data.define(:status, :kind, :media_type)
+
+    # What the runtime needs to call one operation, from the SDK descriptor
+    # document v1, with every argument named by its `name`.
+    class OperationDescriptor
+      attr_reader :id, :http_method, :path, :params, :body, :responses, :security, :pagination, :rpc,
+                  :error_code_field, :gate, :agent, :request, :response, :page_item, :stream, :summary,
+                  :key_names
+
+      # @param doc [Hash] one entry of the document's `operations`
+      # @param defs [Hash] the document's `defs`
+      def initialize(doc, defs)
+        @id = doc["id"].to_s
+        @http_method = doc["method"].to_s.upcase
+        @path = doc["path"].to_s
+        @params = (doc["params"] || []).map do |p|
+          ParamDescriptor.new(key: p["key"].to_s, name: (p["name"] || p["key"]).to_s, wire: p["wire"].to_s,
+                              location: p["in"].to_s, required: p["required"] == true, style: p["style"] || "simple",
+                              explode: p["explode"] == true, role: p["role"] || "plain", constant: p["constant"])
+        end
+        @key_names = {}
+        @params.each { |p| @key_names[p.key] = p.name }
+        @body = body_of(doc["body"])
+        @responses = (doc["responses"] || []).map do |r|
+          ResponseDescriptor.new(status: r["status"], kind: r["kind"].to_s, media_type: r["media_type"])
+        end
+        @security = doc["security"] || []
+        @pagination = pagination_of(doc["pagination"])
+        @rpc = doc["rpc"]
+        @error_code_field = doc["error_code_field"]
+        status = doc["status"] || {}
+        @gate = status["kind"] == "gated" ? { "env_var" => status["env_var"], "disabled_status" => status["disabled_status"] } : nil
+        @agent = agent_of(doc["agent"] || {})
+        @request = doc["request"] ? Schema.new(doc["request"], defs) : nil
+        @response = doc["response"] ? Schema.new(doc["response"], defs) : nil
+        @page_item = doc["page_item"] ? Schema.new(doc["page_item"], defs) : nil
+        s = doc["stream"]
+        @stream = s ? { "event" => Schema.new(s["event"], defs), "done" => s["done"], "flag" => s["flag"] } : nil
+        @summary = doc["summary"].to_s
+      end
+
+      # The parameters the caller supplies as arguments.
+      def argument_params = @params.select(&:argument?)
+
+      # Whether the operation can change state (it is not read-only).
+      def mutation? = @agent["safety"] != "read_only"
+
+      # The argument name of an arguments layout key, or the key itself.
+      def name_of_key(key) = @key_names.fetch(key, key)
+
+      # The argument name of a parameter given by name or wire name.
+      def arg_name(key)
+        p = @params.find { |x| x.name == key } || @params.find { |x| x.wire == key }
+        p ? p.name : key
+      end
+
+      private
+
+      def body_of(b)
+        return nil unless b
+
+        shape = b["shape"] || {}
+        fields = []
+        arg = nil
+        if shape["kind"] == "merged"
+          (shape["fields"] || []).each do |f|
+            name = (f["name"] || f["key"]).to_s
+            fields << [name, f["wire"].to_s]
+            @key_names[f["key"].to_s] = name
+          end
+        else
+          arg = (shape["name"] || shape["arg"]).to_s
+          @key_names[shape["arg"].to_s] = arg
+        end
+        BodyDescriptor.new(media_type: b["media_type"].to_s, encoding: b["encoding"] || "json",
+                           required: b["required"] == true, fields: fields, arg: arg)
+      end
+
+      def pagination_of(p)
+        return nil unless p
+
+        out = p.dup
+        %w[request_param page_size_param offset_param limit_param page_param size_param].each do |k|
+          out[k] = name_of_key(p[k]) if p[k]
+        end
+        out
+      end
+
+      def agent_of(a)
+        out = a.dup
+        out["safety"] ||= "read_only"
+        out["idempotency"] = { "policy" => "none", "persist_required" => false }.merge(a["idempotency"] || {})
+        out["preview"] = a["preview"] || { "mode" => "local" }
+        out["remediation"] = a["remediation"] || {}
+        out["sensitive_response_fields"] = a["sensitive_response_fields"] || []
+        out["sensitive_request_fields"] = (a["sensitive_request_fields"] || []).map do |path|
+          head, rest = path.to_s.split(".", 2)
+          rest ? "#{name_of_key(head)}.#{rest}" : name_of_key(head)
+        end
+        out["shown_once"] = a["shown_once"] == true
+        out
+      end
+    end
+
+    # A macro in the canonical form, from the SDK descriptor document.
+    MacroDescriptor = Data.define(:name, :summary, :safety, :steps, :output, :input, :sensitive_response_fields,
+                                  :shown_once, :cluster) do
+      # The input fields: [key, name, required].
+      def input_fields = (input["fields"] || []).map { |f| [f["key"].to_s, (f["name"] || f["key"]).to_s, f["required"] == true] }
+
+      # The operation whose arguments the input takes.
+      def extends = input["extends"]
+
+      # The added fields as JSON Schemas.
+      def added = input["add"] || {}
+    end
+
+    # The SDK descriptor document of a generated SDK
+    # (`tungsten-descriptors.json`, format `tungsten-sdk-descriptors/1`).
+    class Descriptors
+      FORMAT = "tungsten-sdk-descriptors/1"
+
+      attr_reader :api, :operations, :macros, :defs, :target
+
+      # Read the document at a path.
+      def self.load(path) = new(Json.parse(File.read(path, mode: "rb")))
+
+      # @param doc [Hash] the parsed document
+      def initialize(doc)
+        raise ArgumentError, "not an SDK descriptor document (format #{doc['format'].inspect})" unless doc.is_a?(Hash) && doc["format"] == FORMAT
+
+        @target = doc["target"]
+        @api = doc["api"] || {}
+        @defs = doc["defs"] || {}
+        @operations = (doc["operations"] || {}).transform_values { |o| OperationDescriptor.new(o, @defs) }
+        @macros = (doc["macros"] || {}).transform_values do |m|
+          MacroDescriptor.new(name: m["name"].to_s, summary: m["summary"].to_s, safety: m["safety"] || "read_only",
+                              steps: m["steps"] || [], output: m["output"], input: m["input"] || {},
+                              sensitive_response_fields: m["sensitive_response_fields"] || [],
+                              shown_once: m["shown_once"] == true, cluster: m["cluster"])
+        end
+      end
+
+      def operation(id) = @operations[id]
+      def macro(name) = @macros[name]
+
+      # A validator of the named type `id` (UNSET when the document does not
+      # define it).
+      def schema_of(id)
+        @schemas ||= {}
+        @schemas[id] ||= @defs.key?(id) ? Schema.new(@defs[id], @defs) : UNSET
+      end
+    end
+  end
+end

data/lib/tungsten/runtime/dispatcher.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+# SPDX-License-Identifier: Apache-2.0
+
+module Tungsten
+  module Runtime
+    # The base of every generated `Dispatch`: calls by operation id or macro
+    # name with JSON arguments keyed by the SDK's argument names, for
+    # drivers that only know ids and JSON (the contract suite, tool
+    # servers). Arguments that fit a typed method (every required name
+    # given, no unknown name) run it; any others go to the core as they are,
+    # so pre-flight validation reports them. Results are the typed methods'
+    # (`raw` is the wire value).
+    class Dispatcher
+      # @param client [Object] the generated client
+      # @param operations [Hash] id => [required names, every name, call]
+      def initialize(client, operations:, previews:, pages:, streams:, macros:)
+        @client = client
+        @core = client.core
+        @operations = operations
+        @previews = previews
+        @pages = pages
+        @streams = streams
+        @macros = macros
+      end
+
+      attr_reader :core
+
+      # Every callable operation's id, in IR order.
+      def operations = @operations.keys
+
+      # Every macro's name, in IR order.
+      def macros = @macros.keys
+
+      # Call an operation.
+      # @return [Ok, Err]
+      def invoke(operation, args = {}, opts = nil)
+        run(@operations, operation, args, opts) { @core.call(operation, args, opts) }
+      end
+
+      # Preview an operation.
+      def preview_operation(operation, args = {}, opts = nil)
+        run(@previews, operation, args, opts) { @core.preview(operation, args, opts) }
+      end
+
+      # Every page of a paginated operation: an Enumerator of Ok and, last,
+      # Err.
+      def pages(operation, args = {}, opts = nil)
+        unless @core.operation(operation)&.pagination
+          return [Runtime.diag(operation, "VALIDATION_FAILED").param("operation").expected("a paginated operation")
+                         .remedy("#{operation} is not paginated; use invoke instead. Nothing was sent.").err].each
+        end
+        run(@pages, operation, args, opts) { @core.pages(operation, args, opts) }
+      end
+
+      # The event stream of an operation.
+      # @return [EventStream]
+      def stream(operation, args = {}, opts = nil)
+        run(@streams, operation, args, opts) { @core.stream(operation, args, opts) }
+      end
+
+      # Run a macro.
+      def run_macro(name, input = {}, opts = nil)
+        run(@macros, name, input, opts) { @core.run_macro(name, input, opts) }
+      end
+
+      # Preview a macro.
+      def preview_macro(name, input = {}, opts = nil) = @core.preview_macro(name, input, opts)
+
+      private
+
+      def run(table, name, args, opts)
+        entry = table[name]
+        return yield unless entry && args.is_a?(Hash)
+
+        required, every, call = entry
+        given = args.keys.map(&:to_s)
+        return yield unless (given - every).empty? && (required - given).empty?
+
+        call.call(@client, args.to_h { |k, v| [k.to_sym, v] }, opts)
+      end
+    end
+  end
+end

data/lib/tungsten/runtime/envelope.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+# SPDX-License-Identifier: Apache-2.0
+
+module Tungsten
+  module Runtime
+    # The closed set of error categories shared by every tungsten runtime.
+    CATEGORIES = %w[
+      VALIDATION_FAILED MALFORMED_REQUEST REQUEST_TOO_LARGE AUTH_FAILED NOT_FOUND CONFLICT
+      PRECONDITION_FAILED RATE_LIMITED UPSTREAM_UNAVAILABLE OUTCOME_UNKNOWN TRANSPORT_FAILED
+      CONFIRMATION_REQUIRED GATE_DISABLED UNEXPECTED_RESPONSE
+    ].freeze
+
+    # Whether and how a failed call may be repeated.
+    RETRYABLE = %w[never after_delay same_key_only after_remediation].freeze
+
+    # Written wherever a secret or sensitive value would appear.
+    REDACTED = "<redacted>"
+
+    # The error envelope (planning/06): `to_h` is exactly the fourteen
+    # members of specs/envelope.schema.json in order, every member present
+    # (nil when it has no value), identical across the runtimes.
+    Diagnostic = Data.define(
+      :category, :operation, :http_status, :code, :failed_parameter, :received_value, :expected,
+      :remediation, :retryable, :retry_after_ms, :next_action, :request_id, :attempts
+    ) do
+      def to_h
+        {
+          "status" => "error",
+          "category" => category,
+          "operation" => operation,
+          "http_status" => http_status,
+          "code" => code,
+          "failed_parameter" => failed_parameter,
+          "received_value" => received_value,
+          "expected" => expected,
+          "remediation" => remediation,
+          "retryable" => retryable,
+          "retry_after_ms" => retry_after_ms,
+          "next_action" => next_action,
+          "request_id" => request_id,
+          "trace" => { "attempts" => attempts }
+        }
+      end
+
+      def to_json(*) = Json.text(to_h)
+
+      # "<category> in <operation>: <remediation>".
+      def message = "#{category} in #{operation}: #{remediation}"
+      alias_method :to_s, :message
+    end
+
+    # The default `retryable` of a category.
+    def self.default_retryable(category)
+      case category
+      when "RATE_LIMITED", "UPSTREAM_UNAVAILABLE", "TRANSPORT_FAILED" then "after_delay"
+      when "OUTCOME_UNKNOWN" then "same_key_only"
+      else "never"
+      end
+    end
+
+    GENERIC_REMEDIATION = {
+      "VALIDATION_FAILED" => "The server rejected the arguments. Fix the parameter the API error names and call again; the same request fails the same way.",
+      "MALFORMED_REQUEST" => "The server could not parse the request. Check the format of path and query parameters (for example canonical UUIDs); do not retry unchanged.",
+      "REQUEST_TOO_LARGE" => "The request body is larger than the server accepts. Send a smaller body; do not retry unchanged.",
+      "AUTH_FAILED" => "The credential is missing, expired, revoked or lacks permission. Do not retry; fix the credential configured in ClientOptions.auth.",
+      "NOT_FOUND" => "The resource does not exist or is not visible to this credential. Check the identifiers; do not retry unchanged.",
+      "CONFLICT" => "The request conflicts with the resource's current state. Read the current state before deciding what to do; do not retry unchanged.",
+      "PRECONDITION_FAILED" => "A precondition of this operation is not met (account, billing or resource state). Resolve it first; do not retry unchanged.",
+      "RATE_LIMITED" => "Rate limited. Wait retry_after_ms (or a few seconds when it is null) before calling again.",
+      "UPSTREAM_UNAVAILABLE" => "The service is temporarily unavailable. Wait, then call again.",
+      "OUTCOME_UNKNOWN" => "The server may or may not have applied this call; do not retry it blindly. Check whether it took effect before doing anything else.",
+      "TRANSPORT_FAILED" => "The request could not be delivered (DNS, TLS or connection failure), so the server did not receive it. Check base_url and network access, then call again.",
+      "CONFIRMATION_REQUIRED" => "This operation needs confirmation: call preview(...) and pass its confirmation_token.",
+      "GATE_DISABLED" => "This operation is disabled on this deployment. It is a deployment setting; do not retry.",
+      "UNEXPECTED_RESPONSE" => "The server's response did not match the API description. Do not retry blindly; report it."
+    }.freeze
+
+    # The remediation used when no manifest entry applies.
+    def self.generic_remediation(category) = GENERIC_REMEDIATION.fetch(category, "The call failed.")
+
+    # The category of an HTTP error status without a manifest entry.
+    def self.category_for_status(status, json_body)
+      case status
+      when 401, 403, 407 then "AUTH_FAILED"
+      when 404, 410 then "NOT_FOUND"
+      when 409 then "CONFLICT"
+      when 402, 412, 428 then "PRECONDITION_FAILED"
+      when 413 then "REQUEST_TOO_LARGE"
+      when 422 then "VALIDATION_FAILED"
+      when 429 then "RATE_LIMITED"
+      when 408, 502, 503, 504 then "UPSTREAM_UNAVAILABLE"
+      when 500..599 then "UPSTREAM_UNAVAILABLE"
+      when 400..499 then json_body ? "VALIDATION_FAILED" : "MALFORMED_REQUEST"
+      else "UNEXPECTED_RESPONSE"
+      end
+    end
+
+    # Builds an envelope member by member; `build` fills the remediation
+    # and `retryable` a category implies when they were not set.
+    class Diag
+      def initialize(operation, category)
+        @fields = { operation: operation, category: category, http_status: nil, code: nil, failed_parameter: nil,
+                    received_value: nil, expected: nil, remediation: nil, retryable: nil, retry_after_ms: nil,
+                    next_action: nil, request_id: nil, attempts: 0 }
+      end
+
+      %i[http_status code failed_parameter received_value expected remediation retry_after_ms next_action
+         request_id attempts].each do |name|
+        define_method(name) do |value|
+          @fields[name] = value
+          self
+        end
+      end
+
+      def status(code) = http_status(code)
+      def param(path) = failed_parameter(path)
+      def received(value) = received_value(value)
+      def remedy(text) = remediation(text)
+
+      def retrying(value)
+        @fields[:retryable] = value
+        self
+      end
+
+      # `retrying` unless the value is nil.
+      def retrying_opt(value) = value.nil? ? self : retrying(value)
+
+      def build
+        f = @fields.dup
+        f[:remediation] ||= Runtime.generic_remediation(f[:category])
+        f[:retryable] ||= Runtime.default_retryable(f[:category])
+        Diagnostic.new(**f)
+      end
+
+      def err = Err.new(error: build, partial: UNSET)
+    end
+
+    # A diagnostic builder.
+    def self.diag(operation, category) = Diag.new(operation, category)
+
+    # What the HTTP answer of a call said: the status, the headers (names
+    # lower-cased; repeated values joined with ", ", set-cookie keeps its
+    # last), the request id the server gave and the attempts made.
+    ResponseMeta = Data.define(:status, :headers, :request_id, :attempts) do
+      def self.local = new(status: 0, headers: {}, request_id: nil, attempts: 0)
+    end
+
+    # The result of an operation's verification hook: `checked` false when
+    # it could not run (then `error` says why); `passed` when its
+    # expectation held; `observed` the read's body (sensitive fields
+    # redacted); `timed_out` when polling for its terminal state ran out of
+    # budget.
+    Verification = Data.define(:checked, :passed, :observed, :timed_out, :error) do
+      def self.unchecked(error = nil) = new(checked: false, passed: false, observed: UNSET, timed_out: false, error: error)
+
+      # The verification as the TypeScript runtime shapes it.
+      def to_h
+        out = { "checked" => checked, "passed" => passed, "observed" => UNSET.equal?(observed) ? nil : observed }
+        out["timed_out"] = true if timed_out
+        out["error"] = error.to_h if error
+        out
+      end
+    end
+
+    # A successful call. `value` is the typed value (a model, a page, ...),
+    # `raw` the decoded wire value it came from (nil for a success without a
+    # body), `meta` the HTTP answer, `verification` the verification
+    # result when the call asked for one.
+    Ok = Data.define(:value, :raw, :meta, :verification) do
+      def initialize(value:, meta:, raw: value, verification: nil) = super
+      def ok? = true
+      def error = nil
+      def partial = UNSET
+    end
+
+    # A failed call: `error` is the envelope (a Diagnostic); `partial` what
+    # the failed call or macro already produced when its effect happened (a
+    # mutation's body that failed strict validation, a macro's completed
+    # step results by name), else UNSET. A partial can hold values the API
+    # shows only once: store them before acting on the error.
+    Err = Data.define(:error, :partial) do
+      def initialize(error:, partial: UNSET) = super
+      def ok? = false
+      def value = nil
+      def raw = nil
+      def meta = nil
+      def verification = nil
+      def partial? = !UNSET.equal?(partial)
+    end
+
+    # A request rendered without sending it; secrets show as <redacted>.
+    RenderedRequest = Data.define(:http_method, :url, :headers, :body) do
+      def to_h = { "method" => http_method, "url" => url, "headers" => headers, "body" => body }
+    end
+
+    # One step of a macro preview: `request` is nil when the step's
+    # arguments (or a bytes or multipart body) come from an earlier result.
+    MacroStepPreview = Data.define(:step, :kind, :operation, :as, :safety, :request, :effects) do
+      def to_h
+        { "step" => step, "kind" => kind, "operation" => operation, "as" => as, "safety" => safety,
+          "request" => request&.to_h, "effects" => effects }
+      end
+    end
+
+    # What `preview` returns: the request (for a macro, its first step's),
+    # the side effects in words, and for a mutating operation a
+    # confirmation token bound to the exact arguments for `expires_in_ms`.
+    PreviewResult = Data.define(
+      :operation, :safety, :request, :effects, :confirmation_token, :expires_in_ms, :server_preview, :steps
+    ) do
+      def to_h
+        out = { "operation" => operation, "safety" => safety, "request" => request.to_h, "effects" => effects,
+                "confirmation_token" => confirmation_token, "expires_in_ms" => expires_in_ms }
+        out["server_preview"] = server_preview unless UNSET.equal?(server_preview)
+        out["steps"] = steps.map(&:to_h) if steps
+        out
+      end
+    end
+
+    # One page of a paginated operation: its items, the whole body and the
+    # cursor, offset, page number or URL of the next page (nil at the end).
+    Page = Data.define(:items, :body, :next_page)
+
+    # One event of a stream: its decoded `data` (`value`; `raw` is the JSON
+    # it came from), the event name (`message` when it has none), the last
+    # event id and retry value the stream has set so far, the answer of the
+    # connection it arrived on and the reconnects made up to it.
+    StreamEvent = Data.define(:value, :raw, :event, :id, :retry_ms, :meta, :reconnects)
+  end
+end

data/lib/tungsten/runtime/expr.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+# SPDX-License-Identifier: Apache-2.0
+
+module Tungsten
+  module Runtime
+    # Predicates and expressions of verification hooks, polls and macros.
+    #
+    # Predicates (verify `expect` and `terminal`, poll `until`): field path
+    # to {"in": [...]} | {"equals": x} | {"contains": ...}; any other value is
+    # compared for equality. Every entry must hold.
+    #
+    # Expressions: JSON in which a string starting with "$" is a reference
+    # resolved against a scope ($input.a.b, $<name>.a, $response.x, $args.y),
+    # an object {"expr": "<ref> in [..]" | "<ref> == x" | "<ref> != x"} is a
+    # boolean, anything else a literal. A dry evaluation (macro previews)
+    # knows the input but not the earlier results: a reference to one is the
+    # placeholder "<from step NAME: path>".
+    module Expr
+      module_function
+
+      # Whether every entry of the predicate holds on the value (UNSET when
+      # absent). A nil predicate always holds; a malformed one never does.
+      def predicate?(predicate, value)
+        case predicate
+        when nil then true
+        when Hash then predicate.all? { |path, test| holds?(test, Util.get_path_str(value, path)) }
+        else false
+        end
+      end
+
+      def subset?(value, pattern)
+        case pattern
+        when Hash
+          value.is_a?(Hash) && pattern.all? { |k, v| value.key?(k) && subset?(value[k], v) }
+        when Array
+          value.is_a?(Array) && pattern.all? { |want| value.any? { |have| subset?(have, want) } }
+        else
+          !UNSET.equal?(value) && Json.same?(value, pattern)
+        end
+      end
+
+      def holds?(test, actual)
+        if test.is_a?(Hash) && test.length == 1
+          if test.key?("in")
+            list = test["in"]
+            return list.is_a?(Array) && list.any? { |c| Json.same_opt?(c, actual) }
+          end
+          return Json.same_opt?(test["equals"], actual) if test.key?("equals")
+
+          if test.key?("contains")
+            pattern = test["contains"]
+            if pattern.is_a?(String)
+              return actual.include?(pattern) if actual.is_a?(String)
+              return actual.any? { |i| i == pattern } if actual.is_a?(Array)
+
+              return false
+            end
+            return actual.any? { |item| subset?(item, pattern) } if actual.is_a?(Array) && !pattern.is_a?(Array)
+
+            return subset?(actual, pattern)
+          end
+        end
+        Json.same_opt?(test, actual)
+      end
+
+      # One $name.path reference, or UNSET.
+      def resolve_ref(reference, scope)
+        segments = Util.split_path(reference.delete_prefix("$"))
+        return UNSET if segments.empty? || !scope.key?(segments.first)
+
+        Util.get_path(scope[segments.first], segments.drop(1))
+      end
+
+      # An expression's value; unknown references are UNSET (dropped from
+      # objects, nil in arrays); a malformed expr string is nil.
+      def evaluate(expr, scope, depth = 0)
+        return nil if depth > 64
+
+        case expr
+        when String then expr.start_with?("$") ? resolve_ref(expr, scope) : expr
+        when Array then expr.map { |item| evaluate(item, scope, depth + 1).then { |v| UNSET.equal?(v) ? nil : v } }
+        when Hash
+          return boolean(expr["expr"], scope) if expr.length == 1 && expr["expr"].is_a?(String)
+
+          expr.each_with_object({}) do |(k, v), out|
+            value = evaluate(v, scope, depth + 1)
+            out[k] = value unless UNSET.equal?(value)
+          end
+        else expr
+        end
+      end
+
+      def placeholder(name, path) = path.empty? ? "<from step #{name}>" : "<from step #{name}: #{path}>"
+
+      # [name, path] of a reference to a pending binding, else nil.
+      def pending_ref(reference, pending)
+        return nil unless reference.is_a?(String) && reference.start_with?("$")
+
+        segs = Util.split_path(reference[1..])
+        return nil if segs.empty?
+
+        name = segs.first
+        return nil unless pending.include?(name) && reference.start_with?("$#{name}")
+
+        [name, reference[(name.length + 1)..].delete_prefix(".")]
+      end
+
+      # A dry evaluation: references to the pending bindings become
+      # placeholders.
+      def evaluate_dry(expr, scope, pending, depth = 0)
+        return nil if depth > 64
+
+        case expr
+        when String
+          return expr unless expr.start_with?("$")
+
+          ref = pending_ref(expr, pending)
+          ref ? placeholder(*ref) : resolve_ref(expr, scope)
+        when Array then expr.map { |item| evaluate_dry(item, scope, pending, depth + 1).then { |v| UNSET.equal?(v) ? nil : v } }
+        when Hash
+          if expr.length == 1 && expr["expr"].is_a?(String)
+            source = expr["expr"].strip
+            head = source[/\A\$[^\s=!]+/]
+            ref = head && pending_ref(head, pending)
+            return placeholder(ref[0], source[(ref[0].length + 1)..].delete_prefix(".")) if ref
+
+            return boolean(source, scope)
+          end
+          expr.each_with_object({}) do |(k, v), out|
+            value = evaluate_dry(v, scope, pending, depth + 1)
+            out[k] = value unless UNSET.equal?(value)
+          end
+        else expr
+        end
+      end
+
+      # A predicate in words: state in ["a", "b"], endpoints contains {...},
+      # a = 1, joined with "and".
+      def describe(predicate)
+        return "" unless predicate.is_a?(Hash)
+
+        predicate.map do |path, test|
+          if test.is_a?(Hash) && test.length == 1 && test["in"].is_a?(Array)
+            "#{path} in [#{test['in'].map { |v| Json.text(v) }.join(', ')}]"
+          elsif test.is_a?(Hash) && test.length == 1 && test.key?("equals")
+            "#{path} = #{Json.text(test['equals'])}"
+          elsif test.is_a?(Hash) && test.length == 1 && test.key?("contains")
+            "#{path} contains #{Json.text(test['contains'])}"
+          else
+            "#{path} = #{Json.text(test)}"
+          end
+        end.join(" and ")
+      end
+
+      def literal(text)
+        trimmed = text.strip
+        value = Json.try_parse(trimmed)
+        return value unless UNSET.equal?(value)
+
+        normalized = trimmed.gsub(/'((?:[^'\\]|\\.)*)'/) { Json.quote(Regexp.last_match(1).gsub("\\'", "'")) }
+        Json.try_parse(normalized)
+      end
+
+      BOOLEAN = /\A\s*(\$[^\s=!]+)\s+(in|==|!=)\s+(.+)\z/m
+
+      # `<ref> in [..]`, `<ref> == x` or `<ref> != x`; nil when malformed.
+      def boolean(source, scope)
+        m = source.match(BOOLEAN)
+        return nil unless m
+
+        lit = literal(m[3])
+        return nil if UNSET.equal?(lit)
+
+        actual = resolve_ref(m[1], scope)
+        if m[2] == "in"
+          return nil unless lit.is_a?(Array)
+
+          return lit.any? { |v| Json.same_opt?(v, actual) }
+        end
+        actual = nil if UNSET.equal?(actual)
+        same = Json.same?(actual, lit)
+        m[2] == "==" ? same : !same
+      end
+    end
+  end
+end