rail_verdict 1.2.0 → 1.4.0

data/lib/rail_verdict/cli.rb

@@ -29,6 +29,7 @@ module RailVerdict
         investigate      Investigate top findings with optional AI
         repair           Build a deterministic repair packet for a finding
         receipt          Create or verify a Verification Receipt
+        handoff          Create or verify a Verification Handoff (evidence reuse)
         mcp              MCP adapter (serve)
 
       Global options:
@@ -69,8 +70,10 @@ module RailVerdict
         command_investigate(argv.drop(1))
       when "repair"
         command_repair(argv.drop(1))
-      when "receipt"
+        when "receipt"
         command_receipt(argv.drop(1))
+      when "handoff"
+        command_handoff(argv.drop(1))
       when "mcp"
         command_mcp(argv.drop(1))
       else
@@ -130,15 +133,16 @@ module RailVerdict
     end
 
     def command_check(argv)
-      options = { config: DEFAULT_CONFIG_PATH, format: "console", changed: false, base: nil, baseline: nil, waiver: nil }
+      options = { config: DEFAULT_CONFIG_PATH, format: "console", changed: false, base: nil, baseline: nil, waiver: nil, handoff: nil }
       parser = OptionParser.new do |opts|
-        opts.banner = "Usage: railverdict check [--config PATH] [--format console|json|sarif] [--changed] [--base REV] [--baseline PATH] [--waiver PATH]"
+        opts.banner = "Usage: railverdict check [--config PATH] [--format console|json|sarif] [--changed] [--base REV] [--baseline PATH] [--waiver PATH] [--handoff PATH]"
         opts.on("--config PATH", String) { |value| options[:config] = value }
         opts.on("--format FORMAT", String) { |value| options[:format] = value }
         opts.on("--changed") { options[:changed] = true }
         opts.on("--base REV", String) { |value| options[:base] = value }
         opts.on("--baseline PATH", String) { |value| options[:baseline] = value }
         opts.on("--waiver PATH", String) { |value| options[:waiver] = value }
+        opts.on("--handoff PATH", String) { |value| options[:handoff] = value }
       end
       parse!(parser, argv)
       validate_format!(options[:format])
@@ -146,12 +150,145 @@ module RailVerdict
         raise RailVerdict::UsageError, "--base requires --changed"
       end
 
+      if options[:handoff]
+        return command_check_with_handoff(options)
+      end
+
       outcome, interrupted = execute_check(options)
       return EXIT_NO_GATE unless render_result(outcome.result, options[:format])
 
       exit_code_for(outcome.result, interrupted: interrupted)
     end
 
