paper_trail_diff 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00ac8585544b9421fab5fa7cf677a5eddaae2867058beb2c7958ff0e8f917da5
-  data.tar.gz: 52e079e4f84b77ffd804fd452eaf4acc03618d2e7e685969faddcfe2f8c21eba
+  metadata.gz: e747358edb04ac2ea49e43b11eb8b5b8e811c426b50b017ed6d1c72162bb4632
+  data.tar.gz: b330e3bb80e43e478a0e88ff7afeb2b6576d3550af0a54075948fb0e60dc045d
 SHA512:
-  metadata.gz: 400361a0bd6d3d55b3637a5fdcb42febf04ff62a81b75aba3848f70c62d1865f7983016c31bb34347dc50df5b2f66ccb0e44306e2a31990c3db5c04f3806813e
-  data.tar.gz: 0b8497f1dcb9ecd6e12b09e28b7a69fe17363d251308abffb824e8d1d0033572c4bee71351785ed425dc5e46c656d092612c7cb4c1ff33e69ad270d8e2e7260b
+  metadata.gz: 8bcf171950fd74de94c8118dabf3f911e8db3923ce4ed48463c505b3b5748bafbb9c39819b7af49841bf3ea3f6635e797c9536f5d845a42f0a9df9eb1018d1de
+  data.tar.gz: 2eb4d0d286b9daf4ed91e1d0d674c6835569ef3912a2712034fad27d31648c5eeed1e410f34fbfbec3d59808b5d82f178df84b896a233eaec570c3b24b6b52ab

data/CHANGELOG.md

@@ -3,6 +3,95 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.12.0] - 2026-08-19
+
+### Changed
+
+- Report an array inside a JSON column by membership rather than as one opaque
+  value. `nested_changes` now returns a `PaperTrailDiff::ArrayChange` for a pair
+  of arrays, carrying `added`, `removed` and `reordered?` alongside the whole
+  `from` and `to` it already had. Position is deliberately not reported:
+  elements carry no identity, so an insertion at the front makes every later
+  index look changed and one insertion reads as several edits. Membership is
+  answerable without claiming any pairing. Matching is by value and respects
+  duplicates, so `["a", "a"]` to `["a"]` reports one removal. The one thing
+  membership cannot see -- the same elements in a new order -- is named rather
+  than passed over. An element that is itself an object is reported whole,
+  since saying which of its fields changed would require pairing before- and
+  after-elements that nothing in the value licenses.
+
+## [0.11.0] - 2026-08-18
+
+### Added
+
+- Add `PaperTrailDiff.analyze_scope`, which selects the roots to analyze from an
+  ActiveRecord relation or model class instead of an array the caller assembled,
+  in a fixed number of queries. Also reachable as
+  `PaperTrailDiff.analyze_many(scope: ..., limit: ...)`. Every other option
+  behaves as it does for `analyze_many`.
+- `analyze_scope` returns a `ScopedAnalysis`, which destructures into the usual
+  analyses hash and the roots the relation could not reach. A relation's
+  conditions are evaluated against the live table, so a root destroyed during
+  the window cannot be tested against them at all, even though its history is
+  intact and the state it held at destruction may have matched. Those roots are
+  named rather than dropped, so a page auditing deletions is told where to look
+  instead of coming up short without saying so.
+- Add `PaperTrailDiff.nested_changes`, which reports the keys that changed
+  inside an attribute the database stores whole, such as a JSON or jsonb column
+  or one holding JSON as text. An attribute diff could only say the blob
+  changed, leaving the caller to diff it again by hand. Paths are arrays rather
+  than dotted strings, because a JSON key may itself contain a dot. Arrays are
+  reported whole rather than by index, since their elements carry no identity
+  and a list that merely shifted would otherwise look changed throughout. A key
+  that was absent reads as `NestedComparator::ABSENT` rather than nil, because
+  `{"a": null}` and `{}` mean different things in JSON and an audit trail that
+  showed them alike would be lying about one of them. Additive: the existing
+  attribute diff is unchanged, and a pair that is not two readable structures
+  reports nothing.
+- Raise `PaperTrailDiff::BatchLimitExceededError` when a relation selects more
+  roots than `limit:` allows. `limit:` is required for `analyze_scope`: root
+  selection moves into the gem, so the bound on how much work one page can ask
+  for moves with it. It refuses rather than truncating, because a report that is
+  quietly short is worse than one that fails.
+- Accept `group: :transaction` on `activity_timeline` and `analyze(activity:
+  true)`, reporting one saved transaction as one step. A parent and its
+  children saved together produce a version each, so one deliberate action
+  arrived as several steps, and some of them read as empty even though a change
+  was made at that boundary: a version records the state before its own event,
+  so a child's new value is revealed only by a later version of that child, its
+  destroy version, or the live row, none of which exists yet inside the
+  transaction. The change therefore surfaced a step or more later, folded in
+  with whatever that step carried. A step belongs to the transaction of the
+  event that opens it, since that is the event whose change it reports; a step
+  therefore belongs to its `from_boundary`'s transaction, and consecutive steps
+  sharing one are the parts of a single save. Merging compares the group's
+  outer states rather than combining the diffs between them, so a field set and
+  restored inside one transaction correctly reports as unchanged. Off by
+  default.
+- Expose `ActivityBoundary#transaction_id`.
+- A boundary that records no transaction groups with nothing. PaperTrail leaves
+  the column nil outside a transaction and a custom version class need not
+  carry it at all, so treating those as one shared transaction would merge
+  unrelated history into a single step.
+
+### Changed
+
+- Check that the generated Appraisal gemfiles match the `Gemfile`, in CI and in
+  `rake release:preflight`. Every other job runs against a generated gemfile, so
+  a dependency changed only in the `Gemfile` was one CI never installed: the
+  jobs passed having exercised the old version.
+
+### Fixed
+
+- Resolve "does this model record history" through one predicate,
+  `Support.versioned?`. Three copies existed and one of them tested only
+  `respond_to?(:paper_trail)`, which PaperTrail defines on every ActiveRecord
+  model and which therefore answers true for models that never called
+  `has_paper_trail`. Nothing reached that copy with an unversioned model, since
+  the traversal preparer rejects those first, so no released behaviour changed --
+  but the check looked right while being unable to fail, and reading history
+  through it would have raised at the version class rather than at the question.
+
 ## [0.10.0] - 2026-08-15
 
 ### Added

