bitfab 0.74.2 → 0.75.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2533a42fd8e3080a107eb28117106080a950076630082392805c6a29d86ab7d8
-  data.tar.gz: 77cf546b4d9b69b22370e8e8a5b6eec12fff1b8122a4b598b11a0a077953f2ec
+  metadata.gz: 6976d07abea8e8c456185b0f5a76bbe861148e2a10baa1c3a65ac1a694b6993d
+  data.tar.gz: 072af5081f4c15e748478dbd058a8cc4c249804b345dcc70ed47b3e47f3c5830
 SHA512:
-  metadata.gz: cef1f28295d0d4c140bd23b003bb712d460a10fe9225ce730526159c083e20a2bf8a423d4641eeffb369b4a6509b0ef86cbfc992ae5d1f5641c91594d0d0868f
-  data.tar.gz: 99f81dace42263bf6e770451cbe266ec5e4a5566ecc559e86984d87f7d82f67c214a610a74f358ec188d2dd52383ef84c4f4e4c4be52cf2ce609f7ec818febcc
+  metadata.gz: 5189232282c64908bada35335eac364e16bb6fcadfe9b677cdc5b3330735f59dbdebc6ff71fe4a2984ad1a5c8386b45ade841710c0b2ec1ac0d26c0d07c7d44f
+  data.tar.gz: 90b5fd0acb0d266e6f2e7d2b6d04dc4a08c66d3e1b25ce46f51425e5020cf372167c40ba141cf05c9f7e4f2348cc9a106f1888e9a5b792bbbe9a4f08d2bb0b80

data/lib/bitfab/client.rb

@@ -1021,7 +1021,7 @@ module Bitfab
         "type" => "sdk-function",
         "source" => "ruby-sdk-function",
         "traceFunctionKey" => trace_function_key,
-        "externalTrace" => raw_trace,
+        "rawTrace" => raw_trace,
         "completed" => true
       }
 
@@ -1037,7 +1037,7 @@ module Bitfab
         payload["testRunId"] = trace_state[:experiment_id]
       end
 
-      @http_client.send_external_trace(payload)
+      @http_client.send_trace_payload(payload)
 
       # Clean up trace state
       TraceState.delete(trace_id)
@@ -1146,7 +1146,7 @@ module Bitfab
         }]
       end
 
-      @http_client.send_external_span(payload, declared_node, snapshot)
+      @http_client.send_span_payload(payload, declared_node, snapshot)
     end
 
     # Advance the per-(key, name) call counter when this invocation is a
@@ -1180,10 +1180,6 @@ module Bitfab
     def check_mock_replay(replay_ctx, trace_function_key, span_name, call_index, span_type:, args:, kwargs:, mock_on_replay:)
       mock_entry = replay_ctx[:mock_tree]["#{trace_function_key}:#{span_name}:#{call_index}"]
 