+    def command_check_with_handoff(options)
+      handoff_path = options[:handoff]
+      begin
+        text = File.binread(handoff_path)
+      rescue StandardError => e
+        @stderr.puts "railverdict check --handoff: cannot read handoff: #{e.message}"
+        return EXIT_NO_GATE
+      end
+      handoff_doc, err = Handoff.parse(text)
+      unless handoff_doc
+        @stderr.puts "railverdict check --handoff: handoff invalid (#{err}); running full verification"
+        outcome, interrupted = execute_check(options.reject { |k, _| k == :handoff })
+        return EXIT_NO_GATE unless render_result(outcome.result, options[:format])
+        return exit_code_for(outcome.result, interrupted: interrupted)
+      end
+
+      # Independent observation
+      effective_paths = Check.effective_input_paths(root: @working_directory, config_path: resolved_override_path(options[:config], File.join(@working_directory, DEFAULT_CONFIG_PATH)), baseline_path_override: options[:baseline] && resolved_override_path(options[:baseline], nil), waiver_path_override: options[:waiver] && resolved_override_path(options[:waiver], nil))
+      before_state = RepositoryState.capture(repository_root: @working_directory, configuration_paths: effective_paths)
+      current_state = before_state
+      current_env_obj = VerificationEnvironment.capture(repository_root: @working_directory)
+      current_env = {
+        "ruby_engine" => current_env_obj.ruby_engine,
+        "ruby_version" => current_env_obj.ruby_version,
+        "railverdict_version" => current_env_obj.railverdict_version,
+        "analyzer_versions" => current_env_obj.analyzer_versions
+      }
+      config = Configuration.load(effective_paths[:config]) rescue nil
+      required = config ? config.analyzers.select { |_, s| s["enabled"] && s["required"] }.keys.map(&:to_s) : []
+      contract = { "required_analyzers" => required, "verification_mode" => handoff_doc.dig("source_scope", "verification_mode"), "changed_base" => handoff_doc.dig("source_scope", "changed_base") }
+      reuse_result = Reuse.evaluate(handoff_document: handoff_doc, current_repository_state: current_state, current_environment: current_env, current_contract: contract)
+      after_state = RepositoryState.capture(repository_root: @working_directory, configuration_paths: effective_paths)
+      if before_state && after_state && before_state.digest != after_state.digest
+        reuse_result = Reuse::Result.new(decision: Reuse::VERIFICATION_REQUIRED, reasons: reuse_result.reasons + ["reuse_toctou"], handoff_valid: reuse_result.handoff_valid, receipt_fresh: reuse_result.receipt_fresh)
+      end
+
+      if reuse_result.decision == Reuse::REUSABLE
+        # Whole-set reuse: re-derive GateResult from reused normalized evidence through current baseline/waivers/policy.
+        # This satisfies invariants 6-9: old GateResult never becomes second authority.
+        begin
+          # Reconstruct findings as observed (state observed) for reclassification
+          reused_finding_hashes = handoff_doc.dig("evidence_set", "analyzer_results")&.flat_map { |ar| ar["findings"] || [] } || []
+          reused_findings = reused_finding_hashes.map do |fh|
+            # fh is a Finding schema hash; convert to observed Finding
+            begin
+              Finding.new(
+                fingerprint: fh["fingerprint"],
+                origin: fh["origin"] || "deterministic",
+                analyzer: fh["analyzer"],
+                rule_id: fh["rule_id"],
+                category: fh["category"] || "lint",
+                severity: fh["severity"] || "medium",
+                confidence: fh["confidence"] || "high",
+                state: "observed",
+                evidence_ref: fh["evidence_ref"] || "native:#{fh['analyzer']}:#{fh['fingerprint'][0,8]}",
+                location: fh["location"] || { "path" => fh["path"] || "unknown.rb" },
+                message: fh["message"] || "reused"
+              )
+            rescue StandardError
+              nil
+            end
+          end.compact
+
+          # Reconstruct analyzer_results for policy (finding_ids derived from findings)
+          handoff_ars = handoff_doc.dig("evidence_set", "analyzer_results") || []
+          reused_analyzer_results = handoff_ars.map do |ar|
+            fid_map = reused_findings.select { |f| f.analyzer == ar["analyzer"] }.map(&:id)
+            # Also include fingerprint mapping for policy compatibility (GateResult uses finding_ids)
+            # Use fingerprint-based ids as in original
+            AnalyzerResult.new(
+              analyzer: ar["analyzer"],
+              invocation: { "executable" => ar["analyzer"], "argv" => [] },
+              execution_status: ar["execution_status"] == "succeeded" ? "succeeded" : "succeeded",
+              finding_ids: fid_map,
+              tool_version: ar["tool_version"]
+            )
+          rescue StandardError
+            nil
+          end.compact
+
+          # Load current baseline/waivers (respect effective paths)
+          cfg = Configuration.load(effective_paths[:config]) rescue nil
+          baseline_path = effective_paths[:baseline]
+          waiver_path = effective_paths[:waivers]
+          baseline = File.file?(baseline_path) ? (Baseline.read(baseline_path) rescue nil) : nil
+          waivers = WaiverStore.read_optional(waiver_path) rescue []
+          # Comparison
+          comparison = nil
+          classified = reused_findings
+          if baseline || waivers.any?
+            cmp = Comparison.classify(findings: reused_findings, baseline: baseline, waivers: waivers.map(&:to_h), clock: Time.now.utc)
+            comparison = { "counts" => cmp.counts, "introduced" => cmp.introduced.map(&:fingerprint).sort, "existing" => cmp.existing.map(&:fingerprint).sort, "resolved" => cmp.resolved.map { |e| e.fetch("fingerprint") }.sort, "changed" => cmp.changed.map(&:fingerprint).sort, "moved" => cmp.moved.map(&:fingerprint).sort, "waived" => cmp.counts.fetch("waived", 0) == 0 ? [] : cmp.classified_findings.select { |it| it.state == "waived" }.map(&:fingerprint).sort, "orphaned_waivers" => cmp.orphaned_waivers.map { |w| w["fingerprint"] || w[:fingerprint] }.compact.sort }
+            classified = cmp.classified_findings
+          end
+
+          # Policy evaluation with current config
+          policy_result = Verification::Policy.evaluate(configuration: cfg, analyzer_results: reused_analyzer_results, findings: classified, comparison: comparison, baseline_meta: baseline ? { "loaded" => true, "path" => baseline_path } : nil, git_context: nil)
+          # Build final GateResult (reuse policy_result but attach handoff metadata)
+          gate_result = policy_result
+          # Render with handoff_reuse envelope for machine output
+          if options[:format] == "json"
+            payload = gate_result.to_schema_h
+            payload["handoff_reuse"] = { "decision" => Reuse::REUSABLE, "reasons" => reuse_result.reasons, "handoff_id" => handoff_doc["handoff_id"], "receipt_id" => handoff_doc.dig("receipt", "receipt_id"), "receipt_fresh" => true }
+            @stdout.write(JSON.generate(payload) + "\n")
+          else
+            @stdout.puts "Handoff REUSABLE: #{handoff_doc['handoff_id']} (receipt #{handoff_doc.dig('receipt','receipt_id')})"
+            @stdout.puts "Gate: #{gate_result.gate} (reused evidence, policy re-evaluated, no analyzer execution)"
+          end
+          return gate_result.gate == "FAIL" ? EXIT_POLICY_FAIL : EXIT_OK
+        rescue StandardError => e
+          @stderr.puts "handoff reuse re-evaluation failed (#{e.class}: #{e.message}); falling back to full verification"
+          outcome, interrupted = execute_check(options.reject { |k, _| k == :handoff })
+          return EXIT_NO_GATE unless render_result(outcome.result, options[:format])
+          return exit_code_for(outcome.result, interrupted: interrupted)
+        end
+      else
+        @stderr.puts "Handoff #{reuse_result.decision}: #{reuse_result.reasons.join(', ')}; running full verification" if options[:format] != "json"
+        # Fallback to full verification
+        outcome, interrupted = execute_check(options.reject { |k, _| k == :handoff })
+        # Annotate result with reuse info when json
+        if options[:format] == "json" && outcome.result.respond_to?(:to_schema_h)
+          # We cannot mutate GateResult; we just render normally but also log reuse decision to stderr
+          @stderr.puts JSON.generate({ "handoff_reuse" => { "decision" => reuse_result.decision, "reasons" => reuse_result.reasons } })
+        end
+        return EXIT_NO_GATE unless render_result(outcome.result, options[:format])
+        return exit_code_for(outcome.result, interrupted: interrupted)
+      end
+    end
+
     def command_pr(argv)
       options = { config: DEFAULT_CONFIG_PATH, format: "console", base: nil, baseline: nil, waiver: nil }
       parser = OptionParser.new do |opts|
