woods 1.6.1 → 2.0.0.beta2

data/lib/woods/embedding/openai.rb

@@ -2,6 +2,7 @@
 
 require 'net/http'
 require 'json'
+require_relative 'provider'
 
 module Woods
   module Embedding
@@ -17,6 +18,7 @@ module Woods
       #   vectors = provider.embed_batch(["text1", "text2"])
       class OpenAI
         include Interface
+        include DiscardableClient
 
         ENDPOINT = URI('https://api.openai.com/v1/embeddings')
         DEFAULT_MODEL = 'text-embedding-3-small'
@@ -33,9 +35,11 @@ module Woods
 
         # @param api_key [String] OpenAI API key
         # @param model [String] OpenAI embedding model name (default: text-embedding-3-small)
-        def initialize(api_key:, model: DEFAULT_MODEL)
+        # @param dimensions [Integer, nil] Requested output size for text-embedding-3 models
+        def initialize(api_key:, model: DEFAULT_MODEL, dimensions: nil)
           @api_key = api_key
           @model = model
+          @dimensions = normalize_dimensions(dimensions)
         end
 
         # Embed a single text string.
@@ -47,8 +51,10 @@ module Woods
         def embed(text)
           raise ArgumentError, 'embed(text) requires a non-empty string' if text.nil? || text.to_s.strip.empty?
 
-          response = post_request({ model: @model, input: text })
-          response['data'].first['embedding']
+          response = post_request(request_body(text))
+          vectors = Array(response['data']).map { |item| item['embedding'] }
+          VectorValidation.validate!(vectors, expected_count: 1, provider: 'OpenAI')
+          vectors.first
         end
 
         # Embed multiple texts in a single request.
@@ -59,16 +65,14 @@ module Woods
         # @return [Array<Array<Float>>] array of embedding vectors
         # @raise [Woods::Error] if the API returns an error
         # @raise [ArgumentError] if the array is empty or any element is nil/empty
-        def embed_batch(texts) # rubocop:disable Metrics/CyclomaticComplexity
+        def embed_batch(texts)
           raise ArgumentError, 'embed_batch(texts) requires a non-empty array' if texts.nil? || texts.empty?
           if texts.any? { |t| t.nil? || t.to_s.strip.empty? }
             raise ArgumentError, 'embed_batch(texts) rejects nil/empty entries (OpenAI returns 400)'
           end
 
-          response = post_request({ model: @model, input: texts })
-          response['data']
-            .sort_by { |item| item['index'] }
-            .map { |item| item['embedding'] }
+          response = post_request(request_body(texts))
+          extract_validated_batch(response, texts.size)
         end
 
         # Return the dimensionality of vectors produced by this model.
@@ -78,7 +82,7 @@ module Woods
         #
         # @return [Integer] number of dimensions
         def dimensions
-          DIMENSIONS[@model] || embed('test').length
+          @dimensions || DIMENSIONS[@model] || embed('test').length
         end
 
         # Return the model name.
@@ -98,6 +102,38 @@ module Woods
 
         private
 
+        # Validate the batch response's shape/cardinality/indexes and
+        # return vectors reordered to match the input order.
+        #
+        # @param response [Hash] parsed JSON response
+        # @param expected_count [Integer] number of texts requested
+        # @return [Array<Array<Float>>]
+        def extract_validated_batch(response, expected_count)
+          data = Array(response['data'])
+          VectorValidation.validate!(
+            data.map { |item| item['embedding'] },
+            expected_count: expected_count,
+            provider: 'OpenAI',
+            indexes: data.map { |item| item['index'] }
+          )
+          data.sort_by { |item| item['index'] }.map { |item| item['embedding'] }
+        end
+
+        def request_body(input)
+          { model: @model, input: input }.tap do |body|
+            body[:dimensions] = @dimensions if @dimensions
+          end
+        end
+
+        def normalize_dimensions(value)
+          return if value.nil?
+
+          dimensions = Integer(value)
+          raise ArgumentError, "dimensions must be positive, got #{value.inspect}" unless dimensions.positive?
+
+          dimensions
+        end
+
         # Cap interpolated response bodies so misconfigured API errors
         # (which occasionally echo request metadata, including headers) don't
         # unbounded-leak into logs or re-raised messages.
@@ -116,7 +152,7 @@ module Woods
         # @param body [Hash] request body
         # @return [Hash] parsed JSON response
         # @raise [Woods::Error] if the API returns a non-success status
