scint 0.7.0 → 0.7.1

data/lib/scint/cli/install.rb

@@ -23,7 +23,9 @@ require_relative "../downloader/pool"
 require_relative "../gem/package"
 require_relative "../gem/extractor"
 require_relative "../cache/layout"
+require_relative "../cache/manifest"
 require_relative "../cache/metadata_store"
+require_relative "../cache/validity"
 require_relative "../installer/planner"
 require_relative "../installer/linker"
 require_relative "../installer/preparer"
@@ -41,29 +43,43 @@ module Scint
     class Install
       RUNTIME_LOCK = "scint.lock.marshal"
 
-      def initialize(argv = [])
+      def initialize(argv = [], without: nil, with: nil)
         @argv = argv
         @jobs = nil
         @path = nil
         @verbose = false
         @force = false
+        @without_groups = nil
+        @with_groups = nil
         @download_pool = nil
         @download_pool_lock = Thread::Mutex.new
         @gemspec_cache = {}
         @gemspec_cache_lock = Thread::Mutex.new
         parse_options
+        # Allow programmatic override (for tests)
+        @without_groups = Array(without).map(&:to_sym) if without
+        @with_groups = Array(with).map(&:to_sym) if with
+      end
+
+      def _tmark(label, t0)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        $stderr.puts "  [timing] #{label}: #{((now - t0) * 1000).round}ms" if ENV["SCINT_TIMING"]
+        now
       end
 
       def run
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        _t = start_time
 
         cache = Scint::Cache::Layout.new
+        cache_telemetry = Scint::Cache::Telemetry.new
         bundle_path = @path || ENV["BUNDLER_PATH"] || ".bundle"
         bundle_display = display_bundle_path(bundle_path)
         bundle_path = File.expand_path(bundle_path)
-        worker_count = @jobs || [Platform.cpu_count * 2, 50].min
+        worker_count = [(@jobs || [Platform.cpu_count * 2, 50].min).to_i, 1].max
         compile_slots = compile_slots_for(worker_count)
-        per_type_limits = install_task_limits(worker_count, compile_slots)
+        git_slots = git_slots_for(worker_count)
+        per_type_limits = install_task_limits(worker_count, compile_slots, git_slots)
         $stdout.puts "#{GREEN}💎#{RESET} Scintellating Gemfile into #{BOLD}#{bundle_display}#{RESET} #{DIM}(scint #{VERSION}, ruby #{RUBY_VERSION})#{RESET}"
         $stdout.puts
 
@@ -75,6 +91,7 @@ module Scint
         scheduler.start
 
         begin
+          _t = _tmark("startup", _t)
           # 2. Parse Gemfile
           gemfile = Scint::Gemfile::Parser.parse("Gemfile")
 
@@ -86,6 +103,7 @@ module Scint
           dep_count = gemfile.dependencies.size
           scheduler.scale_workers(dep_count)
 
+          _t = _tmark("parse_gemfile", _t)
           # 3. Enqueue index fetches for all sources immediately
           gemfile.sources.each do |source|
             scheduler.enqueue(:fetch_index, source[:uri] || source.to_s,
@@ -106,20 +124,26 @@ module Scint
                               -> { clone_git_source(source, cache) })
           end
 
+          _t = _tmark("enqueue_fetches", _t)
           # 6. Wait for index fetches, then resolve
           scheduler.wait_for(:fetch_index)
+          _t = _tmark("wait_index", _t)
           scheduler.wait_for(:git_clone)
+          _t = _tmark("wait_git", _t)
 
           resolved = resolve(gemfile, lockfile, cache)
           resolved = dedupe_resolved_specs(adjust_meta_gems(resolved))
+          resolved = filter_excluded_gems(resolved, gemfile)
           force_purge_artifacts(resolved, bundle_path, cache) if @force
 
+          _t = _tmark("resolve", _t)
           # 7. Plan: diff resolved vs installed
-          plan = Installer::Planner.plan(resolved, bundle_path, cache)
+          plan = Installer::Planner.plan(resolved, bundle_path, cache, telemetry: cache_telemetry)
           total_gems = resolved.size
           updated_gems = plan.count { |e| e.action != :skip }
           cached_gems = total_gems - updated_gems
           to_install = plan.reject { |e| e.action == :skip }
+          _t = _tmark("plan", _t)
 
           # Scale up for download/install phase based on actual work count
           scheduler.scale_workers(to_install.size)
@@ -127,6 +151,7 @@ module Scint
           # Warm-cache accelerator: pre-materialize cache-backed gem trees in
           # batches so install workers avoid one cp process per gem.
           bulk_prelink_gem_files(to_install, cache, bundle_path)
+          _t = _tmark("prelink", _t)
 
           if to_install.empty?
             # Keep lock artifacts aligned even when everything is already installed.
@@ -192,9 +217,13 @@ module Scint
           end
         ensure
           begin
