typesafe-sdk-ruby 0.6.0 → 0.6.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2f7c356ecf7107179e8d01aeec562af105267ef4fc640b9a95a8d0c0904413f
-  data.tar.gz: 5a7657f8bc722b9c7ecae8f126b7792b2911b08bbc006a54114f16fb0bf73bb3
+  metadata.gz: a081c1995e40528b73408af6b6188d0c9784b497de463b2821694e6a1a895c81
+  data.tar.gz: 7c7363485285de50ef55a68dfe3f6606e3c0a08f0f41133fbb182010626144bc
 SHA512:
-  metadata.gz: 62fd70fb931ccaae55504bb8ed8db5b674e347978704d938a178003e339c0061ed8f4f5de62574298471dd29b21369e6a82cf8d549985cf9e0e8c22781299a1d
-  data.tar.gz: ac8620432b7afd9cb36ec5e1a64b16fe3709590c3597234401cc71ab797558676441034af33b4b17ff4f650082a7f7627579dba5248db0a98c1ca5b734a48e04
+  metadata.gz: 26a637c0d1fc8afb9f29e20ab2860d287d12491c6a93c7c28c2db574adce747abba8c60eae1d70cff7efd3610b08db1f9ea0fdf4d727c58aeaee08cc12c35811
+  data.tar.gz: 1e9bfee179126a48aa3f640b87149f9af99a8e47c03bb13d29c2d550a520522e98496ceeabd63aa9949fced46f242cc600133c34aab5685b74a23ecfd47a14a5

data/CHANGELOG.md

