bparity 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b9f47440ae17ece5214893bb3f2e012f069fba252bced3580da8dae06e9a808
+  data.tar.gz: b529651ce97730707485285311831a8f1d2b17fc14150f86c7bf15c4a74d953d
+SHA512:
+  metadata.gz: 78738e2d8f3c8d972fb26e723f311f7710fe1beb8c3d982054882b76ffbcdff5196d4824e9f3f721279c84093d73adf364c5f4a34196f4e8257f9bba9ee8e5a4
+  data.tar.gz: ac3460337046a7f8b6a794ae238d0deb67c80eb7d0373526982fb3af56a1d73085c387f9de156e4166a81f4eebe9c4f37f7f383f23c340bd1e3cca376d678cdd

data/.rubocop.yml

@@ -0,0 +1,61 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  CacheRootDirectory: tmp/rubocop_cache
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.1
+  Exclude:
+    - ".idea/**/*"
+    - "fixtures/**/*"
+    - "tmp/**/*"
+    - "vendor/**/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 55
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+    - "Rakefile"
+
+Metrics/ClassLength:
+  Max: 300
+
+Metrics/CyclomaticComplexity:
+  Max: 25
+
+Metrics/MethodLength:
+  Max: 35
+
+Metrics/ModuleLength:
+  Max: 250
+
+Metrics/ParameterLists:
+  Max: 12
+
+Metrics/PerceivedComplexity:
+  Max: 15
+
+RSpec/ExampleLength:
+  Max: 30
+
+RSpec/MultipleExpectations:
+  Max: 8
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/VariableDefinition:
+  Enabled: false
+
+RSpec/VariableName:
+  Enabled: false

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+# bparity
+
+`bparity` captures the observable behavior of a legacy Ruby API, stores it as a portable specification bundle, and checks a structurally different replacement through a small adapter. The legacy dependency is not needed during verification.
+
+## Preserve the legacy environment first
+
+If the old dependency can still run, preserve it before installing anything else:
+
+```bash
+bundle package --all
+bundle exec bparity init --timecapsule
+```
+
+Commit `vendor/cache`, the generated time-capsule Dockerfile, the behavior corpus, and the Specification Bundle. The replacement-side verifier does not load the legacy dependency.
+
+## Installation
+
+```bash
+bundle add bparity
+```
+
+## Usage
+
+Get an initial boundary proposal from calls made by an exercise script. Discovery observes Ruby calls only; C calls are intentionally excluded:
+
+```bash
+bundle exec bparity discover --require lib/legacy.rb --target Legacy::Slugifier script/exercise_legacy.rb
+```
+
+Create `.bparity/boundary.rb` in the legacy environment:
+
+```ruby
+Bparity.boundary do
+  observe "Legacy::Slugifier" do
+    methods :call
+  end
+  driver :rspec, files: "spec/**/*_spec.rb"
+end
+```
+
+Record and synthesize a checked specification bundle while the legacy environment still works:
+
+```bash
+bundle exec bparity record --require lib/legacy.rb
+bundle exec bparity synthesize --coverage .bparity/coverage.json \
+  --tests 'spec/**/*_spec.rb' --source 'lib/**/*.rb'
+```
+
+If the legacy runtime is already unavailable, extract only executable static assertions and mark the missing runtime evidence as a gap:
+
+```bash
+bundle exec bparity synthesize --static-only --tests 'spec/**/*_spec.rb' --source 'lib/**/*.rb'
+```
+
+Commit `.bparity/spec_bundle.yml`. In the replacement environment, map its abstract operations to the new API:
+
+```ruby
+Bparity.adapter(spec: ".bparity/spec_bundle.yml") do
+  subject "Slugifier" do
+    construct { NewSlugService }
+    operation "#call" do
+      invoke { |service, args, _kwargs| service.generate(text: args.fetch(0)) }
+    end
+  end
+end
+```
+
+The verification step requires only the bundle, adapter, and replacement:
+
+```bash
+bundle exec bparity verify --require lib/new_slug_service.rb \
+  --runners replay,property,model --fail-under 100
+```
+
+`replay` checks recorded examples, `property` generates boundary inputs for declared contracts, and `model` checks a stateful replacement against the learned LTS. `differential` additionally requires `--old-command` and `--new-command`; both commands read one JSON input from stdin and print one JSON observation. For same-named classes and public methods, omit `--adapter` to use direct replay. An explicitly supplied but missing adapter is an error.
+
+Reports support `markdown`, `json`, `junit`, and `html`. A changed bundle checksum is rejected; intentional incompatibilities must be declared with `waive` in the adapter. Skipped model checks do not count toward `--fail-under`, and a run with only skipped checks fails.
+
+Generate an adapter skeleton when the bundle is ready:
+
+```bash
+bundle exec bparity init --from-spec .bparity/spec_bundle.yml
+```
+
+Run a bounded exhaustive comparison while both implementations are available:
+
+```bash
+bundle exec bparity prove --level f2 --scope size=3,depth=2 \
+  --require lib/legacy.rb --require lib/replacement.rb \
+  --counterexample-out spec/f2_counterexample_spec.rb --promote-invariants
+```
+
+The result uses `no_difference_found`, `difference_found`, or `inconclusive`; it always includes the enumerated case count, scope, assumptions, and excluded inputs.
+If the legacy class is unavailable, F2 checks the replacement against declared postconditions and invariants instead. It refuses to run when neither legacy execution nor contracts are available. Domain generation is bounded by `--max-cases`; any truncation is reported as `inconclusive`, never exhaustive.
+
+For a stateful subject with `state` projections in both the boundary and adapter, compare learned finite models:
+
+```bash
+bundle exec bparity prove --level f3 --equivalence trace \
+  --require lib/replacement.rb --export-lts tmp/client
+```
+
+F3 reports both model sizes, the learned alphabet, whether exploration was exact, and the shortest distinguishing sequence. `--counterexample-out spec/f3_counterexample_spec.rb` writes that sequence as a regression example. The claim applies only to the projected models.
+
+For an explicitly selected pure Ruby fragment, F4 translates both methods to SMT-LIB 2 and invokes Z3:
+
+```bash
+bundle exec bparity prove --level f4 --solver z3 --validate-translation \
+  --old-source lib/legacy_math.rb --old-method double \
+  --new-source lib/new_math.rb --new-method twice --types Integer \
+  --require lib/legacy_math.rb --require lib/new_math.rb \
+  --counterexample-out spec/f4_counterexample_spec.rb
+```
+
+Translation validation is mandatory. Unsupported Ruby, a translation mismatch, a missing Z3 executable, `unknown`, and solver failures all produce `inconclusive`, never PASS. The implemented fragment covers pure Integer/Boolean/String expressions and conditionals.
+
+Run the five-point adequacy assessment, optionally with the soft `mutant` integration:
+
+```bash
+bundle exec bparity adequacy --require lib/replacement.rb
+bundle exec bparity adequacy --require lib/replacement.rb --mutant
+```
+
+## Assurance limits
+
+A successful replay means no difference was found for the recorded examples (F0). It does not prove complete program equivalence. Formal checks always report their bounded scope, assumptions, and unverified areas; solver `unknown` and timeouts are inconclusive, never PASS. See [Formal assurance limits](docs/formal_assurance_limits.md).
+
+## Reproduce the fixtures
+
+The acceptance suite records, synthesizes, and verifies all five scenarios. Each has a structurally different correct replacement and an intentionally broken replacement:
+
+```bash
+bundle exec rspec spec/acceptance_spec.rb
+```
+
+## Development
+
+After checking out the repository, run `bundle install` and `bundle exec rake`.
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/ydah/bparity.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+require "tmpdir"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+desc "Measure recording overhead against the pure-function fixture"
+task :benchmark_recording do
+  plain = [RbConfig.ruby, "-Ilib", "-r./fixtures/scenarios/01_pure_function/legacy/slugifier.rb",
+           "-S", "rspec", "fixtures/scenarios/01_pure_function/spec/slugifier_spec.rb"]
+  Dir.mktmpdir do |directory|
+    recorded = [RbConfig.ruby, "-Ilib", "exe/bparity", "record", "--boundary",
+                "fixtures/scenarios/01_pure_function/boundary.rb", "--out", File.join(directory, "corpus.jsonl"),
+                "--coverage", File.join(directory, "coverage.json"), "--require",
+                "fixtures/scenarios/01_pure_function/legacy/slugifier.rb"]
+    median = lambda do |command|
+      5.times.map do
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        abort "Benchmark command failed: #{command.join(' ')}" unless system(*command, out: File::NULL, err: File::NULL)
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+      end.sort[2]
+    end
+    baseline = median.call(plain)
+    instrumented = median.call(recorded)
+    overhead = ((instrumented / baseline) - 1) * 100
+    puts format("Recording overhead: %<overhead>.1f%% (plain %<plain>.3fs, recorded %<recorded>.3fs)",
+                overhead:, plain: baseline, recorded: instrumented)
+    abort "Recording overhead exceeds 50%" if overhead > 50
+  end
+end