data/README.md

@@ -354,6 +354,68 @@ argument, are loaded per root; other selected branches remain batched. Callers
 should still use an appropriate database transaction when all live queries
 must observe one atomic snapshot.
 
+### Look inside a JSON column
+
+A `json` or `jsonb` column reifies to one Hash, so an attribute diff can only
+say the blob changed. `nested_changes` says which keys changed:
+
+```ruby
+diff = PaperTrailDiff.compare(from_version, to_version)
+
+PaperTrailDiff.nested_changes(diff.attributes.fetch("config"))
+# => { ["theme"]          => <from "dark" to "light">,
+#      ["limits", "max"]  => <from 10 to 20> }
+```
+
+It reads a column that stores JSON as text as readily as a native one, and also
+takes a bare pair: `PaperTrailDiff.nested_changes(from_value, to_value)`.
+
+Nothing about the attribute diff itself changes. A pair that is not two readable
+structures — text on one side and JSON on the other, or a value that does not
+parse — reports nothing, and the caller still has the whole-value change it
+already had.
+
+Three things about the shape are worth knowing:
+
+**Paths are arrays, not dotted strings.** A JSON key may itself contain a dot, so
+`"a.b"` would be ambiguous between one key and two:
+
+```ruby
+PaperTrailDiff.nested_changes({ "a.b" => 1, "a" => { "b" => 1 } },
+                              { "a.b" => 2, "a" => { "b" => 3 } })
+# => { ["a.b"] => <from 1 to 2>, ["a", "b"] => <from 1 to 3> }
+```
+
+**Arrays are reported by membership, not by position.** Elements carry no
+identity, so an insertion at the front would make every later index look
+changed — one insertion described as several edits. An `ArrayChange` says what
+was added and removed, matching by value and respecting duplicates:
+
+```ruby
+change = PaperTrailDiff.nested_changes(
+  { "keywords" => %w[apollo nasa] },
+  { "keywords" => %w[saturn apollo nasa] }
+).fetch(["keywords"])
+
+change.added      # => ["saturn"]
+change.removed    # => []
+change.reordered? # => false
+change.from       # => ["apollo", "nasa"]   (the whole values remain)
+```
+
+Membership cannot see one thing, so it is named rather than passed over: the
+same elements in a new order report `reordered?` as true with nothing added or
+removed.
+
+An element that is itself an object is reported whole. Saying which field of
+which object changed would need a pairing of before-elements with
+after-elements, and nothing in the value licenses that pairing.
+
+**An absent key is not a null one.** `{"a": null}` and `{}` mean different things
+in JSON, and an audit trail that showed them alike would be lying about one of
+them, so a missing key reads as `PaperTrailDiff::NestedComparator::ABSENT`
+rather than `nil`.
+
 ### Reuse already-preloaded current endpoints
 
 `compare`, `compare_many`, and `activity_timeline(..., to: record)` reload