@@ -3,7 +3,50 @@
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Versions follow the official JavaScript SDK, with a fourth numeric component for Ruby-only
+corrections. See [RELEASING.md](docs/RELEASING.md).
+
+## [0.6.0.1] - 2026-09-21
+
+Compatibility target: official JavaScript SDK 0.6.0, commit `66880cc`.
+
+### Fixed
+
+- Reject malformed/blank API keys at construction without including credentials in errors
+  (upstream #14); trim surrounding spaces and line endings.
+- Validate state types, meaningful noul questions, score/choice bounds, and empty question
+  names before HTTP requests (upstream #6).
+- Reject nil score levels without dropping or renumbering positions; document an explicit
+  empty string for an undescribed position (upstream #12).
+- Fall back to configured backoff for blank retry headers while preserving explicit zero
+  and valid alternate headers (upstream #9).
+
+- Match upstream fallback error messages when API error fields are empty strings.
+- Treat nil retry flags as inherited settings, while keeping explicit false overrides.
+- Enforce the timeout across the entire HTTP attempt, including slow response bodies.
+- Interrupt active requests on cancellation and close/join the request worker before returning.
+- Disable Net::HTTP's implicit retries; detect truncated response bodies as connection errors.
+- Support Ruby/Rails loggers when debug or error details are present.
+- Validate JSON-loaded score questions and reject infinite/NaN/complex timeout and backoff values.
+- Preserve fractional server retry delays; capture HTTP-date rate-limit delays once.
+- Freeze copied retry status overrides to prevent accidental policy mutation.
+- Preserve upstream license attribution and remove the misleading official-company contact.
+
+### Added
+
+- `PaymentRequiredError` (402), `ConflictError` (409), and `PayloadTooLargeError` (413),
+  retaining `APIError` inheritance and existing retry defaults (upstream #13).
+- An audit of all 11 upstream issues, numeric-label coverage, subprocess cancellation checks,
+  and real-socket timeout tests around Node's timer limit (upstream #2, #4, #8).
+
+- Complete answer and nullable retry flag comparisons against the published JS package.
+- README onboarding, primitive/confidence examples, JS-to-Ruby mapping, and support routes.
+- `with_response: true` on inference and model listing for data, HTTP metadata, and request ID.
+- `extra_body:` for additional inference fields, including explicit null values.
+- Fixtures generated by executing the published JS SDK, real socket regression tests, and an
+  opt-in live API smoke test.
+- A single gem version source, explicit `UPSTREAM_VERSION`, release validation, packaged-gem
+  CI checks, Ruby 4.0 coverage, and compatibility/release documentation.
 
 ## [0.6.0] - 2026-09-20
 

data/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2026 TypeSafe Ruby SDK Contributors
+Copyright (c) 2026 TypeSafe (upstream JavaScript SDK)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -4,37 +4,42 @@
 [![CI](https://github.com/afurm/typesafe-sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/afurm/typesafe-sdk-ruby/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-**Community-maintained, unofficial** Ruby SDK for [TypeSafe AI](https://typesafe.ai). Ask named
-questions about text or structured state and get typed answers back: yes/no (noul), choice, and
-score questions — with retries, timeouts, structured logging, and typed errors.
+A community-maintained Ruby client for [TypeSafe AI](https://typesafe.ai), with typed answer
+objects, retries, timeouts, cancellation, and configurable logging.
 
-> This gem is not affiliated with, endorsed by, or supported by TypeSafe AI. It is a faithful
-> community port of the official [JavaScript SDK](https://github.com/typesafe-ai/typesafe-sdk-js).
-> Official SDKs: [JavaScript](https://github.com/typesafe-ai/typesafe-sdk-js) and Python.
+TypeSafe's Jev model evaluates state against questions defined by your application. It returns
+structured decisions that your code can use for classification, ranking, and routing.
+Read the [official introduction](https://docs.typesafe.ai/introduction) for the product model.
 
-> **Versioning:** gem versions intentionally mirror the official JavaScript SDK so it is
-> obvious which upstream release each port tracks (e.g. gem 0.6.0 ≈ JS SDK 0.6.0).
+**Unofficial:** this project is not affiliated with, endorsed by, or supported by TypeSafe AI.
+It targets the official [JavaScript SDK](https://github.com/typesafe-ai/typesafe-sdk-js)
+**0.6.0**. Official [JavaScript and Python SDKs](https://docs.typesafe.ai/sdk) are maintained
+by TypeSafe AI.
 
-## Requirements
-
-- Ruby 3.1 or newer
-- A TypeSafe API key (`TYPESAFE_API_KEY`)
+**Version:** this README documents Ruby **0.6.0.1**, targeting JS **0.6.0**.
+Ruby-only corrections add a fourth version component. Check
+[RubyGems](https://rubygems.org/gems/typesafe-sdk-ruby) and
+[GitHub releases](https://github.com/afurm/typesafe-sdk-ruby/releases) for published versions;
+merging changes into `main` does not publish a gem. See the [changelog](CHANGELOG.md)
+for changes and migration notes.
 
 ## Installation
 
-Install the gem:
+Requires Ruby **3.1 or newer**; CI tests Ruby 3.1, 3.2, 3.3, 3.4, and 4.0.
 
 ```sh
 gem install typesafe-sdk-ruby
 ```
 
-Or add it to your application's `Gemfile`:
+For Bundler, add the gem to your application's `Gemfile` and run `bundle install`:
 
 ```ruby
 gem "typesafe-sdk-ruby"
 ```
 
-and run `bundle install`.
+Create an API key in the [TypeSafe console](https://console.typesafe.ai/), then set
+`TYPESAFE_API_KEY` in your environment or application secret store. The SDK reads it
+automatically. See the [official quick start](https://docs.typesafe.ai/introduction/quickstart).
 
 ## Quickstart
 
@@ -42,159 +47,304 @@ and run `bundle install`.
 require "typesafe-sdk-ruby"
 
 client = Typesafe::SDK::Client.new
-
 response = client.system_one(
   state: { document: "I was charged twice. Please fix this ASAP." },
   questions: {
     category: Typesafe::SDK.choice("What is this ticket about?", {
-      billing: nil,
-      technical: nil,
-      other: nil,
+      billing: "Payments, invoices, or refunds",
+      technical: "A product error or technical problem",
+      other: "A different subject",
     }),
   },
 )
 
-puts response.answers["category"].choice
+category = response[:category]
+puts category.choice
+puts category.confidence
+puts category.probabilities
+puts response.model
+puts response.usage.input_tokens
 ```
 
-Answer objects are typed by the question that produced them:
+`response[:category]` and `response["category"]` work interchangeably.
+`response.answers` is a regular Hash with string keys.
+
+## Choosing a question type
 
-| Question | Answer class | Key fields |
+| Builder | Use it for | Result |
 | --- | --- | --- |
-| `noul` | `Typesafe::SDK::NoulResponse` | `noul` (probability of yes) |
-| `choice` | `Typesafe::SDK::ChoiceResponse` | `choice`, `confidence`, `probabilities` |
-| `score` | `Typesafe::SDK::ScoreResponse` | `score`, `confidence`, `legend`, `probabilities` |
+| `noul` | A yes/no judgment | `noul`: probability of yes, from 0 to 1 |
+| `choice` | Selecting one named option | `choice`, `probabilities`, `confidence` |
+| `score` | Rating against ordered descriptions | `score`, `legend`, `probabilities`, `confidence` |
+
+Mix question types in a single call. Each question is evaluated against the same state,
+independently of the other questions. Put the meaning in the instructions and criteria;
+question IDs identify answers and are not used for inference.
+See [primitives](https://docs.typesafe.ai/primitives) and the [API reference](https://docs.typesafe.ai/api).
+
+```ruby
+response = client.system_one(
+  state: "The export fails in Safari, but I can finish the task in Firefox.",
+  questions: {
+    workaround: Typesafe::SDK.noul("Does the user describe a working alternative?"),
+    category: Typesafe::SDK.choice("Which area is affected?", {
+      export: "Exporting application data",
+      login: "Signing in to the application",
+      other: "Another area",
+    }),
+    severity: Typesafe::SDK.score("How much does this issue affect the user's task?", [
+      "The task works; only its appearance is affected",
+      "The task needs an alternative method to complete",
+      "The task cannot be completed",
+    ]),
+  },
+)
+
+puts response[:workaround].noul
+puts response[:severity].score
+puts response[:severity].probabilities["1"]
+puts response[:severity].legend["1"]
+```
+
+Score criteria are an **ordered array**, with positions starting at zero. A returned score
+is a probability-weighted mean and can be fractional. `legend` and `probabilities` retain
+string keys such as `"0"` and `"1"`. See the [Score guide](https://docs.typesafe.ai/primitives/score).
+
+State, instructions, and criterion descriptions can also contain JSON objects or arrays.
+Optional noul criteria can describe either outcome:
+
+```ruby
+question = Typesafe::SDK.noul("Is this an explicit cancellation request?", criteria: {
+  true: "The customer asks to end the subscription",
+  false: "The customer only asks about cancellation terms",
+})
+```
+
+See [structured questions](https://docs.typesafe.ai/primitives/advanced) for more examples.
+
+From Ruby **0.6.0.1**, builders and raw question hashes are checked before sending:
+
+- State must be a string, object, or array; `nil` is rejected, while `""`, `{}`, and `[]` are allowed.
+- Noul needs instructions or at least one non-nil true/false outcome description.
+- Score needs **2–10** levels. A nil level is rejected; use `""` explicitly to keep an
+  undescribed position. The SDK never drops or renumbers levels.
+- Choice needs **1–255** options. Nil descriptions remain valid for choice labels.
+- Question names must not be empty strings.
+
+Failures raise `Typesafe::SDK::TypeSafeError` without an HTTP request. These checks address
+request shapes reported as rejected by the API, even though JS 0.6.0 accepts them locally.
+See the [upstream issue audit](docs/UPSTREAM_ISSUES.md) for evidence and limitations.
+
+## Using confidence
+
+Choice and Score include confidence derived from their probability distributions. Confidence
+is distinct from the probability of the selected option and is not a guarantee of correctness.
+Noul returns the probability of yes and has no separate confidence field.
+See the [official confidence guide](https://docs.typesafe.ai/confidence).
+
+```ruby
+category = response[:category]
+threshold = 0.8 # Illustrative: evaluate a suitable threshold on your own labeled examples.
+puts(category.confidence >= threshold ? "Route to #{category.choice}" : "Needs review")
+```
 
 ## Configuration
 
 Explicit options take precedence over environment variables, then SDK defaults.
+Blank environment values are ignored for optional settings. An API key is required.
+From Ruby 0.6.0.1, outer spaces, tabs, and line endings are trimmed from keys; blank keys,
+non-ASCII text, embedded whitespace, and control characters raise `TypeSafeError` at
+construction. Error messages do not include the key.
 
 | Option | Environment variable | Default |
 | --- | --- | --- |
-| `api_key:` | `TYPESAFE_API_KEY` | — (required) |
+| `api_key:` | `TYPESAFE_API_KEY` | Required |
 | `base_url:` | `TYPESAFE_BASE_URL` | `https://api.typesafe.ai` |
 | `default_model:` | `TYPESAFE_DEFAULT_MODEL` | `jev-latest` |
 | `log_level:` | `TYPESAFE_LOG_LEVEL` | `warn` |
 
 ```ruby
 client = Typesafe::SDK::Client.new(
-  api_key: "sk-...",
-  base_url: "https://api.typesafe.ai",
-  default_model: "jev-latest",
-  log_level: :info,          # :debug, :info, :warn, :error, :off
-  timeout: 10,               # seconds per attempt
+  timeout: 10, # Seconds per attempt, including connection setup and response body receipt.
   retry_policy: { max_retries: 2, backoff_initial_ms: 500 },
-  default_headers: { "X-My-Header" => "value" },
+  log_level: :info, # :debug, :info, :warn, :error, or :off
+  default_headers: { "X-My-App" => "support" },
 )
 ```
 
+`jev-latest` is a moving alias. For reproducible deployments, select an explicit model from
+`client.models.list` and set `default_model:` or a per-call `model:`. See
+[available models and aliases](https://docs.typesafe.ai/models).
+
 ## Retries and timeouts
 
-The SDK retries HTTP `408`, `429`, and `5xx` responses plus connection failures and timeouts,
-with capped exponential backoff and jitter. It honors `Retry-After` and `retry-after-ms`
-headers up to a cap. Every option is overridable per client or per call:
+By default, the SDK retries HTTP 408, 429, and 5xx responses, connection failures, and timeouts,
+with up to two retries after the initial attempt. Backoff starts at 500 ms, doubles up to
+5,000 ms, and uses up to 25% downward jitter. Server `Retry-After` and `retry-after-ms` delays
+are honored up to 60,000 ms; larger delays fall back to backoff. From Ruby 0.6.0.1, blank
+or malformed delay headers also fall back to backoff; an explicit zero remains valid.
+A blank `retry-after-ms` still permits a valid `Retry-After` header to be used.
+
+Each attempt receives a fresh timeout, so total call time can include several attempts and
+backoff. Override settings per client or per call:
 
 ```ruby
 client.system_one(
-  state: "...",
-  questions: { ... },
+  state: "A refund request",
+  questions: { billing: Typesafe::SDK.noul("Is this about billing?") },
   timeout: 30,
-  retry_policy: { max_retries: 0 },  # disable retries for this call
+  retry_policy: { max_retries: 0 },
 )
 ```
 
+The full retry policy supports `max_retries`, `backoff_initial_ms`, `backoff_max_ms`,
+`backoff_jitter`, `http_statuses`, `respect_retry_after`, `max_retry_after_ms`,
+`api_connection_error`, and `api_timeout_error`. Overrides merge field by field.
+Nil boolean flags inherit the existing setting; explicit `false` disables that behavior.
+
 ## Error handling
 
 ```ruby
 begin
-  client.system_one(state: "...", questions: { ... })
+  client.system_one(
+    state: "A refund request",
+    questions: { billing: Typesafe::SDK.noul("Is this about billing?") },
+  )
 rescue Typesafe::SDK::RateLimitError => e
-  retry_after e.retry_after_ms
+  warn "Rate limited; suggested retry delay: #{e.retry_after_ms.inspect}ms"
 rescue Typesafe::SDK::APIError => e
-  warn "API error #{e.status} (request #{e.request_id}): #{e.body}"
+  warn "API error #{e.status}; request ID: #{e.request_id}"
+rescue Typesafe::SDK::APIConnectionError => e
+  warn e.message
 end
 ```
 
-Error hierarchy:
+Errors reach your code after any configured retries. All SDK errors inherit from
+`Typesafe::SDK::TypeSafeError`:
+
+| Error | Meaning |
+| --- | --- |
+| `BadRequestError` | HTTP 400 |
+| `AuthenticationError` | HTTP 401 |
+| `PaymentRequiredError` | HTTP 402; added in 0.6.0.1 |
+| `PermissionDeniedError` | HTTP 403 |
+| `NotFoundError` | HTTP 404 |
+| `ConflictError` | HTTP 409; added in 0.6.0.1 |
+| `PayloadTooLargeError` | HTTP 413; added in 0.6.0.1 |
+| `UnprocessableEntityError` | HTTP 422 |
+| `RateLimitError` | HTTP 429; exposes `retry_after_ms` |
+| `InternalServerError` | HTTP 5xx |
+| `APIError` | Other non-2xx responses; exposes status, headers, body, and request ID |
+| `APIConnectionError` | Connection or response-body delivery failure |
+| `APITimeoutError` | Subclass of `APIConnectionError`; exposes `timeout_ms` |
+| `APIUserAbortError` | Caller cancellation; never retried |
+
+## Response metadata and additional fields
+
+Added for Ruby **0.6.0.1**:
+
+```ruby
+result = client.system_one(
+  state: "A refund request",
+  questions: { billing: Typesafe::SDK.noul("Is this about billing?") },
+  with_response: true,
+)
+puts result.data[:billing].noul
+puts result.request_id
+puts result.response.status
+```
 
-- `Typesafe::SDK::TypeSafeError` — base class
-  - `Typesafe::SDK::APIError` — non-2xx HTTP responses
-    - `BadRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError` (403),
-      `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitError` (429),
-      `InternalServerError` (5xx)
-  - `Typesafe::SDK::APIConnectionError` — DNS, TLS, connection failures
-    - `Typesafe::SDK::APITimeoutError`
-  - `Typesafe::SDK::APIUserAbortError` — caller cancellation
+`client.models.list(with_response: true)` wraps the model cards the same way. The response
+exposes case-insensitive `headers` and a parsed `body`.
+`extra_body: { new_option: nil }` forwards additional JSON fields; named `state`, `questions`,
+and `model` arguments take precedence. The API decides whether a field is supported.
 
 ## Cancellation
 
 ```ruby
 signal = Typesafe::SDK::Signal.new
-Thread.new { sleep 5; signal.cancel }
-
-client.system_one(state: "...", questions: { ... }, signal: signal)
-# raises Typesafe::SDK::APIUserAbortError once canceled
+canceller = Thread.new { sleep 5; signal.cancel }
+begin
+  client.system_one(
+    state: "A refund request",
+    questions: { billing: Typesafe::SDK.noul("Is this about billing?") },
+    signal: signal,
+  )
+rescue Typesafe::SDK::APIUserAbortError
+  warn "Request canceled"
+ensure
+  canceller.kill.join
+end
 ```
 
+From Ruby 0.6.0.1, cancellation interrupts active requests and retry backoff, and cleans up
+the request worker and socket before returning.
+
 ## Listing models
 
 ```ruby
 client.models.list.each do |model|
-  puts "#{model.name}: #{model.description}"
+  puts "#{model.name}: #{model.description} (#{model.release_date})"
 end
 ```
 
-## Logging
+## Logging and Rails
 
-The default logger writes to `$stderr` with a `[typesafe-sdk-ruby]` prefix. `info` logs request
-summaries; `debug` adds headers (credentials redacted) and bodies. Pass any object responding
-to `debug`/`info`/`warn`/`error`:
+The default logger writes to `$stderr` with a `[typesafe-ai]` prefix. `info` includes request
+summaries; `debug` adds redacted credential headers and request/response bodies. Bodies may
+contain application data and are **not** redacted.
+
+From Ruby 0.6.0.1, standard Ruby `Logger` and `Rails.logger` also accept debug details:
 
 ```ruby
-client = Typesafe::SDK::Client.new(logger: Rails.logger, log_level: :info)
+# config/initializers/typesafe.rb; configure TYPESAFE_API_KEY through your secret store.
+TYPESAFE = Typesafe::SDK::Client.new(logger: Rails.logger, log_level: :info)
 ```
 
-## Ruby on Rails
+Call `TYPESAFE.system_one(...)` from application code. In plain Ruby, use
+`require "logger"` and pass `logger: Logger.new($stderr)`; add the `logger` gem to your
+application if your Ruby version does not provide it by default.
 
-The gem is framework-agnostic and works out of the box in Rails. A common pattern is a
-wrapped initializer:
+## Coming from JavaScript
 
-```ruby
-# config/initializers/typesafe.rb
-TYPESAFE = Typesafe::SDK::Client.new(log_level: :info)
-```
+| JavaScript | Ruby |
+| --- | --- |
+| `new TypeSafeClient()` | `Typesafe::SDK::Client.new` |
+| `systemOne(request, options)` | `system_one(state:, questions:, **options)` |
+| `apiKey`, `baseURL`, `defaultModel` | `api_key:`, `base_url:`, `default_model:` |
+| `timeout` in milliseconds | `timeout:` in seconds |
+| `retry: { maxRetries: 0 }` | `retry_policy: { max_retries: 0 }` |
+| `.withResponse()` | `with_response: true` (Ruby 0.6.0.1+) |
+| `AbortController` | `Typesafe::SDK::Signal` |
+| `answers.category` | `response[:category]` or `response.answers["category"]` |
 
-```ruby
-# app/models/concerns/typesafe_classifiable.rb
-module TypesafeClassifiable
-  def classify(text)
-    TYPESAFE.system_one(
-      state: text,
-      questions: {
-        category: Typesafe::SDK.choice("Category?", {
-          billing: nil, technical: nil, other: nil,
-        }),
-      },
-    ).answers["category"].choice
-  end
-end
-```
+Ruby calls are synchronous and return Ruby answer objects. They do not provide TypeScript
+compile-time inference, Fetch streams, connection pooling, or automatic redirect following.
+See [tested compatibility and intentional differences](docs/COMPATIBILITY.md).
 
-## Development
+## Development and contributing
 
 ```sh
 bundle install
-bundle exec rake        # specs + RuboCop
-bundle exec rspec       # specs only
-bundle exec rubocop     # lint only
+bundle exec rake # Tests and RuboCop; no API key or external API calls required.
 ```
 
-## Contributing
+Native transport tests bind loopback sockets. CI also builds and installs the packaged gem.
+For an explicit live check, follow [live verification](docs/COMPATIBILITY.md#live-verification).
+The [demo](examples/demo.rb) uses real API calls and can be run with
+`bundle exec ruby examples/demo.rb` after configuring your key.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), the [PR template](.github/PULL_REQUEST_TEMPLATE.md),
+and the [release process](docs/RELEASING.md). Changes are reviewed and merged by the repository owner.
+
+## Support and security
 
-Bug reports and pull requests are welcome on
-[GitHub](https://github.com/afurm/typesafe-sdk-ruby/issues). See
-[CONTRIBUTING.md](CONTRIBUTING.md).
+Use [issues](https://github.com/afurm/typesafe-sdk-ruby/issues) for Ruby client bugs and
+[discussions](https://github.com/afurm/typesafe-sdk-ruby/discussions) for usage questions.
+See [SUPPORT.md](SUPPORT.md) for API/account questions and useful report details.
+Report vulnerabilities privately using [SECURITY.md](SECURITY.md).
+All participation follows our [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](LICENSE).
+[MIT](LICENSE), including attribution to the upstream TypeSafe JavaScript SDK.

data/docs/COMPATIBILITY.md

@@ -0,0 +1,89 @@
+# JavaScript SDK compatibility
+
+This unofficial Ruby client targets the official `@typesafe-ai/sdk` **0.6.0** release,
+commit [`66880ccded6cb642dc1809620c2b108c33730214`](https://github.com/typesafe-ai/typesafe-sdk-js/tree/66880ccded6cb642dc1809620c2b108c33730214).
+Audit date: 2026-09-21. 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; structured instructions/state and nullable choice descriptions |
+| 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 and usage; 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.6.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, metadata, error mapping/messages,
+complete answer fields (including fractional scores and string rubric keys), retry header
+parsing, and nullable retry flags. `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, download the official release asset from
+[GitHub](https://github.com/typesafe-ai/typesafe-sdk-js/releases/tag/v0.6.0), unpack it, and run:
+
+```sh
+node script/generate_parity_fixtures.cjs /path/to/package > spec/fixtures/js-0.6.0.json
+bundle exec rake
+```
+
+## Intentional Ruby differences and limits
+
+- Ruby 0.6.0.1 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, or array; question names cannot be empty.
+  Builders and raw question hashes use the same checks. This intentionally tightens the
+  permissive JS 0.6.0 behavior; local validation is not a complete server schema validator.
+- Blank retry headers fall back to configured backoff (or another valid delay header).
+  JS 0.6.0 incorrectly treats blanks as zero. Literal zero remains valid in Ruby.
+- 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 all three 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.

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.