-        def post_request(body) # rubocop:disable Metrics/AbcSize
+        def post_request(body)
           request = Net::HTTP::Post.new(ENDPOINT.path)
           request['Content-Type'] = 'application/json'
           request['Authorization'] = "Bearer #{@api_key}"
@@ -124,22 +160,44 @@ module Woods
 
           response = http_client.request(request)
 
-          unless response.is_a?(Net::HTTPSuccess)
-            raise Woods::Error, "OpenAI API error: #{response.code} #{truncate_response_body(response.body)}"
-          end
+          raise request_error(response) unless response.is_a?(Net::HTTPSuccess)
 
           JSON.parse(response.body)
-        rescue Errno::ECONNRESET, Net::OpenTimeout, IOError
-          # Connection dropped — reset and retry once
-          @http_client = nil
-          response = http_client.request(request)
-          unless response.is_a?(Net::HTTPSuccess)
-            raise Woods::Error, "OpenAI API error: #{response.code} #{truncate_response_body(response.body)}"
+        rescue Errno::ECONNRESET, Net::OpenTimeout, Net::ReadTimeout, IOError
+          # Connection dropped — reset and retry once. A second transport
+          # failure is wrapped (mirroring Ollama) rather than left to escape
+          # as a raw Errno, so callers rescuing Woods::Error see a typed,
+          # context-bearing failure.
+          #
+          # Net::ReadTimeout descends from Timeout::Error, not IOError, so it
+          # needs naming explicitly or a stalled response escapes both the
+          # retry and the typing (STO-15).
+          discard_http_client
+          begin
+            response = http_client.request(request)
+          rescue StandardError => retry_error
+            raise RequestError, "OpenAI API error (retry failed): #{retry_error.message}"
           end
+          raise request_error(response) unless response.is_a?(Net::HTTPSuccess)
 
           JSON.parse(response.body)
         end
 
+        # Build a {RequestError} from a non-success OpenAI response,
+        # attaching the HTTP status and any +Retry-After+ header so the
+        # resilience layer can classify the failure (429/5xx retryable,
+        # 400/401 not) and honor the server-requested back-off.
+        #
+        # @param response [Net::HTTPResponse]
+        # @return [RequestError]
+        def request_error(response)
+          RequestError.new(
+            "OpenAI API error: #{response.code} #{truncate_response_body(response.body)}",
+            http_status: response.code.to_i,
+            retry_after: response['Retry-After']
+          )
+        end
+
         # Return a reusable, started HTTP client for the OpenAI API.
         # Calling http.start opens a persistent TCP connection so
         # keep_alive_timeout actually takes effect across requests.

data/lib/woods/embedding/provider.rb

@@ -4,6 +4,11 @@ require 'net/http'
 require 'json'
 
 module Woods
+  # Standalone-load guard — keeps `require 'woods/embedding/provider'`
+  # working without the top-level woods.rb (same pattern as storage/
+  # and console/). {Provider::RequestError} subclasses this at load time.
+  class Error < StandardError; end unless defined?(Woods::Error)
+
   module Embedding
     # Interface and adapters for embedding providers.
     #
@@ -61,6 +66,151 @@ module Woods
         end
       end
 
