gemvault 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c8bf335258cabfbfbe016fe547e1302da87c37060d1523cae394e941bd493dd
-  data.tar.gz: f4a027c561cb8edf619f777989654d657bae70d741106ba8730b540b38de7f2f
+  metadata.gz: d8478b689eb6f6b68e0c18872f4b2ca47034b1bd93ef9d0d16ecb92e8666de85
+  data.tar.gz: cb7f53a602a6b55a1a0593eda146635197e79dadb7366ca930a1e67b5b40d80d
 SHA512:
-  metadata.gz: 9f3691b960faaa2d6ab493d18363091691ce3ac106a23d8859a052e946fd6aaa78178282da8269823e07c21cf52cb5ba5e9e262c51767aea19d805b620ee6287
-  data.tar.gz: 99feeb31a5af138c4da80b61b3fe3853cd545044954b895e202d57a5f7c2817b3cb59701f752140efbce75c839120f4b6bcf0a5871a806a94cc80cc6d12670ed
+  metadata.gz: afa47c5b978c008d5fe46fb7399a3d1625505c8ad502d7e86e54c2f59a74b20b77077db8a31e60c70e294beeb54d51e8b808e005196c0b42f5e7e5cba0237574
+  data.tar.gz: b9a93c14eaeb496f1a46e78494b6129faeb8501333f678a85e8d1d07afb1a14465b32f7cc941eed294eae0bb7c319dcbbd5a0264305843394a4f1a1113a62530

data/CHANGELOG.md

