fast-completions 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b689b98f53f49ee1e7dcf541b2339f24683d34c6b8331994764ddffc0bdb86df
-  data.tar.gz: 815c13df95de3782a8dfd8303d3ad50173fd9c0d5c8795fa8cdd7fc9173df8c6
+  metadata.gz: 5741f8a7684abbb66479904f8b49d14afebfd783cf3069e2e2c91717a0765238
+  data.tar.gz: 1a20474b48f9278d815b1561101a34cc229ac37c1cfcaeb83ffe9f1ba5bbcf9a
 SHA512:
-  metadata.gz: 5025050d712a676ac2bb5972506260cc63fa4aaff9ca47d20409e18a9ea756b0096deeea9a5168729d5f3757bf03820a88c680107e718d097946b52b0c3ae9dc
-  data.tar.gz: 4715c20690b34fc1d569a9b41ff9f291f3c110d32ed66daa9945989f54b18f53de09b265f6d7c1c11815b0f95201327a3627339968ebe2b0b0f37fbc89468317
+  metadata.gz: bae0596f622cdee7289c271939aca77dc8e10d539aeed94b8c18388ad445957db4b19beb45a6359da7c971d3173d24e42ca917720499cfd081b398fd4e70f3ec
+  data.tar.gz: 30d7cc0ac12964163ca196e3e6a87e2e9e150de3db334ad342d55d923b55f0c522073108def6618c727a78593c5fb5d67f90d2e6d3267e794753575d9ab36bfe

data/CHANGELOG.md

@@ -3,6 +3,81 @@
 Notable changes to the fast-completions gem. The format is prose-first,
 one section per released version, newest first.
 
