bundler-spinel 0.0.1.pre

data/lib/bundler/spinel/probe.rb

@@ -0,0 +1,182 @@
+require "open3"
+require "tmpdir"
+require "timeout"
+
+module Bundler
+  module Spinel
+    # Decides a compatibility verdict for an unpacked gem against the current
+    # Spinel engine. Two complementary signals, because Spinel's failure modes
+    # are *not* exit codes:
+    #
+    #   1. COMPILE SIGNAL. Spinel never exits non-zero on unsupported Ruby; it
+    #      emits `warning: ... cannot resolve call to 'X' ... (emitting 0)` and
+    #      degrades the call to a no-op. So we compile the gem's lib entrypoints
+    #      with `spinel -c` and parse stderr. An unresolved-call warning names
+    #      the exact missing feature (`unresolved:eval`), which is what makes the
+    #      verdict forward-compatible — re-probing under a newer engine clears it
+    #      the moment Spinel learns that call.
+    #
+    #   2. STATIC RISK SIGNAL. Some constructs (define_method, instance_eval, a
+    #      bare `send`) are degraded with *no* warning at all, and dead-code
+    #      elimination can hide an unsupported call that's defined-but-uncalled
+    #      in a library. So we also scan the source for known-risky tokens. These
+    #      don't reject on their own (the gem may never hit that path) but they
+    #      downgrade `clean` → `risky`.
+    #
+    # NEITHER signal catches Spinel's *silent miscompiles* (local-var-name
+    # collapse, Int-0-as-nil). Only the `verified` rung — running the gem's own
+    # tests through a Spinel-compiled harness — does. The lock-time gate trusts
+    # `clean`; only a curated whitelist / platform variant trusts `verified`.
+    class Probe
+      # An unsupported *call* — the strongest, most precise signal, and the one
+      # that's forward-compatible (names the exact feature Spinel lacks today).
+      UNRESOLVED_CALL = /cannot resolve call to '([^']+)'/.freeze
+      # A `require "x"` Spinel couldn't follow. Spinel has no load path (plain
+      # require resolves only against <spinel>/lib), so a gem's own split files
+      # and stdlib deps surface here. Informational, NOT a standalone reject:
+      # it's as often a probe limitation as a real incompatibility.
+      UNRESOLVED_REQUIRE = /require "([^"]+)" could not be resolved/.freeze
+      ANALYZE_FAILED = /\b(analyze failed|fatal)\b/i.freeze
+
+      # Spinel's analyze pass can spin for minutes on pathological inputs (no
+      # internal bound). In a wholesale survey that's indistinguishable from a
+      # hang, so we cap each compile and treat an overrun as its own reject
+      # reason — `analyze-timeout` is itself a useful roadmap signal (which gems
+      # blow up the analyzer). Override with SPINEL_COMPILE_TIMEOUT (seconds).
+      COMPILE_TIMEOUT = Integer(ENV.fetch("SPINEL_COMPILE_TIMEOUT", "60"))
+
+      # token => reason. Tokens Spinel cannot honour and may silently no-op.
+      RISK_TOKENS = {
+        /\beval\s*\(/                  => "eval",
+        /\binstance_eval\b/            => "instance_eval",
+        /\b(class|module)_eval\b/      => "class_eval",
+        /\bdefine_method\b/            => "define_method",
+        /\bmethod_missing\b/           => "method_missing",
+        /\brespond_to_missing\?/       => "respond_to_missing",
+        /\bconst_missing\b/            => "const_missing",
+        /\.send\s*\(/                  => "send",
+        /\bpublic_send\b/              => "public_send",
+        /\bObjectSpace\b/              => "objectspace",
+        /\b(TracePoint|set_trace_func)\b/ => "tracepoint",
+        /\bbinding\b/                  => "binding"
+      }.freeze
+
+      def initialize(engine, ledger)
+        @engine = engine
+        @ledger = ledger
+      end
+
+      # gem_name, version, dir(unpacked) -> recorded Ledger::Verdict
+      def probe(gem_name, version, dir)
+        @engine.ensure!
+        sig = compile_signal(dir, gem_name)
+        risks = static_signal(dir)
+        # Unfollowed requires are notes, not rejections — record them so a human
+        # can see when a verdict is entangled with the no-load-path limitation.
+        risks += sig[:requires].map { |r| "needs:#{r}" }
+
+        verdict, reasons =
+          if !sig[:calls].empty?
+            # Genuine unsupported call(s): unambiguous, forward-compatible reject.
+            ["rejected", sig[:calls].map { |s| "unresolved:#{s}" }]
+          elsif sig[:timed_out]
+            # Analyzer ran past the cap — pathological for Spinel, not the gem.
+            ["rejected", ["analyze-timeout"]]
+          elsif sig[:analyze_failed] || !sig[:exit_ok]
+            ["rejected", ["analyze-failed"]]
+          elsif !static_only_risks(risks).empty?
+            ["risky", []]
+          else
+            ["clean", []]
+          end
+
+        @ledger.record(@ledger.build(
+          gem: gem_name, version: version, rev: @engine.rev,
+          verdict: verdict, reasons: reasons.uniq, risks: risks.uniq, probe: "compile+scan"
+        ))
+      end
+
+      private
+
+      # Compile the gem's lib entrypoints as a Spinel program; classify stderr.
+      def compile_signal(dir, gem_name)
+        entries = entrypoints(dir, gem_name)
+        return { calls: [], requires: [], analyze_failed: true, exit_ok: false, timed_out: false } if entries.empty?
+
+        calls = []
+        requires = []
+        analyze_failed = false
+        exit_ok = true
+        timed_out = false
+        Dir.mktmpdir do |tmp|
+          entries.each do |f|
+            out, ok, hit_timeout = run_spinel(f, File.join(tmp, "out.c"))
+            exit_ok &&= ok
+            timed_out ||= hit_timeout
+            analyze_failed ||= out =~ ANALYZE_FAILED ? true : false
+            out.scan(UNRESOLVED_CALL) { |m| calls << m[0] }
+            out.scan(UNRESOLVED_REQUIRE) { |m| requires << m[0] }
+          end
+        end
+        { calls: calls.uniq, requires: requires.uniq,
+          analyze_failed: analyze_failed, exit_ok: exit_ok, timed_out: timed_out }
+      end
+
+      # Run `spinel -c FILE -o OUT_C` with a wall-clock cap. Returns
+      # [combined_output, exit_ok, timed_out]. The compiler is a shell script
+      # that forks spinel_analyze, so on timeout we KILL the whole process group
+      # (pgroup: true makes the child its own group leader) — killing just the
+      # spinel pid would orphan the spinning analyzer.
+      def run_spinel(file, out_c)
+        Open3.popen2e(@engine.bin, "-c", file, "-o", out_c, pgroup: true) do |stdin, out_io, wait_thr|
+          stdin.close
+          output = +""
+          reader = Thread.new { output << out_io.read }
+          begin
+            Timeout.timeout(COMPILE_TIMEOUT) { wait_thr.value }
+            reader.join
+            [output, wait_thr.value.success?, false]
+          rescue Timeout::Error
+            begin
+              Process.kill("-KILL", wait_thr.pid)
+            rescue StandardError
+              nil
+            end
+            reader.join
+            [output, false, true]
+          end
+        end
+      end
+
+      # Risks from the static source scan (exclude the `needs:` require notes).
+      def static_only_risks(risks)
+        risks.reject { |r| r.start_with?("needs:") }
+      end
+
+      # The gem's conventional require targets: lib/<name>.rb, else top-level
+      # lib/*.rb. Spinel inlines their require_relatives, so compiling the entry
+      # pulls in the whole tree.
+      def entrypoints(dir, gem_name)
+        lib = File.join(dir, "lib")
+        return [] unless File.directory?(lib)
+
+        main = File.join(lib, "#{gem_name}.rb")
+        return [main] if File.exist?(main)
+
+        Dir[File.join(lib, "*.rb")]
+      end
+
+      def static_signal(dir)
+        risks = []
+        # C-extension gems can't be compiled by Spinel at all.
+        risks << "c-extension" if Dir[File.join(dir, "ext", "**", "*.{c,cpp,cc,h}")].any?
+
+        Dir[File.join(dir, "lib", "**", "*.rb")].each do |f|
+          src = File.read(f)
+          RISK_TOKENS.each { |re, reason| risks << reason if src =~ re }
+        end
+        risks.uniq
+      end
+    end
+  end
+end

data/lib/bundler/spinel/proxy.rb

@@ -0,0 +1,154 @@
+require "webrick"
+require "digest"
+require "json"
+require "rubygems/package"
+require "time"
+
+module Bundler
+  module Spinel
+    # A curated RubyGems *source* (Compact Index protocol) that serves only
+    # vetted gems. Point a Gemfile at it:
+    #
+    #     source "http://localhost:9292"
+    #     gem "cleangem"
+    #
+    # and `bundle lock` resolves *only against vetted gems*. A gem that isn't
+    # served (no acceptable verdict for the pinned engine rev) becomes a plain
+    # "could not find compatible versions" resolution failure — no plugin, no
+    # engine-directive trick. The whitelist is not a file: it's the acceptable
+    # subset of the ledger at this rev, plus a local store of .gem artifacts we
+    # built/verified ourselves.
+    #
+    # Empirically the third-party rubygems ecosystem is ~all-rejected today, so
+    # the load-bearing mode is `:store` — a directory of our own Spinel-vetted
+    # .gem files. (Filtered read-through of upstream is a documented extension.)
+    #
+    # NOTE: this CRuby/WEBrick implementation is the MVP that proves Bundler
+    # resolves against it. The dogfood target is to serve the same endpoints
+    # from a Spinel-compiled Tep app — see ARCHITECTURE.md §"Dogfooding".
+    class Proxy
+      # store: dir of vetted *.gem files (the curated artifacts).
+      def initialize(store:, ledger: Ledger.new, engine: Engine.new,
+                     min_verdict: :verified)
+        @store = store
+        @ledger = ledger
+        @engine = engine
+        @min_verdict = min_verdict
+      end
+
+      # name => { version => spec } for every vetted gem in the store.
+      def catalog
+        @catalog ||= Dir[File.join(@store, "*.gem")].each_with_object({}) do |path, acc|
+          spec = Gem::Package.new(path).spec
+          next unless acceptable?(spec.name, spec.version.to_s)
+
+          (acc[spec.name] ||= {})[spec.version.to_s] = { spec: spec, path: path }
+        end
+      end
+
+      # Write the curated source as a *static* Compact Index tree:
+      #   out/names  out/versions  out/info/<gem>  out/gems/<file>.gem
+      # All digest/JSON happens here, offline, in CRuby. The result is plain
+      # text + file bytes — so the dogfood server (Tep/Spinel, which has neither
+      # digest nor JSON — probed 2026-05-26) only has to serve static files.
+      def write_static(out)
+        require "fileutils"
+        FileUtils.mkdir_p(File.join(out, "info"))
+        FileUtils.mkdir_p(File.join(out, "gems"))
+        File.write(File.join(out, "names"), names_body)
+        File.write(File.join(out, "versions"), versions_body)
+        catalog.each_key { |name| File.write(File.join(out, "info", name), info_body(name)) }
+        catalog.values.flat_map(&:values).each do |e|
+          FileUtils.cp(e[:path], File.join(out, "gems", File.basename(e[:path])))
+        end
+        out
+      end
+
+      def serve(port: 9292, quiet: true)
+        server = WEBrick::HTTPServer.new(
+          Port: port,
+          Logger: WEBrick::Log.new(quiet ? File::NULL : $stderr),
+          AccessLog: []
+        )
+        mount(server)
+        trap("INT") { server.shutdown }
+        warn "[spinel-proxy] curated source on http://localhost:#{port} " \
+             "(#{catalog.size} gems, min=#{@min_verdict}, rev=#{@engine.rev})"
+        server.start
+      end
+
+      private
+
+      def acceptable?(name, version)
+        v = @ledger.lookup(name, version, @engine.rev)
+        return false unless v
+
+        case @min_verdict
+        when :verified then v.verified?
+        when :clean    then v.verified? || v.clean?
+        when :risky    then !v.rejected?
+        else false
+        end
+      end
+
+      def mount(server)
+        server.mount_proc("/names") { |_, res| text(res, names_body) }
+        server.mount_proc("/versions") { |_, res| text(res, versions_body) }
+        server.mount_proc("/info") do |req, res|
+          gem = req.path.sub(%r{\A/info/}, "")
+          info = info_body(gem)
+          info ? text(res, info) : (res.status = 404)
+        end
+        server.mount_proc("/gems") do |req, res|
+          file = File.basename(req.path)
+          entry = catalog.values.flat_map(&:values).find { |e| File.basename(e[:path]) == file }
+          if entry
+            res["Content-Type"] = "application/octet-stream"
+            res.body = File.binread(entry[:path])
+          else
+            res.status = 404
+          end
+        end
+      end
+
+      # --- Compact Index bodies ---------------------------------------------
+
+      def names_body
+        "---\n" + catalog.keys.sort.join("\n") + "\n"
+      end
+
+      def versions_body
+        out = +"created_at: #{Time.now.utc.iso8601}\n---\n"
+        catalog.sort.each do |name, versions|
+          vs = versions.keys.sort.join(",")
+          out << "#{name} #{vs} #{::Digest::MD5.hexdigest(info_body(name))}\n"
+        end
+        out
+      end
+
+      def info_body(name)
+        gem = catalog[name]
+        return nil unless gem
+
+        out = +"---\n"
+        gem.sort.each do |version, entry|
+          spec = entry[:spec]
+          deps = spec.runtime_dependencies.map do |d|
+            "#{d.name}:#{d.requirement.requirements.map { |op, v| "#{op} #{v}" }.join('&')}"
+          end.join(",")
+          sha = ::Digest::SHA256.hexdigest(File.binread(entry[:path]))
+          ruby = spec.required_ruby_version.to_s
+          out << "#{version} #{deps}|checksum:#{sha}"
+          out << ",ruby:#{ruby}" unless ruby.empty? || ruby == ">= 0"
+          out << "\n"
+        end
+        out
+      end
+
+      def text(res, body)
+        res["Content-Type"] = "text/plain"
+        res.body = body
+      end
+    end
+  end
+end

data/lib/bundler/spinel/survey.rb

@@ -0,0 +1,130 @@
+require "open3"
+require "set"
+
+module Bundler
+  module Spinel
+    # Wholesale review: probe a large list of gems and aggregate the results.
+    # The point isn't a pass/fail — it's the *histogram of rejection reasons*,
+    # which directly prioritises what Spinel should support next (see RFC asks).
+    #
+    # Embarrassingly parallel: each gem is an independent fetch + compile, both
+    # subprocess-bound (Open3 releases the GVL), so a thread pool scales across
+    # cores. Verdicts are cached in the ledger, so a survey is resumable and
+    # re-runnable; only ledger writes are serialised.
+    class Survey
+      def initialize(engine: Engine.new, ledger: Ledger.new, jobs: 4)
+        @engine = engine
+        @ledger = ledger
+        @jobs = jobs
+        @fetcher = GemFetcher.new
+        @probe = Probe.new(@engine, @ledger)
+        @mutex = Mutex.new
+      end
+
+      # names: Array<String>. Probes each at its latest version (ledger-cached).
+      # Returns the Array<Ledger::Verdict> for the surveyed set.
+      def run(names, progress: $stderr)
+        @engine.ensure!
+        queue = Queue.new
+        names.each { |n| queue << n }
+        results = []
+        done = 0
+        total = names.size
+
+        workers = Array.new([@jobs, total].min) do
+          Thread.new do
+            until queue.empty?
+              name = (queue.pop(true) rescue break)
+              v = probe_one(name)
+              @mutex.synchronize do
+                results << v if v
+                done += 1
+                progress&.print("\r[survey] #{done}/#{total}  #{name.ljust(30)}")
+              end
+            end
+          end
+        end
+        workers.each(&:join)
+        progress&.puts("\r[survey] #{done}/#{total} done#{' ' * 30}")
+        results.compact
+      end
+
+      # Aggregate a markdown report from ledger verdicts for `names` at this rev.
+      #
+      # Reads straight from the ledger — no network. The just-run probes already
+      # recorded a verdict (with its resolved version) per surveyed gem at this
+      # rev, so re-resolving each gem's latest version online would only repeat
+      # work and serialise a 1k-name survey behind 1k `gem list -r` calls. We
+      # take the *last* current-rev entry per gem: append-only means a re-probe
+      # supersedes, and the survey probes a gem at one (latest) version per run.
+      def report(names)
+        wanted = names.to_set
+        rev = @engine.rev
+        latest = {}
+        @ledger.each do |v|
+          latest[v.gem] = v if v.rev == rev && wanted.include?(v.gem)
+        end
+        verdicts = latest.values
+        counts = Hash.new(0)
+        reasons = Hash.new(0)
+        verdicts.each do |v|
+          counts[v.verdict] += 1
+          (v.reasons + v.risks).each { |r| reasons[normalize(r)] += 1 }
+        end
+        render(verdicts.size, counts, reasons)
+      end
+
+      private
+
+      def probe_one(name)
+        version = latest_version(name) or return nil
+        cached = @ledger.lookup(name, version, @engine.rev)
+        return cached if cached
+
+        dir = @fetcher.fetch(name, version)
+        # Probe runs spinel (CPU-bound, GVL released) — this is the whole point
+        # of the thread pool, so it must NOT hold @mutex. The only shared write
+        # is the ledger append, which Ledger#record serialises internally.
+        @probe.probe(name, version, dir)
+      rescue StandardError => e
+        @mutex.synchronize { warn "\n[survey] #{name}: #{e.message}" }
+        nil
+      end
+
+      def latest_version(name)
+        out, st = Open3.capture2e("gem", "list", "-r", "-e", name)
+        return nil unless st.success?
+
+        out[/#{Regexp.escape(name)} \(([^,)]+)/, 1]
+      end
+
+      # Collapse `unresolved:foo`/`risk:bar`/`needs:baz` into ranked buckets.
+      def normalize(reason)
+        reason
+      end
+
+      def render(n, counts, reasons)
+        ok = (counts["clean"] + counts["verified"])
+        lines = []
+        lines << "# Spinel gem-compatibility survey"
+        lines << ""
+        lines << "- engine rev: `#{@engine.rev}`"
+        lines << "- gems surveyed: **#{n}**"
+        lines << "- compatible (clean+verified): **#{ok}** (#{pct(ok, n)})  ·  " \
+                 "risky: #{counts['risky']}  ·  rejected: #{counts['rejected']}"
+        lines << ""
+        lines << "## Top blockers (what to teach Spinel next)"
+        lines << ""
+        lines << "| count | reason |"
+        lines << "|---|---|"
+        reasons.sort_by { |_, c| -c }.first(25).each { |r, c| lines << "| #{c} | `#{r}` |" }
+        lines << ""
+        lines.join("\n")
+      end
+
+      def pct(a, b)
+        b.zero? ? "0%" : "#{(100.0 * a / b).round(1)}%"
+      end
+    end
+  end
+end

data/lib/bundler/spinel/vendorer.rb

@@ -0,0 +1,90 @@
+require "bundler"
+require "bundler/lockfile_parser"
+require "fileutils"
+
+module Bundler
+  module Spinel
+    # "Make it work" — the plugin's primary job. Spinel has no load path
+    # (plain `require "x"` resolves only against <spinel>/lib) and inlines
+    # `require_relative`. So to actually *use* a resolved dependency in a Spinel
+    # build, its source has to be placed somewhere Spinel will follow, with the
+    # require wiring generated. This is the reusable form of what projects do by
+    # hand today (e.g. Toy's build_tep_app.sh concatenation, Roundhouse
+    # vendoring part of Tep).
+    #
+    # Given a Gemfile.lock, vendor each gem's `lib/` into `<into>/<name>/` and
+    # emit `<into>/deps.rb` — a manifest of `require_relative`s in lock order. A
+    # Spinel program then just does `require_relative "vendor/spinel/deps"`.
+    #
+    # Gating is layered on but advisory here: placement and compatibility are
+    # different jobs. `vendor` warns on non-compatible gems (so the experience
+    # is nicer) but still places them; `check` is the hard gate.
+    class Vendorer
+      def initialize(engine: Engine.new, ledger: Ledger.new)
+        @engine = engine
+        @ledger = ledger
+        @fetcher = GemFetcher.new
+      end
+
+      def vendor(lockfile = "Gemfile.lock", into: "vendor/spinel", warn_incompatible: true)
+        parsed = Bundler::LockfileParser.new(File.read(lockfile))
+        into = File.expand_path(into)
+        FileUtils.mkdir_p(into)
+
+        manifest = []
+        parsed.specs.each do |spec|
+          name = spec.name
+          version = spec.version.to_s
+          src = @fetcher.fetch(name, version)
+          dest = File.join(into, name)
+          place(src, dest)
+          manifest << require_target(name, dest)
+          note_compat(name, version) if warn_incompatible
+        end
+
+        write_manifest(into, manifest)
+        { into: into, count: manifest.size }
+      end
+
+      private
+
+      def place(src, dest)
+        FileUtils.rm_rf(dest)
+        FileUtils.mkdir_p(dest)
+        %w[lib].each do |sub|
+          s = File.join(src, sub)
+          FileUtils.cp_r(s, dest) if File.directory?(s)
+        end
+      end
+
+      # The relative path a Spinel program require_relatives. Spinel inlines it
+      # and follows the gem's own require_relatives from there.
+      def require_target(name, dest)
+        base = File.basename(dest)
+        main = File.join(dest, "lib", "#{name}.rb")
+        if File.exist?(main)
+          "#{base}/lib/#{name}"
+        else
+          first = Dir[File.join(dest, "lib", "*.rb")].sort.first
+          first ? "#{base}/lib/#{File.basename(first, '.rb')}" : nil
+        end
+      end
+
+      def note_compat(name, version)
+        v = @ledger.lookup(name, version, @engine.rev)
+        return if v&.clean? || v&.verified?
+
+        label = v ? v.verdict : "unprobed"
+        warn "[vendor] #{name} #{version}: #{label} for #{@engine.rev} " \
+             "— may not compile (run `spinel-compat check`)"
+      end
+
+      def write_manifest(into, targets)
+        body = +"# Generated by bundler-spinel. require_relative this from a\n" \
+                "# Spinel program to pull in vendored dependencies (lock order).\n"
+        targets.compact.each { |t| body << %{require_relative "#{t}"\n} }
+        File.write(File.join(into, "deps.rb"), body)
+      end
+    end
+  end
+end

data/lib/bundler/spinel/verifier.rb

@@ -0,0 +1,100 @@
+require "open3"
+
+module Bundler
+  module Spinel
+    # The `verified` rung: differential testing. Runs a smoke program that
+    # exercises the gem once under CRuby and once compiled by Spinel, and
+    # compares stdout. This is the *only* signal that catches Spinel's silent
+    # miscompiles (local-var-name collapse, Int-0-as-nil) — they emit no warning
+    # and exit 0, so the cheap probe can't see them, but a differential run does:
+    # CRuby and the miscompiled binary diverge.
+    #
+    #   match    -> verified  (CRuby and Spinel agree on this smoke)
+    #   mismatch -> rejected  (reason: miscompile, with a short diff)
+    #   no build -> rejected  (reason: build-error / run-error)
+    #
+    # The smoke is the unit of trust. A require-only default smoke catches
+    # load-time divergence; pass `--smoke FILE` (a snippet that drives the gem's
+    # API and prints deterministic output) to verify behaviour. Verification is
+    # only as good as the smoke — which is why it's opt-in and human-supplied.
+    class Verifier
+      HARNESS = "__spinel_verify.rb".freeze
+
+      def initialize(engine, ledger)
+        @engine = engine
+        @ledger = ledger
+      end
+
+      def verify(gem_name, version, dir, smoke: nil)
+        @engine.ensure!
+        harness = File.join(dir, HARNESS)
+        File.write(harness, harness_source(gem_name, dir, smoke))
+
+        ruby_out, _, ruby_ok = run_ruby(harness)
+        spin_out, spin_err, spin_ok = run_spinel(harness)
+
+        verdict, reasons = classify(ruby_ok, spin_ok, ruby_out, spin_out, spin_err)
+        @ledger.record(@ledger.build(
+          gem: gem_name, version: version, rev: @engine.rev,
+          verdict: verdict, reasons: reasons, probe: "verify"
+        ))
+      ensure
+        File.delete(harness) if harness && File.exist?(harness)
+      end
+
+      private
+
+      def classify(ruby_ok, spin_ok, ruby_out, spin_out, spin_err)
+        unless ruby_ok
+          # Smoke is broken under plain Ruby — can't draw a conclusion.
+          return ["risky", ["smoke-error:cruby"]]
+        end
+        return ["rejected", ["build-or-run-error"] + spin_err.lines.grep(/error|fatal/i).first(2).map(&:strip)] unless spin_ok
+
+        if ruby_out == spin_out
+          ["verified", []]
+        else
+          ["rejected", ["miscompile", "diff:#{first_diff(ruby_out, spin_out)}"]]
+        end
+      end
+
+      # require_relative resolves against the harness's own dir (the gem root),
+      # and Spinel inlines it — so this follows require_relative-split gems
+      # natively. (Plain `require "gem/part"` gems still under-resolve; that's the
+      # documented load-path limitation.)
+      def harness_source(gem_name, dir, smoke)
+        entry = File.exist?(File.join(dir, "lib", "#{gem_name}.rb")) ? "lib/#{gem_name}" : nil
+        body = smoke ? File.read(smoke) : %{puts "spinel-verify: loaded #{gem_name}"}
+        src = +""
+        src << %{require_relative "#{entry}"\n} if entry
+        src << body << "\n"
+        src
+      end
+
+      def run_ruby(file)
+        out, err, st = Open3.capture3("ruby", file)
+        [out, err, st.success?]
+      end
+
+      def run_spinel(file)
+        bin = file.sub(/\.rb$/, ".bin")
+        _, cerr, cst = Open3.capture3(@engine.bin, file, "-o", bin)
+        return ["", cerr, false] unless cst.success? && File.executable?(bin)
+
+        out, err, st = Open3.capture3(bin)
+        [out, (cerr + err), st.success?]
+      ensure
+        File.delete(bin) if bin && File.exist?(bin)
+      end
+
+      def first_diff(a, b)
+        al = a.lines
+        bl = b.lines
+        al.each_index do |i|
+          return "L#{i + 1} cruby=#{al[i].inspect} spinel=#{bl[i].inspect}" if al[i] != bl[i]
+        end
+        "len #{al.size}!=#{bl.size}"
+      end
+    end
+  end
+end

data/lib/bundler/spinel/version.rb

@@ -0,0 +1,7 @@
+module Bundler
+  module Spinel
+    # Pre-release: the `.pre` suffix makes this a RubyGems prerelease, so
+    # `gem install` / `bundle add` skip it unless asked with `--pre`.
+    VERSION = "0.0.1.pre"
+  end
+end

data/lib/bundler/spinel.rb

@@ -0,0 +1,15 @@
+module Bundler
+  module Spinel
+    class Error < StandardError; end
+  end
+end
+
+require_relative "spinel/version"
+require_relative "spinel/engine"
+require_relative "spinel/ledger"
+require_relative "spinel/gem_fetcher"
+require_relative "spinel/probe"
+require_relative "spinel/verifier"
+require_relative "spinel/vendorer"
+require_relative "spinel/survey"
+require_relative "spinel/checker"

data/plugins.rb

@@ -0,0 +1,6 @@
+# Bundler plugin entry point. Read by Bundler when this gem is installed as a
+# plugin (`bundle plugin install bundler-spinel`). Registers the gate commands.
+require_relative "lib/bundler/spinel/command"
+
+Bundler::Plugin::API.command("spinel-lock", Bundler::Spinel::Command)
+Bundler::Plugin::API.command("spinel-check", Bundler::Spinel::Command)