gemvault 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e990085de84c0a510129de569ba8ed103bb12d78dc5cb2a6b666eb4a9e8303d
-  data.tar.gz: 7c37b0d7ada34a481ed270185a120509a90d296c1bee01a596803e0e33d0a149
+  metadata.gz: 100a593cb7221bf6cc5842ad00c67335809a351905251a6088c3698b41fa9b95
+  data.tar.gz: 6645dea254fbdd76dbd2fc1de7f8471f27185d205d5a23e038665d060f253cfa
 SHA512:
-  metadata.gz: b3e09ff83f50247af6f394a7e1cae36387ddeb5de859c7ef845c024d13bc9062cff800f9061202e3af8ca3bffc6dfbc2e9cc7029986f726bd6bfa1221ca9e80b
-  data.tar.gz: 7d864a45342f84b6b82f0e168c8f9c2e9378bae0fe5fe4ff46bf2c5a454dfdda8f3c90f8446b82fad61caecb8ab136f385a2e6fd85de66829cad3f144141a416
+  metadata.gz: a973851f5b6b7b9eaa48fcf21a25660bc3770d36c992ff758e4b9ace061a64e5b2cdd6a0270ee335ca3d2a6cf1b80f842b69e6768a98fd85741ec91141786a60
+  data.tar.gz: 16b6a27438852230e49569493d526efdcf6b07f499137cdcb73a18b29ef06bd89ddf2def281649109bbf1cfbacce1e7e3d4bfdddae44984855fa378e1b79c51f

data/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Tarball vault format ("Tarvault"): new vaults are portable tarballs with a
+  `manifest.json` index and per-gem SHA256 integrity, with no sqlite3 dependency
+  on the read/write path (works on JRuby). The original SQLite format
+  ("Dbvault") is still read transparently.
+- Vaults carry an explicit on-disk **format version**, decoupled from the gem
+  version and validated on open; gemvault refuses a vault written by a newer
+  gemvault instead of misreading it.
+- `gemvault upgrade` migrates a vault to the current format (e.g. SQLite → tar),
+  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.
+
+### 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.
+
+### Deprecated
+- The SQLite vault format is deprecated and now **read-only**: existing SQLite
+  vaults can be read and migrated but no longer written (`add`/`remove` raise and
+  point at `gemvault upgrade`). Opening one prints a one-time deprecation notice
+  (silenceable with `GEMVAULT_SILENCE_DEPRECATIONS=1`). SQLite support will be
+  removed in a future release (0.3-0.5); migrate with `gemvault upgrade`.
+
 ## [0.1.3] - 2026-06-22
 
 ### Added

data/CLAUDE.md

@@ -93,7 +93,7 @@ Integration tests use a manually-written Bundler plugin index to avoid rubygems.
 
 ## Dependencies
 
-- `sqlite3` (~> 2.0) — runtime
 - `bundler` (>= 2.0) — runtime
 - `command_kit` (~> 0.6) — runtime (CLI)
+- `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

data/Dockerfile.test

@@ -9,3 +9,7 @@ RUN cd /tmp/build \
     && gem build bundler-source-vault.gemspec \
     && gem install --no-document bundler-source-vault-*.gem \
     && rm -rf /tmp/build
+
+# sqlite3 is not a gemvault runtime dependency; install it here so the upgrade
+# integration test can build a legacy SQLite (Dbvault) fixture to migrate.
+RUN gem install --no-document sqlite3

data/README.md

@@ -2,7 +2,9 @@
 
 A gem server in a file. No HTTP. No infrastructure.
 
-A `.gemv` file is a SQLite database 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.
+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).
 
 ## Installation
 
@@ -44,14 +46,32 @@ gemvault add myvault.gemv foo.gem bar.gem     # add .gem files
 gemvault list myvault.gemv                    # list contents
 gemvault remove myvault.gemv foo 1.0.0        # remove a gem
 gemvault extract myvault.gemv foo -o vendor/  # extract .gem file to disk
+gemvault upgrade myvault.gemv                 # migrate to the current format
 ```
 
