gemvault 0.1.5 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 100a593cb7221bf6cc5842ad00c67335809a351905251a6088c3698b41fa9b95
-  data.tar.gz: 6645dea254fbdd76dbd2fc1de7f8471f27185d205d5a23e038665d060f253cfa
+  metadata.gz: 6a1d5d0c990e232ac54514f5837db4224d92b127175f370a3443c8d15d44099f
+  data.tar.gz: ab40029793c2dd05206b9812e27da8921eb7fc478164f71fa7485296d5455f15
 SHA512:
-  metadata.gz: a973851f5b6b7b9eaa48fcf21a25660bc3770d36c992ff758e4b9ace061a64e5b2cdd6a0270ee335ca3d2a6cf1b80f842b69e6768a98fd85741ec91141786a60
-  data.tar.gz: 16b6a27438852230e49569493d526efdcf6b07f499137cdcb73a18b29ef06bd89ddf2def281649109bbf1cfbacce1e7e3d4bfdddae44984855fa378e1b79c51f
+  metadata.gz: 916b9a114590c9eb5fa3a377d59e9639c33a28e948429b8bac18399473eba0dcacf6711a9808106e3f91348945d71ebd051c1f65fe05239f9804289f56fcf859
+  data.tar.gz: 9ea36ee67195ca7f7a8bafd7ebc8658e000b72bcbf72356e3a2266c2f8d2679e0d8f5212f0b977a36a36c95441152f2dabae8ada78c5831770c0cd3498c4253d

data/.containerignore

@@ -0,0 +1,10 @@
+.bundle
+.git
+gemv
+pkg
+tmp
+vendor
+*.gem
+*.gemv
+references
+references/

data/.rubocop.yml

@@ -17,10 +17,11 @@ plugins:
 
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 4.0
+  TargetRubyVersion: 3.4.8
   Exclude:
     - bin/*
     - vendor/**/*
+    - references/**/*
     - lib/core_ext/**/*
     - rakelib/project.rb
     - rakelib/project_version.rb
@@ -137,6 +138,13 @@ Style/ArgumentsForwarding:
 Style/RedundantBegin:
   Enabled: false
 
+# Data value objects that carry constants, nested value types, or any class
+# body read best as `class X < Data.define(...)`. The assignment form the cop
+# prefers leaks block-level constants to the enclosing scope and forces a
+# `.freeze` (Style/MutableConstant) on the class. Permitted by David.
+Style/DataInheritance:
+  Enabled: false
+
 # Compact class names are fine for small files and tests.
 Style/ClassAndModuleChildren:
   Enabled: false

data/CHANGELOG.md

@@ -19,10 +19,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   preserving every gem and timestamp, writing a `.bak` backup by default, with
   `--dry-run` and `--no-backup` flags. It is a no-op on an already-current vault.
 