+## 0.4.0 (2026-10-14)
+
+- Strict-sampling tool schemas (pi constrained-sampling, JSON-schema half):
+  tools declare `constrained_sampling` — `false` (explicit opt-out) or
+  `{"type" => "json_schema", "strict" => "prefer"|"require"}`; any other
+  shape raises `ArgumentError` at declaration (grammar-constrained sampling
+  stays out of scope — `type: "grammar"` raises). On a dialect declaring
+  `supports_strict_mode`, a declared tool ships the strict rewrite of its
+  parameters — every property required, non-required null-less properties
+  wrapped in an `anyOf` of the property and `{"type": "null"}`,
+  `additionalProperties: false` appended — with `"strict": true` right after
+  `parameters`; every other function tool on a strict dialect ships
+  `"strict": false` with parameters verbatim (the declared Hash is never
+  mutated — the rewrite deep-copies); tools on non-strict dialects carry no
+  strict key ever, parameters verbatim. `"prefer"` falls back to verbatim
+  silently when the schema is unsupportable; `"require"` raises the new
+  `ConstrainedSamplingError` with pi's message templates. The Dialect
+  vocabulary grows to 14 keys (`supports_strict_mode`, default `false` —
+  OpenAI compatibility alone does not imply strict tool support); the
+  shipped `:zai` declares `true` (pi's glm compat).
+
+## 0.3.0 (2026-10-15)
+
+- Mid-stream salvage: a failure after a 2xx status — a mid-body connection
+  abort, the network-error family, or any other exception except
+  cancellation — no longer discards the streamed work. The client yields the
+  `:error` terminal event FIRST, carrying the live partial (every streamed
+  block and the usage so far; a thinking block's streamed
+  `reasoning_details` are serialized into its signature exactly as finalize
+  would) with no block-end events after the failure, then raises
+  (`ConnectionError` for the network family, message form preserved;
+  anything else re-raised unchanged). Creation-phase failures (non-2xx
+  after the retry decision, network failures with retries exhausted) yield
+  the same `:error` event — the accumulator still empty, `:start` still not
+  emitted — before their mapped raise.
+- Request-creation retry: the POST — creation through status receipt,
+  structurally pre-first-body-byte — now retries bounded at ONE retry by
+  default (constructor `max_retries:`, integer ≥ 0; `0` restores the single
+  attempt), exactly on pi's provider-retry trigger classes: header
+  `x-should-retry: true` (any status) retries; `x-should-retry: false` is
+  final even on 429/5xx; statusless errors (network failures during the
+  POST, a TTFB watchdog fire) retry; 408/409/429/5xx retry; every other
+  status is final. Never after a 2xx — a mid-body failure salvages instead,
+  making exactly one request. Cancellation is never retried; retries are
+  immediate (backoff out of scope); a retried TTFB deadline re-arms per
+  attempt and the final failure still surfaces `TimeoutError`, never
+  `CancelledError`.
+- Outgoing-string scrub (I62): every string the codec emits onto the wire
+  params passes through a `String#scrub { "" }` deletion scrub (pi
+  `sanitizeSurrogates`) at each emission point — the leading instructions
+  and system content, user strings and text parts, the assistant's joined
+  text and reasoning-field text, tool-result content, and the string
+  values inside tool-call `arguments` (deep). Malformed bytes (lone
+  surrogates, CESU-8 pairs, any invalid UTF-8 — Ruby's class is broader
+  than JS's) are DELETED, never replaced with U+FFFD, so
+  `JSON.generate` over a built request no longer raises
+  `GeneratorError` from message content. Valid strings pass
+  byte-identical — the canonical wire fixtures are untouched.
+- `Message#stop_reason` (I62): nil-default replay metadata with no
+  vocabulary validation; `to_h` emits the key only when set, `from_h`
+  round-trips it, and the assistant factory accepts it.
+  `Codec.normalize` skips assistants whose `stop_reason` is `:error` or
+  `:aborted` entirely on replay (pi transform-messages): their tool calls
+  never become pending orphans and never synthesize results, while a
+  previous valid assistant's unanswered calls still do and surrounding
+  user/system messages are unaffected. Histories without errored rows
+  are byte-unaffected.
+- Tool-call index-map backfill (I62): a tool-call fragment that resolves
+  its block by id (or creation) while carrying an `index` now binds the
+  block into the accumulator's index map (pi openai-completions :536-539)
+  — first index wins, one index per block, ever — so the
+  `{id, name}` → `{id, index, args}` → `{index, args}` fragment shape
+  assembles ONE tool call instead of a spurious second block. Boundness
+  is tracked accumulator-side; no scratch keys leak onto message blocks.
+
 ## 0.2.0 (2026-10-15)
 
 - Tolerant inbound stream (I61): a malformed SSE chunk no longer kills

data/lib/fast/completions/client.rb

@@ -11,6 +11,10 @@ module Fast
     # its own (§6).
     class Client
       DEFAULT_TIMEOUT = 30
+      # Bounded creation retry (I62, Grounds R2): ONE retry (two attempts)
+      # by default so a transient 429/5xx/connection refusal no longer
+      # kills the turn; `max_retries: 0` restores the single attempt.
+      DEFAULT_MAX_RETRIES = 1
 
       # TTFB deadline + inactivity read-timeout watchdog (D5/OQ-1): one
       # value serves both. A fire cancels the waiting task; `fired` tells
@@ -26,9 +30,13 @@ module Fast
         attr_reader :fired
 
         # (Re)arm: TTFB deadline before the POST, re-armed as the
-        # inactivity read-timeout after every body chunk.
+        # inactivity read-timeout after every body chunk. The fired flag
+        # resets with the timer: a retried attempt (I62) must not inherit
+        # the previous attempt's fire, or the post-stream guard and the
+        # cancel-vs-fired discipline would misread attempt 2 (D5/D8).
         def arm
           stop
+          @fired = false
           @timer = Async do
             sleep @seconds
             @fired = true
@@ -47,12 +55,15 @@ module Fast
         Errno::ENETUNREACH, Errno::ETIMEDOUT, EOFError, IOError, SocketError,
       ].freeze
 
-      attr_reader :timeout, :dropped_chunks
+      attr_reader :timeout, :max_retries, :dropped_chunks
+
+      def initialize(base_url:, api_key:, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
+        raise ArgumentError, "max_retries must be an Integer >= 0" unless max_retries.is_a?(Integer) && max_retries >= 0
 
-      def initialize(base_url:, api_key:, timeout: DEFAULT_TIMEOUT)
         @endpoint = Async::HTTP::Endpoint.parse(base_url)
         @api_key = api_key
         @timeout = timeout
+        @max_retries = max_retries
         @client = Async::HTTP::Client.new(@endpoint)
         @path = @endpoint.path.chomp("/") + "/chat/completions"
       end
@@ -65,6 +76,17 @@ module Fast
       # POST {base}/chat/completions, stream the SSE reply, yield every
       # Event to the block, return the final assistant Message (the
       # accumulator itself — §3). Runs inside the caller's task.
+      #
+      # Failure discipline (I62): EVERY failure raises AFTER the one
+      # `:error` terminal event — a streaming-phase failure carries the
+      # salvaged partial (pi :707-728 catch-all), a creation-phase
+      # failure an empty accumulator (:start is never emitted for a
+      # failed creation) — except cancellation, which keeps its
+      # no-terminal-event discipline (D8), and the watchdog's read
+      # inactivity, reached as Async::Cancel through the same untouched
+      # ladder. The rescue order is load-bearing: Async::Cancel first
+      # (cancel never salvages, never retries), then the network family,
+      # then the StandardError catch-all.
       def stream(model:, messages:, instructions: nil, tools: [], thinking: nil,
         max_tokens: nil, temperature: nil, session_id: nil, &block)
         request = Protocol.build_request(
@@ -73,31 +95,35 @@ module Fast
           temperature: temperature,
         )
         headers = default_headers.merge(session_headers(model.dialect, session_id))
+        body = JSON.generate(request)
         accumulator = Protocol::StreamAccumulator.new(model, model.dialect)
 
         watchdog = Watchdog.new(Async::Task.current, @timeout)
+        response = nil
         begin
-          watchdog.arm
-          response = @client.post(@path, headers: headers, body: JSON.generate(request))
-          begin
-            raise_api_error(response) unless (200...300).cover?(response.status)
-            yield accumulator.start_event if block # :start precedes every block event (§10.6)
-            feed_stream(response, accumulator, watchdog, &block)
-          ensure
-            # Complete bodies return the connection to the pool; an aborted
-            # read (cancel/timeout) discards it — a cancelled connection is
-            # never reused (AC3/D8).
-            begin
-              response.finish
-            rescue StandardError, Async::Cancel
-              nil
-            end
-          end
+          # The POST attempt — creation through status receipt (§2),
+          # bounded-retried on pi's trigger set; every final creation
+          # failure raises its mapped error from in there.
+          response = create_response(headers, body, watchdog)
+          yield accumulator.start_event if block # :start precedes every block event (§10.6)
+          feed_stream(response, accumulator, watchdog, &block)
         rescue Async::Cancel
           watchdog.fired ? raise(TimeoutError, "no data within #{@timeout}s") : raise(CancelledError, "stream cancelled")
         rescue *NETWORK_ERRORS => e
+          salvage(accumulator, &block) # the :error terminal carries the partial BEFORE the raise (§1)
           raise ConnectionError, "#{e.class}: #{e.message}"
+        rescue StandardError
+          salvage(accumulator, &block) # pi's catch-all: any other streaming failure — same terminal, raised unchanged
+          raise
         ensure
+          # Complete bodies return the connection to the pool; an aborted
+          # read (cancel/timeout) discards it — a cancelled connection is
+          # never reused (AC3/D8).
+          begin
+            response.finish
+          rescue StandardError, Async::Cancel
+            nil
+          end
           watchdog.stop
         end
         raise TimeoutError, "no data within #{@timeout}s" if watchdog.fired
@@ -183,7 +209,96 @@ module Fast
         accumulator.partial
       end
 
-      # Non-2xx: read the body, map per §8.
+      # The bounded creation retry (I62 §2, pi retryProviderRequest around
+      # chat.completions.create — the attempt is creation through status
+      # receipt, structurally pre-first-body-byte, Grounds R4). At most
+      # @max_retries immediate retries, exactly on pi's trigger set
+      # (provider-retry.ts :25-38): header x-should-retry true (any
+      # status) / false (FINAL, even on a retryable status), statusless
+      # errors (NETWORK_ERRORS at the POST, a TTFB watchdog fire),
+      # statuses 408/409/429/5xx. NEVER after a 2xx — the attempt is
+      # committed to streaming and any later failure is §1 salvage, never
+      # a retry. Cancellation is not a failure and is never retried. Each
+      # final failure raises its mapped error; stream's ladder adds the
+      # :error terminal before it (the accumulator is still empty — no
+      # :start was emitted).
+      def create_response(headers, body, watchdog)
+        remaining = @max_retries
+        loop do
+          watchdog.arm # re-armed per attempt: a retried TTFB deadline restarts (D5)
+          begin
+            response = @client.post(@path, headers: headers, body: body)
+          rescue Async::Cancel
+            raise unless watchdog.fired # the user's cancel is not a failure — never retried (D8)
+            raise TimeoutError, "no data within #{@timeout}s" if remaining.zero?
+            remaining -= 1
+            next
+          rescue *NETWORK_ERRORS => e
+            # Statusless — no response was received (pi's statusless trigger).
+            raise ConnectionError, "#{e.class}: #{e.message}" if remaining.zero?
+            remaining -= 1
+            next
+          end
+          return response if (200...300).cover?(response.status)
+
+          if retry_response?(response) && remaining.positive?
+            finish_quietly(response) # the discarded attempt's connection returns to the pool
+            remaining -= 1
+            next
+          end
+          raise_api_error(response) # final non-2xx: the §8 mapping, reached only after the retry decision
+        end
+      end
+
+      # pi provider-retry.ts :26-34, exact: the header beats the status
+      # both ways (strict "true"/"false"); then 408/409/429/5xx; every
+      # other status is final.
+      def retry_response?(response)
+        flag = retry_header(response.headers)
+        return true if flag == "true"
+        return false if flag == "false"
+
+        [408, 409, 429].include?(response.status) || (500..599).cover?(response.status)
+      end
+
+      # Header NAMES arrive in wire case (HTTP/1); Protocol::HTTP::Headers
+      # collects repeated fields into arrays — scan case-insensitively and
+      # unwrap, pi headers.get("x-should-retry") shape.
+      def retry_header(headers)
+        headers.each do |key, value|
+          return Array(value).first if key.to_s.downcase == "x-should-retry"
+        end
+        nil
+      end
+
+      # The salvage arm (pi openai-completions.ts :707-728 catch-all): a
+      # streaming-phase failure yields the ONE error-terminal event FIRST
+      # — the live partial (every streamed block + usage so far) — with NO
+      # block-end events after the failure; the rescue ladder raises
+      # after. pi's catch applies the same scratch finalization to the
+      # partial (applyStreamedReasoningDetails): `finish` runs
+      # finalize_blocks — the thinking reasoning_details serialized into
+      # the signature, tool arguments finalized — whose end events we
+      # discard here, so a salvaged partial replays like a completed one's.
+      def salvage(accumulator)
+        return unless block_given?
+
+        accumulator.finish
+        yield Event.new(type: :error, reason: :error, message: accumulator.partial)
+      end
+
+      # Complete bodies return the connection to the pool; an aborted read
+      # (cancel/timeout) discards it — a cancelled connection is never
+      # reused (AC3/D8). Same discipline as stream's ensure.
+      def finish_quietly(response)
+        response.finish
+      rescue StandardError, Async::Cancel
+        nil
+      end
+
+      # Non-2xx: read the body, map per §8. Now reached only after the
+      # retry decision (I62) — stream's ladder yields the :error terminal
+      # before this raise.
       def raise_api_error(response)
         body = response.body.read
         raise Errors.class_for_status(response.status, body).new(status: response.status, body: body)

data/lib/fast/completions/codec.rb

@@ -20,7 +20,9 @@ module Fast
       # ── Pass 1: transform-messages.ts ──────────────────────────────
 
       def normalize(messages, model)
-        transformed = messages.map { |msg| transform_message(msg, model) }
+        # filter_map: the transform pass drops errored/aborted assistants
+        # ENTIRELY (I62, pi :196-206) so pass 2 never sees their tool calls.
+        transformed = messages.filter_map { |msg| transform_message(msg, model) }
         insert_orphan_synthetic_results(transformed)
       end
 
@@ -30,6 +32,12 @@ module Fast
       # (Specification §12.3 note; pi :97-99).
       def transform_message(msg, model)
         return msg unless msg.assistant?
+        # Errored/aborted turns skip replay entirely (pi :196-206): dropped
+        # in THIS pass, so their tool calls never become pending orphans in
+        # pass 2 and never synthesize results — while a PREVIOUS valid
+        # assistant's unanswered calls still flush there, and user/system
+        # messages around the skip are untouched.
+        return nil if msg.stop_reason == :error || msg.stop_reason == :aborted
 
         same_model = msg.provider == model.provider && msg.model == model.id
         content = msg.content.flat_map do |block|
@@ -48,7 +56,7 @@ module Fast
           end
         end
         Message.new(role: :assistant, content: content, provider: msg.provider,
-          model: msg.model, api: msg.api, usage: msg.usage)
+          model: msg.model, api: msg.api, usage: msg.usage, stop_reason: msg.stop_reason)
       end
 
       # Thinking-block rules (transform-messages.ts :103-118):
@@ -61,7 +69,9 @@ module Fast
           return same_model ? [block] : []
         end
         return [block] if same_model && block[:signature]
-        return [] if block[:thinking].nil? || block[:thinking].strip.empty?
+        # scrub: the empty-predicate must not die on defect-class bytes
+        # (I62) — the reasoning-field text is a scrubbed emission position.
+        return [] if block[:thinking].to_s.scrub { "" }.strip.empty?
         return [block] if same_model
 
         [{type: :text, text: block[:thinking]}]
@@ -122,20 +132,44 @@ module Fast
 
       # ── Pass 2: convertMessages (openai-completions.ts :1293-1465) ──
 
+      # pi sanitizeSurrogates (utils/sanitize-unicode.ts :24-27, call sites
+      # :1259/:1265/:1274/:1305/:1326/:1426): invalid sequences DELETED —
+      # "Text \u{D83D} here" → "Text  here", never U+FFFD. String#scrub
+      # { "" } deletes Ruby's whole invalid-encoding class (lone high/low
+      # surrogates, CESU-8 pairs, any malformed bytes — Ruby's class is
+      # broader than JS's) and is a byte-identical no-op on valid strings,
+      # so JSON.generate over the built params never raises
+      # GeneratorError from message content (Grounds row 3).
+      def scrub_text(str)
+        str.is_a?(String) ? str.scrub { "" } : str
+      end
+
+      # Tool-call arguments are message content too (the live-parsed
+      # JSON): string VALUES scrubbed, Hash/Array recursed, other leaves
+      # (numbers, booleans, nil) pass.
+      def scrub_json_values(node)
+        case node
+        when String then scrub_text(node)
+        when Hash then node.each_with_object({}) { |(key, value), out| out[key] = scrub_json_values(value) }
+        when Array then node.map { |item| scrub_json_values(item) }
+        else node
+        end
+      end
+
       # instructions is the ONE leading system/developer message (§9.1,
       # pi :1233): role "developer" iff model.reasoning AND
       # dialect.supports_developer_role, else "system".
       def to_wire_messages(instructions, messages, model, dialect)
         instruction_role = model.reasoning && dialect.supports_developer_role ? "developer" : "system"
         params = []
-        params << {role: instruction_role, content: instructions} if instructions && !instructions.empty?
+        params << {role: instruction_role, content: scrub_text(instructions)} if instructions && !instructions.empty?
 
         messages.each do |msg|
           case msg.role
           when :system
             next if msg.content.to_s.empty?
 
-            params << {role: instruction_role, content: msg.content}
+            params << {role: instruction_role, content: scrub_text(msg.content)}
           when :user
             wire_user(params, msg)
           when :assistant
@@ -152,13 +186,13 @@ module Fast
       # all-empty blocks skip the message (pi :1319-1342).
       def wire_user(params, msg)
         if msg.content.is_a?(String)
-          params << {role: "user", content: msg.content}
+          params << {role: "user", content: scrub_text(msg.content)}
           return
         end
 
         parts = msg.content
           .select { |block| block[:type] == :text && !block[:text].to_s.empty? }
-          .map { |block| {type: "text", text: block[:text]} }
+          .map { |block| {type: "text", text: scrub_text(block[:text])} }
         return if parts.empty?
 
         params << {role: "user", content: parts}
@@ -168,7 +202,7 @@ module Fast
       # tool_call_id:}; empty → "(no tool output)"; NO name key
       # (requires_tool_result_name unported, §14).
       def wire_tool_result(params, msg)
-        text = text_block_texts(msg.content).join("\n")
+        text = scrub_text(text_block_texts(msg.content).join("\n"))
         text = "(no tool output)" if text.empty?
         params << {role: "tool", content: text, tool_call_id: msg.tool_call_id}
       end
@@ -182,7 +216,7 @@ module Fast
         thinking_blocks = msg.content.select { |b| b[:type] == :thinking }
         tool_calls = msg.content.select { |b| b[:type] == :tool_call }
 
-        non_empty_thinking = thinking_blocks.reject { |b| b[:thinking].to_s.strip.empty? }
+        non_empty_thinking = thinking_blocks.reject { |b| b[:thinking].to_s.scrub { "" }.strip.empty? } # scrub: I62 defect-class safety
         # pi computes preservedReasoningDetails over ALL thinking blocks
         # (:1313-1316) and emits it independent of the non-empty branch
         # (:1382-1386) — encrypted-only blocks replay too.
@@ -190,15 +224,15 @@ module Fast
         unless non_empty_thinking.empty?
           if preserved_details.nil?
             field = non_empty_thinking.first[:signature]
-            assistant[field] = non_empty_thinking.map { |b| b[:thinking] }.join("\n") if REASONING_FIELDS.include?(field)
+            assistant[field] = scrub_text(non_empty_thinking.map { |b| b[:thinking] }.join("\n")) if REASONING_FIELDS.include?(field)
           end
         end
 
-        assistant[:content] = text unless text.empty?
+        assistant[:content] = scrub_text(text) unless text.empty?
         unless tool_calls.empty?
           assistant[:tool_calls] = tool_calls.map do |tc|
             {id: tc[:id], type: "function",
-             function: {name: tc[:name], arguments: JSON.generate(tc[:arguments])}}
+             function: {name: tc[:name], arguments: JSON.generate(scrub_json_values(tc[:arguments]))}}
           end
         end
         assistant["reasoning_details"] = preserved_details if preserved_details
