paper_trail_diff 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfe7bccfe2f013af725d6ac92c772d357127d5a0c14cae72fac0000cb58fad62
-  data.tar.gz: 308cc912a32875582ff8e083ec52016d4ca586ee75f3b0e36172360d2600b01d
+  metadata.gz: 8b8f753f8bf15574c43fe572252b467b6066f097d0ad9990b6f1d8a74f41d938
+  data.tar.gz: 536266a31306236cc26e71b3024af058f96a0544d363f0fb971b5b49f9b1b578
 SHA512:
-  metadata.gz: e948b33a959fc8ffdd00d7468819917f126b961c3daa4548f38260315dabab6fa36cddd9019b171c6aad306eae2b09485568591d5f2f07d42ba9a661e93bfd32
-  data.tar.gz: 2ea2cae4b3147f1c4655e79d2ebe2a68202e991f61227718990ec9dcdce38e631f0122ae6fe510aac217ae15f54c1e223095e28148c08944614698a73c3c42dd
+  metadata.gz: 5070f94bc6bb46a58d6a80352aebd2f7c2392e0486c0197fe8977cb257af3b1a7644643fc1587df33bf6b0138df25ac67a3629ccf004fc627de3be883b321db1
+  data.tar.gz: 8771c47edd7d8ec39347b7d76883af7c2ff7137ac7670064672dbc5fccea0c196d5e461624c183c8d51890b8a84472625fba8cc283c72d1375a0331fd3cb1efd

data/CHANGELOG.md