-      # 1) Selective overrides. The matcher runs on structural metadata only;
-      # the recorded output is fetched (lazily, by externalSpanId) only if the
-      # processor actually asks for it via get_original_output, so a pure
-      # synthetic override triggers zero output fetches.
       overrides = replay_ctx[:mock_overrides]
       if overrides&.any?
         node = {
@@ -1243,7 +1239,7 @@ module Bitfab
     # Resolve a mock-tree entry's recorded output. Prefers an inline output when
     # the tree carried one (eager "all", or an older server that ignores
     # includeOutputs and returns outputs); otherwise lazily fetches it by
-    # externalSpanId through the per-item memoized fetcher on the replay
+    # span ID through the per-item memoized fetcher on the replay
     # context, so only the spans actually mocked pull their output.
     #
     # Deserialization is type-preserving when Ruby-side Marshal+Base64 metadata
@@ -1258,9 +1254,9 @@ module Bitfab
       end
 
       fetcher = replay_ctx[:fetch_span_output]
-      external_span_id = mock_entry[:external_span_id]
-      if fetcher && external_span_id
-        return fetcher.call(external_span_id)
+      span_row_id = mock_entry[:span_row_id]
+      if fetcher && span_row_id
+        return fetcher.call(span_row_id)
       end
 
       # No inline output and nothing to lazily fetch. This is a span that never

data/lib/bitfab/http_client.rb

@@ -192,8 +192,8 @@ module Bitfab
       raise last_error
     end
 
-    # Queue an external span on this client's trace transport (fire-and-forget).
-    def send_external_span(payload, declared_node = false, snapshot = nil)
+    # Queue a span payload on this client's trace transport (fire-and-forget).
+    def send_span_payload(payload, declared_node = false, snapshot = nil)
       if (data = payload.dig("rawSpan", "span_data")).is_a?(Hash) && !data.key?("runtime")
         payload = payload.merge("rawSpan" => payload["rawSpan"].merge("span_data" => data.merge("runtime" => ThreadPropagation.runtime)))
       end
@@ -334,11 +334,12 @@ module Bitfab
       request("/api/sdk/replay/start", payload, timeout:)
     end
 
-    # Fetch an external span by ID. Blocking GET request. The replay view keeps
-    # only the input/output serialization fields used by replay.
-    def get_external_span(span_id, replay_view: false)
+    # Fetch a span's raw record by its Bitfab row ID. Blocking GET request.
+    # The replay view keeps only the input/output serialization fields used
+    # by replay.
+    def get_span_raw(span_id, replay_view: false)
       query = replay_view ? "?view=replay" : ""
-      get("/api/sdk/externalSpans/#{span_id}#{query}", timeout: 30)
+      get("/api/sdk/spans/#{span_id}/raw#{query}", timeout: 30)
     end
 
     def get_trace_span(trace_id, id: nil, name: nil, type: nil, occurrence: "last")
@@ -359,19 +360,19 @@ module Bitfab
       get("/api/sdk/spans/#{encoded_span_id}", timeout: 30)["span"]
     end
 
-    # Fetch the span tree rooted at an external span. Blocking GET request.
+    # Fetch the span tree rooted at a span. Blocking GET request.
     # Used by replay when a mock strategy is active so child spans can be
     # matched against their historical outputs.
     #
     # Returns a hash shaped { "root" => SpanTreeNode } where each node has
-    # sourceSpanId, externalSpanId, traceFunctionKey, spanName, type, and
+    # sourceSpanId, spanId, traceFunctionKey, spanName, type, and
     # children. When include_outputs is true each node also carries its recorded
     # output (and optional outputMeta); when false the server omits the output
     # payloads so only the spans actually mocked are fetched later (by
-    # externalSpanId), avoiding dragging down every span's output when only a
+    # spanId), avoiding dragging down every span's output when only a
     # few are mocked.
-    def get_span_tree(external_span_id, include_outputs: true, include_root_output: true)
-      endpoint = "/api/sdk/replay/spanTree/#{external_span_id}"
+    def get_span_tree(span_id, include_outputs: true, include_root_output: true)
+      endpoint = "/api/sdk/replay/spanTree/#{span_id}"
       query = []
       query << "includeOutputs=false" unless include_outputs
       query << "includeRootOutput=false" unless include_root_output
@@ -402,23 +403,23 @@ module Bitfab
       )
     end
 
-    # Queue an external trace on this client's trace transport (fire-and-forget).
-    def send_external_trace(payload)
+    # Queue a trace payload on this client's trace transport (fire-and-forget).
+    def send_trace_payload(payload)
       submit = ->(record) {
         ref = carrier_ref(record)
         if record["completed"] == true && ref
           @trace_completion.close(ref.trace_id, dropped: record["dropped"] == true) do |count|
-            submit_external_trace(record.merge("expectedSpanCount" => count))
+            submit_trace_payload(record.merge("expectedSpanCount" => count))
           end
         else
           @trace_completion.open(ref.trace_id) if ref
-          submit_external_trace(record)
+          submit_trace_payload(record)
         end
       }
       @simulation_plan ? @simulation_plan.send_trace(payload, &submit) : submit.call(payload)
     end
 