-            scheduler.shutdown
+            cache_telemetry.warn_if_needed(cache_root: cache.root)
           ensure
-            close_download_pool
+            begin
+              scheduler.shutdown
+            ensure
+              close_download_pool
+            end
           end
         end
       end
@@ -233,6 +262,91 @@ module Scint
         seen.values
       end
 
+      # Determine which gem names should be excluded based on group settings.
+      # A gem is excluded if ALL of its group memberships are in excluded groups.
+      # Gems appearing in any non-excluded group are kept.
+      def excluded_gem_names(gemfile, resolved: nil)
+        excluded_groups = compute_excluded_groups(gemfile)
+        return Set.new if excluded_groups.empty?
+
+        # Build map: gem_name => set of all groups it appears in (across all declarations)
+        gem_groups = Hash.new { |h, k| h[k] = Set.new }
+        gemfile.dependencies.each do |dep|
+          dep.groups.each { |g| gem_groups[dep.name] << g }
+        end
+
+        # A gem is directly excluded if ALL its groups are excluded
+        directly_excluded = Set.new
+        gem_groups.each do |name, groups|
+          directly_excluded << name if groups.subset?(excluded_groups)
+        end
+
+        # If we have resolved specs, also exclude transitive-only deps
+        if resolved && directly_excluded.any?
+          exclude_transitive_deps(directly_excluded, resolved, gem_groups)
+        else
+          directly_excluded
+        end
+      end
+
+      # Filter resolved specs, removing gems that belong only to excluded groups.
+      def filter_excluded_gems(resolved, gemfile)
+        excluded = excluded_gem_names(gemfile, resolved: resolved)
+        return resolved if excluded.empty?
+
+        resolved.reject { |spec| excluded.include?(spec.name) }
+      end
+
+      private
+
+      def compute_excluded_groups(gemfile)
+        optional = Set.new(Array(gemfile.optional_groups))
+        without = Set.new(Array(@without_groups))
+        with = Set.new(Array(@with_groups))
+
+        # Optional groups are excluded by default unless explicitly included via --with
+        excluded = optional - with
+        # --without adds more groups to exclude
+        excluded.merge(without)
+        excluded
+      end
+
+      # Walk the dependency graph to find transitive deps that are ONLY
+      # reachable through excluded gems. Shared deps are kept.
+      def exclude_transitive_deps(directly_excluded, resolved, gem_groups)
+        # Build dependency graph: name => [dep_names]
+        dep_graph = {}
+        resolved.each do |spec|
+          dep_names = Array(spec.dependencies).filter_map do |dep|
+            if dep.is_a?(Hash)
+              dep[:name] || dep["name"]
+            elsif dep.respond_to?(:name)
+              dep.name
+            end
+          end
+          dep_graph[spec.name] = dep_names
+        end
+
+        all_names = Set.new(resolved.map(&:name))
+
+        # Start from Gemfile deps that are NOT excluded, then walk transitive deps
+        included_roots = gem_groups.keys.reject { |n| directly_excluded.include?(n) }
+
+        # BFS from included roots to find all reachable gems
+        reachable = Set.new
+        queue = included_roots.dup
+        while (name = queue.shift)
+          next if reachable.include?(name)
+          reachable << name
+          (dep_graph[name] || []).each { |dep| queue << dep }
+        end
+
+        # Everything not reachable from included roots is excluded
+        all_names - reachable
+      end
+
+      public
+
       # Install scint into the bundle by copying our own lib tree.
       # No download needed — we know exactly where we are.
       def install_builtin_gem(entry, bundle_path)
@@ -429,9 +543,9 @@ module Scint
         candidates.each do |gs|
           next unless File.exist?(gs)
           begin
-            spec = Gem::Specification.load(gs)
+            spec = SpecUtils.load_gemspec(gs, isolate: true)
             return spec if spec
-          rescue StandardError
+          rescue SystemExit, StandardError
             nil
           end
         end
@@ -697,10 +811,8 @@ module Scint
         absolute_gemspec = File.join(worktree, gemspec_path)
         return nil unless File.exist?(absolute_gemspec)
 
-        Dir.chdir(File.dirname(absolute_gemspec)) do
-          Gem::Specification.load(absolute_gemspec)
-        end
-      rescue StandardError
+        SpecUtils.load_gemspec(absolute_gemspec, isolate: true)
+      rescue SystemExit, StandardError
         nil
       end
 
@@ -786,7 +898,7 @@ module Scint
         spec = entry.spec
         source = spec.source
         if git_source?(source)
-          prepare_git_checkout(spec, cache, fetch: false)
+          ensure_git_repo_for_spec(spec, cache, fetch: true)
           return
         end
         source_uri = source.to_s
@@ -827,21 +939,34 @@ module Scint
         # Git gems are extracted from the cached checkout; path gems are
         # linked directly from local source.
         if git_source?(spec.source)