@@ -326,8 +360,10 @@ module Fast
 
       def text_block_texts(content, non_whitespace: false)
         blocks = content.is_a?(String) ? [{type: :text, text: content}] : content
+        # scrub before the strip predicate (I62): defect-class bytes must
+        # reach the emission-point scrub, not die in the whitespace filter.
         blocks.select { |b| b.is_a?(Hash) && b[:type] == :text }
-          .map { |b| b[:text].to_s }
+          .map { |b| scrub_text(b[:text]).to_s }
           .then { |texts| non_whitespace ? texts.reject { |t| t.strip.empty? } : texts }
       end
     end

data/lib/fast/completions/constrained_sampling.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Fast
+  module Completions
+    # JSON-schema constrained sampling (I63) — the strict rewrite that lets
+    # a declared tool ship forced property emission on a strict dialect.
+    # Port of pi packages/ai/src/api/constrained-sampling.ts @ f1b2e77f5
+    # (the JSON-schema half; the grammar half is deliberately NOT ported —
+    # nothing half-anticipates grammar). Message bytes are pi's literals
+    # verbatim: they are the parity observable. Check order inside
+    # make_json_schema_node_strict is pi's exactly — which message throws
+    # first is observable behavior.
+    module ConstrainedSampling
+      # pi constrained-sampling.ts :17-34 (16 keys — the frozen order IS
+      # the first-present-key-wins order). NOTE: the iteration Grounds say
+      # "20 keys"; pi's array holds 16 and the Grounds enumerate the same
+      # 16 in the same order — the count numeral in the brief is wrong,
+      # pi is the oracle.
+      UNSUPPORTED_STRICT_SCHEMA_KEYS = [
+        "$ref",
+        "$defs",
+        "definitions",
+        "allOf",
+        "oneOf",
+        "patternProperties",
+        "dependentSchemas",
+        "dependencies",
+        "unevaluatedProperties",
+        "propertyNames",
+        "contains",
+        "prefixItems",
+        "not",
+        "if",
+        "then",
+        "else",
+      ].freeze
+
+      module_function
+
+      # pi :156-178. `true` (strict) or `nil` (loose). Only
+      # UnsupportedStrictJsonSchemaError is caught — any other error
+      # propagates (pi's rethrow).
+      def resolve_json_schema_strict_sampling(tool, supports_strict_mode)
+        config = tool.constrained_sampling
+        return nil if config.nil? || config == false || config["type"] != "json_schema"
+
+        if supports_strict_mode
+          begin
+            make_strict_json_schema(tool.parameters)
+            return true
+          rescue UnsupportedStrictJsonSchemaError => reason
+            return nil if config["strict"] != "require" # silent loose fallback
+
+            raise ConstrainedSamplingError,
+              "Tool \"#{tool.name}\" requires JSON-schema constrained sampling, but #{reason.message}."
+          end
+        end
+        if config["strict"] == "require"
+          raise ConstrainedSamplingError,
+            "Tool \"#{tool.name}\" requires JSON-schema constrained sampling, but strict tools are unsupported."
+        end
+        nil
+      end
+
+      # pi makeStrictJsonSchema :137-151: deep-copy FIRST (the caller's
+      # schema — nested included — is never mutated), then the root arms
+      # use the root-specific message (differs from the nested
+      # "boolean schemas…" arm), then the root type must be "object".
+      def make_strict_json_schema(schema)
+        cloned = deep_copy(schema)
+        raise UnsupportedStrictJsonSchemaError, "root schema must have type object" unless cloned.is_a?(Hash)
+
+        make_json_schema_node_strict(cloned)
+        raise UnsupportedStrictJsonSchemaError, "root schema must have type object" unless cloned["type"] == "object"
+
+        cloned
+      end
+
+      # pi makeJsonSchemaNodeStrict :64-134, IN PLACE on the (cloned) node.
+      def make_json_schema_node_strict(node)
+        # JS isJsonSchemaObject: object, not null, not array. Everything
+        # else — booleans, null, arrays, scalars — throws here (a nil
+        # property value hits this arm: JS undefined equivalence).
+        raise UnsupportedStrictJsonSchemaError, "boolean schemas are unsupported" unless node.is_a?(Hash)
+
+        # JS `schema[key] !== undefined`: present-with-any-value (JSON null
+        # included) throws; Ruby key? is the exact equivalence.
+        UNSUPPORTED_STRICT_SCHEMA_KEYS.each do |key|
+          raise UnsupportedStrictJsonSchemaError, "#{key} schemas are unsupported" if node.key?(key)
+        end
+
+        # pi's optional isUnsupportedKeyword provider hook is NOT ported:
+        # pi's own call sites pass none (Recorded residual R2).
+
+        if node.key?("anyOf") # pi :76-89
+          raise UnsupportedStrictJsonSchemaError, "anyOf must contain at least one schema" if
+            !node["anyOf"].is_a?(Array) || node["anyOf"].empty?
+
+          node["anyOf"].each do |variant|
+            raise UnsupportedStrictJsonSchemaError, "object and array unions are unsupported" if structured_schema?(variant)
+
+            make_json_schema_node_strict(variant)
+          end
+        end
+
+        if node.key?("items") # pi :91-96
+          raise UnsupportedStrictJsonSchemaError, "tuple schemas are unsupported" if node["items"].is_a?(Array)
+
+          make_json_schema_node_strict(node["items"])
+        end
+
+        # JS `schema.type === "object"` — the string, strictly.
+        object_schema = node["type"] == "object"
+        if node.key?("properties") && !object_schema
+          raise UnsupportedStrictJsonSchemaError, "properties require type object"
+        end
+        return unless object_schema # non-object-typed nodes return here
+
+        # JS `!== false`: only exactly boolean false passes.
+        if node.key?("additionalProperties") && node["additionalProperties"] != false
+          raise UnsupportedStrictJsonSchemaError, "schema-valued or true additionalProperties is unsupported"
+        end
+        if node.key?("properties") && !node["properties"].is_a?(Hash)
+          raise UnsupportedStrictJsonSchemaError, "object properties must be a schema map"
+        end
+        if node.key?("required") &&
+            (!node["required"].is_a?(Array) || node["required"].any? { |key| !key.is_a?(String) })
+          raise UnsupportedStrictJsonSchemaError, "object required must be a string array"
+        end
+
+        properties = node.key?("properties") ? node["properties"] : {}
+        property_names = properties.keys
+        required = node.key?("required") ? node["required"] : []
+        if required.any? { |key| !property_names.include?(key) }
+          raise UnsupportedStrictJsonSchemaError, "required contains an unknown property"
+        end
+
+        properties.each do |key, property|
+          make_json_schema_node_strict(property)
+          if !required.include?(key) && !schema_allows_null(property)
+            # Reassignment keeps the key's hash position (JS and Ruby alike).
+            properties[key] = {"anyOf" => [property, {"type" => "null"}]}
+          end
+        end
+        node["required"] = property_names          # existing key keeps its position
+        node["additionalProperties"] = false       # absent key appends
+      end
+
+      # pi schemaAllowsNull :54-60. The const arm needs the key-present
+      # check: JS `schema.const === null` is false when the key is absent
+      # (undefined ≠ null); Ruby `hash["const"].nil?` alone would read an
+      # ABSENT const as null-allowing and skip the wrap.
+      def schema_allows_null(schema)
+        return false unless schema.is_a?(Hash)
+
+        type = schema["type"]
+        return true if type == "null" || (type.is_a?(Array) && type.include?("null"))
+        return true if schema.key?("const") && schema["const"].nil?
+        return true if schema["enum"].is_a?(Array) && schema["enum"].include?(nil)
+
+        schema["anyOf"].is_a?(Array) && schema["anyOf"].any? { |variant| schema_allows_null(variant) }
+      end
+
+      # pi isStructuredSchema :42-51.
+      def structured_schema?(schema)
+        return false unless schema.is_a?(Hash)
+
+        types =
+          if schema["type"].is_a?(String) then [schema["type"]]
+          elsif schema["type"].is_a?(Array) then schema["type"]
+          else []
+          end
+        types.include?("object") || types.include?("array") ||
+          schema.key?("properties") || schema.key?("items")
+      end
+
+      # structuredClone's role: fresh containers all the way down, so the
+      # rewrite (property wraps, required/additionalProperties writes)
+      # never reaches the declared Hash. Leaves (strings, numbers, booleans,
+      # nil) are immutable in Ruby — no copy needed; frozen strings dup
+      # clean by simply being carried over.
+      def deep_copy(value)
+        case value
+        when Hash then value.each_with_object({}) { |(key, val), copy| copy[key] = deep_copy(val) }
+        when Array then value.map { |val| deep_copy(val) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/fast/completions/dialects.rb

@@ -6,7 +6,7 @@ module Fast
     # the codec arms. Nothing here is provider detection, a catalog, or a
     # base-URL constant — the consumer declares, the codec obeys (§4).
     #
-    # The vocabulary is CLOSED to the 13 keys declared below. Unknown keys
+    # The vocabulary is CLOSED to the 14 keys declared below. Unknown keys
     # and unknown enum values raise ArgumentError AT DECLARATION TIME —
     # fail loud, never silently mistranslate (the no-universal-translation
     # discipline).
@@ -27,6 +27,9 @@ module Fast
         supports_thinking_token_budget: [false, nil],
         send_session_affinity_headers: [false, nil],
         session_affinity_format: [:openai, %i[openai openai_nosession openrouter].freeze],
+        # I63 (pi detectCompat :1675): OpenAI compatibility alone does not
+        # imply strict JSON-schema tool support — data, not detection.
+        supports_strict_mode: [false, nil],
       }.freeze
 
       attr_reader :name
