bitfab 0.75.1 → 0.75.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fad2341a7e82e22c18faf4809a1807407660eed238b04886b2687e4dc15989b2
-  data.tar.gz: 7a46b9c4935290898decf6f835257d5b8551281eb1ddebb1680128fcd5ac8c74
+  metadata.gz: 0e8124c4242b339613c4f4b714a68305748f2c32e2d894fd884250bc8c1e4036
+  data.tar.gz: 9ed475b72f8f55b58334af9fe4feae30b07940aa9847c763fbccba227e21e41c
 SHA512:
-  metadata.gz: 82ef99ecba72308fc1e865257f260756cab829bae0167404f50f8317dd0d921446b02f4379f5c254e98f8deb3fb68104afa73075c4081cc9d5a7b7345243611f
-  data.tar.gz: 696fb090a73f51ab3bb9ca07277e89a0529dd3031a8c96bfa581f7c54235ba3205f804df4790e5d83163d635dfa5228f9d0be05e4e37d4c1805fb7271a920732
+  metadata.gz: 7b1356376e48cbaf2a8889fdf7c26945ed21050035603ae480e00d6da313acff4292c981d7f9be751b3dcfd37aa954d5ab6619d492a4f0547f8af5f99faddfdb
+  data.tar.gz: 15239246da620b92a67d87aa731974b22efe17fa97f2f25103491454a6ddd64327225a3b12f92f6df9ebc1770aceb82a7eb090a938ec31b95d32b0ba63ebd37e

data/lib/bitfab/assertions.rb

@@ -4,11 +4,9 @@ require "uri"
 
 module Bitfab
   class Traces
-    CODE_DRAFT_SAVE_TIMEOUT_SECONDS = 300
-    CODED_KINDS = ["code", "hybrid", :code, :hybrid].freeze
     CATEGORY_ID_KEYS = ["category_id", :category_id].freeze
     DEPRECATED_CATEGORY_ID_KEYS = ["category_assertion_id", :category_assertion_id].freeze
-    private_constant :CODE_DRAFT_SAVE_TIMEOUT_SECONDS, :CODED_KINDS, :CATEGORY_ID_KEYS, :DEPRECATED_CATEGORY_ID_KEYS
+    private_constant :CATEGORY_ID_KEYS, :DEPRECATED_CATEGORY_ID_KEYS
 
     def initialize(http_client)
       @http_client = http_client
@@ -31,31 +29,23 @@ module Bitfab
     # pass nil to clear it. The deprecated "category_assertion_id" is still
     # accepted and sent as "category_id"; "category_id" wins when both are set.
     #
-    # "kind" says who decides the assertion: "judge" (the LLM judge), "code"
-    # ("code" decides every replay), or "hybrid" ("code" decides what it can
-    # and returns "defer" for the rest). Send "code" or "hybrid" together with
-    # "code", {"source" => ..., "spanNames" => [...]}. "source" is the body of
-    # an async TypeScript (or plain JavaScript) function called with spans
-    # (each {name, index, hasData}, in start order, without its data), input,
-    # and output. It reads span data with await named("span name") or await
-    # span.data(), and returns "pass", "fail", or "defer" (hybrid only), or
-    # {result, reason}, with one second of compute and the data of at most 50
-    # spans loaded within ten seconds. "spanNames" lists every span a correct run is
-    # expected to produce. Code that cannot run on the trace, or that returns
-    # "defer" for a "code" assertion, is refused. Omit both to keep them, or
-    # pass "kind" => "judge" to remove the code. Returned assertions carry
-    # "kind", "code", and "codeBrokenReason".
-    #
-    # Send "kind" => "code" or "hybrid" without "code", on an assertion that
-    # has no code yet, to have Bitfab write the code: the text is checked by
-    # the guided rewrite (unless skipped), code of that kind is written and run
-    # on the trace, and the save waits for both, so that entry's "rewrite" is
-    # already final. Its returned "codeDraft" hash says what happened:
-    # "requestedKind", "status" ("written", or "not_written" when no working
-    # code could be written and the assertion was saved as "judge" without
-    # code), and "reason" (why not, or nil). Every other entry's "codeDraft"
-    # is nil. At most 10 assertions per save may ask for code this way, and a
-    # save that asks for any waits up to five minutes.
+    # "code" is optional code that decides the assertion on a replay without
+    # the LLM judge: {"source" => ..., "spanNames" => [...]}. Send a "code"
+    # hash to set it, "code" => nil to remove it, or omit "code" to keep the
+    # current code. "source" is the body of an async TypeScript (or plain
+    # JavaScript) function called with spans (each {name, index, hasData}, in
+    # start order, without its data), input, and output. It reads span data
+    # with await named("span name") or await span.data(), with one second of
+    # compute and the data of at most 50 spans loaded within ten seconds. It
+    # returns "pass" or "fail", which decides the verdict with no judge call,
+    # or "defer" to hand the replay to the LLM judge, or {result, reason}. A
+    # defer may carry what the code found for the judge to read alongside the
+    # run: {result: "defer", reason, data}. A thrown error counts as "defer"
+    # with no data. "spanNames" lists every span a correct run is expected to
+    # produce. The code is run on the trace before saving and refused when it
+    # throws, times out, or returns anything other than a result. Returned
+    # assertions carry "code" (nil when the assertion has none) and
+    # "codeBrokenReason", which says why the code could not run on a replay.
     #
     # By default, after the save, Bitfab checks each assertion's text against its
     # trace. When the text bundles two claims, adds a condition, points at a
