fast-completions 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ad51b1c13ffc9236e40151891d9c935967c8ca06b982d43e9871e628900e888
-  data.tar.gz: b814642c835590b0399ff287b0ea2631bf2382766f242ba95a9e8857f9d8a8ae
+  metadata.gz: 296c0ef9c66b4933e440f14845ecca83e7ab18e96f125a572adda19e853be9b7
+  data.tar.gz: 12fe00808afa0c4c81a9b36dc3d898803c63dd570fcb29d86292d6c526b96557
 SHA512:
-  metadata.gz: 2bfbd4a381f09305f49fdeb578cbde26cf0599de031efa9af638d88dce48b96c38abbabd52e97071633404cdfa7c52237d05b718389465b25595a333a559b549
-  data.tar.gz: d510754ec3b2da6fb8564d51d1dd6925f7382423fc9312a4618af126c7174679a4641b62f6e537a2c78f4c6e10d68a299ff455c100093a4f9a1857b4ee9cace8
+  metadata.gz: 63b785f46a6a15265ddf700f6039d920670059a5a0c39b4b40c92892462577fc9bc1b02c0dc33645be44a28fc991961bdbd437568ed32188081e6b62105f9ba4
+  data.tar.gz: c02fdca12bb4133152fc6f41a4c2c2157e011937b93f2eb2dff319c18bda3124836d2a588386ddf96a00022488f13b31b1623edb609c86b7f0c29ea0d77f33c8

data/CHANGELOG.md

@@ -3,6 +3,79 @@
 Notable changes to the fast-completions gem. The format is prose-first,
 one section per released version, newest first.
 
