bitfab 0.51.9 → 0.57.0

data/lib/bitfab/traceable.rb

@@ -53,32 +53,28 @@ module Bitfab
     #   preserve the bound client through the fluent wrapper, matching Python's
     #   `BitfabFunction.span()` and TypeScript's `BitfabFunction.withSpan()`.
     def self.wrap(klass, method_name, trace_function_key:, name: nil, type: "custom",
-      capture_when: "always", mock_on_replay: false, client: nil)
-      span_name = name || method_name.to_s
+      capture_when: "always", mock_on_replay: false, finalize: nil, test_run_id: nil, client: nil)
       method_name_str = method_name.to_s
       bound_client = client
-
       wrapper = Module.new do
         define_method(method_name) do |*args, **kwargs, &block|
-          target_client = bound_client || Bitfab.client
+          target_client = bound_client || Bitfab.client_or_nil
+          next super(*args, **kwargs, &block) unless target_client
+
+          Subtree.assert_surface!(:span) if target_client.send(:should_record?)
           target_client.send(:execute_span,
             trace_function_key:,
-            span_name:,
-            span_type: type,
-            function_name: method_name_str,
-            args:,
-            kwargs:,
-            capture_when:,
-            mock_on_replay:,
-            explicit_span_receiver: self,
-            explicit_span_method_name: method_name) do
+            span_name: name || Subtree.qualified_name(self, method_name),
+            span_type: type, function_name: method_name_str, args:, kwargs:,
+            capture_when:, mock_on_replay:, finalize:, test_run_id:, surface: :span,
+            explicit_span_receiver: self, explicit_span_method_name: method_name) do
             super(*args, **kwargs, &block)
           end
         end
       end
-
       wrapper.instance_variable_set(:@bitfab_span_method, method_name_str)
       wrapper.instance_variable_set(:@bitfab_span_key, trace_function_key)
+      preserve_visibility(klass, wrapper, method_name)
       klass.prepend(wrapper)
     end
 
@@ -87,44 +83,49 @@ module Bitfab
     # beneath it record automatically as function spans.
     def self.trace(klass, method_name, trace_function_key:, name: nil, type: "custom",
       max_depth: Subtree::DEFAULT_MAX_DEPTH, max_spans: Subtree::DEFAULT_MAX_SPANS,
-      exclude: [], include_wrappers: false, client: nil)
-      source = source_of(klass, method_name)
-      capture_config = Subtree.prepare(root_source: source, exclude:)
-      span_name = name || method_name.to_s
+      max_captured_subtree_spans: Subtree::DEFAULT_MAX_CAPTURED_SUBTREE_SPANS,
+      exclude: [], include_wrappers: false, mock_on_replay_default: false, client: nil)
+      validate_trace_options!(max_spans:)
+      capture_config = Subtree.prepare(root_source: source_of(klass, method_name), exclude:)
       method_name_str = method_name.to_s
       bound_client = client
-
       wrapper = Module.new do
         define_method(method_name) do |*args, **kwargs, &block|
-          if Subtree.active_trace?(trace_function_key)
-            next super(*args, **kwargs, &block)
+          target_client = bound_client || Bitfab.client_or_nil
+          next super(*args, **kwargs, &block) unless target_client&.send(:should_record?)
+
+          Subtree.assert_surface!(:trace)
+          next super(*args, **kwargs, &block) if Subtree.nested_root_suppressed?
+
+          target_client.send(:wait_for_simulation_plan) unless Subtree.current_session
+
+          span_name = name || Subtree.qualified_name(self, method_name)
+          managed = SpanContext.current&.dig(:recording_override)
+          if managed && managed.empty? && (ReplayContext.current || SeedContext.current)
+            managed.merge!(name: span_name, type:, function_name: method_name_str, instrumentation: "trace")
+            SpanContext.current[:surface] = :trace
+            next Subtree.capture(
+              client: target_client, trace_function_key:, config: capture_config,
+              max_depth:, max_spans:, max_captured_subtree_spans:, include_wrappers:, mock_on_replay_default:,
+              root_receiver: self, root_method_name: method_name
+            ) { super(*args, **kwargs, &block) }
           end
