jobpayload 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6a279c0d7d4f97b7ba76677146e0d73ebd7b65df8db221b93b61a6e69e1d30a
-  data.tar.gz: 4dc6bc66b1296cf30bf03e1ebad5d68797868f6cfc84117edc9246b555a63881
+  metadata.gz: 4412fc4ef1f876b11092e07462d6a46a998c3c063a8b7576ff33dd871a53cf63
+  data.tar.gz: 514ada469e5d6ea61b44315f03b0e2bb946204b2c072bb58681adb3af24213e9
 SHA512:
-  metadata.gz: e7b0ffe7184e08ca69623c383dd9ebb4f323408ea7a343d3a31accb0c310009c672e00af66411e78583d66545780c326956f098ce70ce86315fef4f1b3f9d10e
-  data.tar.gz: 2dba7bc4c7dbb0786367ae438d94accedf7312f99f9c3733dfc7a3845f2fcf6153e72d260edcfca8fb486fb62f15327fe2008a44bfa9a3f6fe5c50fdf726e093
+  metadata.gz: 0134ac75049008ed572e7d73c1b978441642dce567e945d44071f81ab3decab7be51f33631caf37953fef7839e88c5cb1215e7bcc96589f6d708f049f76fa650
+  data.tar.gz: ccd929aba8e3dd698580fb00f6a643b02fcc7b551c8e4f65be6686569e6bb47e93657b40fedc019fde90ffeea48f746b1c7679d3f024a6a5076ba5f0e9063ea6

data/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to this project are documented in this file.
 
+## 0.2.0
+
+0.2.0 adds snapshot drift detection. Everything 0.1.0 does is unchanged:
+`snapshot`, `snapshot --update` and `check` behave as before, and the fixture
+schema (`jobpayload_schema: 1`), the JSON output schema (`schema_version: 1`),
+finding codes and exit codes are the same. There are no breaking changes.
+
+### Added
+
+- `jobpayload snapshot --check`: serializes every snapshot case with the
+  current code and compares it with the baseline fixture already stored in
+  `--output`, to catch unintended changes to the payloads new code enqueues.
+  - **Read-only:** nothing in `--output` is written, created, renamed or
+    deleted, not even a missing `--output` directory. Cannot be combined with
+    `--update`.
+  - **Comparison:** the whole `job` object, as canonical JSON. The current
+    payload is normalized as `snapshot` writes it; the stored baseline is
+    compared as stored (never re-normalized), so any edit to it, volatile
+    metadata included, is reported. `source` metadata, key order, whitespace
+    and equivalent JSON spellings are ignored; value types (`1` vs `1.0`) and
+    array order are not.
+  - **Statuses and exit codes:** `identical` (0), `different` (1), `missing`
+    (1) and `invalid` (2); the highest exit status wins (2 > 1 > 0). A
+    baseline is `invalid` when it is not valid schema v1 JSON, is a symbolic
+    link (never followed), is not a regular file, cannot be read, or holds a
+    `job` that `snapshot` could never have written. Fixtures with no matching
+    case are ignored.
+  - **Output:** deterministic text, or JSON (`schema_version: 1`,
+    `"mode": "check"`). It reports whether each baseline differs, not where
+    (no field-level diff).
+
+### Security
+
+- `snapshot --check` reads baselines in a way that resists the fixture's
+  directory entry being replaced during the check: after `lstat`, the file
+  is opened read-only with `O_NOFOLLOW` and `O_NONBLOCK`, verified with
+  `fstat` to be the same regular file (device and inode), and read only from
+  that descriptor. An entry swapped for a symlink, FIFO, directory or another
+  file, or removed, is `invalid` (exit 2) and never read, so it cannot leak
+  file contents into the output, block the check, or make it pass. Platforms
+  without these flags fail closed. This protects the final path component
+  only; see README "Race-safe baseline reading" for what is not covered.
+  The hardening was made before `snapshot --check` was released, so no
+  released version is affected. `jobpayload check` is unchanged (it reads by
+  path and follows symbolic links, as in 0.1.0).
+
+### Changed
+
+- Internal: `JobPayload::Fixture.parse_content` parses fixture bytes the
+  caller has already read; `Fixture.parse` keeps its behaviour and shares the
+  same validation.
+- Tests and CI (no runtime change): tests for `snapshot --check` and its
+  race-safe reads (deterministic lstat/open races, FIFO deadlines, descriptor
+  leaks, real-process runs); a macOS smoke job; capability-based skips for
+  file names that are not valid UTF-8; and a separate Rails `main` GlobalID
+  regression workflow (not a supported version).
+- README: documents `snapshot --check`, its security boundaries and the
+  updated version references.
+
 ## 0.1.0
 
 Initial release. The single question v0.1.0 answers is: *can the current