-          materialize_git_spec(entry, cache)
+          assemble_git_spec(entry, cache, fetch: false)
           return
         end
         return if source_uri.start_with?("/") || !source_uri.start_with?("http")
 
-        extracted = cache.extracted_path(spec)
-        return if Dir.exist?(extracted)
+        return if Cache::Validity.cached_valid?(spec, cache)
 
         dest_path = cache.inbound_path(spec)
         raise InstallError, "Missing cached gem file for #{spec.name}: #{dest_path}" unless File.exist?(dest_path)
 
-        FS.mkdir_p(extracted)
-        pkg = GemPkg::Package.new
-        result = pkg.extract(dest_path, extracted)
-        cache_gemspec(spec, result[:gemspec], cache)
+        assembling = cache.assembling_path(spec)
+        tmp = "#{assembling}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+        begin
+          FileUtils.rm_rf(assembling)
+          FileUtils.rm_rf(tmp)
+          FS.mkdir_p(File.dirname(assembling))
+
+          pkg = GemPkg::Package.new
+          result = pkg.extract(dest_path, tmp)
+          FS.atomic_move(tmp, assembling)
+          cache_gemspec(spec, result[:gemspec], cache)
+
+          unless Installer::ExtensionBuilder.needs_build?(spec, assembling)
+            promote_assembled_gem(spec, cache, assembling, result[:gemspec], extensions: false)
+          end
+        ensure
+          FileUtils.rm_rf(tmp) if tmp && File.exist?(tmp)
+        end
       end
 
       def git_source?(source)
@@ -870,16 +995,12 @@ module Scint
       def prepare_git_source(entry, cache)
         # Legacy helper used by tests/callers that expect git download+extract
         # in a single step.
-        spec = entry.spec
-        checkout_dir, resolved_revision, _uri = prepare_git_checkout(spec, cache, fetch: true)
-        materialize_git_spec(entry, cache, checkout_dir: checkout_dir, resolved_revision: resolved_revision)
+        assemble_git_spec(entry, cache, fetch: true)
       end
 
-      def prepare_git_checkout(spec, cache, fetch: false)
+      def ensure_git_repo_for_spec(spec, cache, fetch:)
         source = spec.source
-        uri, revision = git_source_ref(source)
-        submodules = git_source_submodules?(source)
-
+        uri, _revision = git_source_ref(source)
         bare_repo = cache.git_path(uri)
 
         # Serialize all git operations per bare repo — git uses index.lock
@@ -891,92 +1012,100 @@ module Scint
             clone_git_repo(uri, bare_repo)
             fetch_git_repo(bare_repo)
           end
-
-          resolved_revision = resolve_git_revision(bare_repo, revision)
-          incoming_checkout = cache.git_checkout_path(uri, resolved_revision)
-          materialize_git_checkout(
-            bare_repo,
-            incoming_checkout,
-            resolved_revision,
-            spec,
-            uri,
-            submodules: submodules,
-          )
-          [incoming_checkout, resolved_revision, uri]
         end
+
+        bare_repo
       end
 
-      def materialize_git_spec(entry, cache, checkout_dir: nil, resolved_revision: nil)
+      def assemble_git_spec(entry, cache, fetch: true)
         spec = entry.spec
-        checkout_dir, resolved_revision, _uri = prepare_git_checkout(spec, cache, fetch: false) unless checkout_dir && resolved_revision
-        gem_root = resolve_git_gem_subdir(checkout_dir, spec)
-        extracted = cache.extracted_path(spec)
-        marker = git_checkout_marker_path(extracted)
-        if Dir.exist?(extracted) &&
-           File.exist?(marker) &&
-           File.read(marker).strip == resolved_revision &&
-           git_spec_layout_current?(extracted, spec)
-          return
-        end
+        return if Cache::Validity.cached_valid?(spec, cache)
 
-        tmp = "#{extracted}.#{Process.pid}.#{Thread.current.object_id}.tmp"
-        begin
-          FileUtils.rm_rf(tmp)
-          FS.clone_tree(gem_root, tmp)
+        source = spec.source
+        uri, revision = git_source_ref(source)
+        submodules = git_source_submodules?(source)
 
-          FileUtils.rm_rf(extracted)
-          FS.atomic_move(tmp, extracted)
-          FS.atomic_write(marker, "#{resolved_revision}\n")
-        ensure
-          FileUtils.rm_rf(tmp) if tmp && File.exist?(tmp)
-        end
-      end
+        bare_repo = cache.git_path(uri)
 
-      def git_spec_layout_current?(extracted_path, spec)
-        File.exist?(File.join(extracted_path, "#{spec.name}.gemspec"))
-      rescue StandardError
-        false
-      end
+        # Serialize all git operations per bare repo — git uses index.lock
+        # and can't handle concurrent checkouts from the same repo.
+        git_mutex_for(bare_repo).synchronize do
+          tmp_checkout = nil
+          tmp_assembled = nil
 