data/docs/application_example.md

@@ -0,0 +1,25 @@
+# Application example
+
+The repository's five fixture scenarios are the reference application:
+
+1. `01_pure_function` records a slugifier that calls a retired transliterator and exercises replay and F2.
+2. `02_stateful_client` maps a stateful legacy client to a differently shaped session API.
+3. `03_external_boundary` verifies the replacement's interaction with an external boundary, not only its return value.
+4. `04_intentional_divergence` demonstrates that an undeclared change fails and an explicit adapter waiver is reported as `WAIVED`.
+5. `05_formal_negative` changes only a state transition; replay and F3 detect it and F3 emits a distinguishing sequence.
+
+Run the complete application check with:
+
+```bash
+bundle exec rspec spec/acceptance_spec.rb
+```
+
+The acceptance process launches each CLI phase in a fresh Ruby process. This also demonstrates that verification needs the Specification Bundle, adapter, and replacement only; the legacy dependency is loaded solely while recording.
+
+Recording overhead is checked separately against the pure-function fixture:
+
+```bash
+bundle exec rake benchmark_recording
+```
+
+The task uses five runs and fails when median end-to-end overhead exceeds 50%.

data/docs/formal_assurance_limits.md

@@ -0,0 +1,21 @@
+# Formal assurance limits
+
+`bparity` never reports unrestricted program equivalence. Every formal result has one of three verdicts: `no_difference_found`, `difference_found`, or `inconclusive`. It also carries its scope, assumptions, excluded behavior, and any counterexample.
+
+## Levels
+
+- F0 checks only recorded calls. Unrecorded inputs and operation sequences remain unverified.
+- F1 executes declared first-order contracts. A passing result applies only to executed paths.
+- F2 enumerates every value in the reported finite domain. Case, time, or domain-construction limits make the result `inconclusive`; they are never described as exhaustive. When the legacy implementation is unavailable, the claim is limited to the declared postconditions and invariants.
+- F3 compares projected finite-state models. The report includes both model sizes, the learned alphabet, whether exploration completed, and a reminder that this is a model claim rather than a whole-implementation claim.
+- F4 applies only to the declared pure fragment. It requires bounded translation validation before Z3 is consulted. Unsupported Ruby, translation disagreement, solver absence, timeout, or `unknown` invalidates the F4 claim.
+
+## Assumptions
+
+Formal output names its assumptions. H1 freezes the verified class definitions, H3 excludes dynamic evaluation from the verified fragment, H6 models exceptions as outputs, and H7 currently declares single-threaded execution without runtime enforcement. A detected assumption violation invalidates the result.
+
+## Reading a successful result
+
+`no_difference_found` means no counterexample exists in the exact reported scope under the listed assumptions. It says nothing about larger F2 values, unprojected F3 state, operations outside the learned alphabet, unsupported F4 Ruby, concurrency, process effects, timing, GC, or object identity.
+
+Use the five-point assessment alongside the verdict: specification coverage, generated checks, formal reach, mutation constraint strength, and residual risks. Waivers remain visible and require explicit adapter declarations.