@@ -654,23 +791,24 @@ module RailVerdict
         return EXIT_NO_GATE
       end
 
+      effective_paths = begin
+        effective = Check.effective_input_paths(
+          root: @working_directory,
+          config_path: resolved_override_path(options[:config], File.join(@working_directory, DEFAULT_CONFIG_PATH)),
+          baseline_path_override: options[:baseline] && resolved_override_path(options[:baseline], nil),
+          waiver_path_override: options[:waiver] && resolved_override_path(options[:waiver], nil)
+        )
+        {
+          config: effective.fetch(:config),
+          baseline: effective.fetch(:baseline),
+          waivers: effective.fetch(:waivers)
+        }
+      end
       current_state = RepositoryState.capture(
         repository_root: @working_directory,
-        configuration_paths: begin
-          effective = Check.effective_input_paths(
-            root: @working_directory,
-            config_path: resolved_override_path(options[:config], File.join(@working_directory, DEFAULT_CONFIG_PATH)),
-            baseline_path_override: options[:baseline] && resolved_override_path(options[:baseline], nil),
-            waiver_path_override: options[:waiver] && resolved_override_path(options[:waiver], nil)
-          )
-          {
-            config: effective.fetch(:config),
-            baseline: effective.fetch(:baseline),
-            waivers: effective.fetch(:waivers)
-          }
-        end
+        configuration_paths: effective_paths
       )
