bparity 0.1.0

data/lib/bparity/cli/formal_commands.rb

@@ -0,0 +1,428 @@
+# frozen_string_literal: true
+
+module Bparity
+  module FormalCommands # rubocop:disable Metrics/ModuleLength -- one private CLI command family
+    private
+
+    def command_prove(argv)
+      options = formal_options(argv)
+      validate_formal_options!(options)
+      options[:requires].each { |path| require File.expand_path(path) }
+      bundle = SpecBundle::Loader.load(options[:spec])
+      Bparity.reset!
+      load File.expand_path(options[:adapter])
+      raise ConfigurationError, "The adapter file did not call Bparity.adapter." unless Bparity.adapter_definition
+
+      result = case options[:level]
+               when "f2" then run_f2(bundle, Bparity.adapter_definition, options)
+               when "f3" then run_f3(bundle, Bparity.adapter_definition, options)
+               else run_f4(bundle, Bparity.adapter_definition, options)
+               end
+      promote_f2_invariants(bundle, options, result)
+      @out.puts(JSON.pretty_generate(result.to_h))
+      result.success? || result.details["skipped"] ? 0 : 1
+    end
+
+    def formal_options(argv)
+      options = { spec: ".bparity/spec_bundle.yml", adapter: ".bparity/adapter.rb", level: "f2",
+                  size: 3, depth: 2, max_cases: 100_000, timebox: 300, requires: [], relation: "trace" }
+      OptionParser.new do |opts|
+        opts.on("--spec PATH") { |value| options[:spec] = value }
+        opts.on("--adapter PATH") { |value| options[:adapter] = value }
+        opts.on("--level LEVEL") { |value| options[:level] = value }
+        add_formal_target_options(opts, options)
+        opts.on("--scope SCOPE") { |value| parse_scope(value, options) }
+        opts.on("--max-cases N", Integer) { |value| options[:max_cases] = value }
+        opts.on("--timebox SECONDS", Integer) { |value| options[:timebox] = value }
+        opts.on("--state-limit N", Integer) { |value| options[:state_limit] = value }
+        opts.on("--equivalence RELATION") { |value| options[:relation] = value }
+        opts.on("--export-lts PREFIX") { |value| options[:export_lts] = value }
+        opts.on("--counterexample-out PATH") { |value| options[:counterexample_out] = value }
+        add_formal_validation_options(opts, options)
+        opts.on("--old-source PATH") { |value| options[:old_source] = value }
+        opts.on("--new-source PATH") { |value| options[:new_source] = value }
+        opts.on("--old-method NAME") { |value| options[:old_method] = value }
+        opts.on("--new-method NAME") { |value| options[:new_method] = value }
+        opts.on("--types TYPES") { |value| options[:types] = value.split(",") }
+        opts.on("--solver NAME") { |value| options[:solver] = value }
+        opts.on("--require PATH") { |value| options[:requires] << value }
+      end.parse!(argv)
+      options
+    end
+
+    def promote_f2_invariants(bundle, options, result)
+      return unless options[:level] == "f2" && options[:promote_invariants] && result.success? &&
+                    result.scope.exhaustive
+
+      _subject, operation = select_formal_operation(bundle, options)
+      invariants = operation.fetch("invariants", [])
+      invariants.each { |invariant| invariant["formal_level"] = "F2" }
+      result.details["promoted_invariants"] = invariants.map { |invariant| invariant["id"] }
+      SpecBundle::Writer.write(options[:spec], bundle)
+    end
+
+    def add_formal_target_options(parser, options)
+      parser.on("--subject NAME") { |value| options[:subject] = value }
+      parser.on("--operation NAME") { |value| options[:operation] = value }
+    end
+
+    def add_formal_validation_options(parser, options)
+      parser.on("--validate-translation") { options[:validate_translation] = true }
+      parser.on("--promote-invariants") { options[:promote_invariants] = true }
+    end
+
+    def validate_formal_options!(options)
+      unless %w[f2 f3 f4].include?(options[:level])
+        raise ConfigurationError, "Formal level #{options[:level]} is not available. Use f2, f3, or f4."
+      end
+      unless options.values_at(:size, :depth).all? { |value| value >= 0 } &&
+             options.values_at(:max_cases, :timebox).all?(&:positive?) &&
+             (!options[:state_limit] || options[:state_limit].positive?)
+        raise ConfigurationError,
+              "Formal limits are invalid. Use non-negative size/depth and positive case, time, and state limits."
+      end
+      return unless options[:level] == "f4" && !options[:validate_translation]
+
+      raise ConfigurationError, "F4 requires --validate-translation. Run F2 first and enable translation validation."
+    end
+
+    def run_f2(bundle, adapter, options)
+      spec_subject, operation_spec = select_formal_operation(bundle, options)
+      binding, operation = formal_binding(adapter, spec_subject, operation_spec)
+      old_class = legacy_class(spec_subject)
+      domains = f2_domains(operation_spec, options)
+      method_name = operation_spec.fetch("name").delete_prefix("#")
+      validate_legacy_operation!(old_class, method_name) if old_class
+      old_callable = ->(*args) { old_class.new.public_send(method_name, *args) } if old_class
+      new_callable = ->(*args) { operation.invoke(binding.build({}), args, {}) }
+      runner = build_f2_runner(old_callable, new_callable, domains, operation, operation_spec, options)
+      violations = f2_static_violations(old_class, method_name, operation)
+      unless violations.empty?
+        return Formal::Result.new(level: :f2, verdict: :inconclusive,
+                                  scope: Formal::Scope.new(size: options[:size], depth: options[:depth],
+                                                           cases: 0, exhaustive: false,
+                                                           timebox: options[:timebox]),
+                                  assumptions: %i[h1 h3 h7], out_of_scope: ["dynamic Ruby"],
+                                  details: { "assumption_violations" => violations })
+      end
+      target = binding.build({})
+      monitored_class = target.is_a?(Module) ? target.singleton_class : target.class
+      result, violations = Formal::Assumptions::WorldFreeze.new([old_class, monitored_class].compact).check do
+        runner.run
+      end
+      if violations.empty?
+        write_f2_counterexample(result, options, spec_subject, operation_spec)
+        return result
+      end
+
+      Formal::Result.new(level: :f2, verdict: :inconclusive, scope: result.scope,
+                         assumptions: result.assumptions, out_of_scope: result.out_of_scope,
+                         details: { "assumption_violations" => violations })
+    end
+
+    def legacy_class(subject)
+      Bparity.constantize(subject.fetch("old_class"))
+    rescue ConfigurationError => e
+      raise unless e.message.start_with?("Cannot find ")
+
+      nil
+    end
+
+    def validate_legacy_operation!(old_class, method_name)
+      unless old_class.public_method_defined?(method_name)
+        raise ConfigurationError,
+              "Legacy class #{old_class} has no public method #{method_name}. Fix the Spec Bundle target."
+      end
+      old_class.new
+    rescue ConfigurationError
+      raise
+    rescue StandardError => e
+      raise ConfigurationError,
+            "Legacy class #{old_class} cannot be constructed without arguments: #{e.message}. " \
+            "Use contract-only F2 or record a construct mapping."
+    end
+
+    def f2_static_violations(old_class, method_name, operation)
+      old_source = old_class.instance_method(method_name).source_location&.first if old_class
+      paths = [old_source, operation.invoker&.source_location&.first].compact.uniq
+      Formal::Assumptions::DynamicCodeDetector.new.scan(paths)
+    end
+
+    def write_f2_counterexample(result, options, subject, operation)
+      return unless result.counterexample && options[:counterexample_out]
+
+      content = Formal::BoundedCounterexampleRSpec.call(result:, subject_name: subject.fetch("name"),
+                                                        operation_name: operation.fetch("name"))
+      FileUtils.mkdir_p(File.dirname(options[:counterexample_out]))
+      File.write(options[:counterexample_out], content)
+    end
+
+    def f2_domains(operation_spec, options)
+      limit = options.fetch(:max_cases, Formal::ExhaustiveRunner::DEFAULT_MAX_CASES)
+      operation_spec.fetch("params", []).map do |param|
+        observed = param.fetch("observed_values", []).map { |value| Recording::Serializer.load(value) }
+        alphabet = observed.grep(String).flat_map(&:chars).uniq.first(8)
+        enumerator = Formal::ValueEnumerator.new(size: options[:size], depth: options[:depth],
+                                                 alphabet: alphabet.empty? ? %w[a b] : alphabet, observed:,
+                                                 limit:)
+        types = param.fetch("types", [])
+        if types.empty?
+          raise ConfigurationError,
+                "F2 parameter #{param['name']} has no inferred type. Record values or add an explicit input domain."
+        end
+        type_domains = types.map { |type| enumerator.values(type) }
+        values = (type_domains.flat_map(&:to_a) + [nil]).uniq
+        truncated = type_domains.any?(&:truncated) || values.length > limit
+        Formal::Domain.new(values.first(limit), truncated:)
+      end
+    end
+
+    def select_formal_operation(bundle, options)
+      subjects = bundle.fetch("subjects")
+      subjects = subjects.select { |subject| subject["name"] == options[:subject] } if options[:subject]
+      if subjects.length != 1
+        names = bundle.fetch("subjects").map { |subject| subject.fetch("name") }.join(", ")
+        raise ConfigurationError, "Select one formal subject with --subject NAME. Available subjects: #{names}."
+      end
+
+      subject = subjects.first
+      operations = subject.fetch("operations")
+      operations = operations.select { |operation| operation["name"] == options[:operation] } if options[:operation]
+      if operations.length != 1
+        names = subject.fetch("operations").map { |operation| operation.fetch("name") }.join(", ")
+        raise ConfigurationError, "Select one formal operation with --operation NAME. Available operations: #{names}."
+      end
+      [subject, operations.first]
+    end
+
+    def formal_binding(adapter, subject, operation = nil)
+      binding = adapter.subjects[subject.fetch("name")]
+      unless binding
+        raise ConfigurationError,
+              "Adapter subject #{subject.fetch('name')} is missing. Add it to the adapter file."
+      end
+      return binding unless operation
+
+      mapped = binding.operations[operation.fetch("name")]
+      unless mapped
+        raise ConfigurationError,
+              "Adapter operation #{subject.fetch('name')}#{operation.fetch('name')} is missing. Add it to the adapter."
+      end
+      [binding, mapped]
+    end
+
+    def build_f2_runner(old_callable, new_callable, domains, operation, operation_spec, options)
+      contracts = operation_spec.fetch("postconditions", []) + operation_spec.fetch("invariants", [])
+      Formal::ExhaustiveRunner.new(old_callable:, new_callable:, domains:, size: options[:size],
+                                   depth: options[:depth], assumptions: %i[h1 h3 h7],
+                                   contracts:, preconditions: operation_spec.fetch("preconditions", []),
+                                   max_cases: options[:max_cases], timebox: options[:timebox],
+                                   new_error_mapper: operation.method(:map_error))
+    end
+
+    def parse_scope(value, options)
+      value.split(",").each do |entry|
+        key, number = entry.split("=", 2)
+        raise ConfigurationError, "Invalid scope #{entry}. Use size=N,depth=N." unless %w[size depth].include?(key)
+
+        options[key.to_sym] = Integer(number, 10)
+      end
+    rescue ArgumentError
+      raise ConfigurationError, "Invalid scope #{value}. Use size=N,depth=N."
+    end
+
+    def run_f3(bundle, adapter, options)
+      spec_subject = select_f3_subject(bundle, options)
+      old_data = bundle.fetch("lts").find { |model| model["id"] == spec_subject["lts_ref"] }
+      old_lts = Formal::LTS.from_h(old_data)
+      binding = formal_binding(adapter, spec_subject)
+      unless binding.state_projection
+        raise ConfigurationError,
+              "Adapter subject #{binding.name} needs a state block for F3."
+      end
+
+      static_violations = f3_static_violations(spec_subject, binding)
+      return inconclusive_f3(old_lts, options, static_violations) unless static_violations.empty?
+
+      learned, runtime_violations = learn_f3(binding, options)
+      export_lts(options[:export_lts], old_lts, learned.lts) if options[:export_lts]
+      result = Formal::LtsEquivalence.new.compare(old_lts, learned.lts, relation: options[:relation],
+                                                                        exact: learned.complete)
+      unless runtime_violations.empty?
+        return Formal::Result.new(level: :f3, verdict: :inconclusive, scope: result.scope,
+                                  assumptions: result.assumptions, out_of_scope: result.out_of_scope,
+                                  details: result.details.merge("assumption_violations" => runtime_violations))
+      end
+      result.details["skipped"] = "state limit exceeded" unless learned.complete || result.counterexample
+      write_lts_counterexample(result, options, old_lts, spec_subject)
+      result
+    end
+
+    def select_f3_subject(bundle, options)
+      stateful = bundle.fetch("subjects").select { |subject| subject["lts_ref"] }
+      stateful.select! { |subject| subject["name"] == options[:subject] } if options[:subject]
+      if stateful.empty?
+        raise ConfigurationError, "The Spec Bundle has no stateful subject. Record with a state projection first."
+      end
+
+      if stateful.length > 1
+        names = stateful.map { |subject| subject.fetch("name") }.join(", ")
+        raise ConfigurationError, "Select one F3 subject with --subject NAME. Available subjects: #{names}."
+      end
+      stateful.first
+    end
+
+    def f3_static_violations(spec_subject, binding)
+      parameterized = spec_subject.fetch("operations").filter_map do |operation|
+        next if operation.fetch("params", []).empty?
+
+        { "assumption" => "H6", "location" => operation.fetch("name"),
+          "reason" => "F3 requires a declared finite input alphabet for parameterized operations" }
+      end
+      paths = binding.operations.values.filter_map { |operation| operation.invoker&.source_location&.first }.uniq
+      parameterized + Formal::Assumptions::DynamicCodeDetector.new.scan(paths)
+    end
+
+    def learn_f3(binding, options)
+      operations = binding.operations.to_h { |name, operation| [name, observed_operation(operation)] }
+      learner = Formal::ActiveLearner.new(factory: -> { binding.build({}) },
+                                          state_projection: binding.state_projection, operations:,
+                                          state_limit: options.fetch(:state_limit, 500))
+      target = binding.build({})
+      monitored_class = target.is_a?(Module) ? target.singleton_class : target.class
+      Formal::Assumptions::WorldFreeze.new([monitored_class]).check { learner.learn }
+    end
+
+    def inconclusive_f3(old_lts, options, violations)
+      Formal::Result.new(level: :f3, verdict: :inconclusive,
+                         scope: Formal::Scope.new(size: old_lts.states.length, depth: nil, cases: 0,
+                                                  exhaustive: false, timebox: options[:timebox]),
+                         assumptions: %i[h1 h3 h6 h7],
+                         out_of_scope: ["replacement model exploration"],
+                         details: { "assumption_violations" => violations })
+    end
+
+    def observed_operation(operation)
+      lambda do |subject|
+        value = operation.invoke(subject, [], {})
+        Formal::ObservedOutput.new({ "kind" => "return",
+                                     "value" => Recording::Serializer.dump(operation.map_return(value)) })
+      rescue StandardError => e
+        Formal::ObservedOutput.new({ "kind" => "raise", **operation.map_error(e) })
+      end
+    end
+
+    def write_lts_counterexample(result, options, old_lts, spec_subject)
+      return unless result.counterexample && options[:counterexample_out]
+
+      spec = Formal::CounterexampleRSpec.call(lts: old_lts,
+                                              sequence: result.counterexample.fetch("sequence"),
+                                              subject_name: spec_subject.fetch("name"))
+      FileUtils.mkdir_p(File.dirname(options[:counterexample_out]))
+      File.write(options[:counterexample_out], spec)
+    end
+
+    def export_lts(prefix, old_lts, new_lts)
+      FileUtils.mkdir_p(File.dirname(prefix))
+      File.write("#{prefix}_old.aut", Formal::AldebaranExporter.call(old_lts))
+      File.write("#{prefix}_new.aut", Formal::AldebaranExporter.call(new_lts))
+    end
+
+    def run_f4(bundle, adapter, options)
+      validate_f4_options!(options)
+      fragment_violations = Formal::Deductive::FragmentChecker.new.then do |checker|
+        checker.check_file(options[:old_source], options[:old_method]) +
+          checker.check_file(options[:new_source], options[:new_method])
+      end
+      unless fragment_violations.empty?
+        return inconclusive_f4(options, "verifiable fragment rejected",
+                               fragment_violations)
+      end
+
+      subject_spec, operation_spec = select_formal_operation(bundle, options)
+      binding, operation = formal_binding(adapter, subject_spec, operation_spec)
+      runner, old_class = build_f4_runner(subject_spec, binding, operation, options)
+      target = binding.build({})
+      target_class = target.is_a?(Module) ? target.singleton_class : target.class
+      result, violations = Formal::Assumptions::WorldFreeze.new([old_class, target_class]).check { runner.run }
+      if violations.empty?
+        write_f4_counterexample(result, options, subject_spec, operation_spec)
+        return result
+      end
+
+      Formal::Result.new(level: :f4, verdict: :inconclusive, scope: result.scope,
+                         assumptions: result.assumptions, out_of_scope: result.out_of_scope,
+                         details: result.details.merge("assumption_violations" => violations))
+    rescue ConfigurationError => e
+      raise unless e.message.start_with?("F4 does not support")
+
+      inconclusive_f4(options, e.message, [])
+    end
+
+    def build_f4_runner(subject, binding, operation, options)
+      old_class = Bparity.constantize(subject.fetch("old_class"))
+      translator = Formal::Deductive::RubyToSmt.new
+      old_translation = translator.translate_file(options[:old_source], options[:old_method],
+                                                  parameter_types: options[:types])
+      new_translation = translator.translate_file(options[:new_source], options[:new_method],
+                                                  parameter_types: options[:types])
+      validation_inputs = f4_inputs(options[:types], options)
+      runner = Formal::Deductive::Runner.new(
+        old_translation:, new_translation:,
+        old_callable: ->(*args) { old_class.new.public_send(options[:old_method], *args) },
+        new_callable: ->(*args) { operation.invoke(binding.build({}), args, {}) },
+        validation_inputs:,
+        validation_scope: { "size" => options[:size], "depth" => options[:depth],
+                            "cases" => validation_inputs.length, "exhaustive" => true },
+        solver: Formal::Deductive::Z3.new(timeout: options[:timebox])
+      )
+      [runner, old_class]
+    end
+
+    def write_f4_counterexample(result, options, subject, operation)
+      return unless result.counterexample&.key?("input") && options[:counterexample_out]
+
+      content = Formal::Deductive::CounterexampleRSpec.call(
+        result:, subject_name: subject.fetch("name"), operation_name: operation.fetch("name")
+      )
+      FileUtils.mkdir_p(File.dirname(options[:counterexample_out]))
+      File.write(options[:counterexample_out], content)
+    end
+
+    def inconclusive_f4(options, reason, violations)
+      Formal::Result.new(level: :f4, verdict: :inconclusive,
+                         scope: Formal::Scope.new(size: options[:size], depth: options[:depth], cases: 0,
+                                                  exhaustive: false, timebox: options[:timebox]),
+                         assumptions: %i[h1 h3], out_of_scope: ["Ruby outside the declared pure fragment"],
+                         details: { "reason" => reason, "fragment_violations" => violations })
+    end
+
+    def validate_f4_options!(options)
+      required = %i[old_source new_source old_method new_method types]
+      missing = required.reject { |key| options[key] }
+      unless missing.empty?
+        raise ConfigurationError,
+              "F4 is missing #{missing.join(', ')}. Provide both sources, method names, and --types."
+      end
+      return unless options[:solver] && options[:solver] != "z3"
+
+      raise ConfigurationError, "Unsupported F4 solver #{options[:solver]}. Use z3."
+    end
+
+    def f4_inputs(types, options)
+      domains = types.map do |type|
+        Formal::ValueEnumerator.new(size: options[:size], depth: options[:depth]).values(type)
+      end
+      return [[]] if domains.empty?
+
+      cases = domains.reduce(1) { |count, domain| count * domain.length }
+      if cases > options[:max_cases]
+        raise ConfigurationError,
+              "F4 does not support truncated translation validation. Increase --max-cases above #{cases} or " \
+              "reduce --scope."
+      end
+
+      domains.first.product(*domains.drop(1))
+    end
+  end # rubocop:enable Metrics/ModuleLength
+end