+      # Shared connection hygiene for adapters that hold one persistent
+      # Net::HTTP client in +@http_client+. Closing a connection before
+      # dropping the reference keeps the descriptor from lingering until GC.
+      module DiscardableClient
+        # Close the persistent connection before dropping the reference.
+        # Nil-ing +@http_client+ alone abandons the open socket — the
+        # descriptor stays allocated until GC finalizes the object — so
+        # finish it first. Finish raises IOError on a session that was never
+        # started, and a connection that died mid-request can refuse to close
+        # cleanly; the rescue keeps the discard best-effort and only
+        # guarantees the reference is dropped.
+        #
+        # @return [void]
+        def discard_http_client
+          @http_client&.finish
+        rescue StandardError
+          nil
+        ensure
+          @http_client = nil
+        end
+      end
+
+      # Raised when an embedding API answers with a non-success HTTP
+      # response. Carries the HTTP status and the raw +Retry-After+ header
+      # (when the server sent one) so {Woods::Resilience::RetryableProvider}
+      # can distinguish transient failures (429 rate limits, 5xx) from
+      # hopeless ones (400 bad request, 401 bad credentials) and honor the
+      # server's requested back-off instead of its own schedule.
+      #
+      # Subclasses {Woods::Error}, so existing `rescue Woods::Error` call
+      # sites keep working unchanged.
+      class RequestError < Woods::Error
+        # @return [Integer, nil] HTTP status code of the failed response
+        attr_reader :http_status
+
+        # @return [String, nil] raw +Retry-After+ header value (delta-seconds
+        #   or HTTP-date form), or nil when the server sent none
+        attr_reader :retry_after
+
+        # @param message [String] human-readable error message
+        # @param http_status [Integer, nil] HTTP status code
+        # @param retry_after [String, nil] raw +Retry-After+ header value
+        def initialize(message, http_status: nil, retry_after: nil)
+          super(message)
+          @http_status = http_status
+          @retry_after = retry_after
+        end
+      end
+
+      # Raised when a provider's embedding response is malformed: wrong
+      # cardinality, missing/duplicate OpenAI response indexes, a
+      # non-finite/non-numeric or empty vector, or a vector whose dimension
+      # disagrees with the rest of the batch. Left unvalidated, any of
+      # these stores nil or mis-paired vectors and silently corrupts the
+      # vector store.
+      class InvalidEmbeddingResponse < Woods::Error
+        # @return [String] the provider label ("OpenAI", "Ollama")
+        attr_reader :provider
+
+        # @return [Integer] the number of texts in the request this response answers
+        attr_reader :batch_size
+
+        # @param message [String] what specifically was wrong with the response
+        # @param provider [String] provider label
+        # @param batch_size [Integer] number of texts requested
+        def initialize(message, provider:, batch_size:)
+          @provider = provider
+          @batch_size = batch_size
+          super("#{provider} embedding response invalid for batch of #{batch_size}: #{message}")
+        end
+      end
+
+      # Shared response-shape validation for embedding providers. A short
+      # or malformed provider response — fewer vectors than requested,
+      # duplicate/missing OpenAI response indexes, a NaN/Infinity/nil
+      # entry, or a dimension that drifts partway through a batch — would
+      # otherwise store nil or mis-paired vectors with no error at all,
+      # corrupting the index silently. Every provider's `embed`/
+      # `embed_batch` must call {.validate!} before returning.
+      module VectorValidation
+        module_function
+
+        # @param vectors [Array<Array<Numeric>>] vectors about to be returned/stored,
+        #   in whatever order the caller has them (order doesn't matter for these checks)
+        # @param expected_count [Integer] number of texts in the request
+        # @param provider [String] provider label used in the raised error's message
+        # @param indexes [Array<Integer>, nil] raw response `index` values, when the
+        #   provider's wire format carries them (OpenAI). Ollama has no index field —
+        #   its response order is positional — so callers pass nil there and this
+        #   check is skipped.
+        # @raise [InvalidEmbeddingResponse] on any violation
+        # @return [void]
+        def validate!(vectors, expected_count:, provider:, indexes: nil)
+          fail_with = lambda do |msg|
+            raise InvalidEmbeddingResponse.new(msg, provider: provider, batch_size: expected_count)
+          end
+
+          unless vectors.size == expected_count
+            fail_with.call("expected #{expected_count} vector(s), got #{vectors.size}")
+          end
+
+          validate_indexes!(indexes, expected_count, fail_with) if indexes
+
+          validate_vector_shapes!(vectors, fail_with)
+        end
+
+        # @api private
+        def validate_indexes!(indexes, expected_count, fail_with)
+          if indexes.any? { |i| !i.is_a?(Integer) }
+            fail_with.call("response indexes must all be integers, got #{indexes.inspect}")
+          end
+          fail_with.call("response indexes are not unique: #{indexes.sort}") if indexes.uniq.size != indexes.size
+
+          expected_indexes = (0...expected_count).to_a
+          return if indexes.sort == expected_indexes
+
+          fail_with.call("response indexes #{indexes.sort} do not cover 0..#{expected_count - 1}")
+        end
+        private_class_method :validate_indexes!
+
+        # @api private
+        def validate_vector_shapes!(vectors, fail_with)
+          dimension = nil
+          vectors.each_with_index do |vector, i|
+            check_vector_shape!(vector, i, fail_with)
+            dimension ||= vector.size
+            next if vector.size == dimension
+
+            fail_with.call("vector at position #{i} has dimension #{vector.size}, expected #{dimension}")
+          end
+        end
+        private_class_method :validate_vector_shapes!
+
+        # @api private
+        def check_vector_shape!(vector, index, fail_with)
+          unless vector.is_a?(Array) && !vector.empty?
+            fail_with.call("vector at position #{index} is not a non-empty array (got #{vector.class})")
+          end
+          return if vector.all? { |n| n.is_a?(Numeric) && n.finite? }
+
+          fail_with.call("vector at position #{index} contains a non-finite or non-numeric value")
+        end
+        private_class_method :check_vector_shape!
+      end
+
       # Ollama adapter for local embeddings via the Ollama HTTP API.
       #
       # Uses the `/api/embed` endpoint to generate embeddings. Requires a running