@@ -90,8 +80,7 @@ module Bitfab
           "updates" => updates.map { |update| with_new_category_key(update) },
           "source" => source,
           "guidedRewrite" => !skip_guided_rewrite
-        },
-        timeout: save_timeout(updates)
+        }
       )["assertions"]
       saved.is_a?(Array) ? saved.map { |assertion| with_both_category_keys(assertion) } : saved
     end
@@ -102,18 +91,6 @@ module Bitfab
 
     private
 
-    def save_timeout(updates)
-      asks = updates.any? do |update|
-        (update["assertions"] || update[:assertions] || []).any? { |assertion| asks_bitfab_to_write_code?(assertion) }
-      end
-      asks ? CODE_DRAFT_SAVE_TIMEOUT_SECONDS : nil
-    end
-
-    def asks_bitfab_to_write_code?(assertion)
-      kind = assertion["kind"] || assertion[:kind]
-      CODED_KINDS.include?(kind) && !assertion.key?("code") && !assertion.key?(:code)
-    end
-
     def assertions_path(trace_id, suffix = "")
       "/api/sdk/traces/#{URI.encode_www_form_component(trace_id).gsub("+", "%20")}/assertions#{suffix}"
     end

data/lib/bitfab/client.rb

@@ -743,7 +743,7 @@ module Bitfab
           end
         end
       rescue => e
-        error = e.message
+        error = ErrorChain.describe(e)
         complete.call(result, error)
         raise
       end
@@ -944,7 +944,7 @@ module Bitfab
               end
               complete.call(yielded, nil)
             rescue => e
-              complete.call(yielded, e.message)
+              complete.call(yielded, ErrorChain.describe(e))
               raise
             ensure
               SpanContext.stack.pop