@@ -154,6 +157,7 @@ module Fast
       supports_developer_role false
       supports_reasoning_effort true
       supports_store false
+      supports_strict_mode true # pi zai.json glm compat: supportsStrictMode:true
     end
 
     Dialects.declare(:deepseek) do

data/lib/fast/completions/errors.rb

@@ -10,6 +10,9 @@ module Fast
     # Non-2xx responses map here (pi maps the OpenAI SDK status error).
     # #message is "<status>: <provider message>" — the provider's
     # error.message when the body parses, else the raw body truncated.
+    # I62: a non-2xx raise happens only after the creation-retry decision,
+    # and the client-level `:error` event (empty partial, no `:start`)
+    # precedes every such raise (§1 creation-phase discipline).
     class ApiError < Error
       attr_reader :status, :body
 
@@ -28,14 +31,25 @@ module Fast
     class RateLimitError < ApiError; end             # 429
     class ServerError < ApiError; end                # 5xx
 
-    class TimeoutError < Error; end                  # TTFB deadline / read inactivity (D5)
-    class ConnectionError < Error; end               # ECONNREFUSED/ECONNRESET/... (§6)
+    # TTFB deadline / read inactivity (D5). I62: a TTFB fire before the
+    # response is a statusless retry trigger — a retried deadline re-arms
+    # per attempt, and the final failure still surfaces this class, never
+    # CancelledError. A mid-stream read inactivity arrives as
+    # Async::Cancel through the untouched cancel ladder (no retry, no
+    # terminal event).
+    class TimeoutError < Error; end
+    # ECONNREFUSED/ECONNRESET/... (§6). I62: a mid-body network failure
+    # salvages the partial as the `:error` terminal BEFORE this raise
+    # (message form `"<class>: <message>"` preserved); at creation the
+    # same terminal carries the empty accumulator after retries exhaust.
+    class ConnectionError < Error; end
 
     # Terminal stream errors (pi throws inside stream; the gem emits the
     # :error event first, then raises this — §10.5). NOT the malformed-
     # chunk path since I61: a malformed chunk is repaired at the seam,
     # else dropped and counted while the stream continues. What remains