-      def materialize_git_checkout(bare_repo, checkout_dir, resolved_revision, spec, uri, submodules: false)
-        marker = git_checkout_marker_path(checkout_dir)
-        if Dir.exist?(checkout_dir) && File.exist?(marker)
-          checkout_marker = parse_git_checkout_marker(marker)
-          marker_revision = checkout_marker[:revision]
-          marker_submodules = checkout_marker[:submodules]
+          begin
+            if Dir.exist?(bare_repo)
+              fetch_git_repo(bare_repo) if fetch
+            else
+              clone_git_repo(uri, bare_repo)
+              fetch_git_repo(bare_repo)
+            end
 
-          # Legacy markers only recorded revision. If this source now requires
-          # submodules, force a refresh so previously incomplete checkouts are
-          # not reused.
-          return if marker_revision == resolved_revision && (!submodules || marker_submodules == true)
-        end
+            resolved_revision = resolve_git_revision(bare_repo, revision)
+            assembling = cache.assembling_path(spec)
+            tmp_checkout = "#{assembling}.checkout.#{Process.pid}.#{Thread.current.object_id}.tmp"
+            tmp_assembled = "#{assembling}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+            promoter = cache_promoter(cache)
+
+            FileUtils.rm_rf(assembling)
+            FileUtils.rm_rf(tmp_checkout)
+            FileUtils.rm_rf(tmp_assembled)
+            FS.mkdir_p(File.dirname(assembling))
+
+            promoter.validate_within_root!(cache.root, assembling, label: "assembling")
+            promoter.validate_within_root!(cache.root, tmp_checkout, label: "git-checkout")
+            promoter.validate_within_root!(cache.root, tmp_assembled, label: "git-assembled")
+
+            if submodules
+              checkout_git_tree_with_submodules(
+                bare_repo,
+                tmp_checkout,
+                resolved_revision,
+                spec,
+                uri,
+              )
+            else
+              checkout_git_tree(
+                bare_repo,
+                tmp_checkout,
+                resolved_revision,
+                spec,
+                uri,
+              )
+            end
 
-        tmp = "#{checkout_dir}.#{Process.pid}.#{Thread.current.object_id}.tmp"
-        begin
-          FileUtils.rm_rf(tmp)
-          if submodules
-            checkout_git_tree_with_submodules(
-              bare_repo,
-              tmp,
-              resolved_revision,
-              spec,
-              uri,
-            )
-          else
-            checkout_git_tree(
-              bare_repo,
-              tmp,
-              resolved_revision,
-              spec,
-              uri,
-            )
-          end
+            # Remove .git artifacts from checkout so assembled output is
+            # deterministic and contains no git internals.
+            Dir.glob(File.join(tmp_checkout, "**", ".git"), File::FNM_DOTMATCH).each do |path|
+              FileUtils.rm_rf(path)
+            end
 
-          FileUtils.rm_rf(checkout_dir)
-          FS.atomic_move(tmp, checkout_dir)
-          FS.atomic_write(marker, format_git_checkout_marker(resolved_revision, submodules: submodules))
-        ensure
-          FileUtils.rm_rf(tmp) if tmp && File.exist?(tmp)
+            gem_root = resolve_git_gem_subdir(tmp_checkout, spec)
+            gem_rel = git_relative_root(tmp_checkout, gem_root)
+            dest_root = tmp_assembled
+            dest_path = gem_rel.empty? ? dest_root : File.join(dest_root, gem_rel)
+
+            promoter.validate_within_root!(cache.root, dest_path, label: "git-dest")
+
+            FS.clone_tree(gem_root, dest_path)
+            copy_gemspec_root_files(tmp_checkout, gem_root, dest_root, spec)
+            FS.atomic_move(tmp_assembled, assembling)
+
+            gem_subdir = begin
+              resolve_git_gem_subdir(assembling, spec)
+            rescue InstallError
+              assembling
+            end
+            gemspec = read_gemspec_from_extracted(gem_subdir, spec)
+            cache_gemspec(spec, gemspec, cache) if gemspec
+
+            unless Installer::ExtensionBuilder.needs_build?(spec, assembling)
+              promote_assembled_gem(spec, cache, assembling, gemspec, extensions: false)
+            end
+          ensure
+            FileUtils.rm_rf(tmp_checkout) if tmp_checkout && File.exist?(tmp_checkout)
+            FileUtils.rm_rf(tmp_assembled) if tmp_assembled && File.exist?(tmp_assembled)
+          end
         end
       end
 
@@ -993,6 +1122,55 @@ module Scint
         source.respond_to?(:submodules) && !!source.submodules
       end
 
