bitfab 0.59.0 → 0.59.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f71ead77c070efe05df2af12495ef411048fd0164655e0f1fbe11a5457b518c
-  data.tar.gz: 4e9a222f559e2977366ecf411f97429db22f89d1aca6b8b6de767b982594f8ce
+  metadata.gz: 9a45f5360238ae79c517f3514f96a7d02dbad382d4c1c3987ab3d2474d64d85d
+  data.tar.gz: 05af89e2fd6fbaed6ae530b4718234c72ad3a91001fc91da151b4a29cb4acc4b
 SHA512:
-  metadata.gz: 406d7de1521d252c335432fa44c04fd7f3e11f0992281388d8939140ab05b5b055cb3cd5a4dc6bf30cfba15a40795f7c1f21782d989bbbebd1abeac62e5ff7fc
-  data.tar.gz: 9e80632bfc746766ffd6011ceb45848a2875590e29b2f9c983b4c4ed344b722c310a15a760b6d4bd99045357f9def49b08904bb53618ad0dedbf5b33c2c4cffe
+  metadata.gz: 305b1b0ea90a88ef5306eec5c0aaa622f76f0f7f9caaf6d64986c690908ceb34598a0225a4049fbf0d88d5788dc196fc0246ce29f860b000943ec08c0322568e
+  data.tar.gz: 7a022d2714b3e617dfa0a24efb7eecaec531f9bf264a693c5c05b20076a282a4ffe0b85ebb1eff2deb5a75c737951597c975230a72a7f3316c327ed9984a0bfc

data/README.md

@@ -256,7 +256,7 @@ def summarize(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)`.
+Nodes support `name:`, `type:`, `capture:`, `experiment_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 a span limit is reached, it stops reading inputs and outputs 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.
 

data/lib/bitfab/client.rb

@@ -106,7 +106,7 @@ module Bitfab
       tracing_enabled?
     end
 
-    # Replay historical traces through a method and create a test run.
+    # Replay historical traces through a method and create an experiment.
     #
     # @param receiver [Object, Class] an instance for instance methods, or a Class for class methods
     # @param method_name [Symbol] the method to replay
@@ -183,10 +183,16 @@ module Bitfab
     # @param on_item_start [#call, nil] optional callback invoked when a worker
     #   begins processing each item. Pair it with on_item_finish to distinguish
     #   queued work from in-flight work. A raising callback never crashes the run.
-    # @return [Hash] with :items, :test_run_id, :test_run_url
+    # @param on_experiment_start [#call, nil] optional callback invoked once,
+    #   right after the server creates the experiment and before any item runs,
+    #   with a hash { experiment_id:, experiment_url: }. A raising callback never
+    #   crashes the run.
+    # @return [Hash] with :items, :experiment_id, :experiment_url, and the
+    #   deprecated aliases :test_run_id and :test_run_url carrying the same values
     def replay(receiver, method_name = nil, trace_function_key:, limit: nil, trace_ids: nil, concurrency: nil, max_concurrency: ReplayConcurrency::UNSET,
       name: nil, code_change_description: Replay::CODE_CHANGE_UNSET, code_change_files: Replay::CODE_CHANGE_UNSET, experiment_group_id: nil, dataset_id: nil, dataset_ids: nil, grader_ids: nil, mock: "marked", attempts: ReplayConcurrency::UNSET, only_with_assertions: false, judge_assertions: false, dry_run: false,
-      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_item_start: nil, on_item_finish: nil, on_progress: nil)
+      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_item_start: nil, on_item_finish: nil, on_progress: nil,
+      on_experiment_start: nil)
       Replay.run(
         self,
         receiver,
@@ -213,7 +219,8 @@ module Bitfab
         db_branch:,
         on_item_start:,
         on_item_finish:,
-        on_progress:
+        on_progress:,
+        on_experiment_start:
       )
     end
 
@@ -330,14 +337,15 @@ module Bitfab
     # 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: nil, finalize: nil)
+      experiment_id: nil, mock_on_replay: nil, finalize: nil, test_run_id: nil)
+      experiment_id = Bitfab.resolve_experiment_id(experiment_id, test_run_id)
       Bitfab::Traceable.node(
         klass,
         method_name,
         name:,
         type:,
         capture:,
-        test_run_id:,
+        experiment_id:,
         mock_on_replay:,
         finalize:,
         client: self
@@ -376,7 +384,7 @@ module Bitfab
     # 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, independent_root: false,
-      explicit_span_receiver: nil, explicit_span_method_name: nil, test_run_id: nil, finalize: nil,
+      explicit_span_receiver: nil, explicit_span_method_name: nil, experiment_id: nil, finalize: nil,
       surface: nil, on_start: nil, on_complete: nil, around_body: nil, span_data: {}, managed_root: false,
       result_recorded_elsewhere: false, declared_node: false)
       return yield unless should_record?
@@ -405,7 +413,7 @@ module Bitfab
       parent_span_id = nil
       is_root_span = nil
       started_at = nil
-      resolved_test_run_id = nil
+      resolved_experiment_id = nil
       resolved_input_source_span_id = nil
       begin
         replay_ctx = ReplayContext.current
@@ -433,7 +441,7 @@ module Bitfab
           )
         end
         started_at = Bitfab.now_iso_timestamp
-        resolved_test_run_id = replay_ctx ? replay_ctx[:test_run_id] : test_run_id
+        resolved_experiment_id = replay_ctx ? replay_ctx[:experiment_id] : experiment_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)
 
@@ -442,7 +450,7 @@ module Bitfab
           TraceState.create(
             trace_id,
             trace_function_key:,
-            test_run_id: resolved_test_run_id,
+            experiment_id: resolved_experiment_id,
             input_source_trace_id: resolved_input_source_trace_id,
             replay_attempt: replay_ctx&.dig(:replay_attempt),
             db_snapshot: @db_snapshot
@@ -483,7 +491,7 @@ module Bitfab
               kwargs:,
               mocked_output:,
               started_at:,
-              test_run_id: resolved_test_run_id,
+              experiment_id: resolved_experiment_id,
               input_source_span_id: resolved_input_source_span_id,
               mock_source:,
               instrumentation: (surface == :trace) ? "trace" : "span",
@@ -573,7 +581,7 @@ module Bitfab
             error: recorded_error,
             started_at:,
             ended_at:,
-            test_run_id: resolved_test_run_id,
+            experiment_id: resolved_experiment_id,
             input_source_span_id: resolved_input_source_span_id
           )
 