-
-          target_client = bound_client || Bitfab.client
-          target_client.send(
-            :execute_span,
-            trace_function_key:,
-            span_name:,
-            span_type: type,
-            function_name: method_name_str,
-            args:,
-            kwargs:,
-            independent_root: true
-          ) do
+          call = Subtree::ConfiguredCall.new(receiver: self, method_name:, name: span_name,
+            type:, args:, kwargs:, nested_trace_key: trace_function_key)
+          target_client.send(:execute_span,
+            trace_function_key:, span_name:, span_type: type,
+            function_name: method_name_str, args:, kwargs:, independent_root: true,
+            surface: :trace, span_data: call.span_data,
+            on_start: call.method(:start), on_complete: call.method(:complete),
+            around_body: call.method(:run)) do
             Subtree.capture(
-              client: target_client,
-              trace_function_key:,
-              config: capture_config,
-              max_depth:,
-              max_spans:,
-              include_wrappers:,
-              root_receiver: self,
-              root_method_name: method_name
+              client: target_client, trace_function_key:, config: capture_config,
+              max_depth:, max_spans:, max_captured_subtree_spans:, include_wrappers:, mock_on_replay_default:,
+              root_receiver: self, root_method_name: method_name
             ) { super(*args, **kwargs, &block) }
           end
         end
       end
-
       wrapper.instance_variable_set(:@bitfab_span_method, method_name_str)
       wrapper.instance_variable_set(:@bitfab_span_key, trace_function_key)
       preserve_visibility(klass, wrapper, method_name)
@@ -134,55 +135,42 @@ module Bitfab
     # Configure an existing method only when it is discovered beneath a
     # bitfab_trace root. Outside subtree capture the method runs unchanged.
     def self.node(klass, method_name, name: nil, type: "custom", capture: true,
-      test_run_id: nil, mock_on_replay: false, finalize: nil, client: nil)
+      test_run_id: nil, mock_on_replay: nil, finalize: nil, client: nil)
       validate_node_options!(capture:, mock_on_replay:)
-      span_name = name || method_name.to_s
       method_name_str = method_name.to_s
       bound_client = client
-
       wrapper = Module.new do
         define_method(method_name) do |*args, **kwargs, &block|
+          Subtree.assert_surface!(:trace)
           session = Subtree.current_session
           if !session || (bound_client && !session.client.equal?(bound_client))
             next super(*args, **kwargs, &block)
           end
-
           unless capture
             next Subtree.with_suppressed_node(receiver: self, method_name:) do
               super(*args, **kwargs, &block)
             end
           end
 
-          if session.excluded?(method_name)
-            next Subtree.with_suppressed_node(receiver: self, method_name:, sessions: [session]) do
-              super(*args, **kwargs, &block)
-            end
+          span_name = name || Subtree.qualified_name(self, method_name)
+          call = Subtree::ConfiguredCall.new(receiver: self, method_name:, name: span_name,
+            type:, args:, kwargs:, test_run_id:)
+          unless call.owner
+            next call.run { super(*args, **kwargs, &block) }
           end
-
-          unless session.reserve_node
-            next Subtree.with_suppressed_node(receiver: self, method_name:, sessions: [session]) do
-              super(*args, **kwargs, &block)
-            end
+          policy = mock_on_replay.nil? ? call.owner.mock_on_replay_default : mock_on_replay
+          call.with_owner_parent do
+            call.owner.client.send(:execute_span,
+              trace_function_key: call.owner.trace_function_key,
+              span_name:, span_type: type, function_name: method_name_str,
+              args:, kwargs:, capture_when: "nested", mock_on_replay: policy,
+              explicit_span_receiver: self, explicit_span_method_name: method_name,
+              test_run_id:, finalize:, surface: :trace, result_recorded_elsewhere: call.recorded_elsewhere?,
+              on_start: call.method(:start), on_complete: call.method(:complete),
+              around_body: call.method(:run)) { super(*args, **kwargs, &block) }
           end