@@ -445,6 +507,54 @@ value is the same `Analysis` that `analyze` returns for one record. A root with
 no versions inside the window gets an empty `Analysis` rather than raising, so a
 listing page needs no special case. Root identities must be unique.
 
+### Letting a relation choose the roots
+
+Assembling that array means querying `versions` for which roots moved, filtering,
+and loading the records — the same selection this gem already performs.
+`analyze_scope` does it for you:
+
+```ruby
+analyses, unreachable = PaperTrailDiff.analyze_scope(
+  Order.where(status: "open"),
+  within: Time.zone.parse("2026-08-01")...Time.zone.parse("2026-09-01"),
+  associations: [:line_items],
+  limit: 500
+)
+```
+
+`analyses` is the same frozen hash `analyze_many` returns. It is also available
+as `PaperTrailDiff.analyze_many(scope: ..., limit: ...)`, and it accepts a model
+class (`Order`) as readily as a relation. Every other option — `within:`,
+`version_scope:`, `associations:`, `ignore:`, `activity:`, `close_on:` — behaves
+exactly as it does for `analyze_many`, and the query cost stays flat in the
+number of roots.
+
+Two things to know before using it.
+
+**`limit:` is required, and exceeding it raises.** Selection moves into the gem
+here, so the bound on how much work one page can ask for has to move with it. It
+refuses rather than truncating, because an audit report that is quietly short is
+worse than one that fails.
+
+**`unreachable` names roots the relation could not reach.** A relation's
+conditions are evaluated against the live table, so a root destroyed during the
+window cannot be tested against them at all — its history is intact, and the
+state it held when it was destroyed may well have matched:
+
+```ruby
+unreachable # => [["Order", "412"]]
+```
+
+These are reported rather than dropped so that a page auditing deletions is told
+where to look instead of silently coming up short. `analyze_many` requires live
+records by design, so to analyze those roots reach for `activity_timeline`, which
+reads history without needing current state.
+
+Note also that a relation selects on **current** state, not on state during the
+window. `where(status: "open")` means open *now*, which is a different set from
+what was open while the window was open. If you need the historical population,
+select on the version history instead and pass the records.
+
 ### Reporting on a subset of root mutations
 
 `version_scope:` narrows which root versions count as *selected mutations*, so a
@@ -665,6 +775,49 @@ boundary. Passing `to: article` is what removes the need to touch the parent
 after an ordinary versioned child mutation; current state is still never
 implicit.
 
+### Reporting one save as one step
+
+A parent and its children saved together produce a version each, so one
+deliberate action arrives as several steps. `group: :transaction` reports it as
+one:
+
+```ruby
+PaperTrailDiff.activity_timeline(
+  article, from: :first, to: article,
+  associations: [:comments], group: :transaction
+)
+```
+
+Given a single transaction that retitled an article, revised one comment, and
+added another, the ungrouped timeline reports three steps — the title change,
+then a step that reads as empty, then the comment changes. Grouped, it reports
+one step carrying the title *and* the comment changes, credited to whoever made
+the save. Off by default; also accepted by `analyze(activity: true)`.
+
+The middle step reads as empty for a reason worth knowing, because it is the
+same rule the rest of this document turns on. A version records the state
+*before* its own event, so a child's new value is revealed only by something
+later: a further version of that child, its destroy version, or the live row.
+Inside a transaction there is usually none of those yet, so a change made at
+that boundary surfaces a step or more afterwards, folded in with whatever that
+step carried. Nothing is lost — but "when" and "with what" both read wrong.
+
+Two properties this relies on:
+
+**A step belongs to the transaction of the event that opens it.** That is the
+event whose change the step reports, so grouping on the closing boundary instead
+would credit each change to whoever made the next one.
+
+**Merging compares the group's outer states**, rather than combining the diffs
+between them. A field set and then restored inside one transaction has not
+changed, and only comparing the endpoints can say so.
+
+A boundary that records no transaction groups with nothing. PaperTrail leaves
+`transaction_id` nil outside a transaction, and a custom version class need not
+carry the column at all; treating those as one shared transaction would merge
+unrelated history into a single step. `ActivityBoundary#transaction_id` exposes
+what a boundary recorded.
+
 ### Reading the state behind a step
 
 A step's diff carries what changed. A renderer often needs what did *not* — to