data/exe/bparity

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bparity"
+require "bparity/cli"
+
+exit Bparity::CLI.start

data/fixtures/scenarios/01_pure_function/adapter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Bparity.adapter do
+  external "DeadGem::Transliterator" => "Replacement::Transliterator"
+
+  subject "Slugifier" do
+    construct { Replacement::Slugs }
+    operation "#call" do
+      invoke { |subject, args, _kwargs| subject.generate(text: args.fetch(0)) }
+      map_error { |error| { class: error.class.name, message: error.message, cause: error.cause&.class&.name } }
+    end
+  end
+end

data/fixtures/scenarios/01_pure_function/boundary.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+Bparity.boundary do
+  observe "Legacy::Slugifier" do
+    methods :call
+  end
+
+  external "DeadGem::Transliterator" do
+    methods :transliterate
+  end
+
+  driver :rspec, files: "fixtures/scenarios/01_pure_function/spec/**/*_spec.rb"
+  formal do
+    pure_fragment "Legacy::Slugifier#call"
+    bounded_scope size: 3, depth: 2
+  end
+end

data/fixtures/scenarios/01_pure_function/legacy/dead_gem.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module DeadGem
+  class Transliterator
+    def transliterate(value)
+      value.encode("ASCII", invalid: :replace, undef: :replace, replace: "")
+    end
+  end
+end

