bundler-spinel 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f60b276e969f601d5931d3df6b6e7177820f58609d18e1082e49784e4acf7ce3
-  data.tar.gz: 9a5b89828d86ab07cacbb3d85a63ff7167d0cecc83e96138ca4de28e19c51083
+  metadata.gz: 8518bfe1ec1303fb7116e33738abb8246bb3c7072afca1b70057523f824b4a2c
+  data.tar.gz: 5d945e9ca4fa4409f5ff325a6eae9d917469e5c0e7ceb2ef69c8c356551c0fda
 SHA512:
-  metadata.gz: 60290945a8663c019299e28553af1c5bbd6766f8606a1b8675142653b1cd2692eae7e3eb9d7d243fbbfa05765c58f44eee74fb9ebb1852606bf2ecff9ce7ec9b
-  data.tar.gz: fb8b90c9cec7bda764f34625fd3643c27facb676c9a951551fd2a53a1c365e782acd0bd7d318a21c50062ea37c9f41c3105761ab01974d87fa51bfc329a90102
+  metadata.gz: ff071af5cde1af69f32f92b509092ec6d535173dfbbdbe84c02940b5118abb1f7cafacc610cc26a4c3e20263426e4a7422560ba166c766ff296d391be1758e34
+  data.tar.gz: e704f7c8a825a0cdb278c604a86bb38fd9363ac0fe8fe7406c88c52e9b77e1a76cd2675036d503b3e80fe488f27f3ff1820c7803428989f7ac1930bdaff9a412

data/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to `bundler-spinel` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
 project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] — 2026-06-15