@@ -72,6 +222,7 @@ module Woods
       #   vectors = provider.embed_batch(["text1", "text2"])
       class Ollama
         include Interface
+        include DiscardableClient
 
         DEFAULT_MODEL = 'nomic-embed-text'
         DEFAULT_HOST = 'http://localhost:11434'
@@ -118,13 +269,15 @@ module Woods
         #   context from `MODEL_CONTEXT_LENGTHS`, falling back to 2048 for
         #   unknown models. Set explicitly only if running a model with a
         #   known-larger native context that isn't in the registry yet.
+        # @param dimensions [Integer, nil] Requested output vector size.
         # @param read_timeout [Integer] HTTP read timeout in seconds.
         #   Bump this for slow / cold-start hosts or very large batches.
         def initialize(model: DEFAULT_MODEL, host: DEFAULT_HOST, num_ctx: nil,
-                       read_timeout: DEFAULT_READ_TIMEOUT)
+                       dimensions: nil, read_timeout: DEFAULT_READ_TIMEOUT)
           @model = model
           @host = host
           @num_ctx = num_ctx || MODEL_CONTEXT_LENGTHS.fetch(model, FALLBACK_NUM_CTX)
+          @dimensions = normalize_dimensions(dimensions)
           @read_timeout = read_timeout
           @uri = URI("#{host}/api/embed")
         end
@@ -139,7 +292,9 @@ module Woods
           raise ArgumentError, 'embed(text) requires a non-empty string' if text.nil? || text.to_s.strip.empty?
 
           response = post_request(build_body(text))
-          response['embeddings'].first
+          vectors = Array(response['embeddings'])
+          VectorValidation.validate!(vectors, expected_count: 1, provider: 'Ollama')
+          vectors.first
         end
 
         # Embed multiple texts in a single request.
@@ -155,7 +310,9 @@ module Woods
           end
 
           response = post_request(build_body(texts))
-          response['embeddings']
+          vectors = Array(response['embeddings'])
+          VectorValidation.validate!(vectors, expected_count: texts.size, provider: 'Ollama')
+          vectors
         end
 
         # Return the dimensionality of vectors produced by this model.
@@ -186,6 +343,15 @@ module Woods
 
         private
 
+        def normalize_dimensions(value)
+          return if value.nil?
+
+          dimensions = Integer(value)
+          raise ArgumentError, "dimensions must be positive, got #{value.inspect}" unless dimensions.positive?
+
+          dimensions
+        end
+
         # Cap interpolated response bodies so misconfigured Ollama responses
         # (e.g. proxied HTML error pages) don't unbounded-leak into logs or
         # re-raised error messages.
@@ -204,6 +370,7 @@ module Woods
         # tokens and returns 400 when the input exceeds that default.
         def build_body(input)
           body = { model: @model, input: input }
+          body[:dimensions] = @dimensions if @dimensions
           body[:options] = { num_ctx: @num_ctx } if @num_ctx
           body
         end
@@ -213,31 +380,42 @@ module Woods
         # @param body [Hash] request body
         # @return [Hash] parsed JSON response
         # @raise [Woods::Error] if the API returns a non-success status
-        def post_request(body) # rubocop:disable Metrics/AbcSize
+        def post_request(body)
           request = Net::HTTP::Post.new(@uri.path, 'Content-Type' => 'application/json')
           request.body = body.to_json
           response = http_client.request(request)
 
-          unless response.is_a?(Net::HTTPSuccess)
-            raise Woods::Error, "Ollama API error: #{response.code} #{truncate_response_body(response.body)}"
-          end
+          raise request_error(response) unless response.is_a?(Net::HTTPSuccess)
 
           JSON.parse(response.body)
         rescue Errno::ECONNRESET, Net::OpenTimeout, Net::ReadTimeout, IOError
           # Connection dropped — reset and retry once
