bundler-spinel 0.2.1 → 0.4.0

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/site.rb

@@ -52,7 +52,7 @@ module Bundler
 
       # One-line semantics per verdict — used as the lede on each per-verdict page.
       BLURB = {
-        "verified" => "<strong>Full surface</strong> compiles and a behaviour smoke matches CRuby under a Spinel-compiled harness — every <code>lib/</code> file force-required (no <code>autoload</code> masking, no missing-dependency rescue), not just the entrypoint. The only verdict to trust where it matters. A constant/VERSION-only smoke that loads the entrypoint but leaves the gem's real code behind <code>autoload</code> is <em>not</em> enough — that overstated usability, so the bar was tightened to whole-surface. Sticky across engine revisions until a re-run catches a regression.",
+        "verified" => "<strong>Full surface</strong> compiles and a behaviour smoke matches CRuby under a Spinel-compiled harness — every <code>lib/</code> file force-required (no <code>autoload</code> masking, no missing-dependency rescue), not just the entrypoint. The only verdict to trust where it matters. A constant/VERSION-only smoke that loads the entrypoint but leaves the gem's real code behind <code>autoload</code> is <em>not</em> enough — that overstated usability, so the bar was tightened to whole-surface. Sticky across engine revisions until a re-run catches a regression. <strong>Or</strong>: for a gem the mechanical probe can't rank — a Spinel-<em>native</em> program rather than a <code>require</code>-library (e.g. <code>tep</code>, the translator that compiles this very site) — a <span class=\"badge human\">👤 human</span> attestation of real production use is the verification (the strongest signal we carry); a fresh behaviour failure still overrides it.",
         "loaded"   => "Compiles and loads identically under CRuby and Spinel via a require-only differential. Logic untested — a gem can load fine and still silently miscompile in the code paths the require-only smoke doesn't exercise. Weaker than <strong>verified</strong>; not a trust signal.",
         "clean"    => "Compiles clean (cheap static lower bound). No behaviour was exercised — the survey doesn't run the gem. Massively overstates compatibility; the harness is the trustworthy check.",
         "risky"    => "Compiles, but the source uses constructs Spinel degrades silently (<code>eval</code>, <code>define_method</code>, …). Allowed by default; fails under <code>spinel-compat check --strict</code>.",
@@ -313,6 +313,17 @@ module Bundler
           current_entries[v.gem] << v if v.rev == target_rev
         end
 
+        # A human attestation of real production use is the strongest trust
+        # signal we carry — stronger than a hand smoke — and for a gem the
+        # mechanical probe *can't* rank, it's the only applicable verification.
+        # The require-probe assumes "gem = library you require"; a Spinel-native
+        # program like tep (a translator/framework, FFI + no CRuby runtime) can't
+        # pass it though it demonstrably works (it compiles this very site). So a
+        # human-attested (gem,version) earns ★ exactly like a verify-full pass —
+        # unless a fresh *behaviour* probe (verify/verify-full) contradicts the
+        # human's claim (handled by the `behaviour_rejected` guard below).
+        attestations.each_key { |k| ever_verified << k }
+
         current_entries.map do |name, vs|
           # Within the current rev, pick the *strongest* signal — not the
           # most recent. A rejected (compile error or harness miscompile)
@@ -403,6 +414,12 @@ module Bundler
       # candidates.tsv / compat.jsonl for machine consumers).
       def verdict_page_html(verdict, all_rs, counts)
         full = all_rs.select { |r| r.verdict == verdict }
+        # Signals-first in every tier: a gem with a human attestation and/or
+        # passing own-tests outranks an unsignaled one (most-trusted on top),
+        # then by downloads — matching the dynamic /catalog order_by. all_rs is
+        # already downloads-sorted, so the stable sort keeps downloads as the
+        # tiebreak. Keeps signal-bearing low-download gems (e.g. tep) at the top.
+        full = full.sort_by.with_index { |r, i| [-((r.human ? 1 : 0) + (r.tests ? 1 : 0)), i] }
         capped = (verdict == "rejected") && full.size > REJECTED_CAP
         shown = capped ? full.first(REJECTED_CAP) : full
 
@@ -424,7 +441,7 @@ module Bundler
 
         body << %(<div class="filters">\n)
         body << %(  <input id="q" type="search" placeholder="filter by gem name…" autocomplete="off">\n)
-        body << %(  <label class="floor"><input type="checkbox" id="floor" checked> )
+        body << %(  <label class="floor"><input type="checkbox" id="floor"> )
         body << %(hide low-signal gems (&lt; #{fmt_n MIN_DOWNLOADS} downloads)</label>\n)
         body << %(</div>\n)
 
@@ -432,7 +449,7 @@ module Bundler
         body << %(<th class="num">downloads</th><th>updated</th><th>description</th></tr></thead><tbody>\n)
         shown.each do |r|
           gem_cell = r.homepage ? %(<a href="#{h r.homepage}" rel="noopener nofollow">#{h r.gem}</a>) : h(r.gem)
-          body << %(<tr data-gem="#{h r.gem.downcase}" data-dl="#{r.downloads}">)
+          body << %(<tr data-gem="#{h r.gem.downcase}" data-dl="#{r.downloads}" data-sig="#{r.human || r.tests ? 1 : 0}">)
           body << %(<td class="v #{r.verdict}" title="#{h r.notes}">#{GLYPH[r.verdict]} #{r.verdict}</td>)
           body << %(<td class="sig">#{signals_html(r)}</td>)
           body << %(<td class="g">#{gem_cell} <span class="ver">#{h r.version}</span></td>)
@@ -459,7 +476,7 @@ module Bundler
           <body>
           <header>
             <a class="brand" href="/"><svg class="gem" viewBox="0 0 24 24" aria-hidden="true"><path d="M6 3h12l4 6-10 13L2 9z" fill="#7b2d8e"/><path d="M6 3 2 9l10 13z" fill="#5a1f6b" opacity=".55"/><path d="M18 3l4 6-10 13z" fill="#b14fc4"/><path d="M6 3h12l-6 6z" fill="#d98ee8"/></svg>SpinelGems</a>
-            <nav><a href="/">Home</a> <a href="/catalog">Catalog</a> <a href="/history.html">History</a>
+            <nav><a href="/">Home</a> <a href="/catalog">Catalog</a> <a href="/load-bearing.html">Load-bearing</a> <a href="/history.html">History</a>
               <a href="https://github.com/OriPekelman/spinelgems">GitHub</a></nav>
           </header>
           <main>
@@ -528,7 +545,8 @@ module Bundler
           const hideLow = floor.checked;
           for (const tr of rows) {
             const okQ = !term || tr.dataset.gem.includes(term);
-            const okF = !hideLow || (+tr.dataset.dl) >= FLOOR;
+            // signal-bearing rows (👤/✪) are never hidden by the floor
+            const okF = !hideLow || tr.dataset.sig === '1' || (+tr.dataset.dl) >= FLOOR;
             tr.style.display = (okQ && okF) ? '' : 'none';
           }
         }

data/lib/bundler/spinel/vendorer.rb

@@ -29,28 +29,74 @@ 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
-        parsed.specs.each do |spec|
+        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
+        # require_relative'd once, in order. A dependent loaded before its
+        # dependency would reference not-yet-defined constants. tep→spinel_kit
+        # is the first real case (it sorted right only by alphabetical luck).
+        topo_sort(parsed.specs).each do |spec|
           name = spec.name
           version = spec.version.to_s
           src = resolve_source(spec, lock_dir)
           dest = File.join(into, name)
           place(src, dest)
-          exts += wire_extensions(src, dest, ext_overrides, disable)
-          manifest << require_target(name, dest)
+          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
+      # post-order over `spec.dependencies`, with an alphabetical tiebreak for
+      # determinism and a visiting-set guard so a dependency cycle degrades to
+      # *some* stable order instead of looping. Deps not present in this lockset
+      # (stdlib/default gems) are skipped. (spinelgems#19)
+      def topo_sort(specs)
+        by_name = specs.each_with_object({}) { |s, h| h[s.name] = s }
+        ordered = []
+        state = {} # name => :visiting | :done
+        visit = lambda do |spec|
+          st = state[spec.name]
+          return if st == :done || st == :visiting
+          state[spec.name] = :visiting
+          spec.dependencies.sort_by(&:name).each do |dep|
+            dn = dep.respond_to?(:name) ? dep.name : dep.to_s
+            visit.call(by_name[dn]) if by_name[dn]
+          end
+          state[spec.name] = :done
+          ordered << spec
+        end
+        specs.sort_by(&:name).each { |s| visit.call(s) }
+        ordered
       end
 
       # path:/git: lockfile sources (toy ↔ tep is the headline case)
@@ -76,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@"`
@@ -93,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)
 
@@ -111,23 +179,58 @@ 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
 
         wired = 0
+        # name -> vendored build dir, for cross-entry {dir:NAME} link expansion
+        # (toy#45: tinynn's link line needs both its own dir and ggml's).
+        # Entries are processed in manifest order, so referenced units come first.
+        built_dirs = {}
         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
           end
 
+          # Build-unit entry (spinelgems#14): a declared native build (cmake|make)
+          # producing archives *inside the consumer's vendor tree*, with `link`
+          # flags expanded relative to it ({dir} -> the vendored build dir). This
+          # is the heavy-native analogue of `source` per-.c entries — nokogiri's
+          # mini_portile2 precedent, Spinel-shaped. It replaces the per-consumer
+          # post-vendor absolute-path rewrite hooks (toy's prep/post_vendor_toy.rb)
+          # that made vendored trees non-relocatable and toy unpublishable.
+          # A consumer override (SPINEL_EXT_<PLACEHOLDER> / --ext) supplies the
+          # full replacement flags and skips the build (prebuilt escape hatch).
+          if e["build"]
+            if placeholder && (ov = overrides[placeholder] || ENV[ext_env_key(placeholder)])
+              substitute_placeholder(dest, placeholder, ov.to_s)
+              wired += 1
+              next
+            end
+            ven_dir = build_unit(src, dest, e) or next # build failed (warned)
+            built_dirs[name.to_s] = ven_dir if name
+            if placeholder
+              parts = Array(e["link"]).map do |t|
+                t.gsub("{dir}", ven_dir)
+                 .gsub(/\{dir:([^}]+)\}/) { built_dirs[$1] || "{dir:#{$1}}" }
+              end
+              parts.concat(Array(e["libs"]))
+              substitute_placeholder(dest, placeholder, parts.join(" ").strip, name: name)
+            end
+            wired += 1
+            next
+          end
+
           # Compile / place the .o (or take a prebuilt override path). Both forms
           # need this; post-#1011 const-fold form skips the substitution below.
           obj = nil
@@ -160,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
@@ -214,11 +328,180 @@ module Bundler
         nil
       end
 
-      def substitute_placeholder(dest, placeholder, repl)
+      # Build-unit (spinelgems#14): copy the gem's declared build dir into the
+      # vendor tree, run the declared tool there, verify the declared artifacts.
+      # Returns the vendored dir path (project-relative when `into` was given
+      # relative — the usual case — so substituted -L flags stay relocatable
+      # with the consumer project) or nil on failure (warned, entry skipped).
+      #
+      # The tool surface is deliberately constrained to cmake|make with declared
+      # args/targets/artifacts — no free-form shell. extconf.rb is precedent for
+      # arbitrary install-time code in gems, but there's no need to copy that
+      # mistake into spinel-ext.json: a declarative unit stays auditable and the
+      # detector-inferable, consumer-side philosophy survives.
+      def build_unit(src, dest, entry)
+        b = entry["build"]
+        dir_rel = b["dir"].to_s
+        src_dir = File.join(src, dir_rel)
+        unless File.directory?(src_dir)
+          warn "[vendor] build dir not found for #{entry['name'] || entry['placeholder']}: #{dir_rel}"
+          return nil
+        end
+
+        ven_dir = File.join(dest, dir_rel)
+        # 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),
+        # applied into the COPY before configure — mini_portile's patch_files
+        # precedent. Globs resolve against the gem root; patch files are data,
+        # which keeps the no-free-form-shell property of the schema.
+        # `git apply` (not patch(1)): strict, no fuzz — patch(1) happily
+        # *re*-applies hunks fuzzily onto an already-patched tree. Works in
+        # non-repo dirs too (gem-shipped trees have no .git).
+        #
+        # Patches form an ordered STACK (later ones rewrite earlier ones'
+        # hunks), so already-applied detection is stack-level, not per-patch:
+        # a pristine tree forward-applies the FIRST patch; a fully-patched
+        # working tree (path:-sourced dev checkout, toy's `.patched` flow)
+        # reverse-applies the LAST. Anything else is genuine drift — fail.
+        patches = Array(entry["build"]["patches"])
+                  .flat_map { |g| Dir[File.join(src, g.to_s)].sort }
+                  .map { |p| File.expand_path(p) }
+        unless patches.empty?
+          _, pristine = Open3.capture2e("git", "-C", ven_dir, "apply", "--check", patches.first)
+          if pristine.success?
+            patches.each do |abs|
+              out, st = Open3.capture2e("git", "-C", ven_dir, "apply", abs)
+              unless st.success?
+                warn "[vendor] patch failed (#{entry['name']}): #{File.basename(abs)}: #{out.lines.last(2).join.strip}"
+                return nil
+              end
+            end
+          else
+            _, stacked = Open3.capture2e("git", "-C", ven_dir, "apply", "--reverse", "--check", patches.last)
+            unless stacked.success?
+              warn "[vendor] patches for #{entry['name']} neither apply (pristine) nor " \
+                   "reverse-apply (already patched) — source tree drifted from the patch set"
+              return nil
+            end
+            # already-patched working tree: nothing to do
+          end
+        end
+
+        jobs = begin
+          require "etc"
+          Etc.nprocessors.to_s
+        rescue StandardError
+          "4"
+        end
+        cmds =
+          case b["tool"].to_s
+          when "cmake"
+            # 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)
+            bld.push("--target", *targets) unless targets.empty?
+            [cfg, bld]
+          when "make"
+            [["make", "-C", ven_dir, "-j", jobs,
+              *Array(b["args"]).map(&:to_s), *Array(b["targets"]).map(&:to_s)]]
+          else
+            warn "[vendor] unknown build tool #{b['tool'].inspect} for #{entry['name']} (cmake|make)"
+            return nil
+          end
+
+        env = build_env(b["tool"].to_s)
+        cmds.each do |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}"
+            return nil
+          end
+        end
+
+        missing = Array(b["artifacts"]).reject { |a| File.exist?(File.join(ven_dir, a.to_s)) }
+        unless missing.empty?
+          warn "[vendor] build for #{entry['name']} succeeded but artifacts missing: #{missing.join(', ')}"
+          return nil
+        end
+
+        # Project-relative {dir} when the vendor tree lives under the consumer's
+        # cwd (the normal `--into vendor/spinel` case) — substituted -L flags
+        # then survive moving the whole project, not just deleting the gem's
+        # source checkout. Compile from the project root (the documented flow).
+        pwd = Dir.pwd + File::SEPARATOR
+        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
+      # CURRENT_FFI_CFLAGS lockstep constant with a systemic vendor-time check.
+      def substitute_placeholder(dest, placeholder, repl, name: nil)
+        hits = 0
         Dir[File.join(dest, "**", "*.rb")].each do |f|
           body = File.read(f)
-          File.write(f, body.gsub(placeholder, repl)) if body.include?(placeholder)
+          next unless body.include?(placeholder)
+          File.write(f, body.gsub(placeholder, repl))
+          hits += 1
+        end
+        if hits.zero?
+          warn "[vendor] #{name || 'ext'}: placeholder matched NO vendored .rb — " \
+               "manifest drift? (#{placeholder.length > 60 ? placeholder[0, 57] + '...' : placeholder})"
         end
+        hits
       end
 
       # @TEP_SPHTTP_O@ -> SPINEL_EXT_TEP_SPHTTP_O
@@ -248,10 +531,27 @@ module Bundler
              "— may not compile (run `spinel-compat check`)"
       end
 
-      def write_manifest(into, targets)
+      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 (lock order).\n"
-        targets.compact.each { |t| body << %{require_relative "#{t}"\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
+        # $LOAD_PATH lines and the inter-gem `require`, and instead loads
+        # everything via the topo-ordered require_relatives below — so the same
+        # deps.rb is correct for both runtimes. (spinelgems#19, gap 2)
+        es.map { |e| e[:libdir] }.uniq.each do |d|
+          body << %{$LOAD_PATH.unshift(File.expand_path(#{d.inspect}, __dir__))\n}
+        end
+        body << "\n"
+        es.each { |e| body << %{require_relative "#{e[:require]}"\n} }
         File.write(File.join(into, "deps.rb"), body)
       end
     end

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)