gemvault 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75dcaa67889b01ce7e4826681a8ce1f85d9e24e5ebc86f928ab43bfacff21cf2
-  data.tar.gz: d9ca2ade0cddd63f3ef42844324988c011e69591d0afbcd51aa1705a7d93afb4
+  metadata.gz: 3c643dd2d86d0a918dbecb5a8f20026746a0e60670eaa5590009fe35e6f9b9b0
+  data.tar.gz: fa0f695ae5d5d9ab9686caa479cc89c2c6954fc8c53bfdd02841cf12578622bd
 SHA512:
-  metadata.gz: 6356b69dcb629795799ae84ec52a9a998c5f511a55495322fb5832fb93b1d6fb6f1bad969a9a524540806e0f9727cc6c55a793aa4eb90d06beadf0799b4f5848
-  data.tar.gz: 3db86ee7bab4cc3cd27d390b4f7e43eb95e26d0977c2fdadcf32a18fb1084592b52e56a0ca1c775cb8f5f7aa0e8abb3d19edb8259956529d488002af1459f0ea
+  metadata.gz: d16d9d84c05c143a2372eaee7bd55b162aca32019a4709227f689ce47a4c725bd4d2d8a64b9b788f32d107ec37ae8c61b73178d547e60613a221bd55d48aff53
+  data.tar.gz: 21b8fbd66feeea5146546632f5636a194c698c2ab6aa1d51ae0d9544b021dc15f32d4c1171a98e92c67fe62b56cfe2f57dab5138fef2c8dc6a4bb5d194b1952d

data/.containerignore

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

data/.rubocop.yml

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

data/CHANGELOG.md