+- All CLI commands accept `vault://` and `file://` locators wherever they take
+  a vault path, e.g. `gemvault list vault:///path/to/myvault.gemv`; resolution
+  is shared with the RubyGems source via `Gemvault::VaultPath` (issue #9).
+
+### Fixed
+- `bundle plugin install bundler-source-vault` no longer dies with
+  `LoadError: cannot load such file -- bundler/plugin/vault_source`. The shim's
+  `plugins.rb` now derives the gem root from its own installed location (local
+  plugin root, global plugin root, or plain GEM_HOME), registers any spec dirs
+  RubyGems is not searching, and resets RubyGems' spec stub cache when it
+  predates the just-installed gems (issue #10).
+- `bundle exec` no longer fails Gemfile parsing with `Could not find 'bundler'
+  (>= 2.0)` under `path: vendor` on rubies that ship bundler as a regular gem:
+  gemvault no longer declares `bundler` as a runtime dependency (issue #12).
+- Vault gems whose versions carry a non-numeric suffix (e.g. `0.2.1.patch1`)
+  install from a vault with `gem install --pre`, matching RubyGems' prerelease
+  semantics (issue #6).
+- Repeated `bundle install` no longer fails with `cannot load such file --
+  bundler/plugin/vault_source` on machines that have gemvault installed
+  system-wide. Bundler skips installing a plugin dependency already present on
+  the ambient GEM_PATH, so the plugin root holds only the shim; once the app
+  bundle is populated Bundler restricts GEM_PATH to it and the ambient copy
+  falls out of scope. The shim now locates gemvault's `lib` across every root
+  that can hold it — `Gem.default_path` above all, which is what RubyGems knows
+  about its own gem roots and therefore covers rubies from rbenv, asdf, chruby,
+  Homebrew and distros, none of which export `GEM_HOME` or `GEM_PATH` — and
+  loads it via `$LOAD_PATH` rather than gem activation (issue #13).
+- The vault source registers correctly when Bundler evaluates the plugin more
+  than once in a process; gemvault is resolved and required only on the first
+  evaluation, so `Gemvault::GemEntry` can no longer be defined twice from two
+  different gem roots (issue #13).
+- `gemvault new` no longer raises `cannot load such file -- json` on a stock
+  distro ruby. json backs the tarball vault's manifest, so every current-format
+  vault needs it; it is a default gem upstream but a separate package on
+  distros, where `dnf install ruby` leaves it absent. It is now a declared
+  runtime dependency.
+- Reading a vault through the Bundler source no longer raises `cannot load such
+  file -- json` either. Loading gemvault off `$LOAD_PATH` skips activation, and
+  therefore skips its dependencies, so the declared dependency alone did not
+  reach the plugin path. The shim now resolves gemvault's declared runtime
+  dependencies the same way it resolves gemvault and puts their require paths —
+  extension directories included — on `$LOAD_PATH`. A dependency it cannot find
+  is skipped rather than fatal, which is what activation could not do.
+- `bundle install` no longer fails with `Could not find 'command_kit' (~> 0.6)`
+  when gemvault is installed into the plugin root without its dependencies.
+  Loading the vault source no longer activates the gemvault gem, which would
+  demand the full runtime dependency set; `vault_source.rb` reaches the rest of
+  gemvault through `require_relative` alone (issue #13).
+
 ### Changed
 - `sqlite3` is no longer a runtime dependency. Gemvault runs dependency-free on
   the tarball path (including JRuby); `sqlite3` is loaded lazily only to read a
   legacy SQLite vault, with a clear error if it is not installed.
+- `bundler` is no longer a runtime dependency; the Bundler plugin always runs
+  inside an existing Bundler process, and the declared dependency broke gem
+  activation in restricted GEM_PATH contexts.
+- CI is unblocked (issue #11): RuboCop's TargetRubyVersion now matches the
+  gemspec's `required_ruby_version` floor (3.4.8), the previously-missing
+  `spec:integration` rake task exists alongside a non-integration `spec:core`, the
+  unit job no longer needs podman, and the integration job installs podman
+  when the runner image lacks it.
+- Reading a vault's `manifest.json` is now strict: an entry missing any required
+  field (`name`, `version`, `platform`, `created_at`, `sha256`, `encrypted`)
+  raises instead of silently loading `nil` fields, so a truncated or hand-edited
+  manifest fails fast rather than yielding a subtly broken vault.
 
 ### Deprecated
 - The SQLite vault format is deprecated and now **read-only**: existing SQLite

data/CLAUDE.md

@@ -17,6 +17,7 @@ Do NOT modify `.rubocop.yml` or use inline `# rubocop:disable` tags without expl
 9. ALWAYS write specs first. The workflow is: identify the domain concept (rule 5), write specs describing its behavior, then implement. No implementation without a failing spec.
 10. Integration specs are the first line of defense for CLI-tool bugs. For any bug reported from using the CLI tool (not the gemvault lib / Ruby API), the FIRST spec you write is an integration spec that reproduces the user's exact invocation — real subprocess, real vault, real exit code. Stub-heavy unit specs are complementary, not sufficient: they prove internal logic produces the expected value assuming surrounding wiring works, but a user's bug report is evidence the wiring didn't work.
 11. If an integration spec is not catching a reported CLI-tool bug, one of two things is true, and the fix starts by diagnosing which: (a) existing integration specs are not specific enough — extend them to cover the exact scenario before touching production code; or (b) the scenario is not spec'd at all, which means the work is not a bug fix but a new feature — write integration specs for the contract first (per rule 1), then implement.
+12. NEVER write to /tmp. Use /workspace/tmp
 
 ## Additional rules
 
@@ -25,7 +26,7 @@ Do NOT modify `.rubocop.yml` or use inline `# rubocop:disable` tags without expl
 
 ## Project Overview
 
-Multi-gem portable archives backed by SQLite. A single `.gemv` file contains multiple `.gem` files.
+Multi-gem portable archives. A single `.gemv` file is a tarball holding multiple `.gem` files plus a `manifest.json` index; legacy SQLite vaults are read-only.
 
 Two gems, one repo:
 
@@ -56,7 +57,7 @@ gem install --source file:///path/to/myvault.gemv foo
 ## Architecture
 
 - `gemvault.gemspec` — main gem spec (name: `gemvault`)
-- `lib/gemvault/vault.rb` — Core vault class (SQLite CRUD for gem blobs + specs)
+- `lib/gemvault/vault.rb` — Vault facade choosing a backend by file format (Tarvault current, legacy Dbvault read-only)
 - `lib/gemvault/cli.rb` — CLI dispatcher (new/add/list/remove/extract)
 - `lib/bundler/plugin/vault_source.rb` — Bundler `Plugin::API::Source` implementation
 - `lib/rubygems_plugin.rb` — RubyGems plugin: monkey-patches for `--source myvault.gemv` support
@@ -69,13 +70,22 @@ gem install --source file:///path/to/myvault.gemv foo
 
 ## Key Design Decisions
 
-- SQLite storage — random access, ACID, single file, inspectable with `sqlite3` CLI
+- Tar storage — portable, dependency-free, single file, inspectable with `tar`; legacy SQLite vaults readable via lazily-loaded sqlite3
 - Specs extracted from gem blobs at runtime (no separate spec storage)
 - Vault opened/closed per operation in the source plugin (no persistent connection)
 - `fetch_gemspec_files` checks installed state — Bundler computes `full_gem_path` as `dirname(loaded_from)`, so `loaded_from` must point inside the gem directory
 - `bundler-source-vault` name exists because Bundler auto-infers plugin name from `type: :vault` → `bundler-source-vault`
 - `file://` URIs stripped to plain paths in `Gem::Source::Vault#initialize`
 - Verbose logging via `Gem::UserInteraction#verbose` for `--verbose` support
+- `shim/plugins.rb` loads gemvault by putting its `lib` on `$LOAD_PATH`, never by
+  activating the gem. Bundler skips installing a plugin dependency already
+  present on the ambient GEM_PATH, so the plugin root often lacks gemvault, and
+  by load time GEM_PATH is restricted to the plugin root and the app bundle. The
+  shim therefore searches every root that can hold gemvault, including the ones
+  Bundler masked (`Bundler.original_env` GEM_HOME/GEM_PATH). Activation is
+  avoided because it demands gemvault's full runtime dependency set (command_kit),
+  which Bundler skips for the same reason — `vault_source.rb` reaches the rest of
+  gemvault through `require_relative` alone and needs none of it.
 
 ## Testing
 
@@ -83,17 +93,66 @@ gem install --source file:///path/to/myvault.gemv foo
 bundle exec rake test
 ```
 
-- `test/vault_test.rb` — 33 unit tests for Vault class
-- `test/vault_source_test.rb` — 17 unit tests for Bundler source plugin
-- `test/integration_test.rb` — 12 end-to-end bundle install tests
-- `test/cli_test.rb` — 32 CLI tests
-- `test/rubygems_plugin_test.rb` — 28 tests (source, resolver, monkey-patches, gem install integration, file:// URI, verbose logging)
+Minitest covers the library; RSpec covers the CLI and the containerized
+integration suite. `rake` (the default task) runs `test`, `spec` and `rubocop`.
 
-Integration tests use a manually-written Bundler plugin index to avoid rubygems.org resolution during testing.
+```bash
+bundle exec rake test            # minitest only
+bundle exec rake spec:core       # rspec, no containers
+bundle exec rake spec:integration # rspec, containers (builds the image first)
+bundle exec rake spec:build      # rebuild the container image
+bundle exec rake spec:teardown   # remove it
+```
+
+- `test/vault_test.rb` — unit tests for Vault class
+- `test/vault_source_test.rb` — unit tests for Bundler source plugin
+- `test/cli_test.rb` — CLI tests
+- `test/rubygems_plugin_test.rb` — source, resolver, monkey-patches, gem install integration, file:// URI, verbose logging
+- `spec/integration/` — end-to-end specs, each run inside a podman container
+- `spec/support/` — script fragments the integration specs assemble into those containers
+
+Integration specs serve the tree's own gems from a local gem index (`GemIndex`)
+to avoid rubygems.org resolution during testing.
+
+### Container fidelity — do not undo these
+
+The container has to look like a machine a user actually has. The `ruby` base
+image does not, and every way it differs has already hidden a real defect. These
+four are load-bearing; reverting any of them silently makes the suite green
+against something other than the code under test:
+
+1. **`bundler-source-vault` is NOT installed system-wide in `Dockerfile.test`.**
+   An ambient copy satisfies Bundler's plugin resolution without ever populating
+   the plugin root. Specs resolve the shim from the local gem index (`GemIndex`)
+   so they exercise the tree's shim. `gemvault` IS installed system-wide on
+   purpose — that is a real user's machine and the trigger for issue #13.
+2. **`BUNDLE_APP_CONFIG` is not set in the container.** The `ruby` image sets it
+   to `/usr/local/bundle`, which moves `Bundler::Plugin.root` out of the project
+   so no spec ever touches a project-local `.bundle/plugin`. Fedora sets it
+   nowhere; do not add it, and do not adopt a base image that does.
+3. **`GEM_HOME` and `GEM_PATH` are not exported in the container, and nothing
+   pins them.** Gems land in RubyGems' own default dirs. The `ruby` image
+   exports `GEM_HOME`; rubies from rbenv, asdf, chruby, Homebrew and distros
+   export nothing. Anything that reads gem roots back out of the environment
+   finds them on the image and finds nothing on a user's machine — that is what
+   made the first fix for issue #13 pass its specs while still failing for the
+   reporter. Neither `Dockerfile.test` nor `ContainerHelper#podman_run` should
+   grow an `ENV`/`-e` for either variable.
+4. **Bundler is pinned to the version users run, not the image's default gem.**
+   The plugin machinery under test is Bundler's own, so a stale default silently
+   tests different code.
+
+Fidelity is a property of the image, not of a script fragment: integration specs
+run only commands a user would actually type.
+
+If a spec fails only after removing a system-installed gem or an exported
+variable, the spec was passing for the wrong reason — fix the spec, not the
+container.
 
 ## Dependencies
 
-- `bundler` (>= 2.0) — runtime
+- `bundler` — NOT a dependency; the plugin always runs inside an existing Bundler process, and declaring it breaks gem activation under `bundle exec`'s restricted GEM_PATH
 - `command_kit` (~> 0.6) — runtime (CLI)
+- `json` (~> 2.0) — runtime; backs the tarball vault's manifest. A default gem upstream, but distros package it separately, so it is declared. Because the shim loads gemvault off `$LOAD_PATH` without activating it, it has to put json's require paths on `$LOAD_PATH` itself — see `dependency_specs` and `entries` in `shim/gemvault_load_path.rb`.
 - `sqlite3` (~> 2.0) — NOT a runtime dependency; loaded lazily only to read a legacy SQLite (Dbvault) vault. Declared in the Gemfile for development/test.
-- `minitest`, `rake` — development
+- `minitest`, `rspec`, `rake` — development

data/Dockerfile.test

@@ -1,15 +1,70 @@
-FROM docker.io/library/ruby:4.0.1-slim
+# A dev machine, not a packaging convenience.
+#
+# The official ruby image is not shaped like anything a user runs: it redirects
+# gems to /usr/local/bundle, exports GEM_HOME and BUNDLE_APP_CONFIG to match,
+# and freezes bundler at whatever shipped. Each of those differences hid a real
+# defect, and patching them one at a time only moved the blind spot. A distro
+# ruby has none of them: gems land in RubyGems' own default dirs, nothing is
+# exported, and bundler is a regular gem rather than a default one -- which is
+# also the shape that broke `bundle exec` in issue #12.
+FROM docker.io/library/fedora:44
 
-COPY . /tmp/build/
+# redhat-rpm-config carries the hardening specs Fedora's ruby-devel compiles
+# extensions against; without it every native gem fails in extconf. Any Fedora
+# machine that can build a gem has it.
+RUN dnf -y install --setopt=install_weak_deps=False \
+        ruby ruby-devel rubygem-bundler \
+        gcc make redhat-rpm-config sqlite-devel tar \
+    && dnf clean all
 
-RUN cd /tmp/build \
-    && gem build gemvault.gemspec \
-    && gem install --no-document gemvault-*.gem \
-    && cd shim \
-    && gem build bundler-source-vault.gemspec \
-    && gem install --no-document bundler-source-vault-*.gem \
-    && rm -rf /tmp/build
+# Keep this in step with the `BUNDLED WITH` line the project's own lockfile
+# carries. The plugin machinery these specs exercise is Bundler's own, so a
+# stale version silently tests different code.
+RUN gem install --no-document bundler -v 4.0.17
 
 # sqlite3 is not a gemvault runtime dependency; install it here so the upgrade
-# integration test can build a legacy SQLite (Dbvault) fixture to migrate.
+# integration test can read the committed legacy SQLite (Dbvault) fixture it
+# migrates.
 RUN gem install --no-document sqlite3
+
+# Gem files for integration specs that install the plugin from a local gem
+# index at spec runtime, kept for offline use: command_kit and json are
+# gemvault's runtime dependencies, and `bundle plugin install` resolves them
+# against the Gemfile's sources with GEM_PATH already narrowed to the plugin
+# root, so an ambient copy does not satisfy it -- every declared dependency has
+# to be servable from the index. The bundler gem lets specs reinstall bundler
+# in place.
+RUN mkdir -p /opt/gems \
+    && cd /opt/gems \
+    && gem fetch command_kit -v 0.6.0 \
+    && gem fetch json -v "~> 2.0" \
+    && gem fetch bundler -v "$(ruby -rbundler -e 'print Bundler::VERSION')"
+
+# The tree arrives as a bind mount at /src rather than a COPY: the build context
+# lives on a filesystem whose extended-attribute listing podman's copier cannot
+# read. `rake spec:build` supplies both the mount and SOURCE_DIGEST.
+#
+# A bind mount's contents are not part of podman's cache key, so without
+# SOURCE_DIGEST in the command line this layer is reused forever and the image
+# keeps whichever gemvault the tree held the first time it was built -- the
+# suite would then run green against code that is not under test. The digest
+# changes whenever the installed source does, which invalidates the layer. It is
+# last so that editing lib/ does not re-fetch the layers above.
+#
+# gemvault is installed system-wide because integration specs need the CLI to
+# build vault fixtures, and because that is what a real user's machine looks
+# like: `gem install gemvault` puts it on the ambient GEM_PATH. That ambient
+# copy is load-bearing for the plugin root specs -- Bundler skips installing a
+# plugin dependency that is already installed, so the plugin root only gets a
+# complete dependency set if gemvault puts it there itself.
+#
+# bundler-source-vault is deliberately NOT installed system-wide. An ambient
+# copy satisfies Bundler's plugin resolution without ever populating the plugin
+# root, which masks every plugin-root defect the integration specs exist to
+# catch. Specs install it from the local gem index built by GemIndex instead.
+ARG SOURCE_DIGEST=unset
+RUN test "$SOURCE_DIGEST" != unset \
+    && cd /src \
+    && gem build gemvault.gemspec -o /tmp/gemvault.gem \
+    && gem install --no-document /tmp/gemvault.gem \
+    && rm -f /tmp/gemvault.gem

data/README.md

@@ -1,10 +1,8 @@
 # Gemvault
 
-A gem server in a file. No HTTP. No infrastructure.
+A file that behaves like a private gem server.
 
-A `.gemv` file is a self-contained archive that contains Ruby gems. Commit it to your repo, drop it on S3, email it, put it on a USB drive — Bundler and RubyGems read from it directly. Private gems without running a server.
-
-New vaults are portable tarballs (no runtime dependencies, works on JRuby); the original SQLite format is still read transparently. See [Vault format versioning](#vault-format-versioning).
+You can commit it to your repo, drop it on S3, email it, put it on a USB drive, or whatever you feel like doing. Bundler and RubyGems read from it directly.
 
 ## Installation
 
@@ -29,7 +27,6 @@ end
 bundle install
 ```
 
-Bundler auto-discovers the `bundler-source-vault` plugin, installs it, and resolves gems from the vault alongside rubygems.org. No extra configuration.
 
 ### RubyGems CLI
 
@@ -67,12 +64,7 @@ gemvault upgrade myvault.gemv --no-backup  # skip the default myvault.gemv.bak c
 
 ## How It Works
 
-A `.gemv` file is a self-contained archive of gem metadata and raw `.gem` blobs. A current-format (tarball) vault has a `manifest.json` first entry followed by the `.gem` files, inspectable with standard tools:
-
-```bash
-tar -tf myvault.gemv                 # tarball (v2) vault
-sqlite3 myvault.gemv "SELECT name, version, platform FROM gems"   # SQLite (v1) vault
-```
+The gemv file is a tarball containing your .gem files and a json manifest. It has no dependencies other than the tar utilities that rubygems provides.
 
 When Bundler sees `type: :vault` in your Gemfile, it auto-installs the `bundler-source-vault` plugin from rubygems.org. The plugin implements the `Bundler::Plugin::API::Source` interface — it reads gemspecs from the vault, participates in dependency resolution, then extracts and installs gems from the vault's blob storage.
 

data/Rakefile

@@ -10,20 +10,43 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
+RSpec::Core::RakeTask.new("spec:core") do |t|
+  t.rspec_opts = "--tag ~integration"
+end
+
+RSpec::Core::RakeTask.new("spec:integration") do |t|
+  t.rspec_opts = "--tag integration"
+end
+
 require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 require "gempilot/version_task"
 Gempilot::VersionTask.new
 
-CACHED_IMAGE = "gemvault-test:latest".freeze
+require "digest"
+require_relative "spec/support/container_helper"
+
+CACHED_IMAGE = ContainerHelper::CACHED_IMAGE
+
+# Dockerfile.test reads the tree through a bind mount, whose contents podman
+# does not fold into its layer cache key. Feeding this digest in as a build arg
+# is what makes `rake spec:build` notice that the source changed.
+def image_source_digest
+  fingerprints = FileList["lib/**/*", "exe/*", "gemvault.gemspec"]
+                 .select { |path| File.file?(path) }.sort
+                 .map { |path| "#{path} #{Digest::SHA256.hexdigest(File.binread(path))}" }
+  Digest::SHA256.hexdigest(fingerprints.join("\n"))
+end
 
 def cached_image_exists?
   system("podman", "image", "exists", CACHED_IMAGE, out: File::NULL, err: File::NULL)
 end
 
 def build_cached_image
-  sh "podman", "build", "--network=host", "-t", CACHED_IMAGE, "-f", "Dockerfile.test", "."
+  sh "podman", "build", "--network=host", "-v", "#{__dir__}:/src:ro,z",
+     "--build-arg", "SOURCE_DIGEST=#{image_source_digest}",
+     "-t", CACHED_IMAGE, "-f", "Dockerfile.test", "."
 end
 
 def destroy_cached_image
@@ -59,6 +82,7 @@ namespace :shim do
 end
 
 Rake::Task[:spec].enhance ["spec:setup"]
+Rake::Task["spec:integration"].enhance ["spec:setup"]
 Rake::Task[:build].enhance ["shim:build"]
 Rake::Task[:release].enhance ["shim:release"]
 Rake::Task[:clobber].enhance ["spec:teardown"]

data/_claude/archives/issue-13-root-cause.md

@@ -0,0 +1,197 @@
+# Issue #13 — `cannot load such file -- bundler/plugin/vault_source`
+
+Line references are to the vendored RubyGems/Bundler checkout in
+`references/rubygems` (`bundler-v4.0.0-1207-gf912ac9b0b`).
+
+## Symptom
+
+```
+❯ bundle install
+Fetching gem metadata from https://rubygems.org/.......
+Resolving dependencies...
+Installing bundler-source-vault 0.2.0
+
+[!] There was an error parsing `Gemfile`: cannot load such file -- bundler/plugin/vault_source. Bundler cannot continue.
+
+ #  from /Users/davidgillis/repos/reversal-store/Gemfile:19
+ >  source "vendor/vendored.gemv", type: :vault do
+```
+
+Reported as permanent. `gemvault doctor`, `rm -rf .bundle/plugin`, `rm -f
+Gemfile.lock`, and the two combined all left it unchanged.
+
+## Reproduction
+
+The reporter's `.bundle` tarball showed a plugin root holding the shim and
+nothing else:
+
+```
+.bundle/plugin/cache/bundler-source-vault-0.2.0.gem
+.bundle/plugin/gems/bundler-source-vault-0.2.0/plugins.rb
+.bundle/plugin/specifications/bundler-source-vault-0.2.0.gemspec
+.bundle/plugin/index
+```
+
+No `gemvault` anywhere. Reproduced exactly with: gemvault installed on the
+ambient `GEM_PATH`, the shim not installed, a project-local `.bundle` with a
+configured bundle path, and `bundle install` run **twice**.
+
+## Root cause
+
+Three independent mechanisms compose. Each is fine alone.
+
+### 1. Bundler never puts gemvault in the plugin root
+
+`Source::Rubygems#install` (`lib/bundler/source/rubygems.rb:206`) short-circuits:
+
+```ruby
+if (spec.default_gem? && !cached_built_in_gem(...)) || (installed?(spec) && !options[:force])
+  print_using_message "Using #{version_message(spec, options[:previous_spec])}"
+  return nil
+end
+```
+
+`installed?` (`:484`) consults `installed_specs`. On any machine where
+`gem install gemvault` has run — that is, anyone who uses the CLI — the ambient
+copy satisfies it. Bundler prints "Using gemvault" and the plugin root receives
+the shim alone. Nothing is downloaded, so the plugin root's `cache/` has no
+gemvault either, which is exactly what the reporter's tarball showed.
+
+### 2. The ambient copy disappears precisely when it is needed
+
+`Plugin::Installer#install_all_sources` calls
+`Bundler.configure_gem_home_and_path(Plugin.root)`
+(`lib/bundler/plugin/installer.rb:100`), and `configure_gem_path`
+(`lib/bundler.rb:661`) does:
+
+```ruby
+unless use_system_gems?
+  Bundler::SharedHelpers.set_env "GEM_PATH", ""
+end
+```
+
+With a configured bundle path, `use_system_gems?` is false, so `GEM_PATH`
+becomes empty and `Gem.path` collapses to the bundle. The copy that made step 1
+"safe" is now out of scope.
+
+This is why the failure is **permanent and why it starts on the second run**.
+The first `bundle install` succeeds because the ambient gemvault is still
+visible. It populates the bundle path. From then on every `bundle install`
+narrows `GEM_PATH`, and every recovery step the reporter tried rebuilds the same
+incomplete plugin root.
+
+### 3. Locating gemvault is not sufficient — activation cannot survive here
+
+The obvious repair — find gemvault and load it — has a trap. Loading it via
+`$LOAD_PATH` skips activation, and therefore skips its dependencies. gemvault
+reads a vault manifest through `json` (`lib/gemvault/manifest.rb:1`), so the
+plugin dies later, at first vault read, instead of at load.
+
+Activating instead does not work, for two separate reasons:
+
+- **The path would be stripped one line before it is used.** `Runtime#setup`
+  (`lib/bundler/runtime.rb:12-38`) runs `clean_load_path` at line 16 and
+  `@definition.specs_for(groups)` at line 18 — and resolution is what asks the
+  vault source for specs. `clean_load_path`
+  (`lib/bundler/shared_helpers.rb:371-380`) rejects a `$LOAD_PATH` entry only
+  when `loaded_gem_paths.delete(p)` is truthy, and `loaded_gem_paths`
+  (`lib/bundler/rubygems_integration.rb:132-135`) is built from
+  `Gem.loaded_specs` — i.e. **activated gems**. Activating is what would put the
+  path on the chopping block. A directory pushed without activation is absent
+  from that list, so `delete` returns nil and the entry survives.
+
+- **`Gem::Specification` cannot see outside the bundle.** `stub_rubygems`
+  (`lib/bundler/rubygems_integration.rb:336-340`) sets
+  `Gem::Specification.all = specs` and reapplies it through `Gem.post_reset`, so
+  under `bundle exec` `find_by_name` cannot find a gem installed outside the
+  bundle, and `Gem::Specification.reset` will not restore it.
+
+## Why the test suite could not catch any of this
+
+The integration container was the official `ruby` image. It differs from a
+machine anyone develops on in four ways, and each one hid one layer:
+
+| Image behaviour | What it hid |
+|---|---|
+| `gemvault` **and** `bundler-source-vault` installed system-wide | `require "bundler/plugin/vault_source"` resolved from `/usr/local/bundle` no matter what the plugin root held |
+| `BUNDLE_APP_CONFIG=/usr/local/bundle` | `Bundler::Plugin.root` was never project-local, so no spec touched a real `.bundle/plugin` |
+| `GEM_HOME` exported | a first repair that read gem roots out of the environment appeared to work |
+| `json` present as a default gem | the undeclared dependency was invisible |
+
+The first repair for this issue reconstructed gem roots from
+`Bundler.original_env`, which is a snapshot of environment variables.
+`GEM_HOME`/`GEM_PATH` are only present there if something exported them —
+rbenv, asdf, chruby, Homebrew and distro rubies export neither. The reporter is
+on rbenv (`issues.rec`: `/Users/davidgillis/.rbenv/versions/4.0.1/`,
+`rbenv 1.3.2`), so that repair passed its specs in Docker and still failed on
+their machine.
+
+The suite now runs on `fedora:44` with a distro ruby: gems in RubyGems' own
+default dirs, nothing exported, bundler a regular gem. Moving to it immediately
+surfaced two further real defects — the undeclared `json` dependency, and the
+`json/ext/parser` extension path.
+
+## The fix
+
+`shim/gemvault_load_path.rb` locates gemvault and its declared runtime
+dependencies across every root that could hold them, and pushes their require
+paths onto `$LOAD_PATH`.
+
+- **`Gem.default_path` is the load-bearing root.** It is what RubyGems knows
+  about its own gem roots, independent of the narrowing in step 2, so it covers
+  rubies that export nothing. `Bundler.original_env` is still consulted, for the
+  rubies that do export a root outside those defaults, such as RVM.
+- **`$LOAD_PATH`, not activation**, for the reasons in step 3.
+- **Dependencies resolved by hand**, using `full_require_paths`
+  (`lib/rubygems/basic_specification.rb:172-183`), which appends `extension_dir`
+  when `have_extensions?` — without it `json/ext/parser` is unfindable, since
+  json's compiled half lives outside its gem directory.
+- **A dependency that cannot be found is skipped rather than fatal.** That is
+  the one thing activation could not do: it would abort on `command_kit`, which
+  only the CLI needs.
+- **`json` is now a declared runtime dependency**, so `gemvault new` works on a
+  stock distro ruby.
+
+## Does the suite actually protect this?
+
+Green is not evidence on its own — the whole reason this bug shipped is that a
+green suite was being satisfied by an ambient gem. So the two pieces of the fix
+were checked by mutation:
+
+| Mutation | Result |
+|---|---|
+| `Gem.default_path` dropped from the searched roots | 18 examples fail |
+| the shim's pinned gemvault requirement ignored, so the newest wins | both examples of the upgrade-residue scenario fail |
+
+Restoring each returns the suite to green.
+
+## Platforms verified
+
+| Platform | Status |
+|---|---|
+| CRuby 4.0.6, Fedora 44, aarch64 | Full suite, 265 examples |
+| JRuby 10.1.1.0 (the reporter runs 10.1.0.0) | Verified once by hand, **not covered by the suite**: vault create/add/list, `bundle install` twice against a vault source, `bundle exec require`. `json 2.21.1 (java)` installed as a platform gem and resolved, which is the case `full_require_paths` has to get right |
+| macOS `arm64-darwin-24` | **Not verified.** The reporter's own platform. Nothing here can run it |
+
+JRuby has no permanent coverage because JRuby caps its own heap from the cgroup
+and the development sandbox is small enough that the cap lands at 148 MB, where
+even a single `gem fetch` dies. The one successful hand-run above happened in a
+lucky memory window and did not reproduce. A JRuby image, rake task and spec
+were written and then reverted rather than shipped unverified: harness code
+nobody has watched pass is the same defect as a spec that cannot fail. On a
+machine with ordinary memory this is worth adding, and it is the highest-value
+gap left, since issue #13 was reported against JRuby as well as CRuby.
+
+## Coverage
+
+`spec/support/vault_sourced_gemfile_examples.rb` applies "a complete bundle" to
+a vault-sourced Gemfile and then re-applies it after each user action: deleting
+`Gemfile.lock`, deleting `.bundle`, deleting both, removing the vaulted gem,
+adding a gem from rubygems, adding the project's own gemspec (the reporter's
+Gemfile shape), adding another gem from the same vault, and adding one from a
+second vault. `spec/integration/vaulted_project_spec.rb` runs that whole
+group under four bundler configurations — stock, an install path chosen, that
+path undone, and the project's gems cached — and
+`spec/integration/no_ambient_gemvault_spec.rb` covers the machine that has no
+gemvault of its own, where the plugin root has to carry the whole dependency
+set.