data/fixtures/scenarios/01_pure_function/legacy/slugifier.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "dead_gem"
+
+module Legacy
+  class Slugifier
+    def initialize
+      @transliterator = DeadGem::Transliterator.new
+    end
+
+    def call(value)
+      raise ArgumentError, "blank" if value.nil? || value.strip.empty?
+
+      @transliterator.transliterate(value).downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|\-\z/, "")
+    end
+  end
+end

data/fixtures/scenarios/01_pure_function/replacement/broken.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Replacement
+  class Transliterator
+    def transliterate(value) = value
+  end
+
+  module Slugs
+    module_function
+
+    def generate(text:)
+      Transliterator.new.transliterate(text).downcase.gsub(/[^a-z0-9]+/, "-")
+    end
+  end
+end

data/fixtures/scenarios/01_pure_function/replacement/good.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Replacement
+  class Transliterator
+    def transliterate(value)
+      value.encode("ASCII", invalid: :replace, undef: :replace, replace: "")
+    end
+  end
+
+  module Slugs
+    module_function
+
+    def generate(text:)
+      raise ArgumentError, "blank" if text.nil? || text.strip.empty?
+
+      Transliterator.new.transliterate(text).downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|\-\z/, "")
+    end
+  end
+end

data/fixtures/scenarios/01_pure_function/spec/slugifier_spec.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rspec"
+require_relative "../legacy/slugifier"
+
+RSpec.describe Legacy::Slugifier do
+  subject(:slugifier) { described_class.new }
+
+  it "converts spaces to hyphens" do
+    expect(slugifier.call("Hello World")).to eq("hello-world")
+  end
+
+  it "removes punctuation at both ends" do
+    expect(slugifier.call("  Hi!  ")).to eq("hi")
+  end
+
+  it "rejects blank input" do
+    expect { slugifier.call("") }.to raise_error(ArgumentError, "blank")
+  end
+end

data/fixtures/scenarios/01_pure_function/test/slugifier_test.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "minitest/test"
+require_relative "../legacy/slugifier"
+
+class SlugifierTest < Minitest::Test
+  def test_normalizes_a_title
+    assert_equal "hello-world", Legacy::Slugifier.new.call("Hello World")
+  end
+end

data/fixtures/scenarios/02_stateful_client/adapter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+Bparity.adapter do
+  subject "Client" do
+    construct { Replacement::Session.new }
+    state { |session| { open: session.phase == :ready } }
+
+    operation("#connect") do
+      invoke { |session, _args, _kwargs| session.start; true }
+    end
+    operation("#fetch") do
+      invoke { |session, _args, _kwargs| session.query }
+      map_error { |error| { class: "Legacy::NotConnectedError", message: error.message } }
+    end
+    operation("#close") do
+      invoke { |session, _args, _kwargs| session.shutdown; nil }
+    end
+  end
+end

