backspin 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edf2daa2123a270ca28d593b594188db57913b2ca5905a45b6a9e0d1221c0da4
-  data.tar.gz: 3ec4407d3396e3e8390f62b3c0e7d2124bdf026e4b02e74c036ee37fab8430a4
+  metadata.gz: a9533baf54aa3ae09b9d483d41149a6ede985f3f974f038e287034928a0ab1e3
+  data.tar.gz: 75b9cb2018b1f1ca5878f6ce75af74bc9fc4822319ac2f12e8c654f30624f859
 SHA512:
-  metadata.gz: a851d194aa4f400c9104643b5521e7b5bd5e159708a0d6114c70cfd39907fb6174041a3bccffdc824edb3e224bab7db453b906c35adc7f0a2908d2b034a9b11a
-  data.tar.gz: 01b1c9b4288f978d9946090afda49e17001732ec0b4f5e47d3831767975d731e5c940cc0fbdd7ccfca4a2bdf54bc8d281eba7d3dc4cbbd137e3f4edb576d9378
+  metadata.gz: a8d851c2836d8cd0be15b341a7f2af332c356aaa9688766a5b51f65110539a2d500cac8238abd4bc0a668a689effbef45a8f009829a3cd28ff4acd249bb506b4
+  data.tar.gz: 0151e1de9a47285ca75552e97154b57100de50fe691100869144e1ed17e1b7c421a012599c4462a333f6abd0c4779f110a4fbffd2bbe60d14d600469da459bad

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.11.0 - 2026-02-11
+* Added immutable top-level `first_recorded_at` metadata for record files.
+* Added mutable top-level `recorded_at` metadata that updates on each successful re-record.
+* Added top-level `record_count`, incremented on each successful record write.
+* Record format now writes `format_version: 4.1`; loading remains backward-compatible with 4.0 record files.
+* Added acceptance coverage for v4.1 schema and 4.0-to-4.1 upgrade behavior.
+* Removed legacy committed `.yml` record fixtures from old schema versions.
+
 ## 0.10.0 - 2026-02-11
 * Added `filter_on` to `Backspin.run` and `Backspin.capture` (`:both` default, `:record` opt-out).
 * Changed default filter behavior: `filter` now applies during verify comparisons/diffs when `filter_on: :both`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    backspin (0.10.0)