+
+### Fixed
+- **Probe: a require-only compile failure is the load-path limit, not
+  `analyze-failed` (spinel master b60fbd7 absorption).** Since matz/spinel's
+  #1383 fix, an unresolvable plain `require "gem/sub"` makes `spinel -c` exit
+  non-zero instead of warning and continuing. Because that idiom is
+  near-universal, the b60fbd7 corpus reprobe spuriously turned thousands of
+  previously-`clean` gems into `rejected:analyze-failed`. The probe now detects
+  a compile that failed *solely* on an unresolvable `require` (the
+  `CallNode \`require\`` form, with no real codegen error and no other
+  unsupported call) and classifies it `risky [load-path:require]` — the
+  documented no-load-path limitation a real Spinel project resolves by
+  vendoring. Real codegen errors still reject. +`test/probe_classify_test.rb`.
+- **Engine rev detection for worktrees + frozen copies.** `Engine#rev` fell
+  back to an opaque `bin:<hash>` (a) in a git *worktree*, where `.git` is a
+  file not a directory, and (b) for a frozen/detached engine copy with no
+  `.git`. Both now resolve to `git:<short-sha>`: worktree `.git` files are
+  honored (`File.exist?`, not `File.directory?`), and a `.spinel_rev` stamp
+  (a bare HEAD sha written at freeze time) is read first. Keeps the ledger
+  key — and the history/diff tooling that joins on it — consistent across the
+  build layouts a reprobe actually uses. `bin/reprobe-corpus.sh`'s frozen
+  engines now carry the stamp.
+- **cmake build-units on macOS (spinelgems#21).** The Vendorer now sets the
+  SDK libc++ include path (`CPLUS_INCLUDE_PATH` via `xcrun --show-sdk-path`)
+  for cmake build-unit invocations on Darwin — without it every C++ unit died
+  with `fatal error: 'array' file not found` (toy#27's Mac cold-start LIB
+  leg; fix verified on an M2). Caller-set `CPLUS_INCLUDE_PATH` is preserved
+  (SDK path appends); missing/failing `xcrun` degrades to the previous
+  behavior.
+
+### Added
+- **Opt-in build-units + variant build dirs (spinelgems#20).** An `optional`
+  entry may declare `"default": "disabled"`: a plain `vendor` skips its build
+  entirely (placeholder ← `disabled_cflags`) until the consumer enables it via
+  `--with-ext NAME` / `SPINEL_EXT_ENABLE` — what a CUDA unit needs to not
+  attempt nvcc configures on a CUDA-less box. Explicit disable beats enable;
+  unknown enable names warn loud. cmake units take `"build_dir"` (default
+  `"build"`, relative-only) so two entries can build one shared source dir
+  into variant trees (`build/` vs `build-cuda/`), and source dirs are copied
+  once per vendor run — a second entry sharing `dir` no longer wipes the first
+  unit's just-built artifacts. Unblocks toy merging its staged
+  `spinel-ext-gpu.json` into `spinel-ext.json` (toy#45 Phase 3 → publish).
+- **A gem's `sig/*.rbs` acts as the type root (spinelgems#13).** Spinel infers
+  param types from call sites (whole-program, closed-world), so an *uncalled*
+  public method widens to `int`/`poly` — the failure mode hand-written seed
+  blocks exist to patch. `--rbs` was verified to re-pin uncalled methods' param,
+  return, and ivar types, so the tooling now treats a shipped `sig/` tree as
+  authoritative: `spinel-compat verify` auto-passes `--rbs <gem>/sig` when the
+  gem ships signatures (`--rbs DIR` to override, `--no-rbs` to opt out), and
+  records an `rbs:sig` provenance tag in the verdict reasons. `vendor` copies
+  each gem's `sig/` alongside `lib/`, aggregates all of them under
+  `<into>/sig/<gem>/`, and advertises the single `--rbs <into>/sig` root in
+  `deps.rb` and the CLI output. A spinel-native gem (SpinelKit, the Tep
+  batteries) ships one standard Ruby artifact — no seed soup, no manifest keys.
+
 ## [0.3.0] — 2026-06-08
 
 ### Added

data/lib/bundler/spinel/cli.rb

@@ -146,7 +146,11 @@ module Bundler
         smoke = (j = argv.index("--smoke")) ? argv.delete_at(j + 1).tap { argv.delete_at(j) } : nil
         full = !!argv.delete("--full")
         tests = !!argv.delete("--tests")
-        name = argv.shift or raise Error, "usage: spinel-compat verify NAME [VERSION] [--dir PATH] [--smoke FILE | --tests] [--full]"
+        # --rbs DIR / --no-rbs: explicit type root / opt out. Default :auto —
+        # use the gem's own sig/*.rbs when shipped (spinelgems#13).
+        rbs = (k = argv.index("--rbs")) ? argv.delete_at(k + 1).tap { argv.delete_at(k) } : :auto
+        rbs = false if argv.delete("--no-rbs")
+        name = argv.shift or raise Error, "usage: spinel-compat verify NAME [VERSION] [--dir PATH] [--smoke FILE | --tests] [--full] [--rbs DIR | --no-rbs]"
         engine = Engine.new
         if dir
           version = argv.shift || "path"
@@ -164,7 +168,7 @@ module Bundler
           smoke = File.join(Dir.tmpdir, "__spinel_tests_#{name}.rb")
           File.write(smoke, runner)
         end
-        v = Verifier.new(engine, Ledger.new).verify(name, version, gem_dir, smoke: smoke && File.expand_path(smoke), full: full)
+        v = Verifier.new(engine, Ledger.new).verify(name, version, gem_dir, smoke: smoke && File.expand_path(smoke), full: full, rbs: rbs)
         print_verdict(v)
         File.delete(smoke) if tests && smoke && File.exist?(smoke)
         (v.verified? || v.loaded?) ? 0 : 1
@@ -186,13 +190,26 @@ module Bundler
           ext_disable << argv.delete_at(d + 1).to_s
           argv.delete_at(d)
         end
+        # --with-ext NAME : opt IN to a default-disabled entry, e.g. a CUDA
+        # build-unit (repeatable; also SPINEL_EXT_ENABLE). spinelgems#20.
+        ext_enable = []
+        while (w = argv.index("--with-ext"))
+          ext_enable << argv.delete_at(w + 1).to_s
+          argv.delete_at(w)
+        end
         lock = argv.shift || "Gemfile.lock"
         raise Error, "no #{lock}; run `bundle lock` first" unless File.exist?(lock)
 
-        res = Vendorer.new.vendor(lock, into: into, ext_overrides: ext_overrides, ext_disable: ext_disable)
+        res = Vendorer.new.vendor(lock, into: into, ext_overrides: ext_overrides,
+                                        ext_disable: ext_disable, ext_enable: ext_enable)
         ext = res[:extensions].to_i
         @out.puts "vendored #{res[:count]} gem(s)#{ext.positive? ? " (+#{ext} C ext)" : ''} -> #{res[:into]}"
         @out.puts "  require_relative \"#{res[:into]}/deps\" from your Spinel entrypoint"
+        sigs = res[:sig_gems] || []
+        unless sigs.empty?
+          @out.puts "  #{sigs.size} gem(s) ship sig/*.rbs type roots -> #{res[:into]}/sig"
+          @out.puts "  compile with: spinel ... --rbs #{res[:into]}/sig   (spinelgems#13)"
+        end
         0
       end
 
@@ -469,7 +486,9 @@ module Bundler
             spinel-compat probe NAME [VERSION]    probe one gem, record a verdict
             spinel-compat why NAME [--probe]      legible "why doesn't this work (yet)?" report
             spinel-compat verify NAME [--smoke F]  differential CRuby-vs-Spinel run -> verified
-            spinel-compat vendor [LOCK] [--into D] place deps where Spinel finds them + deps.rb
+                                  [--rbs DIR | --no-rbs]  type root: gem's sig/*.rbs (auto when shipped)
+            spinel-compat vendor [LOCK] [--into D] place deps where Spinel finds them + deps.rb (+ sig/ roots)
+                                  [--with-ext NAME | --no-ext NAME]  opt in/out of optional C-ext units
             spinel-compat check [LOCK] [--strict] gate a Gemfile.lock (exit 1 if rejected)
             spinel-compat survey GEM... | --list F  wholesale review -> reason histogram
             spinel-compat serve --store DIR        curated source (only vetted gems)

data/lib/bundler/spinel/engine.rb

@@ -76,7 +76,17 @@ module Bundler
       private
 
       def compute_rev
-        if File.directory?(File.join(@dir, ".git"))
+        # A frozen/detached engine copy (bin/reprobe-corpus.sh's
+        # spinel-frozen-<rev>, or a build whose .git was stripped) can carry a
+        # `.spinel_rev` stamp — a bare HEAD sha written at freeze time — so it
+        # still keys to its real git rev instead of an opaque binary hash.
+        stamp = File.join(@dir, ".spinel_rev")
+        if File.file?(stamp) && !(s = File.read(stamp).strip[0, 12].to_s).empty?
+          return "git:#{s}"
+        end
+        # `.git` is a *file* in a git worktree (a gitdir pointer), not a dir —
+        # File.exist? covers both so worktree checkouts report git:, not bin:.
+        if File.exist?(File.join(@dir, ".git"))
           sha = capture("git", "-C", @dir, "rev-parse", "--short", "HEAD")
           if sha && !sha.empty?
             dirty = capture("git", "-C", @dir, "status", "--porcelain")

data/lib/bundler/spinel/history.rb

@@ -83,6 +83,32 @@ module Bundler
                 "to Ruby source lines via <code>#line</code>, on by default — the " \
                 "<a href=\"https://github.com/matz/spinel/issues/1338\">#1338</a> RFC direction. The behaviour-verified " \
                 "tier reached 144 mechanical ★ this run." },
+        { rev: "cb23cc6", date: "2026-06-09", commit: "~23 commits — 12 harness-filed issues closed in one wave, incl. Mutex/Monitor#synchronize + Thread.new now running and carrying their block value (#1360), class-instance-vars in class methods (#1352), is_a?(IncludedModule)/ancestors (#1350), \\h/\\H regex (#1349), reopened-builtin optional defaults (#1348), bitwise/shift operator mangling (#1358/#1368), the captured-&block value/type family",
+          file: "survey-cb23cc6/compat.jsonl",
+          note: "<strong>Mutex/Thread come in from the cold.</strong> With matz/spinel#1360 landing " \
+                "(<code>Mutex#synchronize</code>/<code>Thread.new</code> now run single-threaded and carry their " \
+                "block's value), the static pre-filter no longer hard-rejects them — they're flagged " \
+                "<code>risky</code> (correct for defensive use, degenerate only for true concurrency). Re-probing " \
+                "the 8,833 gems that had been rejected on sight for <code>Mutex.new</code>/<code>Thread.new</code>, " \
+                "<strong>3,493 (39.5%) moved out of <code>rejected</code></strong> — they compile now; the static " \
+                "wall had been hiding it. The four spine gems (<code>bundler</code>/<code>rake</code>/" \
+                "<code>minitest</code>/<code>thor</code>) now reject for their <em>real</em> reason — the deep " \
+                "metaprogramming surface (<code>send</code>/<code>method_missing</code>/<code>cattr_accessor</code>) — " \
+                "not a misleading <code>hard:Mutex.new</code>. The differential re-audit also caught one regression in " \
+                "the wave: returning <code>self</code> from a reopened-builtin method " \
+                "(<a href=\"https://github.com/matz/spinel/issues/1386\">#1386</a>, <code>to-bool</code>), filed same day." },
+        { rev: "b60fbd7", date: "2026-06-15", commit: "636 commits — the largest wave yet. A type-inference + codegen rewrite (typed-array/poly ~222, inference/cast/box ~168, string ~124, block/yield ~101, module/singleton ~94) closing many harness-filed issues at once: reopened-builtin self (#1386), hash-block String type (#1382/#1394), circular require_relative (#1373), computed require (#1383), class-method yield (#1387), Scheduled-server boot + SIGTERM (#1369/#1384). New surfaces: value-type objects, --rbs/--emit-rbs/--emit-symbol-map.",
+          file: "survey-b60fbd7/compat.jsonl",
+          note: "<strong>The largest movement in the catalog's history.</strong> 636 upstream commits — a type-inference " \
+                "rewrite that resolved the entire <code>unresolved:&lt;method&gt;</code> reject family (~60k records → ~0): " \
+                "<strong>~49,000 gems moved out of <code>rejected</code></strong> (−46%), +22k to <code>clean</code>. The " \
+                "wave also changed unresolvable <code>require</code> to hard-fail the compile (post-#1383); because " \
+                "<code>require \"gem/version\"</code> is near-universal that spuriously rejected thousands, so the probe " \
+                "now classifies a require-only failure as the no-load-path limit (<code>risky [load-path:require]</code>, " \
+                "9,716 gems corrected). Cost side, caught by re-verifying every ★ at this rev: <strong>~34 of 175 " \
+                "behaviour-verified gems regressed</strong> (12 miscompiles incl. <code>after_commit_action</code>, 22 " \
+                "codegen incl. bare-<code>super</code>/<code>ForwardingSuperNode</code>) — the trust tier dropped 175→136. " \
+                "Fresh-verify overrode stickiness, so the ★ count is honest, not carried." },
       ].freeze
 
       ORDER = %w[clean risky rejected].freeze

data/lib/bundler/spinel/localizer.rb

@@ -65,17 +65,19 @@ module Bundler
         file.empty? ? "line #{v['line']}" : "#{file}:#{v['line']}"
       end
 
-      # Resolve bisect.sh. It lives in spinel-dev (separate from the compiler
-      # engine), so there's no fixed relation to the engine dir — probe a few
-      # conventional spots, newest-intent first: an explicit override, a sibling
-      # spinel-dev checkout next to the engine, the conventional ~/sites layout.
+      # Resolve bisect.sh. It lives in the spinel-dev tooling repo (separate from
+      # the compiler engine), so there's no fixed relation to the engine dir —
+      # probe a few conventional spots, newest-intent first: an explicit override,
+      # a sibling checkout next to the engine, the conventional ~/sites layout.
+      # The local checkout may be named spinel-tools (gx10) or spinel-dev (the
+      # GitHub repo name), so probe both.
       def bisect_script
         rel = "tools/value-bisect/bisect.sh"
-        candidates = [
-          ENV["SPINEL_BISECT"],
-          File.expand_path(File.join(@engine.dir, "..", "spinel-dev", rel)),
-          File.expand_path("~/sites/spinel-dev/#{rel}")
-        ]
+        candidates = [ENV["SPINEL_BISECT"]]
+        %w[spinel-tools spinel-dev].each do |repo|
+          candidates << File.expand_path(File.join(@engine.dir, "..", repo, rel))
+          candidates << File.expand_path("~/sites/#{repo}/#{rel}")
+        end
         candidates.find { |c| c && File.exist?(c) }
       end
     end

data/lib/bundler/spinel/probe.rb

@@ -37,6 +37,25 @@ module Bundler
       # 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
+      # Since the #1383 fix, an unresolvable plain `require` no longer warns +
+      # continues (exit 0) — it's emitted as an unsupported CallNode and the
+      # compile EXITS NON-ZERO. On the whole 189k corpus that turned ~thousands
+      # of previously-`clean` gems (the universal `require "gem/version"` idiom)
+      # into spurious `analyze-failed`. We detect this exact form so a
+      # require-ONLY compile failure is classified as the no-load-path
+      # limitation, not a codegen failure. (b60fbd7; see harness/findings.)
+      REQUIRE_CALL_FAIL = /unsupported call:.*CallNode `require`/.freeze
+      # A genuine codegen/compile failure — the C compiler choked, the analyzer
+      # died, or an unsupported construct OTHER than a plain require. Presence of
+      # any of these means the failure is real, not just the load-path limit.
+      HARD_COMPILE_ERROR = %r{
+        out\.c:\d+.*\berror:        |   # gcc error on emitted C
+        \bfatal\b                   |
+        \bSegmentation\ fault\b     |
+        \banalyze\ failed\b         |
+        unsupported\ puts\ argument |   # an unsupported non-require construct
+        unsupported\ call:\ (?!.*CallNode\ `require`)  # any non-require unsupported call
+      }ix.freeze
       ANALYZE_FAILED = /\b(analyze failed|fatal)\b/i.freeze
 
       # Spinel's analyze pass can spin for minutes on pathological inputs (no
@@ -53,15 +72,26 @@ module Bundler
       # Spinel will never support (threads, Mutex, TracePoint). Metaprogramming
       # tokens like `define_method` stay in RISK_TOKENS below — they degrade
       # silently, so the compile signal is still the right call there.
+      # Constructs that put a gem outside the AOT closed-world model entirely —
+      # rejected from a static scan, before a compile is even attempted.
+      # Thread/Mutex lived here until matz/spinel#1360 made them *run* (single-
+      # threaded, carrying the block's value): they're now compiled + flagged
+      # `risky` (below), not hard-rejected. TracePoint/set_trace_func stay —
+      # there is no degenerate-but-correct lowering for runtime tracing.
       HARD_REJECT_TOKENS = {
-        /\bThread\.(new|start|fork)\b/ => "Thread.new",
-        /\bMutex\.new\b/               => "Mutex.new",
-        /\bMutex_m\b/                  => "Mutex_m",
-        /\bTracePoint\b/               => "TracePoint"
+        /\bTracePoint\b/     => "TracePoint",
+        /\bset_trace_func\b/ => "set_trace_func"
       }.freeze
 
       # token => reason. Tokens Spinel cannot honour and may silently no-op.
       RISK_TOKENS = {
+        # Thread/Mutex run single-threaded since matz/spinel#1360 — correct for
+        # defensive use (a mutex guarding state, Thread.new for a value), but
+        # degenerate for genuine concurrency: compiles, flagged, fails
+        # `check --strict`. (Demoted from HARD_REJECT after #1360.)
+        /\bThread\.(new|start|fork)\b/ => "thread",
+        /\bMutex\.new\b/               => "mutex",
+        /\bMutex_m\b/                  => "mutex_m",
         /\beval\s*\(/                  => "eval",
         /\binstance_eval\b/            => "instance_eval",
         /\b(class|module)_eval\b/      => "class_eval",
@@ -108,6 +138,13 @@ module Bundler
           elsif sig[:timed_out]
             # Analyzer ran past the cap — pathological for Spinel, not the gem.
             ["rejected", ["analyze-timeout"]]
+          elsif sig[:require_only_fail]
+            # Compile failed solely on an unresolvable plain `require` (b60fbd7
+            # hard-fails these where cb23cc6 warned + continued). That's the
+            # no-load-path limitation, not a codegen failure — a real Spinel
+            # project vendors deps so the require resolves. Classify as the
+            # load-path limit (risky), keeping the needs: notes below.
+            ["risky", ["load-path:require"]]
           elsif sig[:analyze_failed] || !sig[:exit_ok]
             ["rejected", ["analyze-failed"]]
           elsif !static_only_risks(risks).empty?
@@ -134,18 +171,27 @@ module Bundler
         analyze_failed = false
         exit_ok = true
         timed_out = false
+        require_fail = false   # saw the new unresolvable-require hard-fail form
+        hard_error = false     # saw a genuine codegen/analyzer failure
         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
+            require_fail ||= out =~ REQUIRE_CALL_FAIL ? true : false
+            hard_error ||= out =~ HARD_COMPILE_ERROR ? true : false
             out.scan(UNRESOLVED_CALL) { |m| calls << m[0] }
             out.scan(UNRESOLVED_REQUIRE) { |m| requires << m[0] }
           end
         end
+        # A compile that failed ONLY because a plain `require` is unresolvable
+        # (no real codegen error, no other unsupported call) is the documented
+        # no-load-path limitation, not a failure of the gem's own code.
+        require_only_fail = !exit_ok && !timed_out && require_fail && !hard_error && calls.empty?
         { calls: calls.uniq, requires: requires.uniq,
-          analyze_failed: analyze_failed, exit_ok: exit_ok, timed_out: timed_out }
+          analyze_failed: analyze_failed, exit_ok: exit_ok, timed_out: timed_out,
+          require_only_fail: require_only_fail }
       end
 
       # Run `spinel -c FILE -o OUT_C` with a wall-clock cap. Returns

data/lib/bundler/spinel/vendorer.rb

@@ -29,15 +29,24 @@ module Bundler
       end
 
       def vendor(lockfile = "Gemfile.lock", into: "vendor/spinel", warn_incompatible: true,
-                 ext_overrides: {}, ext_disable: [])
+                 ext_overrides: {}, ext_disable: [], ext_enable: [])
         parsed = Bundler::LockfileParser.new(File.read(lockfile))
         lock_dir = File.dirname(File.expand_path(lockfile))
         into = File.expand_path(into)
         FileUtils.mkdir_p(into)
         disable = (ext_disable + ENV["SPINEL_EXT_DISABLE"].to_s.split(",")).map(&:strip).reject(&:empty?)
+        enable = (ext_enable + ENV["SPINEL_EXT_ENABLE"].to_s.split(",")).map(&:strip).reject(&:empty?)
+        # Per-run state for build-units: copy-once over shared source dirs
+        # (spinelgems#20) + the optional-entry names actually seen, so a typo'd
+        # --with-ext warns loud instead of silently doing nothing.
+        @copied_build_dirs = {}
+        @ext_names_seen = []
 
         manifest = []
         exts = 0
+        sig_root = File.join(into, "sig")
+        FileUtils.rm_rf(sig_root)
+        sig_gems = []
         # Topological order (dependencies before dependents), not the lockfile's
         # alphabetical `specs` (spinelgems#19): Spinel has no load path, so
         # deps.rb is a *flattened single load* — each gem's entrypoint
@@ -50,15 +59,20 @@ module Bundler
           src = resolve_source(spec, lock_dir)
           dest = File.join(into, name)
           place(src, dest)
-          exts += wire_extensions(src, dest, ext_overrides, disable)
+          exts += wire_extensions(src, dest, ext_overrides, disable, enable)
+          sig_gems << name if collect_sig(dest, sig_root, name)
           if (target = require_target(name, dest))
             manifest << { require: target, libdir: "#{File.basename(dest)}/lib" }
           end
           note_compat(name, version) if warn_incompatible
         end
 
-        write_manifest(into, manifest)
-        { into: into, count: manifest.size, extensions: exts }
+        unless (unknown = enable - @ext_names_seen).empty?
+          warn "[vendor] --with-ext/SPINEL_EXT_ENABLE names matched no optional " \
+               "entry in any vendored manifest: #{unknown.join(', ')}"
+        end
+        write_manifest(into, manifest, sig_gems)
+        { into: into, count: manifest.size, extensions: exts, sig_gems: sig_gems }
       end
 
       # Order specs so every gem's runtime dependencies come before it — a DFS
@@ -108,12 +122,29 @@ module Bundler
       def place(src, dest)
         FileUtils.rm_rf(dest)
         FileUtils.mkdir_p(dest)
-        %w[lib].each do |sub|
+        # sig/ rides along with lib/: a gem's shipped *.rbs is its type root
+        # under Spinel (spinelgems#13) — verify --dir on the vendored copy
+        # auto-detects it, and vendor() aggregates one --rbs root from all gems.
+        %w[lib sig].each do |sub|
           s = File.join(src, sub)
           FileUtils.cp_r(s, dest) if File.directory?(s)
         end
       end
 
+      # Aggregate a vendored gem's sig/*.rbs under <into>/sig/<name>/ so the
+      # consumer build passes a single `--rbs <into>/sig` (the driver takes one
+      # DIR; spinel_rbs_extract walks it recursively). Without this, uncalled
+      # public methods in a library widen to int/poly — the seed-block failure
+      # mode spinelgems#13 retires. Returns true when the gem contributed sigs.
+      def collect_sig(dest, sig_root, name)
+        sig = File.join(dest, "sig")
+        return false if Dir[File.join(sig, "**", "*.rbs")].empty?
+
+        FileUtils.mkdir_p(sig_root)
+        FileUtils.cp_r(sig, File.join(sig_root, name))
+        true
+      end
+
       # Build + wire any C extensions the gem declares in spinel-ext.json
       # (OriPekelman/spinelgems#2; see docs/c-ext.md). Each entry substitutes its
       # @PLACEHOLDER@ in the placed Ruby — so the gem's `ffi_cflags "@PLACEHOLDER@"`
@@ -125,8 +156,13 @@ module Bundler
       #   - any static `libs`.
       # An `optional` entry the consumer opted out of (`name` in `disable` /
       # SPINEL_EXT_DISABLE) substitutes its `disabled_cflags` instead (category C).
-      # Returns the count wired. A no-op for gems without the manifest.
-      def wire_extensions(src, dest, overrides, disable)
+      # An `optional` entry declaring `"default": "disabled"` is opt-IN
+      # (spinelgems#20 — CUDA/Metal units must not build, or fail to configure,
+      # on a default `vendor`): it is treated as opted-out unless the consumer
+      # enables it (`--with-ext NAME` / SPINEL_EXT_ENABLE). Explicit disable
+      # beats enable. Returns the count wired. A no-op for gems without the
+      # manifest.
+      def wire_extensions(src, dest, overrides, disable, enable = [])
         manifest = File.join(src, "spinel-ext.json")
         return 0 unless File.exist?(manifest)
 
@@ -143,7 +179,7 @@ module Bundler
         sib_cflags = Hash.new { |h, k| h[k] = [] }
         entries.each do |e|
           next if e["source"] || !e["name"]              # only CFLAGS-only siblings
-          next if e["optional"] && disable.include?(e["name"].to_s)
+          next if ext_disabled?(e, disable, enable)
           (cf = pkg_config_cflags(e)) && sib_cflags[e["name"].to_s].concat(cf)
           sib_cflags[e["name"].to_s].concat(Array(e["cflags"])) if e["cflags"]
         end
@@ -156,9 +192,11 @@ module Bundler
         entries.each do |e|
           placeholder = e["placeholder"]
           name = e["name"]
+          (@ext_names_seen ||= []) << name.to_s if name && e["optional"]
 
-          # Opt-out (only meaningful with a placeholder to write disabled_cflags into).
-          if e["optional"] && name && disable.include?(name.to_s)
+          # Opted out — explicitly (`--no-ext`), or an opt-in (`"default":
+          # "disabled"`) entry the consumer didn't enable (spinelgems#20).
+          if ext_disabled?(e, disable, enable)
             substitute_placeholder(dest, placeholder, e["disabled_cflags"].to_s) if placeholder
             wired += 1
             next
@@ -225,6 +263,17 @@ module Bundler
         0
       end
 
+      # Is this optional entry off for this run? Explicit disable always wins;
+      # an opt-in entry (`"default": "disabled"`, spinelgems#20) is off unless
+      # its name is in the enable set. `default` is only meaningful on an
+      # `optional` entry with a `name`.
+      def ext_disabled?(entry, disable, enable)
+        return false unless entry["optional"] && entry["name"]
+        n = entry["name"].to_s
+        return true if disable.include?(n)
+        entry["default"].to_s == "disabled" && !enable.include?(n)
+      end
+
       # System libs/cflags for an entry, resolved at the consumer's environment:
       # `pkg-config --cflags --libs <name>`, else `pkg_config_fallback`, else nil
       # (leave the placeholder so the build fails loud — we never silently drop a
@@ -300,18 +349,28 @@ module Bundler
         end
 
         ven_dir = File.join(dest, dir_rel)
-        FileUtils.mkdir_p(File.dirname(ven_dir))
-        FileUtils.rm_rf(ven_dir)
-        # Source-only copy: a path:-sourced dev checkout carries build state —
-        # build*/ dirs (whose CMakeCache pins the ORIGINAL source path and makes
-        # cmake refuse the copy), the .patched sentinel, .git. ggml: 205MB with
-        # build dirs, 24MB without. Top-level name filter covers the real cases.
-        FileUtils.mkdir_p(ven_dir)
-        Dir.children(src_dir).each do |c|
-          next if c.start_with?("build") || c == ".git" || c == ".patched"
-          # stale dev objects/archives would also poison make's mtime logic
-          next if c =~ /\.(o|a|so|dylib|bundle)\z/
-          FileUtils.cp_r(File.join(src_dir, c), File.join(ven_dir, c))
+        # Copy-once (spinelgems#20): two entries may share one source dir —
+        # toy's CPU and CUDA ggml units differ only in configure args/build_dir.
+        # The rm_rf+recopy below would wipe the first entry's just-built tree,
+        # so a dir already placed this vendor run is reused as-is. (Patches stay
+        # declarable on both entries: the stack-level detection no-ops on an
+        # already-patched copy.)
+        @copied_build_dirs ||= {}
+        unless @copied_build_dirs[ven_dir]
+          FileUtils.mkdir_p(File.dirname(ven_dir))
+          FileUtils.rm_rf(ven_dir)
+          # Source-only copy: a path:-sourced dev checkout carries build state —
+          # build*/ dirs (whose CMakeCache pins the ORIGINAL source path and makes
+          # cmake refuse the copy), the .patched sentinel, .git. ggml: 205MB with
+          # build dirs, 24MB without. Top-level name filter covers the real cases.
+          FileUtils.mkdir_p(ven_dir)
+          Dir.children(src_dir).each do |c|
+            next if c.start_with?("build") || c == ".git" || c == ".patched"
+            # stale dev objects/archives would also poison make's mtime logic
+            next if c =~ /\.(o|a|so|dylib|bundle)\z/
+            FileUtils.cp_r(File.join(src_dir, c), File.join(ven_dir, c))
+          end
+          @copied_build_dirs[ven_dir] = true
         end
 
         # Declared patches (toy#45: pristine vendored ggml + vendor-patches/*.patch),
@@ -360,7 +419,15 @@ module Bundler
         cmds =
           case b["tool"].to_s
           when "cmake"
-            build_dir = File.join(ven_dir, "build")
+            # Variant build dirs over a shared source (spinelgems#20): toy's
+            # CUDA unit configures the same vendored ggml into build-cuda/
+            # alongside the CPU unit's build/. Relative, no escape.
+            bd = (b["build_dir"] || "build").to_s
+            if bd.start_with?("/") || bd.split(File::SEPARATOR).include?("..")
+              warn "[vendor] bad build_dir for #{entry['name']}: #{bd.inspect} (relative, no ..)"
+              return nil
+            end
+            build_dir = File.join(ven_dir, bd)
             cfg = ["cmake", "-S", ven_dir, "-B", build_dir, *Array(b["args"]).map(&:to_s)]
             bld = ["cmake", "--build", build_dir, "-j", jobs]
             targets = Array(b["targets"]).map(&:to_s)
@@ -374,8 +441,9 @@ module Bundler
             return nil
           end
 
+        env = build_env(b["tool"].to_s)
         cmds.each do |cmd|
-          out, st = Open3.capture2e(*cmd)
+          out, st = Open3.capture2e(env, *cmd)
           unless st.success?
             warn "[vendor] build failed (#{entry['name']}): #{cmd.take(2).join(' ')} ... : " \
                  "#{out.lines.last(3).join.strip}"
@@ -397,6 +465,26 @@ module Bundler
         ven_dir.start_with?(pwd) ? ven_dir.delete_prefix(pwd) : ven_dir
       end
 
+      # Build-unit environment (spinelgems#21): on macOS, a cmake unit with C++
+      # sources can't find the stdlib headers (`fatal error: 'array' file not
+      # found`) unless CPLUS_INCLUDE_PATH carries the SDK's libc++ path —
+      # toy#27's Mac cold-start LIB leg, verified fix on the M2. Tool-side, not
+      # per-gem env: the platform knowledge belongs here, or every gem with a
+      # C++ unit repeats it. A caller-set CPLUS_INCLUDE_PATH is preserved (the
+      # SDK path appends); xcrun absent/failing degrades to no env, and the
+      # build then fails with the original loud cmake error.
+      def build_env(tool, platform: RUBY_PLATFORM)
+        return {} unless tool == "cmake" && platform.include?("darwin")
+        sdk, st = Open3.capture2e("xcrun", "--show-sdk-path")
+        sdk = sdk.strip
+        return {} unless st.success? && !sdk.empty?
+        libcxx = File.join(sdk, "usr", "include", "c++", "v1")
+        paths = [ENV["CPLUS_INCLUDE_PATH"].to_s, libcxx].reject(&:empty?)
+        { "CPLUS_INCLUDE_PATH" => paths.join(File::PATH_SEPARATOR) }
+      rescue Errno::ENOENT
+        {}
+      end
+
       # A placeholder that substitutes ZERO files is drift (toy#45: a gem whose
       # ffi_cflags line moved out from under its manifest's literal-string
       # placeholder) — warn loud. This replaces per-gem canary hacks like toy's
@@ -443,11 +531,16 @@ module Bundler
              "— may not compile (run `spinel-compat check`)"
       end
 
-      def write_manifest(into, entries)
+      def write_manifest(into, entries, sig_gems = [])
         es = entries.compact
         body = +"# Generated by bundler-spinel. require_relative this from a\n" \
                 "# Spinel program to pull in vendored dependencies (topo order:\n" \
                 "# every gem's dependencies are loaded before it — spinelgems#19).\n"
+        unless sig_gems.empty?
+          body << "# Type roots: #{sig_gems.join(', ')} ship sig/*.rbs, aggregated\n" \
+                  "# under sig/ — compile with `--rbs #{File.join(into, 'sig')}`\n" \
+                  "# so uncalled public methods keep their declared types (spinelgems#13).\n"
+        end
         # Put each vendored gem's lib root on $LOAD_PATH so a dependent's plain
         # `require "<depgem>"` resolves under CRuby too (the differential verify
         # and plain-Ruby dev runs). Spinel has no load path: it ignores both the

data/lib/bundler/spinel/verifier.rb

@@ -37,13 +37,20 @@ module Bundler
       # vocabulary is unchanged; the probe is tagged `verify-full` so the
       # whole-surface signal stays distinguishable in the ledger from the
       # entrypoint-only `verify`.
-      def verify(gem_name, version, dir, smoke: nil, full: false)
+      # rbs: a gem's shipped sig/*.rbs acts as the type root for the Spinel
+      # compile (spinelgems#13). `--rbs` re-pins *uncalled* public methods'
+      # param/return/ivar types that whole-program inference would otherwise
+      # widen to int/poly for lack of a call site — the failure mode hand-written
+      # seed blocks exist to patch. :auto (default) uses <dir>/sig when it
+      # contains .rbs files; a String is an explicit root; nil/false disables.
+      def verify(gem_name, version, dir, smoke: nil, full: false, rbs: :auto)
         @engine.ensure!
+        rbs_root = resolve_rbs_root(dir, rbs)
         harness = File.join(dir, HARNESS)
         File.write(harness, harness_source(gem_name, dir, smoke, full))
 
         ruby_out, ruby_err, ruby_ok = run_ruby(harness, dir)
-        spin_out, spin_err, spin_ok = run_spinel(harness)
+        spin_out, spin_err, spin_ok = run_spinel(harness, rbs_root)
 
         verdict, reasons = classify(ruby_ok, spin_ok, ruby_out, spin_out, spin_err, behavior: !smoke.nil?)
         # Tag *why* (the spinelgems#4 usability rubric) so a failure says what it'd
@@ -57,9 +64,14 @@ module Bundler
         # and, when it pins a diverging scalar, appends `localized:<file>:<line>
         # <var> cruby=… spinel=…`. Best-effort: nil when it can't localize.
         if verdict == "rejected" && reasons.include?("miscompile")
+          # Note: the bisector compiles without the sig root, so localization of
+          # an rbs-seeded build is best-effort (bisect.sh has no --rbs passthrough).
           loc = Localizer.new(@engine).localize(harness)
           reasons += [loc] if loc
         end
+        # Provenance: the verdict was reached with the gem's sig/ as type root —
+        # legible in the ledger/notes, ignored by the site's sticky logic.
+        reasons += ["rbs:sig"] if rbs_root
         @ledger.record(@ledger.build(
           gem: gem_name, version: version, rev: @engine.rev,
           verdict: verdict, reasons: reasons, probe: full ? "verify-full" : "verify"
@@ -180,9 +192,18 @@ module Bundler
         [out, err, st.success?]
       end
 
-      def run_spinel(file)
+      def resolve_rbs_root(dir, rbs)
+        return nil if rbs.nil? || rbs == false
+        return File.expand_path(rbs) if rbs.is_a?(String)
+        sig = File.join(dir, "sig")
+        Dir[File.join(sig, "**", "*.rbs")].empty? ? nil : sig
+      end
+
+      def run_spinel(file, rbs_root = nil)
         bin = file.sub(/\.rb$/, ".bin")
-        _, cerr, cst = Open3.capture3(@engine.bin, file, "-o", bin)
+        args = [@engine.bin, file, "-o", bin]
+        args += ["--rbs", rbs_root] if rbs_root
+        _, cerr, cst = Open3.capture3(*args)
         return ["", cerr, false] unless cst.success? && File.executable?(bin)
 
         out, err, st = Open3.capture3(bin)

data/lib/bundler/spinel/version.rb

@@ -1,9 +1,12 @@
 module Bundler
   module Spinel
-    # 0.3.0: `spinel-compat vendor` grows build-units (cmake/make native deps
-    # built inside the consumer's vendor tree — heavy-native gems like toy's
-    # ggml vendor self-contained + relocatable, #14), and a new
-    # `spinel-compat why <gem>` legible diagnostic (#12).
-    VERSION = "0.3.0"
+    # 0.4.0: a gem's shipped `sig/*.rbs` acts as the Spinel type root —
+    # `verify` auto-`--rbs`, `vendor` aggregates one root, retiring seed soup
+    # (#13); opt-in (`"default":"disabled"`) build-units + variant `build_dir`
+    # over a shared source for optional CUDA/Metal backends (#20); macOS SDK
+    # libc++ path for cmake build-units (#21); and probe/engine robustness for
+    # the b60fbd7 corpus reprobe (require-only → load-path limit; git rev for
+    # worktrees/frozen copies).
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bundler-spinel
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ori Pekelman