data/lib/bparity/cli/verification_commands.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Bparity
+  module VerificationCommands
+    private
+
+    def command_verify(argv)
+      options = verify_options(argv)
+      validate_verify_options!(options)
+      options[:requires].each { |path| require File.expand_path(path) }
+      bundle = SpecBundle::Loader.load(options[:spec])
+      adapter = load_verify_adapter(bundle, options[:adapter], options[:adapter_explicit])
+      results = options[:runners].flat_map { |runner| run_verify_runner(runner, bundle, adapter, options) }
+      write_verification_report(results, bundle, options)
+      verify_success?(results, options[:fail_under]) ? 0 : 1
+    end
+
+    def verify_options(argv)
+      options = { spec: ".bparity/spec_bundle.yml", adapter: ".bparity/adapter.rb", format: "markdown",
+                  runners: ["replay"], fail_under: 100.0, size: 3, depth: 2, max_cases: 1_000,
+                  timebox: 300, state_limit: 500, relation: "trace", requires: [] }
+      OptionParser.new do |opts|
+        add_verify_core_options(opts, options)
+        add_verify_generation_options(opts, options)
+      end.parse!(argv)
+      options
+    end
+
+    def add_verify_core_options(parser, options)
+      parser.on("--spec PATH") { |value| options[:spec] = value }
+      parser.on("--adapter PATH") do |value|
+        options[:adapter] = value
+        options[:adapter_explicit] = true
+      end
+      parser.on("--mode MODE") { |value| options[:mode] = value }
+      parser.on("--runners LIST") { |value| options[:runners] = value.split(",") }
+      parser.on("--fail-under PERCENT", Float) { |value| options[:fail_under] = value }
+      parser.on("--format FORMAT") { |value| options[:format] = value }
+      parser.on("--out PATH") { |value| options[:out] = value }
+      parser.on("--require PATH") { |value| options[:requires] << value }
+    end
+
+    def add_verify_generation_options(parser, options)
+      parser.on("--scope SCOPE") { |value| parse_scope(value, options) }
+      parser.on("--max-cases N", Integer) { |value| options[:max_cases] = value }
+      parser.on("--timebox SECONDS", Integer) { |value| options[:timebox] = value }
+      parser.on("--state-limit N", Integer) { |value| options[:state_limit] = value }
+      parser.on("--equivalence RELATION") { |value| options[:relation] = value }
+      parser.on("--subject NAME") { |value| options[:subject] = value }
+      parser.on("--operation NAME") { |value| options[:operation] = value }
+      parser.on("--old-command COMMAND") { |value| options[:old_command] = Shellwords.split(value) }
+      parser.on("--new-command COMMAND") { |value| options[:new_command] = Shellwords.split(value) }
+    end
+
+    def validate_verify_options!(options)
+      unless Reporting::Reporter::FORMATS.include?(options[:format])
+        raise ConfigurationError,
+              "Unknown report format #{options[:format]}. Use markdown, json, junit, or html."
+      end
+      allowed = %w[replay property model differential]
+      unknown = options[:runners] - allowed
+      unless unknown.empty?
+        raise ConfigurationError,
+              "Unknown verification runner #{unknown.join(', ')}. Use replay, property, model, or differential."
+      end
+      raise ConfigurationError, "At least one verification runner is required." if options[:runners].empty?
+      unless (0.0..100.0).cover?(options[:fail_under])
+        raise ConfigurationError, "Verification threshold must be between 0 and 100."
+      end
+      unless options.values_at(:size, :depth).all? { |value| value >= 0 } &&
+             options.values_at(:max_cases, :timebox, :state_limit).all?(&:positive?)
+        raise ConfigurationError,
+              "Verification limits are invalid. Use non-negative size/depth and positive case, time, and state limits."
+      end
+      return unless options[:runners].include?("differential") &&
+                    (!options[:old_command] || !options[:new_command])
+
+      raise ConfigurationError,
+            "Differential verification requires --old-command and --new-command. " \
+            "Each command must read JSON from stdin."
+    end
+
+    def load_verify_adapter(bundle, path, explicit)
+      if File.exist?(path)
+        Bparity.reset!
+        load File.expand_path(path)
+        return Bparity.adapter_definition || raise(ConfigurationError,
+                                                   "The adapter file did not call Bparity.adapter.")
+      end
+      if explicit
+        raise ConfigurationError,
+              "Adapter file #{path} was not found. Correct the path or omit --adapter for direct replay."
+      end
+
+      direct_adapter(bundle)
+    end
+
+    def direct_adapter(bundle)
+      Adapter::Definition.new.tap do |definition|
+        bundle.fetch("subjects").each do |spec_subject|
+          name = spec_subject.fetch("name")
+          definition.subject(name) do
+            construct do
+              target = Bparity.constantize(name)
+              target.is_a?(Class) ? target.new : target
+            end
+            spec_subject.fetch("operations").each do |spec_operation|
+              operation(spec_operation.fetch("name"))
+            end
+          end
+        end
+      end
+    end
+
+    def run_verify_runner(name, bundle, adapter, options)
+      case name
+      when "replay" then Verification::Runner.new(bundle:, adapter:, mode: options[:mode]).run
+      when "property" then run_property_verification(bundle, adapter, options)
+      when "model" then [formal_verification_result(run_f3(bundle, adapter, options), "model")]
+      else run_differential_verification(bundle, options)
+      end
+    end
+
+    def run_property_verification(bundle, adapter, options)
+      checks = bundle.fetch("subjects").flat_map do |subject|
+        subject.fetch("operations").filter_map do |operation_spec|
+          contracts = operation_spec.fetch("postconditions", []) + operation_spec.fetch("invariants", [])
+          next if contracts.empty?
+
+          binding, operation = formal_binding(adapter, subject, operation_spec)
+          callable = lambda do |*args|
+            operation.map_return(operation.invoke(binding.build({}), args, {}))
+          end
+          counterexample = Formal::PropertyRunner.new(
+            callable:, invariants: contracts, inputs: generated_inputs(operation_spec, options),
+            preconditions: operation_spec.fetch("preconditions", [])
+          ).run
+          property_result(subject, operation_spec, counterexample)
+        end
+      end
+      return checks unless checks.empty?
+
+      raise ConfigurationError,
+            "Property verification found no contracts. Synthesize invariants or select the replay runner."
+    end
+
+    def run_differential_verification(bundle, options)
+      subject, operation = select_formal_operation(bundle, options)
+      differences = Formal::DifferentialRunner.new(
+        old_command: options[:old_command], new_command: options[:new_command],
+        inputs: generated_inputs(operation, options)
+      ).run
+      if differences.empty?
+        return [Verification::Result.new(id: "differential:#{subject['name']}#{operation['name']}",
+                                         status: :pass, description: "Generated differential inputs matched",
+                                         differences: [], provenance: { "runner" => "differential" })]
+      end
+
+      differences.each_with_index.map do |difference, index|
+        Verification::Result.new(id: "differential:#{subject['name']}#{operation['name']}:#{index + 1}",
+                                 status: :fail, description: "Generated differential input differed",
+                                 differences: difference.fetch("differences"),
+                                 provenance: { "runner" => "differential",
+                                               "input" => Recording::Serializer.dump(difference.fetch("input")) })
+      end
+    end
+
+    def generated_inputs(operation, options)
+      domains = operation.fetch("params", []).map { |param| generated_domain(param, options) }
+      Enumerator.new do |items|
+        if domains.empty?
+          items << []
+        else
+          domains.first.product(*domains.drop(1)) { |input| items << input }
+        end
+      end.take(options[:max_cases])
+    end
+
+    def generated_domain(param, options)
+      observed = param.fetch("observed_values", []).map { |value| Recording::Serializer.load(value) }
+      alphabet = observed.grep(String).flat_map(&:chars).uniq.first(8)
+      generator = Formal::InputGenerator.new(size: options[:size], depth: options[:depth], observed:,
+                                             alphabet: alphabet.empty? ? %w[a b] : alphabet)
+      types = param.fetch("types", [])
+      if types.empty?
+        raise ConfigurationError,
+              "Property parameter #{param['name']} has no inferred type. Record values or add an input domain."
+      end
+      types.flat_map { |type| generator.values(type) }.uniq
+    end
+
+    def property_result(subject, operation, counterexample)
+      differences = []
+      if counterexample
+        differences = counterexample.fetch("violations").map do |violation|
+          { "path" => "$.contracts.#{violation['id']}", "expected" => true,
+            "actual" => violation["error"] || false }
+        end
+      end
+      Verification::Result.new(id: "property:#{subject['name']}#{operation['name']}",
+                               status: differences.empty? ? :pass : :fail,
+                               description: "Generated property inputs satisfy declared contracts",
+                               differences:, provenance: { "runner" => "property",
+                                                           "input" => Recording::Serializer.dump(
+                                                             counterexample&.fetch("input", nil)
+                                                           ) })
+    end
+
+    def formal_verification_result(result, name)
+      skipped = result.details["skipped"]
+      differences = if result.success? || skipped
+                      []
+                    else
+                      [{ "path" => "$.#{name}", "expected" => "no difference",
+                         "actual" => result.counterexample || result.details }]
+                    end
+      status = if skipped then :skipped
+               elsif differences.empty? then :pass
+               else :fail
+               end
+      Verification::Result.new(id: name, status:, description: skipped || "Finite-state model conformance",
+                               differences:, provenance: { "runner" => name, "formal_result" => result.to_h })
+    end
+
+    def write_verification_report(results, bundle, options)
+      report = Reporting::Reporter.new(results, bundle:).public_send(options[:format])
+      return @out.puts(report) unless options[:out]
+
+      FileUtils.mkdir_p(File.dirname(options[:out]))
+      File.write(options[:out], report)
+    end
+
+    def verify_success?(results, threshold)
+      eligible = results.reject { |result| result.status == :skipped }
+      return false if eligible.empty? || eligible.any? { |result| result.status == :fail }
+
+      100.0 * eligible.count { |result| %i[pass waived].include?(result.status) } / eligible.length >= threshold
+    end
+  end
+end