data/lib/paper_trail_diff/activity_boundary.rb

@@ -12,6 +12,10 @@ module PaperTrailDiff
     attr_reader :event #: String?
     attr_reader :whodunnit #: untyped
     attr_reader :record #: RecordReference
+    # The transaction the version was written in, when PaperTrail recorded one.
+    # Several versions saved together share it, which is what lets a timeline
+    # report one save as one step rather than as its parts.
+    attr_reader :transaction_id #: untyped
 
     class << self
       #: (untyped) -> ActivityBoundary
@@ -23,7 +27,8 @@ module PaperTrailDiff
           item_id: version.item_id,
           recorded_at: version.created_at,
           event: version.event,
-          whodunnit: version.whodunnit
+          whodunnit: version.whodunnit,
+          transaction_id: transaction_id(version)
         )
       end
 
@@ -50,12 +55,21 @@ module PaperTrailDiff
           item_id: version.item_id,
           recorded_at: version.created_at,
           event: version.event,
-          whodunnit: version.whodunnit
+          whodunnit: version.whodunnit,
+          transaction_id: transaction_id(version)
         )
       end
+
+      # A custom version class need not carry the column, and PaperTrail leaves
+      # it nil outside a transaction. Both read as "no transaction here", which
+      # groups with nothing.
+      #: (untyped) -> untyped
+      def transaction_id(version)
+        version.transaction_id if version.respond_to?(:transaction_id)
+      end
     end
 
-    #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped) -> void
+    #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
       kind:,
       version_id:,
@@ -63,7 +77,8 @@ module PaperTrailDiff
       item_id:,
       recorded_at:,
       event: nil,
-      whodunnit: nil
+      whodunnit: nil,
+      transaction_id: nil
     )
       @kind = kind
       @version_id = Support.immutable_copy(version_id)
@@ -72,6 +87,7 @@ module PaperTrailDiff
       @recorded_at = Support.immutable_copy(recorded_at)
       @event = Support.immutable_copy(event&.to_s)
       @whodunnit = Support.immutable_copy(whodunnit)
+      @transaction_id = Support.immutable_copy(transaction_id)
       @record = RecordReference.new(type: @item_type, id: @item_id)
       freeze
     end

data/lib/paper_trail_diff/activity_grouping.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Shared by the two activity builders. They differ in how they choose
+  # boundaries -- one from an explicit version range, one from a wall-clock
+  # window -- but a transaction has to collapse the same way in both, or the
+  # same history would read differently depending on how it was asked for.
+  module ActivityGrouping
+    private
+
+    #: () -> bool
+    def grouping?
+      @group == :transaction
+    end
+
+    # Applied last, to finished steps, so grouping sees the same timeline the
+    # caller would otherwise have received.
+    #: (Array[ActivityStep]) -> Array[ActivityStep]
+    def group_steps(steps)
+      return steps unless grouping?
+
+      ActivityTransactionGrouper.new(steps, retain: @snapshots).call
+    end
+  end
+end

data/lib/paper_trail_diff/activity_timeline_builder.rb

@@ -4,9 +4,15 @@
 module PaperTrailDiff
   # Compares adjacent root and selected-descendant activity boundaries.
   class ActivityTimelineBuilder
-    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
-    def initialize(record, range:, tree:, snapshotter:, snapshots: false)
+    include ActivityGrouping
+
+    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
+    def initialize(record, range:, tree:, snapshotter:, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists
       @snapshots = snapshots
+      @group = group
+      # Merging a group compares its outer states, so the snapshots must survive
+      # the build even when the caller did not ask to keep them.
+      @retain = snapshots || grouping?
       @record = record
       @from = range.from
       @to = range.to
@@ -155,10 +161,10 @@ module PaperTrailDiff
         steps << ActivityStep.between(
           from_boundary: previous_boundary, to_boundary: final_boundary,
           from_snapshot: history.last_snapshot, to_snapshot: final_snapshot,
-          retain: @snapshots
+          retain: @retain
         )
       end
-      steps.freeze
+      group_steps(steps).freeze
     end
 
     # A destroyed root has no later version, but its own event states that
@@ -178,7 +184,7 @@ module PaperTrailDiff
         events,
         @snapshotter,
         current: current,
-        snapshots: @snapshots
+        snapshots: @retain
       ).call
     end
 