data/fixtures/scenarios/02_stateful_client/boundary.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+Bparity.boundary do
+  observe "Legacy::Client" do
+    methods :connect, :fetch, :close
+    state { |client| { open: client.status == :open } }
+  end
+  driver :rspec, files: "fixtures/scenarios/02_stateful_client/spec/**/*_spec.rb"
+  formal { lts_learning :active }
+end

data/fixtures/scenarios/02_stateful_client/legacy/client.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Legacy
+  class NotConnectedError < StandardError; end
+
+  class Client
+    attr_reader :status
+
+    def initialize
+      @status = :closed
+    end
+
+    def connect
+      @status = :open
+      true
+    end
+
+    def fetch
+      raise NotConnectedError, "client is closed" unless status == :open
+
+      :data
+    end
+
+    def close
+      @status = :closed
+      nil
+    end
+  end
+end

data/fixtures/scenarios/02_stateful_client/replacement/broken.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Replacement
+  class Disconnected < StandardError; end
+
+  class Session
+    attr_reader :phase
+
+    def initialize = @phase = :down
+    def start = @phase = :ready
+    def query = :data
+    def shutdown = nil
+  end
+end

data/fixtures/scenarios/02_stateful_client/replacement/good.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Replacement
+  class Disconnected < StandardError; end
+
+  class Session
+    attr_reader :phase
+
+    def initialize
+      @phase = :down
+    end
+
+    def start = @phase = :ready
+
+    def query
+      raise Disconnected, "client is closed" unless phase == :ready
+
+      :data
+    end
+
+    def shutdown = @phase = :down
+  end
+end

data/fixtures/scenarios/02_stateful_client/spec/client_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rspec"
+require_relative "../legacy/client"
+
+RSpec.describe Legacy::Client do
+  subject(:client) { described_class.new }
+
+  it "fetches after connecting" do
+    expect(client.connect).to be(true)
+    expect(client.fetch).to eq(:data)
+  end
+
+  it "rejects fetch while closed" do
+    expect { client.fetch }.to raise_error(Legacy::NotConnectedError)
+  end
+
+  it "closes an open client" do
+    client.connect
+    expect(client.close).to be_nil
+  end
+
+  it "allows repeated connect" do
+    client.connect
+    expect(client.connect).to be(true)
+  end
+
+  it "allows close while already closed" do
+    expect(client.close).to be_nil
+  end
+end

data/fixtures/scenarios/03_external_boundary/adapter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Bparity.adapter do
+  external "RetiredFormatter::Money" => "Replacement::Currency" do
+    map_call(:render) { |call| call.merge("method" => "format") }
+  end
+  subject "Receipt" do
+    construct { Replacement::ReceiptView.new }
+    operation "#print" do
+      invoke { |view, args, _kwargs| view.render(total: args.fetch(0)) }
+    end
+  end
+end

data/fixtures/scenarios/03_external_boundary/boundary.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+Bparity.boundary do
+  observe "Legacy::Receipt" do
+    methods :print
+  end
+  external "RetiredFormatter::Money" do
+    methods :format
+  end
+  driver :rspec, files: "fixtures/scenarios/03_external_boundary/spec/**/*_spec.rb"
+end

data/fixtures/scenarios/03_external_boundary/legacy/dead_formatter.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RetiredFormatter
+  class Money
+    def format(cents) = "$#{cents / 100}"
+  end
+end

data/fixtures/scenarios/03_external_boundary/legacy/receipt.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "dead_formatter"
+
+module Legacy
+  class Receipt
+    def print(cents)
+      "Total: #{RetiredFormatter::Money.new.format(cents)}"
+    end
+  end
+end

data/fixtures/scenarios/03_external_boundary/replacement/broken.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Replacement
+  class Currency
+    def render(cents) = "$#{cents / 100}"
+  end
+
+  class ReceiptView
+    def render(total:) = "Total: $#{total / 100}"
+  end
+end

data/fixtures/scenarios/03_external_boundary/replacement/good.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Replacement
+  class Currency
+    def render(cents) = "$#{cents / 100}"
+  end
+
+  class ReceiptView
+    def render(total:) = "Total: #{Currency.new.render(total)}"
+  end
+end