-
-          session.client.send(
-            :execute_span,
-            trace_function_key: session.trace_function_key,
-            span_name:,
-            span_type: type,
-            function_name: method_name_str,
-            args:,
-            kwargs:,
-            capture_when: "nested",
-            mock_on_replay:,
-            explicit_span_receiver: self,
-            explicit_span_method_name: method_name,
-            test_run_id:,
-            finalize:
-          ) { super(*args, **kwargs, &block) }
         end
       end
-
       preserve_visibility(klass, wrapper, method_name)
       klass.prepend(wrapper)
     end
@@ -205,6 +193,14 @@ module Bitfab
     end
     private_class_method :preserve_visibility
 
+    def self.validate_trace_options!(max_spans:)
+      return if max_spans.is_a?(Integer) && max_spans >= 1
+
+      raise ArgumentError,
+        "bitfab_trace max_spans must be an integer of at least 1 because the root span takes one slot, got #{max_spans.inspect}."
+    end
+    private_class_method :validate_trace_options!
+
     def self.validate_node_options!(capture:, mock_on_replay:)
       return unless !capture && mock_on_replay
 
@@ -278,7 +274,7 @@ module Bitfab
       #   When true, `client.replay(...)` returns this span's
       #   historical output instead of executing the wrapped method.
       def bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom",
-        capture_when: "always", mock_on_replay: false)
+        capture_when: "always", mock_on_replay: false, finalize: nil, test_run_id: nil)
         trace_function_key ||= @bitfab_function_key
         unless trace_function_key
           raise "No trace function key provided. Pass `trace_function_key:` to `bitfab_span` " \
@@ -288,7 +284,7 @@ module Bitfab
         # If the method already exists (inline or after-method style), wrap it immediately
         if method_defined?(method_name) || private_method_defined?(method_name)
           _bitfab_wrap_method(
-            method_name, trace_function_key:, name:, type:, capture_when:, mock_on_replay:
+            method_name, trace_function_key:, name:, type:, capture_when:, mock_on_replay:, finalize:, test_run_id:
           )
         else
           # Method doesn't exist yet (before-method style) - register for method_added hook
@@ -298,7 +294,9 @@ module Bitfab
             name:,
             type:,
             capture_when:,
-            mock_on_replay:
+            mock_on_replay:,
+            finalize:,
+            test_run_id:
           }
         end
       end
@@ -307,7 +305,9 @@ module Bitfab
       # Descendants require no Bitfab declarations and record as function spans.
       def bitfab_trace(method_name, trace_function_key: nil, name: nil, type: "custom",
         max_depth: Subtree::DEFAULT_MAX_DEPTH, max_spans: Subtree::DEFAULT_MAX_SPANS,
-        exclude: [], include_wrappers: false)
+        max_captured_subtree_spans: Subtree::DEFAULT_MAX_CAPTURED_SUBTREE_SPANS,
+        exclude: [], include_wrappers: false, mock_on_replay_default: false)
+        Traceable.send(:validate_trace_options!, max_spans:)
         trace_function_key ||= @bitfab_function_key
         unless trace_function_key
           raise "No trace function key provided. Pass `trace_function_key:` to `bitfab_trace` " \
@@ -320,8 +320,10 @@ module Bitfab
           type:,
           max_depth:,
           max_spans:,
+          max_captured_subtree_spans:,
           exclude:,
-          include_wrappers:
+          include_wrappers:,
+          mock_on_replay_default:
         }
         if method_defined?(method_name) || private_method_defined?(method_name)
           _bitfab_trace_method(method_name, **config)