+      def copy_gemspec_root_files(repo_root, gem_root, dest_root, spec)
+        repo_root = File.expand_path(repo_root.to_s)
+        gem_root = File.expand_path(gem_root.to_s)
+        return if repo_root == gem_root
+
+        gemspec_path = git_gemspec_path_for_root(gem_root, spec)
+        return unless gemspec_path && File.exist?(gemspec_path)
+
+        content = File.read(gemspec_path) rescue nil
+        return unless content
+
+        root_files = git_root_files_from_gemspec(content)
+        root_files.each do |file|
+          source = File.join(repo_root, file)
+          next unless File.file?(source)
+
+          dest = File.join(dest_root, file)
+          next if File.exist?(dest)
+
+          FS.clonefile(source, dest)
+        end
+      end
+
+      def git_gemspec_path_for_root(gem_root, spec)
+        if spec && spec.respond_to?(:name)
+          candidate = File.join(gem_root, "#{spec.name}.gemspec")
+          return candidate if File.exist?(candidate)
+        end
+
+        Dir.glob(File.join(gem_root, "*.gemspec")).first
+      end
+
+      def git_root_files_from_gemspec(content)
+        files = ["RAILS_VERSION", "VERSION"]
+        files.select { |file| content.include?(file) }
+      end
+
+      def git_relative_root(repo_root, gem_root)
+        repo_root = File.expand_path(repo_root.to_s)
+        gem_root = File.expand_path(gem_root.to_s)
+        return "" if repo_root == gem_root
+
+        if gem_root.start_with?("#{repo_root}/")
+          return gem_root.delete_prefix("#{repo_root}/")
+        end
+
+        File.basename(gem_root)
+      end
+
       def checkout_git_tree(bare_repo, destination, resolved_revision, spec, uri)
         FileUtils.mkdir_p(destination)
         _out, err, status = git_capture3(
@@ -1093,64 +1271,59 @@ module Scint
         Open3.capture3("git", "-c", "core.fsmonitor=false", *args)
       end
 
-      def git_checkout_marker_path(dir)
-        "#{dir}.scint_git_revision"
-      end
-
-      def parse_git_checkout_marker(path)
-        content = File.read(path)
-        revision = nil
-        submodules = nil
-
-        content.each_line do |line|
-          key, value = line.strip.split("=", 2)
-          case key
-          when "revision"
-            revision = value
-          when "submodules"
-            submodules = (value == "1" || value == "true")
-          end
-        end
-
-        if revision.nil?
-          # Legacy format: raw revision only.
-          revision = content.strip
-        end
+      def compile_slots_for(worker_count)
+        # Scale compile concurrency with available CPUs.
+        # Most native extensions have 1-3 source files and don't benefit from
+        # high make -j; running more concurrent builds is more effective.
+        # Each slot gets cpu_count/slots make jobs (see adaptive_make_jobs).
+        workers = [worker_count.to_i, 1].max
+        override = positive_integer_env("SCINT_COMPILE_CONCURRENCY")
+        return [override, workers].min if override
 
-        { revision: revision, submodules: submodules }
-      rescue StandardError
-        { revision: nil, submodules: nil }
+        cpus = Platform.cpu_count
+        # Aim for 8 make-jobs per slot → slots = cpus / 8, clamped.
+        slots = cpus / 8
+        slots = [[slots, 2].max, workers].min
+        slots
       end
 
-      def format_git_checkout_marker(revision, submodules:)
-        "revision=#{revision}\nsubmodules=#{submodules ? 1 : 0}\n"
+      def git_slots_for(worker_count)
+        workers = [worker_count.to_i, 1].max
+        override = positive_integer_env("SCINT_GIT_CONCURRENCY")
+        slots = override || workers
+        [[slots, workers].min, 1].max
       end
 
-      def compile_slots_for(worker_count)
-        # Keep compile parallelism conservative: at most 2 native builds.
-        # Small pools stay single-lane; larger pools can run two builds.
-        workers = worker_count.to_i
-        return 1 if workers <= 6
-
-        2
-      end
-
-      def install_task_limits(worker_count, compile_slots)
+      def install_task_limits(worker_count, compile_slots, git_slots = worker_count)
         # Leave headroom for compile and binstub lanes so link/download
         # throughput cannot fully starve them.
-        io_cpu_limit = [worker_count - compile_slots - 1, 1].max
+        workers = [worker_count.to_i, 1].max
+        io_cpu_limit = [workers - compile_slots - 1, 1].max
         # Keep download in-flight set bounded so fail-fast exits quickly on
         # auth/source errors instead of queueing a large burst.
         download_limit = [io_cpu_limit, 8].min
+        git_limit = [[git_slots.to_i, 1].max, workers].min
         {
           download: download_limit,
           extract: io_cpu_limit,
           link: io_cpu_limit,
+          git_clone: git_limit,
           build_ext: compile_slots,
           binstub: 1,
         }
       end
 
+      def positive_integer_env(key)
+        raw = ENV[key]
+        return nil if raw.nil? || raw.empty?
+
+        value = Integer(raw, exception: false)
+        return nil unless value
+        return nil if value <= 0
+
+        value
+      end
+
       def display_bundle_path(path)
         return path if path.start_with?("/", "./", "../")
 
@@ -1297,10 +1470,21 @@ module Scint
             source_str
           end
         else
-          base = entry.cached_path || cache.extracted_path(entry.spec)
-          if git_source?(entry.spec.source) && Dir.exist?(base)
+          cached_dir = cache.cached_path(entry.spec)
+          assembling = cache.assembling_path(entry.spec)
+          base = if entry.cached_path
+            entry.cached_path
+          elsif Cache::Validity.cached_valid?(entry.spec, cache)
+            cached_dir
+          elsif Dir.exist?(assembling)
+            assembling
+          else
+            nil
+          end
+
+          if git_source?(entry.spec.source) && base && Dir.exist?(base)
             resolve_git_gem_subdir(base, entry.spec)
-          elsif path_source?(entry.spec.source) && Dir.exist?(base)
+          elsif path_source?(entry.spec.source) && base && Dir.exist?(base)
             begin
               resolve_path_gem_subdir(base, entry.spec)
             rescue InstallError
@@ -1371,19 +1555,18 @@ module Scint
           from_cache: true,
         )
         Installer::Linker.link_files(prepared, bundle_path)
