typesafe-sdk-ruby 0.6.0 → 0.6.0.1

data/docs/UPSTREAM_ISSUES.md

@@ -0,0 +1,64 @@
+# Upstream issue audit
+
+Reviewed all **11 issues** returned by the official JavaScript repository's all-state issue
+list on **2026-09-21**, including their comments. All were open at review time. The baseline
+is `@typesafe-ai/sdk` **0.6.0**, commit `66880ccded6cb642dc1809620c2b108c33730214`.
+Ruby changes below are included in **0.6.0.1**.
+
+This audit distinguishes client fixes from runtime differences and server feature requests.
+It does not claim that the upstream issues are closed or that every requested API feature
+is available. Valid supported requests continue to follow the JS wire format; reproducing
+known JS bugs is not a compatibility goal.
+
+## Disposition of every issue
+
+| Upstream issue | Ruby disposition | Evidence or remaining limitation |
+| --- | --- | --- |
+| [#14: API key disclosure and empty keys](https://github.com/typesafe-ai/typesafe-sdk-js/issues/14) | Fixed locally | Validate explicit and environment keys at construction, trim outer spaces/tabs/line endings, reject empty/non-ASCII/control/embedded-whitespace values, and copy/freeze the key. Validation errors contain no key and make no request or retry. Header-construction failures also propagate without connection retries. |
+| [#13: actionable HTTP error classes](https://github.com/typesafe-ai/typesafe-sdk-js/issues/13) | Implemented | HTTP 402, 409, and 413 map to `PaymentRequiredError`, `ConflictError`, and `PayloadTooLargeError`. Each remains an `APIError`, retains response metadata, and is not retried by default. |
+| [#12: null score levels](https://github.com/typesafe-ai/typesafe-sdk-js/issues/12) | Fixed locally | Builders and raw hashes reject nil levels. Use an explicit empty string for an undescribed position; entries are never removed or renumbered. This workaround is reported accepted in the upstream issue, not independently verified against the live API here. |
+| [#11: calibrated multi-label selection](https://github.com/typesafe-ai/typesafe-sdk-js/issues/11) | Requires upstream API/model support | Choice selects one option. Multiple noul questions are independent judgments, not a calibrated competitive multi-label substitute. The Ruby SDK does not invent such an endpoint or promise equivalent calibration. |
+| [#10: cached or registered criteria](https://github.com/typesafe-ai/typesafe-sdk-js/issues/10) | Requires upstream API support | Reusing a Ruby question Hash still sends the criteria on each request and does not reduce billed tokens. There is no supported registration/cache API in the audited JS SDK. No synthetic `cached_tokens` field is exposed. |
+| [#9: blank retry delay headers](https://github.com/typesafe-ai/typesafe-sdk-js/issues/9) | Fixed locally | Blank/whitespace-only delays fall back to configured backoff; blank milliseconds can fall through to valid seconds. Literal zero is still honored. Request-path tests verify the actual retry delay. |
+| [#8: Node timer overflow](https://github.com/typesafe-ai/typesafe-sdk-js/issues/8) | Node-specific; Ruby equivalent tested | Ruby does not use Node timers. Real loopback requests with delayed responses succeed at and just above Node's 2,147,483,647 ms boundary, for both constructor and per-call settings. This is not a guarantee for every arbitrarily large OS timeout. |
+| [#7: list the community Go SDK](https://github.com/typesafe-ai/typesafe-sdk-js/issues/7) | Upstream documentation request | No Ruby defect. Whether TypeSafe lists third-party clients is an upstream decision; this repository clearly identifies itself as unofficial. |
+| [#6: API-invalid request shapes and limits](https://github.com/typesafe-ai/typesafe-sdk-js/issues/6) | Fixed locally | Require string/object/array state and reject nil; require noul instructions or a non-nil true/false description; enforce 2–10 score levels, 1–255 choice options, and nonempty question names. Empty state containers, single-option choice, and whitespace-only names remain allowed. |
+| [#4: numeric choice label inference](https://github.com/typesafe-ai/typesafe-sdk-js/issues/4) | TypeScript-specific; Ruby equivalent tested | Ruby has no TypeScript `never` inference. Numeric labels serialize as JSON string keys and choice answers/probability keys remain strings. |
+| [#2: handled cancellation crashes Node](https://github.com/typesafe-ai/typesafe-sdk-js/issues/2) | Different transport; Ruby equivalent tested | The Net::HTTP worker is cleaned up before cancellation returns. Separate processes with `Thread.abort_on_exception = true` catch `APIUserAbortError` and exit normally after cancellation during successful and error response bodies, for inference and model listing. Existing socket tests also exercise cancellation and worker cleanup. |
+
+## Compatibility and migration
+
+The local validation, blank-header handling, and added error subclasses intentionally differ
+from JS 0.6.0. Previously accepted local inputs that are reported rejected by the API now raise
+`TypeSafeError` earlier. In particular, replace `noul()` with an actual question or outcome
+criteria, supply non-nil state, and replace nil score placeholders explicitly with descriptions
+or empty strings. Do not drop score slots to pass validation, because their positions define
+the scale. Nil choice descriptions remain supported.
+
+Raw question hashes, including JSON-loaded hashes with string keys, receive the same checks
+as builders. These targeted checks are not a complete copy of the server's evolving schema;
+the API remains authoritative for other validation and model behavior.
+
+New error subclasses retain the public `APIError` contract. Catching `APIError` continues to
+work; code comparing exact classes may need updating. HTTP 402/409/413 are still excluded
+from the default retry statuses.
+
+For future server fields, `with_response: true` exposes the parsed response body, including
+its raw `usage` object. This does not mean the server currently reports cache usage. Consult
+upstream documentation before relying on newly introduced fields or sending `extra_body:`.
+
+## Verification scope
+
+- [Issue regressions](../spec/typesafe/sdk/upstream_issues_spec.rb): request validation,
+  API key handling, retry scheduling, error mapping, and numeric labels using synthetic data.
+- [Socket regressions](../spec/typesafe/sdk/http_spec.rb): actual Ruby transport behavior,
+  including the Node timer boundary, cancellation, and slow/truncated bodies.
+- [Subprocess cancellation](../spec/typesafe/sdk/cancellation_process_spec.rb): handled
+  cancellation must not crash the caller process or leak an uncaught worker error.
+- [JS baseline comparisons](../spec/typesafe/sdk/parity_spec.rb): fixtures generated by
+  running the published JS package; known corrections are explicit in assertions and the
+  fixture preserves the original JS output for those cases.
+
+No live API key was available. Input constraints and reported server behavior above come from
+upstream issue reports; tests prove Ruby's handling, not an independent live reproduction.
+See [compatibility and live verification](COMPATIBILITY.md) for the opt-in smoke test.

data/lib/typesafe/sdk/client.rb

@@ -35,8 +35,7 @@ module Typesafe
       def initialize(api_key: nil, base_url: nil, default_model: nil, log_level: nil,
                      logger: nil, retry_policy: nil, timeout: nil, default_headers: nil,
                      http: nil, env: ::ENV)
-        @api_key = ENV.from_code_or_env(api_key, ENV::API_KEY, source: env)
-        raise TypeSafeError, missing_api_key_message if @api_key.nil? || @api_key.empty?
+        @api_key = validate_api_key(api_key.nil? ? env[ENV::API_KEY] : api_key)
 
         @base_url = strip_trailing_slashes(
           ENV.from_code_or_env(base_url, ENV::BASE_URL, source: env) || DEFAULT_BASE_URL
@@ -56,13 +55,14 @@ module Typesafe
 
       # Answer named questions about text or structured state.
       #
-      # @param state [String, Hash, Array, nil] the content to evaluate.
+      # @param state [String, Hash, Array] the content to evaluate.
       # @param questions [Hash{Symbol, String => Hash}] nonempty questions keyed by name.
       # @param model [String, nil] model override; omitted values inherit `default_model`.
-      # @param options [Hash] per-call `timeout`, `retry`, `headers`, and `signal` settings.
-      # @return [SystemOneResult] answers keyed by question name, with model and token usage.
-      # @raise [TypeSafeError] questions are empty, or score criteria are not a list of at
-      #   least two entries.
+      # @param extra_body [Hash] additional JSON fields; named request arguments take precedence.
+      # @param with_response [Boolean] return data with HTTP metadata and request ID.
+      # @param options [Hash] per-call `timeout`, `retry_policy`, `headers`, and `signal` settings.
+      # @return [SystemOneResult, WithResponse] answers keyed by question name, with model and token usage.
+      # @raise [TypeSafeError] state or questions violate the locally checked API constraints.
       # @raise [APIError] the server returns a non-2xx response after retries.
       # @raise [APIConnectionError] the request cannot connect or times out after retries.
       # @raise [APIUserAbortError] the caller cancels the request.
@@ -72,17 +72,21 @@ module Typesafe
       #     state: "I was charged twice. Please help.",
       #     questions: { billing: Typesafe::SDK.noul("Is this about billing?") },
       #   )
-      #   response.answers[:billing].noul # => 0.93
-      def system_one(state:, questions:, model: nil, **options)
+      #   response[:billing].noul # => 0.93
+      def system_one(state:, questions:, model: nil, extra_body: {}, with_response: false, **options)
+        Questions.validate_state!(state)
         Questions.validate!(questions)
-        body = { state: state, questions: questions, model: model || @default_model }
+        body = extra_body.transform_keys(&:to_s).merge(
+          "state" => state, "questions" => questions, "model" => model || @default_model
+        )
         response = request(:post, "/v1/systemone", body: body, **options)
-        SystemOneResult.new(response.body)
+        result = SystemOneResult.new(response.body)
+        with_response ? WithResponse.new(result, response) : result
       end
 
       # Send a request and parse its response body. Internal; used by API resources.
       #
-      # @return [Response] the parsed response, with `data`, `status`, `headers`, and `request_id`.
+      # @return [Response] the parsed response, with `body`, `status`, `headers`, and `request_id`.
       def request(method, path, body: nil, headers: {}, timeout: nil, retry_policy: nil,
                   signal: nil)
         resolved = {
@@ -106,6 +110,21 @@ module Typesafe
 
       private
 
+      def validate_api_key(value)
+        raise TypeSafeError, missing_api_key_message if value.nil?
+        unless value.is_a?(String) && value.valid_encoding? && value.ascii_only?
+          raise TypeSafeError, "API key must be an ASCII string."
+        end
+
+        key = value.gsub(/\A[ \t\r\n]+|[ \t\r\n]+\z/, "")
+        raise TypeSafeError, missing_api_key_message if key.empty?
+        if key.match?(/[\x00-\x20\x7f]/)
+          raise TypeSafeError, "API key must not contain whitespace or control characters."
+        end
+
+        key.freeze
+      end
+
       def missing_api_key_message
         "No API key was provided. Pass `api_key:` to Typesafe::SDK::Client.new or set the " \
           "#{ENV::API_KEY} environment variable."
@@ -121,7 +140,7 @@ module Typesafe
       end
 
       def assert_positive(name, value)
-        unless value.is_a?(Numeric) && value.positive?
+        unless value.is_a?(Numeric) && value.real? && value.finite? && value.positive?
           raise TypeSafeError,
                 "`#{name}` must be a positive number, got #{value.inspect}."
         end
@@ -138,7 +157,7 @@ module Typesafe
       end
 
       def assert_non_negative(name, value)
-        unless value.is_a?(Numeric) && value >= 0
+        unless value.is_a?(Numeric) && value.real? && value.finite? && value >= 0
           raise TypeSafeError, "`#{name}` must be a non-negative number, got #{value.inspect}."
         end
 
@@ -146,7 +165,7 @@ module Typesafe
       end
 
       def assert_fraction(name, value)
-        unless value.is_a?(Numeric) && value >= 0 && value <= 1
+        unless value.is_a?(Numeric) && value.real? && value.finite? && value >= 0 && value <= 1
           raise TypeSafeError, "`#{name}` must be between 0 and 1, got #{value.inspect}."
         end
 
@@ -159,7 +178,7 @@ module Typesafe
             raise TypeSafeError, "`#{name}` must contain HTTP status codes, got #{status.inspect}."
           end
         end
-        statuses
+        statuses.freeze
       end
 
       # Merge and validate retry overrides, copying the status list to isolate later mutations.
@@ -196,18 +215,23 @@ module Typesafe
                          else
                            base[:http_statuses]
                          end,
-          respect_retry_after: o.fetch(:respect_retry_after, base[:respect_retry_after]),
+          respect_retry_after: resolve_retry_flag(base, o, :respect_retry_after),
           max_retry_after_ms: if o.key?(:max_retry_after_ms)
                                 assert_non_negative("retry.max_retry_after_ms",
                                                     o[:max_retry_after_ms])
                               else
                                 base[:max_retry_after_ms]
                               end,
-          api_connection_error: o.fetch(:api_connection_error, base[:api_connection_error]),
-          api_timeout_error: o.fetch(:api_timeout_error, base[:api_timeout_error])
+          api_connection_error: resolve_retry_flag(base, o, :api_connection_error),
+          api_timeout_error: resolve_retry_flag(base, o, :api_timeout_error)
         }.freeze
       end
 
+      # Like upstream's nullish fallback, nil inherits while false stays explicit.
+      def resolve_retry_flag(base, overrides, name)
+        overrides[name].nil? ? base[name] : overrides[name]
+      end
+
       # Last value wins regardless of casing; `nil` removes a protected header.
       def merge_headers(*sources)
         merged = {}
@@ -312,9 +336,9 @@ module Typesafe
         sleep_with_signal(delay, req[:signal])
       end
 
-      def sleep_with_signal(seconds, signal)
+      def sleep_with_signal(milliseconds, signal)
         signal&.check!
-        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + (seconds / 1000.0)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + (milliseconds / 1000.0)
         loop do
           if signal
             signal.check!

data/lib/typesafe/sdk/errors.rb

@@ -35,7 +35,7 @@ module Typesafe
 
       def self.describe(status, body)
         detail = extract_message(body)
-        return "#{status} #{detail}" if detail
+        return "#{status} #{detail}" if detail && !detail.empty?
         return "#{status} status code (no body)" if body.nil?
 
         raw = body.is_a?(String) ? body : JSON.generate(body)
@@ -56,8 +56,11 @@ module Typesafe
         @status_classes ||= {
           400 => Typesafe::SDK::BadRequestError,
           401 => Typesafe::SDK::AuthenticationError,
+          402 => Typesafe::SDK::PaymentRequiredError,
           403 => Typesafe::SDK::PermissionDeniedError,
           404 => Typesafe::SDK::NotFoundError,
+          409 => Typesafe::SDK::ConflictError,
+          413 => Typesafe::SDK::PayloadTooLargeError,
           422 => Typesafe::SDK::UnprocessableEntityError,
           429 => Typesafe::SDK::RateLimitError
         }.freeze
@@ -94,18 +97,27 @@ module Typesafe
     class BadRequestError < APIError; end
     # HTTP 401: authentication failed.
     class AuthenticationError < APIError; end
+    # HTTP 402: payment is required.
+    class PaymentRequiredError < APIError; end
     # HTTP 403: access is denied.
     class PermissionDeniedError < APIError; end
     # HTTP 404: the resource was not found.
     class NotFoundError < APIError; end
+    # HTTP 409: the request conflicts with the current state.
+    class ConflictError < APIError; end
+    # HTTP 413: the request payload is too large.
+    class PayloadTooLargeError < APIError; end
     # HTTP 422: request validation failed.
     class UnprocessableEntityError < APIError; end
 
     # HTTP 429: the rate limit was exceeded.
     class RateLimitError < APIError
-      # Server retry delay in milliseconds, or `nil` when absent or invalid.
-      def retry_after_ms
-        Typesafe::SDK::Retry.parse_retry_after(@headers)
+      # Captured at response time, so HTTP-date delays do not change between reads.
+      attr_reader :retry_after_ms
+
+      def initialize(...)
+        super
+        @retry_after_ms = Typesafe::SDK::Retry.parse_retry_after(@headers)
       end
     end
 

data/lib/typesafe/sdk/http.rb

@@ -9,6 +9,7 @@ module Typesafe
       def initialize
         @mutex = Mutex.new
         @canceled = false
+        @condition = ConditionVariable.new
       end
 
       def canceled?
@@ -16,7 +17,10 @@ module Typesafe
       end
 
       def cancel
-        @mutex.synchronize { @canceled = true }
+        @mutex.synchronize do
+          @canceled = true
+          @condition.broadcast
+        end
       end
 
       # Raise {APIUserAbortError} if canceled.
@@ -27,8 +31,10 @@ module Typesafe
       # Wait up to `seconds`, returning early when canceled.
       def wait(seconds)
         deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
-        while !canceled? && (remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)).positive?
-          sleep([remaining, 0.05].min)
+        @mutex.synchronize do
+          while !@canceled && (remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)).positive?
+            @condition.wait(@mutex, remaining)
+          end
         end
       end
     end
@@ -69,6 +75,7 @@ module Typesafe
         check_signal!(signal)
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = uri.scheme == "https"
+        http.max_retries = 0 # Only the SDK owns retries and retry-count headers.
         http.open_timeout = timeout
         http.read_timeout = timeout
         http.write_timeout = timeout if http.respond_to?(:write_timeout=)
@@ -78,9 +85,7 @@ module Typesafe
         headers.each { |name, value| req[name] = value }
         req.body = body if body
 
-        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        raw = http.request(req)
-        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+        raw = perform(http, req, timeout, signal)
         body_text = raw.body.to_s
         parsed = parse_body(body_text, raw["content-type"])
         Response.new(
@@ -93,13 +98,56 @@ module Typesafe
         raise
       rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
         raise APITimeoutError.new((timeout * 1000).round, cause: e)
-      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ETIMEDOUT,
-             SocketError, OpenSSL::SSL::SSLError, EOFError, IOError => e
+      rescue SystemCallError, SocketError, OpenSSL::SSL::SSLError, EOFError, IOError,
+             Net::HTTPBadResponse, Net::ProtocolError, Zlib::Error => e
         raise APIConnectionError.new("Connection error: #{e.message}", cause: e)
       end
 
       private
 
+      # Net::HTTP's read timeout resets for every read. A private worker bounds the
+      # whole connection/upload/body lifecycle without interrupting the caller thread.
+      # Killing it runs Net::HTTP's ensure blocks; join completes socket cleanup before return.
+      def perform(http, request, timeout, signal)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        worker = Thread.new do
+          Thread.current.report_on_exception = false
+          begin
+            [read_response(http, request), nil]
+          rescue StandardError => e
+            [nil, e]
+          end
+        end
+        loop do
+          signal&.check!
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise APITimeoutError, (timeout * 1000).round unless remaining.positive?
+          break if worker.join([remaining, 0.01].min)
+        end
+        signal&.check!
+        response, error = worker.value
+        raise error if error
+
+        response
+      ensure
+        worker&.kill&.join
+      end
+
+      def read_response(http, request)
+        http.start do
+          http.request(request) do |response|
+            response.ignore_eof = false if response.respond_to?(:ignore_eof=)
+            response.read_body
+            # Older Ruby releases silently accept short Content-Length bodies.
+            # Net::HTTP removes Content-Length when automatically decompressing.
+            length = response["content-length"]
+            if length && response.body && response.body.bytesize < length.to_i
+              raise EOFError, "Response body ended before Content-Length bytes arrived"
+            end
+          end
+        end
+      end
+
       def check_signal!(signal)
         signal&.check!
       end

data/lib/typesafe/sdk/logging.rb

@@ -64,7 +64,11 @@ module Typesafe
         define_method(severity) do |message, **data|
           return if LogLevel::RANK.fetch(severity) < @rank
 
-          @sink.public_send(severity, message, **data)
+          if data.empty? || @sink.method(severity).parameters.any? { |kind, _| %i[key keyreq keyrest].include?(kind) }
+            @sink.public_send(severity, message, **data)
+          else
+            @sink.public_send(severity, "#{message} #{data.map { |k, v| "#{k}=#{v.inspect}" }.join(' ')}")
+          end
         end
       end
     end

data/lib/typesafe/sdk/questions.rb

@@ -4,61 +4,87 @@ module Typesafe
   module SDK
     # Builders and validation for the three question types.
     module Questions
+      MAX_SCORE_LEVELS = 10
+      MAX_CHOICE_OPTIONS = 255
+
       module_function
 
-      # Create a yes/no question with optional descriptions for either outcome.
-      #
-      # @param instructions [String, Hash, Array, nil] the question; defaults to `nil`.
-      # @param criteria [Hash, nil] optional descriptions of the yes and no outcomes.
+      # Create a yes/no question. Supply instructions or at least one outcome description.
+      # @param instructions [String, Hash, Array, nil]
+      # @param criteria [Hash, nil] optional true/false outcome descriptions.
       def noul(instructions = nil, criteria: nil)
-        { type: "noul", instructions: instructions, criteria: criteria }
+        question = { type: "noul", instructions: instructions, criteria: criteria }
+        validate_noul!(instructions, criteria, "noul")
+        question
       end
 
-      # Create a score question using an ordered rubric.
-      #
-      # @param instructions [String, Hash, Array, nil] the question.
-      # @param criteria [Array] at least two descriptions indexed by score from zero.
+      # Create a score question with 2–10 ordered descriptions. Nil levels are not supported.
+      # An empty string preserves a position without a description.
       def score(instructions, criteria)
-        unless criteria.is_a?(Array)
-          raise TypeSafeError,
-                "Score criteria must be a list of descriptions indexed by score from zero, " \
-                "not a map."
-        end
-
+        validate_score!(criteria, "score")
         { type: "score", instructions: instructions, criteria: criteria }
       end
 
-      # Create a question that selects between named alternatives.
-      #
-      # @param instructions [String, Hash, Array, nil] the question.
-      # @param criteria [Hash] labels mapped to descriptions, or `nil` for undescribed labels.
+      # Create a choice between 1–255 named options; nil leaves a label undescribed.
       def choice(instructions, criteria)
-        if criteria.is_a?(Array)
-          raise TypeSafeError, "Choice criteria must be a map of labels to descriptions, not a list."
-        end
-
+        validate_choice!(criteria, "choice")
         { type: "choice", instructions: instructions, criteria: criteria }
       end
 
-      # Reject empty question sets and score questions without a list of at least two criteria.
+      def validate_state!(state)
+        return if state.is_a?(String) || state.is_a?(Hash) || state.is_a?(Array)
+
+        raise TypeSafeError, "`state` must be a string, object, or array; nil is not supported."
+      end
+
+      # Validate builders and raw JSON-style questions without altering the caller's data.
       def validate!(questions)
-        raise TypeSafeError, "At least one question is required." if questions.empty?
+        raise TypeSafeError, "At least one question is required." unless questions.is_a?(Hash) && !questions.empty?
 
         questions.each do |name, question|
-          next unless question.is_a?(Hash) && question[:type] == "score"
+          raise TypeSafeError, "Question key cannot be empty." if name.to_s.empty?
+          raise TypeSafeError, "Question must be an object." unless question.is_a?(Hash)
 
-          criteria = question[:criteria]
-          unless criteria.is_a?(Array)
-            raise TypeSafeError,
-                  "Score question \"#{name}\" has criteria that are not a list; " \
-                  "score criteria must be a list of descriptions indexed by score from zero."
+          wire = question.transform_keys(&:to_s)
+          case wire["type"].to_s
+          when "score" then validate_score!(wire["criteria"], name)
+          when "choice" then validate_choice!(wire["criteria"], name)
+          when "noul" then validate_noul!(wire["instructions"], wire["criteria"], name)
           end
-          next unless criteria.length < 2
+        end
+      end
+
+      def validate_noul!(instructions, criteria, name)
+        descriptions = criteria.is_a?(Hash) ? criteria.transform_keys(&:to_s) : {}
+        return unless instructions.nil? && %w[true false].all? { |key| descriptions[key].nil? }
+
+        raise TypeSafeError, "Noul question #{name.inspect} must have instructions or criteria."
+      end
 
+      def validate_score!(criteria, name)
+        unless criteria.is_a?(Array)
           raise TypeSafeError,
-                "Score question \"#{name}\" has #{criteria.length} criteria; " \
-                "at least two scores are required."
+                "Score question #{name.inspect} has criteria that are not a list; " \
+                "score criteria must be a list of descriptions indexed by score from zero."
+        end
+        raise TypeSafeError, "Score question #{name.inspect}: at least two scores are required." if criteria.length < 2
+        if criteria.length > MAX_SCORE_LEVELS
+          raise TypeSafeError, "Score question #{name.inspect}: at most #{MAX_SCORE_LEVELS} levels are allowed."
         end
+        return unless criteria.any?(&:nil?)
+
+        raise TypeSafeError,
+              "Score question #{name.inspect} contains a nil level; use a description or an empty string " \
+              "to preserve its position."
+      end
+
+      def validate_choice!(criteria, name)
+        unless criteria.is_a?(Hash)
+          raise TypeSafeError, "Choice criteria must be a map of labels to descriptions, not a list."
+        end
+        return if criteria.length.between?(1, MAX_CHOICE_OPTIONS)
+
+        raise TypeSafeError, "Choice question #{name.inspect} requires 1–#{MAX_CHOICE_OPTIONS} options."
       end
     end
   end

data/lib/typesafe/sdk/resources/models.rb

@@ -11,11 +11,12 @@ module Typesafe
 
         # List the models available to the account.
         #
-        # @param options [Hash] per-call `timeout`, `retry`, `headers`, and `signal` settings.
-        # @return [Array<ModelCard>]
+        # @param options [Hash] per-call `timeout`, `retry_policy`, `headers`, and `signal` settings.
+        # @param with_response [Boolean] return model cards with HTTP metadata and request ID.
+        # @return [Array<ModelCard>, WithResponse]
         # @raise [TypeSafeError] the response shape is unexpected.
         # @raise [APIError] the server returns a non-2xx response after retries.
-        def list(**options)
+        def list(with_response: false, **options)
           response = @client.request(:get, "/v1/models", **options)
           wire = response.body
           unless wire.is_a?(Hash) && wire["models"].is_a?(Array)
@@ -23,7 +24,8 @@ module Typesafe
                   "Unexpected response shape from GET /v1/models; expected { models: [...] }."
           end
 
-          wire["models"].map { |card| ModelCard.new(card) }
+          result = wire["models"].map { |card| ModelCard.new(card) }
+          with_response ? WithResponse.new(result, response) : result
         end
       end
     end

data/lib/typesafe/sdk/retry.rb

@@ -38,15 +38,15 @@ module Typesafe
         return nil unless headers.respond_to?(:[])
 
         if (ms = headers["retry-after-ms"])
-          parsed = Integer(ms, exception: false)
-          return parsed if parsed && parsed >= 0
+          parsed = Float(ms, exception: false) unless ms.to_s.strip.empty?
+          return parsed if parsed&.finite? && parsed >= 0
         end
 
         raw = headers["retry-after"]
-        return nil if raw.nil?
+        return nil if raw.nil? || raw.to_s.strip.empty?
 
         seconds = Float(raw, exception: false)
-        return (seconds * 1000).round if seconds && seconds >= 0
+        return seconds >= 0 ? seconds * 1000 : nil if seconds&.finite?
 
         date = begin
           Time.parse(raw)

data/lib/typesafe/sdk/types.rb

@@ -2,6 +2,17 @@
 
 module Typesafe
   module SDK
+    # Parsed data together with HTTP metadata, like the JS SDK withResponse() result.
+    class WithResponse
+      attr_reader :data, :response, :request_id
+
+      def initialize(data, response)
+        @data = data
+        @response = response
+        @request_id = response.request_id
+      end
+    end
+
     # Token usage for a request.
     class Usage
       attr_reader :input_tokens, :output_tokens

data/lib/typesafe/sdk/version.rb

@@ -2,7 +2,8 @@
 
 module Typesafe
   module SDK
-    # Keep in sync with the gemspec version. Checked by the version consistency spec.
-    VERSION = "0.6.0"
+    # Ruby-only fixes use a fourth numeric component; the first three track upstream.
+    VERSION = "0.6.0.1"
+    UPSTREAM_VERSION = "0.6.0"
   end
 end