@@ -205,7 +211,8 @@ module PaperTrailDiff
         range: @range,
         tree: @tree,
         snapshotter: @snapshotter,
-        snapshots: @snapshots
+        snapshots: @snapshots,
+        group: @group
       )
     end
   end

data/lib/paper_trail_diff/activity_transaction_grouper.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Reports one saved transaction as one activity step.
+  #
+  # A parent and its children saved together produce a version each, and the
+  # timeline reports the gap between every pair of them. One deliberate action
+  # therefore arrives as several steps, none of which is the thing the person
+  # did.
+  #
+  # A version records the state before its own event. Two things follow.
+  #
+  # The change a step reports was made by the event that *opens* it, so a step
+  # belongs to the transaction of its `from_boundary`, and consecutive steps
+  # sharing one are the parts of a single save. Grouping on the closing boundary
+  # instead would credit each change to whoever made the next one.
+  #
+  # And a child's new value is revealed only by something later -- a further
+  # version of that child, its destroy version, or the live row. Inside a
+  # transaction there is usually none of those yet, so a step can read as empty
+  # while a change was in fact made at that boundary, and the change surfaces
+  # later, folded in with whatever that step carried. Grouping puts it back
+  # together with the save it belongs to.
+  #
+  # Merging compares the group's outer snapshots rather than combining the
+  # diffs between them. A field set and then restored inside one transaction
+  # has not changed, and only a comparison of the endpoints can say so.
+  #
+  # A boundary with no transaction groups with nothing. PaperTrail leaves the
+  # column nil outside a transaction, and a custom version class need not carry
+  # it at all; treating those as one shared transaction would merge unrelated
+  # history into a single step.
+  class ActivityTransactionGrouper
+    #: (Array[ActivityStep], retain: bool) -> void
+    def initialize(steps, retain:)
+      @steps = steps
+      @retain = retain
+    end
+
+    #: () -> Array[ActivityStep]
+    def call
+      grouped = [] #: Array[Array[ActivityStep]]
+      @steps.each do |step|
+        open_group = grouped.last
+        if open_group && continues?(open_group, step)
+          open_group << step
+        else
+          grouped << [step]
+        end
+      end
+      grouped.map { |group| merge(group) }
+    end
+
+    private
+
+    # @rbs @steps: Array[ActivityStep]
+    # @rbs @retain: bool
+
+    #: (Array[ActivityStep], ActivityStep) -> bool
+    def continues?(open_group, step)
+      transaction = step.from_boundary.transaction_id
+      return false if transaction.nil?
+
+      open_group.last.from_boundary.transaction_id == transaction
+    end
+
+    # Rebuilt rather than reused even when a group holds one step, so that every
+    # returned step retains its snapshots on the same terms.
+    #: (Array[ActivityStep]) -> ActivityStep
+    def merge(group)
+      first = group.first #: ActivityStep
+      last = group.last #: ActivityStep
+      ActivityStep.between(
+        from_boundary: first.from_boundary,
+        to_boundary: last.to_boundary,
+        from_snapshot: first.from_snapshot,
+        to_snapshot: last.to_snapshot,
+        retain: @retain
+      )
+    end
+  end
+end

data/lib/paper_trail_diff/diagnostics.rb

@@ -198,7 +198,7 @@ module PaperTrailDiff
 
     #: (untyped) -> bool
     def model_versioned?(model_class)
-      model_class.respond_to?(:paper_trail_options) && !model_class.paper_trail_options.nil?
+      Support.versioned?(model_class)
     end
 
     #: (untyped) -> bool

data/lib/paper_trail_diff/errors.rb

@@ -32,6 +32,10 @@ module PaperTrailDiff
   # Raised when versions sharing a timestamp cannot be ordered by their ids.
   class AmbiguousVersionOrderError < Error; end
 
+  # Raised when a relation selects more roots than the batch was told to analyze.
+  # Truncating instead would hand back a report that is short without saying so.
+  class BatchLimitExceededError < Error; end
+
   # Raised when a requested ActiveRecord association does not exist.
   class UnknownAssociationError < Error; end
 

