gemvault 0.2.5 → 0.2.7

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

@@ -1,4 +1,7 @@
 require_relative "../command"
+require_relative "../../bundler_gemfile"
+require_relative "../../bundler_plugin_index"
+require_relative "../../bundler_plugin_root"
 require_relative "../../ghost_specification"
 
 module Gemvault
@@ -25,9 +28,22 @@ module Gemvault
       # Re-running bundle install afterwards triggers Bundler to reinstall
       # the plugin against whatever the current Gemfile declares. Run this
       # from the project directory.
+      #
+      # A project whose Gemfile is inline has no Gemfile to reinstall from, and
+      # keeps its plugins in a root Bundler will not consult unless told to.
+      # Both are handled below.
+      #
+      # The repair is transactional. `bundle install` does more than reinstall
+      # the plugin, and that extra work can fail on its own; the index the
+      # uninstall clears is snapshotted first and put back when the reinstall
+      # never happened, so a failed run leaves the machine as found rather
+      # than with no plugin at all (issue #27). Every failure is one line on
+      # stderr and exit 1 (issue #24).
       class Doctor < Command
         description "Repair broken bundler-source-vault plugin state and reinstall the plugin"
 
+        PLUGIN = "bundler-source-vault".freeze
+
         OWNED_GEMS = %w[gemvault bundler-source-vault].freeze
 
         PERMISSION_HINT = "(re-run with permissions for that gem home, e.g. sudo gemvault doctor)".freeze
@@ -39,8 +55,9 @@ module Gemvault
             print_error("#{e.message} #{PERMISSION_HINT}")
             exit(1)
           end
-          system("bundle", "plugin", "uninstall", "bundler-source-vault", exception: true)
-          exec("bundle", "install")
+          saved = index.snapshot
+          uninstall_plugin
+          reinstall_or_explain(saved)
         end
 
         private
@@ -51,6 +68,77 @@ module Gemvault
             puts "Removed ghost specification #{ghost}"
           end
         end
+
+        def gemfile
+          @gemfile ||= BundlerGemfile.new
+        end
+
+        def plugin_root
+          @plugin_root ||= BundlerPluginRoot.new(gemfile: gemfile)
+        end
+
+        def index
+          @index ||= BundlerPluginIndex.new(plugin_root.consulted)
+        end
+
+        # bundler/inline's own trick: a non-empty BUNDLE_GEMFILE is the whole of
+        # what Bundler::Plugin.root consults to prefer a project's plugin
+        # directory over the global one, so setting it reaches the entry that
+        # needs clearing. The file it names never has to exist.
+        def uninstall_env
+          return {} unless plugin_root.unreachable?
+
+          { "BUNDLE_GEMFILE" => "Gemfile" }
+        end
+
+        def uninstall_plugin
+          return if system(uninstall_env, "bundle", "plugin", "uninstall", PLUGIN)
+
+          print_error("bundle plugin uninstall #{PLUGIN} failed")
+          exit(1)
+        end
+
+        # `bundle install` with no Gemfile prints its entire usage screen and
+        # exits 10, which reads as gemvault itself failing. By this point the
+        # repair has already happened; only the reinstall is unavailable.
+        def reinstall_or_explain(saved)
+          return reinstall(saved) if gemfile.exist?
+          return explain_inline_repair if plugin_root.unreachable?
+
+          puts "No Gemfile here to reinstall from -- re-run gemvault doctor from the"
+          puts "project directory to reinstall the plugin."
+        end
+
+        def reinstall(saved)
+          return if system("bundle", "install")
+          return exit_partially_repaired if index.registered?(PLUGIN)
+
+          exit_restoring(saved)
+        end
+
+        # The plugin came back before the install died, so the repair stands;
+        # only the rest of the bundle is unfinished.
+        def exit_partially_repaired
+          print_error("bundle install failed; the #{PLUGIN} plugin itself was reinstalled " \
+                      "-- fix the install error and re-run bundle install")
+          exit(1)
+        end
+
+        def exit_restoring(saved)
+          index.restore(saved)
+          print_error("bundle install failed before reinstalling #{PLUGIN}; restored the " \
+                      "previous plugin index -- fix the install error and re-run gemvault doctor")
+          exit(1)
+        end
+
+        # The local path is named only when it was the uninstall's target --
+        # otherwise bundler worked against its global root, and naming this
+        # project's path would misreport what happened.
+        def explain_inline_repair
+          puts "Cleared the #{PLUGIN} plugin index at #{plugin_root.local}."
+          puts "No Gemfile here to reinstall from -- an inline gemfile installs the plugin"
+          puts "again the next time the script runs."
+        end
       end
     end
   end