-    def submit_external_trace(payload)
+    def submit_trace_payload(payload)
       trace_transport&.submit(
         "external_trace",
         payload.merge("sdkVersion" => VERSION),
@@ -473,7 +474,7 @@ module Bitfab
     def payload_timestamp(payload, field)
       raw = payload.dig("rawSpan", field) if payload["rawSpan"].is_a?(Hash)
       if raw.nil?
-        raw_trace = payload["externalTrace"] || payload["rawTrace"]
+        raw_trace = payload["rawTrace"] || payload["externalTrace"]
         raw = raw_trace[field] if raw_trace.is_a?(Hash)
       end
       return nil unless raw.is_a?(String)
@@ -496,7 +497,7 @@ module Bitfab
     def carrier_ref(payload)
       trace_id = payload["sourceTraceId"]
       unless trace_id.is_a?(String)
-        raw_trace = payload["externalTrace"] || payload["rawTrace"]
+        raw_trace = payload["rawTrace"] || payload["externalTrace"]
         trace_id = raw_trace["id"] if raw_trace.is_a?(Hash)
       end
       return nil unless trace_id.is_a?(String)

data/lib/bitfab/replay.rb

@@ -1144,20 +1144,9 @@ module Bitfab
         )
       end
 
-      span = http_client.get_external_span(original_span_id, replay_view: true)
+      span = http_client.get_span_raw(original_span_id, replay_view: true)
       item_data = extract_span_data(span)
 
-      # Fetch the span tree when the base strategy needs recorded outputs
-      # ("all"/"marked") OR when selective mock overrides are present. Overrides
-      # gate on the same non-root call-counter machinery the tree drives, so
-      # the tree must be fetched for them to fire even under mock: "none".
-      #
-      # Only mock: "all" needs every span's recorded output inline (it mocks
-      # every matched recorded child), so it fetches an eager tree even when
-      # overrides exist.
-      # Non-"all" runs that need a tree ("marked", or "none" with overrides)
-      # fetch it payload-free (includeOutputs=false) and pull each mocked span's
-      # output lazily by externalSpanId, never dragging down unused outputs.
       overrides_present = !mock_overrides.nil? && !mock_overrides.empty?
       include_outputs = mock_strategy == "all"
       mock_tree = nil
@@ -1201,7 +1190,7 @@ module Bitfab
         experiment_id,
         span["id"],
         metrics,
-        input_source_trace_id: span["externalTraceId"],
+        input_source_trace_id: span["traceId"] || span["externalTraceId"],
         selective_replay:,
         mock_strategy:,
         mock_tree:,
@@ -1294,14 +1283,9 @@ module Bitfab
           counter_key = "#{key}:#{name}"
           index = counters[counter_key] || 0
           counters[counter_key] = index + 1
-          # externalSpanId is what the lazy path fetches the recorded output by
-          # when the tree came back payload-free (includeOutputs=false). output
-          # / outputMeta are copied ONLY when the node actually carries them, so
-          # the presence of the :output key distinguishes an inline nil output
-          # from a payload-free entry (mirrors TS's undefined-vs-null check).
           entry = {
             source_span_id: node["sourceSpanId"],
-            external_span_id: node["externalSpanId"]
+            span_row_id: node["spanId"] || node["externalSpanId"]
           }
           entry[:output] = node["output"] if node.key?("output")
           entry[:output_meta] = node["outputMeta"] if node.key?("outputMeta")
@@ -1316,25 +1300,25 @@ module Bitfab
     end
 
     # Build a memoized lazy fetcher for a single replay item. The returned
-    # lambda takes an externalSpanId and returns that span's deserialized
-    # recorded output, fetching it via get_external_span at most once per id
+    # lambda takes a span ID and returns that span's deserialized
+    # recorded output, fetching it via get_span_raw at most once per id
     # (a span read twice - as a base "marked" mock and via an override's
     # get_original_output - fetches once). The cache is per item: each item
     # replays synchronously on its own thread, so no lock is needed.
     def build_span_output_fetcher(http_client)
       cache = {}
