rail_verdict 1.2.0 → 1.4.0

data/lib/rail_verdict/mcp/cache.rb

@@ -6,6 +6,7 @@ require "json"
 
 require_relative "../canonical_json"
 require_relative "../repository_state"
+require_relative "../verification_environment"
 
 module RailVerdict
   module MCP
@@ -39,23 +40,32 @@ module RailVerdict
         nil
       end
 
-      # Returns the cached entry only when the CURRENT observable state still
-      # matches the state that was verified. Never reruns analyzers.
-      def fresh_entry(current_state)
+      # Returns the cached entry only when the CURRENT observable identity
+      # (repository + environment) still matches what was verified. Never reruns analyzers,
+      # but does perform lightweight version probes for environment observation.
+      def fresh_entry(current_state, current_environment = nil)
         entry = @mutex.synchronize { @entry }
         return nil if entry.nil? || entry.state_digest.nil?
         return nil if current_state.nil? || !current_state.available?
         return nil if current_state.digest != entry.state_digest
 
+        current_env = current_environment || current_environment_for(entry.outcome)
+        return nil if current_env.nil? || !current_env.available?
+        return nil if current_env.digest != entry.environment_digest
+
         entry
       end
 
-      def verification_state(current_state)
+      def verification_state(current_state, current_environment = nil)
         entry = @mutex.synchronize { @entry }
         return "verification_required" if entry.nil? || entry.state_digest.nil?
         return "state_unavailable" if current_state.nil? || !current_state.available?
         return "stale" if current_state.digest != entry.state_digest
 
+        current_env = current_environment || current_environment_for(entry.outcome)
+        return "state_unavailable" if current_env.nil? || !current_env.available?
+        return "stale" if current_env.digest != entry.environment_digest
+
         "fresh"
       end
 
@@ -78,8 +88,11 @@ module RailVerdict
         current = current_state_for(entry.outcome)
         return false if current.nil? || !current.available?
 
+        current_env = current_environment_for(entry.outcome)
+        return false if current_env.nil? || !current_env.available?
+
         current.digest == entry.state_digest &&
-          environment_digest_for(entry.outcome) == entry.environment_digest
+          current_env.digest == entry.environment_digest
       rescue StandardError
         false
       end
@@ -102,6 +115,16 @@ module RailVerdict
         @mutex.synchronize { @last_packets[packet_id] }
       end
 
+      def store_handoff(handoff)
+        @mutex.synchronize do
+          @last_handoff = handoff
+        end
+      end
+
+      def fetch_handoff
+        @mutex.synchronize { @last_handoff }
+      end
+
       private
 
       def state_digest_for(outcome)
@@ -143,10 +166,31 @@ module RailVerdict
         }
       end
 
+      def current_environment_for(outcome)
+        root = outcome&.context&.repository_root
+        root ||= outcome&.result&.git&.fetch("repository_root", nil) rescue nil
+        return nil unless root.is_a?(String) && File.directory?(root)
+
+        real = begin
+          File.realpath(root)
+        rescue StandardError
+          return nil
+        end
+        config = outcome&.configuration
+        VerificationEnvironment.capture(repository_root: real, configuration: config)
+      rescue StandardError
+        nil
+      end
+
       def environment_digest_for(outcome)
+        env = current_environment_for(outcome)
+        return env.digest if env&.available? && env.digest
+
+        # Fallback for cases where current capture fails (e.g., no config)
         payload = {
           "railverdict_version" => RailVerdict::VERSION,
-          "ruby_version" => RUBY_VERSION,
+          "ruby_engine" => RUBY_ENGINE.to_s,
+          "ruby_version" => RUBY_VERSION.to_s,
           "analyzer_versions" => sorted_analyzer_versions(outcome)
         }
         Digest::SHA256.hexdigest(CanonicalJSON.generate(payload))

data/lib/rail_verdict/mcp/server.rb

@@ -70,6 +70,9 @@ module RailVerdict
         require_relative "tools/investigate"
         require_relative "tools/get_verification_receipt"
         require_relative "tools/get_pr_intelligence"
