rspec-tracer 2.0.0.pre.1 → 2.0.0.pre.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04d2e3c76b8351f5f71f93cd722af23975f80da067f19970471455b3b2ed16aa
-  data.tar.gz: 0ab86f0d744275db42ed0d355d5781d25a6f65ed49a76fcd70d3df1acd7e01b4
+  metadata.gz: 552b92475298cfa692f8748b7b7097b12a82a2e8b1003848d1194fe560c0b385
+  data.tar.gz: 34a9d94756083aaf46220460c4d10002d30992703c1aad0e417640ad5b2d79ae
 SHA512:
-  metadata.gz: e802e4c67a41d1d1ebd16df2fd4ee874f0993678097563f38b5bd3e443024662040547df140dd45196c0e81e7d510ecfe79dbf4a3e01ab1a4685f380f9ec829f
-  data.tar.gz: 72435a0282503ff2c90b6b80168fb810bd48412bc162043b4d70780b35f74478fc5236c43710bb9e948657b2c6c17734a59406fc617cb712eaba7e1a3c2e4dfb
+  metadata.gz: 57b510bf3f8da2071a72ee222d598e9ce8042b5745cec84e053ea7b7db87e203e73829f890f105d934901835813cee66290ff0b24a07f278b1821c3b75febdb7
+  data.tar.gz: 57adb9424e1bdc3775294de9573726f3b80bea35615d6a41410985724d930faa00c984bf3c9b637297565fa11bf72c938bb92ce8464b7968c9be9fa5b476b2f2

data/CHANGELOG.md

