bitfab 0.51.2 → 0.51.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea799ee55cf7c1ac7167300d800d9593162ddc6b906557c12c3079607fcfc4f4
-  data.tar.gz: f7985925a6a8b3cf8c5e2ea4389bd8122646f5bf2eb5bf59e6769d9f533636b1
+  metadata.gz: 571e505294f7f5abe3b1d4c8521c4427cf30c105e03eb87509e70dd929559f43
+  data.tar.gz: 2a39fa504e22027f19a845efb156fb6a7c38d4a1187b7df64dad1623b5cccb4b
 SHA512:
-  metadata.gz: 10c67dc35cf10ed1c445108ce1801993b8f4115afda9411fe1dc3b9e12213ab090441e91c6a59a0864925822a09d344360e4d10ab15cac0a1a183c56d007972e
-  data.tar.gz: 2f968a4c58b66fd51d49c74199b20207a44aecd56285656b2ece8df04a76e9070b9f87c7dcbb53f2eeedfe61ba0a271d68660b934b4a56eb1f8fca278221f452
+  metadata.gz: e4146889a3a1f02b3bca7a104810067d59ec1e138cd099dc4822d241bcf34a6cb1514535d0bb902628e18a990bb31b5b1c79074cb946bdae7416bad3121a877c
+  data.tar.gz: ab9ab7427fb6065d4a6c1748b780a60d12b70302971b474927741653da400f60deb8a739addb5eb60ef79e7e9c791922538c86cbe53f163a1eb69c4dd175b87b

data/README.md