+        require_relative "tools/create_handoff"
+        require_relative "tools/inspect_handoff"
+        require_relative "tools/verify_handoff"
 
         [
           Tools::Verify,
@@ -80,7 +83,10 @@ module RailVerdict
           Tools::Explain,
           Tools::Investigate,
           Tools::GetVerificationReceipt,
-          Tools::GetPRIntelligence
+          Tools::GetPRIntelligence,
+          Tools::CreateHandoff,
+          Tools::InspectHandoff,
+          Tools::VerifyHandoff
         ].each do |tool_class|
           instance = tool_class.new(server: self)
           mcp_server.define_tool(

data/lib/rail_verdict/mcp/tools/create_handoff.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module MCP
+    module Tools
+      class CreateHandoff
+        def initialize(server:)
+          @server = server
+        end
+
+        def tool_name
+          "create_handoff"
+        end
+
+        def tool_title
+          "Create verification handoff"
+        end
+
+        def tool_description
+          "Create a deterministic Verification Handoff (bounded transport envelope) from a fresh verification. Runs verification, builds receipt and handoff. Offline, file/process usable, fail-closed. Handoff never self-authorizes reuse."
+        end
+
+        def tool_input_schema
+          {
+            type: "object",
+            properties: {
+              changed: { type: "boolean" },
+              base: { type: "string" },
+              config_path: { type: "string" },
+              baseline_path: { type: "string" },
+              waiver_path: { type: "string" }
+            },
+            additionalProperties: false
+          }
+        end
+
+        def tool_output_schema
+          {
+            type: "object",
+            properties: {
+              handoff: { type: "object" },
+              receipt: { type: "object" },
+              handoff_id: { type: "string" }
+            },
+            required: %w[handoff]
+          }
+        end
+
+        def tool_annotations
+          { read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false, title: tool_title }
+        end
+
+        def call(changed: nil, base: nil, config_path: nil, baseline_path: nil, waiver_path: nil, **_rest)
+          changed = changed == true
+          base_validated = Validators.validate_base_revision(base)
+          return Serializers.error_response("--base requires --changed", code: "invalid_arguments") if base_validated && !changed
+
+          config_file = resolve_config_path(config_path)
+          outcome = @server.synchronized_verification { run_check(changed: changed, base: base_validated, config_path: config_file, baseline_path: baseline_path, waiver_path: waiver_path) }
+          receipt = Receipt.build(outcome: 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 }
+              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)
+          @server.cache.store_handoff(handoff) if @server.cache.respond_to?(:store_handoff)
+          Serializers.tool_response({ "handoff" => Serializers.scrub(handoff), "receipt" => Serializers.scrub(receipt), "handoff_id" => handoff["handoff_id"] }, error: false)
+        rescue Handoff::BuildError, Receipt::BuildError => e
+          Serializers.error_response("#{e.code}: #{e.message}", code: e.code)
+        rescue ArgumentError => e
+          Serializers.error_response(e.message, code: "invalid_arguments")
+        rescue StandardError => e
+          Serializers.error_response("create_handoff failed: #{e.message}", code: "internal_error")
+        end
+
+        private
+
+        def run_check(changed:, base:, config_path:, baseline_path:, waiver_path:)
+          root = @server.repository_root
+          opts = { repository_root: root, config_path: config_path }
+          opts[:changed] = true if changed
+          opts[:base] = base if base
+          baseline_resolved = resolve_contained_path(baseline_path, "baseline_path") if baseline_path && !baseline_path.to_s.strip.empty?
+          waiver_resolved = resolve_contained_path(waiver_path, "waiver_path") if waiver_path && !waiver_path.to_s.strip.empty?
+          opts[:baseline_path_override] = baseline_resolved if baseline_resolved
+          opts[:waiver_path_override] = waiver_resolved if waiver_resolved
+          Check.execute_with_state_guard(**opts)
+        end
+
+        def resolve_contained_path(raw_path, field_name)
+          raw = raw_path.to_s.strip
+          raise ArgumentError, "#{field_name} contains NUL byte" if raw.include?("\u0000")
+          expanded = File.expand_path(raw, @server.repository_root)
+          raise ArgumentError, "#{field_name} escapes repository root" unless RepositoryRoot.contained?(@server.repository_root, expanded)
+          expanded
+        end
+
+        def resolve_config_path(config_path)
+          return File.join(@server.repository_root, ".railverdict.yml") if config_path.nil? || config_path.to_s.strip.empty?
+          raw = config_path.to_s.strip
+          raise ArgumentError, "config_path contains NUL byte" if raw.include?("\u0000")
+          expanded = File.expand_path(raw, @server.repository_root)
+          raise ArgumentError, "config_path escapes repository root" unless RepositoryRoot.contained?(@server.repository_root, expanded)
+          expanded
+        end
+      end
+    end
+  end
+end

data/lib/rail_verdict/mcp/tools/get_pr_intelligence.rb

@@ -48,10 +48,23 @@ module RailVerdict
         end
 
         def call(**_rest)