-      lambda do |external_span_id|
-        return cache[external_span_id] if cache.key?(external_span_id)
+      lambda do |span_row_id|
+        return cache[span_row_id] if cache.key?(span_row_id)
 
-        span = http_client.get_external_span(external_span_id, replay_view: true)
+        span = http_client.get_span_raw(span_row_id, replay_view: true)
         span_data = (span["rawData"] || {})["span_data"] || {}
         meta = span_data["output_serialized"]
         meta = span_data["output_meta"] if meta.nil? || meta == ""
-        cache[external_span_id] = Serialize.deserialize_output(span_data["output"], meta)
+        cache[span_row_id] = Serialize.deserialize_output(span_data["output"], meta)
       end
     end
 
-    # Extract input/output data from an external span's rawData.
+    # Extract input/output data from a span's rawData.
     def extract_span_data(span)
       raw_data = span["rawData"] || {}
       span_data = raw_data["span_data"] || {}

data/lib/bitfab/simulation_plan.rb

@@ -198,7 +198,7 @@ module Bitfab
     end
 
     def trace_id(payload)
-      payload["traceId"] || payload["sourceTraceId"] || payload.dig("externalTrace", "id") || payload["id"]
+      payload["traceId"] || payload["sourceTraceId"] || payload.dig("rawTrace", "id") || payload.dig("externalTrace", "id") || payload["id"]
     end
 
     def framework?(payload)

data/lib/bitfab/verdicts.rb

@@ -194,12 +194,27 @@ module Bitfab
       end
     end
 
-    # Reads one trace's verdicts, or nil when the trace has none.
+    # Reads one trace's verdicts, or nil when the trace has none. See {#get_all} for the shape of each
+    # "evidence" item.
     def get(trace_id)
       get_all([trace_id]).first
     end
 
-    # Reads the verdicts of several traces.
+    # Reads the verdicts of several traces. Each trace and each entry of its "assertions" carries
+    # "evidence": nil, or an array of hashes, one per span cited, each with "spanId" and "text".
+    #
+    # Evidence written by Bitfab's assertion judge also carries "field", "ranges", and "spanChanged",
+    # which point at the exact passages the judge read. "field" is the span field the judge read
+    # ("summary", "input", "output", "reasoning", "content", "metadata", "errors", "contexts", or
+    # "llm_usage"). "ranges" are [start, end) character ranges into that field's text as the judge saw
+    # it: a string field as is, any other value as JSON indented by two spaces. Indexes are JavaScript
+    # string indexes (UTF-16 code units), not Ruby character indexes, so text outside the Basic
+    # Multilingual Plane counts two per character. Use them to highlight only when "spanChanged" is false.
+    #
+    # "spanChanged" is true when the span no longer matches what was judged: "text" is then only a short
+    # preview saved with the verdict, and "ranges" must not be used to highlight anything. When it is
+    # false, "text" is the full text of "ranges" read from the span, joined by a newline, an ellipsis,
+    # and a newline. Unknown keys are passed through as the server sent them.
     def get_all(trace_ids)
       return [] if trace_ids.empty?
 

data/lib/bitfab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitfab
-  VERSION = "0.74.2"
+  VERSION = "0.75.0"
 end

data/lib/bitfab.rb

@@ -146,9 +146,6 @@ module Bitfab
       lease = ctx[:db_branch_lease]
       return unless lease
 
-      # Surface the Bitfab trace ID (what the customer sees in the dashboard),
-      # not the external one. Falling back to the external ID keeps replays from
-      # external sources working until that path is fully wired.
       trace_id = ctx[:source_bitfab_trace_id] || ctx[:input_source_trace_id]
       return unless trace_id
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.74.2
+  version: 0.75.0
 platform: ruby
 authors:
 - Harvest Team