@@ -334,7 +336,7 @@ module Bitfab
       # EXPERIMENTAL. Configure one method discovered beneath bitfab_trace.
       # The node inherits the active trace key and never traces by itself.
       def bitfab_node(method_name, name: nil, type: "custom", capture: true,
-        test_run_id: nil, mock_on_replay: false, finalize: nil)
+        test_run_id: nil, mock_on_replay: nil, finalize: nil)
         Traceable.send(:validate_node_options!, capture:, mock_on_replay:)
         config = {name:, type:, capture:, test_run_id:, mock_on_replay:, finalize:}
         if method_defined?(method_name) || private_method_defined?(method_name)
@@ -361,88 +363,16 @@ module Bitfab
         end
       end
 
-      def _bitfab_wrap_method(method_name, trace_function_key:, name: nil, type: "custom",
-        capture_when: "always", mock_on_replay: false)
-        span_name = name || method_name.to_s
-        method_name_str = method_name.to_s
-
-        wrapper = Module.new do
-          define_method(method_name) do |*args, **kwargs, &block|
-            # If Bitfab was never configured, run the real method untraced
-            # rather than raising a "not configured" error into the host app.
-            client = Bitfab.client_or_nil
-            return super(*args, **kwargs, &block) unless client
-
-            client.send(:execute_span,
-              trace_function_key:,
-              span_name:,
-              span_type: type,
-              function_name: method_name_str,
-              args:,
-              kwargs:,
-              capture_when:,
-              mock_on_replay:,
-              explicit_span_receiver: self,
-              explicit_span_method_name: method_name) do
-              super(*args, **kwargs, &block)
-            end
-          end
-        end
-
-        wrapper.instance_variable_set(:@bitfab_span_method, method_name_str)
-        wrapper.instance_variable_set(:@bitfab_span_key, trace_function_key)
-        prepend(wrapper)
+      def _bitfab_wrap_method(method_name, **options)
+        Traceable.wrap(self, method_name, **options)
       end
 