@@ -1,3 +1,193 @@
+## [2.0.0.pre.2] - 2026-05-16
+
+Bug-fix + interop release after the field-test pass that followed
+`v2.0.0.pre.1`. 15 issues filed publicly
+([#182](https://github.com/avmnu-sng/rspec-tracer/issues/182)–[#196](https://github.com/avmnu-sng/rspec-tracer/issues/196))
+plus two follow-on findings
+([#210](https://github.com/avmnu-sng/rspec-tracer/issues/210) and
+[#218](https://github.com/avmnu-sng/rspec-tracer/issues/218))
+surfaced during fix-verification; all 17 are closed at tag. No CI
+surface drops, no Ruby / Rails / RSpec floor changes.
+
+The cumulative cache `schema_version` path is `3 → 5` (two bumps
+across [#209](https://github.com/avmnu-sng/rspec-tracer/pull/209)
+and [#211](https://github.com/avmnu-sng/rspec-tracer/pull/211));
+a pre.1 cache cold-loads cleanly on the pre.2 upgrade in one cold
+run, then warm caches resume. See [`UPGRADING.md`](UPGRADING.md).
+
+### Added
+
+- **`coverage_modes` config DSL** for the standalone Coverage
+  path (no SimpleCov). Pass any subset of
+  `[:lines, :branches, :methods, :oneshot_lines, :eval]`; default
+  `[:lines]` keeps byte-compatibility with prior runs. Threaded
+  through both `RSpecTracer.setup_coverage` and
+  `Engine#ensure_coverage_started`; inert when SimpleCov drives
+  Coverage. New COOKBOOK recipe "Coverage modes (rspec-tracer +
+  SimpleCov interop)" under recipe 9 documents the per-mode
+  interop matrix.
+- **`bin/rspec-tracer cache:clear --force` / `-f`** as a synonym
+  for `--yes` / `-y`. Matches the common Unix-CLI convention.
+- **COOKBOOK recipe for the `:msgpack` serializer** documenting
+  the `storage_backend :json, serializer: :msgpack` option for
+  ~3.5× smaller caches than `:json` on dependency-heavy suites.
+  Notes that `.msgpack.gz` payloads are raw `Zlib::Deflate`
+  streams (not gzip format) — the suffix is cosmetic and may
+  change in a future major release.
+
+### Changed
+
+- **Cache `schema_version` bump 3 → 5** (cumulative). The
+  `example_id` digest now drops the load-order-dependent
+  generated-class-name suffix and the line-number fields, and
+  substitutes a positional discriminator for unnamed
+  `it { }` / `specify { }` / `example { }` examples that
+  previously picked up RSpec's `"example at <path>:<line>"`
+  description fallback. First run on pre.2 is cold; subsequent
+  runs return to warm. See [`UPGRADING.md`](UPGRADING.md)
+  "Schema-version cold runs."
+- **Duplicate-example-identity detection now prune-and-continue.**
+  When the runner detects two examples with the same identity,
+  it drops the colliders from the run and lets the rest of the
+  suite proceed, instead of aborting the entire run to zero
+  examples. `fail_on_duplicates` becomes purely an exit-code
+  lever — the non-colliding remainder always runs. The error log
+  names the colliding examples (file:line + description) with a
+  remediation hint. See [`UPGRADING.md`](UPGRADING.md)
+  "Duplicate example identities."
+
+### Fixed
+
+- **Restored flaky-test detection across runs.** A top-line
+  README feature present in 1.x since v1.0.0; silently dropped
+  in the 2.0 rewrite — the registry `:flaky` status, the
+  `:flaky_example` filter reason, the `flaky_examples` snapshot
+  field, and the HTML reporter's Flaky tab were all retained,
+  but no production code path transitioned an example into
+  `:flaky`. `on_example_passed` now promotes a
+  previously-failed-or-flaky example into `:flaky`;
+  `on_example_failed` keeps a previously-flaky example sticky.
+  Closes [#194](https://github.com/avmnu-sng/rspec-tracer/issues/194).
+- **`run_reason` field in `report.json` (and the terminal
+  `by reason:` line) now persists the correct reason on warm
+  runs for every reason path** — `Failed previously`,
+  `Pending previously`, `Interrupted previously`, `Files changed`,
+  `Environment changed`. Previously displayed as `No cache` on
+  every warm-run case because `Engine#register_example`
+  short-circuited on the entry already seeded from the previous
+  snapshot. Single-character fix closing all five reason paths.
+  Closes [#186](https://github.com/avmnu-sng/rspec-tracer/issues/186).
+- **Parallel-`tests` `cache_hit_reason` counts no longer inflated
+  by worker count.** Each worker independently computed an
+  identical `filtered_examples` hash against the global
+  previous-run snapshot; the pre-fix sum-merge inflated
+  always-re-run buckets N-fold. The merge now keys on
+  `example_id` (first-write-wins), then re-tallies. Closes
+  [#193](https://github.com/avmnu-sng/rspec-tracer/issues/193).
+- **`example_id` stable across runs when multiple files share a
+  `describe` name** (the load-order-dependent
+  `RSpec::ExampleGroups::Name_N` disambiguator suffix is no
+  longer in the digest) **and stable across line-shift edits for
+  unnamed one-liner examples** (`it { is_expected.to eq(7) }`,
+  `specify { ... }`, `example { ... }`). Long-standing bugs since
+  v1.0.0; pervasive in shoulda-matchers model specs which are
+  almost entirely one-liner matcher syntax. Closes
+  [#196](https://github.com/avmnu-sng/rspec-tracer/issues/196)
+  + [#210](https://github.com/avmnu-sng/rspec-tracer/issues/210).
+- **NPE in `RSpec.world.example_count` for suites with
+  intermediate describe groups after rspec-tracer drops a
+  duplicate-identity example.** Companion fix to the
+  duplicate-detection prune-and-continue redesign above — the
+  kept-map needed a default block so descendants of an
+  intermediate describe (a describe containing only nested
+  describes, no direct `it`s) resolve to an empty array on the
+  `filtered_examples` lookup instead of `nil`. Closes
+  [#218](https://github.com/avmnu-sng/rspec-tracer/issues/218).
+- **`storage_backend :json, serializer: :msgpack` no longer
+  crashes on `Time` values** (and `Symbol` values now round-trip
+  losslessly across the cache). Registered
+  `MessagePack::Factory` type extensions for `Time` (12-byte
+  `tv_sec + tv_nsec`, UTC-canonicalized on decode) and `Symbol`
+  (UTF-8 body). Users who followed rspec-tracer's own 50 MiB
+  cache warning's `:msgpack` recommendation no longer brick
+  their cache silently on the first run that writes a `Time`.
+  Closes [#182](https://github.com/avmnu-sng/rspec-tracer/issues/182).
+- **`bin/rspec-tracer cache:info` and `explain` now compose with
+  `storage_backend :sqlite`.** Previously hardcoded the
+  JsonBackend on-disk layout and reported `no last_run.json yet`
+  on every sqlite run, even after a successful rspec. Both CLI
+  sub-commands now dispatch through a shared
+  `Storage::Backend.build` factory; sqlite metadata-table reads
+  surface alongside JSON manifest reads behind the same
+  protocol. Closes
+  [#183](https://github.com/avmnu-sng/rspec-tracer/issues/183).
+- **`bin/rspec-tracer doctor` no longer false-reports `SimpleCov:
+  not loaded` / `Rails: not loaded`** when those gems ARE in the
+  Gemfile (doctor runs in its own process; app code doesn't load
+  there). Three states are now reported: loaded-in-this-process
+  (`OK`), installed-but-not-loaded
+  (`INFO ... installed (<version>; not loaded in doctor's process)`),
+  and not-installed (`INFO ... not installed`). Closes
+  [#184](https://github.com/avmnu-sng/rspec-tracer/issues/184).
+- **`bin/rspec-tracer` invocation guidance flipped to
+  `bundle exec rspec-tracer`** across README, COOKBOOK, and
+  UPGRADING. The bare `bin/rspec-tracer` form required users to
+  run `bundle binstubs rspec-tracer` first; `bundle exec
+  rspec-tracer` works out of the box. Closes
+  [#185](https://github.com/avmnu-sng/rspec-tracer/issues/185).
+- **`reports_s3_path` deprecation warning no longer false-flags
+  on the probe path** — when no `remote_cache_backend` /
+  `remote_cache_uri` is configured AND the user runs
+  `rake rspec_tracer:remote_cache:download` / `:upload` /
+  `:prune_all`. A new non-warning predicate gates the probe; the
+  deprecation now fires only on legitimate use of the legacy
+  DSL. Closes
+  [#187](https://github.com/avmnu-sng/rspec-tracer/issues/187).
+- **`remote_cache` success now emits visible INFO lines** for
+  `download!` (`restored cache from <ref>` — with a
+  `(cross-branch fallback)` qualifier when a PR-tier download
+  falls through to a commit-ancestry ref successfully),
+  `upload!` (`uploaded cache to <ref>`), and `prune_all!`
+  (`prune_all removed N refs`). One fix covers all three
+  backends (s3 / redis / file) + the cron-driven `prune_all`
+  admin task. Closes
+  [#188](https://github.com/avmnu-sng/rspec-tracer/issues/188).
+- **`track_ar_schema_notifications` now installs correctly under
+  the canonical README setup order** (`RSpecTracer.start` BEFORE
+  `require_relative '../config/environment'`). Previously,
+  `defined?(::Rails::VERSION)` was false at engine.setup time
+  and the entire Rails-observer install path short-circuited —
+  the `sql.active_record` subscriber never attached AND the
+  documented `use_transactional_fixtures`-widening warn never
+  fired. Now late-binds via a `before(:suite)` hook that
+  re-checks Rails-loaded state after `rails_helper.rb` has
+  required the environment. Closes
+  [#192](https://github.com/avmnu-sng/rspec-tracer/issues/192).
+- **`RSpecTracer.start` no longer crashes** when the user
+  pre-starts `::Coverage` (e.g. to opt into branch coverage for
+  SimpleCov-free runs). The `setup_coverage` entry point now
+  matches `Engine#ensure_coverage_started`'s `Coverage.running?`
+  guard + `RuntimeError` rescue. Closes
+  [#195](https://github.com/avmnu-sng/rspec-tracer/issues/195).
+- **`InvalidUsageError` raised on conflicting
+  `remote_cache_backend` / `remote_cache_uri` configuration now
+  names both DSLs and explains they are alternatives.** The
+  previous `<dsl> already configured` message was confusing when
+  the user only typed `remote_cache_uri` (which dispatches
+  internally to `remote_cache_backend`).
+- **README per-example-precision section now covers Rails
+  engines.** An engine's own `lib/` is `require`d at gem-load
+  time via the Gemfile.lock cascade and lands in the boot set
+  **regardless of `eager_load`**. COOKBOOK gains a
+  `transitive_load_tracking false` opt-out recipe with the
+  trade-off documented. Closes
+  [#189](https://github.com/avmnu-sng/rspec-tracer/issues/189).
+- **Engine + dummy-app two-rspec-summary explainer** added to
+  COOKBOOK — clarifies which of the two terminal summary totals
+  is authoritative when an engine fixture invokes RSpec against
+  its dummy app. Closes
+  [#190](https://github.com/avmnu-sng/rspec-tracer/issues/190).
+
 ## [2.0.0.pre.1] - 2026-05-06
 
 The first pre-release of the 2.0 line. Architecture rewrite around

data/README.md

@@ -48,7 +48,7 @@ Rails 8.0 needs Ruby 3.2+. JRuby 9.4 is supported.
    ```ruby
    # 2.0 is in pre-release. Pin to the pre-release version explicitly;
    # switch to '~> 2.0' once 2.0.0 final ships.
-   gem 'rspec-tracer', '= 2.0.0.pre.1', group: :test, require: false
+   gem 'rspec-tracer', '= 2.0.0.pre.2', group: :test, require: false
    ```
 
    `bundle install` will resolve the pre-release version. You can
@@ -144,6 +144,17 @@ eager-loaded test environments — see
 [`CHANGELOG.md`](CHANGELOG.md) "Deferred to 2.1" for the planned
 contract.
 
+**Rails engines:** a gem-loaded engine's own `lib/` files are
+`require`d at gem-load time via the Gemfile.lock cascade and land
+in the boot set **regardless of `eager_load`**. Editing them
+re-runs every example — same SAFE-but-coarser shape as the
+`eager_load = true` case above. The rationale (closing the
+constants-lookup blind spot) lives in
+[`lib/rspec_tracer/tracker/loaded_files_tracker.rb`](lib/rspec_tracer/tracker/loaded_files_tracker.rb).
+Teams that want tighter per-example precision and accept the blind
+spot can set `transitive_load_tracking false` — see
+[`COOKBOOK.md`](COOKBOOK.md) recipe 2 for the trade-off.
+
 ## Per-example `tracks:` DSL
 
 Annotate any describe / context / example with extra inputs the
@@ -365,19 +376,23 @@ Or override per-run via env: `RSPEC_TRACER_STORAGE=sqlite`.
 
 ## Command-line tools
 
-`bin/rspec-tracer` exposes five sub-commands:
+`rspec-tracer` exposes five sub-commands. Run them via Bundler so the
+gem's executable resolves cleanly without needing `bundle binstubs
+rspec-tracer` first:
 
 ```sh
-bin/rspec-tracer doctor         # diagnose config + environment
-bin/rspec-tracer cache:info     # size, last run, invalidation stats
-bin/rspec-tracer cache:clear    # rm cache dirs
-bin/rspec-tracer report:open    # open the HTML report
-bin/rspec-tracer explain <id>   # why is <example_id> scheduled to (re-)run?
+bundle exec rspec-tracer doctor         # diagnose config + environment
+bundle exec rspec-tracer cache:info     # size, last run, invalidation stats
+bundle exec rspec-tracer cache:clear    # rm cache dirs
+bundle exec rspec-tracer report:open    # open the HTML report
+bundle exec rspec-tracer explain <id>   # why is <example_id> scheduled to (re-)run?
 ```
 
-The CLI is opt-in for local-dev convenience. The
-`rake rspec_tracer:remote_cache:*` tasks remain first-class for CI
-integration — nothing in the CLI replaces them.
+Generated binstubs (`bin/rspec-tracer …`) work too once you've run
+`bundle binstubs rspec-tracer` in your project. The CLI is opt-in for
+local-dev convenience; the `rake rspec_tracer:remote_cache:*` tasks
+remain first-class for CI integration — nothing in the CLI replaces
+them.
 
 ## SimpleCov interop
 

data/lib/rspec_tracer/cli/cache_clear.rb

@@ -23,8 +23,7 @@ module RSpecTracer
         return nothing_to_remove(stdout) if existing.empty?
 
         announce(stdout, existing)
-        force = args.include?('--yes') || args.include?('-y')
-        return aborted(stdout) unless force || confirm?(stdout)
+        return aborted(stdout) unless skip_confirmation?(args) || confirm?(stdout)
 
         remove_each(stdout, existing)
         0
@@ -33,6 +32,19 @@ module RSpecTracer
         1
       end
 
+      # Returns true when any of the documented skip-confirmation
+      # flags is present. `--yes` / `-y` is the canonical form;
+      # `--force` / `-f` is the Unix-conventional synonym accepted
+      # so users' muscle memory works. Either form skips the
+      # interactive `Proceed? [y/N]` prompt.
+      # @api private
+      SKIP_CONFIRMATION_FLAGS = %w[--yes -y --force -f].freeze
+
+      # @api private
+      def self.skip_confirmation?(args)
+        args.any? { |arg| SKIP_CONFIRMATION_FLAGS.include?(arg) }
+      end
+
       # Internal helper for the tracer pipeline.
       # @api private
       def self.existing_targets
@@ -83,13 +95,14 @@ module RSpecTracer
       # @api private
       def self.print_help(stdout)
         stdout.puts <<~HELP
-          Usage: rspec-tracer cache:clear [--yes]
+          Usage: rspec-tracer cache:clear [--yes | --force]
 
           Remove cache, coverage, and report directories. The next rspec
           run will be a cold run (full re-execution + cache rebuild).
 
           Options:
-            -y, --yes   Skip the confirmation prompt.
+            -y, --yes     Skip the confirmation prompt.
+            -f, --force   Synonym for --yes.
         HELP
         0
       end

data/lib/rspec_tracer/cli/cache_info.rb

@@ -1,14 +1,19 @@
 # frozen_string_literal: true
 
-require 'json'
+require 'rspec_tracer/storage/backend'
+require 'rspec_tracer/storage/json_backend'
+require 'rspec_tracer/storage/schema'
+require 'rspec_tracer/storage/sqlite_backend' if RUBY_ENGINE == 'ruby'
 
 module RSpecTracer
   # Internal CLI — see {RSpecTracer} for the user-facing surface.
   # @api private
   module CLI
     # `rspec-tracer cache:info` — show cache size, last run, and
-    # invalidation stats. Reads `last_run.json` + the run-id'd JSON
-    # files written by Storage::JsonBackend.
+    # invalidation stats. Backend-agnostic: dispatches through
+    # {RSpecTracer::Storage::Backend.build} so `storage_backend
+    # :sqlite` reports the populated cache instead of the false
+    # "no cache yet" the JsonBackend-only path used to emit.
     module CacheInfo
       # @param args [Array<String>] sub-command args (`-h` / `--help`).
       # @param stdout [IO]
@@ -23,18 +28,15 @@ module RSpecTracer
         stdout.puts "cache_path: #{cache_path}"
         stdout.puts "size:       #{format_bytes(directory_size(cache_path))}"
 
-        last_run_path = File.join(cache_path, 'last_run.json')
-        unless File.file?(last_run_path)
-          stdout.puts 'last_run:   no last_run.json yet (run rspec first)'
+        backend = Storage::Backend.build(cache_path: cache_path, configuration: RSpecTracer)
+        run_id = backend.last_run_id
+        if run_id.nil? || run_id.to_s.empty?
+          stdout.puts 'last_run:   no cache yet (run rspec first)'
           return 0
         end
 
-        manifest = JSON.parse(File.read(last_run_path, encoding: 'UTF-8'))
-        run_id = manifest['run_id']
         stdout.puts "last_run:   #{run_id}"
-        stdout.puts "generated:  #{manifest['generated_at']}" if manifest['generated_at']
-
-        print_run_summary(stdout, cache_path, run_id) if run_id
+        print_example_count(stdout, backend)
         0
       rescue StandardError => e
         stderr.puts "cache:info: #{e.class}: #{e.message}"
@@ -48,24 +50,23 @@ module RSpecTracer
           Usage: rspec-tracer cache:info
 
           Show the on-disk cache size, the last run id, and example counts
-          for the most recent run. Reads `last_run.json` plus the run-id'd
-          JSON files; does not modify any files.
+          for the most recent run. Backend-aware: works under
+          `storage_backend :json` (default) and `storage_backend :sqlite`.
+          Read-only; does not modify the cache.
         HELP
         0
       end
 
       # Internal helper for the tracer pipeline.
       # @api private
-      def self.print_run_summary(stdout, cache_path, run_id)
-        run_dir = File.join(cache_path, run_id)
-        return unless File.directory?(run_dir)
-
-        all_examples_path = File.join(run_dir, 'all_examples.json')
-        return unless File.file?(all_examples_path)
+      def self.print_example_count(stdout, backend)
+        snapshot = backend.load_graph(schema_version: Storage::Schema::CURRENT)
+        if snapshot.nil?
+          stdout.puts 'examples:   <unknown> (schema mismatch; next rspec run will be cold)'
+          return
+        end
 
-        data = JSON.parse(File.read(all_examples_path, encoding: 'UTF-8'))
-        total = data.size
-        stdout.puts "examples:   #{total} tracked"
+        stdout.puts "examples:   #{snapshot.all_examples.size} tracked"
       end
 
       # Internal helper for the tracer pipeline.

data/lib/rspec_tracer/cli/doctor.rb

@@ -109,24 +109,33 @@ module RSpecTracer
         end
       end
 
-      # Internal helper for the tracer pipeline.
-      # @api private
+      # `bundle exec rspec-tracer doctor` runs in its own process via
+      # the gem's `bin/rspec-tracer` binstub, NOT inside the user's
+      # rspec boot — so app code never loads here and a bare
+      # `defined?(::SimpleCov)` check would falsely report "not
+      # loaded" on projects that DO have SimpleCov in their
+      # Gemfile. Probe `Gem.loaded_specs` first to surface the
+      # "installed but not loaded in doctor's process" case
+      # separately from "actually not installed."
       def self.simplecov_check
-        if defined?(::SimpleCov)
-          'OK   SimpleCov:   loaded (interop active)'
-        else
-          'INFO SimpleCov:   not loaded (this is fine; SimpleCov is optional)'
-        end
+        return 'OK   SimpleCov:   loaded (interop active)' if defined?(::SimpleCov)
+
+        spec = Gem.loaded_specs['simplecov']
+        return "INFO SimpleCov:   installed (v#{spec.version}; not loaded in doctor's process)" if spec
+
+        'INFO SimpleCov:   not installed (this is fine; SimpleCov is optional)'
       end
 
-      # Internal helper for the tracer pipeline.
-      # @api private
+      # See {.simplecov_check} for the doctor-runs-in-its-own-
+      # process rationale. Same three-state probe shape: loaded in
+      # this process / installed but not loaded / not installed.
       def self.rails_check
-        if defined?(::Rails::VERSION) && !::Rails::VERSION.nil?
-          "OK   Rails:       #{::Rails::VERSION::STRING}"
-        else
-          'INFO Rails:       not loaded (this is fine for non-Rails projects)'
-        end
+        return "OK   Rails:       #{::Rails::VERSION::STRING}" if defined?(::Rails::VERSION) && !::Rails::VERSION.nil?
+
+        spec = Gem.loaded_specs['rails']
+        return "INFO Rails:       installed (v#{spec.version}; not loaded in doctor's process)" if spec
+
+        'INFO Rails:       not installed (this is fine for non-Rails projects)'
       end
 
       # Surface a 1.x->2.0 cache mismatch BEFORE the user runs

data/lib/rspec_tracer/cli/explain.rb

@@ -1,16 +1,19 @@
 # frozen_string_literal: true
 
-require 'json'
+require 'rspec_tracer/storage/backend'
+require 'rspec_tracer/storage/json_backend'
+require 'rspec_tracer/storage/schema'
+require 'rspec_tracer/storage/sqlite_backend' if RUBY_ENGINE == 'ruby'
 
 module RSpecTracer
   # Internal CLI — see {RSpecTracer} for the user-facing surface.
   # @api private
   module CLI
     # `rspec-tracer explain <example>` — show why a given example is
-    # scheduled to run or skip on the next rspec invocation. Reads the
-    # most recent run's JSON files (all_examples.json + dependency.json
-    # + failed_examples.json + flaky_examples.json) to surface the
-    # dependency set, last-run status, and the run-decision reason.
+    # scheduled to run or skip on the next rspec invocation. Backend-
+    # agnostic: dispatches through {RSpecTracer::Storage::Backend.build}
+    # so `storage_backend :sqlite` resolves the latest run from the
+    # meta table instead of the JsonBackend-only `last_run.json` file.
     module Explain
       # @param args [Array<String>] sub-command args. First positional
       #   arg is the example_id (or substring) to explain.
@@ -24,14 +27,13 @@ module RSpecTracer
         require 'rspec_tracer/load_config'
         cache_path = RSpecTracer.cache_path
 
-        run_dir = resolve_run_dir(cache_path, stderr)
-        return 1 if run_dir.nil?
+        snapshot = load_snapshot(cache_path, stderr)
+        return 1 if snapshot.nil?
 
-        all_examples = read_json(File.join(run_dir, 'all_examples.json'))
-        match = find_example(all_examples, args.first)
-        return no_match(args.first, all_examples, stderr) if match.nil?
+        match = find_example(snapshot.all_examples, args.first)
+        return no_match(args.first, snapshot.all_examples, stderr) if match.nil?
 
-        print_explanation(stdout, match, run_dir)
+        print_explanation(stdout, match, snapshot)
         0
       rescue StandardError => e
         stderr.puts "explain: #{e.class}: #{e.message}"
@@ -40,21 +42,21 @@ module RSpecTracer
 
       # Internal helper for the tracer pipeline.
       # @api private
-      def self.resolve_run_dir(cache_path, stderr)
-        last_run_path = File.join(cache_path, 'last_run.json')
-        unless File.file?(last_run_path)
-          stderr.puts "explain: no last_run.json at #{cache_path} — run rspec first"
+      def self.load_snapshot(cache_path, stderr)
+        backend = Storage::Backend.build(cache_path: cache_path, configuration: RSpecTracer)
+        run_id = backend.last_run_id
+        if run_id.nil? || run_id.to_s.empty?
+          stderr.puts "explain: no cache yet at #{cache_path} — run rspec first"
           return nil
         end
 
-        run_id = JSON.parse(File.read(last_run_path, encoding: 'UTF-8'))['run_id']
-        run_dir = File.join(cache_path, run_id.to_s)
-        unless File.directory?(run_dir)
-          stderr.puts "explain: run_id #{run_id} directory missing at #{run_dir}"
+        snapshot = backend.load_graph(schema_version: Storage::Schema::CURRENT)
+        if snapshot.nil?
+          stderr.puts "explain: cache at #{cache_path} is incompatible with this rspec-tracer; next rspec run is cold"
           return nil
         end
 
-        run_dir
+        snapshot
       end
 
       # Internal helper for the tracer pipeline.
@@ -73,20 +75,13 @@ module RSpecTracer
 
           Show why an example is scheduled to run or skip. Matches against
           example_id exactly first, then falls back to a substring match
-          on the example's full_description. Requires a prior rspec run.
+          on the example's full_description. Backend-aware: works under
+          `storage_backend :json` (default) and `storage_backend :sqlite`.
+          Requires a prior rspec run.
         HELP
         0
       end
 
-      # Internal helper for the tracer pipeline.
-      # @api private
-      def self.read_json(path)
-        return {} unless File.file?(path)
-
-        parsed = JSON.parse(File.read(path, encoding: 'UTF-8'))
-        parsed.is_a?(Hash) ? parsed : {}
-      end
-
       # Internal helper for the tracer pipeline.
       # @api private
       def self.find_example(all_examples, query)
@@ -94,50 +89,65 @@ module RSpecTracer
 
         all_examples.find do |id, meta|
           meta = {} unless meta.is_a?(::Hash)
-          desc = meta['full_description'] || meta['description'] || ''
+          desc = fetch_meta(meta, 'full_description') || fetch_meta(meta, 'description') || ''
           id.include?(query) || desc.include?(query)
         end&.last
       end
 
       # Internal helper for the tracer pipeline.
       # @api private
-      def self.print_explanation(stdout, meta, run_dir)
+      def self.print_explanation(stdout, meta, snapshot)
         meta = {} unless meta.is_a?(::Hash)
         format_lines(meta).each { |line| stdout.puts line }
-        print_dependency_summary(stdout, meta, run_dir)
+        print_dependency_summary(stdout, meta, snapshot)
       end
 
       # Internal helper for the tracer pipeline.
       # @api private
       def self.format_lines(meta)
-        id = first_non_nil(meta, 'example_id', 'id') || '<unknown>'
-        file = first_non_nil(meta, 'rerun_file_name', 'file_name')
-        line = first_non_nil(meta, 'rerun_line_number', 'line_number')
-        status = meta.dig('execution_result', 'status') || meta['status'] || 'unknown'
+        id = fetch_meta(meta, 'example_id', 'id') || '<unknown>'
+        file = fetch_meta(meta, 'rerun_file_name', 'file_name')
+        line = fetch_meta(meta, 'rerun_line_number', 'line_number')
+        status = dig_meta(meta, 'execution_result', 'status') || fetch_meta(meta, 'status') || 'unknown'
         [
           "id:           #{id}",
-          "description:  #{first_non_nil(meta, 'full_description', 'description')}",
+          "description:  #{fetch_meta(meta, 'full_description', 'description')}",
           "location:     #{file}:#{line}",
           "last status:  #{status}",
-          "run reason:   #{meta['run_reason'] || '<not recorded>'}"
+          "run reason:   #{fetch_meta(meta, 'run_reason') || '<not recorded>'}"
         ]
       end
 
-      # Internal helper for the tracer pipeline.
-      # @api private
-      def self.first_non_nil(meta, *keys)
-        keys.each { |k| return meta[k] unless meta[k].nil? }
+      # Look up a key from a Hash, tolerating both String and Symbol
+      # storage. Snapshot Hashes round-tripped through JSON yield
+      # String keys; the post-#182 msgpack serializer preserves
+      # Symbol keys end-to-end, so callers can't assume either shape.
+      def self.fetch_meta(meta, *keys)
+        keys.each do |k|
+          v = meta[k]
+          return v unless v.nil?
+
+          sym_value = meta[k.to_sym]
+          return sym_value unless sym_value.nil?
+        end
         nil
       end
 
+      # Look up a nested key from a Hash, tolerating both String and
+      # Symbol storage at each level. See {.fetch_meta} for rationale.
+      def self.dig_meta(meta, *keys)
+        keys.reduce(meta) do |acc, k|
+          break nil if acc.nil? || !acc.is_a?(::Hash)
+
+          acc[k] || acc[k.to_sym]
+        end
+      end
+
       # Internal helper for the tracer pipeline.
       # @api private
-      def self.print_dependency_summary(stdout, meta, run_dir)
-        deps_path = File.join(run_dir, 'dependency.json')
-        return unless File.file?(deps_path)
-
-        deps = read_json(deps_path)
-        id = meta['example_id'] || meta['id']
+      def self.print_dependency_summary(stdout, meta, snapshot)
+        id = fetch_meta(meta, 'example_id', 'id')
+        deps = snapshot.dependency || {}
         files = Array(deps[id])
         stdout.puts "dependencies: #{files.size} files tracked"
         files.first(10).each { |f| stdout.puts "  - #{f}" }