-        # If this gem has a cached native build, materialize it during link.
-        # This lets reinstalling into a fresh .bundle skip build_ext entirely.
-        Installer::ExtensionBuilder.link_cached_build(prepared, bundle_path, cache)
       end
 
       def build_extensions(entry, cache, bundle_path, progress = nil, compile_slots: 1)
+        spec = entry.spec
         extracted = extracted_path_for_entry(entry, cache)
-        gemspec = load_gemspec(extracted, entry.spec, cache)
+        gemspec = load_gemspec(extracted, spec, cache)
+        promote_after_build = assembling_path?(extracted, cache)
 
-        sync_build_env_dependencies(entry.spec, bundle_path, cache)
+        sync_build_env_dependencies(spec, bundle_path, cache)
 
         prepared = PreparedGem.new(
-          spec: entry.spec,
+          spec: spec,
           extracted_path: extracted,
           gemspec: gemspec,
           from_cache: true,
@@ -1394,8 +1577,24 @@ module Scint
           bundle_path,
           cache,
           compile_slots: compile_slots,
-          output_tail: ->(lines) { progress&.on_build_tail(entry.spec.name, lines) },
+          output_tail: ->(lines) { progress&.on_build_tail(spec.name, lines) },
         )
+
+        ruby_dir = Platform.ruby_install_dir(bundle_path)
+        bundle_gem_dir = File.join(ruby_dir, "gems", SpecUtils.full_name(spec))
+        if Dir.exist?(bundle_gem_dir)
+          Installer::ExtensionBuilder.sync_extensions_into_gem(extracted, bundle_gem_dir)
+          File.write(File.join(bundle_gem_dir, Installer::ExtensionBuilder::BUILD_MARKER), "")
+        end
+
+        return unless promote_after_build
+
+        promote_assembled_gem(spec, cache, extracted, gemspec, extensions: true)
+      rescue StandardError
+        if promote_after_build && extracted && Dir.exist?(extracted)
+          FileUtils.rm_rf(extracted)
+        end
+        raise
       end
 
       def sync_build_env_dependencies(spec, bundle_path, cache)
@@ -1460,6 +1659,12 @@ module Scint
           return cached
         end
 
+        direct = read_gemspec_from_extracted(extracted_path, spec)
+        if direct
+          @gemspec_cache_lock.synchronize { @gemspec_cache[cache_key] = direct }
+          return direct
+        end
+
         inbound = cache.inbound_path(spec)
         return nil unless File.exist?(inbound)
 
@@ -1473,49 +1678,90 @@ module Scint
         end
       end
 
+      def read_gemspec_from_extracted(extracted_dir, spec)
+        return nil unless extracted_dir && Dir.exist?(extracted_dir)
+
+        pattern = File.join(extracted_dir, "*.gemspec")
+        candidates = Dir.glob(pattern)
+        return nil if candidates.empty?
+
+        load_gemspec_file(candidates.first, spec)
+      end
+
+      # Load a .gemspec file, temporarily injecting VERSION env var for gems
+      # like kgio/unicorn that use `ENV["VERSION"] or abort` in their gemspec.
+      def load_gemspec_file(path, spec = nil)
+        version = spec.respond_to?(:version) ? spec.version.to_s : nil
+        old_version = ENV["VERSION"]
+        begin
+          ENV["VERSION"] = version if version && !ENV["VERSION"]
+          SpecUtils.load_gemspec(path, isolate: true)
+        rescue SystemExit, StandardError
+          nil
+        ensure
+          ENV["VERSION"] = old_version
+        end
+      end
+
       def bulk_prelink_gem_files(entries, cache, bundle_path)
-        # Keep small installs simple; batching is for large warm-path runs.
         return if entries.length < 32
 
         ruby_dir = File.join(bundle_path, "ruby", RUBY_VERSION.split(".")[0, 2].join(".") + ".0")
         gems_dir = File.join(ruby_dir, "gems")