data/lib/gemvault/legacy_tarvault.rb

@@ -0,0 +1,114 @@
+require "pathname"
+# rubygems loads zlib and psych only as it inflates a gem's metadata, so the
+# rescue below requires them itself to name their errors whichever one fires.
+require "psych"
+require "zlib"
+require_relative "vault"
+require_relative "vault_session"
+require_relative "gem_extraction"
+require_relative "gem_entry"
+require_relative "manifest_text"
+require_relative "tarball"
+require_relative "timestamp"
+require_relative "deprecation"
+
+module Gemvault
+  ##
+  # Read-only reader for a format-2 vault: a tarball whose index is the
+  # manifest.json gemvault wrote through 0.2.x. It exists so +gemvault upgrade+
+  # migrates such a vault through the same pipeline every other format takes,
+  # rather than leaving the gems stranded behind an error.
+  #
+  # It does not read that manifest. The index is derived from the payload
+  # instead: each stored .gem carries its own gemspec, which is where the
+  # manifest's identity fields came from in the first place. That keeps the
+  # old notation from re-entering the codebase to be parsed (issue #25) and
+  # makes the reader indifferent to a manifest that is damaged or missing.
+  #
+  # Two things the old index held are consequently gone. Each gem's stored
+  # time is unrecoverable, so entries are stamped when the vault is opened;
+  # and the per-gem digests cannot be checked, so a migrated gem is trusted as
+  # the bytes found in the archive -- the new vault records fresh digests of
+  # exactly what it copied.
+  class LegacyTarvault
+    extend VaultSession
+    include GemExtraction
+
+    FORMAT_VERSION = 2
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = Pathname(path).expand_path
+      @archive = Tarball.new(@path)
+      @closed = false
+      open_vault!
+    end
+
+    def add(*)
+      raise Vault::ReadOnlyError, read_only_message
+    end
+
+    def remove(*)
+      raise Vault::ReadOnlyError, read_only_message
+    end
+
+    def gem_data(entry)
+      bytes = @archive.read(entry.filename)
+      raise Vault::NotFoundError, "Gem not found: #{entry}" unless bytes
+
+      bytes
+    end
+
+    def gem_entries
+      @gem_entries ||= derived_entries
+    end
+
+    def format_version = FORMAT_VERSION
+
+    def size = gem_members.size
+
+    def close
+      @closed = true
+    end
+
+    def closed? = @closed
+
+    private
+
+    def open_vault!
+      raise Vault::NotFoundError, "Vault not found: #{@path}" unless @path.exist?
+
+      @opened_at = Timestamp.now
+      Deprecation.warn_once(deprecation_message)
+    end
+
+    # Deriving the index means reading the archive and every gem in it, so it
+    # meets the same wreckage Tarvault's open path does and owes the user the
+    # same answer: the vault named, not a tar library's error.
+    def derived_entries
+      begin
+        gem_members.map { |member| entry_for(member) }.sort_by { |gem| [gem.name, gem.version] }
+      rescue Gem::Exception, Psych::Exception, Zlib::Error, ArgumentError, Errno::EINVAL
+        raise Vault::Error, "Not a valid Tarvault: #{@path}"
+      end
+    end
+
+    def gem_members
+      @archive.entries.reject { |member| member.name == ManifestText::LEGACY_FILENAME }
+    end
+
+    def entry_for(member)
+      GemEntry.from_spec(Gem::Package.new(StringIO.new(member.bytes)).spec, created_at: @opened_at)
+    end
+
+    def read_only_message
+      "Vault #{@path} is format #{FORMAT_VERSION} and read-only. Migrate it with: gemvault upgrade #{@path}"
+    end
+
+    def deprecation_message
+      "format #{FORMAT_VERSION} vaults are read-only, and their stored times cannot be recovered. " \
+        "Migrate #{@path} with: gemvault upgrade #{@path}"
+    end
+  end
+end