@@ -3,6 +3,293 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.14.0] - 2026-10-29
+
+### Breaking changes
+
+- A `has_and_belongs_to_many` with a scope, or whose target has a default
+  scope, raises `UnsupportedAssociationError` up front in every method, and
+  `association_paths` leaves it out. PT-AT records a HABTM's members through
+  its scope when the owner saves, so a target that entered the scope between
+  saves was missing from history, and `activity_timeline` raised `KeyError`.
+  Replace it with a `has_many :through` a versioned join model.
+- `report`, and `analyze_scope` with `activity: true`, also select a record
+  when only a record on one of its requested `associations:` changed in the
+  window: editing a comment selects its article. They used to skip it, although
+  `analyze_many` reports that activity. A report can therefore return more
+  records and reach `limit:` sooner. Nested paths count at every level,
+  `has_many :through` counts its join rows, and a child that moved selects its
+  old and new owner. Selection adds one query per association level, not per
+  record. Checkpoint analyses (`activity: false`) are unchanged: they compare a
+  record's own versions, so only those select it. To keep only records that
+  changed themselves, drop analyses whose `timeline` is empty. A record
+  selected through a HABTM path in a window that ends at the current record
+  raises `UnsupportedLiveActivityError`, as one that changed itself already
+  does.
+- A path that continues past a polymorphic `belongs_to`, such as
+  `"notable.comments"`, raises `UnsupportedAssociationError`. The part after
+  it used to be ignored without a word.
+- A HABTM below the root, such as `"tags.articles"`, `"author.articles.tags"`,
+  or `"comments.article.tags"`, raises `UnsupportedAssociationError` up front
+  in every method, naming the path and the HABTM. `association_paths` leaves
+  such a path out. PT-AT records HABTM membership only when its owner saves a
+  version, in rows that do not name the owner, so a root checkpoint holds the
+  root's membership alone. These paths read the root's rows instead and
+  returned a wrong diff. An article that joined a tag went unreported, and
+  against the current record every member read as added. A sibling article
+  reached through its author was given the root's tags. `activity_timeline`
+  raised `KeyError`. Only a path that led back to the root, like
+  `"comments.article.tags"`, read correctly; request `"tags"` instead.
+- A root HABTM read at a version saved in the same transaction as a version of
+  another record with a HABTM of that name raises
+  `IncompleteAssociationHistoryError`, naming the association and the
+  transaction, when PT-AT recorded members there. Those rows do not say which
+  record they belong to, so the root used to read every such record's members
+  as its own: two articles updated in one transaction each gained the other's
+  tags, and an unchanged article reported them removed. It happened in every
+  method, with no error. A transaction where only one record with that
+  association saved a version, or where none recorded a member, reads as
+  before, and `diagnose` reports the shared case as `habtm_transaction_shared`.
+  Save HABTM owners' versions in separate transactions, as a
+  [checkpoint](docs/reference.md#saving-a-checkpoint) does.
+
+### Added
+
+- `recorded_changes(version)` returns what PaperTrail stored with one version
+  in `object_changes`, as a frozen hash of `ValueChange` objects, typed by the
+  version's model. Unlike PaperTrail's `version.changeset`, it never loads the
+  record, so it costs no query per version and still types a deleted record's
+  values. It returns `nil` when nothing was recorded, and takes an `ignore:`
+  array that defaults to `updated_at`.
+
+### Changed
+
+- Batch reads of a `has_many :through` and of a polymorphic `belongs_to` no
+  longer call `reify` on each root version. They are read from stored
+  attributes like other associations. In the reconstruction probe, `report`
+  over a through went from 7 `reify` calls per root to none and builds about
+  half as many model instances. Results are unchanged. A type that names no
+  class, an unversioned target, and a scope that cannot be read as conditions
+  still take the record path.
+- Batch methods read an association scope, or a target's default scope, made
+  of plain conditions on the target's columns (equality, `IN`, `nil`, their
+  `where.not` forms, combined with `and` and `or`) from prepared history, so
+  they no longer need `allow_expensive: true` for it and its query count no
+  longer grows with the records. String conditions are read this way only on
+  SQLite and PostgreSQL. Scopes that take the owner and other conditions are
+  still rejected without the opt-in. A default-scoped model whose scope assigns
+  no attributes is read without `reify`.
+- Batch methods also read a `limit` or `offset`, and the order of a `has_one`,
+  from prepared history when the order is total, reaching the primary key, and
+  sorts only by integer, boolean, or integer enum columns of the target. NULL
+  sorts as each adapter puts it by default. In the reconstruction probe,
+  `report` over `order(:id).limit(1)` went from 252 queries and 160 `reify`
+  calls at 20 roots, with the opt-in, to 32 queries and none without it. A
+  string order, an order with ties, and a `has_one :through` over a ranked
+  part are still rejected without the opt-in.
+- Batch methods also rank by date columns, and by datetime columns when the
+  column declares a precision that history keeps and times are stored in UTC,
+  such as `order(created_at: :desc).limit(5)` with YAML history. JSON history
+  keeps milliseconds by default, so with it only a `datetime(3)` column is
+  read. A time-of-day column, and a datetime without a precision, are still
+  rejected without the opt-in.
+- Batch methods read a `has_many :through` over a part with a `limit`,
+  `offset`, or `has_one` order, and one with its own `limit` or `offset`, from
+  prepared history without the opt-in.
+- The README recipe for deleted records also reads each record as it was just
+  before deletion, which a record created inside the window has no other
+  snapshot of.
+- The documentation now says where a change saved without a version, such as
+  with `update_columns`, appears: in the step for that record's previous
+  recorded change, credited to its author, anywhere in a range. It used to say
+  only that the last step of a range ending at the current record shows them,
+  and that a step's diff is exactly what its event changed. Ending a range at a
+  version leaves out only the writes after it. Specs pin this behavior, which
+  is unchanged.
+- The README has a recipe that turns a report into one row per changed field,
+  with the record, whether it changed, appeared, or disappeared, and the step's
+  author, event, and time.
+- Batch methods no longer need `allow_expensive: true` for a
+  `has_many :through` whose source is a `has_many`, such as an author's
+  comments through articles. It is read from prepared history like the other
+  associations, so its queries no longer grow with the records: the five-record
+  probe in `docs/performance.md` went from 200 queries to 20.
+
+### Fixed
+
+- A `limit` or `offset` scope, or an ordered `has_one`, read at a version
+  returns the records its query returned then, when the order is total and
+  sorts by columns batch methods can rank. It used to start from
+  the association's current rows, so a range whose records later changed
+  reported the wrong ones: with comments `first` and `second` under
+  `order(:id).limit(1)`, destroying `first` and adding `third` reported
+  `third` added instead of `second`. Other ranked scopes still read the
+  current rows.
+- A `has_many :through` reads its parts as its own query does, keeping their
+  conditions but not their `limit`, `offset`, or `has_one` cut. History used
+  to apply them, and read with the opt-in it could raise PT-AT's
+  `FoundMoreThanOne`; batched history kept only one record through a `has_one`
+  part. A through's own `limit` or `offset` counts a record reached through
+  two join records twice, as the query does.
+- Batch comparisons with a current endpoint load a `has_many :through` over a
+  part with a `limit`, `offset`, or `has_one` per record. Active Record's
+  preloader applied the part's limit across every record in the batch, so a
+  record could show another's members or none.
+- A record reached through two join records is one member of a current
+  association, as it already was of a historical one, so a through loaded per
+  record no longer raises a duplicate identity error.
+- In a batch, a `has_one` with an `offset` is loaded per record at the current
+  end. The preloader applied the offset across all records at once, so a
+  record could show another record's member.
+- Activity reports a change to a `belongs_to` target that is an STI subclass.
+  When the target was destroyed, or its `type` changed between a subclass and
+  another class, activity reported nothing while checkpoint analysis reported
+  it, because a target's version names only the base class. This includes the
+  same target further down a path, such as `"note.badge"`.
+- An association that only an STI subclass declares can be requested on a
+  root of that subclass in every method. Without an `item_subtype` column on
+  versions, each version resolved to the base class, so every method raised
+  `UnknownAssociationError`. The subclass is now read from the type the
+  version stored, or for a `create`, from its recorded changes. A stored type
+  that names no class raises `InvalidEndpointError`.
+- A `has_many :through` with `source_type:` holds only the records reached
+  through join records of that type, in every method. History used to ignore
+  the option, so a join record pointing at another type made its target a
+  member: a holder whose links named a tag reported the tag among its authors,
+  and the tag's changes opened activity steps and selected the holder in
+  `report`. The current record was read correctly, so a comparison with it
+  reported the tag as removed. A join record whose type changes now adds or
+  removes its target in the step of that version.
+- A scoped or default-scoped association read from history now holds the
+  records that met the scope at each point. It used to ignore the scope's
+  conditions for history: a record that left the scope was reported as
+  changed instead of removed, one that entered it as changed instead of
+  added, and a record outside the scope could be reported as removed when it
+  was destroyed or moved. Activity reports entering or leaving the scope as
+  an addition or removal at the version that did it.
+- `compare` and `compare_many` between two versions report a `has_many` child
+  that moved to another owner afterwards. They reported no change: the
+  comparison read associations through PT-AT, which finds children by the keys
+  their versions recorded after each change, so the child was not found at the
+  earlier version. Version pairs now read the same prepared history as a
+  comparison with the current record, including for a record that was deleted.
+- Historical analysis through a polymorphic `belongs_to` works in every method.
+  Only comparisons between two versions used to work: timelines, analyses,
+  reports, and comparisons with the current record raised `ArgumentError`.
+  Batches load the targets with one query per target class. A target class
+  without `has_paper_trail` raises `UnversionedAssociationError` when a record
+  names it, rather than a `NoMethodError` from PT-AT, and a default-scoped
+  target class is read as its association returns it. A type that names no
+  class, such as one a renamed model left in its versions, raises
+  `IncompleteAssociationHistoryError` naming the record and the type, rather
+  than a `NameError` that names neither.
+- Activity leaves out the `belongs_to` target a record moves to in the
+  version that closes the window. Its changes inside the window used to add
+  empty steps, attributed to a record the root never pointed at there.
+- Activity reports a change to a `belongs_to` target, or to the source of a
+  `has_many :through`, when the record pointing at it did not change in the
+  window: an author renamed under an article nobody edited. It used to report
+  nothing. A record that changed its target in the window also reports
+  changes to the target it pointed at before.
+- `include_deleted: true` with `activity: true` reports the association
+  activity of a deleted record that did not change itself in the window. Its
+  analysis used to be empty.
+- History of an association to an STI subclass, such as
+  `has_many :pinned_badges, class_name: 'PinnedBadge'`, holds only that class
+  and its subclasses, as the live association does. It used to hold the
+  sibling classes' records too, so a range ending at the current record
+  reported them as removed. Activity used to report a sibling's changes under
+  the association too, and to open a step for each version of a sibling or of
+  its children.
+- Activity reports a record whose STI type changed in the step of the version
+  that changed it, as a removal of the old type and an addition of the new,
+  and adds it to or removes it from an association to an STI subclass there.
+  It used to add the new type alongside the old one and leave the old one in
+  place until a later step, or to the end of a range ending at a version.
+- `activity_timeline`, and `analyze` with `activity: true`, return no steps for
+  a range that ends at a version when `version_scope:` keeps none of its
+  versions, as a checkpoint timeline does. They used to raise `NoMethodError`.
+- `analyze_scope` and `report` list `unreachable` in the same sorted order
+  whatever the type of `versions.item_id`. With a string `item_id` it used to
+  follow the database's order.
+- On SQL Server, activity places a version saved within two milliseconds of a
+  window's start or end on the side it was saved. The window's bounds used to
+  be rounded to 1/300 second, so such a version could be read as outside the
+  window, or one just past its end as inside it.
+- A `has_many :through` that goes through a `has_and_belongs_to_many`, as its
+  `through:`, its `source:`, or further down its chain, raises
+  `UnsupportedAssociationError` up front in every method, naming the path and
+  the HABTM. Comparing two versions used to raise `NoMethodError` from inside
+  PT-AT, and analyses `ActiveRecord::StatementInvalid`. A `has_many :through`
+  Active Record cannot follow at all, such as one through a polymorphic
+  `belongs_to`, likewise raises Active Record's own error in every method,
+  where historical work used to fail partway with `ArgumentError` or
+  `NoMethodError`.
+- `association_paths` leaves out a `has_many :through` that goes through a
+  `has_and_belongs_to_many`, so every path it lists can be requested. It
+  decides with the same check a request makes. It used to list such a path,
+  and a settings screen built from it offered one that failed when picked. A
+  model it reaches with a `has_many :through` Active Record cannot follow,
+  such as one through a polymorphic `belongs_to`, raises Active Record's own
+  error, where discovery used to raise `ArgumentError`, `NameError`, or
+  `NoMethodError` from inside the reflection, or list a path that raised when
+  requested.
+- A `has_many :through` whose source is a `has_many` follows records that
+  move. A comment moved to another article leaves the first article's author
+  and joins the other's, and an article that moves to another author takes its
+  comments with it. Analyses, timelines, and comparisons with the current
+  record used to report no change for such a move, and could report a record
+  that left and came back as changed. They read these associations through
+  PT-AT, which finds a record by the keys its later versions recorded.
+- A `has_many :through` whose `through:` is itself a `has_many :through`, such
+  as `has_many :comment_reviewers, through: :comments, source: :reviewer` with
+  `comments` through `articles`, reports its changes in analyses, timelines,
+  and batches. It used to read as empty at every point, so it never reported a
+  change.
+
+### Development
+
+- Mutation testing also covers `ScopeCondition`, which decides the records an
+  association scope admits. The reconstruction probe has a `scoped` scenario.
+- The consistency specs also check that activity selection includes every
+  record whose analysis reports a change.
+- Mutation testing also covers `TimeRange`, `VersionRange`,
+  `TimeVersionRange`, `BatchedRootVersions`, and `DeletedAnalysisBatch`, each
+  with a unit spec of its own; all 5,485 mutations across the fourteen classes
+  are caught.
+- Mutation testing also covers `RecordedChanges`; all 257 of its mutations are
+  caught.
+- Mutation testing also covers the association code: `ScopedRootSelection`,
+  `AssociationActivitySelection`, `AssociationActivityEdge`,
+  `ActivityTargetCandidateLoader`, `PreparedHistoryLoader`,
+  `PreparedEdgeLoader`, `ActivityTimelineBuilder`,
+  `ActivityTransactionGrouper`, and `BatchSafety`, each with a spec of its
+  own. All 10,732 mutations across the 24 classes are caught.
+- Mutation testing also covers `AssociationTraversal`, which decides which
+  association paths a request accepts, with a spec of its own; all 764 of its
+  mutations are caught.
+- Mutation testing also covers range and boundary handling:
+  `ActivityRange`, `VersionAssociationCandidateScope`, and
+  `PreparedActivityIndex`, each with a spec of its own; all 1,507 of their
+  mutations are caught.
+- Mutation testing also covers `HabtmTransactionOwners`, which decides whether
+  a transaction's HABTM members can be read as one record's, with a spec of
+  its own.
+- `benchmark/investigation/reconstruction.rb` runs again: the association
+  fixtures load the monotonic test clock they use. Its `prepared-through`
+  experiment and `benchmark/investigation/prepared_through_override.rb` are
+  removed, since the gem now reads those throughs that way.
+- `spec/association/through_membership_spec.rb` writes out the expected
+  membership of a `has_many :through` with a `has_many` source over moves,
+  deletions, transactions, and changes saved without a version, alone and in
+  a batch.
+- `ActivityEventRouteFinder` no longer checks for a polymorphic `belongs_to`
+  before following a path below it. Validation already rejects such a path,
+  so the check could not be reached.
+- The `PreparedHistoryLoader` spec checks that an edge into a versioned model
+  with records stays prepared. A full mutation run of the 29 classes now
+  catches all 13,284 mutations.
+
 ## [0.13.1] - 2026-10-28
 
 ### Fixed