+## 0.7.0 (2026-10-25)
+
+- Telemetry sink interface: `Client.new` accepts `telemetry:` — any
+  Enumerable of sink objects (an Array, a Set, …), validated loudly at
+  construction (a non-Enumerable, or a
+  sink not responding to all five hooks, raises `ArgumentError` naming
+  the offender and the missing hook; duck-typed sinks are accepted
+  without module inclusion; the client keeps its own frozen Array —
+  `entries` — so the caller's container is never frozen or mutated) — and dispatches five
+  observation hooks around a completion, ONE `Client#stream` invocation
+  (creation retries inside, tool execution outside):
+  `on_completion_start(model.id, body bytesize)` before the first POST,
+  `on_completion_ttfb` at the first parser item of the successful
+  attempt (a retried attempt's clock restarts), `on_event` for every
+  Event — before its consumer twin, terminals and the salvage `:error`
+  included, and even with no consumer block — `on_completion_end(stop
+  reason, duration, live message)` when `stream` returns, and
+  `on_completion_error(error Symbol derived from the raising class,
+  duration)` on every raise-out, cancellation included. Multiple sinks
+  dispatch in registration order. The allocation discipline is pinned
+  by spec measurement gates: zero added heap objects on the hot paths
+  with no sink registered, zero ADDED objects with a no-op sink (only
+  refs and immediates cross the boundary, durations are flonum
+  differences, every call site short-circuits on a precomputed
+  emptiness check), and zero added `Process.clock_gettime` reads. The
+  new reference page `docs/reference/telemetry.md` documents the
+  protocol, the ordering rule (telemetry is the ground-truth record
+  when consumer code is the suspect), the read-only convention for
+  sinks, and that metric naming belongs to the adapter.
+
+## 0.6.0 (2026-10-25)
+
+- `Client#raw_stream` — the raw completions surface a proxy needs: the
+  caller's body forwarded verbatim (a String as-is, anything else
+  JSON-generated), every parsed SSE payload yielded to the block in
+  arrival order with the wire's terminal DONE token in its wire
+  position, and `nil` returned — the block is the only output channel.
+  No message accumulation, no tool interpretation, no stop-reason
+  mapping, no salvage, no StreamError, and exactly ONE POST attempt —
+  no auto-retry of any kind; a non-2xx raises the §8 mapping
+  immediately. A malformed payload still rides the I61 chunk seam:
+  one repair pass, then drop-and-count on `dropped_chunks` while the
+  stream continues.
+- The watchdog is now two-deadline: `ttfb_timeout` (status + headers)
+  and `inactivity_timeout` (re-armed after every body chunk), each an
+  optional constructor kwarg and per-call override on `raw_stream`,
+  validated as a positive Numeric, falling back to the shared
+  `timeout` when unset; prefill-scale values (1400 s) are first-class.
+  A fire surfaces the phase-named `TimeoutError` ("no response headers
+  within Ns" / "no data within Ns") — never `CancelledError` — and a
+  user cancel still surfaces `CancelledError`. `Client#stream` keeps
+  its single shared timeout and its byte-identical behavior; the
+  additive default on `Watchdog#arm` is the only existing-signature
+  change.
+- Authentication is optional: `api_key` defaults to nil and the
+  `authorization` header is sent only when the key is present and
+  non-empty — a local engine needs no key. With a key present the
+  header set is unchanged.
+- Docs: a README "Raw streaming" section plus the full reference page
+  (`docs/reference/raw-stream.md`); the README owner-prose gate now
+  rules two zones. Platform unchanged: ruby floor `>= 3.3`, CI matrix
+  3.3/3.4/4.0, no new dependencies.
+- Internal refactor of `Client#raw_stream` (operator review of #7): the
+  method is short orchestration over three private seams — the request
+  seam (payload resolution + the ONE POST under the TTFB arm), the
+  each-event seam (the SSE parser, the per-chunk inactivity re-arm, the
+  DONE yield, the drop-and-count reset), and the cancel→timeout
+  translation — with the timeout phase derived from the response
+  instead of a threading flag. Behavior-identical: signature, yielded
+  events, error classes and messages, no-retry, and the
+  connection-finish discipline are unchanged, and the raw_stream spec
+  passes byte-unmodified.
+
 ## 0.5.0 (2026-10-17)
 
 - Tool-args streaming is now an incremental string-state machine

data/README.md

@@ -126,6 +126,23 @@ requests run inside the caller's reactor — the gem never creates its
 own. Cancellation (`Async::Cancel` / `Chat#cancel`) aborts the
 in-flight request, discards the connection, and raises
 `CancelledError` with no phantom terminal event.
+
+## Raw streaming
+
+`Client#raw_stream` is the low-level surface a proxy or gateway needs:
+the request body goes over the wire verbatim (a Hash is JSON-encoded
+as given, a String is sent untouched — no merging, no filtering, no
+`stream` injection), and the block receives every parsed SSE payload
+in arrival order, with the wire's terminal DONE token yielded in its
+wire position. No message accumulation, no tool interpretation, no
+stop-reason mapping; exactly one POST attempt — nothing is retried.
+The watchdog is two-deadline: `ttfb_timeout` bounds the wait for the
+response headers and `inactivity_timeout` bounds the gap between body
+chunks (re-armed after every chunk) — prefill-scale values such as
+1400 s are first-class, and an unset knob falls back to the shared
+`timeout`. The `authorization` header is sent only when `api_key` is
+present and non-empty, so a local engine needs no key. See
+[the raw-stream reference](docs/reference/raw-stream.md).
 [see the tool docs]: docs/reference/tools.md
 [see the dialect docs]: docs/reference/dialects.md
 [Dialect Docs]: docs/reference/dialects.md

data/lib/fast/completions/client.rb

@@ -34,11 +34,14 @@ module Fast
         # 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
+        # The additive seconds parameter (I03) lets one watchdog arm
+        # deadlines of different lengths — raw_stream's split phases —
+        # while a bare arm keeps the constructor value (stream, unchanged).
+        def arm(seconds = @seconds)
           stop
           @fired = false
           @timer = Async do
-            sleep @seconds
+            sleep seconds
             @fired = true
             @task.cancel
           end
@@ -55,17 +58,48 @@ module Fast
         Errno::ENETUNREACH, Errno::ETIMEDOUT, EOFError, IOError, SocketError,
       ].freeze
 
-      attr_reader :timeout, :max_retries, :dropped_chunks
+      # The five Telemetry::Sink hooks a registered sink must respond to
+      # (I01). Checked ONCE at construction — the only sanctioned
+      # respond_to? use; notification-time dispatch never reflects.
+      TELEMETRY_HOOKS = %i[
+        on_completion_start on_completion_ttfb on_event on_completion_end on_completion_error
+      ].freeze
+
+      attr_reader :timeout, :max_retries, :dropped_chunks, :ttfb_timeout, :inactivity_timeout
 
-      def initialize(base_url:, api_key:, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
+      def initialize(base_url:, api_key: nil, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES,
+        ttfb_timeout: nil, inactivity_timeout: nil, telemetry: [])
         raise ArgumentError, "max_retries must be an Integer >= 0" unless max_retries.is_a?(Integer) && max_retries >= 0
+        validate_deadline!(:ttfb_timeout, ttfb_timeout)
+        validate_deadline!(:inactivity_timeout, inactivity_timeout)
+        unless telemetry.is_a?(Enumerable)
+          raise ArgumentError, "telemetry must be an Enumerable of sink objects, got #{telemetry.class}"
+        end
+
+        telemetry.each do |sink|
+          missing = TELEMETRY_HOOKS.reject { |hook| sink.respond_to?(hook) }
+          next if missing.empty?
+
+          raise ArgumentError,
+            "telemetry sink #{sink.inspect} does not respond to #{missing.join(", ")} (Telemetry::Sink hooks)"
+        end
 
         @endpoint = Async::HTTP::Endpoint.parse(base_url)
         @api_key = api_key
         @timeout = timeout
         @max_retries = max_retries
+        @ttfb_timeout = ttfb_timeout
+        @inactivity_timeout = inactivity_timeout
         @client = Async::HTTP::Client.new(@endpoint)
         @path = @endpoint.path.chomp("/") + "/chat/completions"
+        # I01: the client's own frozen copy (the caller's container is
+        # never frozen or mutated) + the precomputed emptiness check every
+        # call site short-circuits on — zero allocation, zero added
+        # clock reads when no sink is registered. `entries` always
+        # builds a fresh Array — for an Array input too, so any
+        # Enumerable input lands in the same frozen-Array shape.
+        @telemetry = telemetry.entries.freeze
+        @telemetry_active = !@telemetry.empty?
       end
 
       def close
@@ -97,48 +131,129 @@ module Fast
         headers = default_headers.merge(session_headers(model.dialect, session_id))
         body = JSON.generate(request)
         accumulator = Protocol::StreamAccumulator.new(model, model.dialect)
-
+        started_at = notify_start(model.id, body.bytesize) # I01 §1: the completion clock, nil without sinks
         watchdog = Watchdog.new(Async::Task.current, @timeout)
         response = nil
+        post_started_at = nil # the committed attempt's POST clock (I01 §2), set by create_response's yield
         begin
-          # 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)
+          response = create_response(headers, body, watchdog) { |t0| post_started_at = t0 }
+          if block || @telemetry_active # :start even blockless (I01 §4); a consumer raise flies to the ladder
+            dispatch_event(accumulator.start_event, &block)
+          end
+          feed_stream(response, accumulator, watchdog, post_started_at, &block)
         rescue Async::Cancel
-          watchdog.fired ? raise(TimeoutError, "no data within #{@timeout}s") : raise(CancelledError, "stream cancelled")
+          if watchdog.fired # I01 §7: fired → timeout, else user cancel (D8); cancel never salvages (AC3)
+            notify_error(:timeout_error, started_at)
+            raise(TimeoutError, "no data within #{@timeout}s")
+          end
+          notify_error(:cancelled_error, started_at)
+          raise(CancelledError, "stream cancelled")
         rescue *NETWORK_ERRORS => e
-          salvage(accumulator, &block) # the :error terminal carries the partial BEFORE the raise (§1)
+          salvage(accumulator, started_at, &block) # the :error terminal carries the partial BEFORE the raise (§1)
+          notify_error(:connection_error, started_at) # I01 §7: the symbol of the ConnectionError about to raise
           raise ConnectionError, "#{e.class}: #{e.message}"
-        rescue StandardError
-          salvage(accumulator, &block) # pi's catch-all: any other streaming failure — same terminal, raised unchanged
+        rescue StandardError => e
+          salvage(accumulator, started_at, &block) # pi's catch-all: same terminal, raised unchanged
+          notify_error(telemetry_symbol_for(e), started_at) # I01 §7: derived from the re-raised class
           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
+          finish_quietly(response) # nil-safe: no response yet, or an aborted read (AC3/D8)
           watchdog.stop
         end
-        raise TimeoutError, "no data within #{@timeout}s" if watchdog.fired
+        if watchdog.fired # I01 §7: the post-ensure watchdog raise
+          notify_error(:timeout_error, started_at)
+          raise TimeoutError, "no data within #{@timeout}s"
+        end
+        deliver_terminal(accumulator, started_at, &block)
+      end
 
-        deliver_terminal(accumulator, &block)
+      # The raw surface a proxy needs (I03, BRIEF §3): the caller's
+      # request body forwarded VERBATIM (a String as-is, anything else
+      # JSON.generate'd — no merging, no filtering, no stream
+      # injection, no Model/dialect involvement, no session-affinity
+      # headers), every parsed SSE data payload yielded to the block in
+      # arrival order — the SSE::DONE sentinel in its wire position —
+      # and nil returned: the block is the only output channel. No
+      # Message accumulation, no tool interpretation, no stop-reason
+      # mapping, no salvage, no StreamError — a stream that ends without
+      # the terminal token simply ends. Exactly ONE POST attempt: no
+      # create_response, no retry logic, no x-should-retry consultation;
+      # a non-2xx raises the existing §8 mapping (raise_api_error).
+      #
+      # Watchdog, split by I03: two deadlines. TTFB (status + headers)
+      # arms before the POST; from response receipt on the inactivity
+      # deadline re-arms after every body chunk (D5). Each resolves per
+      # phase — call kwarg > client kwarg > the shared timeout. A fire
+      # cancels the waiting task and surfaces the phase-named
+      # TimeoutError, never CancelledError (D8); a user cancel surfaces
+      # CancelledError. Runs inside the caller's task (§6).
+      #
+      # I05 revision (operator review of #7 — "the raw_stream method
+      # is way too long and not idiomatic ruby"): the method is now
+      # short orchestration over three private seams — the request seam
+      # (post_raw_body), the each-event seam (each_raw_event), and the
+      # cancel translation (raise_raw_cancel). The phase a timeout
+      # fires in is derived from the response itself — headers are
+      # outstanding exactly until the POST returns — so no phase flag
+      # threads through the ladder.
+      def raw_stream(body, ttfb_timeout: nil, inactivity_timeout: nil, &block)
+        ttfb = resolve_deadline(:ttfb_timeout, ttfb_timeout, @ttfb_timeout)
+        idle = resolve_deadline(:inactivity_timeout, inactivity_timeout, @inactivity_timeout)
+
+        watchdog = Watchdog.new(Async::Task.current, ttfb)
+        response = nil
+        begin
+          response = post_raw_body(body, watchdog)
+          raise_api_error(response) unless (200...300).cover?(response.status)
+
+          each_raw_event(response, idle, watchdog, &block)
+        rescue Async::Cancel
+          raise_raw_cancel(watchdog, response, ttfb, idle)
+        rescue *NETWORK_ERRORS => e
+          raise ConnectionError, "#{e.class}: #{e.message}"
+        ensure
+          finish_quietly(response)
+          watchdog.stop
+        end
+        nil
       end
 
       private
 
       def default_headers
-        {
-          "authorization" => "Bearer #{@api_key}",
-          "content-type" => "application/json",
-          "accept" => "application/json",
-        }
+        # Authorization is optional (I03): sent only when a key is
+        # present and non-empty — a local engine needs none. With a key
+        # the header set is byte-identical to before.
+        if @api_key && !@api_key.empty?
+          {
+            "authorization" => "Bearer #{@api_key}",
+            "content-type" => "application/json",
+            "accept" => "application/json",
+          }
+        else
+          {"content-type" => "application/json", "accept" => "application/json"}
+        end
+      end
+
+      # The deadline knobs (I03): nil = unset (resolution falls through
+      # to the shared timeout); any explicitly-given value must be a
+      # positive Numeric. Applies at the constructor and, via
+      # resolve_deadline, to per-call overrides on raw_stream.
+      def validate_deadline!(name, value)
+        return if value.nil?
+        return if value.is_a?(Numeric) && value.positive?
+
+        raise ArgumentError, "#{name} must be a positive Numeric"
+      end
+
+      # Per-phase deadline resolution for raw_stream (I03): the call
+      # kwarg, else the client's, else the shared timeout. A call kwarg
+      # validates even though the client's own did — both are public
+      # surfaces. Runs BEFORE any reactor dependency, so a bad knob
+      # raises ArgumentError outside a reactor too.
+      def resolve_deadline(name, call_value, client_value)
+        validate_deadline!(name, call_value) unless call_value.nil?
+        call_value || client_value || @timeout
       end
 
       # Session-affinity headers per dialect when a session id is supplied
@@ -156,19 +271,83 @@ module Fast
         end
       end
 
-      def feed_stream(response, accumulator, watchdog, &block)
+      # The raw request seam (I05 revision): resolve the payload (a
+      # String verbatim, anything else JSON-generated) and make the ONE
+      # POST, the TTFB deadline armed for creation through status
+      # receipt. The status check stays with the caller — raw_stream's
+      # ensure ladder must see even a non-2xx response to keep the
+      # connection-finish discipline (raise_api_error reads the body;
+      # finish then returns the connection to the pool).
+      def post_raw_body(body, watchdog)
+        payload = body.is_a?(String) ? body : JSON.generate(body)
+        watchdog.arm
+        @client.post(@path, headers: default_headers, body: payload)
+      end
+
+      # The raw each-event seam (I05 revision) — a reusable "each
+      # event" concern: owns the SSE parser, the per-chunk inactivity
+      # re-arm (D5 — the first chunk's arm is the TTFB→inactivity
+      # transition), and the I61 drop-and-count reset; yields the DONE
+      # sentinel in its wire position and every surviving payload
+      # parsed. The block is optional — a blockless call drains.
+      def each_raw_event(response, idle, watchdog, &block)
         parser = SSE.new
         @dropped_chunks = 0
+        response.body.each do |chunk|
+          watchdog.arm(idle) # re-arm the inactivity read-timeout per chunk (D5)
+          parser.push(chunk).each do |item|
+            if item.equal?(SSE::DONE) # the wire's terminal token: yielded in place, no payload
+              block&.call(item)
+              next
+            end
+
+            json = parse_chunk(item)
+            next if json.nil? # dropped (I61): counted, the stream continues
+
+            block&.call(json)
+          end
+        end
+      end
+
+      # Cancel→timeout translation (I05 revision): a watchdog fire
+      # surfaces the PHASE-named TimeoutError — headers while the POST
+      # is outstanding (the response is still nil), read inactivity
+      # once the body has begun — while a user's cancel stays
+      # CancelledError (D8). The phase needs no flag: headers are
+      # outstanding exactly until post_raw_body returns.
+      def raise_raw_cancel(watchdog, response, ttfb, idle)
+        if watchdog.fired
+          message = response.nil? ? "no response headers within #{ttfb}s" : "no data within #{idle}s"
+          raise TimeoutError, message
+        end
+        raise CancelledError, "stream cancelled"
+      end
+
+      # The wire read (§3): SSE parse → accumulator → dispatch. TTFB
+      # fires at the FIRST parser-yielded item of the SUCCESSFUL attempt
+      # (I01 §3 — a `[DONE]` sentinel counts; comments and keepalives
+      # never yield items, sse.rb drops them structurally), measured
+      # from that attempt's POST (post_started_at, threaded in from
+      # create_response; a retried attempt's clock restarts), at most
+      # once per completion. Consumer raises here fly to stream's
+      # ladder, which closes the record after salvage.
+      def feed_stream(response, accumulator, watchdog, post_started_at, &block)
+        parser = SSE.new
+        @dropped_chunks = 0
+        ttfb_fired = false
         response.body.each do |chunk|
           watchdog.arm # re-arm the inactivity read-timeout per chunk (D5)
           parser.push(chunk).each do |item|
+            if @telemetry_active && !ttfb_fired # before this item's dispatches; a flonum difference — no heap
+              ttfb_fired = true
+              notify_ttfb(Process.clock_gettime(Process::CLOCK_MONOTONIC) - post_started_at)
+            end
             next if item == SSE::DONE # terminal token; no payload
 
             json = parse_chunk(item)
             next if json.nil? # dropped (I61): counted, the stream continues
 
-            events = accumulator.consume(json)
-            events.each { |event| yield event } if block
+            accumulator.consume(json).each { |event| dispatch_event(event, &block) }
           end
         end
       end
@@ -198,14 +377,29 @@ module Fast
       # stop and a missing finish both emit :error FIRST, then raise
       # StreamError; otherwise :done with the mapped reason. Cancel never
       # reaches here — it unwinds mid-read with NO terminal event (AC3).
-      def deliver_terminal(accumulator, &block)
+      # I01 §5: every terminal dispatch reaches the sinks (blockless
+      # included), on_completion_error rides the StreamError raise, and
+      # on_completion_end fires after the :done dispatches. The terminal
+      # Events are built only under the observer guard (zero-path
+      # discipline); every yield below is a ladder-UNCOVERED site — this
+      # method runs AFTER the ladder — so dispatch_event closes the
+      # record on a consumer raise here (see dispatch_event).
+      def deliver_terminal(accumulator, started_at, &block)
         events, outcome = accumulator.finish
-        events.each { |event| yield event } if block
-        if outcome[0] == :stream_error
-          yield Event.new(type: :error, reason: :error, message: accumulator.partial) if block
-          raise StreamError.new(outcome[1], stop_reason: :error)
+        if block || @telemetry_active
+          events.each { |event| dispatch_event(event, started_at, closing: true, &block) }
+          if outcome[0] == :stream_error
+            dispatch_event(Event.new(type: :error, reason: :error, message: accumulator.partial),
+              started_at, closing: true, &block)
+            notify_error(:stream_error, started_at) # the symbol of the StreamError about to raise
+          else
+            dispatch_event(Event.new(type: :done, reason: outcome[1], message: accumulator.partial),
+              started_at, closing: true, &block)
+            notify_end(outcome[1], accumulator.partial, started_at) # after the :done dispatches, before the return
+          end
         end
-        yield Event.new(type: :done, reason: outcome[1], message: accumulator.partial) if block
+        raise StreamError.new(outcome[1], stop_reason: :error) if outcome[0] == :stream_error
+
         accumulator.partial
       end
 
@@ -226,6 +420,7 @@ module Fast
         remaining = @max_retries
         loop do
           watchdog.arm # re-armed per attempt: a retried TTFB deadline restarts (D5)
+          t0 = @telemetry_active ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil # I01 §2, guarded (gate 3)
           begin
             response = @client.post(@path, headers: headers, body: body)
           rescue Async::Cancel
@@ -234,12 +429,14 @@ module Fast
             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?
+            raise ConnectionError, "#{e.class}: #{e.message}" if remaining.zero? # statusless trigger
             remaining -= 1
             next
           end
-          return response if (200...300).cover?(response.status)
+          if (200...300).cover?(response.status) # committed to streaming: never retried past a 2xx
+            yield(t0) if block_given? # the committed attempt's POST clock → stream's TTFB local (allocation-free)
+            return response
+          end
 
           if retry_response?(response) && remaining.positive?
             finish_quietly(response) # the discarded attempt's connection returns to the pool
@@ -280,16 +477,22 @@ module Fast
       # 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?
+      # The yield below runs INSIDE a rescue arm — ladder-uncovered — so
+      # dispatch_event closes the record on a consumer raise; the early
+      # return keeps the blockless-no-sink path byte-identical (I01 §6).
+      def salvage(accumulator, started_at, &block)
+        return unless block_given? || @telemetry_active # the blockless-no-sink early return (I01 §6)
 
         accumulator.finish
-        yield Event.new(type: :error, reason: :error, message: accumulator.partial)
+        dispatch_event(Event.new(type: :error, reason: :error, message: accumulator.partial),
+          started_at, closing: true, &block)
       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.
+      # reused (AC3/D8). Serves the discarded retry attempt and stream's
+      # ensure; nil-safe (no response yet → the rescue swallows the
+      # NoMethodError exactly as the inline form did).
       def finish_quietly(response)
         response.finish
       rescue StandardError, Async::Cancel
@@ -303,6 +506,98 @@ module Fast
         body = response.body.read
         raise Errors.class_for_status(response.status, body).new(status: response.status, body: body)
       end
+
+      # ── I01 telemetry dispatch ─────────────────────────────────────
+      # Every helper short-circuits on the precomputed emptiness check
+      # BEFORE any clock read or dispatch: with no sink registered the
+      # call sites cost one no-op method call, zero allocations, zero
+      # Process.clock_gettime reads. Per-completion state (the
+      # completion-start clock, the per-attempt POST clock, the
+      # ttfb-once flag) is threaded as locals/args, never Client ivars
+      # (I03); durations are flonum differences; dispatch is in
+      # registration order; the loop block itself is never materialized,
+      # so a no-op sink adds zero heap objects (gate 2).
+
+      # The ONE event dispatch seam: sinks first, consumer second (I01
+      # §4/§5 — telemetry is the ground-truth record). `closing:` marks
+      # yield sites the rescue ladder does NOT cover — deliver_terminal
+      # runs after it, salvage inside a rescue arm — where a consumer
+      # raise closes the record here (the raiser's symbol) before the
+      # unchanged, backtrace-preserving re-raise; on StandardError only,
+      # the ladder's own catch scope, so cancel and Exception-class
+      # raises keep today's escape semantics. At the ladder-covered
+      # sites the StandardError arm does the closing (after salvage) —
+      # closing here too would double-fire the record. Dispatch is
+      # implicit yield/block_given? (no captured &block of its own — no
+      # Proc materialization, gate 2); callers forward their
+      # already-captured Proc at the call site, which is free.
+      def dispatch_event(event, started_at = nil, closing: false)
+        return unless block_given? || @telemetry_active
+
+        notify_event(event)
+        if closing
+          begin
+            yield event if block_given?
+          rescue StandardError => e
+            notify_error(telemetry_symbol_for(e), started_at)
+            raise
+          end
+        else
+          yield event if block_given?
+        end
+      end
+
+      # I01 §1: the completion clock (every duration below differs from
+      # it) + on_completion_start, before the first POST of the first
+      # attempt. Returns the clock — nil without a sink, zero added
+      # clock reads (gate 3).
+      def notify_start(model_id, request_bytes)
+        return nil unless @telemetry_active
+
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @telemetry.each { |sink| sink.on_completion_start(model_id, request_bytes) }
+        started_at
+      end
+
+      def notify_ttfb(elapsed)
+        return unless @telemetry_active
+
+        @telemetry.each { |sink| sink.on_completion_ttfb(elapsed) }
+      end
+
+      def notify_event(event)
+        return unless @telemetry_active
+
+        @telemetry.each { |sink| sink.on_event(event) }
+      end
+
+      def notify_end(stop_reason, message, started_at)
+        return unless @telemetry_active
+
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+        @telemetry.each { |sink| sink.on_completion_end(stop_reason, duration, message) }
+      end
+
+      def notify_error(error, started_at)
+        return unless @telemetry_active
+
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+        @telemetry.each { |sink| sink.on_completion_error(error, duration) }
+      end
+
+      # The re-raise arm's error Symbol: derived from the raising class —
+      # demodulized, underscored (RateLimitError → :rate_limit_error,
+      # RuntimeError → :runtime_error). Computed only on the raise path,
+      # under the active guard; an anonymous class has no name.
+      def telemetry_symbol_for(error)
+        name = error.class.name
+        return :anonymous_error if name.nil?
+
+        name.split("::").last
+          .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase.to_sym
+      end
     end
   end
 end

data/lib/fast/completions/telemetry.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Fast
+  module Completions
+    # The telemetry observation protocol (I01): a sink includes this
+    # module and overrides what it wants — the defaults are no-ops. No
+    # base class, no respond_to? dispatch at notification time (Client
+    # validates the five hooks ONCE at construction, the only sanctioned
+    # respond_to? use); duck-typed sinks that define all five are
+    # accepted without including the module.
+    #
+    # Unit of observation: a COMPLETION — ONE Client#stream invocation
+    # (one logical request-response on POST {base}/chat/completions with
+    # stream: true). Creation retries are INSIDE the completion (a
+    # retried completion is one completion); tool execution (the Chat
+    # batch) is OUTSIDE it.
+    #
+    # All hook arguments are existing references or immediates — no Hash
+    # payloads, no structs, no interpolated strings, no keyword splats —
+    # so dispatching to a no-op sink allocates nothing on the hot paths.
+    module Telemetry
+      # A sink includes this module and overrides what it wants. The
+      # defaults are no-ops. No base class; no respond_to? dispatch at
+      # notification time.
+      module Sink
+        # Exactly once per completion, before the first POST of the
+        # first attempt. `model_id` is the Model#id String ref
+        # (equal?-stable, never a copy); `request_bytes` is the Integer
+        # bytesize of the serialized request body actually POSTed.
+        def on_completion_start(model_id, request_bytes); end
+
+        # At most once, at the FIRST item the SSE parser yields for the
+        # SUCCESSFUL (2xx) attempt — measured from that attempt's POST
+        # initiation (a retried attempt's clock restarts). Seconds since
+        # the POST, a Float. Does not fire when the completion fails
+        # before any item.
+        def on_completion_ttfb(seconds); end
+
+        # Every Event the consumer block sees, BEFORE the consumer
+        # block, same order — terminals (:done, :error) and the
+        # salvage-path :error included; with a registered sink but no
+        # consumer block, sinks still receive every Event produced at
+        # the yield sites. The argument is the Event ref the accumulator
+        # already allocated.
+        def on_event(event); end
+
+        # Exactly once, when Client#stream returns: after the :done
+        # event's dispatches. `stop_reason` is the mapped Symbol (:stop,
+        # :length, :tool_use); `duration` is the Float from the
+        # completion-start clock; `message` is the accumulator's LIVE
+        # assistant Message (see the read-only convention in
+        # docs/reference/telemetry.md).
+        def on_completion_end(stop_reason, duration, message); end
+
+        # Exactly once on EVERY raise-out of Client#stream — the mapped
+        # paths and any other raise re-raised through the ladder.
+        # `error` is a Symbol derived from the raising class
+        # (demodulized, underscored: :rate_limit_error,
+        # :connection_error, :timeout_error, :cancelled_error,
+        # :stream_error, :runtime_error, …); `duration` is the Float
+        # start-to-raise on the same completion-start clock.
+        def on_completion_error(error, duration); end
+      end
+    end
+  end
+end

data/lib/fast/completions/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   module Completions
-    VERSION = "0.5.0"
+    VERSION = "0.7.0"
   end
 end

data/lib/fast/completions.rb

@@ -13,6 +13,7 @@ require_relative "completions/sse"
 require_relative "completions/codec"
 require_relative "completions/constrained_sampling"
 require_relative "completions/protocol"
+require_relative "completions/telemetry"
 require_relative "completions/client"
 require_relative "completions/tool"
 require_relative "completions/cancellation"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast-completions
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Eric Jacobs
@@ -44,6 +44,7 @@ files:
 - lib/fast/completions/errors.rb
 - lib/fast/completions/protocol.rb
 - lib/fast/completions/sse.rb
+- lib/fast/completions/telemetry.rb
 - lib/fast/completions/tool.rb
 - lib/fast/completions/types.rb
 - lib/fast/completions/version.rb