@@ -215,6 +215,51 @@ end
 #       └─ check_fraud (grandchild)
 ```
 
+### Experimental Subtree Tracing
+
+Use `bitfab_trace` to record a root method and every first-party Ruby method it calls without wrapping each descendant:
+
+```ruby
+class OrderPipeline
+  include Bitfab::Traceable
+  bitfab_function "order-pipeline"
+
+  bitfab_trace :process, type: "agent"
+  def process(order_id)
+    validate(order_id)
+  end
+
+  def validate(order_id)
+    { order_id:, valid: true }
+  end
+end
+```
+
+Capture uses `TracePoint` only during the root call. It skips Ruby/runtime code, dependency gems, Bitfab SDK internals, blocks, lambdas, and forwarding wrappers. When the root belongs to an installed application gem, that gem is the first-party boundary; neighboring dependency gems remain excluded. It follows recursion, modules, inheritance, `define_method`, and same-thread child Fibers; aliases are recorded and excluded by the name that was invoked. Child Fibers created during capture inherit node policies, trace identity, parenting, and depth limits while retaining separate call stacks. Pre-existing Fibers, `Fiber.new(storage: nil)`, and child threads do not inherit subtree context. When an inner capture ends, child Fibers retain any still-active outer capture; inherited context expires once all enclosing captures end. While a root remains active, hitting `max_spans` stops new capture but allows already-open spans in every Fiber to finish. `max_depth:`, `max_spans:`, `exclude:`, and `include_wrappers:` control the subtree. Automatically captured calls are not replay mock targets. Declare a call with `bitfab_span` when replay must substitute it: its explicit span records once, and automatic descendants continue beneath it.
+
+When capture ends, already-open automatic calls in suspended Fibers are emitted once with a nil output and `Subtree capture ended before the call returned` as the error, unless a real error was already observed. Their inputs and parenting are retained. The SDK does not resume Fibers, and later resumption cannot add spans to the ended capture. If hot reload moves the root to an unresolved source, the last valid first-party boundary and its exclusions remain in use.
+
+Returning an `Enumerator` keeps capture pending until iteration finishes or raises, including calls already paused in child Fibers. Capture is inactive between the initial return and consumption. Automatic spans record lazy return values as placeholders without iterating them; the traced root records the yielded values.
+
+A nested `bitfab_trace` with a different key starts an independent trace while the outer trace continues recording the overlapping subtree. Both traces have distinct trace and span IDs, including during replay, and the complete structure each root would record alone, so two active roots double span volume in their shared region. A recursive call or nested annotation using the same key stays in the active trace instead of creating another root.
+
+Configure a discovered method with `bitfab_node`. A node never creates a span or trace by itself; the active `bitfab_trace` owns its key, limits, parent, and lifecycle:
+
+```ruby
+bitfab_node :summarize,
+  name: "Model call",
+  type: "llm",
+  mock_on_replay: true,
+  finalize: ->(response) { {text: response.text} }
+def summarize(order)
+  model.generate(order)
+end
+```
+
+Nodes support `name:`, `type:`, `capture:`, `test_run_id:`, `mock_on_replay:`, and `finalize:`. `capture: false` omits the method while attaching captured descendants to its nearest visible parent. `finalize:` changes only the recorded output, never the return value. A finalizer failure is recorded on the node without crashing the caller. The before-`def`, inline, and after-`def` forms all preserve method visibility. For external code, use `Bitfab.client.node(MyClass, :method)`.
+
+`bitfab_trace` prepares its project boundary and exclusions when the method is declared, refreshes the boundary if the root definition moves during hot reload, caches canonical source paths, and shares one `TracePoint` dispatcher across active roots on the calling thread. After `max_spans` is exhausted, it stops collecting metadata and values immediately, then stops processing events for that session once its captured calls finish. Each active root still captures and serializes its own copy of every overlapping call, so this remains a discovery tool rather than the production default. Prefer explicit `bitfab_span` declarations on hot paths. Run `mise exec -- ruby -Ilib benchmark/subtree.rb` from this package to measure the no-network caller path on your Ruby build.
+
 ### Input/Output Capture
 
 Positional and keyword arguments are automatically captured:
@@ -427,6 +472,10 @@ See [bitfab-ruby-example/](../bitfab-ruby-example/) for complete working example
 
 - [test_span.rb](../bitfab-ruby-example/scripts/test_span.rb) - Basic span creation
 - [test_nested_spans.rb](../bitfab-ruby-example/scripts/test_nested_spans.rb) - Nested span hierarchies
+- [test_subtree.rb](../bitfab-ruby-example/scripts/test_subtree.rb) - Whole-subtree capture with independent overlapping roots
+- [test_subtree_comprehensive.rb](../bitfab-ruby-example/scripts/test_subtree_comprehensive.rb) - Self-checking subtree and node behavior examples, including child-Fiber context and installed application gems
+- [test_subtree_replay.rb](../bitfab-ruby-example/scripts/test_subtree_replay.rb) - Live subtree record and replay
+- [subtree coverage map](../bitfab-ruby-example/subtree_examples/README.md) - Every subtree spec behavior mapped to its runnable example
 - [test_wrap.rb](../bitfab-ruby-example/scripts/test_wrap.rb) - Wrapping external code
 - [test_enabled.rb](../bitfab-ruby-example/scripts/test_enabled.rb) - Using the enabled flag
 - [test_metadata.rb](../bitfab-ruby-example/scripts/test_metadata.rb) - Custom metadata

data/lib/bitfab/client.rb

@@ -7,6 +7,7 @@ require_relative "constants"
 require_relative "http_client"
 require_relative "replay"
 require_relative "span_context"
+require_relative "subtree"
 require_relative "serialize"
 require_relative "timestamp"
 require_relative "warn_once"
@@ -303,6 +304,23 @@ module Bitfab
       BitfabFunction.new(self, trace_function_key)
     end
 
+    # Configure an existing method only when it is discovered beneath a
+    # bitfab_trace root owned by this client.
+    def node(klass, method_name, name: nil, type: "custom", capture: true,
+      test_run_id: nil, mock_on_replay: false, finalize: nil)
+      Bitfab::Traceable.node(
+        klass,
+        method_name,
+        name:,
+        type:,
+        capture:,
+        test_run_id:,
+        mock_on_replay:,
+        finalize:,
+        client: self
+      )
+    end
+
     # Fetch one persisted span without loading the full trace.
     # Exactly one of id or name is required. Name lookups return the last
     # matching span by default; occurrence also accepts "first" or a zero-based
@@ -327,7 +345,8 @@ module Bitfab
     # Execute a block inside a span context, sending trace data on completion.
     # Called by Traceable, not intended for direct use.
     def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:,
-      capture_when: "always", mock_on_replay: false)
+      capture_when: "always", mock_on_replay: false, independent_root: false,
+      explicit_span_receiver: nil, explicit_span_method_name: nil, test_run_id: nil, finalize: nil)
       # Decide at CALL time, not construction. The key may be set after the
       # client is built (env loaded later), so re-checking per call lets a
       # late-resolved key take effect.
@@ -359,13 +378,24 @@ module Bitfab
       resolved_input_source_span_id = nil
       begin
         replay_ctx = ReplayContext.current
-        parent = SpanContext.current || ReplayContext.current_span
-        trace_id = parent ? parent[:trace_id] : (replay_ctx&.dig(:trace_id) || SecureRandom.uuid)
+        # A subtree annotation declares a trace-function root, even when it is
+        # invoked inside another span. Outer subtree sessions keep observing it
+        # through TracePoint instead of owning this root span.
+        ambient_parent = SpanContext.current || ReplayContext.current_span
+        parent = independent_root ? nil : ambient_parent
+        if parent && (subtree_parent_span_id = Subtree.current_parent_span_id(parent[:trace_id]))
+          parent = parent.merge(span_id: subtree_parent_span_id)
+        end
+        trace_id = if independent_root && ambient_parent
+          SecureRandom.uuid
+        else
+          parent&.dig(:trace_id) || replay_ctx&.dig(:trace_id) || SecureRandom.uuid
+        end
         span_id = SecureRandom.uuid
         parent_span_id = parent&.dig(:span_id)
         is_root_span = parent_span_id.nil?
         started_at = Bitfab.now_iso_timestamp
-        resolved_test_run_id = replay_ctx&.dig(:test_run_id)
+        resolved_test_run_id = replay_ctx ? replay_ctx[:test_run_id] : test_run_id
         resolved_input_source_span_id = replay_ctx&.dig(:input_source_span_id)
         resolved_input_source_trace_id = replay_ctx&.dig(:input_source_trace_id)
 
@@ -439,18 +469,28 @@ module Bitfab
       error = nil
       span_contexts = nil
       span_prompt = nil
-      finalized = false
+      completed = false
 
-      finalize = lambda do |final_result, final_error|
+      complete = lambda do |final_result, final_error|
         # Never crash the host app due to span building/sending. Idempotent:
         # only the first call sends the span. Subsequent calls (e.g. from the
         # enumerator wrapper after iteration completes) are no-ops.
-        next if finalized
+        next if completed
 
-        finalized = true
+        completed = true
 
         begin
           ended_at = Bitfab.now_iso_timestamp
+          recorded_result = final_result
+          recorded_error = final_error
+          if finalize && final_error.nil?
+            begin
+              recorded_result = finalize.call(final_result)
+            rescue => e
+              recorded_result = nil
+              recorded_error = "finalize failed: #{e.message}"
+            end
+          end
 
           send_span(
             trace_function_key:,
@@ -464,8 +504,8 @@ module Bitfab
             prompt: span_prompt,
             args:,
             kwargs:,
-            result: final_result,
-            error: final_error,
+            result: recorded_result,
+            error: recorded_error,
             started_at:,
             ended_at:,
             test_run_id: resolved_test_run_id,
@@ -514,8 +554,22 @@ module Bitfab
 
       begin
         ReplayContext.with_span(trace_id:, span_id:) do
-          SpanContext.with_span(trace_id:, span_id:) do
-            result = yield
+          SpanContext.with_span(
+            trace_id:,
+            span_id:,
+            explicit_span_receiver:,
+            explicit_span_method_name: explicit_span_method_name&.to_sym
+          ) do
+            result = if explicit_span_receiver
+              Subtree.with_borrowed_span(
+                trace_id:,
+                span_id:,
+                receiver: explicit_span_receiver,
+                method_name: explicit_span_method_name
+              ) { yield }
+            else
+              yield
+            end
           ensure
             # Capture contexts before the span context is popped
             span_contexts = SpanContext.current&.dig(:contexts)
@@ -524,7 +578,7 @@ module Bitfab
         end
       rescue => e
         error = e.message
-        finalize.call(result, error)
+        complete.call(result, error)
         raise
       end
 
@@ -542,10 +596,17 @@ module Bitfab
       # once iteration completes (or errors).
       #
       if result.is_a?(Enumerator)
-        return wrap_enumerator(result, trace_id:, span_id:, finalize:)
+        return wrap_enumerator(
+          result,
+          trace_id:,
+          span_id:,
+          complete:,
+          explicit_span_receiver:,
+          explicit_span_method_name:
+        )
       end
 
-      finalize.call(result, error)
+      complete.call(result, error)
       result
     end
 
@@ -606,8 +667,13 @@ module Bitfab
     # callbacks nest under the parent span. Yielded values are collected as the
     # span output. The span is sent exactly once: when iteration finishes,
     # raises, or the wrapper is `.close`d.
-    def wrap_enumerator(source, trace_id:, span_id:, finalize:)
+    def wrap_enumerator(source, trace_id:, span_id:, complete:, explicit_span_receiver: nil,
+      explicit_span_method_name: nil)
       span_entry = {trace_id:, span_id:}
+      if explicit_span_receiver
+        span_entry[:explicit_span_receiver] = explicit_span_receiver
+        span_entry[:explicit_span_method_name] = explicit_span_method_name&.to_sym
+      end
       yielded = []
 
       Enumerator.new do |yielder|
@@ -619,13 +685,26 @@ module Bitfab
           SpanContext.with_fiber_bridge(trace_id:, span_id:) do
             SpanContext.stack.push(span_entry)
             begin
-              source.each do |value|
-                yielded << value
-                yielder << value
+              iterate = lambda do
+                source.each do |value|
+                  yielded << value
+                  yielder << value
+                end
+              end
+              if explicit_span_receiver
+                Subtree.with_borrowed_span(
+                  trace_id:,
+                  span_id:,
+                  receiver: explicit_span_receiver,
+                  method_name: explicit_span_method_name,
+                  &iterate
+                )
+              else
+                iterate.call
               end
-              finalize.call(yielded, nil)
+              complete.call(yielded, nil)
             rescue => e
-              finalize.call(yielded, e.message)
+              complete.call(yielded, e.message)
               raise
             ensure
               SpanContext.stack.pop
@@ -1009,5 +1088,22 @@ module Bitfab
         client: @client
       )
     end
+
+    # Experimentally trace an existing method and its first-party call subtree.
+    def trace(klass, method_name, name: nil, type: "custom",
+      max_depth: Subtree::DEFAULT_MAX_DEPTH, max_spans: Subtree::DEFAULT_MAX_SPANS,
+      exclude: [], include_wrappers: false)
+      Bitfab::Traceable.trace(
+        klass, method_name,
+        trace_function_key: @trace_function_key,
+        name:,
+        type:,
+        max_depth:,
+        max_spans:,
+        exclude:,
+        include_wrappers:,
+        client: @client
+      )
+    end
   end
 end

data/lib/bitfab/span_context.rb

@@ -133,7 +133,7 @@ module Bitfab
     end
 
     def current
-      stack.last || fiber_bridge_stack.last
+      stack.last || Subtree.fiber_context&.inherited_span || fiber_bridge_stack.last
     end
 
     # Enumerator.new and enum_for run their source body in another Fiber on
@@ -149,8 +149,12 @@ module Bitfab
 
     # Execute a block with a new span pushed onto the stack.
     # The span is automatically popped when the block completes.
-    def with_span(trace_id:, span_id:)
+    def with_span(trace_id:, span_id:, explicit_span_receiver: nil, explicit_span_method_name: nil)
       entry = {trace_id:, span_id:}
+      if explicit_span_receiver
+        entry[:explicit_span_receiver] = explicit_span_receiver
+        entry[:explicit_span_method_name] = explicit_span_method_name
+      end
       stack.push(entry)
       yield
     ensure