typesafe-sdk-ruby 0.6.0 → 0.7.0

data/docs/COMPATIBILITY.md

@@ -0,0 +1,119 @@
+# JavaScript SDK compatibility
+
+This unofficial Ruby client targets the official `@typesafe-ai/sdk` **0.7.0** release,
+commit [`b844cd1aca12855a5d24a2df52a1401c86e7d37a`](https://github.com/typesafe-ai/typesafe-sdk-js/tree/b844cd1aca12855a5d24a2df52a1401c86e7d37a).
+Audit date: 2026-10-16. This is a tested compatibility target, not a claim of endorsement
+or a guarantee about future API changes.
+
+## What is covered
+
+| Surface | Ruby behavior |
+| --- | --- |
+| Endpoints | `POST /v1/systemone`, `GET /v1/models` |
+| Defaults | `jev-latest`, 10-second attempt timeout, two retries |
+| Questions | Noul, choice, ordered score criteria, and box; structured instructions/state and nullable choice descriptions |
+| Images | `image`, `Image.from_base64`, images in content, `with_assets`/`join_assets` text, named `assets:`; multipart encoding, part names, content types, and reference validation |
+| Compression | zstd for bodies of 1 KiB or more (UTF-8 bytes), `compression: false`, protected `Content-Encoding`, same bytes on every retry |
+| Serialization | Non-finite floats sent as `"NaN"`, `"Infinity"`, `"-Infinity"`; the request is copied when the call starts |
+| Configuration | Explicit settings override trimmed environment values |
+| Retries | 408, 429, 500–599; connection and timeout failures independently configurable |
+| Server delays | Fractional milliseconds/seconds, HTTP dates, maximum delay and jitter |
+| Headers | Case-insensitive overrides; protected auth, content type, SDK and retry headers |
+| Errors | HTTP subclasses, validation messages, request IDs, connection/timeout/cancellation errors |
+| Transport | Timeout includes full body delivery; cancellation interrupts an active attempt and backoff; truncated bodies are retried |
+| Results | Typed answers (including box answers and nullable usage), `to_h` with unmodeled fields; model cards; `with_response: true` for HTTP metadata |
+| Extension fields | `extra_body:` forwards additional JSON fields without overriding named arguments |
+
+The checked-in `spec/fixtures/js-0.7.0.json` was generated by executing the published
+JavaScript package, rather than by copying expected output from the Ruby implementation.
+`parity_spec.rb` compares question JSON, request payloads (including non-finite numbers),
+multipart requests and parts with images in content, text, and named assets, `withAssets.join`
+text, asset validation messages, base64 decoding, compression thresholds, metadata, error
+mapping/messages, complete answer fields (including box answers, fractional scores, and string
+rubric keys), retry header parsing, and nullable retry flags. Image references are random, so
+the fixture replaces them with stable labels. `http_spec.rb` uses real loopback sockets to exercise behavior
+that mocked HTTP adapters cannot verify. Other specs cover Ruby configuration and logging.
+Known upstream bugs are corrected explicitly in the comparisons; the fixtures retain the
+original JS behavior for those cases.
+See the [issue-by-issue audit](UPSTREAM_ISSUES.md) for every upstream issue reviewed.
+
+To regenerate the fixtures with Node.js 22.15 or newer, unpack the official package
+(`npm pack @typesafe-ai/sdk@0.7.0`, or the asset from the
+[GitHub release](https://github.com/typesafe-ai/typesafe-sdk-js/releases/tag/v0.7.0)) and run:
+
+```sh
+node script/generate_parity_fixtures.cjs /path/to/package > spec/fixtures/js-0.7.0.json
+bundle exec rake
+```
+
+## Intentional Ruby differences and limits
+
+- Images: Ruby accepts a binary `String`, a `Pathname` (read when the request is sent, like a
+  JavaScript `Blob`), or an IO (read immediately, since it may not be readable twice). Ruby has
+  no tagged template literals, so `with_assets(*parts)` joins text and images given as separate
+  arguments, converting other values with `to_s` (`nil` becomes `""`, as in interpolation; the
+  JavaScript template writes `null`). A Hash or Array part is written with `to_s`, which includes
+  the references of images inside it, so those images are attached; JavaScript writes
+  `[object Object]` and attaches none. `join_assets` defaults to `","`, as `withAssets.join` does.
+- `assets:` must be a Hash of nonempty names to images; Ruby checks this before sending.
+  A request containing a cycle raises `TypeSafeError`; JavaScript raises a `TypeError`.
+- Compression needs the optional `zstd-ruby` gem; it is detected once per process, as JS
+  detects Node.js zstd support. `compression:` accepts `:zstd`, `"zstd"`, or `false`, and
+  `client.compression` returns `:zstd` or `false`.
+- JS 0.7.0 returns rejected promises instead of throwing for invalid requests. Ruby calls are
+  synchronous, so invalid requests and options raise `TypeSafeError` from the call, before any
+  image is read or request is sent.
+- Ruby keeps its 0.6.0.1 validation messages. JS 0.7.0 adds similar checks for nil state and
+  empty noul questions with its own wording, and both now reject non-Hash noul criteria.
+
+- Since 0.6.0.1, Ruby validates API keys without echoing their contents and rejects reported
+  API-invalid state/question shapes locally. Score levels must be non-nil and number 2–10;
+  choice options must number 1–255; noul requires instructions or an outcome description;
+  state must be a string, object, array, or image; question names cannot be empty.
+  Builders and raw question hashes use the same checks. This intentionally tightens the
+  JS 0.7.0 behavior, which still accepts nil score levels and unbounded score/choice sizes; local validation is not a complete server schema validator.
+- Blank retry headers fall back to configured backoff (or another valid delay header).
+  JS 0.7.0 still treats blanks as zero. Literal zero remains valid in Ruby.
+- Debug logs fully mask `x-api-key` and keep only an alphabetic authorization scheme followed
+  by a credential (upstream #18, unchanged in JS 0.7.0). Cloudflare HTML error pages get a
+  message naming the edge block and `cf-ray` ID (upstream #15).
+- HTTP 402, 409, and 413 have `PaymentRequiredError`, `ConflictError`, and
+  `PayloadTooLargeError` subclasses. Existing `APIError` rescue clauses still catch them.
+- Methods/options use snake_case. `timeout:` is in **seconds**; retry settings ending in
+  `_ms` remain milliseconds. `retry_policy:` corresponds to JavaScript's `retry` option.
+- Calls are synchronous. There is no JavaScript `Promise`, `AbortController`, or compile-time
+  inference. Ruby returns answer classes and accepts `Typesafe::SDK::Signal` for cancellation.
+- `with_response: true` returns `.data`, `.response`, and `.request_id`. The response exposes
+  `.status`, `.headers`, and an already parsed `.body`; it is not a Fetch response or stream.
+  Non-2xx responses still raise typed errors. Unlike JavaScript's `asResponse()`, these
+  resource methods always construct typed results; there is no unparsed Fetch body API.
+- `result[:question]` and `result["question"]` are both supported. `result.answers` itself
+  is a Hash with string keys, as received in JSON.
+- The noul builder serializes omitted criteria as JSON null; upstream omits the property.
+  Both are accepted by the upstream question type. Explicit criteria serialize identically.
+- The built-in transport opens one connection and one private worker per attempt. It closes
+  and joins them on completion, timeout, or cancellation. It does not pool connections or
+  implement a fiber-native asynchronous interface. Custom adapters own timeout/cancellation
+  enforcement and must implement the documented `HTTP#request` contract.
+- Net::HTTP does not follow redirects automatically; a 3xx raises `APIError`. Use the canonical
+  API URL. JavaScript Fetch may follow redirects.
+- Ruby's HTTP-date parser and JavaScript's Date parser may differ for malformed, non-HTTP dates.
+  Standard HTTP dates and the tested numeric forms are covered.
+
+## Live verification
+
+Offline tests do not prove account authentication, current model availability, billing, or
+production inference behavior. No live API key was available during this audit, so no live
+TypeSafe request was made.
+
+An explicit smoke test checks model listing and the noul, choice, and score answer types with
+synthetic input:
+
+```sh
+# Set TYPESAFE_API_KEY securely in your environment first.
+TYPESAFE_LIVE_TEST=1 bundle exec ruby script/smoke_test.rb
+```
+
+This makes one inference request, which may incur normal API charges. It does not retry or
+print the API key, input bodies, or full responses. Add `TYPESAFE_LIVE_IMAGES=1` for an account
+with image access to also send one image with a box question to `jev-preview`.

data/docs/RELEASING.md

@@ -0,0 +1,38 @@
+# Releasing
+
+Only the repository owner merges pull requests and initiates releases. Opening or merging
+a pull request does not publish a gem. Publication starts when the owner pushes a version tag.
+
+## Versions
+
+`Typesafe::SDK::UPSTREAM_VERSION` records the official JS compatibility target.
+`Typesafe::SDK::VERSION` is the Ruby package version and is the single source for the gemspec.
+
+- A new upstream port uses its exact three-part version, for example `0.7.0`.
+- Ruby-only corrections use a fourth numeric component, for example `0.6.0.1` and `0.6.0.2`.
+  These still target JS `0.6.0`; they do not imply an upstream `0.6.1` release.
+- Published versions and tags must not be replaced or reused. RubyGems accepts numeric
+  fourth-component versions as stable releases.
+
+Before a new upstream port, compare the tagged source and tests, update the compatibility
+document and generated fixtures, and run the suite. Version equality alone is not evidence
+of compatibility.
+
+## Owner checklist
+
+1. Review and merge the release pull request after all CI matrix jobs pass.
+2. Run the opt-in live smoke test described in [COMPATIBILITY.md](COMPATIBILITY.md).
+3. Set the changelog release date and update the README release-status notice in a reviewed
+   pull request before tagging.
+4. On the merged main commit, run `bundle exec rake`, `ruby script/check_release.rb`, and
+   `gem build typesafe-sdk-ruby.gemspec --strict`.
+5. Create and push the matching annotated tag, for example `v0.6.0.1`.
+6. Verify the Release workflow, RubyGems version, GitHub release, and attached gem artifact.
+
+The workflow rejects non-owner runs, tags that differ from the gem version, commits outside
+main's history, and upstream versions that do not match the official tagged package.
+It reruns tests and lint before publishing with the repository's `RUBYGEMS_API_KEY` secret.
+Keep that credential restricted to this gem. Required branch checks remain in force.
+
+If RubyGems publication succeeds but GitHub release creation fails, verify the published
+artifact before recovering the GitHub release; do not delete the tag or republish the version.

data/docs/UPSTREAM_ISSUES.md

@@ -0,0 +1,74 @@
+# Upstream issue audit
+
+Reviewed all **17 issues** in the official JavaScript repository's issue list, including their
+comments: the first 11 on **2026-09-21** against `@typesafe-ai/sdk` **0.6.0** (commit
+`66880cc`), with Ruby fixes in **0.6.0.1**, and #15–#20 on **2026-10-16** against **0.7.0**
+(commit `b844cd1aca12855a5d24a2df52a1401c86e7d37a`), with Ruby fixes in **0.7.0**. The issue
+page showed no closed issues; it does not show each issue's state, so the six new issues were
+checked individually and were open.
+
+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 |
+| --- | --- | --- |
+| [#20: 0.7.0 fails every request on Bun](https://github.com/typesafe-ai/typesafe-sdk-js/issues/20) | Bun/Fetch-specific; not applicable | The failure is in JS 0.7.0's Fetch body buffering under Bun. Ruby's Net::HTTP transport reads each body once in its own worker; real-socket tests cover body delivery, timeouts, and cancellation. |
+| [#19: custom `fetch` called with the client as `this`](https://github.com/typesafe-ai/typesafe-sdk-js/issues/19) | JavaScript-specific; not applicable | Ruby calls a custom `http:` adapter's `request` method on the adapter itself, so there is no receiver mismatch. |
+| [#18: secrets shown as an authorization scheme in logs](https://github.com/typesafe-ai/typesafe-sdk-js/issues/18) | Fixed locally | Ruby had the same logic. `x-api-key` values are always fully masked; authorization headers keep only an alphabetic scheme followed by a credential. `"sk-live-… x"` and `"TOKEN "` are no longer shown. Unchanged in JS 0.7.0. |
+| [#17: non-finite numbers serialized as null](https://github.com/typesafe-ai/typesafe-sdk-js/issues/17) | Matches JS 0.7.0 | Ruby 0.6.0.1 raised `JSON::GeneratorError`. Like JS 0.7.0, Ruby now sends `"NaN"`, `"Infinity"`, and `"-Infinity"` instead; the issue proposed rejecting them, and Ruby follows the released upstream behavior. |
+| [#16: token admission bounds and billing reconciliation](https://github.com/typesafe-ai/typesafe-sdk-js/issues/16) | Requires upstream API/documentation | There is no official tokenizer, token-count endpoint, or charge export to wrap. Ruby doesn't estimate tokens; `with_response: true` exposes the request ID and raw `usage` for reconciliation. |
+| [#15: Cloudflare HTML 403 for state containing shell commands](https://github.com/typesafe-ai/typesafe-sdk-js/issues/15) | Server-side; clearer Ruby error | The block happens before the API, so no client change can let these requests through. Ruby now names a Cloudflare HTML page and its `cf-ray` ID in the error message instead of quoting HTML. The class stays `PermissionDeniedError`, and the HTML stays in `body`. |
+| [#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; still accepted by JS 0.7.0 | 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; unchanged in JS 0.7.0 | 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; partly in JS 0.7.0 | Require string/object/array/image 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. JS 0.7.0 now rejects null state, empty noul questions, and empty or non-map choice criteria, but not the size bounds. |
+| [#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, and most still differ from JS 0.7.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.
+- [0.7.0 regressions](../spec/typesafe/sdk/release_0_7_spec.rb): non-finite numbers (#17),
+  credential redaction (#18), Cloudflare error pages (#15), and box/validation changes.
+- [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/assets.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "securerandom"
+
+module Typesafe
+  module SDK
+    # A PNG or JPEG image asset, created by {SDK.image} or {Image.from_base64}.
+    #
+    # Place it in `state`, question instructions, or criteria, join it into text with
+    # {SDK.with_assets}, or pass it in `assets:` under a name of your choice.
+    class Image
+      # The file signatures that PNG (PNG spec §5.2) and JPEG (ITU T.81 SOI marker) files start
+      # with, and the content type each identifies.
+      CONTENT_TYPES = [
+        ["image/png", "\x89PNG\r\n\x1A\n".b],
+        ["image/jpeg", "\xFF\xD8\xFF".b]
+      ].freeze
+
+      # The asset type sent to the API.
+      def type
+        "image"
+      end
+
+      # The frozen binary file bytes, or a `Pathname` read when the request is sent.
+      attr_reader :data
+
+      # @param data [String, Pathname, #read] file bytes, a path to read when the request is
+      #   sent, or an IO read now.
+      # @raise [TypeSafeError] `data` is empty, unreadable, or not a supported type.
+      def initialize(data)
+        @data = coerce(data)
+        size = @data.is_a?(Pathname) ? file_size(@data) : @data.bytesize
+        raise TypeSafeError, "Image data is empty." if size.zero?
+
+        @reference = "<image:#{SecureRandom.hex(16)}>".freeze
+      end
+
+      # Create an image from base64-encoded file bytes, decoding them now.
+      #
+      # @param text [String] the file bytes, base64-encoded, without a `data:` URL prefix.
+      #   ASCII whitespace and missing padding are accepted, as by JavaScript's `atob`.
+      # @raise [TypeSafeError] `text` isn't valid base64 or decodes to no bytes.
+      def self.from_base64(text)
+        raise TypeSafeError, "Image data must contain valid base64 text." unless text.is_a?(String)
+
+        # The forgiving-base64 decode that `atob` uses (WHATWG Infra Standard).
+        compact = text.b.delete(" \t\n\f\r")
+        compact = compact.sub(/={1,2}\z/, "") if (compact.length % 4).zero?
+        unless compact.match?(%r{\A[A-Za-z0-9+/]*\z}) && compact.length % 4 != 1
+          raise TypeSafeError, "Image data must contain valid base64 text."
+        end
+
+        new("#{compact}#{'=' * (-compact.length % 4)}".unpack1("m"))
+      end
+
+      # The bytes to send, reading `Pathname` data.
+      # @param name [String] the asset's name or reference, for error messages.
+      def read(name)
+        return @data unless @data.is_a?(Pathname)
+
+        File.binread(@data).freeze
+      rescue SystemCallError, IOError => e
+        raise TypeSafeError.new("Asset #{name.inspect} could not be read: #{e.message}", cause: e)
+      end
+
+      # The unique reference this image is sent under, for referencing it inside text.
+      def to_s
+        @reference
+      end
+
+      # The reference, written wherever the image appears in JSON.
+      def to_json(*args)
+        @reference.to_json(*args)
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} #{@reference}>"
+      end
+
+      # The content type whose signature `bytes` start with, or `application/octet-stream`.
+      def self.content_type_of(bytes)
+        CONTENT_TYPES.each { |type, signature| return type if bytes.b.start_with?(signature) }
+        "application/octet-stream"
+      end
+
+      private
+
+      def coerce(data)
+        case data
+        when String then data.b.freeze
+        when Pathname then data
+        else
+          unless data.respond_to?(:read)
+            raise TypeSafeError,
+                  "Image data must be file bytes (a String), a Pathname, or an IO; got #{data.class}."
+          end
+
+          bytes = data.read
+          raise TypeSafeError, "Image data read from #{data.class} must be a String." unless bytes.is_a?(String)
+
+          bytes.b.freeze
+        end
+      end
+
+      def file_size(path)
+        File.size(path)
+      rescue SystemCallError => e
+        raise TypeSafeError.new("Image file could not be read: #{e.message}", cause: e)
+      end
+    end
+
+    # Text from {SDK.with_assets} or {SDK.join_assets}, with the assets written into it.
+    class TextWithAssets
+      # The text, with each asset written as its reference.
+      attr_reader :text
+      # The assets written into the text, including those in nested `TextWithAssets`.
+      attr_reader :assets
+
+      def initialize(text, assets)
+        @text = text.dup.freeze
+        @assets = assets.dup.freeze
+      end
+
+      def to_s
+        @text
+      end
+
+      # The text, written wherever this value appears in JSON.
+      def to_json(*args)
+        @text.to_json(*args)
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} #{@text.inspect}>"
+      end
+
+      # Join `parts` into text, as an interpolated string would, and attach the assets among them.
+      def self.build(*parts)
+        attach(parts.map { |part| stringify(part) }.join, parts)
+      end
+
+      # Join `values` with `separator` and attach the assets among them.
+      def self.join(values, separator = ",")
+        values = values.to_a
+        attach(values.map { |value| stringify(value) }.join(separator.to_s), values)
+      end
+
+      # `text` with the assets in `values` whose references it contains, in order of appearance.
+      def self.attach(text, values)
+        interpolated = {}
+        collect(values, interpolated, {}.compare_by_identity)
+        assets = {}
+        text.scan(Assets::REFERENCE) do |reference|
+          asset = interpolated[reference]
+          assets[reference] = asset if asset
+        end
+        new(text, assets.values)
+      end
+
+      def self.stringify(value)
+        value.is_a?(TextWithAssets) ? value.text : value.to_s
+      end
+
+      # Add the images in `value`, including those in `TextWithAssets`, to `found` by reference.
+      def self.collect(value, found, visited)
+        case value
+        when Image then found[value.to_s] = value
+        when TextWithAssets then value.assets.each { |asset| found[asset.to_s] = asset }
+        when Hash, Array
+          return if visited.key?(value)
+
+          visited[value] = true
+          (value.is_a?(Hash) ? value.values : value).each { |item| collect(item, found, visited) }
+        end
+      end
+    end
+
+    # A `multipart/form-data` request body (RFC 7578) whose first part is a JSON payload.
+    class MultipartBody
+      # The JSON payload, sent as the `request` part.
+      attr_reader :payload
+      # The `Content-Type` header value, including the boundary.
+      attr_reader :content_type
+      # The encoded binary body.
+      attr_reader :content
+
+      # @param parts [Array<Hash>] `name`, `content_type`, `content`, and optional `filename`.
+      def initialize(payload, parts)
+        # A random boundary, as browsers use, is practically certain not to occur in the content.
+        boundary = SecureRandom.hex(16)
+        content = String.new(encoding: Encoding::BINARY)
+        [{ name: "request", content_type: "application/json", content: JSON.generate(payload) }, *parts]
+          .each do |part|
+          disposition = %(name="#{part[:name]}")
+          disposition += %(; filename="#{part[:filename]}") if part[:filename]
+          content << "--#{boundary}\r\nContent-Disposition: form-data; #{disposition}\r\n" \
+                     "Content-Type: #{part[:content_type]}\r\n\r\n".b << part[:content].b << "\r\n"
+        end
+        content << "--#{boundary}--\r\n"
+        @payload = payload
+        @content_type = "multipart/form-data; boundary=#{boundary}"
+        @content = content.freeze
+      end
+    end
+
+    # Request serialization and `multipart/form-data` encoding for assets.
+    module Assets
+      # Matches `Image#to_s`: the reference an image is sent under.
+      REFERENCE = /<image:[0-9a-f]{32}>/
+
+      module_function
+
+      # Validate `assets:` and return it with string names, preserving order.
+      def normalize(assets)
+        return {} if assets.nil?
+        raise TypeSafeError, "`assets` must be a Hash of names to images." unless assets.is_a?(Hash)
+
+        assets.each_with_object({}) do |(name, asset), normalized|
+          key = name.to_s
+          raise TypeSafeError, "Asset names must be nonempty." if key.empty?
+          unless asset.is_a?(Image)
+            raise TypeSafeError,
+                  "Asset #{key.inspect} must be an image created with Typesafe::SDK.image, got #{asset.class}."
+          end
+
+          normalized[key] = asset
+        end
+      end
+
+      # Serialize `payload` to JSON, writing each image as its name in `assets`, or else as its
+      # reference, and collect the assets the request sends.
+      #
+      # The assets are those in `assets`, then each image whose reference appears in the JSON, in
+      # order of appearance. Non-finite floats are sent as the strings `NaN`, `Infinity`, and
+      # `-Infinity`, as the JavaScript SDK does.
+      #
+      # @return [Array(String, Hash{String => Image}, nil)] the JSON and the assets to send.
+      # @raise [TypeSafeError] the payload holds a cycle, a reference of an image not attached to
+      #   the request, or doesn't contain the name of an image in `assets`.
+      def serialize_request(payload, assets = {})
+        # An image under several names is written as the last one.
+        names = {}.compare_by_identity
+        assets.each { |name, asset| names[asset] = name }
+        known = assets.values.to_h { |asset| [asset.to_s, asset] }
+        json = JSON.generate(prepare(payload, names, known, {}.compare_by_identity))
+
+        unreferenced = assets.keys.reject { |name| json.include?(JSON.generate(name)[1..-2]) }
+        unless unreferenced.empty?
+          raise TypeSafeError,
+                "Assets not referenced in the request: #{unreferenced.join(', ')}. " \
+                "Write each name in `assets` into `state`, question instructions, or criteria."
+        end
+
+        sent = assets.dup
+        missing = []
+        json.scan(REFERENCE) do |reference|
+          next if sent.key?(reference)
+
+          asset = known[reference]
+          asset ? sent[reference] = asset : missing << reference
+        end
+        unless missing.empty?
+          raise TypeSafeError,
+                "Image references without an attached image: #{missing.uniq.join(', ')}. " \
+                "Join images into text with Typesafe::SDK.with_assets instead of string interpolation."
+        end
+
+        [json, sent.empty? ? nil : sent]
+      end
+
+      # A JSON-ready copy of `value` with assets written as names or references.
+      def prepare(value, names, known, path)
+        case value
+        when Image
+          name = names[value]
+          return name if name
+
+          known[value.to_s] = value
+          value.to_s
+        when TextWithAssets
+          value.assets.reduce(value.text) do |text, asset|
+            name = names[asset]
+            known[asset.to_s] = asset unless name
+            name ? text.gsub(asset.to_s) { name } : text
+          end
+        when Float
+          value.finite? ? value : value.to_s
+        when Hash, Array
+          raise TypeSafeError, "The request contains a circular reference." if path.key?(value)
+
+          path[value] = true
+          begin
+            if value.is_a?(Hash)
+              value.to_h { |key, item| [key.to_s, prepare(item, names, known, path)] }
+            else
+              value.map { |item| prepare(item, names, known, path) }
+            end
+          ensure
+            path.delete(value)
+          end
+        else
+          value
+        end
+      end
+
+      # A multipart body whose `request` part is `payload` with `assets` added, followed by each
+      # asset's file bytes in its own part. The API accepts each part for only one asset, so an
+      # image under several references is sent once per reference.
+      #
+      # @raise [TypeSafeError] a `Pathname` image can't be read.
+      def encode(payload, assets)
+        parts = []
+        entries = {}
+        assets.each do |name, asset|
+          bytes = asset.read(name)
+          part = "asset-#{parts.length}"
+          parts << { name: part, content_type: Image.content_type_of(bytes), content: bytes, filename: part }
+          entries[name] = { "type" => asset.type, "part" => part }
+        end
+        MultipartBody.new(payload.merge("assets" => entries), parts)
+      end
+    end
+  end
+end