-      def _bitfab_trace_method(method_name, trace_function_key:, name: nil, type: "custom",
-        max_depth: Subtree::DEFAULT_MAX_DEPTH, max_spans: Subtree::DEFAULT_MAX_SPANS,
-        exclude: [], include_wrappers: false)
-        source = Traceable.send(:source_of, self, method_name)
-        capture_config = Subtree.prepare(root_source: source, exclude:)
-        span_name = name || method_name.to_s
-        method_name_str = method_name.to_s
-
-        wrapper = Module.new do
-          define_method(method_name) do |*args, **kwargs, &block|
-            if Subtree.active_trace?(trace_function_key)
-              next super(*args, **kwargs, &block)
-            end
-
-            client = Bitfab.client_or_nil
-            return super(*args, **kwargs, &block) unless client
-
-            client.send(
-              :execute_span,
-              trace_function_key:,
-              span_name:,
-              span_type: type,
-              function_name: method_name_str,
-              args:,
-              kwargs:,
-              independent_root: true
-            ) do
-              Subtree.capture(
-                client:,
-                trace_function_key:,
-                config: capture_config,
-                max_depth:,
-                max_spans:,
-                include_wrappers:,
-                root_receiver: self,
-                root_method_name: method_name
-              ) { super(*args, **kwargs, &block) }
-            end
-          end
-        end
-
-        wrapper.instance_variable_set(:@bitfab_span_method, method_name_str)
-        wrapper.instance_variable_set(:@bitfab_span_key, trace_function_key)
-        Traceable.send(:preserve_visibility, self, wrapper, method_name)
-        prepend(wrapper)
+      def _bitfab_trace_method(method_name, **options)
+        Traceable.trace(self, method_name, **options)
       end
 
       def _bitfab_node_method(method_name, name: nil, type: "custom", capture: true,
-        test_run_id: nil, mock_on_replay: false, finalize: nil)
+        test_run_id: nil, mock_on_replay: nil, finalize: nil)
         Traceable.node(
           self,
           method_name,

data/lib/bitfab/version.rb

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

data/lib/bitfab.rb

@@ -14,13 +14,20 @@ require_relative "bitfab/git_state"
 require_relative "bitfab/span_context"
 require_relative "bitfab/http_client"
 require_relative "bitfab/datasets"
+require_relative "bitfab/assertion_categories"
 require_relative "bitfab/traces"
+require_relative "bitfab/assertions"
+require_relative "bitfab/labels"
+require_relative "bitfab/graders"
 require_relative "bitfab/mock_override"
 require_relative "bitfab/replay"
 require_relative "bitfab/replay_branch"
 require_relative "bitfab/client"
+require_relative "bitfab/seed"
+require_relative "bitfab/baml"
 require_relative "bitfab/traceable"
 require_relative "bitfab/replay_registry"
+require_relative "bitfab/seed_cli"
 require_relative "bitfab/replay_cli"
 
 module Bitfab
@@ -79,8 +86,8 @@ module Bitfab
     # @example
     #   Bitfab.configure(api_key: ENV["BITFAB_API_KEY"])
     #
-    def configure(api_key: nil, service_url: nil, enabled: nil, strict: false)
-      @client = Client.new(api_key:, service_url:, enabled:, strict:)
+    def configure(api_key: nil, service_url: nil, capture_enabled: nil, enabled: nil, strict: false, simulation_plan: true, timeout: 120, trace_across_threads: nil, env_vars: nil, baml_client: nil, db_snapshot: nil)
+      @client = Client.new(api_key:, service_url:, capture_enabled:, enabled:, strict:, simulation_plan:, timeout:, trace_across_threads:, env_vars:, baml_client:, db_snapshot:)
     end
 
     # Returns the global client, raising if not configured.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.51.9
+  version: 0.57.0
 platform: ruby
 authors:
 - Harvest Team
@@ -43,6 +43,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -133,32 +147,49 @@ email:
 - team@goharvest.ai
 executables:
 - bitfab-replay
+- bitfab-seed
 extensions: []
 extra_rdoc_files: []
 files:
 - README.md
 - exe/bitfab-replay
+- exe/bitfab-seed
 - lib/bitfab.rb
+- lib/bitfab/assertion_categories.rb
+- lib/bitfab/assertions.rb
+- lib/bitfab/baml.rb
 - lib/bitfab/client.rb
 - lib/bitfab/commit_ref.rb
 - lib/bitfab/compress.rb
 - lib/bitfab/constants.rb
 - lib/bitfab/datasets.rb
 - lib/bitfab/db_snapshot.rb
+- lib/bitfab/detached_trace.rb
 - lib/bitfab/env.rb
 - lib/bitfab/git_command.rb
 - lib/bitfab/git_state.rb
+- lib/bitfab/graders.rb
 - lib/bitfab/http_client.rb
+- lib/bitfab/labels.rb
 - lib/bitfab/mock_override.rb
 - lib/bitfab/otel.rb
 - lib/bitfab/payload_budget.rb
 - lib/bitfab/replay.rb
 - lib/bitfab/replay_branch.rb
 - lib/bitfab/replay_cli.rb
+- lib/bitfab/replay_concurrency.rb
+- lib/bitfab/replay_memory.rb
+- lib/bitfab/replay_processes.rb
 - lib/bitfab/replay_registry.rb
+- lib/bitfab/seed.rb
+- lib/bitfab/seed_cli.rb
+- lib/bitfab/seed_context.rb
 - lib/bitfab/serialize.rb
+- lib/bitfab/simulation_plan.rb
 - lib/bitfab/span_context.rb
+- lib/bitfab/span_origin.rb
 - lib/bitfab/subtree.rb
+- lib/bitfab/thread_propagation.rb
 - lib/bitfab/timestamp.rb
 - lib/bitfab/trace_completion.rb
 - lib/bitfab/traceable.rb