-    # here: a provider error finish_reason or a missing finish.
+    # here: a provider error finish_reason or a missing finish. I62 did
+    # not change this path — it IS the model for the new salvage arm.
     class StreamError < Error
       attr_reader :stop_reason
 
@@ -47,6 +61,20 @@ module Fast
 
     class CancelledError < StandardError; end        # NOT < Error (D8)
 
+    # I63 constrained sampling (pi api/constrained-sampling.ts). INTERNAL:
+    # a tool schema outside the strict subset pi's makeStrictJsonSchema
+    # accepts — the reason bytes are pi's literals verbatim. Never escapes
+    # the resolver: "prefer" falls back to loose on it, "require" converts
+    # it to the public ConstrainedSamplingError (pi rethrows only other
+    # error classes).
+    class UnsupportedStrictJsonSchemaError < Error; end
+
+    # PUBLIC: a strict:"require" tool whose schema cannot be strict-rewritten,
+    # or that runs on a dialect without supports_strict_mode — pi's two
+    # message templates verbatim (the inner reason carries no trailing
+    # period; the template adds it).
+    class ConstrainedSamplingError < Error; end
+
     # Internal: error classification helpers (Specification §8).
     module Errors
       # pi utils/overflow.ts :33-96 — the FULL pattern list, ported