+        cache_abi_dir = cache.cached_abi_dir
 
-        sources = entries.filter_map do |entry|
+        gem_names = []
+        entries.each do |entry|
           next unless entry.action == :link || entry.action == :build_ext
 
-          extracted = cache.extracted_path(entry.spec)
+          source_dir = entry.cached_path
+          next unless source_dir
+
           full_name = cache.full_name(entry.spec)
-          next unless File.basename(extracted) == full_name
-          next unless Dir.exist?(extracted)
+          next unless File.basename(source_dir) == full_name
+          next unless Dir.exist?(source_dir)
           next if Dir.exist?(File.join(gems_dir, full_name))
 
-          extracted
+          gem_names << full_name
         end
-        return if sources.empty?
 
-        FS.clone_many_trees(sources, gems_dir)
+        return if gem_names.empty?
+
+        if ENV["SCINT_TIMING"]
+          $stderr.puts "  [timing] prelink: #{gem_names.size} gems via linker"
+        end
+
+        FS.bulk_link_gems(cache_abi_dir, gems_dir, gem_names)
       rescue StandardError => e
         $stderr.puts("bulk prelink warning: #{e.message}") if ENV["SCINT_DEBUG"]
       end
 
       def load_cached_gemspec(spec, cache, extracted_path)
-        path = cache.spec_cache_path(spec)
-        return nil unless File.exist?(path)
+        paths = [cache.cached_spec_path(spec)]
 
-        data = File.binread(path)
-        gemspec = if data.start_with?("---")
-          Gem::Specification.from_yaml(data)
-        else
-          begin
-            Marshal.load(data)
-          rescue StandardError
+        paths.each do |path|
+          next unless File.exist?(path)
+
+          data = File.binread(path)
+          gemspec = if data.start_with?("# -*- encoding")
+            # Ruby format (to_ruby output) — most reliable, preserves require_paths
+            Gem::Specification.load(path)
+          elsif data.start_with?("---")
+            data.force_encoding("UTF-8") if data.encoding != Encoding::UTF_8
             Gem::Specification.from_yaml(data)
+          else
+            begin
+              Marshal.load(data)
+            rescue StandardError
+              data.force_encoding("UTF-8") if data.encoding != Encoding::UTF_8
+              Gem::Specification.from_yaml(data)
+            end
           end
+          return gemspec if cached_gemspec_valid?(gemspec, extracted_path)
         end
-        return gemspec if cached_gemspec_valid?(gemspec, extracted_path)
 
         nil
-      rescue StandardError
+      rescue SystemExit, StandardError
         nil
       end
 
@@ -1549,12 +1795,108 @@ module Scint
       end
 
       def cache_gemspec(spec, gemspec, cache)
-        path = cache.spec_cache_path(spec)
-        FS.atomic_write(path, gemspec.to_yaml)
+        path = cache.cached_spec_path(spec)
+        content = if gemspec.respond_to?(:to_ruby)
+          gemspec.to_ruby
+        else
+          gemspec.to_yaml
+        end
+        FS.atomic_write(path, content)
       rescue StandardError
         # Non-fatal: we'll read metadata from .gem next time.
       end
 