@@ -931,8 +939,9 @@ module Bitfab
       if trace_state&.dig(:session_id)
         payload["sessionId"] = trace_state[:session_id]
       end
-      if trace_state&.dig(:test_run_id)
-        payload["testRunId"] = trace_state[:test_run_id]
+      if trace_state&.dig(:experiment_id)
+        payload["experimentId"] = trace_state[:experiment_id]
+        payload["testRunId"] = trace_state[:experiment_id]
       end
 
       @http_client.send_external_trace(payload)
@@ -943,7 +952,7 @@ module Bitfab
 
     def send_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,
       span_name:, span_type:, function_name:, contexts:, prompt:, args:, kwargs:, result:, error:,
-      started_at:, ended_at:, test_run_id: nil, input_source_span_id: nil, mocked: false,
+      started_at:, ended_at:, experiment_id: nil, input_source_span_id: nil, mocked: false,
       mock_target: nil, mock_source: nil, span_data: {}, instrumentation: "span", declared_node: false,
       nearest_captured_ancestor_span_id: nil)
       extra_span_data = span_data
@@ -1016,7 +1025,10 @@ module Bitfab
         "rootTraceFunctionKey" => TraceState.get(trace_id)&.dig(:trace_function_key) || trace_function_key,
         "rawSpan" => raw_span
       }
-      payload["testRunId"] = test_run_id if test_run_id
+      if experiment_id
+        payload["experimentId"] = experiment_id
+        payload["testRunId"] = experiment_id
+      end
       # Flag spans served from the original trace's recorded output during a
       # replay so the trace view can mark them (matches the Python and
       # TypeScript SDKs).
@@ -1163,12 +1175,12 @@ module Bitfab
       nil
     end
 
-    # Record a span entry for a mocked invocation so the test run reflects the
+    # Record a span entry for a mocked invocation so the experiment reflects the
     # mocked execution. Mirrors send_span's payload shape but with the mocked
     # output as the result and no error.
     def send_mocked_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,
       span_name:, span_type:, function_name:, args:, kwargs:, mocked_output:,