data/lib/fast/completions/protocol.rb

@@ -66,18 +66,32 @@ module Fast
       end
 
       # §9.8 / pi buildParams :853-863: tools iff declared (declaration
-      # order; parameters VERBATIM — the consumer's schema is the bytes);
-      # zai tool_stream right after; the `tools: []` fallback when tool
-      # history exists with no declared tools.
+      # order). Parameters stay VERBATIM — the consumer's schema is the
+      # bytes — EXCEPT the I63 strict arm: a tool declaring
+      # constrained_sampling on a strict dialect ships the strict REWRITE
+      # (pi convertTools :1505-1516, getJsonSchemaToolParameters) and the
+      # function object carries "strict" right after "parameters" (pi key
+      # order: name, description, parameters, strict) — declared-strict
+      # true, undeclared/loose false. VERBATIM remains the discipline for
+      # undeclared tools and non-strict dialects: no strict key ever there,
+      # and the emitted parameters are the declared object itself
+      # (object-identity emission). zai tool_stream right after; the
+      # `tools: []` fallback when tool history exists with no declared
+      # tools.
       def apply_tools(params, tools, messages, dialect)
         if tools.any?
+          strict_capable = dialect.supports_strict_mode
           params[:tools] = tools.map do |tool|
-            {"type" => "function",
-             "function" => {
-               "name" => tool.name,
-               "description" => tool.description,
-               "parameters" => tool.parameters,
-             }}
+            strict = ConstrainedSampling.resolve_json_schema_strict_sampling(tool, strict_capable)
+            function = {
+              "name" => tool.name,
+              "description" => tool.description,
+              "parameters" => strict == true ? ConstrainedSampling.make_strict_json_schema(tool.parameters) : tool.parameters,
+            }
+            # pi :1513 — the explicit key on EVERY function tool when the
+            # dialect supports strict mode ("Some reject unknown fields").
+            function["strict"] = strict || false if strict_capable
+            {"type" => "function", "function" => function}
           end
           params[:tool_stream] = true if dialect.zai_tool_stream
         elsif tool_history?(messages)