data/lib/bitfab/error_chain.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Bitfab
+  # Reads the chain of causes below an exception. A database driver error
+  # usually reaches a traced method wrapped one or two levels down, so
+  # recording only the top message makes a connection timeout read as a broken
+  # query. Spans and replay results carry the deepest cause too.
+  module ErrorChain
+    # How many causes below an exception are followed.
+    MAX_DEPTH = 10
+    CODE_METHODS = %i[code sqlstate errno].freeze
+
+    module_function
+
+    # The causes below `error`, nearest first, stopping at the depth limit or
+    # at a cause already seen.
+    def causes(error)
+      found = []
+      seen = {error.object_id => true}
+      current = error
+      while found.length < MAX_DEPTH
+        cause = current.cause
+        break if cause.nil? || seen[cause.object_id]
+
+        found << cause
+        seen[cause.object_id] = true
+        current = cause
+      end
+      found
+    end
+
+    # The exception's message, followed by the deepest cause's message when it
+    # wraps another exception, e.g. `Failed query: ... (caused by: connection
+    # timeout)`. The cause is left off when the message already contains it.
+    def describe(error)
+      message = error.message
+      deepest = causes(error).last
+      return message if deepest.nil?
+
+      deepest_message = deepest.message.to_s.strip
+      return message if deepest_message.empty? || message.include?(deepest_message)
+
+      "#{message} (caused by: #{deepest_message})"
+    end
+
+    # An exception as a JSON record: type, message, backtrace, the driver's
+    # code when it has one, and its causes nested under `cause` down to the
+    # depth limit. The block adds fields a specific exception type carries.
+    def serialize(error, &extra)
+      serialize_at(error, 1, {}, &extra)
+    end
+
+    # `seen` is created fresh by `serialize` for each top-level call, so one
+    # call never skips a cause another call already recorded.
+    def serialize_at(error, depth, seen, &extra)
+      seen[error.object_id] = true
+      serialized = {type: error.class.name, message: error.message, backtrace: error.backtrace}
+      code = error_code(error)
+      serialized[:code] = code unless code.nil?
+      serialized.merge!(extra.call(error)) if extra
+      cause = error.cause
+      if cause && !seen[cause.object_id] && depth < MAX_DEPTH
+        serialized[:cause] = serialize_at(cause, depth + 1, seen, &extra)
+      end
+      serialized
+    end
+    private_class_method :serialize_at
+
+    def error_code(error)
+      CODE_METHODS.each do |name|
+        next unless error.respond_to?(name)
+
+        value = begin
+          error.public_send(name)
+        rescue
+          nil
+        end
+        return value if value.is_a?(String) || value.is_a?(Integer)
+      end
+      nil
+    end
+  end
+end

data/lib/bitfab/replay.rb

@@ -160,13 +160,9 @@ module Bitfab
     def json_safe(value)
       case value
       when Exception
-        serialized = {type: value.class.name, message: value.message, backtrace: value.backtrace}
-        if value.is_a?(DbBranchReplayError)
-          serialized[:code] = value.code
-          serialized[:original_trace_id] = value.original_trace_id
-          serialized[:cause] = json_safe(value.cause) if value.cause
+        ErrorChain.serialize(value) do |error|
+          error.is_a?(DbBranchReplayError) ? {original_trace_id: error.original_trace_id} : {}
         end
-        serialized
       when Hash
         value.to_h { |key, child| [key, json_safe(child)] }
       when Array
@@ -177,7 +173,7 @@ module Bitfab
     end
 
     def replay_item_error_message(error)
-      return error.message unless error.is_a?(DbBranchReplayError)
+      return ErrorChain.describe(error) unless error.is_a?(DbBranchReplayError)
 
       "Replay requested a database branch for trace #{error.original_trace_id} but it " \
         "could not be resolved (#{error.code}): #{error.message}. The method was not run, " \
@@ -1528,7 +1524,7 @@ module Bitfab
         input: kwargs.empty? ? args : [*args, kwargs],
         result: fn_result,
         original_output: item["output"],
-        error: item_error&.message,
+        error: item_error && ErrorChain.describe(item_error),
         trace_error: fn_error,
         replay_error:,
         duration_ms: replay_duration_ms,

data/lib/bitfab/subtree.rb

@@ -740,7 +740,7 @@ module Bitfab
         return unless entry.is_a?(OpenSpan)
 
         exception = event.raised_exception
-        entry.error = "#{exception.class}: #{exception.message}"
+        entry.error = "#{exception.class}: #{ErrorChain.describe(exception)}"
       end
 
       def clear_rescued_error(event)

data/lib/bitfab/version.rb

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

data/lib/bitfab.rb

@@ -5,6 +5,7 @@ require "json"
 require_relative "bitfab/version"
 require_relative "bitfab/constants"
 require_relative "bitfab/warn_once"
+require_relative "bitfab/error_chain"
 require_relative "bitfab/experiment_id"
 require_relative "bitfab/payload_budget"
 require_relative "bitfab/serialize"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.75.1
+  version: 0.75.3
 platform: ruby
 authors:
 - Harvest Team
@@ -183,6 +183,7 @@ files:
 - lib/bitfab/db_snapshot.rb
 - lib/bitfab/detached_trace.rb
 - lib/bitfab/env.rb
+- lib/bitfab/error_chain.rb
 - lib/bitfab/experiment_id.rb
 - lib/bitfab/experiments.rb
 - lib/bitfab/git_command.rb