+    backspin (0.11.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -91,6 +91,28 @@ result = Backspin.run(["echo", "hello"], name: "echo_test", mode: :verify)
 expect(result.verified?).to be true
 ```
 
+### Record Metadata
+
+Backspin writes records using `format_version: "4.1"` with top-level metadata:
+
+```yaml
+---
+format_version: "4.1"
+first_recorded_at: "2026-01-01T10:00:00Z" # immutable
+recorded_at: "2026-02-01T10:00:00Z"       # updates on each write
+record_count: 3                            # increments on each write
+snapshot:
+  command_type: "Open3::Capture3"
+  args: ["echo", "hello"]
+  stdout: "hello\n"
+  stderr: ""
+  status: 0
+  recorded_at: "2026-02-01T10:00:00Z"
+```
+
+When re-recording with `mode: :record`, Backspin preserves `first_recorded_at`, updates `recorded_at`, and increments `record_count`.
+Existing `4.0` records still load and are upgraded to `4.1` metadata on the next write.
+
 ### Environment Variables
 
 ```ruby

data/docs/backspin-result-api-sketch.md

@@ -141,14 +141,16 @@ result.expected.stdout
 - Error message is generated from `BackspinResult#error_message`.
 - Do not duplicate `diff` content in exception formatting.
 
-## Record Format Sketch (v4)
+## Record Format Sketch (v4.1)
 
 Single-snapshot format to match single-snapshot runtime model:
 
 ```yaml
 ---
-format_version: "4.0"
+format_version: "4.1"
+first_recorded_at: "2026-01-01T00:00:00Z"
 recorded_at: "2026-02-11T00:00:00Z"
+record_count: 3
 snapshot:
   command_type: "Open3::Capture3"
   args: ["echo", "hello"]
@@ -184,11 +186,11 @@ Status date: 2026-02-11
 
 1. `Snapshot` and `BackspinResult` classes are implemented and wired into runtime paths.
 2. `Backspin.run` and `Backspin.capture` now return `BackspinResult`.
-3. `Record` persistence moved to v4 single-snapshot format (`snapshot` key, no `commands` array).
+3. `Record` persistence moved to v4 single-snapshot format (`snapshot` key, no `commands` array), with v4.1 top-level metadata.
 4. `Matcher` and `CommandDiff` now operate on expected/actual snapshots.
 5. Legacy result/command layering was removed from `lib/`.
-6. Specs have been migrated to the new result contract and v4 format.
-7. Validation is green: `66 examples, 0 failures` and Standard lint passes.
+6. Specs have been migrated to the new result contract and v4.1 format.
+7. Validation is green: `89 examples, 0 failures` and Standard lint passes.
 8. Public docs now use `result.actual` / `result.expected` terminology.
 
 ## Success Criteria
@@ -198,7 +200,7 @@ Status date: 2026-02-11
 3. In `:verify` mode, `result.expected` is present, `result.verified?` is boolean, and mismatch cases populate `result.diff` plus `result.error_message`.
 4. No multi-command result API remains in the public result contract.
 5. Snapshot object exposes a stable single-command shape: `stdout`, `stderr`, `status`, `args`, `env`, `command_type`.
-6. Record format uses one snapshot (v4), not a commands array.
+6. Record format uses one snapshot (v4.x), not a commands array.
 7. Existing strict verification behavior remains: default raises `Backspin::VerificationError`, while `raise_on_verification_failure = false` returns a failed result without raising.
 8. End-to-end Unix command examples are covered in specs: `echo` record/verify, `ls -1` record/verify, `date` mismatch behavior (or matcher override), and captured `grep | wc` pipeline output via `Backspin.capture`.
 9. Matcher behavior is preserved: default matching remains stdout/stderr/status, and custom `matcher:` contract (Proc, hash fields, `:all`) continues to work for both run and capture verification.

data/fixtures/backspin/.gitkeep

@@ -0,0 +1 @@
+

data/lib/backspin/record.rb

@@ -4,8 +4,9 @@ module Backspin
   class RecordFormatError < StandardError; end
 
   class Record
-    FORMAT_VERSION = "4.0"
-    attr_reader :path, :snapshot, :recorded_at
+    FORMAT_VERSION = "4.1"
+    SUPPORTED_FORMAT_VERSIONS = ["4.0", FORMAT_VERSION].freeze
+    attr_reader :path, :snapshot, :first_recorded_at, :recorded_at, :record_count
 
     def self.load_or_create(path)
       record = new(path)
@@ -36,12 +37,16 @@ module Backspin
     def initialize(path)
       @path = path
       @snapshot = nil
+      @first_recorded_at = nil
       @recorded_at = nil
+      @record_count = nil
     end
 
     def set_snapshot(snapshot)
       @snapshot = snapshot
-      @recorded_at ||= snapshot.recorded_at
+      snapshot_recorded_at = snapshot.recorded_at || Time.now.iso8601
+      @first_recorded_at ||= snapshot_recorded_at
+      @recorded_at = snapshot_recorded_at
       self
     end
 
@@ -49,17 +54,23 @@ module Backspin
       FileUtils.mkdir_p(File.dirname(@path))
       snapshot_data = @snapshot&.to_h
       snapshot_data = filter.call(deep_dup(snapshot_data)) if snapshot_data && filter
+      next_record_count = (@record_count || 0) + 1
       record_data = {
         "format_version" => FORMAT_VERSION,
+        "first_recorded_at" => @first_recorded_at,
         "recorded_at" => @recorded_at,
+        "record_count" => next_record_count,
         "snapshot" => snapshot_data
       }
       File.write(@path, record_data.to_yaml)
+      @record_count = next_record_count
     end
 
     def reload
       @snapshot = nil
+      @first_recorded_at = nil
       @recorded_at = nil
+      @record_count = nil
       load_from_file if File.exist?(@path)
     end
 
@@ -73,13 +84,15 @@ module Backspin
 
     def clear
       @snapshot = nil
+      @first_recorded_at = nil
       @recorded_at = nil
+      @record_count = nil
     end
 
     def load_from_file
       data = YAML.load_file(@path.to_s)
 
-      unless data.is_a?(Hash) && data["format_version"] == FORMAT_VERSION
+      unless data.is_a?(Hash) && SUPPORTED_FORMAT_VERSIONS.include?(data["format_version"])
         raise RecordFormatError, "Invalid record format: expected format version #{FORMAT_VERSION}"
       end
 
@@ -88,7 +101,17 @@ module Backspin
         raise RecordFormatError, "Invalid record format: missing snapshot"
       end
 
-      @recorded_at = data["recorded_at"]
+      format_version = data["format_version"]
+      @recorded_at = data["recorded_at"] || snapshot_data["recorded_at"]
+      if format_version == FORMAT_VERSION
+        @first_recorded_at = data["first_recorded_at"]
+        @record_count = data["record_count"]
+      else
+        # Backfill metadata for v4.0 records.
+        @first_recorded_at = data["first_recorded_at"] || @recorded_at
+        @record_count = data.fetch("record_count", 1)
+      end
+      validate_metadata!
       @snapshot = Snapshot.from_h(snapshot_data)
     rescue Psych::SyntaxError => e
       raise RecordFormatError, "Invalid record format: #{e.message}"
@@ -96,6 +119,20 @@ module Backspin
 
     private
 
+    def validate_metadata!
+      unless @first_recorded_at.is_a?(String) && !@first_recorded_at.empty?
+        raise RecordFormatError, "Invalid record format: missing first_recorded_at"
+      end
+
+      unless @recorded_at.is_a?(String) && !@recorded_at.empty?
+        raise RecordFormatError, "Invalid record format: missing recorded_at"
+      end
+
+      unless @record_count.is_a?(Integer) && @record_count.positive?
+        raise RecordFormatError, "Invalid record format: record_count must be a positive integer"
+      end
+    end
+
     def deep_dup(value)
       case value
       when Hash

data/lib/backspin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Backspin
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

data/lib/backspin.rb

@@ -120,11 +120,7 @@ module Backspin
       mode = determine_mode(mode, record_path)
       validate_mode!(mode)
 
-      record = if mode == :record
-        Record.create(record_name)
-      else
-        Record.load_or_create(record_path)
-      end
+      record = Record.load_or_create(record_path)
 
       recorder = Recorder.new(record: record, mode: mode, matcher: matcher, filter: filter, filter_on: filter_on)
 
@@ -147,11 +143,7 @@ module Backspin
       mode = determine_mode(mode, record_path)
       validate_mode!(mode)
 
-      record = if mode == :record
-        Record.create(name)
-      else
-        Record.load_or_create(record_path)
-      end
+      record = Record.load_or_create(record_path)
 
       normalized_env = env.nil? ? nil : normalize_env(env)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Rob Sanheim
@@ -39,61 +39,7 @@ files:
 - bin/setup
 - docs/backspin-result-api-sketch.md
 - examples/match_on_example.rb
-- fixtures/backspin/all_and_fields.yml
-- fixtures/backspin/all_bypass_equality.yml
-- fixtures/backspin/all_checks_equality.yml
-- fixtures/backspin/all_for_logging.yml
-- fixtures/backspin/all_matcher_basic.yml
-- fixtures/backspin/all_matcher_custom.yml
-- fixtures/backspin/all_matcher_demo.yml
-- fixtures/backspin/all_matcher_test.yml
-- fixtures/backspin/all_mode_filter.yml
-- fixtures/backspin/all_no_short_circuit.yml
-- fixtures/backspin/all_pass_field_fail.yml
-- fixtures/backspin/all_short_circuit.yml
-- fixtures/backspin/all_skips_equality.yml
-- fixtures/backspin/all_with_equality.yml
-- fixtures/backspin/all_with_fields.yml
-- fixtures/backspin/combined_fail_demo.yml
-- fixtures/backspin/combined_matcher_demo.yml
-- fixtures/backspin/credential_filter.yml
-- fixtures/backspin/echo_hello.yml
-- fixtures/backspin/echo_verify.yml
-- fixtures/backspin/episodes_filter.yml
-- fixtures/backspin/failure_test.yml
-- fixtures/backspin/field_matcher_demo.yml
-- fixtures/backspin/field_matcher_values.yml
-- fixtures/backspin/full_data_filter.yml
-- fixtures/backspin/key_confusion_test.yml
-- fixtures/backspin/match_on_any_fail.yml
-- fixtures/backspin/match_on_bad_format.yml
-- fixtures/backspin/match_on_fail.yml
-- fixtures/backspin/match_on_invalid.yml
-- fixtures/backspin/match_on_multiple.yml
-- fixtures/backspin/match_on_nil.yml
-- fixtures/backspin/match_on_other_fields.yml
-- fixtures/backspin/match_on_run_bang.yml
-- fixtures/backspin/match_on_run_bang_fail.yml
-- fixtures/backspin/match_on_single.yml
-- fixtures/backspin/mixed_calls.yml
-- fixtures/backspin/multi_command.yml
-- fixtures/backspin/multi_command_filter.yml
-- fixtures/backspin/multi_field_filter.yml
-- fixtures/backspin/multi_system.yml
-- fixtures/backspin/nil_filter.yml
-- fixtures/backspin/none_mode_test.yml
-- fixtures/backspin/path_test.yml
-- fixtures/backspin/playback_system.yml
-- fixtures/backspin/playback_test.yml
-- fixtures/backspin/stderr_test.yml
-- fixtures/backspin/strict_test.yml
-- fixtures/backspin/string_symbol_test.yml
-- fixtures/backspin/system_echo.yml
-- fixtures/backspin/system_false.yml
-- fixtures/backspin/timestamp_test.yml
-- fixtures/backspin/verify_system.yml
-- fixtures/backspin/verify_system_diff.yml
-- fixtures/backspin/version_test.yml
+- fixtures/backspin/.gitkeep
 - lib/backspin.rb
 - lib/backspin/backspin_result.rb
 - lib/backspin/command_diff.rb

data/fixtures/backspin/all_and_fields.yml

@@ -1,15 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:27:40-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - echo 'valid'; exit 0
-  stdout: 'valid
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:27:40-05:00'

data/fixtures/backspin/all_bypass_equality.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:02:03-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - first output
-  stdout: 'first output
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:02:03-05:00'

data/fixtures/backspin/all_checks_equality.yml

@@ -1,17 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - echo 'original'; echo 'original error' >&2
-  stdout: 'original
-
-    '
-  stderr: 'original error
-
-    '
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_for_logging.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - 'test output with : colons'
-  stdout: 'test output with : colons
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_matcher_basic.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - hello world
-  stdout: 'hello world
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_matcher_custom.yml

@@ -1,17 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - 'echo ''PASS: test 1''; echo ''WARNING: minor issue'' >&2'
-  stdout: 'PASS: test 1
-
-    '
-  stderr: 'WARNING: minor issue
-
-    '
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_matcher_demo.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:02:02-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:02:02-05:00'

data/fixtures/backspin/all_matcher_test.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:00:57-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:00:57-05:00'

data/fixtures/backspin/all_mode_filter.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - "'second'"
-  stdout: 'filtered output 2
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_no_short_circuit.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:27:40-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:27:40-05:00'

data/fixtures/backspin/all_pass_field_fail.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - hello
-  stdout: 'hello
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_short_circuit.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_skips_equality.yml

@@ -1,17 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - echo 'original'; echo 'original error' >&2
-  stdout: 'original
-
-    '
-  stderr: 'original error
-
-    '
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_with_equality.yml

@@ -1,17 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:27:40-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - echo 'output1'; echo 'error1' >&2
-  stdout: 'output1
-
-    '
-  stderr: 'error1
-
-    '
-  status: 0
-  recorded_at: '2025-06-10T11:27:40-05:00'

data/fixtures/backspin/all_with_fields.yml

@@ -1,17 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - echo 'output'; echo 'error' >&2
-  stdout: 'output
-
-    '
-  stderr: 'error
-
-    '
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/combined_fail_demo.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:02:03-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:02:03-05:00'

data/fixtures/backspin/combined_matcher_demo.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:02:03-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:02:03-05:00'

data/fixtures/backspin/credential_filter.yml

@@ -1,18 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - "'My"
-  - API
-  - key
-  - is
-  - "********************'"
-  stdout: 'MY API KEY IS ********************
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/echo_hello.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - hello
-  stdout: 'hello
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/echo_verify.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - hello
-  stdout: 'hello
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'