@@ -403,7 +417,6 @@ module Fast
           block ||= @tool_by_id[entry["id"]] if entry["id"]
           unless block
             block = {type: :tool_call, id: entry["id"] || "", name: name, arguments: {}}
-            @tool_by_index[index] = block if index
             @tool_by_id[block[:id]] = block unless block[:id].empty?
             @partial.append_block(block)
             events << Event.new(type: :tool_call_start, content_index: content_index(block), partial: @partial)
@@ -413,6 +426,17 @@ module Fast
             @tool_by_id[block[:id]] = block
           end
           block[:name] = name if block[:name].empty? && !name.empty?
+          # Index-map backfill (I62, pi :536-539): a fragment that resolved
+          # its block — by index, by id, or by creation — while CARRYING an
+          # index the block has never bound, binds it here. FIRST index
+          # wins; one index per block, ever. Boundness is tracked
+          # accumulator-side (identity-keyed, like @args_scratch): the
+          # blocks ARE message content — no scratch keys on them.
+          @tool_index_bound ||= {}.compare_by_identity
+          if index && !@tool_index_bound.key?(block)
+            @tool_by_index[index] = block
+            @tool_index_bound[block] = true
+          end
 
           raw = entry.dig("function", "arguments")
           raw = "" unless raw.is_a?(String)