data/README.md

@@ -16,6 +16,7 @@ application can still be deserialized by the **new** version.
 - [Quick start](#quick-start)
 - [Creating snapshot cases](#creating-snapshot-cases)
 - [Generating baseline fixtures](#generating-baseline-fixtures)
+  - [Detecting snapshot drift (`snapshot --check`)](#detecting-snapshot-drift-snapshot---check)
 - [Checking old fixtures on new code](#checking-old-fixtures-on-new-code)
 - [Two-way rolling-deploy checking](#two-way-rolling-deploy-checking)
 - [GlobalID / inconclusive semantics](#globalid--inconclusive-semantics)
@@ -28,6 +29,7 @@ application can still be deserialized by the **new** version.
 - [Non-goals](#non-goals)
 - [Known limitations](#known-limitations)
 - [Security / safety notes](#security--safety-notes)
+  - [Race-safe baseline reading (`snapshot --check`)](#race-safe-baseline-reading-snapshot---check)
 
 ## What jobpayload checks
 
@@ -47,7 +49,10 @@ A baseline fixture is compatible with the current application when:
    subclasses, nested arrays/hashes and GlobalID lookups, in your real
    (test) environment.
 
-v0.1.0 checks **backward-read compatibility only**: old payload → new code.
+`check` checks **backward-read compatibility only**: old payload → new code.
+Since v0.2.0, `snapshot --check` can also detect *drift*: whether the current
+code still serializes each snapshot case exactly as its stored baseline
+(see [Detecting snapshot drift](#detecting-snapshot-drift-snapshot---check)).
 
 ## Why queued payload compatibility matters
 
@@ -150,6 +155,7 @@ bundle exec jobpayload snapshot [options]
 | `--boot PATH` | `config/environment.rb` | File required to boot the app |
 | `--environment NAME` | `test` | Value assigned to `RAILS_ENV` before booting |
 | `--update` | off | Replace existing fixtures whose content changed |
+| `--check` | off | Compare with existing fixtures without writing (see [Detecting snapshot drift](#detecting-snapshot-drift-snapshot---check)) |
 | `--format text\|json` | `text` | Output format |
 
 Behaviour:
@@ -193,7 +199,7 @@ One JSON file per fixture, schema v1:
   "name": "billing-money-v1",
   "source": {
     "active_job_version": "8.1.4",
-    "jobpayload_version": "0.1.0",
+    "jobpayload_version": "0.2.0",
     "rails_version": "8.1.4",
     "ruby_version": "3.4.8"
   }
@@ -213,6 +219,93 @@ One JSON file per fixture, schema v1:
   two-space layout (independent of the json gem version), UTF-8, LF line endings,
   a final newline, written atomically (temp file + rename).
 
+### Detecting snapshot drift (`snapshot --check`)
+
+```sh
+bundle exec jobpayload snapshot --check [options]
+```
+
+`--check` serializes every snapshot case with the current code, exactly as
+`snapshot` would, and compares the result with the fixture already stored in
+`--output`. It answers "did the payload this code writes change?", so an
+unintended change to what new code enqueues fails CI before it ships. It is
+**read-only for the fixtures**: nothing in `--output` is written, replaced,
+created or deleted, not even a missing `--output` directory. (Like `snapshot`,
+it still boots your application and runs your cases file, which may write to
+the test database.) `--check` and `--update` cannot be combined.
+
+Only the `job` object is compared, and every key in it counts. The current
+payload is normalized exactly as `snapshot` writes it (fixed `job_id`,
+`enqueued_at` and so on); the stored `job` is compared as stored, so any edit
+to a fixture's `job`, volatile metadata included, is reported as `different`.
+`source` metadata, key order, whitespace and equivalent JSON spellings
+(`"\u00e9"` and `"é"`, `1.0e2` and `100.0`) are ignored. Value types and array
+order are kept: `1` and `1.0`, or `null` and a missing key, are different
+payloads.
+
+| Status | Meaning | Exit |
+| --- | --- | --- |
+| `identical` | The stored `job` matches what the current code serializes | 0 |
+| `different` | The payload the current code writes differs from the stored `job` | 1 |
+| `missing` | No fixture file for the case | 1 |
+| `invalid` | The fixture cannot be used: invalid JSON or UTF-8, wrong schema, name mismatch, a symbolic link (never followed, even when it points to a valid fixture), not a regular file (such as a directory or FIFO), replaced or removed while it is being checked, unreadable or inaccessible (for example an unsearchable directory), or a `job` that `snapshot` could never have written (a non-finite number such as `1e400`, or nesting deeper than `snapshot`'s limit of 100) | 2 |
+
+The exit status is the highest that applies (`2` > `1` > `0`). Case errors,
+boot errors and usage errors exit 2 as for `snapshot`. Fixtures with no
+matching case are ignored. A `--output` directory that does not exist is not an
+error: every case is reported `missing` (exit 1), so check the path if
+everything is missing. Only the fixture file entry itself must not be a symbolic
+link; `--output` may be one. Baselines are read in a way that
+resists the file being swapped during the check; see
+[Race-safe baseline reading](#race-safe-baseline-reading-snapshot---check).
+
+Text output has one line per case, in name order, and a summary. The status
+says whether a fixture differs, not where; compare the files (for example
+with `git diff` after `snapshot --update`) to see the change:
+
+```text
+identical billing-legacy-money-v1  test/jobpayload_fixtures/billing-legacy-money-v1.json
+different billing-money-v1  test/jobpayload_fixtures/billing-money-v1.json
+missing   scheduled-v1  test/jobpayload_fixtures/scheduled-v1.json
+
+3 fixtures: 1 identical, 1 different, 1 missing, 0 invalid
+```
+
+With `--format json` the document (schema v1) is:
+
+```json
+{
+  "schema_version": 1,
+  "tool_version": "0.2.0",
+  "mode": "check",
+  "status": "fail",
+  "summary": {
+    "fixtures": 1,
+    "identical": 0,
+    "different": 1,
+    "missing": 0,
+    "invalid": 0
+  },
+  "fixtures": [
+    {
+      "name": "billing-money-v1",
+      "path": "test/jobpayload_fixtures/billing-money-v1.json",
+      "status": "different",
+      "reason": null
+    }
+  ]
+}
+```
+
+`status` is `pass`, `fail` or `tool_error` for exit 0, 1 and 2. `reason` is
+set only for `invalid`.
+Text and JSON output are deterministic for the same input.
+
+A `different` result is not a compatibility failure by itself: it means the
+new code writes a different payload than the fixture records. Add a new case
+for the new format (keeping the old fixture for `check`), or re-run
+`snapshot --update` if the fixture was meant to follow the code.
+
 ## Checking old fixtures on new code
 
 ```sh
@@ -310,7 +403,8 @@ database (seeds, fixtures, or a boot file) to get a conclusive answer.
 
 ## Finding codes
 
-Finding codes are a stable API for 0.1.x.
+Finding codes are a stable API: 0.2.0 keeps every 0.1.0 code and its meaning
+unchanged.
 
 | Code | Name | Kind | Meaning |
 | --- | --- | --- | --- |
@@ -331,6 +425,10 @@ Finding codes are a stable API for 0.1.x.
 
 When several apply, the highest priority wins: `2` > `1` > `0`.
 
+These are the exit statuses of `check`. `snapshot --check` uses the same
+`2` > `1` > `0` precedence with its own meanings; see
+[Detecting snapshot drift](#detecting-snapshot-drift-snapshot---check).
+
 Results are written to **stdout**. Usage, configuration and boot errors are
 written to **stderr** (and nothing is written to stdout in that case).
 jobpayload itself writes nothing else to stdout. While booting and
@@ -401,6 +499,9 @@ A summary line `N tool error(s)` is added when fixtures had fatal findings.
 
 ## JSON output
 
+This section describes `check --format json`. The `snapshot --check` document
+is described in [Detecting snapshot drift](#detecting-snapshot-drift-snapshot---check).
+
 ```sh
 bundle exec jobpayload check --format json
 ```
@@ -408,7 +509,7 @@ bundle exec jobpayload check --format json
 ```json
 {
   "schema_version": 1,
-  "tool_version": "0.1.0",
+  "tool_version": "0.2.0",
   "status": "fail",
   "summary": {
     "fixtures": 3,
@@ -467,7 +568,7 @@ bundle exec jobpayload check --format json
 
 | Field | Meaning |
 | --- | --- |
-| `schema_version` | JSON output schema version. Always `1` in 0.1.x. |
+| `schema_version` | JSON output schema version. Always `1` in 0.1.x and 0.2.0. |
 | `tool_version` | jobpayload version. |
 | `status` | `"pass"` (exit 0), `"fail"` (exit 1) or `"tool_error"` (exit 2). With `--fail-on-inconclusive`, inconclusive fixtures make it `"fail"`. |
 | `summary.fixtures` | Number of fixture files checked. |
@@ -487,7 +588,7 @@ Backtraces are never included in JSON output. The same input always produces
 byte-identical JSON. Exception messages, fixture file names and paths are
 emitted as valid UTF-8 (invalid bytes become U+FFFD).
 
-**Stability policy.** Within `schema_version: 1` (all 0.1.x releases),
+**Stability policy.** Within `schema_version: 1` (0.1.x and 0.2.0),
 existing fields are never removed or renamed, and the meaning and allowed
 values of existing fields do not change. New fields may be added, so consumers
 should ignore fields they do not know. Any incompatible change bumps
@@ -514,13 +615,15 @@ jobs:
           bundler-cache: true
       - run: bin/rails db:prepare
       - run: bundle exec jobpayload check
+      # Optional: fail when the code changes the payloads it writes.
+      - run: bundle exec jobpayload snapshot --check
 ```
 
 For two-way checking, check out both the base and the head revision (for
 example two `actions/checkout` steps with different `path:` and `ref:`), then
 run `check` twice: base fixtures → head app, and head fixtures → base app, as
 shown in [Two-way rolling-deploy checking](#two-way-rolling-deploy-checking).
-jobpayload 0.1.0 does not orchestrate checkouts itself.
+jobpayload does not orchestrate checkouts itself.
 
 ## Supported Ruby / Active Job versions
 
@@ -543,7 +646,7 @@ built-in fixture set.
 
 ## Non-goals
 
-v0.1.0 deliberately does **not**:
+jobpayload deliberately does **not**:
 
 - execute `perform` or any job business logic, enqueue, or retry jobs
 - check `perform` arity or execution semantics. A successful deserialize does
@@ -558,6 +661,8 @@ v0.1.0 deliberately does **not**:
 - orchestrate forward/two-way compatibility automatically
 - re-serialize deserialized arguments (round-trip / re-enqueue compatibility)
 - provide ignore/suppression lists or a configuration file
+- show field-level (structural) diffs: `snapshot --check` reports only
+  whether a baseline differs, not where
 
 ## Known limitations
 
@@ -567,6 +672,8 @@ v0.1.0 deliberately does **not**:
   never writes more than 100). Such a fixture is reported as `AJP900` with a
   `SystemStackError` cause, or the check stops with an internal error; either
   way the exit status is 2, never 0 or 1.
+  `snapshot --check` reports a baseline nested deeper than 100 levels as
+  `invalid` (exit 2).
 - **GlobalIDs inside custom serializer payloads.** Only a top-level or
   plain-array/hash GlobalID argument can be inconclusive. If a custom
   serializer's own payload contains a GlobalID whose record is missing, the
@@ -578,6 +685,13 @@ v0.1.0 deliberately does **not**:
   [Exit codes](#exit-codes) and can corrupt `--format json` output.
 - **Semantic changes** that still deserialize successfully pass (see
   [Non-goals](#non-goals)).
+- **File names that are not valid UTF-8.** jobpayload passes the exact bytes
+  it is given for `--output`, `--fixtures`, `--cases` and `--boot` to the file
+  system, and only replaces invalid bytes with U+FFFD in text and JSON output.
+  Whether such a name can exist at all depends on the file system: most Linux
+  file systems accept any bytes, while macOS (APFS) rejects names that are
+  not valid UTF-8, so jobpayload cannot create them there. Ordinary UTF-8
+  paths work on every platform.
 - **Database errors during GlobalID lookup** (`ActiveRecord::StatementInvalid`,
   for example a column or table that the current schema no longer has) are
   reported as `AJP900` with exit 2, not as `AJP201`. The run still fails.
@@ -601,12 +715,55 @@ v0.1.0 deliberately does **not**:
   at production databases. Note that a `DATABASE_URL` set in your shell is
   still used by Rails in the `test` environment.
 
+### Race-safe baseline reading (`snapshot --check`)
+
+`snapshot --check` reads each baseline so that the fixture's directory entry
+cannot be swapped between the type check and the read:
+
+1. `lstat` the fixture path. A symbolic link, directory, FIFO or anything else
+   that is not a regular file is `invalid`; nothing is opened.
+2. Open it read-only with `O_NOFOLLOW` (a symbolic link put in its place is
+   refused instead of followed) and `O_NONBLOCK` (a FIFO put in its place
+   cannot block the open waiting for a writer). The open never creates or
+   truncates anything.
+3. `fstat` the open descriptor. It must be a regular file with the same device
+   and inode numbers `lstat` reported, so a different file renamed into place
+   is detected. Only then is anything read.
+4. Read the bytes from that same descriptor (the path is never opened again)
+   and parse them.
+
+An entry that is replaced, turned into a symlink, FIFO or directory, or removed
+between steps 1 and 2 is reported as `invalid` (exit 2), with a reason such as
+`replaced by a different file after it was checked`; its contents are never
+read, so they cannot leak into the output or make the check pass. If the
+platform lacks `O_NOFOLLOW` or `O_NONBLOCK`, every baseline is `invalid`
+rather than read without them.
+
+What this does **not** guarantee:
+
+- Only the final path component is protected. Parent directories, including a
+  symlinked `--output` directory (which is allowed), are resolved normally and
+  are trusted; replacing a parent directory is not detected.
+- The device/inode check pins the file that was opened, not its contents: a
+  process that rewrites that same file while it is read is not detected.
+- A hard link is a regular file and is read like any other.
+- Something swapped in after `lstat` is opened before `fstat` can reject it.
+  Opening is non-blocking and never makes a terminal the controlling one, but
+  opening some device nodes can still have side effects of its own.
+- Inode reuse, network file systems and unusual file systems may weaken these
+  checks; they are not a complete guarantee on every file system.
+- It does not make untrusted code safe: your application and cases file still
+  run as described above.
+
+`jobpayload check` is unchanged: it still reads its fixtures by path and
+follows symbolic links, as in 0.1.0.
+
 ## Development
 
 ```sh
 bundle install
 bundle exec rake test     # Minitest; randomized order
-bundle exec rake build    # pkg/jobpayload-0.1.0.gem
+bundle exec rake build    # pkg/jobpayload-0.2.0.gem
 
 # Another Active Job version:
 BUNDLE_GEMFILE=gemfiles/activejob_7.2.gemfile bundle install
@@ -617,6 +774,28 @@ The test suite boots small Rails-free applications from `test/apps` (Active
 Job + Active Record on in-memory SQLite) in subprocesses: `v1` writes baseline
 fixtures, `v2_compatible` and `v2_breaking` model later versions of the same app.
 
+Tests that need file names which are not valid UTF-8 probe the file system
+of their own temporary directory and are skipped, with the reason, only when
+it rejects such names (as on macOS).
+
+CI runs:
+
+- **Linux matrix** (`.github/workflows/ci.yml`): the full suite for every
+  supported Ruby / Active Job combination above.
+- **macOS smoke test** (same workflow): the full suite on Ruby 3.4 / Active
+  Job 8.1.
+- **Rails edge** (`.github/workflows/rails-edge.yml`, on pull requests,
+  weekly and on demand): GlobalID classification regression tests
+  (`test/edge`) against Rails `main` (`gemfiles/rails_edge.gemfile`), as a
+  separate workflow and check. This is an early warning about upstream
+  changes, not a supported version; its result is independent of the matrix
+  above, and a failure is reported as a failure.
+
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_edge.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_edge.gemfile bundle exec rake test:rails_edge
+```
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

data/lib/jobpayload/cli.rb

@@ -98,10 +98,13 @@ module JobPayload
         opts.on("--output DIR", "Fixture output directory (default: #{DEFAULT_FIXTURES})") { |v| options[:output] = v }
         boot_options(opts, options)
         opts.on("--update", "Replace existing fixtures whose content changed") { options[:update] = true }
+        opts.on("--check", "Compare with existing fixtures without writing (exit 1 on drift)") { options[:check] = true }
         format_option(opts, options)
       end
       return EXIT_SUCCESS if parse(parser)
 
+      raise UsageError, "--check and --update cannot be used together" if options[:check] && options[:update]
+
       formatter_name = options[:format]
       raise ConfigurationError, "cases file not found: #{options[:cases]}" unless File.file?(options[:cases])
       if File.exist?(options[:output]) && !File.directory?(options[:output])
@@ -110,11 +113,20 @@ module JobPayload
 
       boot(options)
       registry = CaseRegistry.load(options[:cases])
+      return snapshot_check(registry, options[:output], formatter_name) if options[:check]
+
       entries = Snapshotter.new(registry: registry, output_dir: options[:output], update: options[:update]).call
       @stdout.print(formatter_name == "json" ? snapshot_json(entries) : snapshot_text(entries))
       EXIT_SUCCESS
     end
 
+    # `snapshot --check`: read-only drift detection against existing fixtures.
+    def snapshot_check(registry, fixtures_dir, formatter_name)
+      entries = SnapshotChecker.new(registry: registry, fixtures_dir: fixtures_dir).call
+      @stdout.print(formatter_name == "json" ? snapshot_check_json(entries) : snapshot_check_text(entries))
+      SnapshotChecker.exit_code(entries)
+    end
+
     def check
       options = {
         fixtures: DEFAULT_FIXTURES, boot: Boot::DEFAULT_PATH, environment: Boot::DEFAULT_ENVIRONMENT,
@@ -200,6 +212,34 @@ module JobPayload
       Canonical.pretty(document)
     end
 
+    def snapshot_check_text(entries)
+      lines = entries.map do |entry|
+        line = format("%-9s %s  %s", entry.status, entry.name, JobPayload.scrub_utf8(entry.path))
+        entry.reason ? "#{line}  (#{JobPayload.scrub_utf8(entry.reason)})" : line
+      end
+      counts = entries.map(&:status).tally
+      summary = SnapshotChecker::STATUSES.map { |status| "#{counts.fetch(status, 0)} #{status}" }.join(", ")
+      "#{lines.join("\n")}\n\n#{entries.size} fixtures: #{summary}\n"
+    end
+
+    def snapshot_check_json(entries)
+      counts = entries.map(&:status).tally
+      document = {
+        "schema_version" => 1,
+        "tool_version" => VERSION,
+        "mode" => "check",
+        "status" => SnapshotChecker.status(entries),
+        "summary" => { "fixtures" => entries.size }.merge(SnapshotChecker::STATUSES.to_h { |s| [s.to_s, counts.fetch(s, 0)] }),
+        "fixtures" => entries.map do |e|
+          {
+            "name" => e.name, "path" => JobPayload.scrub_utf8(e.path), "status" => e.status.to_s,
+            "reason" => e.reason && JobPayload.scrub_utf8(e.reason)
+          }
+        end
+      }
+      Canonical.pretty(document)
+    end
+
     def usage_error(message)
       @stderr.puts("jobpayload: #{message}")
       @stderr.puts("Run `jobpayload --help` for usage.")

data/lib/jobpayload/finding.rb

@@ -3,7 +3,7 @@
 module JobPayload
   # One problem found while checking a fixture.
   #
-  # Finding codes are a stable API: their meaning does not change within 0.1.x.
+  # Finding codes are a stable API: 0.2.0 keeps every 0.1.0 code and meaning.
   Finding = Struct.new(
     :code,
     :fixture,

data/lib/jobpayload/fixture.rb

@@ -24,9 +24,24 @@ module JobPayload
     end
 
     def self.parse(path)
+      build(path) { File.binread(path) }
+    end
+
+    # Like parse, for bytes the caller has already read from +path+ (for
+    # example through SecureFixtureReader); +path+ only names the fixture.
+    def self.parse_content(path, content)
+      build(path) { content }
+    end
+
+    def self.build(path)
       basename = File.basename(path, ".json")
       reason = catch(:invalid) do
-        data = parse_json(path)
+        content = begin
+          yield
+        rescue SystemCallError => e
+          invalid!("cannot read file: #{e.message}")
+        end
+        data = parse_json(content)
         validate!(data, basename)
         return new(name: data["name"], path: path, job: data["job"], source: data["source"])
       end
@@ -35,8 +50,8 @@ module JobPayload
       Invalid.new(JobPayload.scrub_utf8(basename), path, JobPayload.scrub_utf8(reason))
     end
 
-    def self.parse_json(path)
-      content = File.binread(path).force_encoding(Encoding::UTF_8)
+    def self.parse_json(content)
+      content = content.dup.force_encoding(Encoding::UTF_8)
       invalid!("file is not valid UTF-8") unless content.valid_encoding?
       data = JSON.parse(content, max_nesting: false)
       # Some json versions decode a lone surrogate escape ("\udc80") into
@@ -45,8 +60,6 @@ module JobPayload
       data
     rescue JSON::ParserError => e
       invalid!("invalid JSON: #{e.message.lines.first.to_s.strip}")
-    rescue SystemCallError => e
-      invalid!("cannot read file: #{e.message}")
     end
 
     # Iterative, so that deeply nested fixtures cannot exhaust the stack here.
@@ -89,6 +102,6 @@ module JobPayload
     def self.invalid!(reason)
       throw :invalid, reason
     end
-    private_class_method :parse_json, :valid_strings?, :validate!, :invalid!
+    private_class_method :build, :parse_json, :valid_strings?, :validate!, :invalid!
   end
 end

data/lib/jobpayload/formatter/json.rb

@@ -5,7 +5,7 @@ require "json"
 module JobPayload
   module Formatter
     # Machine-readable output, schema v1. Field names and meanings are stable
-    # for 0.1.x; see README "JSON output".
+    # within schema_version 1; see README "JSON output".
     module JSON
       SCHEMA_VERSION = 1
 

data/lib/jobpayload/secure_fixture_reader.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module JobPayload
+  # Reads a baseline fixture for `snapshot --check` without trusting the path
+  # to still name the entry that was checked with lstat.
+  #
+  # The file is opened read-only with O_NOFOLLOW (a final-component symlink is
+  # refused, not followed) and O_NONBLOCK (opening a FIFO never waits for a
+  # writer). The open descriptor is then checked with fstat: it must be a
+  # regular file with the device and inode lstat reported. Only then is
+  # anything read, and only from that descriptor; the path is never reopened.
+  #
+  # This defends against the fixture's directory entry being replaced between
+  # lstat and open. It does not pin parent directories, and it cannot stop a
+  # process from rewriting the verified file's contents while it is read.
+  module SecureFixtureReader
+    # content is set on success, reason otherwise.
+    Result = Struct.new(:content, :reason)
+
+    UNSUPPORTED = "cannot open file safely: this platform lacks O_NOFOLLOW or O_NONBLOCK"
+
+    module_function
+
+    # +expected+ is the File::Stat from File.lstat(path), already known to be
+    # a regular file.
+    def read(path, expected)
+      flags = open_flags
+      return Result.new(nil, UNSUPPORTED) unless flags
+
+      io = begin
+        File.new(path, flags, binmode: true)
+      rescue Errno::ENOENT
+        return Result.new(nil, "file disappeared after it was checked")
+      rescue *symlink_errors
+        return Result.new(nil, "replaced by a symbolic link after it was checked (not followed)")
+      rescue SystemCallError => e
+        return Result.new(nil, "cannot read file: #{e.message}")
+      end
+
+      begin
+        actual = io.stat
+        return Result.new(nil, "replaced by something that is not a regular file after it was checked") unless actual.file?
+        unless actual.dev == expected.dev && actual.ino == expected.ino
+          return Result.new(nil, "replaced by a different file after it was checked")
+        end
+
+        Result.new(read_verified(io), nil)
+      rescue SystemCallError, IOError => e
+        Result.new(nil, "cannot read file: #{e.message}")
+      ensure
+        io.close
+      end
+    end
+
+    # Read-only, no-follow, non-blocking; never creates or truncates. nil when
+    # the platform cannot provide that (Ruby defines missing flags as 0), so
+    # the caller fails closed instead of falling back to a plain read.
+    def open_flags(constants = File::Constants)
+      nofollow = constants.const_defined?(:NOFOLLOW) ? constants::NOFOLLOW : 0
+      nonblock = constants.const_defined?(:NONBLOCK) ? constants::NONBLOCK : 0
+      return nil if nofollow.zero? || nonblock.zero?
+
+      flags = constants::RDONLY | nofollow | nonblock
+      # Never become the controlling terminal if the entry was swapped for one.
+      flags |= constants::NOCTTY if constants.const_defined?(:NOCTTY)
+      flags
+    end
+
+    # Errors open(2) reports for a final-component symlink under O_NOFOLLOW:
+    # ELOOP on Linux and macOS, EMLINK on FreeBSD, EFTYPE on NetBSD.
+    def symlink_errors
+      %i[ELOOP EMLINK EFTYPE].filter_map { |name| Errno.const_get(name) if Errno.const_defined?(name) }
+    end
+
+    # Only ever called on a descriptor that passed the checks above.
+    def read_verified(io)
+      io.read
+    end
+  end
+end

data/lib/jobpayload/snapshot_checker.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JobPayload
+  # Compares what the current application serializes for each snapshot case
+  # with the fixture already stored for it (`jobpayload snapshot --check`).
+  #
+  # Read-only: never writes, renames or creates anything. Only the `job`
+  # objects are compared, and every key in them counts. The current job is
+  # normalized exactly as `snapshot` writes it; the stored job is taken as
+  # is, so an edited baseline (including its volatile metadata) is never
+  # masked. Both are compared as canonical JSON: `source` metadata, key order
+  # and layout are ignored, while value types (1 and 1.0 differ, because
+  # Active Job reads them differently) and array order are kept.
+  class SnapshotChecker
+    # status: :identical, :different, :missing or :invalid; reason is set for
+    # :invalid only.
+    Entry = Struct.new(:name, :path, :status, :reason)
+
+    STATUSES = %i[identical different missing invalid].freeze
+
+    # Overall status => exit status.
+    EXIT_CODES = { "pass" => 0, "fail" => 1, "tool_error" => 2 }.freeze
+
+    def initialize(registry:, fixtures_dir:)
+      @registry = registry
+      @fixtures_dir = fixtures_dir
+    end
+
+    # Evaluates every case first (a failing case raises before anything is
+    # compared), then checks the fixtures in name order.
+    def call
+      snapshotter = Snapshotter.new(registry: @registry, output_dir: @fixtures_dir)
+      current = @registry.cases.map { |kase| [kase.name, snapshotter.build_document(kase)["job"]] }
+      current.map { |name, job| compare(name, job) }
+    end
+
+    # "tool_error" when any baseline is invalid, else "fail" when any differs
+    # or is missing, else "pass".
+    def self.status(entries)
+      statuses = entries.map(&:status)
+      return "tool_error" if statuses.include?(:invalid)
+      return "fail" if statuses.intersect?(%i[different missing])
+
+      "pass"
+    end
+
+    # 2 > 1 > 0, from status.
+    def self.exit_code(entries)
+      EXIT_CODES.fetch(status(entries))
+    end
+
+    # Canonical JSON for a stored job, without normalizing it. Raises
+    # ::JSON::JSONError when the job is not something `snapshot` could have
+    # written: a non-finite number (1e400 parses to Infinity) or nesting
+    # deeper than snapshot's limit of 100.
+    def self.canonical_baseline(job)
+      ::JSON.generate(job)
+      Canonical.generate(job)
+    end
+
+    private
+
+    # +current_job+ is already normalized (Snapshotter#build_document).
+    def compare(name, current_job)
+      path = File.join(@fixtures_dir, "#{name}.json")
+      stat = begin
+        File.lstat(path)
+      rescue Errno::ENOENT
+        return Entry.new(name, path, :missing, nil)
+      rescue SystemCallError => e
+        # For example an unsearchable fixture directory: not "never generated".
+        return invalid(name, path, "cannot access file: #{e.message}")
+      end
+      # From lstat, so a symlink is never followed, whatever it points to.
+      return invalid(name, path, "symbolic link (not followed)") if stat.symlink?
+      return invalid(name, path, "not a regular file") unless stat.file?
+
+      # Opened without following symlinks or blocking, and read only after the
+      # open file is confirmed to be the one lstat saw.
+      read = SecureFixtureReader.read(path, stat)
+      return invalid(name, path, read.reason) if read.reason
+
+      fixture = begin
+        Fixture.parse_content(path, read.content)
+      rescue SystemStackError => e
+        # Some json versions parse recursively; nesting deep enough to
+        # exhaust the stack must not abort the other fixtures.
+        return invalid(name, path, "job cannot be canonicalized: #{e.message}")
+      end
+      return invalid(name, path, fixture.reason) if fixture.is_a?(Fixture::Invalid)
+
+      baseline = begin
+        self.class.canonical_baseline(fixture.job)
+      rescue ::JSON::JSONError, ArgumentError, EncodingError, SystemStackError => e
+        return invalid(name, path, "job cannot be canonicalized: #{e.message}")
+      end
+      status = baseline == Canonical.generate(current_job) ? :identical : :different
+      Entry.new(name, path, status, nil)
+    end
+
+    def invalid(name, path, reason)
+      Entry.new(name, path, :invalid, reason)
+    end
+  end
+end

data/lib/jobpayload/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JobPayload
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/jobpayload.rb

@@ -15,6 +15,8 @@ module JobPayload
   autoload :Boot, "jobpayload/boot"
   autoload :Canonical, "jobpayload/canonical"
   autoload :Snapshotter, "jobpayload/snapshotter"
+  autoload :SnapshotChecker, "jobpayload/snapshot_checker"
+  autoload :SecureFixtureReader, "jobpayload/secure_fixture_reader"
   autoload :Fixture, "jobpayload/fixture"
   autoload :FixtureLoader, "jobpayload/fixture_loader"
   autoload :Checker, "jobpayload/checker"

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jobpayload
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - cottondesu
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -34,6 +35,7 @@ description: |
   deterministic JSON fixtures and checks that the current application can still
   deserialize them (ActiveJob::Base.deserialize and ActiveJob::Arguments.deserialize)
   without ever performing the job.
+email:
 executables:
 - jobpayload
 extensions: []
@@ -58,6 +60,8 @@ files:
 - lib/jobpayload/formatter/json.rb
 - lib/jobpayload/formatter/text.rb
 - lib/jobpayload/result.rb
+- lib/jobpayload/secure_fixture_reader.rb
+- lib/jobpayload/snapshot_checker.rb
 - lib/jobpayload/snapshotter.rb
 - lib/jobpayload/version.rb
 homepage: https://github.com/cottondesu/jobpayload
@@ -68,6 +72,7 @@ metadata:
   source_code_uri: https://github.com/cottondesu/jobpayload
   changelog_uri: https://github.com/cottondesu/jobpayload/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -82,7 +87,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Checks that previously serialized Active Job payloads still deserialize on
   new code.