-          @http_client = nil
+          discard_http_client
           begin
             response = http_client.request(request)
           rescue StandardError => retry_error
             raise Woods::Error, "Ollama API error (retry failed): #{retry_error.message}"
           end
-          unless response.is_a?(Net::HTTPSuccess)
-            raise Woods::Error, "Ollama API error: #{response.code} #{truncate_response_body(response.body)}"
-          end
+          raise request_error(response) unless response.is_a?(Net::HTTPSuccess)
 
           JSON.parse(response.body)
         end
 
+        # Build a {RequestError} from a non-success Ollama response,
+        # attaching the HTTP status and any +Retry-After+ header so the
+        # resilience layer can classify the failure and honor the
+        # server-requested back-off.
+        #
+        # @param response [Net::HTTPResponse]
+        # @return [RequestError]
+        def request_error(response)
+          RequestError.new(
+            "Ollama API error: #{response.code} #{truncate_response_body(response.body)}",
+            http_status: response.code.to_i,
+            retry_after: response['Retry-After']
+          )
+        end
+
         # Return a reusable, started HTTP client for the Ollama API.
         #
         # @return [Net::HTTP]

data/lib/woods/embedding/text_preparer.rb

@@ -6,7 +6,7 @@ module Woods
   module Embedding
     # Prepares ExtractedUnit data for embedding by building context-prefixed text.
     #
-    # Follows the context prefix format from docs/CONTEXT_AND_CHUNKING.md:
+    # Follows the context prefix format (see `git log --follow -- docs/design/CONTEXT_AND_CHUNKING.md`):
     #   [type] identifier
     #   namespace: ...
     #   file: ...

data/lib/woods/embedding/token_counter.rb

@@ -58,13 +58,6 @@ module Woods
         tok ? tok.encode(text).ids.length : estimate(text)
       end
 
-      # True when the real tokenizer is loaded and in use.
-      #
-      # @return [Boolean]
-      def exact?
-        !tokenizer.nil?
-      end
-
       private
 
       def estimate(text)

data/lib/woods/evaluation/ablation_agent_payload.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Woods
+  module Evaluation
+    # Parses the `claude -p --output-format json` shaped payload an ablation
+    # agent prints on stdout (#280).
+    module AblationAgentPayload
+      TOKEN_KEYS = %w[input_tokens output_tokens cache_creation_input_tokens cache_read_input_tokens].freeze
+
+      module_function
+
+      # The last line that parses as a JSON object wins, so a preamble on
+      # stdout does not hide the result.
+      #
+      # @param stdout [String]
+      # @return [Hash, nil]
+      def parse(stdout)
+        stdout.to_s.lines.reverse_each do |line|
+          parsed = JSON.parse(line)
+          return parsed if parsed.is_a?(Hash)
+        rescue JSON::ParserError
+          next
+        end
+        nil
+      end
+
+      # @param usage [Hash, nil]
+      # @return [Integer, nil]
+      def token_total(usage)
+        return nil unless usage.is_a?(Hash)
+
+        TOKEN_KEYS.sum { |key| usage[key].to_i }
+      end
+    end
+  end
+end