data/lib/gemvault/manifest.rb

@@ -1,47 +1,26 @@
-require "json"
 require "digest"
 require_relative "gem_entry"
 
 module Gemvault
-  # The manifest.json stored as the first entry of a Tarvault. Records each
-  # gem's identity, timestamp, and SHA256 digest so listing and integrity
-  # checks never require reading every gem blob.
+  # The index stored as the first entry of a Tarvault. Records each gem's
+  # identity, timestamp, and SHA256 digest so listing and integrity checks
+  # never require reading every gem blob. Its on-disk notation belongs to
+  # Gemvault::ManifestText.
   class Manifest < Data.define(:created_at, :records, :format_version)
-    FILENAME = "manifest.json".freeze
-    FORMAT_VERSION = 2
+    FORMAT_VERSION = 3
 
     # One stored gem: its identity (a GemEntry) plus the integrity digest and
     # encryption flag the manifest keeps alongside it.
     class StoredGem < Data.define(:gem, :sha256, :encrypted)
-      def self.from_h(hash)
-        hash => { name:, version:, platform:, created_at:, sha256:, encrypted: }
-        entry = GemEntry.new(name:, version:, platform:, created_at:)
-        new(gem: entry, sha256:, encrypted:)
-      end
-
       def filename = gem.filename
 
       def matches?(bytes) = Manifest.digest(bytes) == sha256
-
-      def to_h
-        {
-          name: gem.name, version: gem.version, platform: gem.platform,
-          created_at: gem.created_at, sha256:, encrypted:
-        }
-      end
     end
 
     def self.digest(bytes) = Digest::SHA256.hexdigest(bytes)
 
     def self.empty(created_at:) = new(created_at:, records: [])
 
-    def self.parse(json)
-      data = JSON.parse(json, symbolize_names: true)
-      records = data.fetch(:gems, []).map { |gem| StoredGem.from_h(gem) }
-      format_version = (data[:vault_version] || FORMAT_VERSION).to_i
-      new(created_at: data[:created_at], records:, format_version:)
-    end
-
     def initialize(created_at:, records:, format_version: FORMAT_VERSION)
       super
     end
@@ -63,16 +42,5 @@ module Gemvault
     def gem_entries
       records.map(&:gem).sort_by { |gem| [gem.name, gem.version] }
     end
-
-    def to_h
-      {
-        vault_version: FORMAT_VERSION,
-        format: "tarvault",
-        created_at:,
-        gems: records.map(&:to_h),
-      }
-    end
-
-    def to_json(*_args) = JSON.pretty_generate(to_h)
   end
 end

data/lib/gemvault/manifest_text.rb