+## Vault format versioning
+
+Every vault records an on-disk **format version** — `1` for the original SQLite format, `2` for the current tarball format. This version lives inside the file and is **independent of the gemvault gem version**: it changes only when the storage layout changes, so upgrading the gem never invalidates your vaults.
+
+gemvault reads any format up to the one it understands and **refuses a vault written by a newer gemvault** with a clear message (rather than silently misreading it).
+
+The SQLite format (`1`) is **deprecated and read-only**: you can still read and migrate an existing SQLite vault, but `add`/`remove` are refused and print `gemvault upgrade`. Opening one shows a one-time deprecation notice (silence it with `GEMVAULT_SILENCE_DEPRECATIONS=1`). SQLite support will be removed in a future release (0.3–0.5). To migrate a vault to the current format:
+
+```bash
+gemvault upgrade myvault.gemv              # e.g. SQLite (v1) -> tarball (v2)
+gemvault upgrade myvault.gemv --dry-run    # show the plan, change nothing
+gemvault upgrade myvault.gemv --no-backup  # skip the default myvault.gemv.bak copy
+```
+
+`upgrade` preserves every gem and its timestamp, writes `myvault.gemv.bak` by default, and is a no-op on an already-current vault.
+
 ## How It Works
 
-A `.gemv` file is a SQLite database containing gem metadata and raw `.gem` blobs. You can inspect it directly:
+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
-sqlite3 myvault.gemv "SELECT name, version, platform FROM gems"
+tar -tf myvault.gemv                 # tarball (v2) vault
+sqlite3 myvault.gemv "SELECT name, version, platform FROM gems"   # SQLite (v1) vault
 ```
 
 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

@@ -8,9 +8,7 @@ end
 
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec) do |t|
-  t.exclude_pattern = "spec/integration/**/*_spec.rb"
-end
+RSpec::Core::RakeTask.new(:spec)
 
 require "rubocop/rake_task"
 RuboCop::RakeTask.new
@@ -20,27 +18,49 @@ Gempilot::VersionTask.new
 
 CACHED_IMAGE = "gemvault-test:latest".freeze
 
+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", "."
+end
+
+def destroy_cached_image
+  strays = `podman ps -aq --filter ancestor=#{CACHED_IMAGE}`.split
+  sh "podman", "rm", "-f", *strays unless strays.empty?
+  sh "podman", "rmi", CACHED_IMAGE
+end
+
 namespace :spec do
   desc "Build cached container image with gemvault pre-installed"
-  task :build do
-    sh "podman", "build",
-       "--network=host",
-       "-t", CACHED_IMAGE,
-       "-f", "Dockerfile.test",
-       "."
-  end
+  task(:build) { build_cached_image }
 
-  desc "Run container-backed integration specs (requires Podman; run spec:build first)"
-  RSpec::Core::RakeTask.new(:integration) do |t|
-    t.pattern = "spec/integration/**/*_spec.rb"
-  end
+  desc "Build the cached image unless it already exists"
+  task(:setup) { build_cached_image unless cached_image_exists? }
+
+  desc "Remove test containers and the cached image"
+  task(:teardown) { destroy_cached_image if cached_image_exists? }
+end
+
+directory "pkg" do
+  mkdir "pkg"
 end
 
 namespace :shim do
-  desc "Build the bundler-source-vault shim gem"
-  task :build do
-    Dir.chdir("shim") { sh "gem build bundler-source-vault.gemspec" }
+  Bundler::GemHelper.install_tasks dir: "shim", name: "bundler-source-vault"
+  CLOBBER.include "shim/pkg"
+
+  Rake::Task[:build].enhance ["pkg"] do
+    FileList["shim/pkg/*.gem"].each do |g|
+      mv g, "pkg", verbose: false
+    end
   end
 end
 