data/lib/woods/evaluation/ablation_executor.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module Woods
+  module Evaluation
+    # Default executor for {AblationRunner}: spawns a real subprocess and
+    # exposes the pid of the most recent spawn via {#pid} (#280 review), so
+    # {AblationTimedExecutor} can terminate it on timeout. `Open3.capture3`
+    # blocks synchronously and never surfaces a pid to the caller, which is
+    # exactly the gap that let a timed-out agent keep running in the
+    # background.
+    class AblationExecutor
+      # @return [Integer, nil] the pid of the most recently spawned process
+      attr_reader :pid
+
+      # @param command [String] a full shell command line
+      # @param chdir [String]
+      # @return [Array(String, String, Boolean)] stdout, stderr, success
+      def call(command, chdir:)
+        stdout_r, stdout_w = IO.pipe
+        stderr_r, stderr_w = IO.pipe
+        spawn_child(command, chdir, stdout_w, stderr_w)
+        stdout_w.close
+        stderr_w.close
+
+        # Read concurrently with the wait, not after it: a pipe holds only
+        # ~64KB on Linux before a write blocks, so a child that writes more
+        # than that to either stream, with nothing draining it, blocks
+        # forever, and Process.wait2 alone never touches either pipe. That
+        # made AblationTimedExecutor report a false timeout on a chatty
+        # agent instead of ever reaching a real result.
+        stdout_thread = reader_thread(stdout_r)
+        stderr_thread = reader_thread(stderr_r)
+        _reaped_pid, status = Process.wait2(@pid)
+        [stdout_thread.value, stderr_thread.value, status.success?]
+      ensure
+        stdout_r&.close
+        stderr_r&.close
+        stdout_w&.close unless stdout_w&.closed?
+        stderr_w&.close unless stderr_w&.closed?
+      end
+
+      private
+
+      # A timeout wrapping #call can interrupt it mid-read, closing the pipe
+      # out from under whichever reader thread is still blocked on it. That
+      # IOError is expected and the caller already discards this call's
+      # result, so it should not be reported as an unhandled thread
+      # exception.
+      def reader_thread(io)
+        Thread.new { io.read }.tap { |thread| thread.report_on_exception = false }
+      end
+
+      # `Thread.handle_interrupt` defers the async Timeout::Error
+      # AblationTimedExecutor's Timeout.timeout can raise into this thread,
+      # so it cannot land between Process.spawn returning and `@pid` being
+      # set (#280 review, minor): a pid lost that way could never be
+      # terminated on timeout.
+      def spawn_child(command, chdir, stdout_w, stderr_w)
+        Thread.handle_interrupt(Timeout::Error => :never) do
+          @pid = Process.spawn(command, chdir: chdir, in: File::NULL, out: stdout_w, err: stderr_w)
+        end
+      end
+    end
+  end
+end

data/lib/woods/evaluation/ablation_provenance.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Woods
+  module Evaluation
+    # Per-trial provenance (a binding ruling): the exact agent command run,
+    # the model the agent reported (when the JSON payload names one), the
+    # MCP wiring in effect, the Woods generation on disk in the checkout,
+    # and the baseline SHA the checkout came from (#280).
+    AblationProvenance = Struct.new(:agent_command, :model, :config, :woods_generation, :baseline_sha,
+                                    keyword_init: true) do
+      # @return [AblationProvenance]
+      def self.build(agent_command:, chdir:, baseline_sha:)
+        new(agent_command: agent_command, model: nil, config: mcp_config_of(agent_command),
+            woods_generation: woods_generation_at(chdir), baseline_sha: baseline_sha)
+      end
+
+      def self.mcp_config_of(command)
+        return 'strict' if command.include?('--strict-mcp-config')
+
+        match = command.match(/--mcp-config[= ](\S+)/)
+        match && match[1]
+      end
+
+      def self.woods_generation_at(chdir)
+        generation_file = File.join(chdir, 'tmp', 'woods', 'generation.json')
+        return nil unless File.exist?(generation_file)
+
+        JSON.parse(File.read(generation_file))['number']
+      rescue StandardError
+        nil
+      end
+
+      private_class_method :mcp_config_of, :woods_generation_at
+    end
+  end
+end

data/lib/woods/evaluation/ablation_report_writer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module Woods
+  module Evaluation
+    # Serializes an {AblationRunner::Report} to JSON and renders the terminal
+    # summary for `woods:evaluate:ablation` (#280).
+    class AblationReportWriter
+      # @param report [AblationRunner::Report]
+      def initialize(report)
+        @report = report
+      end
+
+      # @param path [String]
+      # @return [void]
+      def write(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        results = @report.results.map { |result| result.to_h.merge(provenance: result.provenance.to_h) }
+        File.write(path, JSON.pretty_generate('summary' => @report.summary, 'results' => results))
+      end
+
+      # @return [String] a human-readable summary, explicit that this is a
+      #   paired-run harness rather than a causal-evidence report
+      def summary_text
+        lines = ['', 'Ablation complete! This is a harness for paired runs, not causal evidence.', '=' * 50]
+        %i[on off delta].each { |condition| lines.concat(condition_lines(condition)) }
+        lines << ('=' * 50)
+        lines.join("\n")
+      end
+
+      private
+
+      def condition_lines(condition)
+        section = @report.summary[condition]
+        return [] unless section
+
+        ["  #{condition}:"] + section.map { |key, value| "    #{key.to_s.ljust(18)}: #{value.nil? ? 'n/a' : value}" }
+      end
+    end
+  end
+end