data/QUICKSTART.md

@@ -203,9 +203,10 @@ report.analyses.each_value { |analysis| analysis.diff.to_h }
 are selected, the call raises instead of returning a partial report. Omit
 `include_deleted:` if you only need articles that still exist.
 
-An article needs its own PaperTrail version in the time window to be selected.
-Editing a comment alone does not select its article. A relation's `where`
-conditions check current values; they cannot check a deleted article's values.
+An article is selected when it has a PaperTrail version in the time window. With
+`associations: [:comments]`, editing a comment alone also selects its article. A
+relation's `where` conditions check current values; they cannot check a deleted
+article's values.
 
 For one article, use a window ending now:
 
@@ -374,9 +375,11 @@ window to select that article.
   change. Pass `article` to read the current saved values.
 - PaperTrail's creation version returns `nil` from `reify`. There was no record
   before creation; the diff reports the record being added.
-- A range ending at the current article includes changes PaperTrail never
-  recorded, such as `update_columns`. Pass a version as `to:` to stop at
-  recorded history.
+- Changes PaperTrail never recorded, such as `update_columns`, still show up:
+  in the step for the article's previous recorded change, credited to its
+  author. Passing a version as `to:` leaves out only the ones made after it.
+  `PaperTrailDiff.recorded_changes(version)` reads just what a version
+  recorded.
 - `ignore:` replaces the default list. Include `updated_at` yourself when using
   a custom list and you still want it ignored.
 - Historical associations require PT-AT to be installed, loaded, migrated, and