+Rake::Task[:spec].enhance ["spec:setup"]
+Rake::Task[:build].enhance ["shim:build"]
+Rake::Task[:release].enhance ["shim:release"]
+Rake::Task[:clobber].enhance ["spec:teardown"]
+
 task default: [:test, :spec, :rubocop]

data/docs/tarvault-findings.md

@@ -0,0 +1,186 @@
+# Tarvault Spike — Findings
+
+Spike for `docs/tarvault.md`: replace/augment the SQLite storage of a `.gemv`
+with a **tarball** ("Tarvault") whose first entry is `manifest.json` and whose
+remaining entries are `.gem` files. Motivation: drop the hard `sqlite3`
+dependency (unportable, no JRuby) using only tooling that already ships with
+rubygems.
+
+## Result
+
+Tarvault is implemented and wired **behind the existing `Gemvault::Vault`
+facade**, so the CLI, the Bundler `type: :vault` source, and the RubyGems
+`--source` path use it transparently:
+
+- `Gemvault::Vault` is now a `Forwardable` delegator that selects a backend by
+  file format — existing SQLite files open as `Gemvault::Dbvault` (the old code,
+  extracted verbatim); new or tar files as `Gemvault::Tarvault`. New vaults are
+  Tarvaults.
+- Backends are **lazily required**, so a process that only touches Tarvaults
+  never loads `sqlite3` — the JRuby-portability win.
+- `Gemvault::Manifest` owns `manifest.json`; `Gemvault::TarArchive` owns the
+  low-level tar read + atomic rewrite; `Gemvault::GemExtraction` /
+  `Gemvault::VaultSession` are shared mixins.
+
+**Drop-in proof:** the entire pre-existing suite passes with *no change to any
+`spec/` behavior or integration file* — only new unit specs were added, plus two
+Minitest assertions that had probed a SQLite closed-handle artifact.
+
+- Minitest: `111 tests, 0 failures` (the Vault-contract, Bundler-source, and
+  RubyGems-plugin tests now run on the **tar** backend via the facade).
+- RSpec incl. podman integration: `88 examples, 0 failures` — real
+  `bundle install` (`type: :vault`), `gem install --source myvault.gemv`,
+  bundler-inline, and CLI, all against tar-backed vaults. *(Note: the container
+  image must be rebuilt (`rake spec:build`) after code changes — a stale image
+  silently tests old code and still passes on SQLite.)*
+- New unit specs (`spec/gemvault/**`): `42 examples, 0 failures`.
+
+A Tarvault on disk:
+
+```
+$ file myvault.gemv        # POSIX tar archive
+$ tar -tf myvault.gemv
+manifest.json
+addressable-2.9.0.gem
+rstore-0.3.9.gem
+```
+
+```json
+// manifest.json
+{
+  "vault_version": "2",
+  "format": "tarvault",
+  "created_at": "2026-07-11 20:32:25",
+  "gems": [
+    { "name": "addressable", "version": "2.9.0", "platform": "ruby",
+      "created_at": "…", "sha256": "7fdf6ac3…", "encrypted": false }
+  ]
+}
+```
+
+## Doc Q1 — Integrity: are checksums used?
+
+Yes. Three layers exist; the manifest adds the one that matters for the container:
+
+1. **Tar header checksum** — every 512-byte tar header carries an octal
+   *byte-sum*. It protects the header only and is not cryptographic.
+2. **Inside each `.gem`** — a `.gem` already contains `checksums.yaml.gz`
+   (SHA256/SHA512 of its own members). This protects a gem's internals, not its
+   identity within the vault.
+3. **Manifest per-gem digest (added)** — each `manifest.json` record stores a
+   cryptographic **SHA256 of the whole `.gem` blob**
+   (`OpenSSL::Digest.new("SHA256")`, matching rubygems' own `Gem::Security`
+   convention). `Tarvault#gem_data` recomputes and compares on read, raising
+   `Vault::Error` on mismatch (verified by a test that flips a byte inside the
+   stored blob).
+
+**Boundary:** `gem_entries`/`specs` read the manifest and do **not** re-hash
+blobs; only `gem_data` (the byte-serving path used by install/extract) verifies.
+This is a deliberate scope for the spike — list operations stay O(manifest). If
+list-time verification is ever wanted, the same `Manifest.digest` is the hook.
+
+## Doc feasibility — the one-liner
+
+`docs/tarvault.md`'s one-liner works, but for a subtle reason worth recording:
+
+```ruby
+Enumerator.new { |y|
+  Gem::Package::TarReader.new(File.open(path)) { |r| r.each_entry { |e| y << Gem::Package.new(e) } }
+}.map(&:spec)
+```
+
+`TarReader#each` **closes each entry after yielding** (verified: reading a
+stashed entry raises `IOError: closed Entry`). The one-liner still returns
+correct specs *only* because `Enumerator.new{}.map(&:spec)` interleaves
+consumption — `.spec` runs while the entry is still open. Materialize the
+packages first (`.to_a` then `map(&:spec)`, or stash the entries) and every
+`.spec` raises `IOError`.
+
+**Rule:** read specs eagerly, inside the iteration. Tarvault sidesteps the trap
+entirely — it lists from the manifest and reads any single gem via
+`TarReader#seek` into a private `StringIO`
+(`Gem::Package.new(StringIO.new(entry.read)).spec`), never depending on
+post-close entry behavior.
+
+## Doc Q2 — Encryption: is it possible?
+
+Yes (feasibility only — not implemented). `OpenSSL::Cipher` AES-256-GCM
+round-trips raw `.gem` bytes cleanly (verified, incl. auth-tag failure on
+tamper). The design already reserves the extension point: `Manifest::Record`
+carries an `encrypted` flag (currently always `false`). Encryption would:
+
+- encrypt the raw `.gem` bytes, store the ciphertext as the tar entry, and set
+  `encrypted: true` plus cipher/iv/auth-tag on the record;
+- `gem_data` decrypts (key from env/keyring) before returning, composing with
+  the checksum by hashing the plaintext.
+
+Because gemvault mediates every read and the manifest signals encryption, this
+is a localized change in `gem_data`. `OpenSSL` ships on JRuby, so it does not
+reintroduce a portability problem.
+
+## Portability (the motivation)
+
+The tar path uses only pure-Ruby rubygems tooling (`Gem::Package::TarReader`/
+`TarWriter`), `OpenSSL`, and `JSON` — all present on JRuby. The facade lazily
+`require`s `dbvault` (hence `sqlite3`) **only** when opening an existing SQLite
+file, so a JRuby process that only touches Tarvaults never loads `sqlite3`.
+
+**Done:** `sqlite3` is no longer a runtime dependency. It is removed from the
+gemspec and loaded lazily only to read a legacy SQLite vault; if it is absent,
+`Vault.build_dbvault` raises a clear "install sqlite3 or upgrade the vault"
+error. A process that only touches Tarvaults never loads it (verified by a
+subprocess spec asserting `defined?(SQLite3)` is `nil`).
+
+## Atomicity & locking
+
+Tar has no index, and the leading `manifest.json` changes size on every
+mutation, so **every add/remove is a full rewrite** — to a sibling tempfile in
+the target directory (same filesystem → atomic `File.rename`), with `fsync`
+before rename. `flock` (the doc's suggestion) would guard concurrent *gemvault*
+processes only; external tar edits remain unsupported by design and are out of
+spike scope.
+
+## Follow-on / productionization notes
+
+- Streaming rewrite: the current model reads all gem blobs into memory during a
+  rewrite — fine for a spike; large vaults would want a copy-through stream.
+- Encryption (`encrypted` flag → real cipher params).
+- List-time integrity verification, if wanted.
+- Unify the two backends' error taxonomy and temp-file logic once Tarvault is
+  confirmed as "the way."
+
+There is deliberately **no** format-selection flag on `gemvault new`. Tarvault is
+the way forward; new vaults are always Tarvaults. A user who needs a SQLite vault
+uses an older gemvault.
+
+## Update — format versioning & `gemvault upgrade` (implemented)
+
+A follow-up shipped explicit format versioning and a migration command:
+
+- Each vault records an on-disk **format version** (`1` = Dbvault, `2` = Tarvault)
+  read and validated on open. It is **decoupled from the gemvault gem version** —
+  it bumps only when the byte layout changes. `Vault::UnsupportedVersionError` is
+  raised for a vault newer than `Vault::CURRENT_FORMAT` instead of misreading it,
+  closing the "reads fail open" hole.
+- `Vault.backend_for` now positively identifies the container (`:sqlite`/`:tar`/
+  `:unknown`) ahead of parsing and refuses unrecognized envelopes.
+- `Gemvault::VaultUpgrade` (+ `gemvault upgrade`) reads a vault through its
+  existing backend and rewrites it in the current format with an atomic swap,
+  a default `.bak` backup, `--dry-run`, idempotency, and `created_at` preservation
+  (the write path gained `add(created_at:)`).
+
+`sqlite3` is now optional (removed from the gemspec, loaded lazily, clear error
+when absent). There is no `gemvault new --format` flag by design — Tarvault is
+the only write format.
+
+The Dbvault deprecation lifecycle is decided and phase 1 is shipped:
+
+- **Now:** SQLite vaults are **read-only** (`Dbvault#add`/`#remove` raise
+  `Vault::ReadOnlyError` → `gemvault upgrade`), reads still work, and opening one
+  emits a once-per-process notice via `Gemvault::Deprecation` (stderr, silenceable
+  with `GEMVAULT_SILENCE_DEPRECATIONS=1`, suppressed during `gemvault upgrade`).
+  "Writable" tracks *created-this-session* so migration/legacy tooling that
+  constructs a Dbvault directly still works.
+- **0.3–0.5:** Dbvault removed entirely.
+
+Still open: streaming rewrite and encryption.

data/docs/tarvault.md

@@ -0,0 +1,42 @@
+# GEMVAULT TAR SPIKE
+
+## Problem
+
+Gemvault has been working thus far, but the sqlite3 dependency makes the gem less portable then it should be:
+
+1. The whole idea and basis of gemvault is that it _is_ a portable gem server in a file, and you shouldn't need dependencies to use it.
+2. sqlite3 is not supported by jruby
+
+## Solution
+
+    Since gemvault is just reading blobs from sqlite3, and doesn't really need any of its other stuff, I propose using a simpler storage model - a tarball. *.gem files, otherwise known as  Packages, already are stored in this format, and all of the necessary equipment for reading them is already in rubygems, so it's a natural fit. If we are really worried about integrity that sqlite3 provides, we can use flock or similar to do locking. It is not intended or recommended to manipulate the tar version of the gemv file without going through gemvault, so anything beyond that is not supported. We shall refer to the tar version of a gemv file as a Tarvault and the sqlite3 version as a Dbvault to ensure communication is clear.
+
+One can read all the gemspecs from a Tarvault using this chained oneliner:
+
+```ruby
+gemspecs = Enumerator.new { |y| Gem::Package::TarReader.new(File.open("tarvault.gemv")) { |reader| reader.each_entry { y << Gem::Package.new(it) } } }.map(&:spec)
+
+
+```
+
+All of the dependencies are already provided.
+
+## Things to think about
+
+1. A Dbvault makes it trivial to store additional information about a given Package. I think we can meet any needs for metadata via a json manifest or metadata file to keep as the very first entry in a Tarvault. So structure would resemble something like:
+
+```
+$ tar -tf tarvault.gemv
+
+manifest.json
+myprivategem-0.1.0.gem
+rails-8.0.0.gem
+
+```
+
+1. For files like this, e.g. files within a file, what is the usual way to maintain integrity? Are checksums used?
+2. Encryption can be supported by encrypting a Package directly, and appending the raw bytes directly to the Tarvault. The manifest can indicate that they are encrypted. OpenSSL can be used all the way through (Encryption is not to be done on this spike, but whether it is possible is a key factor)
+
+## Notes
+
+1. gemvault is below 1.0.0 at the moment and therefore does not guarantee any backwards compatibility with sqlite3 version or anything for that matter. Keeping this compatitble with the Dbvault is not something you should keep in mind. Move forward. Users can use an old version of gemvault if we decide that Tarvault is _the way_

data/lib/bundler/plugin/vault_source.rb

@@ -8,16 +8,28 @@ module Bundler
       def initialize(opts)
         super
         @vault_path = resolve_vault_path(@uri)
+        @allow_remote = false
       end
 
       def fetch_gemspec_files
         validate_vault_exists!
 
         Gemvault::Vault.open(@vault_path) do |vault|
-          vault.gem_entries.map { |entry| gemspec_file_for(vault, entry) }
+          vault.gem_entries.filter_map { |entry| gemspec_file_for(vault, entry) }
         end
       end
 
+      # Bundler first asks a source, in local mode, which gems are already
+      # unpacked so it can tell what still needs installing, then switches to
+      # remote mode to resolve and install the rest. A vault gem is not on the
+      # load path until it is unpacked, so advertising one that still lives only
+      # inside the archive makes Bundler believe it is installed: it skips the
+      # install and the later require fails. Advertise not-yet-unpacked gems
+      # only once Bundler has asked for remote specs.
+      def remote!
+        @allow_remote = true
+      end
+
       def install(spec, opts = {})
         gem_dir = gem_dir_for(spec.full_name)
         return use_installed_gem(spec, gem_dir) if File.directory?(gem_dir) && !opts[:force]
@@ -46,6 +58,7 @@ module Bundler
         spec = vault.spec_from_blob(entry.name, entry.version, entry.platform)
         gem_dir = gem_dir_for(spec.full_name)
         return anchor_gemspec(gem_dir, spec.full_name, spec.to_ruby) if File.directory?(gem_dir)
+        return nil unless @allow_remote
 
         write_tmp_gemspec(spec.full_name, spec.to_ruby)
       end

data/lib/gemvault/cli/commands/upgrade.rb

@@ -0,0 +1,48 @@
+require_relative "../command"
+require_relative "../../vault_upgrade"
+
+module Gemvault
+  class CLI
+    module Commands
+      # Upgrades a vault to the current storage format (e.g. a SQLite Dbvault
+      # to a Tarvault), preserving every gem and its timestamp.
+      class Upgrade < Command
+        description "Upgrade a vault to the current storage format"
+
+        argument :vault, required: true,
+                         usage: "VAULT",
+                         desc: "Vault file"
+
+        option :dry_run, desc: "Show what would change without modifying the vault"
+        option :no_backup, desc: "Do not write a .bak copy before upgrading"
+
+        def run(vault)
+          upgrade = Gemvault::VaultUpgrade.new(vault, backup: !options[:no_backup])
+          summary = upgrade.plan
+          return report_no_op(vault, summary) if summary.no_op?
+          return report_dry_run(vault, summary) if options[:dry_run]
+
+          upgrade.call
+          report_upgraded(vault, summary)
+        rescue Gemvault::Vault::Error => e
+          print_error(e.message)
+          exit(1)
+        end
+
+        private
+
+        def report_no_op(vault, summary)
+          puts "#{vault} is already current (format #{summary.to_version})"
+        end
+
+        def report_dry_run(vault, summary)
+          puts "Would upgrade #{vault}: #{summary} (#{summary.gem_count} gems)"
+        end
+
+        def report_upgraded(vault, summary)
+          puts "Upgraded #{vault}: #{summary} (#{summary.gem_count} gems)"
+        end
+      end
+    end
+  end
+end

data/lib/gemvault/dbvault.rb

@@ -0,0 +1,98 @@
+require "sqlite3"
+require_relative "vault"
+require_relative "vault_session"
+require_relative "gem_extraction"
+require_relative "gem_entry"
+require_relative "deprecation"
+
+module Gemvault
+  # Read-only reader for a SQLite-backed vault (a "Dbvault"). Attempts to write
+  # are refused with a pointer to run gemvault upgrade, and opening a vault
+  # emits a one-time notice.
+  class Dbvault
+    extend VaultSession
+    include GemExtraction
+
+    FORMAT_VERSION = 1
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = File.expand_path(path)
+      open_vault!
+    end
+
+    def add(*)
+      raise Vault::ReadOnlyError, read_only_message
+    end
+
+    def remove(*)
+      raise Vault::ReadOnlyError, read_only_message
+    end
+
+    def gem_data(name, version, platform: "ruby")
+      row = @db.execute(
+        "SELECT data FROM gems WHERE name = ? AND version = ? AND platform = ?",
+        [name, version, platform],
+      ).first
+      raise Vault::NotFoundError, "Gem not found: #{name}-#{version} (#{platform})" unless row
+
+      row["data"]
+    end
+
+    def gem_entries
+      @db.execute(
+        "SELECT name, version, platform, created_at FROM gems ORDER BY name, version",
+      ).map { |row| GemEntry.new(**row.transform_keys(&:to_sym)) }
+    end
+
+    def size
+      @db.execute("SELECT COUNT(*) AS count FROM gems").first["count"]
+    end
+
+    def close
+      @db.close if @db && !@db.closed?
+    end
+
+    def closed?
+      @db.nil? || @db.closed?
+    end
+
+    def format_version
+      row = @db.execute("SELECT value FROM metadata WHERE key = 'vault_version'").first
+      row ? row["value"].to_i : FORMAT_VERSION
+    end
+
+    private
+
+    def open_vault!
+      raise Vault::NotFoundError, "Vault not found: #{@path}" unless File.exist?(@path)
+
+      validate_sqlite!
+      @db = new_database
+      Vault.assert_readable!(format_version, @path)
+      Deprecation.warn_once(deprecation_message)
+    end
+
+    def new_database
+      db = SQLite3::Database.new(@path)
+      db.results_as_hash = true
+      db
+    end
+
+    def validate_sqlite!
+      return if File.binread(@path, Vault::SQLITE_MAGIC.bytesize) == Vault::SQLITE_MAGIC
+
+      raise Vault::Error, "Not a valid vault file (not SQLite): #{@path}"
+    end
+
+    def read_only_message
+      "#{@path} uses the deprecated read-only SQLite format. Migrate it first: gemvault upgrade #{@path}"
+    end
+
+    def deprecation_message
+      "SQLite vaults are deprecated and read-only; support will be removed in a future release (0.3-0.5). " \
+        "Migrate #{@path} with: gemvault upgrade #{@path}"
+    end
+  end
+end

data/lib/gemvault/deprecation.rb

@@ -0,0 +1,46 @@
+module Gemvault
+  # Emits deprecation notices once per unique message, to a configurable IO
+  # (stderr in production). Silenceable per-block or via an environment opt-out
+  # so automated pipelines that consume a legacy vault are not spammed.
+  module Deprecation
+    ENV_KEY = "GEMVAULT_SILENCE_DEPRECATIONS".freeze
+
+    class << self
+      attr_writer :output
+
+      def output
+        @output ||= $stderr
+      end
+
+      def warn_once(message)
+        return if silenced? || seen.include?(message)
+
+        seen << message
+        output.puts("gemvault: #{message}")
+      end
+
+      def silence
+        previous = @silenced
+        @silenced = true
+        yield
+      ensure
+        @silenced = previous
+      end
+
+      def silenced?
+        @silenced || ENV.key?(ENV_KEY)
+      end
+
+      def reset!
+        @seen = []
+        @silenced = false
+      end
+
+      private
+
+      def seen
+        @seen ||= []
+      end
+    end
+  end
+end