@@ -0,0 +1,149 @@
+require_relative "gem_entry"
+require_relative "manifest"
+require_relative "timestamp"
+
+module Gemvault
+  ##
+  # The manifest's on-disk notation: a header and one line per stored gem.
+  #
+  #   gemvault 3
+  #   created 2026-08-12T16:05:55Z
+  #
+  #   foo 1.0.0 ruby 2026-08-12T16:05:55Z <sha256> 0
+  #
+  # A manifest is a table, not a document -- fixed-arity records of scalars,
+  # with no nesting and no free text -- so it is written and read as one.
+  # Every field comes from an alphabet that excludes whitespace: rubygems
+  # validates gem names against <tt>/\A[a-zA-Z0-9._-]+\z/</tt>, versions and
+  # platforms are drawn from the same characters, digests are hex, the flag is
+  # a bit, and Gemvault::Timestamp keeps times space-free. That makes a line
+  # unambiguous without quoting or escapes.
+  #
+  # The gain over a general notation is what a reader cannot be asked to do:
+  # there is no recursion to exhaust the stack, no escape grammar, no
+  # backtracking, and no library to load -- the last of which is what let a
+  # <tt>require "json"</tt> in this path activate a gem version a project had
+  # locked (issue #25).
+  #
+  # Reading validates every field, because a vault is a file that arrives from
+  # elsewhere. Writing trusts the values this library computed or normalized
+  # (digests, flags, times through Gemvault::Timestamp) -- but a gem's
+  # identity arrives in a gem file this library did not write, and
+  # <tt>Gem::Package#spec</tt> never validates it, so a vault asks
+  # unwritable_field before admitting a gem.
+  module ManifestText
+    # Raised when text is not a manifest this gemvault can read.
+    class MalformedError < StandardError; end
+
+    # The archive entry holding the manifest, and the one older gemvaults
+    # wrote, recognized only to say so.
+    FILENAME = "manifest".freeze
+    LEGACY_FILENAME = "manifest.json".freeze
+
+    MAGIC = "gemvault".freeze
+
+    HEADER_LINES = 3
+
+    # Field alphabets, composed into RECORD below.
+    NAME = "[a-zA-Z0-9._-]+".freeze
+    VERSION = "[0-9][0-9a-zA-Z.-]*".freeze
+    PLATFORM = "[a-zA-Z0-9._-]+".freeze
+    STAMP = "\\d{4}-\\d\\d-\\d\\dT\\d\\d:\\d\\d:\\d\\dZ".freeze
+    DIGEST = "\\h{64}".freeze
+    FLAG = "[01]".freeze
+
+    # gemvault <version>
+    MAGIC_LINE = /\A#{MAGIC} (?<version>\d+)\z/
+    # created <timestamp>
+    CREATED_LINE = /\Acreated (?<created_at>#{STAMP})\z/
+    # A record line's fields, in the order the line carries them.
+    RECORD_FIELDS = { name: NAME, version: VERSION, platform: PLATFORM,
+                      stored_at: STAMP, sha256: DIGEST, encrypted: FLAG }.freeze
+    RECORD = /\A#{RECORD_FIELDS.map { |field, alphabet| "(?<#{field}>#{alphabet})" }.join(" ")}\z/
+
+    # The spec-supplied alphabets anchored singly, for asking whether one
+    # field fits before a record is written.
+    IDENTITY_ALPHABETS = { name: /\A#{NAME}\z/, version: /\A#{VERSION}\z/, platform: /\A#{PLATFORM}\z/ }.freeze
+
+    ENCRYPTED = "1".freeze
+
+    # The lines every manifest opens with: the format version the writing
+    # gemvault declared, the vault's creation time, and a blank separator.
+    class Header < Data.define(:format_version, :created_at)
+      def lines = ["#{MAGIC} #{format_version}", "created #{created_at}", ""]
+    end
+
+    module_function
+
+    # :call-seq:
+    #   render(manifest) -> String
+    #
+    # +manifest+ as the text a vault stores.
+    def render(manifest)
+      header = Header.new(format_version: Manifest::FORMAT_VERSION, created_at: manifest.created_at)
+      "#{(header.lines + manifest.records.map { |record| record_line(record) }).join("\n")}\n"
+    end
+
+    def record_line(record)
+      gem = record.gem
+      [gem.name, gem.version, gem.platform, gem.created_at,
+       record.sha256, record.encrypted ? ENCRYPTED : "0"].join(" ")
+    end
+
+    # :call-seq:
+    #   unwritable_field(entry) -> Symbol or nil
+    #
+    # The first of +entry+'s identity fields holding a value outside its
+    # alphabet, or nil when a record for +entry+ would read back intact.
+    def unwritable_field(entry)
+      IDENTITY_ALPHABETS.each_key.find { |field| !IDENTITY_ALPHABETS[field].match?(entry.public_send(field)) }
+    end
+
+    # :call-seq:
+    #   parse(text) -> Manifest
+    #
+    # The Manifest +text+ describes. Raises MalformedError for anything outside
+    # the notation above; the version a well-formed header declares is returned
+    # as parsed, readability being Vault.assert_readable!'s question.
+    def parse(text)
+      lines = text.to_s.lines(chomp: true)
+      header = read_header(lines)
+      records = lines.drop(HEADER_LINES).map { |line| read_record(line) }
+      Manifest.new(created_at: header.created_at, records:, format_version: header.format_version)
+    end
+
+    def read_header(lines)
+      raise MalformedError, "Not a gemvault manifest: no header" if lines.size < HEADER_LINES
+
+      magic, created, separator = lines
+      reject(separator, reason: "expected a blank line after the header") unless separator.empty?
+      Header.new(format_version: read_version(magic), created_at: read_created(created))
+    end
+
+    def read_version(line)
+      Integer(capture(line, pattern: MAGIC_LINE, expecting: "expected a #{MAGIC} version line")[:version], 10)
+    end
+
+    def read_created(line) = capture(line, pattern: CREATED_LINE, expecting: "expected a created line")[:created_at]
+
+    def capture(line, pattern:, expecting:)
+      pattern.match(line) || reject(line, reason: expecting)
+    end
+
+    def read_record(line)
+      fields = capture(line, pattern: RECORD, expecting: "expected a gem record")
+      entry = GemEntry.new(name: fields[:name], version: fields[:version],
+                           platform: fields[:platform], created_at: fields[:stored_at])
+      Manifest::StoredGem.new(gem: entry, sha256: fields[:sha256], encrypted: fields[:encrypted] == ENCRYPTED)
+    end
+
+    # Truncated because a rejected line is arbitrary bytes from a file the
+    # caller did not write, and it is about to be printed.
+    def reject(line, reason:)
+      raise MalformedError, "Not a gemvault manifest (#{reason}): #{line.to_s[0, 60].inspect}"
+    end
+
+    private_class_method :record_line, :read_header, :read_version, :read_created,
+                         :capture, :read_record, :reject
+  end
+end

data/lib/gemvault/tarball.rb

@@ -20,6 +20,12 @@ module Gemvault
       each_entry.map { |member| ArchiveEntry.new(name: member.full_name, bytes: member.read) }
     end
 
+    # The member names alone. Reads tar headers without any member's bytes, so
+    # a caller asking what kind of vault this is does not load the whole file.
+    def names
+      each_entry.map(&:full_name)
+    end
+
     def write(entries)
       Tempfile.create(["tarvault", ".tar"], @path.dirname) do |tmp|
         write_entries(io: tmp, entries:)

data/lib/gemvault/tarvault.rb

@@ -1,16 +1,17 @@
-require "time"
 require "pathname"
 require_relative "vault"
 require_relative "vault_session"
 require_relative "gem_extraction"
 require_relative "manifest"
+require_relative "manifest_text"
+require_relative "timestamp"
 require_relative "tarball"
 require_relative "archive_entry"
 require_relative "gem_entry"
 require_relative "gem_reference"
 
 module Gemvault
-  # A Tarvault: a tarball whose first entry is manifest.json and whose
+  # A Tarvault: a tarball whose first entry is the manifest and whose
   # remaining entries are .gem files. Portable, dependency-free storage.
   class Tarvault
     extend VaultSession
@@ -30,7 +31,8 @@ module Gemvault
       raise Vault::NotFoundError, "Gem file not found: #{gem_path}" unless gem_path.file?
 
       spec = spec_from_gem_file(gem_path)
-      entry = GemEntry.from_spec(spec, created_at: created_at || timestamp)
+      entry = GemEntry.from_spec(spec, created_at: Timestamp.canonical(created_at || Timestamp.now))
+      raise_if_unwritable(entry, gem_path:)
       raise_if_duplicate(entry)
       store(entry:, bytes: gem_path.binread)
     end
@@ -80,7 +82,7 @@ module Gemvault
     def create_vault!
       raise Vault::Error, "Vault already exists: #{@path}" if @path.exist?
 
-      @manifest = Manifest.empty(created_at: timestamp)
+      @manifest = Manifest.empty(created_at: Timestamp.now)
       rewrite([])
     end
 
@@ -88,18 +90,18 @@ module Gemvault
       begin
         raise Vault::NotFoundError, "Vault not found: #{@path}" unless @path.exist?
 
-        @manifest = Manifest.parse(read_manifest_json)
+        @manifest = ManifestText.parse(read_manifest)
         Vault.assert_readable!(version: @manifest.format_version, path: @path)
-      rescue JSON::ParserError, Gem::Package::TarInvalidError, ArgumentError, Errno::EINVAL
+      rescue ManifestText::MalformedError, Gem::Package::TarInvalidError, ArgumentError, Errno::EINVAL
         raise Vault::Error, "Not a valid Tarvault: #{@path}"
       end
     end
 
-    def read_manifest_json
-      json = @archive.read(Manifest::FILENAME)
-      raise Vault::Error, "Not a valid Tarvault (missing manifest): #{@path}" unless json
+    def read_manifest
+      text = @archive.read(ManifestText::FILENAME)
+      raise Vault::Error, "Not a valid Tarvault (missing manifest): #{@path}" unless text
 
-      json
+      text
     end
 
     def store(entry:, bytes:)
@@ -109,12 +111,12 @@ module Gemvault
     end
 
     def rewrite(gems)
-      manifest_entry = ArchiveEntry.new(name: Manifest::FILENAME, bytes: @manifest.to_json)
+      manifest_entry = ArchiveEntry.new(name: ManifestText::FILENAME, bytes: ManifestText.render(@manifest))
       @archive.write([manifest_entry] + gems)
     end
 
     def survivors
-      @archive.entries.reject { |entry| entry.name == Manifest::FILENAME }
+      @archive.entries.reject { |entry| entry.name == ManifestText::FILENAME }
     end
 
     def survivors_excluding(dropped)
@@ -132,8 +134,16 @@ module Gemvault
       raise Vault::DuplicateGemError, "Gem already in vault: #{entry}"
     end
 
-    def timestamp
-      Time.now.utc.strftime("%Y-%m-%d %H:%M:%S")
+    # A spec arrives inside a gem file this library did not write, and
+    # Gem::Package#spec never validates it; a field the manifest's notation
+    # cannot hold would corrupt the whole vault on the next read.
+    def raise_if_unwritable(entry, gem_path:)
+      field = ManifestText.unwritable_field(entry)
+      return unless field
+
+      value = entry.public_send(field).to_s[0, 60]
+      raise Vault::InvalidGemError,
+            "Invalid gem file #{gem_path}: #{field} #{value.inspect} cannot be stored in a manifest"
     end
   end
 end

data/lib/gemvault/timestamp.rb

@@ -0,0 +1,45 @@
+module Gemvault
+  ##
+  # The notation a vault records times in.
+  #
+  # A manifest is a table of whitespace-separated fields (see
+  # Gemvault::ManifestText), so a stored time may not contain a space. ISO 8601
+  # in UTC satisfies that, sorts lexically, and is what a reader expects.
+  #
+  # Legacy SQLite vaults stored <tt>"2000-01-01 00:00:00"</tt>, and
+  # +gemvault upgrade+ carries those values straight into the new vault, so the
+  # two known notations are accepted and everything else is refused rather than
+  # written into a manifest it would corrupt.
+  module Timestamp
+    # Raised when a value is in no notation a vault can store.
+    class Error < StandardError; end
+
+    FORMAT = "%Y-%m-%dT%H:%M:%SZ".freeze
+
+    # What FORMAT produces: 2026-08-12T16:05:55Z.
+    CANONICAL = /\A\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ\z/
+
+    # What Dbvault wrote: the same instant with a space for the T and no zone.
+    LEGACY = /\A(\d{4}-\d\d-\d\d) (\d\d:\d\d:\d\d)\z/
+
+    module_function
+
+    # This instant, in the vault's notation.
+    def now = Time.now.utc.strftime(FORMAT)
+
+    # :call-seq:
+    #   canonical(value) -> String
+    #
+    # +value+ in the vault's notation, converting a legacy vault's notation on
+    # the way. Raises Error for anything else.
+    def canonical(value)
+      text = value.to_s
+      return text if CANONICAL.match?(text)
+
+      legacy = LEGACY.match(text)
+      raise Error, "Not a time a vault can store: #{text.inspect}" unless legacy
+
+      "#{legacy[1]}T#{legacy[2]}Z"
+    end
+  end
+end

data/lib/gemvault/vault.rb

@@ -4,9 +4,10 @@ require_relative "vault_session"
 
 module Gemvault
   # The public vault interface. Delegates storage to a backend chosen by file
-  # format: a Dbvault (SQLite) for existing SQLite files, a Tarvault (tarball)
-  # otherwise. New vaults are Tarvaults. Only the selected backend is loaded,
-  # so the tar path never requires sqlite3.
+  # format: a Dbvault (SQLite) for existing SQLite files, a read-only
+  # LegacyTarvault for a tarball still indexed by manifest.json, and a Tarvault
+  # for every other tarball. New vaults are Tarvaults. Only the selected
+  # backend is loaded, so the tar path never requires sqlite3.
   class Vault
     extend VaultSession
     extend Forwardable
@@ -22,7 +23,7 @@ module Gemvault
     TAR_MAGIC = "ustar".freeze
     TAR_MAGIC_OFFSET = 257
 
-    CURRENT_FORMAT = 2
+    CURRENT_FORMAT = 3
     MIN_READABLE_FORMAT = 1
 
     def_delegators :@backend,
@@ -85,7 +86,31 @@ module Gemvault
 
     def self.build_tarvault(path, create:)
       require_relative "tarvault"
-      Tarvault.new(path, create:)
+      return Tarvault.new(path, create:) if create || !legacy_tarvault?(path)
+
+      require_relative "legacy_tarvault"
+      LegacyTarvault.new(path)
+    end
+
+    # A tarball indexed the way vaults were through format 2. Asked by name
+    # rather than by version, because the version is recorded in the very
+    # index this gemvault no longer reads.
+    #
+    # An archive too damaged to enumerate answers no rather than raising here.
+    # This runs ahead of every backend, so a wreck raised from it would escape
+    # the rescue Tarvault opens with and reach the user as a tar library's
+    # backtrace; declining instead leaves that path to report it as the
+    # Vault::Error it has always been.
+    def self.legacy_tarvault?(path)
+      require_relative "manifest_text"
+      require_relative "tarball"
+
+      begin
+        names = Tarball.new(path).names
+        !names.include?(ManifestText::FILENAME) && names.include?(ManifestText::LEGACY_FILENAME)
+      rescue Gem::Package::Error, ArgumentError, Errno::EINVAL
+        false
+      end
     end
 
     def initialize(path, create: false)

data/lib/gemvault/vault_upgrade.rb

@@ -6,7 +6,9 @@ require_relative "deprecation"
 module Gemvault
   # Migrates a vault to the current storage format by reading it through its
   # existing backend and rewriting it through the current-format writer, then
-  # atomically swapping the file into place. Preserves each gem's created_at.
+  # atomically swapping the file into place. Each gem's created_at carries
+  # over as the source backend reports it -- which for a format-2 vault is a
+  # fresh stamp, its stored times being unreadable (see LegacyTarvault).
   class VaultUpgrade
     include FileUtils
 
@@ -22,8 +24,8 @@ module Gemvault
       end
     end
 
-    # Copies gems from a source vault into a target vault, preserving each
-    # gem's stored timestamp. Holds the two endpoints so the per-gem call
+    # Copies gems from a source vault into a target vault, carrying each
+    # entry's created_at across. Holds the two endpoints so the per-gem call
     # takes only the entry.
     class GemCopy < Data.define(:source, :target)
       def call(entry)