-      document, _receipt = Receipt.evaluate(text, current_state: current_state)
+      document, _receipt = Receipt.evaluate(text, current_state: current_state, repository_root: @working_directory, configuration_paths: effective_paths)
       render_receipt_validation(document, options[:format])
       exit_code_for_validation(document)
     rescue RailVerdict::UsageError => error
@@ -710,6 +848,216 @@ module RailVerdict
       end
     end
 
+    def command_handoff(argv)
+      sub = argv.first
+      raise RailVerdict::UsageError, "handoff requires a subcommand: create, inspect, or verify" unless %w[create inspect verify].include?(sub)
+
+      case sub
+      when "create" then command_handoff_create(argv.drop(1))
+      when "inspect" then command_handoff_inspect(argv.drop(1))
+      when "verify" then command_handoff_verify(argv.drop(1))
+      end
+    rescue RailVerdict::UsageError => e
+      @stderr.puts "railverdict handoff: #{e.message}"
+      @stderr.puts handoff_usage
+      EXIT_NO_GATE
+    end
+
+    def handoff_usage
+      <<~USAGE
+        Usage: railverdict handoff create [options]
+               railverdict handoff inspect PATH [options]
+               railverdict handoff verify PATH [options]
+
+        Create options:
+          --config PATH, --format console|json, --output PATH
+          --changed --base REV --baseline PATH --waiver PATH
+
+        Inspect options:
+          --format console|json
+
+        Verify options:
+          --format console|json
+          --config PATH, --baseline PATH, --waiver PATH
+      USAGE
+    end
+
+    def command_handoff_create(argv)
+      options = { config: DEFAULT_CONFIG_PATH, format: "json", output: nil, changed: false, base: nil, baseline: nil, waiver: nil }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict handoff create [--config PATH] [--format console|json] [--output PATH] [--changed] [--base REV] [--baseline PATH] [--waiver PATH]"
+        opts.on("--config PATH", String) { |v| options[:config] = v }
+        opts.on("--format FORMAT", String) { |v| options[:format] = v }
+        opts.on("--output PATH", String) { |v| options[:output] = v }
+        opts.on("--changed") { options[:changed] = true }
+        opts.on("--base REV", String) { |v| options[:base] = v }
+        opts.on("--baseline PATH", String) { |v| options[:baseline] = v }
+        opts.on("--waiver PATH", String) { |v| options[:waiver] = v }
+      end
+      parse!(parser, argv)
+      raise RailVerdict::UsageError, "--base requires --changed" if options[:base] && !options[:changed]
+      unless %w[console json].include?(options[:format])
+        raise RailVerdict::UsageError, "invalid --format #{options[:format].inspect}; expected console or json"
+      end
+      options[:config] = resolved_override_path(options[:config], File.join(@working_directory, DEFAULT_CONFIG_PATH))
+      options[:baseline] = resolved_override_path(options[:baseline], nil) if options[:baseline]
+      options[:waiver] = resolved_override_path(options[:waiver], nil) if options[:waiver]
+
+      outcome, interrupted = execute_check_with_guard(options)
+      return EXIT_INTERRUPTED if interrupted || outcome.result.completion_status == "interrupted"
+
+      receipt = Receipt.build(outcome: outcome, pr_intelligence_document: pr_intelligence_document_for(outcome))
+      evidence_set = {
+        "analyzer_results" => outcome.result.analyzer_results.map do |ar|
+          h = { "analyzer" => ar.analyzer, "execution_status" => ar.execution_status, "tool_version" => ar.tool_version }
+          # Include normalized findings for reuse (bounded) — use canonical Finding hashes
+          findings = outcome.findings.select { |f| f.analyzer == ar.analyzer }.map(&:to_schema_h).sort_by { |ff| ff["fingerprint"] }
+          h["findings"] = findings if findings.any?
+          h
+        end
+      }
+      provenance = { "analyzer_versions" => outcome.context&.analyzer_versions || {} }
+      scope = {
+        "verification_mode" => outcome.result.git ? "changed" : "full",
+        "changed_base" => outcome.result.git && outcome.result.git["base"],
+        "changed_merge_base" => outcome.result.git && outcome.result.git["merge_base"]
+      }
+      handoff = Handoff.build(receipt: receipt, evidence_set: evidence_set, evidence_provenance: provenance, source_scope: scope)
+      write_handoff_file(handoff, options[:output]) if options[:output]
+      render_handoff(handoff, options[:format], output_path: options[:output])
+      exit_code_for(outcome.result, interrupted: interrupted)
+    rescue Handoff::BuildError, Receipt::BuildError => e
+      payload = { "status" => "unavailable", "reasons" => ["#{e.code}: #{e.message}"] }
+      render_handoff_unavailable(payload, options && options[:format])
+      EXIT_NO_GATE
+    end
+
+    def command_handoff_inspect(argv)
+      options = { format: "json" }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict handoff inspect PATH [--format console|json]"
+        opts.on("--format FORMAT", String) { |v| options[:format] = v }
+      end
+      rest = begin parser.parse(argv.dup) rescue raise RailVerdict::UsageError, $!.message end
+      path = rest.first
+      raise RailVerdict::UsageError, "inspect requires the handoff file path" if path.nil?
+      unless %w[console json].include?(options[:format])
+        raise RailVerdict::UsageError, "invalid --format #{options[:format].inspect}"
+      end
+      text = begin File.binread(path) rescue (@stderr.puts "railverdict handoff inspect: cannot read handoff: #{$!.message}"; return EXIT_NO_GATE) end
+      doc, err = Handoff.parse(text)
+      if doc
+        render_handoff(doc, options[:format])
+        EXIT_OK
+      else
+        payload = { "status" => "invalid", "reasons" => [err.to_s] }
+        render_handoff_unavailable(payload, options[:format])
+        EXIT_NO_GATE
+      end
+    end
+
+    def command_handoff_verify(argv)
+      options = { format: "json", config: DEFAULT_CONFIG_PATH, baseline: nil, waiver: nil }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict handoff verify PATH [--format console|json] [--config PATH] [--baseline PATH] [--waiver PATH]"
+        opts.on("--format FORMAT", String) { |v| options[:format] = v }
+        opts.on("--config PATH", String) { |v| options[:config] = v }
+        opts.on("--baseline PATH", String) { |v| options[:baseline] = v }
+        opts.on("--waiver PATH", String) { |v| options[:waiver] = v }
+      end
+      rest = begin parser.parse(argv.dup) rescue raise RailVerdict::UsageError, $!.message end
+      path = rest.first
+      raise RailVerdict::UsageError, "verify requires the handoff file path" if path.nil?
+      unless %w[console json].include?(options[:format])
+        raise RailVerdict::UsageError, "invalid --format #{options[:format].inspect}"
+      end
+      text = begin File.binread(path) rescue (@stderr.puts "railverdict handoff verify: cannot read handoff: #{$!.message}"; return EXIT_NO_GATE) end
+      doc, err = Handoff.parse(text)
+      unless doc
+        payload = { "handoff_valid" => false, "receipt_fresh" => false, "decision" => Reuse::INVALID, "reasons" => [err.to_s] }
+        render_handoff_verify(payload, options[:format])
+        return EXIT_NO_GATE
+      end
+      effective_paths = Check.effective_input_paths(root: @working_directory, config_path: resolved_override_path(options[:config], File.join(@working_directory, DEFAULT_CONFIG_PATH)), baseline_path_override: options[:baseline] && resolved_override_path(options[:baseline], nil), waiver_path_override: options[:waiver] && resolved_override_path(options[:waiver], nil))
+      before_state = RepositoryState.capture(repository_root: @working_directory, configuration_paths: effective_paths)
+      current_state = before_state
+      current_env_obj = VerificationEnvironment.capture(repository_root: @working_directory)
+      current_env = {
+        "ruby_engine" => current_env_obj.ruby_engine,
+        "ruby_version" => current_env_obj.ruby_version,
+        "railverdict_version" => current_env_obj.railverdict_version,
+        "analyzer_versions" => current_env_obj.analyzer_versions
+      }
+      # Evaluate via canonical Reuse
+      config = Configuration.load(effective_paths[:config]) rescue nil
+      required = config ? config.analyzers.select { |_, s| s["enabled"] && s["required"] }.keys.map(&:to_s) : []
+      contract = { "required_analyzers" => required, "verification_mode" => doc.dig("source_scope", "verification_mode"), "changed_base" => doc.dig("source_scope", "changed_base") }
+      result = Reuse.evaluate(handoff_document: doc, current_repository_state: current_state, current_environment: current_env, current_contract: contract)
+      # TOCTOU guard: re-observe repository state
+      after_state = RepositoryState.capture(repository_root: @working_directory, configuration_paths: effective_paths)
+      if before_state && after_state && before_state.digest != after_state.digest
+        result = Reuse::Result.new(decision: Reuse::VERIFICATION_REQUIRED, reasons: result.reasons + ["reuse_toctou"], handoff_valid: result.handoff_valid, receipt_fresh: result.receipt_fresh)
+      end
+      payload = { "handoff_valid" => result.handoff_valid, "receipt_fresh" => result.receipt_fresh, "decision" => result.decision, "reasons" => result.reasons, "handoff_id" => doc["handoff_id"], "receipt_id" => doc.dig("receipt", "receipt_id") }
+      render_handoff_verify(payload, options[:format])
+      result.decision == Reuse::REUSABLE ? EXIT_OK : EXIT_NO_GATE
+    end
+
+    def capture_current_env
+      # Minimal env capture for reuse freshness — reuse VerificationEnvironment where possible
+      begin
+        VerificationEnvironment.capture(repository_root: @working_directory)
+      rescue StandardError
+        { "ruby_engine" => RUBY_ENGINE, "ruby_version" => RUBY_VERSION, "railverdict_version" => RailVerdict::VERSION, "analyzer_versions" => {} }
+      end
+    end
+
+    def write_handoff_file(document, path)
+      dir = File.dirname(File.expand_path(path))
+      FileUtils.mkdir_p(dir)
+      tmp = File.join(dir, ".#{File.basename(path)}.tmp.#{Process.pid}.#{SecureRandom.hex(8)}")
+      begin
+        File.open(tmp, "wb", 0o600) do |file|
+          file.write(JSON.generate(document) + "\n")
+          file.flush
+          file.fsync
+        end
+        File.rename(tmp, path)
+      ensure
+        File.unlink(tmp) if File.exist?(tmp)
+      end
+    end
+
+    def render_handoff(document, format, output_path: nil)
+      if format == "json"
+        @stdout.write(JSON.generate(document) + "\n")
+      else
+        @stdout.puts "Handoff: #{document['handoff_id']}"
+        @stdout.puts "Receipt: #{document.dig('receipt', 'receipt_id')}"
+        @stdout.puts "Evidence analyzers: #{Array(document.dig('evidence_set', 'analyzer_results')).map { |ar| ar['analyzer'] }.join(', ')}"
+        @stdout.puts "Written to #{output_path}" if output_path
+      end
+    end
+
+    def render_handoff_unavailable(payload, format)
+      if format == "json"
+        @stdout.write(JSON.generate(payload) + "\n")
+      else
+        @stdout.puts "Handoff unavailable: #{payload['reasons'].join('; ')}"
+      end
+    end
+
+    def render_handoff_verify(payload, format)
+      if format == "json"
+        @stdout.write(JSON.generate(payload) + "\n")
+      else
+        @stdout.puts "Handoff: #{payload['handoff_id']} valid=#{payload['handoff_valid']}"
+        @stdout.puts "Receipt fresh: #{payload['receipt_fresh']}"
+        @stdout.puts "Decision: #{payload['decision']}"
+        @stdout.puts "Reasons: #{payload['reasons'].join(', ')}" unless payload["reasons"].empty?
+      end
+    end
+
     def command_mcp(argv)
       sub = argv.first
       raise RailVerdict::UsageError, "mcp requires subcommand: serve" unless sub == "serve"