@@ -5,6 +5,62 @@ 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.
+
+- All CLI commands accept `vault://` and `file://` locators wherever they take
+  a vault path, e.g. `gemvault list vault:///path/to/myvault.gemv`; resolution
+  is shared with the RubyGems source via `Gemvault::VaultPath` (issue #9).
+
+### Fixed
+- `bundle plugin install bundler-source-vault` no longer dies with
+  `LoadError: cannot load such file -- bundler/plugin/vault_source`. The shim's
+  `plugins.rb` now derives the gem root from its own installed location (local
+  plugin root, global plugin root, or plain GEM_HOME), registers any spec dirs
+  RubyGems is not searching, and resets RubyGems' spec stub cache when it
+  predates the just-installed gems (issue #10).
+- `bundle exec` no longer fails Gemfile parsing with `Could not find 'bundler'
+  (>= 2.0)` under `path: vendor` on rubies that ship bundler as a regular gem:
+  gemvault no longer declares `bundler` as a runtime dependency (issue #12).
+- Vault gems whose versions carry a non-numeric suffix (e.g. `0.2.1.patch1`)
+  install from a vault with `gem install --pre`, matching RubyGems' prerelease
+  semantics (issue #6).
+
+### Changed
+- `sqlite3` is no longer a runtime dependency. Gemvault runs dependency-free on
+  the tarball path (including JRuby); `sqlite3` is loaded lazily only to read a
+  legacy SQLite vault, with a clear error if it is not installed.
+- `bundler` is no longer a runtime dependency; the Bundler plugin always runs
+  inside an existing Bundler process, and the declared dependency broke gem
+  activation in restricted GEM_PATH contexts.
+- CI is unblocked (issue #11): RuboCop's TargetRubyVersion now matches the
+  gemspec's `required_ruby_version` floor (3.4.8), the previously-missing
+  `spec:integration` rake task exists alongside a non-integration `spec:core`, the
+  unit job no longer needs podman, and the integration job installs podman
+  when the runner image lacks it.
+- Reading a vault's `manifest.json` is now strict: an entry missing any required
+  field (`name`, `version`, `platform`, `created_at`, `sha256`, `encrypted`)
+  raises instead of silently loading `nil` fields, so a truncated or hand-edited
+  manifest fails fast rather than yielding a subtly broken vault.
+
+### Deprecated
+- The SQLite vault format is deprecated and now **read-only**: existing SQLite
+  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

@@ -17,6 +17,7 @@ Do NOT modify `.rubocop.yml` or use inline `# rubocop:disable` tags without expl
 9. ALWAYS write specs first. The workflow is: identify the domain concept (rule 5), write specs describing its behavior, then implement. No implementation without a failing spec.
 10. Integration specs are the first line of defense for CLI-tool bugs. For any bug reported from using the CLI tool (not the gemvault lib / Ruby API), the FIRST spec you write is an integration spec that reproduces the user's exact invocation — real subprocess, real vault, real exit code. Stub-heavy unit specs are complementary, not sufficient: they prove internal logic produces the expected value assuming surrounding wiring works, but a user's bug report is evidence the wiring didn't work.
 11. If an integration spec is not catching a reported CLI-tool bug, one of two things is true, and the fix starts by diagnosing which: (a) existing integration specs are not specific enough — extend them to cover the exact scenario before touching production code; or (b) the scenario is not spec'd at all, which means the work is not a bug fix but a new feature — write integration specs for the contract first (per rule 1), then implement.
+12. NEVER write to /tmp. Use /workspace/tmp
 
 ## Additional rules
 
@@ -25,7 +26,7 @@ Do NOT modify `.rubocop.yml` or use inline `# rubocop:disable` tags without expl
 
 ## Project Overview
 
-Multi-gem portable archives backed by SQLite. A single `.gemv` file contains multiple `.gem` files.
+Multi-gem portable archives. A single `.gemv` file is a tarball holding multiple `.gem` files plus a `manifest.json` index; legacy SQLite vaults are read-only.
 
 Two gems, one repo:
 
@@ -56,7 +57,7 @@ gem install --source file:///path/to/myvault.gemv foo
 ## Architecture
 
 - `gemvault.gemspec` — main gem spec (name: `gemvault`)
-- `lib/gemvault/vault.rb` — Core vault class (SQLite CRUD for gem blobs + specs)
+- `lib/gemvault/vault.rb` — Vault facade choosing a backend by file format (Tarvault current, legacy Dbvault read-only)
 - `lib/gemvault/cli.rb` — CLI dispatcher (new/add/list/remove/extract)
 - `lib/bundler/plugin/vault_source.rb` — Bundler `Plugin::API::Source` implementation
 - `lib/rubygems_plugin.rb` — RubyGems plugin: monkey-patches for `--source myvault.gemv` support
@@ -69,7 +70,7 @@ gem install --source file:///path/to/myvault.gemv foo
 
 ## Key Design Decisions
 
-- SQLite storage — random access, ACID, single file, inspectable with `sqlite3` CLI
+- Tar storage — portable, dependency-free, single file, inspectable with `tar`; legacy SQLite vaults readable via lazily-loaded sqlite3
 - Specs extracted from gem blobs at runtime (no separate spec storage)
 - Vault opened/closed per operation in the source plugin (no persistent connection)
 - `fetch_gemspec_files` checks installed state — Bundler computes `full_gem_path` as `dirname(loaded_from)`, so `loaded_from` must point inside the gem directory
@@ -93,7 +94,7 @@ Integration tests use a manually-written Bundler plugin index to avoid rubygems.
 
 ## Dependencies
 
-- `sqlite3` (~> 2.0) — runtime
-- `bundler` (>= 2.0) — runtime
+- `bundler` — NOT a dependency; the plugin always runs inside an existing Bundler process, and declaring it breaks gem activation under `bundle exec`'s restricted GEM_PATH
 - `command_kit` (~> 0.6) — runtime (CLI)
+- `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,17 @@ 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 read the committed legacy SQLite (Dbvault) fixture it
+# migrates.
+RUN gem install --no-document sqlite3
+
+# Gem files for integration specs that install the plugin from a local gem
+# index at spec runtime, kept for offline use: command_kit is gemvault's
+# runtime dependency; the bundler gem lets specs simulate distro rubies where
+# bundler is a regular (non-default) gem.
+RUN mkdir -p /opt/gems \
+    && cd /opt/gems \
+    && gem fetch command_kit -v 0.6.0 \
+    && gem fetch bundler -v "$(ruby -rbundler -e 'print Bundler::VERSION')"

data/README.md

@@ -1,8 +1,8 @@
 # Gemvault
 
-A gem server in a file. No HTTP. No infrastructure.
+A file that behaves like a private gem server.
 
-A `.gemv` file is a 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.
+You can commit it to your repo, drop it on S3, email it, put it on a USB drive, or whatever you feel like doing. Bundler and RubyGems read from it directly.
 
 ## Installation
 
@@ -27,7 +27,6 @@ end
 bundle install
 ```
 
-Bundler auto-discovers the `bundler-source-vault` plugin, installs it, and resolves gems from the vault alongside rubygems.org. No extra configuration.
 
 ### RubyGems CLI
 
@@ -44,16 +43,29 @@ 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
 ```
 
-## How It Works
+## 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.
 
-A `.gemv` file is a SQLite database containing gem metadata and raw `.gem` blobs. You can inspect it directly:
+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
-sqlite3 myvault.gemv "SELECT name, version, platform FROM gems"
+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
+
+The gemv file is a tarball containing your .gem files and a json manifest. It has no dependencies other than the tar utilities that rubygems provides.
+
 When Bundler sees `type: :vault` in your Gemfile, it auto-installs the `bundler-source-vault` plugin from rubygems.org. The plugin implements the `Bundler::Plugin::API::Source` interface — it reads gemspecs from the vault, participates in dependency resolution, then extracts and installs gems from the vault's blob storage.
 
 The RubyGems plugin works similarly: `gem install --source vault.gemv` loads specs and extracts gems on demand.

data/Rakefile

@@ -10,6 +10,14 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
+RSpec::Core::RakeTask.new("spec:core") do |t|
+  t.rspec_opts = "--tag ~integration"
+end
+
+RSpec::Core::RakeTask.new("spec:integration") do |t|
+  t.rspec_opts = "--tag integration"
+end
+
 require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
@@ -43,12 +51,23 @@ namespace :spec do
   task(:teardown) { destroy_cached_image if cached_image_exists? }
 end
 
+directory "pkg" do
+  mkdir "pkg"
+end
+
 namespace :shim do
   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["spec:integration"].enhance ["spec:setup"]
 Rake::Task[:build].enhance ["shim:build"]
 Rake::Task[:release].enhance ["shim:release"]
 Rake::Task[:clobber].enhance ["spec:teardown"]

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_