@@ -9,15 +9,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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.
+  plain-text `manifest` 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.
+  preserving every gem, writing a `.bak` backup by default, with `--dry-run` and
+  `--no-backup` flags. Timestamps survive a v1 upgrade; a v2 vault's are
+  restamped, its stored times living in an index this gemvault no longer reads
+  (see Changed). 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
@@ -83,17 +85,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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.
+  distro ruby, where json is a default gem upstream but a separate package that
+  `dnf install ruby` leaves absent. json backed the tarball vault's manifest
+  when this was first fixed by declaring it a runtime dependency; the manifest
+  is now plain text and gemvault never loads json at runtime, so the failure is
+  retired outright rather than papered over (see Changed, issue #25).
 - 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.
+  therefore skips its dependencies, so a declared dependency (json, at the time)
+  never reached 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. The manifest being plain text, nothing on this path requires json at all
+  (see Changed, issue #25).
 - `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
@@ -101,6 +106,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   gemvault through `require_relative` alone (issue #13).
 
 ### Changed
+- The manifest is now line-oriented text rather than JSON (vault format 3).
+  It was never document-shaped: a header plus one whitespace-separated line
+  per gem — name, version, platform, stored-at, SHA256, encrypted — with no
+  nesting and no free text, so `tar -xOf myvault.gemv manifest` gives you
+  something `grep` and `awk` read directly. Because every field comes from an
+  alphabet without whitespace, reading needs no parser beyond `split` plus
+  per-field validation: no recursion to exhaust the stack, no escape grammar,
+  and no library to load — which is what stops gemvault from ever activating
+  a json gem a project had locked (issue #25). Times are stored as
+  `2026-08-12T18:23:32Z`; a legacy vault's `2026-08-12 18:23:32` is converted
+  on upgrade. A format-2 vault (`manifest.json`) stays readable: it opens
+  read-only through the same path a legacy SQLite vault does, and
+  `gemvault upgrade` migrates it. That backend never parses the old manifest —
+  it derives the index from the stored gems, each of which carries its own
+  gemspec — so migrated gems keep their identity but are restamped, the old
+  index's times being unrecoverable.
 - `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.
@@ -112,10 +133,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `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.
+- Reading a vault's manifest is now strict: every field is validated against
+  its own alphabet, 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

@@ -27,7 +27,7 @@ Do NOT modify `.rubocop.yml` or use inline `# rubocop:disable` tags without expl
 
 ## Project Overview
 
-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.
+Multi-gem portable archives. A single `.gemv` file is a tarball holding multiple `.gem` files plus a line-oriented `manifest` index; legacy SQLite vaults are read-only.
 
 Two gems, one repo:
 
@@ -58,7 +58,10 @@ gem install --source file:///path/to/myvault.gemv foo
 ## Architecture
 
 - `gemvault.gemspec` — main gem spec (name: `gemvault`)
-- `lib/gemvault/vault.rb` — Vault facade choosing a backend by file format (Tarvault current, legacy Dbvault read-only)
+- `lib/gemvault/vault.rb` — Vault facade choosing a backend by file format (Tarvault current; Dbvault and LegacyTarvault read-only)
+- `lib/gemvault/legacy_tarvault.rb` — read-only backend for a format-2 (manifest.json) vault; derives its index from the stored gems instead of parsing that manifest, so `gemvault upgrade` migrates one through the ordinary pipeline
+- `lib/gemvault/manifest_text.rb` — the manifest's on-disk notation: a header plus one whitespace-separated line per gem, validated field by field on read
+- `lib/gemvault/timestamp.rb` — the space-free notation a vault records times in, and conversion of a legacy vault's times into it
 - `lib/gemvault/cli.rb` — CLI dispatcher (new/add/list/remove/extract)
 - `lib/gemvault/ghost_specification.rb` — installation records whose gem directory is gone; swept by `gemvault doctor` (issue #23)
 - `lib/bundler/plugin/vault_source.rb` — Bundler `Plugin::API::Source` implementation
@@ -165,6 +168,6 @@ container.
 
 - `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` — NOT a dependency, though it backs the tarball vault's manifest. A default gem upstream; distros that unbundle it (Fedora's `rubygem-json`) still install it alongside ruby itself, and it stays requireable even under `bundle exec`'s restricted view. Declaring it would compile a native extension on every `gem install gemvault` for no gain.
+- `json` — NOT a dependency and never loaded at runtime. The manifest is a table, not a document, so `Gemvault::ManifestText` reads and writes it directly; nothing in `lib/` may `require "json"`. On rubies where require resolves through gem activation, a require inside a Bundler process activates the newest installed json and a project locking an older one dies in `check_for_activated_spec!` (issue #25).
 - `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`, `rspec`, `rake` — development

data/README.md

@@ -48,23 +48,33 @@ 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.
+Every vault records an on-disk **format version** — `1` for the original SQLite format, `2` for a tarball with a JSON manifest, `3` for the current tarball with a plain-text manifest. 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:
+Formats `1` (SQLite) and `2` (JSON manifest) are **deprecated and read-only**: you can still list, extract from, and migrate an existing one, 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              # e.g. SQLite (v1) or JSON manifest (v2) -> current (v3)
 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.
+`upgrade` preserves every gem, writes `myvault.gemv.bak` by default, and is a no-op on an already-current vault. Timestamps survive a v1 upgrade; a v2 vault's are restamped, because its stored times live in the JSON index this gemvault deliberately no longer reads — the gems themselves are read straight out of the tarball.
 
 ## How It Works
 
-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.
+The gemv file is a tarball containing your .gem files and a plain-text manifest. It has no dependencies other than the tar utilities that rubygems provides.
+
+```console
+$ tar -xOf myvault.gemv manifest
+gemvault 3
+created 2026-08-12T18:23:32Z
+
+rails 7.1.3 ruby 2026-08-12T18:23:32Z 9f2c...  0
+```
+
+One header, then one line per gem: name, version, platform, when it was stored, its SHA256, and whether it is encrypted. Every field is drawn from an alphabet without whitespace, so reading the index needs no parser beyond `split` — and `grep`, `awk` and `cut` work on it directly.
 
 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/issues.rec

@@ -1163,7 +1163,62 @@ Description: Project with Gemfile + locked json version + gemvault throws "bundl
 + /Users/davidgillis/.rbenv/versions/4.0.1/lib/ruby/gems/4.0.0/gems/bundler-4.0.18/lib/bundler/runtime.rb:328:in 'Bundler::Runtime#check_for_activated_spec!': You have already activated json 2.21.2, but your Gemfile requires json 2.19.7. Prepending `bundle exec` to your command may solve this. (Gem::LoadError)"
 + 
 + I believe this error to be coming from gemvault's dependency on JSON. It is clear that dependencies are cursed in this project, whether its the added load time for reinstalling them on every `bundle install`, or errors like this one. Rather than rely on JSON, I think it would be better to just marshal our own manifest, or use some other serialization tool if any that rubygems already provides.
-Status: open
++
++ RESOLUTION: gemvault no longer loads json, and the manifest is no longer a
++ JSON document. Whether gemvault's require was the activator on the reported
++ machine cannot be settled from here -- on the Fedora reproduction stack
++ require resolves json from the stdlib path with no activation at all, and
++ bundler loads json itself before the vault source runs -- but on rbenv-style
++ stacks require does activate, gemvault held a live require in its
++ vault-read path, and it can no longer be the component that detonates
++ check_for_activated_spec!.
++
++ Marshal was considered as the reporter suggested and rejected: a .gemv is a
++ file that arrives from elsewhere, the manifest is the root of trust (the
++ SHA256 digests live inside it, so nothing verifies it first), and
++ Marshal.load runs attacker-chosen code during load itself -- demonstrated
++ here, a hash key's #hash fires inside load before the caller touches the
++ result. `gemvault list` on an untrusted vault would become arbitrary code
++ execution, and Marshal's versioned wire format would break the portability
++ a .gemv exists for.
++
++ What replaced JSON is neither: the manifest was never document-shaped. It is
++ a table -- a header plus fixed-arity records of scalars, no nesting, no free
++ text -- and every field is drawn from an alphabet without whitespace once
++ times are canonicalized (Gemvault::Timestamp; rubygems itself validates gem
++ names against /\A[a-zA-Z0-9._-]+\z/). Gemvault::ManifestText writes and
++ reads it as lines. There is no recursion to exhaust the stack, no escape
++ grammar, no backtracking, and no library to load -- the same reasoning that
++ keeps BundlerPluginIndex from requiring yaml. Reading validates every field
++ and rejects everything else, because the file comes from elsewhere; writing
++ trusts the value objects this library constructed. Precedent is rubygems'
++ own compact index and Gemfile.lock, both line-oriented text.
++
++ Format version 3; vaults are inspectable with `tar -xOf v.gemv manifest`.
++
++ An existing format-2 vault keeps working. Gemvault::LegacyTarvault opens one
++ read-only, exactly as Dbvault does for SQLite, so `gemvault upgrade` migrates
++ it through the ordinary pipeline rather than leaving its gems stranded behind
++ an error. That backend never parses manifest.json: it derives the index from
++ the payload, since every stored .gem carries the gemspec the manifest's
++ identity fields came from -- which keeps the old notation from re-entering
++ the codebase and makes the reader indifferent to a damaged manifest. Two
++ things the old index held are lost with it: each gem's stored time (entries
++ are restamped on open, and the deprecation notice says so) and the per-gem
++ digests (the new vault records fresh digests of exactly the bytes it copied).
++ Covered end to end by spec/integration/cli/commands/legacy_tarvault_spec.rb
++ against a committed format-2 fixture: list, extract, refused add, upgrade,
++ and writing to the upgraded vault.
++
++ Settled after all: the Fedora image reproduces the rbenv-style stack once
++ the unbundled stdlib json is cleared away -- require then resolves through
++ gem activation, exactly the reported semantics.
++ spec/integration/locked_json_spec.rb runs the reporter's flow (a project
++ locking an older json than the machine's newest, gemvault ambient, bundle
++ exec through the vault source) and fails against a gemvault that requires
++ json on either the CLI path or the plugin path, the latter dying with the
++ reported check_for_activated_spec! error verbatim.
+Status: closed
 
 Id: 27
 Updated: Wed, 12 Aug 2026 16:05:55 +0000

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)

data/lib/gemvault/version.rb

@@ -1,3 +1,3 @@
 module Gemvault
-  VERSION = "0.2.6".freeze
+  VERSION = "0.2.7".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemvault
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.7
 platform: ruby
 authors:
 - David Gillis
@@ -78,9 +78,12 @@ files:
 - lib/gemvault/gem_reference/parser.rb
 - lib/gemvault/gem_reference/specific_version.rb
 - lib/gemvault/ghost_specification.rb
+- lib/gemvault/legacy_tarvault.rb
 - lib/gemvault/manifest.rb
+- lib/gemvault/manifest_text.rb
 - lib/gemvault/tarball.rb
 - lib/gemvault/tarvault.rb
+- lib/gemvault/timestamp.rb
 - lib/gemvault/vault.rb
 - lib/gemvault/vault_destination.rb
 - lib/gemvault/vault_path.rb