+      def cache_promoter(cache)
+        @cache_promoter ||= Installer::Promoter.new(root: cache.root)
+      end
+
+      def assembling_path?(path, cache)
+        return false if path.nil? || path.empty?
+
+        root = File.expand_path(cache.assembling_dir)
+        candidate = File.expand_path(path)
+        candidate == root || candidate.start_with?("#{root}/")
+      end
+
+      def promote_assembled_gem(spec, cache, assembling_path, gemspec, extensions:)
+        return unless assembling_path && Dir.exist?(assembling_path)
+
+        cached_dir = cache.cached_path(spec)
+        promoter = cache_promoter(cache)
+        lock_key = "#{Platform.abi_key}-#{cache.full_name(spec)}"
+
+        promoter.validate_within_root!(cache.root, assembling_path, label: "assembling")
+        promoter.validate_within_root!(cache.root, cached_dir, label: "cached")
+
+        begin
+          result = nil
+          promoter.with_staging_dir(prefix: "cached") do |staging|
+            FS.clone_tree(assembling_path, staging)
+            manifest = build_cached_manifest(spec, cache, staging, extensions: extensions)
+            Cache::Manifest.write_dotfiles(staging, manifest)
+            spec_payload = gemspec ? gemspec.to_ruby : nil
+            result = promoter.promote_tree(
+              staging_path: staging,
+              target_path: cached_dir,
+              lock_key: lock_key,
+            )
+            if result == :promoted
+              write_cached_metadata(spec, cache, spec_payload, manifest)
+            end
+            FileUtils.rm_rf(assembling_path) if Dir.exist?(assembling_path)
+          end
+          result
+        rescue StandardError
+          FileUtils.rm_rf(cached_dir) if Dir.exist?(cached_dir)
+          raise
+        end
+      end
+
+      def write_cached_metadata(spec, cache, spec_payload, manifest)
+        spec_path = cache.cached_spec_path(spec)
+        manifest_path = cache.cached_manifest_path(spec)
+        FS.mkdir_p(File.dirname(spec_path))
+
+        FS.atomic_write(spec_path, spec_payload) if spec_payload
+        Cache::Manifest.write(manifest_path, manifest)
+      end
+
+      def build_cached_manifest(spec, cache, gem_dir, extensions:)
+        Cache::Manifest.build(
+          spec: spec,
+          gem_dir: gem_dir,
+          abi_key: Platform.abi_key,
+          source: manifest_source_for(spec),
+          extensions: extensions,
+        )
+      end
+
+      def manifest_source_for(spec)
+        source = spec.source
+        if source.is_a?(Source::Git)
+          {
+            "type" => "git",
+            "uri" => source.uri.to_s,
+            "revision" => source.revision || source.ref || source.branch || source.tag,
+          }.compact
+        elsif source.is_a?(Source::Path)
+          {
+            "type" => "path",
+            "path" => File.expand_path(source.path.to_s),
+            "uri" => source.path.to_s,
+          }
+        else
+          source_str = source.to_s
+          if source_str.start_with?("http://", "https://")
+            { "type" => "rubygems", "uri" => source_str }
+          elsif path_source?(source)
+            { "type" => "path", "path" => File.expand_path(source_str), "uri" => source_str }
+          else
+            { "type" => "rubygems", "uri" => source_str }
+          end
+        end
+      end
+
       # --- Lockfile + runtime config ---
 
       def write_lockfile(resolved, gemfile, lockfile = nil)
@@ -1963,10 +2305,10 @@ module Scint
       def read_require_paths(spec_file)
         return ["lib"] unless File.exist?(spec_file)
 
-        gemspec = Gem::Specification.load(spec_file)
+        gemspec = SpecUtils.load_gemspec(spec_file)
         paths = Array(gemspec&.require_paths).reject(&:empty?)
         paths.empty? ? ["lib"] : paths
-      rescue StandardError
+      rescue SystemExit, StandardError
         ["lib"]
       end
 
@@ -2020,8 +2362,12 @@ module Scint
 
           # Global cache artifacts.
           FileUtils.rm_f(cache.inbound_path(spec))
-          FileUtils.rm_rf(cache.extracted_path(spec))
+          FileUtils.rm_rf(cache.assembling_path(spec))
+          FileUtils.rm_rf(cache.cached_path(spec))
+          FileUtils.rm_f(cache.cached_spec_path(spec))
+          FileUtils.rm_f(cache.cached_manifest_path(spec))
           FileUtils.rm_f(cache.spec_cache_path(spec))
+          FileUtils.rm_rf(cache.extracted_path(spec))
           FileUtils.rm_rf(cache.ext_path(spec))
 
           # Local bundle artifacts.
@@ -2111,6 +2457,12 @@ module Scint
           when "--path"
             @path = @argv[i + 1]
             i += 2
+          when "--without"
+            @without_groups = @argv[i + 1]&.split(/[\s:,]+/)&.map(&:to_sym) || []
+            i += 2
+          when "--with"
+            @with_groups = @argv[i + 1]&.split(/[\s:,]+/)&.map(&:to_sym) || []
+            i += 2
           when "--verbose"
             @verbose = true
             i += 1
@@ -2121,6 +2473,32 @@ module Scint
             i += 1
           end
         end
+
+        # Also read BUNDLE_WITHOUT / BUNDLE_WITH env vars (Bundler compat)
+        if !@without_groups && ENV["BUNDLE_WITHOUT"]
+          @without_groups = ENV["BUNDLE_WITHOUT"].split(/[\s:,]+/).map(&:to_sym)
+        end
+        if !@with_groups && ENV["BUNDLE_WITH"]
+          @with_groups = ENV["BUNDLE_WITH"].split(/[\s:,]+/).map(&:to_sym)
+        end
+
+        # Read from .bundle/config if present
+        load_bundle_config_groups if !@without_groups && !@with_groups
+      end
+
+      def load_bundle_config_groups
+        config_path = File.join(".bundle", "config")
+        return unless File.exist?(config_path)
+
+        config = YAML.safe_load(File.read(config_path)) rescue nil
+        return unless config.is_a?(Hash)
+
+        if config["BUNDLE_WITHOUT"] && !@without_groups
+          @without_groups = config["BUNDLE_WITHOUT"].to_s.split(/[\s:]+/).map(&:to_sym)
+        end
+        if config["BUNDLE_WITH"] && !@with_groups
+          @with_groups = config["BUNDLE_WITH"].to_s.split(/[\s:]+/).map(&:to_sym)
+        end
       end
     end
   end