data/README.md

@@ -121,6 +121,10 @@ responsible for that change, including its `whodunnit`, `event`, `item_type`,
 and `item_id`. Its `recorded_at` is the version's `created_at`.
 Use this source information for attribution: the version used to read the
 resulting state, exposed as `to_boundary`, may have been saved by someone else.
+A change saved without a version, such as with `update_columns`, appears in the
+step for that record's previous recorded change. To read only what a version
+recorded, use `PaperTrailDiff.recorded_changes(version)`; see
+[what a version recorded](docs/reference.md#what-a-version-recorded).
 
 `group: :transaction` combines changes from one database transaction. Its source
 information comes from the first event in that group. Omit `group:` if you need
@@ -172,16 +176,24 @@ unavailable = report.deleted.select { |_identity, analysis| analysis.nil? }.keys
 deleted_activity = report.deleted.transform_values do |analysis|
   analysis&.activity_timeline
 end
+last_state = report.deleted.transform_values do |analysis|
+  analysis&.activity_timeline&.last&.diff&.record_presence_change&.from
+end
 ```
 
 The results are already computed; you do not need to query or reify each deleted
-record. Omit `include_deleted:` if you only need records that still exist.
+record. `last_state` is each record just before its deletion, which the final
+step removes. Use it to show what a deleted record was, such as its title:
+`analysis.from_snapshot` is the record when the window began, so it is `nil` for
+one created inside the window. Omit `include_deleted:` if you only need records
+that still exist.
 
 Three selection rules matter:
 
-- The record itself needs a PaperTrail version in the time window. For example,
-  editing only a comment does not select its article. Comment activity is included
-  for selected articles when you request `associations: [:comments]`.
+- A record is selected when it, or a record on one of the `associations:` you
+  request, has a PaperTrail version in the time window. With
+  `associations: [:comments]`, editing only a comment selects its article, and
+  the article's report shows the edit.
 - A relation such as `Article.where(status: "open")` checks today's values.
   It cannot establish whether deleted articles matched that condition. Deleted
   records are therefore listed separately.
@@ -197,7 +209,64 @@ for pagination, deleted records, and selecting by past values with
 `historical_filter:`.
 
 For a fixed past window, use `analyze_scope(Article.all, within: start_time...end_time,
-limit: 100)`.
+activity: true, limit: 100)`. Without `activity: true`, `analyze_scope` compares
+each record's own versions, so it selects only records with a version of their
+own.
+
+## 4. Turn a report into rows
+
+For a history table or an export, flatten a report into one row per changed
+field. Each row names the record, the change, and who made it. This example
+requires the association setup in the quickstart:
+
+<!-- executable:recipe-summary -->
+```ruby
+report = PaperTrailDiff.report(
+  Article.all, since: 1.day.ago, limit: 100,
+  associations: [:comments], include_deleted: true
+)
+analyses = report.analyses.merge(report.deleted.compact)
+
+rows = analyses.flat_map do |root, analysis|
+  analysis.activity_timeline.flat_map do |step|
+    source = step.source_boundary
+    step.diff.each_entry.filter_map do |entry|
+      next unless entry.attribute # skip entries for whole records and associations
+
+      from, to, change =
+        if entry.change?
+          [entry.value.from, entry.value.to, :changed]
+        elsif entry.state == :after
+          [nil, entry.value, :added]
+        else
+          [entry.value, nil, :removed]
+        end
+      next if from.nil? && to.nil? # a blank field of an added or removed record
+
+      record = entry.record # nil for the article itself
+
+      {
+        root: root,
+        association: entry.association_path.join("."), # "" for the article itself
+        record: record ? [record.type, record.id.to_s] : root,
+        change: change, attribute: entry.attribute, from: from, to: to,
+        actor: source.whodunnit, event: source.event, recorded_at: source.recorded_at
+      }
+    end
+  end
+end
+```
+
+`change` is `:changed` for an edited field. It is `:added` or `:removed` for
+each field of a record that appeared or disappeared: the article was created
+or deleted, or a comment joined or left it. A comment moved from another
+article is also `:added`; its `event` is then `"update"` rather than
+`"create"`. `actor`, `event`, and `recorded_at` describe the step's source
+version. With `group: :transaction`, that is the transaction's first event.
+
+Rows follow the report's record order, with deleted records last, then each
+record's steps in time order. Labels, grouping, and formatting are left to your
+application.
 
 ## Choose a method
 
@@ -225,10 +294,16 @@ method inside a loop. They share history loading across records. Ordinary
 record and direct-association histories can be read without creating a model
 instance for every historical state.
 
-Some associations still need per-record queries. Batch methods reject scoped
-associations and certain `has_many :through` histories by default with
-`UnsupportedBatchPathError`. The error names the association. Remove it from
-`associations:`, or pass `allow_expensive: true` if you accept that cost.
+Scopes and default scopes made of plain conditions, such as
+`-> { where(archived: false) }`, are batched too, and so is a `limit` or
+`offset` ordered by integer, boolean, date, or datetime columns down to the
+primary key, such as `-> { order(:position, :id).limit(3) }`, on a direct
+association or a `has_many :through`. Some associations still need per-record
+queries, such as a `limit` ordered by a string or scopes that take
+the owner.
+Batch methods reject those by default with `UnsupportedBatchPathError`. The
+error names the association. Remove it from `associations:`, or pass
+`allow_expensive: true` if you accept that cost.
 Callbacks and callable historical filters can also issue queries. See the
 [performance guide](docs/performance.md) for measured behavior and limitations.
 

data/docs/architecture.md

@@ -36,9 +36,26 @@ only the association paths you request:
 
 From that, the gem builds each state without querying again. Plain recorded
 attributes are read straight from the stored version, without creating a model
-instance. Models with initialization callbacks, custom attribute types or
-defaults, default scopes, or encrypted attributes are rebuilt with PaperTrail's
-`reify` instead, so their behavior is kept.
+instance, including the members of a `has_many :through` and the target of a
+polymorphic `belongs_to`. Models with initialization callbacks, custom
+attribute types or defaults, default scopes that assign attributes, or
+encrypted attributes are rebuilt with PaperTrail's `reify` instead, so their
+behavior is kept.
+
+An association scope or a target's default scope is read once into a
+`ScopeCondition`: the `where` conditions of the relation it builds, kept only
+when each is an equality, `IN`, or `nil` test, or a negation of one, on the
+target's own column of a type Ruby compares as the database does. A record
+belongs to the association at a point when its key matches and its state
+there meets the condition. A `limit`, `offset`, or `has_one` order is read
+into a `ScopeRanking` when its order is total and every key compares in Ruby
+as the database sorts it, including where each adapter puts NULL; the records
+that meet the condition are then sorted, offset, and limited as the
+association's query would. A `has_many :through` reads its parts' conditions
+only, at any depth, as its query joins them, and ranks by its own order the
+rows the join yields, a record reached twice counting twice. Activity reads a scoped branch again at each event
+on it rather than patching the previous snapshot, since any edit can move a
+record into or out of the scope, and with a ranking, move another record too.
 
 Each rebuilt state is an immutable snapshot. Activity timelines carry the
 previous snapshot forward and replace only the parts an event changed, so an
@@ -51,17 +68,23 @@ These association shapes cannot be read from the loaded history. The gem asks
 PT-AT to rebuild them at each point instead, which costs queries per record and
 resolves association membership by timestamp only:
 
-- associations with a scope, including `limit` and owner-dependent scopes;
-- targets with a default scope;
+- associations with a scope the gem cannot read as plain conditions and an
+  exact ranking, including owner-dependent scopes and a `limit` without a
+  total integer order;
+- targets with such a default scope;
 - targets that are not versioned;
-- composite foreign keys;
-- `has_many :through` associations whose source is not a `belongs_to`.
+- composite foreign keys.
 
-Batch methods reject the scoped and through cases unless you pass
+Batch methods reject the scoped cases unless you pass
 `allow_expensive: true`; see [costly associations](reference.md#costly-associations).
 
 HABTM membership comes from the snapshots PT-AT records with each transaction,
-so it is only known at root versions saved in a transaction.
+so it is only known at root versions saved in a transaction. Those snapshots
+name the transaction and the association but not the owner, so they give only
+the root's own membership, and a HABTM below the root is rejected before any
+history is read. Even at the root, a transaction in which another record with a
+HABTM of the same name saved a version holds both records' members;
+`HabtmTransactionOwners` finds those transactions, and reading one raises.
 
 ## Database indexes