-          current_state = RailVerdict::RepositoryState.capture(repository_root: @server.repository_root)
-          case @server.cache.verification_state(current_state)
+          root = @server.repository_root
+          effective_paths = begin
+            RailVerdict::Check.effective_input_paths(root: File.realpath(root), config_path: File.join(File.realpath(root), ".railverdict.yml"))
+          rescue StandardError
+            nil
+          end
+          current_state = RailVerdict::RepositoryState.capture(repository_root: root, configuration_paths: effective_paths)
+          current_env = begin
+            outcome = @server.cache.fetch_outcome
+            config = outcome&.configuration
+            RailVerdict::VerificationEnvironment.capture(repository_root: root, configuration: config)
+          rescue StandardError
+            nil
+          end
+          case @server.cache.verification_state(current_state, current_env)
           when "fresh"
-            entry = @server.cache.fresh_entry(current_state)
+            entry = @server.cache.fresh_entry(current_state, current_env)
             document = entry&.pr_intelligence_document
             if document.is_a?(Hash)
               payload = { "status" => "fresh", "pr_intelligence" => Serializers.scrub(document) }

data/lib/rail_verdict/mcp/tools/get_verification_receipt.rb

@@ -48,10 +48,24 @@ module RailVerdict
         end
 
         def call(**_rest)
-          current_state = RailVerdict::RepositoryState.capture(repository_root: @server.repository_root)
-          case @server.cache.verification_state(current_state)
+          root = @server.repository_root
+          effective_paths = begin
+            RailVerdict::Check.effective_input_paths(root: File.realpath(root), config_path: File.join(File.realpath(root), ".railverdict.yml"))
+          rescue StandardError
+            nil
+          end
+          current_state = RailVerdict::RepositoryState.capture(repository_root: root, configuration_paths: effective_paths)
+          current_env = begin
+            # Use cached outcome config if available for relevant probing
+            outcome = @server.cache.fetch_outcome
+            config = outcome&.configuration
+            RailVerdict::VerificationEnvironment.capture(repository_root: root, configuration: config)
+          rescue StandardError
+            nil
+          end
+          case @server.cache.verification_state(current_state, current_env)
           when "fresh"
-            entry = @server.cache.fresh_entry(current_state)
+            entry = @server.cache.fresh_entry(current_state, current_env)
             receipt = entry&.receipt_document
             if receipt.is_a?(Hash) && receipt["receipt_id"]
               payload = { "status" => "fresh", "receipt" => Serializers.scrub(receipt) }

data/lib/rail_verdict/mcp/tools/inspect_handoff.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module MCP
+    module Tools
+      class InspectHandoff
+        def initialize(server:)
+          @server = server
+        end
+
+        def tool_name
+          "inspect_handoff"
+        end
+
+        def tool_title
+          "Inspect verification handoff"
+        end
+
+        def tool_description
+          "Parse and validate a Verification Handoff. Bounded, deterministic, tamper-detected via handoff_id. Does not execute analyzers."
+        end
+
+        def tool_input_schema
+          {
+            type: "object",
+            properties: {
+              handoff: { type: "object", description: "Handoff document to inspect" },
+              handoff_json: { type: "string", description: "Handoff JSON string (alternative to handoff object)" }
+            },
+            additionalProperties: false
+          }
+        end
+
+        def tool_output_schema
+          {
+            type: "object",
+            properties: {
+              valid: { type: "boolean" },
+              handoff: { type: ["object", "null"] },
+              error: { type: "string" },
+              handoff_id: { type: "string" }
+            },
+            required: %w[valid]
+          }
+        end
+
+        def tool_annotations
+          { read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false, title: tool_title }
+        end
+
+        def call(handoff: nil, handoff_json: nil, **_rest)
+          text = if handoff_json && !handoff_json.to_s.strip.empty?
+                   handoff_json.to_s
+                 elsif handoff
+                   JSON.generate(handoff)
+                 else
+                   return Serializers.error_response("handoff or handoff_json is required", code: "invalid_arguments")
+                 end
+          return Serializers.error_response("handoff too large", code: "handoff_too_large") if text.bytesize > Handoff::MAX_DOCUMENT_BYTES
+          doc, err = Handoff.parse(text)
+          if doc
+            Serializers.tool_response({ "valid" => true, "handoff" => Serializers.scrub(doc), "handoff_id" => doc["handoff_id"] }, error: false)
+          else
+            Serializers.tool_response({ "valid" => false, "error" => err.to_s, "handoff" => nil }, error: false)
+          end
+        rescue StandardError => e
+          Serializers.error_response("inspect_handoff failed: #{e.message}", code: "internal_error")
+        end
+      end
+    end
+  end
+end