data/lib/fast/completions/tool.rb

@@ -25,12 +25,34 @@ module Fast
           end
           @parameters || {"type" => "object", "properties" => {}}
         end
+
+        # pi types.ts :736-754: constrainedSampling?: false |
+        # {type:"json_schema", strict:"prefer"|"require"}. Default nil
+        # (undeclared — no strict participation); false is the explicit
+        # opt-out, wire-equivalent to nil. ANY other shape raises here, at
+        # declaration time — fail loud, never silently mistranslate
+        # (unknown type — grammar included, the named exclusion — unknown
+        # strict value, missing keys, non-Hash values).
+        UNSET = Object.new.freeze # nil is NOT a passable value (raises below)
+
+        def constrained_sampling(config = UNSET)
+          return @constrained_sampling if config.equal?(UNSET)
+
+          unless config == false || (config.is_a?(Hash) &&
+              config["type"] == "json_schema" && %w[prefer require].include?(config["strict"]))
+            raise ArgumentError,
+              "constrained_sampling must be false or {\"type\" => \"json_schema\", " \
+              "\"strict\" => \"prefer\"|\"require\"}; got #{config.inspect}"
+          end
+          @constrained_sampling = config
+        end
       end
 
       # Instance readers forward to the class declaration.
       def description = self.class.description
       def tool_name = self.class.tool_name
       def parameters = self.class.parameters
+      def constrained_sampling = self.class.constrained_sampling
 
       # The wire name: the declared tool_name if set, else the class name (§11).
       def name

data/lib/fast/completions/types.rb

@@ -138,10 +138,12 @@ module Fast
       ROLES = %i[system user assistant tool_result].freeze
 
       attr_reader :role, :content, :provider, :model, :api, :usage,
-        :tool_call_id, :tool_name, :is_error, :response_id, :response_model
+        :tool_call_id, :tool_name, :is_error, :response_id, :response_model,
+        :stop_reason
 
       def initialize(role:, content:, provider: nil, model: nil, api: nil,
-        tool_call_id: nil, tool_name: nil, is_error: false, usage: nil)
+        tool_call_id: nil, tool_name: nil, is_error: false, usage: nil,
+        stop_reason: nil)
         unless ROLES.include?(role)
           raise ArgumentError, "role must be one of #{ROLES.inspect}, got #{role.inspect}"
         end
@@ -155,6 +157,10 @@ module Fast
         @tool_name = tool_name
         @is_error = is_error == true
         @usage = usage
+        # Stream/replay metadata (I62, pi transform-messages :196-206): nil
+        # default, NO vocabulary validation — consumers may carry their own
+        # values (tart's follow-up threads the stream's mapped reasons).
+        @stop_reason = stop_reason
         @response_id = nil
         @response_model = nil
       end
@@ -190,12 +196,13 @@ module Fast
         new(role: :system, content: content).freeze
       end
 
-      def self.assistant(content, provider: nil, model: nil, api: nil)
+      def self.assistant(content, provider: nil, model: nil, api: nil, stop_reason: nil)
         unless content.is_a?(Array)
           raise ArgumentError, "assistant content must be an Array of block hashes"
         end
 
-        new(role: :assistant, content: content, provider: provider, model: model, api: api).freeze
+        new(role: :assistant, content: content, provider: provider, model: model, api: api,
+          stop_reason: stop_reason).freeze
       end
 
       def self.tool_result(tool_call_id:, content:, tool_name: nil, is_error: false)
@@ -219,6 +226,7 @@ module Fast
         out[:usage] = @usage.to_h if @usage
         out[:response_id] = @response_id if @response_id
         out[:response_model] = @response_model if @response_model
+        out[:stop_reason] = @stop_reason if @stop_reason
         out
       end
 
@@ -234,6 +242,7 @@ module Fast
           tool_name: hash[:tool_name],
           is_error: hash[:is_error] == true,
           usage: hash[:usage] && Usage.new(**hash[:usage].transform_keys(&:to_sym)),
+          stop_reason: hash[:stop_reason]&.to_sym,
         )
         message.set_response_id(hash[:response_id]) if hash[:response_id]
         message.set_response_model(hash[:response_model]) if hash[:response_model]

data/lib/fast/completions/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   module Completions
-    VERSION = "0.2.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/fast/completions.rb

@@ -11,6 +11,7 @@ require_relative "completions/types"
 require_relative "completions/dialects"
 require_relative "completions/sse"
 require_relative "completions/codec"
+require_relative "completions/constrained_sampling"
 require_relative "completions/protocol"
 require_relative "completions/client"
 require_relative "completions/tool"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast-completions
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Eric Jacobs
@@ -38,6 +38,7 @@ files:
 - lib/fast/completions/chat.rb
 - lib/fast/completions/client.rb
 - lib/fast/completions/codec.rb
+- lib/fast/completions/constrained_sampling.rb
 - lib/fast/completions/dialects.rb
 - lib/fast/completions/errors.rb
 - lib/fast/completions/protocol.rb