data/lib/rail_verdict/doctor.rb

@@ -19,7 +19,8 @@ module RailVerdict
         adapter = build_adapter(name, rubocop_command_resolver)
         next unless adapter
 
-        probes[name] = adapter.probe(root, runner: runner, timeout_seconds: configuration.analyzer_timeout_seconds(name))
+        probe_timeout = [[(configuration.analyzer_timeout_seconds(name) || 5.0).to_f, 5.0].min, 1.0].max
+        probes[name] = adapter.probe(root, runner: runner, timeout_seconds: probe_timeout)
       end
       analyzer_versions = probes.transform_values(&:version)
       context = RunContext.build(

data/lib/rail_verdict/handoff.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+require_relative "canonical_json"
+require_relative "schema_validator"
+
+module RailVerdict
+  class Handoff
+    SCHEMA_VERSION = "1.0"
+    ID_PATTERN = /\Asha256:[0-9a-f]{64}\z/
+    MAX_DOCUMENT_BYTES = 256 * 1024
+
+    class BuildError < RailVerdict::Error
+      attr_reader :code
+      def initialize(code, message)
+        @code = code.to_s
+        super(message)
+      end
+    end
+
+    attr_reader :document
+
+    def self.build(receipt:, evidence_set:, railverdict_version: RailVerdict::VERSION, evidence_provenance: nil, source_scope: nil)
+      raise BuildError.new(:handoff_unavailable, "receipt is required") if receipt.nil? || !receipt.is_a?(Hash)
+      raise BuildError.new(:handoff_unavailable, "evidence_set is required") if evidence_set.nil? || !evidence_set.is_a?(Hash)
+
+      # Validate receipt structurally (reuse Receipt validation without re-persisting)
+      errors = SchemaValidator.validate_receipt(receipt)
+      raise BuildError.new(:receipt_schema_invalid, errors.join("; ")) unless errors.empty?
+
+      payload = {
+        "schema_version" => SCHEMA_VERSION,
+        "railverdict_version" => railverdict_version.to_s,
+        "receipt" => receipt,
+        "evidence_set" => normalize_evidence_set(evidence_set)
+      }
+      payload["evidence_provenance"] = normalize_provenance(evidence_provenance) if evidence_provenance
+      payload["source_scope"] = normalize_scope(source_scope) if source_scope
+
+      document = payload.merge("handoff_id" => id_for(payload))
+      errors = SchemaValidator.validate_handoff(document)
+      raise BuildError.new(:handoff_schema_violation, errors.join("; ")) unless errors.empty?
+      raise BuildError.new(:handoff_too_large, "handoff exceeds #{MAX_DOCUMENT_BYTES} bytes") if JSON.generate(document).bytesize > MAX_DOCUMENT_BYTES
+
+      deep_freeze(document)
+    end
+
+    def self.id_for(payload)
+      "sha256:#{Digest::SHA256.hexdigest(CanonicalJSON.generate(payload))}"
+    end
+
+    def self.normalize_evidence_set(set)
+      # Ensure deterministic ordering: sorted by analyzer, findings sorted by fingerprint
+      results = Array(set["analyzer_results"] || set[:analyzer_results]).map do |ar|
+        h = {
+          "analyzer" => ar["analyzer"] || ar[:analyzer],
+          "execution_status" => ar["execution_status"] || ar[:execution_status]
+        }
+        tv = ar["tool_version"] || ar[:tool_version]
+        h["tool_version"] = tv.nil? ? nil : tv.to_s
+        findings = Array(ar["findings"] || ar[:findings]).map { |f| f.is_a?(Hash) ? f : {} }.sort_by { |f| f["fingerprint"] || "" }
+        h["findings"] = findings if findings.any?
+        h
+      end.sort_by { |ar| ar["analyzer"] }
+      { "analyzer_results" => results }
+    end
+    private_class_method :normalize_evidence_set
+
+    def self.normalize_provenance(prov)
+      return nil unless prov.is_a?(Hash)
+      out = {}
+      av = prov["analyzer_versions"] || prov[:analyzer_versions]
+      out["analyzer_versions"] = av.sort.to_h if av.is_a?(Hash) && av.any?
+      db = prov["advisory_db_revision"] || prov[:advisory_db_revision]
+      out["advisory_db_revision"] = db.to_s if db
+      out
+    end
+    private_class_method :normalize_provenance
+
+    def self.normalize_scope(scope)
+      return nil unless scope.is_a?(Hash)
+      out = {}
+      vm = scope["verification_mode"] || scope[:verification_mode]
+      out["verification_mode"] = vm.to_s if vm
+      cb = scope["changed_base"] || scope[:changed_base]
+      out["changed_base"] = cb.to_s if cb
+      mb = scope["changed_merge_base"] || scope[:changed_merge_base]
+      out["changed_merge_base"] = mb.to_s if mb
+      out
+    end
+    private_class_method :normalize_scope
+
+    def self.deep_freeze(value)
+      case value
+      when Hash then value.each { |k, v| k.freeze if k.is_a?(String); deep_freeze(v) }; value.freeze
+      when Array then value.each { |c| deep_freeze(c) }; value.freeze
+      when String then value.freeze
+      else value
+      end
+    end
+
+    def self.parse(text)
+      return [nil, :handoff_too_large] if text.bytesize > MAX_DOCUMENT_BYTES
+      document = begin JSON.parse(text) rescue return [nil, :handoff_malformed] end
+      parse_document(document)
+    end
+
+    def self.parse_document(document)
+      return [nil, :handoff_malformed] unless document.is_a?(Hash)
+      return [nil, :incompatible_handoff_version] unless document["schema_version"] == SCHEMA_VERSION
+      errors = SchemaValidator.validate_handoff(document)
+      return [nil, :handoff_schema_invalid] unless errors.empty?
+      stored = document["handoff_id"]
+      payload = document.reject { |k, _| k == "handoff_id" }
+      expected = id_for(payload)
+      return [nil, :handoff_integrity_failed] unless stored == expected
+      [deep_freeze(document), nil]
+    end
+  end
+end