-      started_at:, test_run_id:, input_source_span_id:, mock_source:, instrumentation: "span", declared_node: false)
+      started_at:, experiment_id:, input_source_span_id:, mock_source:, instrumentation: "span", declared_node: false)
       ended_at = Bitfab.now_iso_timestamp
       send_span(
         trace_function_key:,
@@ -1186,7 +1198,7 @@ module Bitfab
         error: nil,
         started_at:,
         ended_at:,
-        test_run_id:,
+        experiment_id:,
         input_source_span_id:,
         mocked: true,
         instrumentation:,
@@ -1234,7 +1246,8 @@ module Bitfab
     #   values warn once and default to "always"
     # @param mock_on_replay [Boolean] mark this span for the default "marked"
     #   mock strategy. A missing selected occurrence fails closed.
-    def wrap(klass, method_name, name: nil, type: "custom", capture_when: "always", mock_on_replay: false, finalize: nil, test_run_id: nil)
+    def wrap(klass, method_name, name: nil, type: "custom", capture_when: "always", mock_on_replay: false, finalize: nil, experiment_id: nil, test_run_id: nil)
+      experiment_id = Bitfab.resolve_experiment_id(experiment_id, test_run_id)
       Bitfab::Traceable.wrap(
         klass,
         method_name,
@@ -1244,7 +1257,7 @@ module Bitfab
         capture_when:,
         mock_on_replay:,
         finalize:,
-        test_run_id:,
+        experiment_id:,
         client: @client
       )
     end

data/lib/bitfab/experiment_id.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Bitfab
+  class << self
+    def resolve_experiment_id(experiment_id, test_run_id)
+      return experiment_id if test_run_id.nil?
+
+      if !experiment_id.nil? && experiment_id != test_run_id
+        raise ArgumentError, "experiment_id and test_run_id name the same experiment ID but were " \
+          "passed different values. Pass experiment_id only; test_run_id is deprecated."
+      end
+      warn_once("test-run-id-deprecated", "test_run_id: is deprecated; use experiment_id: instead.")
+      test_run_id
+    end
+  end
+end

data/lib/bitfab/http_client.rb

@@ -241,7 +241,7 @@ module Bitfab
     end
 
     # Start a replay session by fetching historical traces.
-    # Blocking call. Returns hash with testRunId, testRunUrl, and items array.
+    # Blocking call. Returns hash with experimentId, experimentUrl, and items array.
     #
     # @param code_change_description [String, nil] optional rationale for the
     #   code change being tested in this replay
@@ -250,7 +250,7 @@ module Bitfab
     # @param experiment_group_id [String, nil] optional UUID grouping multiple
     #   replay runs into a single experiment batch
     # @param name [String, nil] optional display name for the resulting
-    #   experiment/test run
+    #   experiment
     # @param dataset_ids [Array<String>, nil] optional UUIDs of the datasets this
     #   replay runs against. The run replays the union of their traces, graded by
     #   the union of their graders, and is attributed to every one of them. A
@@ -344,9 +344,9 @@ module Bitfab
       get(endpoint, timeout: 30)
     end
 
-    # Mark a replay test run as completed. Blocking call.
-    def complete_replay(test_run_id)
-      request("/api/sdk/replay/complete", {"testRunId" => test_run_id}, timeout: 30)
+    # Mark a replay experiment as completed. Blocking call.
+    def complete_replay(experiment_id)
+      request("/api/sdk/replay/complete", {"experimentId" => experiment_id, "testRunId" => experiment_id}, timeout: 30)
     end
 
     # Release a previously-resolved DB branch by deleting its Neon branch.
@@ -356,8 +356,8 @@ module Bitfab
       request("/api/sdk/replay/releaseDbBranchLease", {"neonBranchId" => neon_branch_id}, timeout: 30)
     end
 
-    def resolve_db_branch_lease(test_run_id, trace_id, db_branch_settings = nil, attempt = 0)
-      payload = {"testRunId" => test_run_id, "traceId" => trace_id}
+    def resolve_db_branch_lease(experiment_id, trace_id, db_branch_settings = nil, attempt = 0)
+      payload = {"experimentId" => experiment_id, "testRunId" => experiment_id, "traceId" => trace_id}
       payload["attempt"] = attempt if attempt.positive?
       payload["dbBranchSettings"] = db_branch_settings unless db_branch_settings.nil?
       request(
@@ -398,10 +398,10 @@ module Bitfab
     end
 
     # Read the replay traces the server has fully persisted so far.
-    def get_replay_status(test_run_id, expected_span_counts)
+    def get_replay_status(experiment_id, expected_span_counts)
       request(
         "/api/sdk/replay/status",
-        {"testRunId" => test_run_id, "expectedSpanCounts" => expected_span_counts},
+        {"experimentId" => experiment_id, "testRunId" => experiment_id, "expectedSpanCounts" => expected_span_counts},
         timeout: 30
       )
     end

data/lib/bitfab/labels.rb

@@ -15,29 +15,36 @@ module Bitfab
     end
 
     def save(label:, annotation:, trace_id: nil, original_trace_id: nil, attempt: nil,
-      confidence: nil, test_run_id: nil, assertion_id: nil, evidence: EVIDENCE_UNSET)
+      confidence: nil, experiment_id: nil, assertion_id: nil, evidence: EVIDENCE_UNSET, test_run_id: nil)
+      experiment_id = Bitfab.resolve_experiment_id(experiment_id, test_run_id)
       update = label_target(trace_id:, original_trace_id:, attempt:, assertion_id:)
       update["label"] = label
       update["annotation"] = annotation
       update["confidence"] = confidence unless confidence.nil?
       update["evidence"] = evidence unless evidence.equal?(EVIDENCE_UNSET)
-      save_all([update], test_run_id:).first
+      save_all([update], experiment_id:).first
     end
 
-    def save_all(labels, test_run_id: nil)
+    def save_all(labels, experiment_id: nil, test_run_id: nil)
+      experiment_id = Bitfab.resolve_experiment_id(experiment_id, test_run_id)
       payload = {"labels" => labels}
-      payload["testRunId"] = test_run_id unless test_run_id.nil?
+      unless experiment_id.nil?
+        payload["experimentId"] = experiment_id
+        payload["testRunId"] = experiment_id
+      end
       @http_client.request(LABELS_PATH, payload)["labels"]
     end
 
-    def skip(trace_id: nil, original_trace_id: nil, attempt: nil, test_run_id: nil, assertion_id: nil)
+    def skip(trace_id: nil, original_trace_id: nil, attempt: nil, experiment_id: nil, assertion_id: nil, test_run_id: nil)
+      experiment_id = Bitfab.resolve_experiment_id(experiment_id, test_run_id)
       update = label_target(trace_id:, original_trace_id:, attempt:, assertion_id:)
-      save_all([update.merge("skip" => true)], test_run_id:).first
+      save_all([update.merge("skip" => true)], experiment_id:).first
     end
 
-    def archive(trace_id: nil, original_trace_id: nil, attempt: nil, test_run_id: nil, assertion_id: nil)
+    def archive(trace_id: nil, original_trace_id: nil, attempt: nil, experiment_id: nil, assertion_id: nil, test_run_id: nil)
+      experiment_id = Bitfab.resolve_experiment_id(experiment_id, test_run_id)
       update = label_target(trace_id:, original_trace_id:, attempt:, assertion_id:)
-      save_all([update.merge("archive" => true)], test_run_id:).first
+      save_all([update.merge("archive" => true)], experiment_id:).first
     end
 
     def save_human(label:, annotation:, trace_id:, confidence: nil, assertion_id: nil,
@@ -77,7 +84,7 @@ module Bitfab
     def label_target(trace_id:, original_trace_id:, attempt:, assertion_id:)
       if trace_id.nil? == original_trace_id.nil?
         raise ArgumentError, "Pass exactly one of trace_id or original_trace_id. " \
-          "Use original_trace_id for a replay verdict, with the test_run_id it ran under."
+          "Use original_trace_id for a replay verdict, with the experiment_id it ran under."
       end
 
       update = {}

data/lib/bitfab/replay.rb

@@ -27,13 +27,23 @@ module Bitfab
 
   # Whole-run replay failure with every item collected before the run failed.
   class ReplayError < StandardError
-    attr_reader :items, :test_run_id, :test_run_url
+    attr_reader :items, :experiment_id, :experiment_url
 
-    def initialize(message, items:, test_run_id:, test_run_url:)
+    def initialize(message, items:, experiment_id: nil, experiment_url: nil, test_run_id: nil, test_run_url: nil)
       super(message)
       @items = items
-      @test_run_id = test_run_id
-      @test_run_url = test_run_url
+      @experiment_id = experiment_id || test_run_id
+      @experiment_url = experiment_url || test_run_url
+    end
+
+    # @deprecated Use {#experiment_id}.
+    def test_run_id
+      experiment_id
+    end
+
+    # @deprecated Use {#experiment_url}.
+    def test_run_url
+      experiment_url
     end
   end
 
@@ -73,13 +83,13 @@ module Bitfab
 
     # Execute a block with replay context set for every fiber on the current
     # thread. Child threads and processes intentionally do not inherit it.
-    def with_context(test_run_id:, input_source_span_id: nil, input_source_trace_id: nil, trace_id: nil,
+    def with_context(experiment_id:, input_source_span_id: nil, input_source_trace_id: nil, trace_id: nil,
       mock_tree: nil, mock_strategy: nil, mock_overrides: nil, fetch_span_output: nil,
       db_branch_lease: nil, db_branch_timings: nil, source_bitfab_trace_id: nil, replay_attempt: nil)
       previous = Thread.current.thread_variable_get(REPLAY_CONTEXT_KEY)
       ctx = {
         replay_attempt:,
-        test_run_id:,
+        experiment_id:,
         input_source_span_id:,
         input_source_trace_id:,
         trace_id:,
@@ -127,7 +137,7 @@ module Bitfab
     end
   end
 
-  # Replay historical traces through a traced method and create a test run.
+  # Replay historical traces through a traced method and create an experiment.
   module Replay
     CODE_CHANGE_UNSET = Object.new.freeze
     PERSISTENCE_TIMEOUT_SECONDS = 30.0
@@ -167,19 +177,19 @@ module Bitfab
       items.map { |item| item.except(:_sdk_trace_id) }
     end
 
-    def preserve_replay_failure(items, test_run_id, test_run_url)
+    def preserve_replay_failure(items, experiment_id, experiment_url)
       yield
     rescue => cause
       error = ReplayError.new(
         cause.message,
         items: public_replay_items(items),
-        test_run_id:,
-        test_run_url:
+        experiment_id:,
+        experiment_url:
       )
       raise error, cause:
     end
 
-    # Replay historical traces through a method and create a test run.
+    # Replay historical traces through a method and create an experiment.
     #
     # Fetches the last N traces for the given trace function key, re-runs each
     # through the provided receiver and method, and returns comparison data.
@@ -193,7 +203,7 @@ module Bitfab
     #   already determines how many traces replay. Supplying trace_ids also
     #   emits a warning.
     # @param trace_ids [Array<String>, nil] optional list of trace IDs to replay (max 100)
-    # @param name [String, nil] optional display name for the resulting experiment/test run
+    # @param name [String, nil] optional display name for the resulting experiment
     # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
     # @param code_change_description [String, nil] optional rationale for the
     #   code change being tested in this replay (stored on the experiment).
@@ -255,11 +265,18 @@ module Bitfab
     #   begins processing each item, before replay setup and customer code run.
     #   Pair it with on_item_finish to distinguish queued work from in-flight work.
     #   A raising callback never crashes the run.
-    # @return [Hash] with :items, :test_run_id, :test_run_url
+    # @param on_experiment_start [#call, nil] optional callback invoked once,
+    #   right after the server creates the experiment and before any item runs,
+    #   with a hash { experiment_id:, experiment_url: }. Use it to show the
+    #   experiment link even if the run later fails. A raising callback never
+    #   crashes the run.
+    # @return [Hash] with :items, :experiment_id, :experiment_url, and the
+    #   deprecated aliases :test_run_id and :test_run_url carrying the same values
     def run(client, receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, name: nil,
       concurrency: nil, max_concurrency: ReplayConcurrency::UNSET, code_change_description: CODE_CHANGE_UNSET, code_change_files: CODE_CHANGE_UNSET, experiment_group_id: nil,
       dataset_id: nil, dataset_ids: nil, grader_ids: nil, mock: "marked", attempts: ReplayConcurrency::UNSET, only_with_assertions: false, judge_assertions: false, dry_run: false,
-      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_item_start: nil, on_item_finish: nil, on_progress: nil)
+      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_item_start: nil, on_item_finish: nil, on_progress: nil,
+      on_experiment_start: nil)
       concurrency_options = ReplayConcurrency.resolve(concurrency, attempts, max_concurrency)
       attempts = concurrency_options.attempts
       max_concurrency = concurrency_options.max_concurrency
@@ -293,7 +310,7 @@ module Bitfab
       # Reject a trace_function_key that contradicts the method's declared key.
       # replay() fetches historical traces by trace_function_key but records the
       # replayed spans under the method's own bitfab_span key (via send below),
-      # so a mismatch produces an incoherent test run (traces fetched for one
+      # so a mismatch produces an incoherent experiment (traces fetched for one
       # function, recorded under another). Only fires when the method's key is
       # introspectable; an untraced method falls through to the persistence
       # check in complete_replay. Mirrors the TypeScript/Python SDKs.
@@ -358,9 +375,16 @@ module Bitfab
         include_original_metadata: !adapt_inputs.nil?,
         db_branch_settings: resolved_db_branch_settings
       )
-      test_run_id = replay_data["testRunId"]
-      test_run_url = replay_data["testRunUrl"]
-      full_test_run_url = "#{client.service_url}#{test_run_url}"
+      experiment_id = replay_data["experimentId"] || replay_data["testRunId"]
+      experiment_url = replay_data["experimentUrl"] || replay_data["testRunUrl"]
+      full_experiment_url = "#{client.service_url}#{experiment_url}"
+      if on_experiment_start
+        begin
+          on_experiment_start.call({experiment_id:, experiment_url: full_experiment_url})
+        rescue => e
+          warn "Bitfab: replay on_experiment_start callback raised: #{e.message}"
+        end
+      end
       server_items = attempts.times.flat_map do |attempt|
         (replay_data["items"] || []).map do |source|
           item = source.merge("attempt" => attempt)
@@ -373,7 +397,7 @@ module Bitfab
       end
 
       result_items = if server_items.any?
-        process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency, mock.to_s,
+        process_items(http_client, server_items, receiver, method_name, experiment_id, max_concurrency, mock.to_s,
           adapt_inputs, include_db_branch_lease, resolved_db_branch_settings, on_item_start:,
           on_item_finish: item_finish_callback,
           mock_overrides: resolved_overrides, dry_run:, process_executor:)
@@ -383,11 +407,14 @@ module Bitfab
 
       if dry_run
         begin
-          http_client.complete_replay(test_run_id)
+          http_client.complete_replay(experiment_id)
         rescue => e
           warn "Bitfab: could not finalize dry run: #{e.message}"
         end
-        result = {items: public_replay_items(result_items), test_run_id:, test_run_url: full_test_run_url, attempts:}
+        result = {
+          items: public_replay_items(result_items), experiment_id:, experiment_url: full_experiment_url,
+          test_run_id: experiment_id, test_run_url: full_experiment_url, attempts:
+        }
         write_replay_result_file(result)
         return result
       end
@@ -396,8 +423,8 @@ module Bitfab
       # to finalize once the server confirms every replay trace it queued: the
       # trace-ID mapping complete_replay builds would otherwise race the
       # in-flight batches and hand back nil for every item.
-      delivered_trace_ids = preserve_replay_failure(result_items, test_run_id, full_test_run_url) do
-        wait_for_replay_persistence(http_client, test_run_id, result_items.map { |item| item[:_sdk_trace_id] })
+      delivered_trace_ids = preserve_replay_failure(result_items, experiment_id, full_experiment_url) do
+        wait_for_replay_persistence(http_client, experiment_id, result_items.map { |item| item[:_sdk_trace_id] })
       end
 
       # Primary source for item[:trace_id]: the server's assigned traces.id, read
@@ -414,8 +441,8 @@ module Bitfab
       # complete_replay finalizes the run and returns the token/diagnostic
       # mapping; its failures propagate loudly because a run that never
       # completed can't be finalized.
-      complete_response = preserve_replay_failure(result_items, test_run_id, full_test_run_url) do
-        http_client.complete_replay(test_run_id)
+      complete_response = preserve_replay_failure(result_items, experiment_id, full_experiment_url) do
+        http_client.complete_replay(experiment_id)
       end
       trace_id_map = complete_response&.dig("traceIds")
       # Per-replay-trace token usage keyed by server trace id: the REPLAYED
@@ -431,7 +458,7 @@ module Bitfab
       # now that the row exists, attach each item's server-aggregated token usage,
       # and detect a systemic upload failure early. Verdict persistence does NOT
       # use this map: it is keyed by the original-trace lineage (:original_trace_id +
-      # test_run_id), which needs no client-held server id. Older servers that omit
+      # experiment_id), which needs no client-held server id. Older servers that omit
       # the map yield no replay tokens and leave item[:trace_id] nil.
       unless trace_id_map.nil?
         missing = []
@@ -461,14 +488,14 @@ module Bitfab
           server_count = trace_count.nil? ? "" : " The server persisted #{trace_count} trace(s) for this run."
           cause = RuntimeError.new("Replay completed but the server has no persisted trace for " \
             "any of the #{completed_count} completed item(s) " \
-            "(test_run_id #{test_run_id}).#{server_count} Trace uploads were " \
+            "(experiment #{experiment_id}).#{server_count} Trace uploads were " \
             "flushed, so either the uploads failed or the replayed method is " \
             "not traced (no root span was emitted).")
           error = ReplayError.new(
             cause.message,
             items: public_replay_items(result_items),
-            test_run_id:,
-            test_run_url: full_test_run_url
+            experiment_id:,
+            experiment_url: full_experiment_url
           )
           raise error, cause:
         end
@@ -477,7 +504,7 @@ module Bitfab
         if missing.any?
           warn "Bitfab: server has no persisted trace for #{missing.length} of " \
             "#{completed_count} completed replay item(s) " \
-            "(test_run_id #{test_run_id}). Their replay token usage is " \
+            "(experiment #{experiment_id}). Their replay token usage is " \
             "unavailable and they cannot be labeled."
         end
       end
@@ -489,8 +516,10 @@ module Bitfab
       result = {
         attempts:,
         items: result_items,
-        test_run_id:,
-        test_run_url: full_test_run_url
+        experiment_id:,
+        experiment_url: full_experiment_url,
+        test_run_id: experiment_id,
+        test_run_url: full_experiment_url
       }
       # Persist the enriched result so the Bitfab plugin never has to parse the
       # replay's stdout, which a dependency's logging can corrupt.
@@ -503,7 +532,8 @@ module Bitfab
         begin
           on_progress.call({
             type: "complete",
-            test_run_id:,
+            experiment_id:,
+            test_run_id: experiment_id,
             completed: total,
             total:,
             succeeded: total - errored,
@@ -744,7 +774,7 @@ module Bitfab
     end
 
     # Process all replay items, optionally in parallel using threads.
-    def process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency, mock_strategy,
+    def process_items(http_client, server_items, receiver, method_name, experiment_id, max_concurrency, mock_strategy,
       adapt_inputs = nil, include_db_branch_lease = false, db_branch_settings = nil, on_item_start: nil, on_item_finish: nil,
       mock_overrides: [], dry_run: false, process_executor: nil)
       concurrency = max_concurrency || server_items.length
@@ -774,7 +804,7 @@ module Bitfab
 
           begin
             on_item_start.call({
-              type: "started", test_run_id:, started:, completed:, total:, succeeded:, errored:,
+              type: "started", experiment_id:, test_run_id: experiment_id, started:, completed:, total:, succeeded:, errored:,
               item: {
                 attempt:,
                 original_trace_id:,
@@ -804,7 +834,7 @@ module Bitfab
         warn "Bitfab: replay per-item flush failed: #{e.message}"
       end
 
-      report = lambda do |result, original_trace_id, original_span_id, test_run_id|
+      report = lambda do |result, original_trace_id, original_span_id, experiment_id|
         # Deliver this item's trace now, then read its server id back off the
         # ingest response. A flush failure never crashes the run: the id stays
         # nil and the end-of-run barrier remains the authority on persistence.
@@ -818,7 +848,7 @@ module Bitfab
 
           begin
             on_item_finish.call({
-              test_run_id:, completed:, total:, succeeded:, errored:,
+              experiment_id:, test_run_id: experiment_id, completed:, total:, succeeded:, errored:,
               item: {
                 attempt: result[:attempt],
                 ingestion_type: result[:ingestion_type],
@@ -854,9 +884,9 @@ module Bitfab
 
       execute = lambda do |item|
         if process_executor
-          process_executor.call(item, test_run_id, mock_strategy, include_db_branch_lease, db_branch_settings, dry_run:)
+          process_executor.call(item, experiment_id, mock_strategy, include_db_branch_lease, db_branch_settings, dry_run:)
         else
-          process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy,
+          process_single_item(http_client, item, receiver, method_name, experiment_id, mock_strategy,
             adapt_inputs, include_db_branch_lease, db_branch_settings, mock_overrides:, dry_run:)
         end
       end
@@ -865,7 +895,7 @@ module Bitfab
         server_items.map do |item|
           report_start.call(original_trace_id_of(item), original_span_id_of(item), item["attempt"] || 0)
           result = execute.call(item)
-          report.call(result, original_trace_id_of(item), original_span_id_of(item), test_run_id)
+          report.call(result, original_trace_id_of(item), original_span_id_of(item), experiment_id)
           result
         end
       else
@@ -883,7 +913,7 @@ module Bitfab
               report_start.call(original_trace_id_of(item), original_span_id_of(item), item["attempt"] || 0)
               result = execute.call(item)
               results_mutex.synchronize { results[idx] = result }
-              report.call(result, original_trace_id_of(item), original_span_id_of(item), test_run_id)
+              report.call(result, original_trace_id_of(item), original_span_id_of(item), experiment_id)
             end
           end
         end
@@ -899,7 +929,7 @@ module Bitfab
     # deserializing inputs is captured on the returned item's :error rather
     # than propagated, so one bad trace never aborts the whole replay run
     # (mirrors the TypeScript and Python SDKs' per-item rescue).
-    def process_single_item(http_client, server_item, receiver, method_name, test_run_id, mock_strategy,
+    def process_single_item(http_client, server_item, receiver, method_name, experiment_id, mock_strategy,
       adapt_inputs = nil, include_db_branch_lease = false, db_branch_settings = nil, mock_overrides: [], dry_run: false)
       metrics = extract_server_item_metrics(server_item)
       attempt = server_item["attempt"] || 0
@@ -925,7 +955,7 @@ module Bitfab
       db_branch_timings = include_db_branch_lease ? server_item["dbBranchTimings"] : nil
       if include_db_branch_lease && lease.nil? && lease_error.nil?
         begin
-          resolved = http_client.resolve_db_branch_lease(test_run_id, original_trace_id, db_branch_settings, attempt)
+          resolved = http_client.resolve_db_branch_lease(experiment_id, original_trace_id, db_branch_settings, attempt)
         rescue => cause
           error = DbBranchReplayError.new(
             "lease_request_failed",
@@ -1001,7 +1031,7 @@ module Bitfab
         item_data,
         receiver,
         method_name,
-        test_run_id,
+        experiment_id,
         span["id"],
         metrics,
         input_source_trace_id: span["externalTraceId"],
@@ -1180,7 +1210,7 @@ module Bitfab
     # repeat itself. Acks cannot settle a request that timed out client-side
     # after the server committed, so anything short of fully delivered falls
     # through to the server poll, which stays the authority there.
-    def wait_for_replay_persistence(http_client, test_run_id, sdk_trace_ids, timeout: nil)
+    def wait_for_replay_persistence(http_client, experiment_id, sdk_trace_ids, timeout: nil)
       timeout ||= PERSISTENCE_TIMEOUT_SECONDS
       trace_ids = sdk_trace_ids.compact
 
@@ -1212,7 +1242,7 @@ module Bitfab
       missing = expected_span_counts.keys
 
       while missing.any?
-        status = http_client.get_replay_status(test_run_id, expected_span_counts)
+        status = http_client.get_replay_status(experiment_id, expected_span_counts)
         ready = status["traceIds"]
         ready = {} unless ready.is_a?(Hash)
         read_back_trace_ids.merge!(ready)
@@ -1230,7 +1260,7 @@ module Bitfab
           "spans likely never reached the server."
       end
       raise "Replay traces were not fully persisted before the delivery deadline " \
-        "(test_run_id #{test_run_id}, missing #{missing.length} of " \
+        "(experiment #{experiment_id}, missing #{missing.length} of " \
         "#{expected_span_counts.length} trace(s)).#{cause}"
     end
 
@@ -1249,7 +1279,7 @@ module Bitfab
     end
 
     # Execute a single replay item: deserialize inputs, call method with replay context.
-    def execute_item(item, receiver, method_name, test_run_id, input_source_span_id = nil, metrics = {},
+    def execute_item(item, receiver, method_name, experiment_id, input_source_span_id = nil, metrics = {},
       input_source_trace_id: nil, mock_strategy: "marked", mock_tree: nil, mock_overrides: nil,
       fetch_span_output: nil, adapt_inputs: nil, adapt_ctx: nil, db_branch_lease: nil, db_branch_timings: nil,
       source_bitfab_trace_id: nil, db_snapshot_ref: nil, http_client: nil, attempt: 0, dry_run: false)
@@ -1273,7 +1303,7 @@ module Bitfab
       begin
         ReplayContext.with_context(
           replay_attempt: attempt,
-          test_run_id:,
+          experiment_id:,
           input_source_span_id:,
           input_source_trace_id:,
           trace_id: sdk_trace_id,

data/lib/bitfab/replay_cli.rb

@@ -31,6 +31,7 @@ module Bitfab
       run(argv:, stdout:, stderr:)
       0
     rescue => error
+      stderr.puts "Experiment #{error.experiment_id}: #{error.experiment_url}" if error.is_a?(ReplayError) && error.experiment_id
       stderr.puts error.message
       1
     end

data/lib/bitfab/replay_processes.rb

@@ -46,15 +46,15 @@ module Bitfab
       result = nil
       Bitfab.collect_delivery_problems do
         result = Replay.process_single_item(http, assignment.fetch("item"), receiver, method_name,
-          assignment.fetch("test_run_id"), assignment.fetch("mock"), options[:adapt_inputs],
+          assignment.fetch("experiment_id"), assignment.fetch("mock"), options[:adapt_inputs],
           assignment.fetch("include_db_branch_lease"), assignment["db_branch_settings"],
           mock_overrides: overrides, dry_run: assignment.fetch("dry_run"))
         unless assignment["dry_run"]
           begin
-            mapped = Replay.wait_for_replay_persistence(http, assignment.fetch("test_run_id"), [result[:_sdk_trace_id]], timeout: delivery_timeout)
+            mapped = Replay.wait_for_replay_persistence(http, assignment.fetch("experiment_id"), [result[:_sdk_trace_id]], timeout: delivery_timeout)
             result[:trace_id] = mapped[result[:_sdk_trace_id]] || result[:trace_id]
             if result[:_sdk_trace_id] && result[:trace_id].nil?
-              status = http.get_replay_status(assignment.fetch("test_run_id"), {result[:_sdk_trace_id] => 1})
+              status = http.get_replay_status(assignment.fetch("experiment_id"), {result[:_sdk_trace_id] => 1})
               result[:trace_id] = status.fetch("traceIds", {})[result[:_sdk_trace_id]]
             end
             raise "Child replay trace persistence could not be confirmed" if result[:error].nil? && result[:trace_id].nil?
@@ -67,7 +67,7 @@ module Bitfab
         hook = options[:concurrency]&.on_item_finish_in_child_process
         if hook && !assignment["dry_run"]
           begin
-            hook.call({test_run_id: assignment.fetch("test_run_id"), item: Replay.public_replay_items([result]).first})
+            hook.call({experiment_id: assignment.fetch("experiment_id"), test_run_id: assignment.fetch("experiment_id"), item: Replay.public_replay_items([result]).first})
           rescue => error
             stderr.puts "[replay] child grading hook failed for #{result[:original_trace_id]} attempt #{result[:attempt]}: #{error}"
           end
@@ -130,14 +130,14 @@ module Bitfab
         @throttle = ReplayMemoryThrottle.new(enabled: concurrency.memory_throttle)
       end
 
-      def call(item, test_run_id, mock, include_db_branch_lease, db_branch_settings, dry_run: false)
+      def call(item, experiment_id, mock, include_db_branch_lease, db_branch_settings, dry_run: false)
         index = @mutex.synchronize { @sequence += 1 }
         @throttle.admit(index)
         result_path = File.join(@directory, "#{index}.result")
         assignment_path = File.join(@directory, "#{index}.json")
         stdout_path, stderr_path = File.join(@directory, "#{index}.out"), File.join(@directory, "#{index}.err")
         delivery_problems_path = File.join(@directory, "#{index}.delivery")
-        assignment = {pipeline: @args.fetch(:pipeline), params: @params, item:, test_run_id:, mock:, include_db_branch_lease:, db_branch_settings:, dry_run:, result_path:, delivery_problems_path:}
+        assignment = {pipeline: @args.fetch(:pipeline), params: @params, item:, experiment_id:, mock:, include_db_branch_lease:, db_branch_settings:, dry_run:, result_path:, delivery_problems_path:}
         File.write(assignment_path, JSON.generate(assignment), mode: "w", perm: 0o600)
         executable = File.expand_path("../../exe/bitfab-replay", __dir__)
         pid = @mutex.synchronize do

data/lib/bitfab/replay_registry.rb

@@ -240,6 +240,9 @@ module Bitfab
 
       stderr.puts "[replay] Replaying #{describe_selection(options)} from \"#{registration.trace_function_key}\"..."
 
+      options[:on_experiment_start] = lambda do |experiment|
+        stderr.puts "[replay] Experiment #{experiment[:experiment_id]}: #{experiment[:experiment_url]}"
+      end
       result = begin
         registration.client.replay(
           registration.receiver,
@@ -428,7 +431,7 @@ module Bitfab
         stderr.puts "  Missed expected:  #{missed}"
       end
       stderr.puts "  Errors:   #{errors}" if errors > 0
-      stderr.puts "\n  #{result[:test_run_url]}"
+      stderr.puts "\n  #{result[:experiment_url]}"
     end
   end
 end

data/lib/bitfab/span_context.rb

@@ -187,7 +187,7 @@ module Bitfab
       @states_mutex.synchronize { @states[trace_id] }
     end
 
-    def create(trace_id, test_run_id: nil, input_source_trace_id: nil, replay_attempt: nil, trace_function_key: nil, db_snapshot: nil)
+    def create(trace_id, experiment_id: nil, input_source_trace_id: nil, replay_attempt: nil, trace_function_key: nil, db_snapshot: nil)
       @states_mutex.synchronize do
         @states[trace_id] ||= begin
           started_at = Bitfab.now_iso_timestamp
@@ -195,7 +195,7 @@ module Bitfab
             trace_id:,
             trace_function_key:,
             started_at:,
-            test_run_id:,
+            experiment_id:,
             input_source_trace_id:,
             replay_attempt:,
             # Capture the wall clock now, before the wrapped function runs.

data/lib/bitfab/subtree.rb

@@ -50,7 +50,7 @@ module Bitfab
       :started_at,
       :error,
       :span_type,
-      :test_run_id,
+      :experiment_id,
       :span_data,
       :declared_node,
       keyword_init: true
@@ -83,7 +83,7 @@ module Bitfab
     class ConfiguredCall
       attr_reader :span_data, :owner
 
-      def initialize(receiver:, method_name:, name:, type:, args:, kwargs:, test_run_id: nil,
+      def initialize(receiver:, method_name:, name:, type:, args:, kwargs:, experiment_id: nil,
         nested_trace_key: nil)
         @receiver = receiver
         @method_name = method_name
@@ -93,7 +93,7 @@ module Bitfab
         @records = Subtree.active_sessions.map do |session|
           omitted = session.excluded?(method_name)
           entry = unless omitted
-            session.configured_entry(name:, type:, args:, kwargs:, test_run_id:)
+            session.configured_entry(name:, type:, args:, kwargs:, experiment_id:)
           end
           [session, entry, !omitted]
         end
@@ -189,7 +189,7 @@ module Bitfab
           trace_function_key:,
           trace_id: span[:trace_id],
           root_span_id: span[:span_id],
-          test_run_id: replay&.dig(:test_run_id),
+          experiment_id: replay&.dig(:experiment_id),
           input_source_span_id: replay&.dig(:input_source_span_id),
           config:,
           max_depth:,
@@ -416,7 +416,7 @@ module Bitfab
         @parent_session = session.parent_session if @parent_session.equal?(session)
       end
 
-      def initialize(client:, trace_function_key:, trace_id:, root_span_id:, test_run_id:,
+      def initialize(client:, trace_function_key:, trace_id:, root_span_id:, experiment_id:,
         input_source_span_id:, config:, max_depth:, include_wrappers:,
         root_receiver:, root_method_name:, max_captured_subtree_spans: DEFAULT_MAX_CAPTURED_SUBTREE_SPANS, mock_on_replay_default: false)
         @mock_on_replay_default = mock_on_replay_default
@@ -424,7 +424,7 @@ module Bitfab
         @trace_function_key = trace_function_key
         @trace_id = trace_id
         @root_span_id = root_span_id
-        @test_run_id = test_run_id
+        @experiment_id = experiment_id
         @input_source_span_id = input_source_span_id
         @root = config.root
         @root_path = config.root_path
@@ -532,13 +532,13 @@ module Bitfab
         entry&.span_data&.dig("content_off_by_simulation_plan") == true
       end
 
-      def configured_entry(name:, type:, args:, kwargs:, test_run_id:)
+      def configured_entry(name:, type:, args:, kwargs:, experiment_id:)
         return unless reserve_node
 
         entry = OpenSpan.new(
           span_id: SecureRandom.uuid,
           parent_span_id: current_parent_span_id,
-          name:, span_type: type, args:, kwargs:, test_run_id:, started_at: now,
+          name:, span_type: type, args:, kwargs:, experiment_id:, started_at: now,
           span_data: {}, declared_node: true
         )
         @configured_entries[entry.object_id] = entry
@@ -744,7 +744,7 @@ module Bitfab
           error: entry.error,
           started_at: entry.started_at,
           ended_at: now,
-          test_run_id: entry.test_run_id || @test_run_id,
+          experiment_id: entry.experiment_id || @experiment_id,
           input_source_span_id: @input_source_span_id
         )
       rescue Exception # rubocop:disable Lint/RescueException

data/lib/bitfab/traceable.rb

@@ -53,7 +53,8 @@ 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, finalize: nil, test_run_id: nil, client: nil)
+      capture_when: "always", mock_on_replay: false, finalize: nil, experiment_id: nil, client: nil, test_run_id: nil)
+      experiment_id = Bitfab.resolve_experiment_id(experiment_id, test_run_id)
       method_name_str = method_name.to_s
       bound_client = client
       wrapper = Module.new do
@@ -66,7 +67,7 @@ module Bitfab
             trace_function_key:,
             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,
+            capture_when:, mock_on_replay:, finalize:, experiment_id:, surface: :span,
             explicit_span_receiver: self, explicit_span_method_name: method_name) do
             super(*args, **kwargs, &block)
           end
@@ -134,7 +135,8 @@ 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: nil, finalize: nil, client: nil)
+      experiment_id: nil, mock_on_replay: nil, finalize: nil, client: nil, test_run_id: nil)
+      experiment_id = Bitfab.resolve_experiment_id(experiment_id, test_run_id)
       validate_node_options!(capture:, mock_on_replay:)
       method_name_str = method_name.to_s
       bound_client = client
@@ -153,7 +155,7 @@ module Bitfab
 
           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:)
+            type:, args:, kwargs:, experiment_id:)
           unless call.owner
             next call.run { super(*args, **kwargs, &block) }
           end
@@ -164,7 +166,7 @@ module Bitfab
               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?, declared_node: true,
+              experiment_id:, finalize:, surface: :trace, result_recorded_elsewhere: call.recorded_elsewhere?, declared_node: true,
               on_start: call.method(:start), on_complete: call.method(:complete),
               around_body: call.method(:run)) { super(*args, **kwargs, &block) }
           end
@@ -214,7 +216,7 @@ module Bitfab
     # replay() uses this to reject a trace_function_key that contradicts the
     # method's declared key: a mismatch fetches one function's historical
     # traces but re-records the replay under the method's own key, producing
-    # an incoherent test run. Mirrors the TypeScript and Python SDKs, which
+    # an incoherent experiment. Mirrors the TypeScript and Python SDKs, which
     # throw on the same key mismatch.
     def self.trace_function_key_for(receiver, method_name)
       name = method_name.to_s
@@ -265,7 +267,8 @@ 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, finalize: nil, test_run_id: nil)
+        capture_when: "always", mock_on_replay: false, finalize: nil, experiment_id: nil, test_run_id: nil)
+        experiment_id = Bitfab.resolve_experiment_id(experiment_id, test_run_id)
         trace_function_key ||= @bitfab_function_key
         unless trace_function_key
           raise "No trace function key provided. Pass `trace_function_key:` to `bitfab_span` " \
@@ -275,7 +278,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:, finalize:, test_run_id:
+            method_name, trace_function_key:, name:, type:, capture_when:, mock_on_replay:, finalize:, experiment_id:
           )
         else
           # Method doesn't exist yet (before-method style) - register for method_added hook
@@ -287,7 +290,7 @@ module Bitfab
             capture_when:,
             mock_on_replay:,
             finalize:,
-            test_run_id:
+            experiment_id:
           }
         end
       end
@@ -325,9 +328,10 @@ 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: nil, finalize: nil)
+        experiment_id: nil, mock_on_replay: nil, finalize: nil, test_run_id: nil)
+        experiment_id = Bitfab.resolve_experiment_id(experiment_id, test_run_id)
         Traceable.send(:validate_node_options!, capture:, mock_on_replay:)
-        config = {name:, type:, capture:, test_run_id:, mock_on_replay:, finalize:}
+        config = {name:, type:, capture:, experiment_id:, mock_on_replay:, finalize:}
         if method_defined?(method_name) || private_method_defined?(method_name)
           _bitfab_node_method(method_name, **config)
         else
@@ -361,14 +365,14 @@ module Bitfab
       end
 
       def _bitfab_node_method(method_name, name: nil, type: "custom", capture: true,
-        test_run_id: nil, mock_on_replay: nil, finalize: nil)
+        experiment_id: nil, mock_on_replay: nil, finalize: nil)
         Traceable.node(
           self,
           method_name,
           name:,
           type:,
           capture:,
-          test_run_id:,
+          experiment_id:,
           mock_on_replay:,
           finalize:,
           client: nil

data/lib/bitfab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitfab
-  VERSION = "0.59.0"
+  VERSION = "0.59.1"
 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/experiment_id"
 require_relative "bitfab/payload_budget"
 require_relative "bitfab/serialize"
 require_relative "bitfab/db_snapshot"
@@ -175,7 +176,10 @@ module Bitfab
     #   succeeded, errored, and item (the object replay already passes to
     #   on_item_finish)
     def report_replay_progress(progress)
-      warn("#{BITFAB_PROGRESS_PREFIX}#{Replay.json_safe(progress).to_json}")
+      payload = Replay.json_safe(progress)
+      experiment_id = progress[:experiment_id] if progress.is_a?(Hash)
+      payload = payload.merge(experimentId: experiment_id) unless experiment_id.nil?
+      warn("#{BITFAB_PROGRESS_PREFIX}#{payload.to_json}")
     rescue
       nil
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.59.0
+  version: 0.59.1
 platform: ruby
 authors:
 - Harvest Team
@@ -167,6 +167,7 @@ files:
 - lib/bitfab/db_snapshot.rb
 - lib/bitfab/detached_trace.rb
 - lib/bitfab/env.rb
+- lib/bitfab/experiment_id.rb
 - lib/bitfab/git_command.rb
 - lib/bitfab/git_state.rb
 - lib/bitfab/graders.rb