data/lib/rail_verdict/mcp/tools/verify_handoff.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module MCP
+    module Tools
+      class VerifyHandoff
+        def initialize(server:)
+          @server = server
+        end
+
+        def tool_name
+          "verify_handoff"
+        end
+
+        def tool_title
+          "Verify handoff reuse"
+        end
+
+        def tool_description
+          "Evaluate whether a Verification Handoff is REUSABLE under current repository state/environment. Re-observes state/environment independently, never trusts Handoff. Returns REUSABLE or VERIFICATION_REQUIRED with reasons. Does not execute analyzers."
+        end
+
+        def tool_input_schema
+          {
+            type: "object",
+            properties: {
+              handoff: { type: "object", description: "Handoff document" },
+              handoff_json: { type: "string", description: "Handoff JSON string" },
+              config_path: { type: "string" },
+              baseline_path: { type: "string" },
+              waiver_path: { type: "string" }
+            },
+            additionalProperties: false
+          }
+        end
+
+        def tool_output_schema
+          {
+            type: "object",
+            properties: {
+              handoff_valid: { type: "boolean" },
+              receipt_fresh: { type: "boolean" },
+              decision: { type: "string", enum: %w[REUSABLE VERIFICATION_REQUIRED INVALID UNAVAILABLE] },
+              reasons: { type: "array" },
+              handoff_id: { type: "string" },
+              receipt_id: { type: "string" }
+            },
+            required: %w[decision]
+          }
+        end
+
+        def tool_annotations
+          { read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false, title: tool_title }
+        end
+
+        def call(handoff: nil, handoff_json: nil, config_path: nil, baseline_path: nil, waiver_path: nil, **_rest)
+          text = if handoff_json && !handoff_json.to_s.strip.empty?
+                   handoff_json.to_s
+                 elsif handoff
+                   JSON.generate(handoff)
+                 else
+                   return Serializers.error_response("handoff or handoff_json required", code: "invalid_arguments")
+                 end
+          return Serializers.error_response("handoff too large", code: "handoff_too_large") if text.bytesize > Handoff::MAX_DOCUMENT_BYTES
+          doc, err = Handoff.parse(text)
+          unless doc
+            return Serializers.tool_response({ "handoff_valid" => false, "receipt_fresh" => false, "decision" => Reuse::INVALID, "reasons" => [err.to_s] }, error: false)
+          end
+
+          root = @server.repository_root
+          effective_paths = Check.effective_input_paths(root: File.realpath(root), config_path: resolve_config_path(config_path), baseline_path_override: resolve_contained_path(baseline_path, "baseline_path"), waiver_path_override: resolve_contained_path(waiver_path, "waiver_path"))
+          before_state = RepositoryState.capture(repository_root: root, configuration_paths: effective_paths)
+          current_env_obj = VerificationEnvironment.capture(repository_root: root)
+          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" => doc.dig("source_scope", "verification_mode"), "changed_base" => doc.dig("source_scope", "changed_base") }
+          result = Reuse.evaluate(handoff_document: doc, current_repository_state: before_state, current_environment: current_env, current_contract: contract)
+          after_state = RepositoryState.capture(repository_root: root, 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
+          Serializers.tool_response({ "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") }, error: false)
+        rescue ArgumentError => e
+          Serializers.error_response(e.message, code: "invalid_arguments")
+        rescue StandardError => e
+          Serializers.error_response("verify_handoff failed: #{e.message}", code: "internal_error")
+        end
+
+        private
+
+        def resolve_contained_path(raw_path, field_name)
+          return nil if raw_path.nil? || raw_path.to_s.strip.empty?
+          raw = raw_path.to_s.strip
+          raise ArgumentError, "#{field_name} contains NUL byte" if raw.include?("\u0000")
+          expanded = File.expand_path(raw, @server.repository_root)
+          raise ArgumentError, "#{field_name} escapes repository root" unless RepositoryRoot.contained?(@server.repository_root, expanded)
+          expanded
+        end
+
+        def resolve_config_path(config_path)
+          return File.join(@server.repository_root, ".railverdict.yml") if config_path.nil? || config_path.to_s.strip.empty?
+          raw = config_path.to_s.strip
+          raise ArgumentError, "config_path contains NUL byte" if raw.include?("\u0000")
+          expanded = File.expand_path(raw, @server.repository_root)
+          raise ArgumentError, "config_path escapes repository root" unless RepositoryRoot.contained?(@server.repository_root, expanded)
+          expanded
+        end
+      end
+    end
+  end
+end