spinel_native 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 341a37c7333aabb9a5ca73e8bfc1dfeea3949c9629fdc809c81c34ee83369c43
+  data.tar.gz: d5a28eafd41ffe17e21c5fee4af88807f1e7103209a163a8e78a88e23d25a6f7
+SHA512:
+  metadata.gz: 79161e43d39d1d61384f14675c2b732c21c2b4d34f7ca0e38760ce929c339b04e51b0818d306c83bb74698e03b7bd447c42f1e4f257381a6e549090c5ac2b95c
+  data.tar.gz: cf96d9b21b54cb6a1adc910caceeced6aa8f14c766b2a70624ec9b13b1775918ba20e1551f154480ae066ba5ebc6ead092bba4d0bdd3d2ebfcffc7492cad9306

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- `native def` marks a method; its first call samples the argument types,
+  compiles the kernel with `spinel --ext cruby`, and rebinds the method.
+- `native "(T, ...) -> R"` declares the types instead; `Spinel::Native.compile!`
+  builds at boot.
+- `SPINEL_NATIVE=off|verify|strict` modes; the Ruby definition stays as
+  fallback and oracle.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Hasiński
+
+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,115 @@
+# spinel_native
+
+Compile a single Ruby method to native code with the
+[Spinel](https://github.com/matz/spinel) AOT compiler, from inside a running
+CRuby program. Mark the hot method, keep everything else on CRuby.
+
+```ruby
+require "spinel/native"
+
+module Physics
+  extend Spinel::Native
+
+  native def dot(a, b)
+    s = 0.0
+    i = 0
+    while i < a.length
+      s += a[i] * b[i]
+      i += 1
+    end
+    s
+  end
+end
+
+Physics.dot(xs, ys)   # first call: compile + rebind (about 1s, cached on disk)
+Physics.dot(xs, ys)   # native
+```
+
+That is the whole interface: `native def`. The method stays plain Ruby until
+its first call. The argument types of that call seed Spinel's whole-program
+type inference, the kernel is compiled into a CRuby extension, and the method
+is rebound to the compiled entry. If anything goes wrong the Ruby definition
+stays in place and a warning says why.
+
+## Interface
+
+- `native def name(args)` marks a method. In a module it is also callable as
+  `Mod.name` (it can never use `self`, so the distinction is moot). `native
+  def self.name` works too, and so do instance methods of a class.
+- `native "(Array[Float], Integer) -> Float"` on the line before a `def`
+  declares the parameter types instead of sampling them. The return type is
+  inferred by Spinel and only checked for shape.
+- `Spinel::Native.compile!(Mod)` compiles every declared entry now, at boot,
+  so compile errors surface before the first request.
+- `SPINEL_NATIVE=off` runs the Ruby definitions only. `verify` runs both paths
+  on every call and raises `Spinel::Native::Mismatch` when they disagree (the
+  Ruby definition is the oracle). `strict` turns the silent fallback into a
+  raised `CompileError` / `TypeError`. Same knob: `Spinel::Native.mode = :verify`.
+- `SPINEL=/path/to/spinel` names the compiler (otherwise `spinel` on PATH),
+  `SPINEL_NATIVE_CACHE` the build cache (default `~/.cache/spinel-native`),
+  `SPINEL_NATIVE_VERBOSE=1` prints the commands and timings.
+
+## Rules for a native method
+
+- Parameters and the return value cross the boundary **by copy**. Supported
+  types: `Integer` (64-bit), `Float`, `String`, `bool`, and `Array` of those.
+  Mutating a parameter is refused at compile time; return the result instead.
+- The body must not touch `self`, instance variables, or anything outside the
+  module. Native methods may call each other; everything reachable must be
+  `native` too, because the kernel is exactly the set of marked methods.
+- A `raise` inside the kernel arrives in Ruby as the same exception class and
+  message. Integer overflow raises `RangeError` where CRuby would promote to a
+  Bignum, and a Bignum argument is a `RangeError` at the boundary.
+- The kernel runs without the GVL, one call at a time per module.
+
+## How it works
+
+1. `Method#source_location` plus Prism pull the `def` back out of its file.
+2. The marked methods become `def self.` methods of a synthetic module, with
+   a `if __FILE__ == $0` driver that calls each exported entry once with a
+   literal of its parameter types (`[0.0]`, `0`, `"x"`). Spinel infers from
+   that call site and never runs the driver.
+3. `spinel kernel.rb -c --ext cruby --ext-init ... --ext-entry Mod.a,Mod.b`
+   emits the kernel C, a header contract, and a CRuby shim that converts
+   `VALUE`s, releases the GVL, and re-raises kernel exceptions.
+4. The C compiler from `RbConfig` links those with the Spinel runtime into a
+   shared object, keyed in the cache by the kernel source, the entries, the
+   Spinel binary and the Ruby ABI. The runtime itself is compiled once per
+   Spinel build with `-fPIC` (a couple of seconds), since the archive Spinel
+   ships is meant for executables. On Linux the object exports only its
+   `Init_*` symbol and binds the rest internally, because CRuby loads
+   extensions `RTLD_GLOBAL` and two kernels would otherwise share one
+   `sp_raise_cls`. `require` loads the object; the method is redefined to
+   forward to the extension.
+
+## Install
+
+Spinel is not on RubyGems; build it from source once and point the gem at it:
+
+```sh
+git clone https://github.com/matz/spinel && cd spinel && make deps && make
+export SPINEL=$PWD/bin/spinel
+gem install spinel_native   # or: gem "spinel_native" in the Gemfile
+```
+
+## Running the example
+
+```sh
+git clone https://github.com/khasinski/spinel_native && cd spinel_native
+ruby -I lib examples/demo.rb
+bundle exec rake test
+```
+
+On an M-series Mac with CRuby master the demo prints roughly:
+
+```
+dot(2M floats)       ruby 0.136s  native 0.016s  x8.4
+mandel_row(4000)     ruby 0.517s  native 0.013s  x39.6
+count_primes(5M)     ruby 0.645s  native 0.072s  x9.0
+```
+
+## Status
+
+A proof of concept. Not yet done: shipping the compiled kernel inside a gem
+(Spinel's own `spin ext` covers that path), zero-copy numeric buffers, keyword
+and block parameters, Hash parameters, and `--int-overflow=promote` parity.

data/examples/demo.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# ruby -I lib examples/demo.rb
+require "benchmark"
+require "spinel/native"
+
+module Physics
+  extend Spinel::Native
+
+  # Types are sampled from the first call.
+  native def dot(a, b)
+    s = 0.0
+    i = 0
+    while i < a.length
+      s += a[i] * b[i]
+      i += 1
+    end
+    s
+  end
+
+  # Or declared, so the kernel can be compiled before the first call.
+  native "(Float, Float, Integer) -> Integer"
+  def mandel(cr, ci, limit)
+    zr = 0.0
+    zi = 0.0
+    n = 0
+    while n < limit && zr * zr + zi * zi < 4.0
+      t = zr * zr - zi * zi + cr
+      zi = 2.0 * zr * zi + ci
+      zr = t
+      n += 1
+    end
+    n
+  end
+
+  # Native methods may call each other; everything reachable must be native too.
+  native def mandel_row(ci, width, limit)
+    out = []
+    x = 0
+    while x < width
+      out << mandel(-2.0 + 3.0 * x / width, ci, limit)
+      x += 1
+    end
+    out
+  end
+end
+
+class Sieve
+  extend Spinel::Native
+
+  # Instance methods work too; they must not touch ivars or self.
+  native def count_primes(n)
+    flags = Array.new(n + 1, true)
+    count = 0
+    i = 2
+    while i <= n
+      if flags[i]
+        count += 1
+        j = i * i
+        while j <= n
+          flags[j] = false
+          j += i
+        end
+      end
+      i += 1
+    end
+    count
+  end
+end
+
+a = Array.new(2_000_000) { |i| i * 0.5 }
+
+Spinel::Native.mode = :off
+t_ruby = Benchmark.realtime { 3.times { Physics.dot(a, a) } } / 3
+p_ruby = Benchmark.realtime { Physics.mandel_row(0.1, 4000, 2000) }
+s_ruby = Benchmark.realtime { Sieve.new.count_primes(5_000_000) }
+
+Spinel::Native.mode = :on
+Physics.dot(a, a) # first call compiles (or loads from cache)
+Physics.mandel_row(0.1, 4, 10)
+Sieve.new.count_primes(10)
+t_nat = Benchmark.realtime { 3.times { Physics.dot(a, a) } } / 3
+p_nat = Benchmark.realtime { Physics.mandel_row(0.1, 4000, 2000) }
+s_nat = Benchmark.realtime { Sieve.new.count_primes(5_000_000) }
+
+puts "dot(2M floats)       ruby %.3fs  native %.3fs  x%.1f" % [t_ruby, t_nat, t_ruby / t_nat]
+puts "mandel_row(4000)     ruby %.3fs  native %.3fs  x%.1f" % [p_ruby, p_nat, p_ruby / p_nat]
+puts "count_primes(5M)     ruby %.3fs  native %.3fs  x%.1f" % [s_ruby, s_nat, s_ruby / s_nat]
+Spinel::Native.mode = :off
+ruby_dot = Physics.dot(a, a)
+Spinel::Native.mode = :on
+puts "results agree: #{Physics.dot(a, a) == ruby_dot && Sieve.new.count_primes(100) == 25 && Physics.mandel(0.0, 0.0, 50) == 50}"

data/lib/spinel/native/builder.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "etc"
+require "open3"
+require "shellwords"
+
+module Spinel
+  module Native
+    # Turns a kernel (a module of `def self.` methods plus a witness driver)
+    # into a loaded CRuby extension:
+    #
+    #   spinel kernel.rb -c --ext cruby --ext-init ... --ext-entry Mod.a,Mod.b
+    #   cc -bundle kernel.c kernel_ext.c libspinel_rt.a
+    #   require kernel.bundle
+    #
+    # Builds are cached under SPINEL_NATIVE_CACHE (default ~/.cache/spinel-native)
+    # keyed by the kernel source, the exported entries, the spinel binary and
+    # the Ruby ABI, so a repeated run of the same program compiles nothing.
+    class Builder
+      Result = Struct.new(:module_name, :bundle, :dir, :cached, :seconds)
+
+      class << self
+        def spinel_bin
+          @spinel_bin ||= begin
+            env = ENV["SPINEL"].to_s
+            found = env.empty? ? which("spinel") : env
+            raise Error, "spinel compiler not found: set SPINEL=/path/to/spinel or put it on PATH" if found.to_s.empty?
+            File.realpath(found)
+          end
+        end
+
+        # The runtime headers and archive ship beside the compiler: <root>/bin/spinel, <root>/lib.
+        def runtime_dir
+          @runtime_dir ||= begin
+            env = ENV["SPINEL_HDR_DIR"].to_s
+            candidates = [env, File.expand_path("../lib", File.dirname(spinel_bin)),
+                          File.expand_path("lib", File.dirname(spinel_bin))]
+            candidates.find { |d| !d.empty? && File.exist?(File.join(d, "spinel_rt.h")) } or
+              raise Error, "spinel runtime (spinel_rt.h) not found next to #{spinel_bin}; set SPINEL_HDR_DIR"
+          end
+        end
+
+        def cache_dir
+          ENV["SPINEL_NATIVE_CACHE"] || File.join(ENV["XDG_CACHE_HOME"] || File.join(Dir.home, ".cache"), "spinel-native")
+        end
+
+        def which(cmd)
+          ENV["PATH"].split(File::PATH_SEPARATOR).each do |d|
+            p = File.join(d, cmd)
+            return p if File.executable?(p) && !File.directory?(p)
+          end
+          nil
+        end
+
+        def fingerprint
+          @fingerprint ||= begin
+            st = File.stat(spinel_bin)
+            Digest::SHA256.hexdigest([st.size, st.mtime.to_i, RUBY_VERSION, RUBY_PLATFORM, RbConfig::CONFIG["CC"]].join("|"))
+          end
+        end
+
+        def cc
+          Shellwords.split(RbConfig::CONFIG["CC"] || "cc")
+        end
+
+        # The runtime archive Spinel ships is built for executables, not
+        # position-independent code, so a shared object cannot link it on
+        # Linux. Compile the runtime sources once per Spinel build into a
+        # -fPIC archive in the cache; the sources sit beside the headers.
+        def runtime_archive
+          @runtime_archive ||= begin
+            dir = File.join(cache_dir, "runtime_#{fingerprint[0, 12]}")
+            archive = File.join(dir, "libspinel_rt_pic.a")
+            build_runtime_archive(dir, archive) unless File.exist?(archive)
+            archive
+          end
+        end
+
+        def build_runtime_archive(dir, archive)
+          t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          FileUtils.mkdir_p(dir)
+          sources = Dir[File.join(runtime_dir, "*.c")] + Dir[File.join(runtime_dir, "regexp", "*.c")]
+          raise Error, "no runtime sources in #{runtime_dir}" if sources.empty?
+          jobs = Etc.respond_to?(:nprocessors) ? Etc.nprocessors : 4
+          queue = Queue.new
+          sources.each { |src| queue << src }
+          failures = Queue.new
+          objects = sources.map { |src| File.join(dir, File.basename(src, ".c") + ".o") }
+          Array.new(jobs) do
+            Thread.new do
+              while (src = queue.pop(true) rescue nil)
+                obj = File.join(dir, File.basename(src, ".c") + ".o")
+                cmd = [*cc, "-c", "-fPIC", "-O2", "-w", "-ffunction-sections", "-fdata-sections",
+                       "-I#{runtime_dir}", "-I#{File.join(runtime_dir, 'regexp')}", src, "-o", obj]
+                out, status = Open3.capture2e(*cmd)
+                failures << "#{cmd.join(' ')}\n#{out}" unless status.success?
+              end
+            end
+          end.each(&:join)
+          raise CompileError, "compiling the Spinel runtime failed:\n#{failures.pop}" unless failures.empty?
+          out, status = Open3.capture2e("ar", "rcs", archive, *objects)
+          raise CompileError, "ar failed:\n#{out}" unless status.success?
+          FileUtils.rm_f(objects)
+          Native.log("runtime compiled with -fPIC in #{(Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0).round(2)}s (#{archive})")
+        end
+      end
+
+      # +body+ is the module body (the `def self.` methods), +entries+ maps the
+      # exported names to their parameter types.
+      def initialize(body, entries)
+        @body = body
+        @entries = entries
+        digest = Digest::SHA256.hexdigest([self.class.fingerprint, body, entries.inspect].join("\0"))[0, 12]
+        @module_name = "SpinelKernel#{digest}"
+        @feature = "spinel_kernel_#{digest}"
+        @dir = File.join(self.class.cache_dir, @feature)
+      end
+
+      attr_reader :module_name, :feature, :dir
+
+      def kernel_source
+        witness = @entries.map do |name, types|
+          "  #{@module_name}.#{name}(#{types.map { |t| Types.witness(t) }.join(', ')})"
+        end
+        <<~RUBY
+          module #{@module_name}
+          #{@body.gsub(/^/, "  ")}
+          end
+
+          if __FILE__ == $0
+          #{witness.join("\n")}
+          end
+        RUBY
+      end
+
+      def bundle
+        File.join(@dir, "#{@feature}.#{RbConfig::CONFIG['DLEXT']}")
+      end
+
+      def build
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        cached = File.exist?(bundle)
+        unless cached
+          FileUtils.mkdir_p(@dir)
+          File.write(File.join(@dir, "kernel.rb"), kernel_source)
+          run_spinel
+          run_cc
+        end
+        require bundle
+        Result.new(@module_name, bundle, @dir, cached, Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0)
+      end
+
+      private
+
+      def run_spinel
+        entry_list = @entries.keys.map { |n| "#{@module_name}.#{n}" }.join(",")
+        cmd = [self.class.spinel_bin, File.join(@dir, "kernel.rb"), "-c", "--no-line-map",
+               "--ext", "cruby", "--ext-init", "spx_init_#{@feature}", "--ext-entry", entry_list,
+               "-o", File.join(@dir, "#{@feature}.c")]
+        sh(cmd, "spinel")
+      end
+
+      # Every kernel carries its own copy of the runtime and exports the same
+      # global symbols. CRuby dlopens extensions RTLD_GLOBAL, and an ELF
+      # shared object binds its calls to the first definition in the
+      # process, so a second kernel would raise through the first kernel's
+      # exception stack and die as "unhandled". Export only Init_* and bind
+      # everything else inside the object. (Mach-O two-level namespaces do
+      # this by default.)
+      def shared_flags
+        return %w[-bundle -Wl,-undefined,dynamic_lookup] if RUBY_PLATFORM.include?("darwin")
+        script = File.join(@dir, "exports.map")
+        File.write(script, "{ global: Init_*; local: *; };\n")
+        ["-shared", "-Wl,-Bsymbolic", "-Wl,--version-script=#{script}"]
+      end
+
+      def run_cc
+        cmd = [*self.class.cc, *shared_flags, "-fPIC", "-O2", "-w",
+               "-I#{RbConfig::CONFIG['rubyhdrdir']}", "-I#{RbConfig::CONFIG['rubyarchhdrdir']}",
+               "-I#{self.class.runtime_dir}", "-I#{@dir}",
+               File.join(@dir, "#{@feature}.c"), File.join(@dir, "#{@feature}_ext.c"),
+               self.class.runtime_archive, "-lm", "-o", bundle]
+        sh(cmd, "cc")
+      end
+
+      def sh(cmd, what)
+        Native.log(cmd.join(" "))
+        out, status = Open3.capture2e(*cmd)
+        File.write(File.join(@dir, "#{what}.log"), out)
+        return if status.success?
+        FileUtils.rm_f(bundle)
+        raise CompileError, "#{what} failed (exit #{status.exitstatus}) building #{@dir}:\n#{out}"
+      end
+    end
+  end
+end

data/lib/spinel/native/registry.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Spinel
+  module Native
+    # One per module that `extend Spinel::Native`. Tracks the methods marked
+    # `native`, keeps their pure-Ruby definitions, and swaps the compiled
+    # entries in once their parameter types are known.
+    class Registry
+      Entry = Struct.new(:name, :kind, :pure, :source, :types, :compiled, :module_function, keyword_init: true)
+
+      attr_accessor :pending_signature
+      attr_reader :entries
+
+      def initialize(owner)
+        @owner = owner
+        @entries = {}
+        @last_def = nil
+        @installing = false
+      end
+
+      # Called from the method_added hooks.
+      def defined(kind, name)
+        return if @installing
+        @last_def = [kind, name]
+        return unless @pending_signature
+        sig = @pending_signature
+        @pending_signature = nil
+        mark(name, sig)
+      end
+
+      # `native def name` (types nil: sampled from the first call) or a
+      # signature-declared entry.
+      def mark(name, types = nil)
+        kind = @last_def && @last_def[1] == name ? @last_def[0] : :instance
+        pure = kind == :singleton ? @owner.method(name) : @owner.instance_method(name)
+        entry = Entry.new(name: name, kind: kind, pure: pure, source: Source.of_method(pure), types: types,
+                          # in a module, `native def x` is also callable as Mod.x (it never uses self)
+                          module_function: kind == :instance && @owner.instance_of?(Module))
+        if types && pure.arity != types.length
+          raise TypeError, "#{name}: signature has #{types.length} parameter(s), the method takes #{pure.arity}"
+        end
+        @entries[name] = entry
+        install(entry) { |args, this| dispatch(entry, args, this) }
+        entry
+      end
+
+      def compile_known!
+        known = @entries.values.select { |e| e.types && !e.compiled }
+        compile(known) unless known.empty?
+        known
+      end
+
+      # The pure definition, bound like the original call.
+      def pure_call(entry, args, this)
+        entry.kind == :singleton ? entry.pure.call(*args) : entry.pure.bind_call(this, *args)
+      end
+
+      private
+
+      # First call of a not-yet-compiled entry: settle its types, compile the
+      # kernel, then either forward or (verify mode) keep comparing.
+      def dispatch(entry, args, this)
+        return pure_call(entry, args, this) if Native.mode == :off
+        unless entry.compiled
+          entry.types ||= args.map { |a| Types.of_value(a) }
+          compile(@entries.values.select { |e| e.types && !e.compiled })
+        end
+        return pure_call(entry, args, this) unless entry.compiled
+        native_call(entry, args, this)
+      rescue Native::TypeError, CompileError => e
+        raise if Native.mode == :strict
+        warn "[spinel-native] #{@owner}##{entry.name}: staying on Ruby (#{e.message.lines.first.strip})"
+        entry.types = nil
+        install(entry) { |a, t| pure_call(entry, a, t) }
+        pure_call(entry, args, this)
+      end
+
+      def native_call(entry, args, this)
+        got = entry.compiled.public_send(entry.name, *args)
+        if Native.mode == :verify
+          want = pure_call(entry, args, this)
+          unless want == got || (want.is_a?(Float) && got.is_a?(Float) && want.nan? && got.nan?)
+            raise Mismatch, "#{@owner}##{entry.name}(#{args.map(&:inspect).join(', ')}): ruby=#{want.inspect} native=#{got.inspect}"
+          end
+        end
+        got
+      end
+
+      # Every marked method goes into the kernel (they may call each other);
+      # the ones with known types are exported.
+      def compile(exports)
+        body = @entries.values.map(&:source).join("\n\n")
+        builder = Builder.new(body, exports.to_h { |e| [e.name, e.types] })
+        result = builder.build
+        mod = Object.const_get(result.module_name)
+        exports.each do |e|
+          e.compiled = mod
+          if Native.mode == :verify
+            install(e) { |args, this| native_call(e, args, this) }
+          else
+            install(e) { |args, _this| mod.public_send(e.name, *args) }
+          end
+        end
+        Native.log("#{@owner}: #{exports.map { |e| "#{e.name}(#{e.types.map { |t| Types.to_s(t) }.join(', ')})" }.join(', ')} " \
+                   "#{result.cached ? 'loaded from cache' : 'compiled'} in #{result.seconds.round(2)}s (#{result.dir})")
+      end
+
+      def install(entry, &body)
+        @installing = true
+        target = entry.kind == :singleton ? @owner.singleton_class : @owner
+        redefine(target, entry.name) { |*args| body.call(args, self) }
+        redefine(@owner.singleton_class, entry.name) { |*args| body.call(args, self) } if entry.module_function
+      ensure
+        @installing = false
+      end
+
+      # define_method over an existing definition warns under -w; drop it first.
+      def redefine(target, name, &impl)
+        target.send(:remove_method, name) if target.method_defined?(name, false) || target.private_method_defined?(name, false)
+        target.send(:define_method, name, &impl)
+      end
+    end
+  end
+end

data/lib/spinel/native/source.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Spinel
+  module Native
+    # Pulls the source text of a method back out of its file with Prism, and
+    # rewrites its header to the `def self.name` form the kernel module uses.
+    module Source
+      module_function
+
+      def of_method(meth)
+        file, line = meth.source_location
+        raise Error, "#{meth.name}: no source location (defined in C or eval?)" unless file && File.exist?(file)
+        node = find_def(Prism.parse_file(file).value, meth.name, line)
+        raise Error, "#{meth.name}: no `def` found at #{file}:#{line}" unless node
+        as_module_function(node)
+      end
+
+      def find_def(node, name, line)
+        return node if node.is_a?(Prism::DefNode) && node.name == name && node.location.start_line == line
+        node.compact_child_nodes.each do |child|
+          found = find_def(child, name, line)
+          return found if found
+        end
+        nil
+      end
+
+      def as_module_function(node)
+        raise Error, "#{node.name}: block parameters cannot cross the boundary" if node.parameters&.block
+        text = node.slice
+        text.sub(/\Adef\s+(self\s*\.\s*)?#{Regexp.escape(node.name.to_s)}/, "def self.#{node.name}")
+      end
+    end
+  end
+end

data/lib/spinel/native/types.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Spinel
+  module Native
+    # The types that cross the extension boundary (by copy), and how a Ruby
+    # value maps onto them. A type is one of:
+    #   :int, :float, :str, :bool, [:array, :int|:float|:str]
+    module Types
+      module_function
+
+      NAMES = {
+        "Integer" => :int, "Float" => :float, "String" => :str,
+        "bool" => :bool, "true" => :bool, "false" => :bool,
+      }.freeze
+
+      # "(Array[Float], Integer) -> Float" => [[:array, :float], :int]
+      # The return type is inferred by Spinel and only checked for shape here.
+      def parse_signature(sig)
+        m = sig.strip.match(/\A\((.*)\)\s*->\s*(.+)\z/m)
+        raise TypeError, "bad signature #{sig.inspect}, want \"(T1, T2) -> R\"" unless m
+        params = split_top_level(m[1]).map { |t| parse_type(t) }
+        parse_type(m[2])
+        params
+      end
+
+      def parse_type(text)
+        t = text.strip
+        if (m = t.match(/\AArray\[(.+)\]\z/))
+          elem = parse_type(m[1])
+          raise TypeError, "nested arrays cannot cross the boundary: #{t}" if elem.is_a?(Array)
+          return [:array, elem]
+        end
+        NAMES.fetch(t) { raise TypeError, "unsupported type #{t.inspect} (supported: Integer, Float, String, bool, Array[...])" }
+      end
+
+      def split_top_level(text)
+        out, depth, cur = [], 0, +""
+        text.each_char do |ch|
+          case ch
+          when "[" then depth += 1; cur << ch
+          when "]" then depth -= 1; cur << ch
+          when "," then depth.zero? ? (out << cur; cur = +"") : cur << ch
+          else cur << ch
+          end
+        end
+        out << cur unless cur.strip.empty?
+        out.map(&:strip)
+      end
+
+      # The boundary type of a live Ruby value, or raise TypeError.
+      def of_value(v)
+        case v
+        when Integer then :int
+        when Float then :float
+        when String then :str
+        when true, false then :bool
+        when Array
+          raise TypeError, "cannot infer the element type of an empty array (declare a signature)" if v.empty?
+          elem = of_value(v.first)
+          raise TypeError, "nested arrays cannot cross the boundary" if elem.is_a?(Array)
+          unless v.all? { |e| of_value(e) == elem }
+            raise TypeError, "mixed-type array cannot cross the boundary"
+          end
+          [:array, elem]
+        else
+          raise TypeError, "#{v.class} cannot cross the boundary (Integer, Float, String, bool, Array of those)"
+        end
+      end
+
+      # A Ruby literal of the type, used as the witness call that seeds
+      # Spinel's whole-program inference for an exported entry.
+      def witness(type)
+        case type
+        in :int then "0"
+        in :float then "0.0"
+        in :str then '"x"'
+        in :bool then "true"
+        in [:array, elem] then "[#{witness(elem)}]"
+        end
+      end
+
+      def to_s(type)
+        case type
+        in :int then "Integer"
+        in :float then "Float"
+        in :str then "String"
+        in :bool then "bool"
+        in [:array, elem] then "Array[#{to_s(elem)}]"
+        end
+      end
+    end
+  end
+end

data/lib/spinel/native/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Spinel
+  module Native
+    VERSION = "0.1.0"
+  end
+end

data/lib/spinel/native.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# Spinel::Native -- compile individual Ruby methods to a native extension with
+# the Spinel AOT compiler, from inside a running CRuby program.
+#
+#   module Physics
+#     extend Spinel::Native
+#
+#     native def dot(a, b)
+#       s = 0.0
+#       i = 0
+#       while i < a.length
+#         s += a[i] * b[i]
+#         i += 1
+#       end
+#       s
+#     end
+#   end
+#
+# The method keeps running as plain Ruby until it is first called; the
+# argument types of that first call seed Spinel's type inference, the kernel
+# is compiled into a CRuby extension (cached on disk), and the method is
+# re-bound to the compiled entry. If anything fails the pure-Ruby definition
+# stays in place, so the program is never worse off than without the gem.
+#
+# SPINEL_NATIVE=off     never compile, run the Ruby definitions
+# SPINEL_NATIVE=verify  run both and raise Spinel::Native::Mismatch on divergence
+# SPINEL_NATIVE=strict  a compile failure raises instead of falling back
+
+require "rbconfig"
+require "digest"
+require "fileutils"
+require "prism"
+
+require_relative "native/version"
+require_relative "native/types"
+require_relative "native/source"
+require_relative "native/builder"
+require_relative "native/registry"
+
+module Spinel
+  module Native
+    class Error < StandardError; end
+    class CompileError < Error; end
+    class TypeError < Error; end
+    class Mismatch < Error; end
+
+    class << self
+      # :on (default), :off, :verify, :strict
+      def mode
+        @mode ||= (ENV["SPINEL_NATIVE"] || "on").to_sym
+      end
+      attr_writer :mode
+
+      def verbose?
+        ENV["SPINEL_NATIVE_VERBOSE"] == "1"
+      end
+
+      def log(msg)
+        warn("[spinel-native] #{msg}") if verbose?
+      end
+
+      # Compile every native method of +mod+ whose parameter types are known
+      # (from a signature or an earlier call). Useful at boot to pay the
+      # compile cost up front and surface errors early.
+      def compile!(mod)
+        registry_of(mod).compile_known!
+      end
+
+      # The registry behind a module that has `extend Spinel::Native`.
+      def registry_of(mod)
+        mod.instance_variable_get(:@__spinel_native) or
+          raise Error, "#{mod} does not extend Spinel::Native"
+      end
+
+      def extended(base)
+        base.instance_variable_set(:@__spinel_native, Registry.new(base))
+        base.singleton_class.prepend(Hooks)
+      end
+    end
+
+    # Records which `def` ran last so `native def x` knows what it marked.
+    module Hooks
+      def method_added(name)
+        @__spinel_native&.defined(:instance, name)
+        super
+      end
+
+      def singleton_method_added(name)
+        @__spinel_native&.defined(:singleton, name)
+        super
+      end
+    end
+
+    # native def foo(a, b) ... end          types sampled from the first call
+    # native "(Array[Float], Integer) -> Float"; def foo(a, b) ... end
+    #                                         types declared, compiled on first call
+    def native(arg = nil)
+      registry = @__spinel_native
+      case arg
+      when Symbol then registry.mark(arg)
+      when String then registry.pending_signature = Types.parse_signature(arg)
+      when nil    then raise ArgumentError, "native: expected `native def ...` or `native \"(...) -> ...\"`"
+      else raise ArgumentError, "native: unexpected #{arg.inspect}"
+      end
+      arg
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: spinel_native
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Hasiński
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Mark a hot method with `native def`; on its first call it is compiled
+  by Spinel into a CRuby extension and rebound, with the Ruby definition kept as fallback
+  and oracle.
+email:
+- krzysztof.hasinski@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- examples/demo.rb
+- lib/spinel/native.rb
+- lib/spinel/native/builder.rb
+- lib/spinel/native/registry.rb
+- lib/spinel/native/source.rb
+- lib/spinel/native/types.rb
+- lib/spinel/native/version.rb
+homepage: https://github.com/khasinski/spinel_native
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/khasinski/spinel_native
+  changelog_uri: https://github.com/khasinski/spinel_native/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/khasinski/spinel_native/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Compile individual Ruby methods to native code with the Spinel AOT compiler
+test_files: []