data/lib/paper_trail_diff/nested_comparator.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'json'
+
+module PaperTrailDiff
+  # Compares the inside of a value a database column holds whole.
+  #
+  # A JSON or jsonb column reifies to one Hash, so an ordinary attribute diff
+  # can only say that the blob changed. This says which keys changed, leaving
+  # the surrounding diff untouched.
+  #
+  # Three decisions worth knowing about.
+  #
+  # Paths are arrays, not dotted strings. A JSON key may contain a dot -- host
+  # names and locales routinely do -- and joining would make `a.b` ambiguous
+  # between one key and two.
+  #
+  # Arrays are reported by membership, not by position -- see ArrayChange. Their
+  # elements carry no identity, so an insertion at the front makes every later
+  # index look changed, and one insertion reads as several edits. What is added
+  # and removed can be answered without claiming any pairing; what cannot is the
+  # same elements in a new order, so that is named rather than passed over.
+  #
+  # An absent key is not a null one. `{"a": null}` and `{}` mean different
+  # things in JSON and an audit trail that conflated them would be lying about
+  # one of them, so absence is its own value rather than nil.
+  class NestedComparator
+    # Stands in for a key that was not there at all.
+    ABSENT = Object.new
+    def ABSENT.inspect = '#<PaperTrailDiff absent>'
+    def ABSENT.to_s = 'absent'
+    ABSENT.freeze
+
+    #: (untyped, untyped) -> nested_changes
+    def self.call(from_value, to_value)
+      new(from_value, to_value).call
+    end
+
+    #: (untyped, untyped) -> void
+    def initialize(from_value, to_value)
+      @from_value = from_value
+      @to_value = to_value
+    end
+
+    # Returns the changed paths, or an empty hash when the pair is not two
+    # structures this can look inside. An empty result therefore means "nothing
+    # to report at this depth", and the caller still has the whole-value change.
+    #: () -> nested_changes
+    def call
+      from_structure, to_structure = structures
+      return {} unless from_structure && to_structure
+
+      changes = {} #: nested_changes
+      walk(from_structure, to_structure, [], changes)
+      changes.freeze
+    end
+
+    private
+
+    # @rbs @from_value: untyped
+    # @rbs @to_value: untyped
+
+    # Both sides have to be readable as a Hash for a nested answer to mean
+    # anything. A column that held text on one side and JSON on the other
+    # changed wholesale, and saying so is the accurate report.
+    #: () -> [Hash[untyped, untyped]?, Hash[untyped, untyped]?]
+    def structures
+      [structure(@from_value), structure(@to_value)]
+    end
+
+    #: (untyped) -> Hash[untyped, untyped]?
+    def structure(value)
+      return value if value.is_a?(Hash)
+      return unless value.is_a?(String)
+
+      parsed = begin
+        JSON.parse(value)
+      rescue JSON::ParserError, TypeError
+        nil
+      end
+      parsed if parsed.is_a?(Hash)
+    end
+
+    #: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
+    def walk(from_hash, to_hash, path, changes)
+      keys(from_hash, to_hash).each do |key|
+        from_item = from_hash.key?(key) ? from_hash[key] : ABSENT
+        to_item = to_hash.key?(key) ? to_hash[key] : ABSENT
+        next if from_item == to_item
+
+        here = [*path, key.to_s].freeze
+        if from_item.is_a?(Hash) && to_item.is_a?(Hash)
+          walk(from_item, to_item, here, changes)
+        else
+          changes[here] = change_for(from_item, to_item)
+        end
+      end
+    end
+
+    # Two arrays are a membership change; anything else is a change to the
+    # value as a whole, including an array facing something that is not one.
+    #: (untyped, untyped) -> nested_change
+    def change_for(from_item, to_item)
+      if from_item.is_a?(Array) && to_item.is_a?(Array)
+        ArrayChange.new(from: from_item, to: to_item)
+      else
+        ValueChange.new(from: from_item, to: to_item)
+      end
+    end
+
+    # Sorted so a report reads the same twice, and stringified because a hash
+    # loaded from JSON and one built in Ruby can key the same field differently.
+    #: (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[untyped]
+    def keys(from_hash, to_hash)
+      (from_hash.keys | to_hash.keys).sort_by(&:to_s)
+    end
+  end
+end