forest_admin_agent 1.45.2 → 1.46.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3d274612ae79795715d531ee72fce9566b2f6bc0ca79fd2f60538498f8cef8e
-  data.tar.gz: 54daad3999b1ff2bdcef2257c9638dd2896c160083f852f6e4501cef3288d478
+  metadata.gz: be21283660e21385c61e7a2b4312996bd27c516d5835483a9548967eda3c10a3
+  data.tar.gz: 8db034fa9e1562fd7552d2f8b4fae5ddc29944b71d1902a715d05d4531c15b47
 SHA512:
-  metadata.gz: c585bcad5f56d230eeb0dfd382c0a5543bf0a01b97bfee5499ae70e8533055f17b1b1093156ea18daf53ef06fa6daf57c953107da0da94a6461cde8620173f13
-  data.tar.gz: 361983398aa5072601e09aea9ddaf75209a9582edc1b28291be9aa144a4c85f512394ea4ef1e40d3449cdb97c39d798ba8564625ee44b7403a1bf99f94218c2d
+  metadata.gz: 691a6dc3a633103b92e6cea06db4c7adf5fb1bcf2d294bbcdac8afd1c4d27af6794f325ad8b4c286c5c06e9469df8428f1a0c6fce81f8ca8318f072367435add
+  data.tar.gz: 67b147dbe477ca883faa985b2802187e3e0c6971896e129c288a15c85a9dc7118fe811f7d497bee9ef534c233bf15b0e0e008bb5ac121cae118605a3ee17b32c

data/AUDIT_TRAIL.md

@@ -13,8 +13,9 @@ Two parts, both internal:
   schema and creates/evolves the `audit_logs` table through versioned migrations, and reads the
   per-record history back for the routes below.
 
-Storage uses ActiveRecord: outside Rails, add `gem 'activerecord'` (and the adapter gem) to your
-Gemfile. Nothing is loaded and no connection is opened until the feature is configured.
+Storage uses ActiveRecord on a PostgreSQL database. The agent depends on `activerecord` and `pg`, so
+there is nothing to add to the Gemfile, even in an app whose main datasource is not SQL. Nothing is loaded
+and no connection is opened until the feature is configured.
 
 ## Turn it on
 
@@ -122,6 +123,7 @@ or removed still reads as they were when they acted. Optional filters (all combi
 | query param | format                           | effect                                          |
 | ----------- | -------------------------------- | ----------------------------------------------- |
 | `userIds`   | comma-separated integers `12,45` | keep only entries whose `user_id` is in the list |
+| `operations` | comma-separated, from `create`, `update`, `delete`, `action`, `action_failed` | keep only entries recorded under one of them |
 | `startDate` | `YYYY-MM-DD` or datetime (incl.) | keep entries from this lower bound onward       |
 | `endDate`   | `YYYY-MM-DD` or datetime (incl.) | keep entries up to this upper bound             |
 | `fields`    | comma-separated field names      | keep only entries whose diff touched one of them |
@@ -164,7 +166,9 @@ happens in SQL. Two shapes are accepted:
 
 Both bounds are **inclusive**. Defensive parsing: non-numeric `userIds` tokens are dropped
 (`12,abc,45` → `12,45`), and a `startDate` / `endDate` matching no accepted format returns **HTTP
-400** (`ValidationError`); an invalid `timezone` likewise returns **400**.
+400** (`ValidationError`); an invalid `timezone` likewise returns **400**. An unrecognized
+`operations` value returns **400** rather than being dropped: a silently ignored filter would hand back
+unfiltered rows into a list the caller believes is filtered.
 
 Pagination follows JSON:API: `page[number]` is 1-based (default `1`), `page[size]` defaults to `20`
 and is capped at `100`; out-of-bound or non-numeric values fall back to the defaults rather than
@@ -180,21 +184,10 @@ the merge tiebreaker.
 Inside the value objects: a record's column names pass through untouched, while an action answer's keys are
 Forest's own and so are camelCase (`mimeType`, not `mime_type`) — the agent transforms them on write.
 
-**A record that was renamed keeps one timeline** — on this agent. The Node agent files an update under the
-record's new id too, but has no `previous_record_id` and so cannot walk back past the rename: the same record
-shows a complete chain here and a history beginning at the rename there, until that column is ported.
- An update that moves a writable primary key files its row
-under the record's new id — the id later lookups use — and remembers the one it left. Both the history and the
-state routes walk that back, so asking for the current id returns everything the record has ever been filed
-under, rather than starting the story at the rename.
-
-Each earlier id counts only **up to the moment it was left**, because a primary key a record abandons can be
-taken by another record afterwards, and those rows are none of this record's business. What the trail cannot
-separate is the opposite case: rows written under an id *before* the record that holds it now arrived — a
-reused key, or a delete followed by a recreate — since the packed id is the only identity the trail has. That
-is deliberate for delete/recreate (the state reconstruction walks into an earlier life on purpose) and the
-same limitation for a reused key. Telling those apart needs a lineage of its own on every row, which is a
-bigger change than this one.
+**A record whose primary key moved starts its history at the move**, as on the Node agent. An update that
+moves a writable primary key files its row under the record's new id, and the rows written before stay under
+the id they were true of; the history and state routes read the requested id only. Migration `002` drops the
+`previous_record_id` column an earlier version kept for this.
 
 A record that no longer exists keeps its history: only a record that still exists *outside* the
 caller's permission scope is refused (404). Inspecting what was deleted is much of the point of an
@@ -213,10 +206,11 @@ are withheld: `nil` there is a missing answer, not a passing one, and a redacted
 Primary keys are the exception: the packed id fills in whatever the snapshot cannot answer — a read-only key
 it never captured, or a writable one the trail redacts — so a scope on the id still matches the record it
 belongs to. It fills in only what is missing: where a side captured the key itself, that value is the one
-that was true there. Each side of an update is read against the id it was filed under, the row's own id and,
-for the previous side of an update that moved the key, the id it moved from. A `pending` row is filed under
-the id the record had *before* the write, which may not have landed, so its new side is given no id to fill
-from and answers with what it captured or not at all.
+that was true there. The row's id answers only for the side it was filed under, as on the Node agent: a
+create, a delete, an update's new side. On an update's previous side it fills a key never captured (read-only,
+so it cannot have moved) but not a redacted one (writable, so it may have), and that side is withheld from a
+scope on a redacted key. A `pending` row is filed under the id the record had *before* the write, which may
+not have landed, so its new side is given no id to fill from and answers with what it captured or not at all.
 
 Neither failure this can meet is fatal, and each costs only what it actually broke. An id that stopped
 decoding when the primary key changed shape costs the keys it would have filled and nothing more, so a scope
@@ -246,9 +240,17 @@ read it, that is a **404**, the same as for a request starting a moment later; i
 life's values stay withheld all the same. The second read is skipped when no scope is in effect, and on the
 correlation routes when the answer holds no rows.
 
-Where the delete and the recreation both happened *before* the request, both reads see the live record and
-its history is served whole, earlier lives included — the documented delete/recreate behaviour, and a
-separate question from the one above.
+**An id freed and taken since has two lives.** Where the delete and the recreation both happened *before*
+the request, both reads see the live record, and a live record in the caller's scope says nothing about the
+rows filed under its id before it took the id: they are an earlier record's. The boundary is the id's latest
+confirmed `delete` (the earlier record's last row) or `create` (the current record's first), whichever is
+later; the `create` covers an id freed with no confirmed `delete`, by a primary-key move or a delete that was
+never confirmed. A `pending` row marks no boundary, since it may never have landed. The rows before the
+boundary go through the same withholding as a record gone for good — on the history route (with `search` and
+`fields` matched against the served values, so the count and the authors cannot leak them either), on the
+correlation routes, and on `/state`, whose reconstruction at an instant **strictly before** the boundary is
+tested against the scope: at the boundary's own instant the state already includes a replacement `create`
+sharing it. The lookup runs only for a scoped caller on a live record. Same rule as the Node agent.
 
 **Every route that serves captured values applies this**, since a rule only one of them applies is one
 lookup away from being no rule at all. The two correlation routes withhold row by row exactly as the history
@@ -278,6 +280,34 @@ Walking back stops being able to help where the trail stops: only audited (writa
 reconstructed, and a `create` means the record did not exist before it, while a `delete` restores the whole
 row it recorded and the walk carries on into any earlier life of the same id.
 
+### Timeline route
+
+`GET /forest/_audit-trail` is the project-level timeline: the audit rows of every collection the caller can
+read, in one walk, for the project's Activity Logs page. It mirrors the Node agent's route, and the capability
+payload announces it as `canUseAuditTrailTimeline` and `canSortAuditTrailTimeline`, both true wherever the
+trail is configured.
+
+```json
+{ "data": [...], "meta": { "cursor": { "before": "2026-01-02T03:04:05.000Z", "excludeIds": [42] },
+                           "availableUsers": [...] } }
+```
+
+- Values follow the per-record history's rule: a caller who can read a collection reads its rows' values,
+  whatever their permission level. Who may open the page at all is the team's Activity Logs setting, enforced
+  by Forest, not by the agent.
+- A collection the caller sees only through a record-level scope is left out entirely: a scope cannot be
+  evaluated across the whole timeline, and a row alone would say that a record they cannot read was touched.
+- `sort=timestamp` walks oldest first; anything else newest first. Ties follow `id` in the same direction.
+- Paged by cursor, not page number, since the front merges this walk with the activity logs and no count spans
+  both. `before` (newest first) or `after` (oldest first) is an **inclusive** ISO instant, and `excludeIds`
+  drops the rows already served at it; the other direction's bound is ignored, and a bound that is not an ISO
+  instant is a **400**. The bound and the date filter on its side combine, the tighter winning. `meta.cursor`
+  is `null` on the last page, and when the walk would not progress.
+- `page[size]` as on the history route. `userIds`, `operations`, `startDate`, `endDate`, `timezone` and
+  `search` as on the history route; no `fields`, since a column name means nothing across collections.
+- `meta.availableUsers` on the first page only (neither `before` nor `after`): the distinct authors the
+  filters match across the readable collections. Later pages omit the key.
+
 ### Correlation route
 
 `GET /forest/_audit-trail/correlation/{correlationKey}` returns `{ "data": [...] }` — the
@@ -370,7 +400,6 @@ one table nobody deletes from.
 | `operation`       | `create` / `update` / `delete`                              |
 | `collection`      | audited collection name                                     |
 | `record_id`       | packed record id (primary keys joined by `\|`), TEXT and nullable — a create's pending row has none yet, and a composite id outgrows a varchar |
-| `previous_record_id` | set only on an update that moved a writable primary key: the id the row was filed under before |
 | `user_id`         | the Forest user who made the change                         |
 | `user_first_name`, `user_last_name`, `user_email` | denormalised from the caller at write time: who acted then, not whoever holds that id today |
 | `action_name`     | smart-action rows only                                       |

data/forest_admin_agent.gemspec

@@ -33,6 +33,7 @@ admin work on any Ruby application."
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "activerecord", ">= 6.1"
   spec.add_dependency "activesupport", ">= 6.1"
   spec.add_dependency "base64"
   spec.add_dependency "benchmark"
@@ -52,6 +53,7 @@ admin work on any Ruby application."
   spec.add_dependency "ld-eventsource", "~> 2.2"
   spec.add_dependency "mono_logger", "~> 1.1"
   spec.add_dependency "openid_connect", "~> 2.2"
+  spec.add_dependency "pg", "~> 1.1"
   spec.add_dependency "rake", "~> 13.0"
   spec.add_dependency "rack-cors", "~> 3.0"
   spec.add_dependency "zeitwerk", "~> 2.3"

data/lib/forest_admin_agent/audit_trail/audit_record.rb

@@ -7,7 +7,7 @@ module ForestAdminAgent
     # follows the write protocol — inserted as {Recording::PENDING} before the write and confirmed
     # {Recording::DONE} after, so a row left pending means the write may or may not have landed.
     AuditRecord = Struct.new(
-      :id, :timestamp, :operation, :collection, :record_id, :previous_record_id, :status,
+      :id, :timestamp, :operation, :collection, :record_id, :status,
       :user_id, :user_first_name, :user_last_name, :user_email, :action_name,
       :correlation_key, :previous_values, :new_values,
       keyword_init: true

data/lib/forest_admin_agent/audit_trail/capture.rb

@@ -136,14 +136,8 @@ module ForestAdminAgent
           if delta[:new_values].empty?
             empty << pending[:ids][index]
           else
-            before_id = record_id(record, pks)
-            after_id = record_id(after, pks)
-
             confirm(pending[:ids][index],
-                    record_id: after_id,
-                    # Only when the key actually moved, so a history query can walk back to the rows filed
-                    # under the id this record used to have.
-                    previous_record_id: after_id == before_id ? nil : before_id,
+                    record_id: record_id(after, pks),
                     previous_values: redacted(target[:name], delta[:previous_values]),
                     new_values: redacted(target[:name], delta[:new_values]))
           end

data/lib/forest_admin_agent/audit_trail/sql/audit_connection_base.rb

@@ -1,8 +1,4 @@
-begin
-  require 'active_record'
-rescue LoadError
-  raise LoadError, 'config.audit_trail needs the activerecord gem: add `gem "activerecord"` to your Gemfile.'
-end
+require 'active_record'
 
 module ForestAdminAgent
   module AuditTrail

data/lib/forest_admin_agent/audit_trail/sql/migrations.rb

@@ -1,10 +1,9 @@
 module ForestAdminAgent
   module AuditTrail
     module Sql
-      # The audit table's schema, as an ordered, append-only list. Nothing has shipped yet, so this is still a
-      # single entry; once a release is out, never edit one — add another, since a database out there has
-      # already recorded the earlier ones as applied. Every statement tolerates being replayed
-      # (`if_not_exists`), which is what makes a lost race harmless.
+      # The audit table's schema, as an ordered, append-only list. Never edit a released entry — add another,
+      # since a database out there has already recorded the earlier ones as applied. Every statement tolerates
+      # being replayed (`if_not_exists` / `if_exists`), which is what makes a lost race harmless.
       module Migrations
         ALL = [
           {
@@ -26,8 +25,7 @@ module ForestAdminAgent
                 t.text :user_first_name
                 t.text :user_last_name
                 t.text :user_email
-                # Set only on an update that moved a writable primary key: the id the row was filed under
-                # before. What lets a history query follow a record across a rename.
+                # Dropped by 002.
                 t.text :previous_record_id
                 # Smart-action rows only.
                 t.text :action_name
@@ -45,6 +43,25 @@ module ForestAdminAgent
               connection.add_index(table, :correlation_key, name: "#{base}_correlation_key", if_not_exists: true)
               connection.add_index(table, :user_id, name: "#{base}_user_id", if_not_exists: true)
             end
+          },
+          {
+            # The agent no longer follows a record across a primary-key move, so nothing writes or reads the
+            # column. No released version wrote it to a row a client relies on.
+            name: '002-drop-previous-record-id',
+            up: lambda do |connection, table|
+              # Checked first as well: older ActiveRecord versions accept `if_exists` here but ignore it.
+              next unless connection.column_exists?(table, :previous_record_id)
+
+              connection.remove_column(table, :previous_record_id, if_exists: true)
+            end
+          },
+          {
+            # The timeline pages the whole table in (timestamp, id) order, which no other index serves.
+            name: '003-index-timestamp-id',
+            up: lambda do |connection, table|
+              connection.add_index(table, %i[timestamp id], name: "#{table.split(".").last}_timestamp_id",
+                                                            if_not_exists: true)
+            end
           }
         ].freeze
       end

data/lib/forest_admin_agent/audit_trail/store.rb

@@ -11,7 +11,7 @@ module ForestAdminAgent
     class Store
       DEFAULT_SCHEMA = 'forest'.freeze
       DEFAULT_TABLE = 'audit_logs'.freeze
-      COLUMNS = %i[timestamp operation collection record_id previous_record_id status user_id user_first_name
+      COLUMNS = %i[timestamp operation collection record_id status user_id user_first_name
                    user_last_name user_email action_name correlation_key previous_values new_values].freeze
       AUTHOR_COLUMNS = %i[user_id user_first_name user_last_name user_email].freeze
 
@@ -73,13 +73,14 @@ module ForestAdminAgent
         model.where(id: ids).delete_all unless ids.empty?
       end
 
-      def list_by_record(collection:, record_id:, skip: 0, limit: nil, user_ids: nil, start_timestamp: nil,
-                         end_timestamp: nil, fields: nil, search: nil, order: 'asc', after: nil)
+      def list_by_record(collection:, record_id:, skip: 0, limit: nil, user_ids: nil, operations: nil,
+                         start_timestamp: nil, end_timestamp: nil, fields: nil, search: nil, order: 'asc', after: nil)
         descending = order.to_s == 'desc'
         # `id` (insertion order) breaks ties on equal timestamps in both directions, keeping pages
         # deterministic and stable.
-        relation = scope(collection, record_id, user_ids: user_ids, start_timestamp: start_timestamp,
-                                                end_timestamp: end_timestamp, fields: fields, search: search)
+        relation = scope(collection, record_id, user_ids: user_ids, operations: operations,
+                                                start_timestamp: start_timestamp, end_timestamp: end_timestamp,
+                                                fields: fields, search: search)
                    .order(timestamp: descending ? :desc : :asc, id: :asc)
                    .offset(skip || 0)
         relation = relation.where(*past_row_condition(after, descending)) if after
@@ -88,42 +89,52 @@ module ForestAdminAgent
         relation.map { |row| from_row(row) }
       end
 
-      def count_by_record(collection:, record_id:, user_ids: nil, start_timestamp: nil,
+      def count_by_record(collection:, record_id:, user_ids: nil, operations: nil, start_timestamp: nil,
                           end_timestamp: nil, fields: nil, search: nil)
-        scope(collection, record_id, user_ids: user_ids, start_timestamp: start_timestamp,
+        scope(collection, record_id, user_ids: user_ids, operations: operations, start_timestamp: start_timestamp,
                                      end_timestamp: end_timestamp, fields: fields, search: search).count
       end
 
       # The distinct authors of the entries the current filters match, whatever page is being asked for. The
       # identity comes from the rows themselves, so a user who has since been renamed or removed still reads
       # as they were when they acted.
-      def authors_by_record(collection:, record_id:, user_ids: nil, start_timestamp: nil,
+      def authors_by_record(collection:, record_id:, user_ids: nil, operations: nil, start_timestamp: nil,
                             end_timestamp: nil, fields: nil, search: nil)
-        scope(collection, record_id, user_ids: user_ids, start_timestamp: start_timestamp,
-                                     end_timestamp: end_timestamp, fields: fields, search: search)
-          .where.not(user_id: nil)
-          .distinct
-          .pluck(*AUTHOR_COLUMNS)
-          .map { |values| AUTHOR_COLUMNS.zip(values).to_h }
-          .uniq { |author| author[:user_id] }
+        authors(scope(collection, record_id, user_ids: user_ids, operations: operations,
+                                             start_timestamp: start_timestamp, end_timestamp: end_timestamp,
+                                             fields: fields, search: search))
       end
 
-      # The ids this record was renamed from, each with the moment it stopped being that id. Walking those back
-      # is what lets a history query reach rows written before a rename — they stay under the id they were
-      # written with, since that is the id they were true of — and the moment bounds how far: the id it left may
-      # have been taken by another record afterwards, whose rows are none of this record's business.
-      def renamed_from(collection:, record_id:)
-        model.where(collection: collection, record_id: record_id)
-             .where.not(previous_record_id: nil)
-             .pluck(:previous_record_id, :timestamp, :id)
-             .group_by(&:first)
-             .map do |id, rows|
-               # The row id comes along as the tie-breaker: the trail orders itself by (timestamp, id), so a
-               # bound that knew only the timestamp would mean something slightly different from "before".
-               _, at, row = rows.max_by { |(_, timestamp, row_id)| [timestamp, row_id] }
-
-               { id: id, until: as_iso(at), until_row: row }
-             end
+      # The project-level timeline across `collections`, the ones the caller may read: newest first, or oldest
+      # first with `order: 'asc'`, ties broken by id in the same direction. `before` / `after` are the cursor's
+      # inclusive bound and `exclude_ids` the rows already served at it.
+      def list_timeline(collections:, limit:, order: 'desc', **filters)
+        return [] if collections.empty?
+
+        direction = order.to_s == 'asc' ? :asc : :desc
+
+        timeline_scope(collections, **filters).order(timestamp: direction, id: direction).limit(limit)
+                                              .map { |row| from_row(row) }
+      end
+
+      # The distinct authors of the timeline the filters match, whatever the cursor.
+      def timeline_users(collections:, **filters)
+        return [] if collections.empty?
+
+        authors(timeline_scope(collections, **filters))
+      end
+
+      # The id's latest confirmed `delete` or `create`, in the trail's (timestamp, id) order: where the life of
+      # the record holding the id now began. A pending row may never have landed, so it marks nothing. Nil when
+      # the id has had one life only — no boundary at all, or a `create` with nothing filed before it — so a
+      # record created through Forest does not pay for the earlier-life withholding it can never need.
+      def life_boundary_of(collection:, record_id:)
+        rows = model.where(collection: collection, record_id: record_id)
+        row = rows.where(operation: %w[delete create], status: Recording::DONE).order(timestamp: :desc, id: :desc).first
+        return nil if row.nil?
+        return nil if row.operation == 'create' && !rows.where(*before_row_condition(row)).exists?
+
+        from_row(row)
       end
 
       # Entries recorded strictly after `timestamp`, newest first: what a state reconstruction has to undo.
@@ -135,7 +146,7 @@ module ForestAdminAgent
       # cannot act on them.
       def list_since(collection:, record_id:, timestamp:)
         model.where(collection: collection, status: Recording::DONE)
-             .where(*segments_condition(record_id))
+             .where(record_id: record_id)
              .where('timestamp > ?', as_time(timestamp))
              .order(timestamp: :desc, id: :desc)
              .map { |row| from_row(row) }
@@ -155,12 +166,28 @@ module ForestAdminAgent
 
       private
 
-      # Every filter is an AND, so the count matches exactly what a page of this history holds.
-      def scope(collection, record_id, user_ids: nil, start_timestamp: nil, end_timestamp: nil,
-                fields: nil, search: nil)
-        relation = model.where(collection: collection).where(*segments_condition(record_id))
-        relation = relation.where(user_id: user_ids) if user_ids
+      def scope(collection, record_id, fields: nil, **filters)
+        relation = filtered(model.where(collection: collection, record_id: record_id), **filters)
         relation = relation.where(Sql::FieldFilter.new(model.connection).condition(fields)) if fields&.any?
+        relation
+      end
+
+      # Each cursor bound and the date filter on its side are both inclusive, so the tighter one wins.
+      def timeline_scope(collections, before: nil, after: nil, exclude_ids: nil, start_timestamp: nil,
+                         end_timestamp: nil, **filters)
+        relation = filtered(model.where(collection: collections),
+                            start_timestamp: [start_timestamp, after].compact.max_by { |bound| as_time(bound) },
+                            end_timestamp: [end_timestamp, before].compact.min_by { |bound| as_time(bound) },
+                            **filters)
+        relation = relation.where.not(id: exclude_ids) if exclude_ids&.any?
+        relation
+      end
+
+      # The filters the per-record history and the timeline share, so they cannot drift apart. Every one is an
+      # AND, so the count matches exactly what a page holds.
+      def filtered(relation, user_ids: nil, operations: nil, search: nil, start_timestamp: nil, end_timestamp: nil)
+        relation = relation.where(user_id: user_ids) if user_ids
+        relation = relation.where(operation: operations) if operations
         relation = relation.where(Sql::TextSearch.new(model.connection).condition(search)) if search
         # Compare as Time so ActiveRecord casts the bound to the datetime column's storage format
         # (raw ISO strings with a `Z` would compare lexically against the cast rows and never match).
@@ -169,6 +196,21 @@ module ForestAdminAgent
         relation
       end
 
+      def authors(relation)
+        relation.where.not(user_id: nil)
+                .distinct
+                .pluck(*AUTHOR_COLUMNS)
+                .map { |values| AUTHOR_COLUMNS.zip(values).to_h }
+                .uniq { |author| author[:user_id] }
+      end
+
+      # Rows strictly before `row` in the trail's (timestamp, id) order.
+      def before_row_condition(row)
+        at = as_time(row.timestamp)
+
+        ['timestamp < ? OR (timestamp = ? AND id < ?)', at, at, row.id]
+      end
+
       # Rows strictly past `row` in the history's own order, so a scan keyed on the last row it read neither
       # repeats nor skips one when entries are written between its reads, as an offset would.
       def past_row_condition(row, descending)
@@ -182,34 +224,6 @@ module ForestAdminAgent
         value.is_a?(::Time) ? value : ::Time.iso8601(value.to_s)
       end
 
-      def as_iso(value)
-        value.respond_to?(:iso8601) ? value.iso8601(3) : value.to_s
-      end
-
-      # One record's history is its current id plus every id it was renamed from, each earlier one only up to
-      # the rename: `record_id = '7' OR (record_id = '1' AND timestamp <= …)`. A plain `IN` would hand over the
-      # rows of whichever record holds that id now.
-      #
-      # Takes an id, several, or segments — `{ id:, until: }` — so a caller that has no rename to care about
-      # simply passes the id.
-      def segments_condition(record_id)
-        binds = []
-        sql = Array(record_id).map { |value| value.is_a?(Hash) ? value : { id: value, until: nil } }.map do |segment|
-          binds << segment[:id]
-          next 'record_id = ?' unless segment[:until]
-
-          binds << as_time(segment[:until])
-          # Same millisecond as the rename, and the id says which side of it a row falls on: another record
-          # taking the abandoned key that fast would otherwise land in this record's history.
-          next '(record_id = ? AND timestamp <= ?)' unless segment[:until_row]
-
-          binds << as_time(segment[:until]) << segment[:until_row]
-          '(record_id = ? AND (timestamp < ? OR (timestamp = ? AND id <= ?)))'
-        end
-
-        [sql.join(' OR '), *binds]
-      end
-
       def model
         ensure_ready
         @model

data/lib/forest_admin_agent/http/router.rb

@@ -50,12 +50,14 @@ module ForestAdminAgent
           { name: 'charts', handler: -> { Charts::Charts.new.routes } },
           { name: 'collections', handler: -> { Capabilities::Collections.new.routes } },
           { name: 'native_query', handler: -> { Resources::NativeQuery.new.routes } },
-          # Both must come before the routes matching on `:collection_name`: Rails matches in
+          # All three must come before the routes matching on `:collection_name`: Rails matches in
           # definition order, so `/_audit-trail/correlations` would otherwise be read as
-          # `/:collection_name/:id` and 404 on a collection named `_audit-trail`. Correlation first, so
+          # `/:collection_name/:id`, and the timeline's `/_audit-trail` as `/:collection_name`, and both 404 on a
+          # collection named `_audit-trail`. Correlation first, so
           # `/_audit-trail/correlations` wins over the per-record `/_audit-trail/:collection_name/:id`.
           { name: 'audit_trail_correlation', handler: -> { Resources::AuditTrailCorrelation.new.routes } },
           { name: 'audit_trail', handler: -> { Resources::AuditTrail.new.routes } },
+          { name: 'audit_trail_timeline', handler: -> { Resources::AuditTrailTimeline.new.routes } },
           { name: 'count', handler: -> { Resources::Count.new.routes } },
           { name: 'delete', handler: -> { Resources::Delete.new.routes } },
           { name: 'csv', handler: -> { Resources::Csv.new.routes } },

data/lib/forest_admin_agent/routes/capabilities/collections.rb

@@ -69,6 +69,10 @@ module ForestAdminAgent
                 canUseProjectionViaHeaderOnList: true,
                 canUseMultipleFieldsProjectionOnRelation: true,
                 canUseAuditTrail: audit_trail_enabled?,
+                # The store always lists the timeline, both ways, so the cross-collection route is mounted
+                # wherever the trail is.
+                canUseAuditTrailTimeline: audit_trail_enabled?,
+                canSortAuditTrailTimeline: audit_trail_enabled?,
                 checksRelationReadPermissions: !skip_relation_read_permissions?
               }
             },

data/lib/forest_admin_agent/routes/resources/audit_trail.rb

@@ -10,13 +10,9 @@ module ForestAdminAgent
       class AuditTrail < AbstractAuthenticatedRoute
         include ForestAdminAgent::Utils
         include AuditTrailRoute
+        include AuditTrailQueryParams
 
-        DEFAULT_PAGE_SIZE = 20
-        MAX_PAGE_SIZE = 100
         SCAN_BATCH_SIZE = 500
-        DATE_ONLY = /\A\d{4}-\d{2}-\d{2}\z/
-        # Wall-clock datetime, `T` or space separator, seconds optional: `YYYY-MM-DD[T ]HH:mm[:ss]`.
-        DATE_TIME = /\A(\d{4}-\d{2}-\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?\z/
 
         def setup_routes
           return self unless store
@@ -46,9 +42,8 @@ module ForestAdminAgent
 
           filters = {
             collection: context.collection.name,
-            # args[:params]['id'] is already Forest's packed id, the form the audit store keys on — plus any id
-            # this record was filed under before a rename, each bounded by when it stopped being that id.
-            record_id: record_segments(context.collection, args[:params]['id']),
+            # Already Forest's packed id, the form the audit store keys on.
+            record_id: args[:params]['id'],
             **parse_filters(args)
           }
 
@@ -81,7 +76,7 @@ module ForestAdminAgent
           timestamp = parse_state_timestamp(args)
           entries = store.list_since(
             collection: context.collection.name,
-            record_id: record_segments(context.collection, args[:params]['id']),
+            record_id: args[:params]['id'],
             timestamp: timestamp
           )
           # Fully qualified: inside this class, `AuditTrail` is the route itself.
@@ -89,15 +84,24 @@ module ForestAdminAgent
           # Asked again now, for the same reason the history route asks, and the same way: the record read
           # above can be deleted — or an id that was gone then be taken by somebody else's record — while the
           # audit read is in flight.
-          withholding_scope = withholding_scope_for(context, context.collection, args[:params]['id'],
-                                                    gone_at_check)
+          withholding = withholding_of(context, context.collection, args[:params]['id'], gone_at_check)
 
           { name: args[:params]['collection_name'],
-            content: { data: answerable_state(state, withholding_scope, context, args[:params]['id']) } }
+            content: { data: answerable_state(state, state_scope(withholding, timestamp), context,
+                                              args[:params]['id']) } }
         end
 
         private
 
+        # The whole reconstruction belongs to an earlier record when it stands strictly before the boundary. At
+        # the boundary's own instant it already reflects every row there, a replacement `create` sharing it
+        # included, so it is the current record's.
+        def state_scope(withholding, timestamp)
+          return withholding.scope if withholding.boundary.nil?
+
+          withholding.scope if ::Time.iso8601(timestamp) < ::Time.iso8601(withholding.boundary.timestamp.to_s)
+        end
+
         # The history route withholds a gone record's captured values from a caller whose scope they fail, and
         # this route is nothing but those values reassembled: without the same test they come back one request
         # away. A reconstruction the scope cannot answer withholds too — absent is not the same as passing.
@@ -125,11 +129,6 @@ module ForestAdminAgent
           (page.is_a?(Hash) ? page['number'].to_i : 0) <= 1
         end
 
-        def available_user(author)
-          { id: author[:user_id], firstName: author[:user_first_name],
-            lastName: author[:user_last_name], email: author[:user_email] }
-        end
-
         def history_matched_in_store(context, args, filters, gone_at_check)
           skip, limit = parse_pagination(args)
           history = store.list_by_record(**filters, skip: skip, limit: limit, order: parse_sort(args))
@@ -137,8 +136,8 @@ module ForestAdminAgent
           count = store.count_by_record(**filters)
           withholding = withholding_for(context, args, gone_at_check)
 
-          # Gone between the check and the read: this answer withholds, so the rows, count and authors matched
-          # in SQL above must not decide what is served either.
+          # Gone between the check and the read, or carrying an earlier record's rows: this answer withholds, so
+          # the rows, count and authors matched in SQL above must not decide what is served either.
           if withholding.scope && filters.slice(:search, :fields).any?
             return history_matched_after_withholding(context, args, filters, gone_at_check, withholding)
           end
@@ -149,7 +148,8 @@ module ForestAdminAgent
         # Matched in SQL, `search` and `fields` would test the values as captured, so which rows come back, the
         # count and the authors would still say what the withholding hides — one probe per character. They are
         # matched against what is served instead, which means scanning the whole history here, in batches, so
-        # only the page asked for is kept. Only for a gone record: one in scope was the caller's to read whole.
+        # only the page asked for is kept. Whenever a withholding scope applies: a gone record, or the rows an earlier
+        # record filed under a live one's id. Otherwise the history was the caller's to read whole.
         def history_matched_after_withholding(context, args, filters, gone_at_check, withholding = nil)
           skip, limit = parse_pagination(args)
           value_filters = filters.slice(:search, :fields)
@@ -192,10 +192,7 @@ module ForestAdminAgent
         # Asked again now, because the check above ran before these rows were read: a record deleted in
         # between answered "present and in scope" for rows that already carry its delete.
         def withholding_for(context, args, gone_at_check)
-          withholding_scope = withholding_scope_for(context, context.collection, args[:params]['id'],
-                                                    gone_at_check)
-
-          Withholding.new(context.collection, withholding_scope, context.caller.timezone)
+          withholding_of(context, context.collection, args[:params]['id'], gone_at_check)
         end
 
         def matches_value_filters?(entry, search: nil, fields: nil)
@@ -256,105 +253,15 @@ module ForestAdminAgent
           args.dig(:params, 'sort').to_s == 'timestamp' ? 'asc' : 'desc'
         end
 
-        # JSON:API pagination: 1-based page[number] (default 1) and page[size] (default 20, capped at
-        # 100). Out-of-bound or non-numeric values fall back to the defaults rather than erroring.
+        # JSON:API pagination: 1-based page[number] (default 1) and page[size]. Out-of-bound or non-numeric
+        # values fall back to the defaults rather than erroring.
         def parse_pagination(args)
-          # `?page=foo` reaches us as a bare String, which `dig` refuses to walk into.
-          page = args.dig(:params, 'page')
-          page = {} unless page.is_a?(Hash)
-
-          size = page['size'].to_i
-          size = DEFAULT_PAGE_SIZE if size < 1
-          size = MAX_PAGE_SIZE if size > MAX_PAGE_SIZE
-
-          number = page['number'].to_i
+          size = parse_page_size(args)
+          number = page_param(args)['number'].to_i
           number = 1 if number < 1
 
           [(number - 1) * size, size]
         end
-
-        def request_timezone(args)
-          timezone = args.dig(:params, 'timezone').to_s
-
-          timezone.empty? ? 'UTC' : timezone
-        end
-
-        def parse_filters(args)
-          timezone = request_timezone(args)
-
-          {
-            user_ids: parse_user_ids(args.dig(:params, 'userIds')),
-            fields: parse_fields(args.dig(:params, 'fields')),
-            search: parse_search(args.dig(:params, 'search')),
-            start_timestamp: parse_date_boundary(args.dig(:params, 'startDate'), timezone, :start),
-            end_timestamp: parse_date_boundary(args.dig(:params, 'endDate'), timezone, :end)
-          }.compact
-        end
-
-        # Free text, trimmed; blank means no filter rather than a term that matches everything.
-        def parse_search(raw)
-          term = raw.to_s.strip
-
-          term.empty? ? nil : term
-        end
-
-        # Comma-separated field names, kept verbatim (a name may hold a dot). Empty after parsing → no filter.
-        def parse_fields(raw)
-          return nil if raw.nil?
-
-          names = (raw.is_a?(Array) ? raw : raw.to_s.split(',')).map { |name| name.to_s.strip }.reject(&:empty?)
-          names.empty? ? nil : names
-        end
-
-        # Comma-separated integer ids; non-numeric tokens are dropped. Empty after parsing → no filter.
-        def parse_user_ids(raw)
-          return nil if raw.nil? || raw.to_s.empty?
-
-          ids = raw.to_s.split(',').map(&:strip).grep(/\A\d+\z/).map(&:to_i)
-          ids.empty? ? nil : ids
-        end
-
-        # `startDate`/`endDate` accept a bare day (`YYYY-MM-DD`) or a wall-clock datetime
-        # (`YYYY-MM-DD[T ]HH:mm[:ss]`), read as local time in the request timezone and returned as a UTC
-        # ISO instant the store can compare against stored timestamps.
-        def parse_date_boundary(raw, timezone, boundary)
-          return nil if raw.nil? || raw.to_s.empty?
-
-          zone = Time.find_zone(timezone)
-          raise Http::Exceptions::ValidationError, "Invalid timezone: \"#{timezone}\"" if zone.nil?
-
-          instant = begin
-            local_instant(zone, raw.to_s, boundary)
-          rescue ArgumentError
-            nil
-          end
-
-          if instant.nil?
-            raise Http::Exceptions::ValidationError,
-                  "Invalid date: \"#{raw}\" (expected YYYY-MM-DD or YYYY-MM-DDTHH:mm)"
-          end
-
-          instant.utc.iso8601(3)
-        end
-
-        def local_instant(zone, raw, boundary)
-          if DATE_ONLY.match?(raw)
-            day = zone.parse(raw)
-            # Bare day → start (00:00:00.000) or end (23:59:59.999) of that local day.
-            boundary == :end ? day.end_of_day : day.beginning_of_day
-          elsif (match = DATE_TIME.match(raw))
-            date, hours, minutes, seconds = match.captures
-            base = zone.parse("#{date}T#{hours}:#{minutes}")
-            if seconds
-              base.change(sec: seconds.to_i, usec: 0)
-            elsif boundary == :end
-              # Minutes-only end boundary stays inclusive to :59.999; start stays at :00.000.
-              base.change(sec: 59, usec: 999_000)
-            else
-              base
-            end
-          end
-        end
       end
     end
   end

data/lib/forest_admin_agent/routes/resources/audit_trail_correlation.rb

@@ -74,9 +74,7 @@ module ForestAdminAgent
           # An empty answer has nothing to withhold, so it does not earn a second read of the record.
           return history if history.empty?
 
-          scope = withholding_scope_for(context, collection, record_id, gone_at_check)
-
-          withhold_out_of_scope_values(history, Withholding.new(collection, scope, context.caller.timezone))
+          withhold_out_of_scope_values(history, withholding_of(context, collection, record_id, gone_at_check))
         end
 
         def assert_scope(args)

data/lib/forest_admin_agent/routes/resources/audit_trail_query_params.rb

@@ -0,0 +1,131 @@
+module ForestAdminAgent
+  module Routes
+    module Resources
+      # The query params every audit-trail listing reads the same way, the per-record history and the
+      # cross-collection timeline alike, so a filter cannot mean one thing on one route and another on the
+      # other. Mirrors the Node agent's `audit-trail/query-params.ts`.
+      module AuditTrailQueryParams
+        DEFAULT_PAGE_SIZE = 20
+        MAX_PAGE_SIZE = 100
+        DATE_ONLY = /\A\d{4}-\d{2}-\d{2}\z/
+        # Wall-clock datetime, `T` or space separator, seconds optional: `YYYY-MM-DD[T ]HH:mm[:ss]`.
+        DATE_TIME = /\A(\d{4}-\d{2}-\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?\z/
+        OPERATIONS = %w[create update delete action action_failed].freeze
+
+        private
+
+        # `?page=foo` reaches us as a bare String, which `dig` refuses to walk into.
+        def page_param(args)
+          page = args.dig(:params, 'page')
+
+          page.is_a?(Hash) ? page : {}
+        end
+
+        # page[size] defaults to 20 and is capped at 100.
+        def parse_page_size(args)
+          size = page_param(args)['size'].to_i
+
+          size < 1 ? DEFAULT_PAGE_SIZE : [size, MAX_PAGE_SIZE].min
+        end
+
+        def request_timezone(args)
+          timezone = args.dig(:params, 'timezone').to_s
+
+          timezone.empty? ? 'UTC' : timezone
+        end
+
+        def parse_filters(args)
+          timezone = request_timezone(args)
+
+          {
+            user_ids: parse_user_ids(args.dig(:params, 'userIds')),
+            operations: parse_operations(args.dig(:params, 'operations')),
+            fields: parse_fields(args.dig(:params, 'fields')),
+            search: parse_search(args.dig(:params, 'search')),
+            start_timestamp: parse_date_boundary(args.dig(:params, 'startDate'), timezone, :start),
+            end_timestamp: parse_date_boundary(args.dig(:params, 'endDate'), timezone, :end)
+          }.compact
+        end
+
+        # Free text, trimmed; blank means no filter rather than a term that matches everything.
+        def parse_search(raw)
+          term = raw.to_s.strip
+
+          term.empty? ? nil : term
+        end
+
+        # Comma-separated field names, kept verbatim (a name may hold a dot). Empty after parsing → no filter.
+        def parse_fields(raw)
+          return nil if raw.nil?
+
+          names = (raw.is_a?(Array) ? raw : raw.to_s.split(',')).map { |name| name.to_s.strip }.reject(&:empty?)
+          names.empty? ? nil : names
+        end
+
+        # Comma-separated, from a closed set. An unrecognized value is rejected rather than dropped: a silently
+        # ignored filter returns unfiltered rows into a list the caller believes is filtered.
+        def parse_operations(raw)
+          tokens = raw.to_s.split(',').map(&:strip).reject(&:empty?)
+          unknown = tokens.find { |token| !OPERATIONS.include?(token) }
+
+          if unknown
+            raise Http::Exceptions::ValidationError,
+                  "Invalid operation: \"#{unknown}\" (expected one of #{OPERATIONS.join(", ")})"
+          end
+
+          tokens.empty? ? nil : tokens
+        end
+
+        # Comma-separated integer ids; non-numeric tokens are dropped. Empty after parsing → no filter.
+        def parse_user_ids(raw)
+          return nil if raw.nil? || raw.to_s.empty?
+
+          ids = raw.to_s.split(',').map(&:strip).grep(/\A\d+\z/).map(&:to_i)
+          ids.empty? ? nil : ids
+        end
+
+        # `startDate`/`endDate` accept a bare day (`YYYY-MM-DD`) or a wall-clock datetime
+        # (`YYYY-MM-DD[T ]HH:mm[:ss]`), read as local time in the request timezone and returned as a UTC
+        # ISO instant the store can compare against stored timestamps.
+        def parse_date_boundary(raw, timezone, boundary)
+          return nil if raw.nil? || raw.to_s.empty?
+
+          zone = Time.find_zone(timezone)
+          raise Http::Exceptions::ValidationError, "Invalid timezone: \"#{timezone}\"" if zone.nil?
+
+          instant = begin
+            local_instant(zone, raw.to_s, boundary)
+          rescue ArgumentError
+            nil
+          end
+
+          if instant.nil?
+            raise Http::Exceptions::ValidationError,
+                  "Invalid date: \"#{raw}\" (expected YYYY-MM-DD or YYYY-MM-DDTHH:mm)"
+          end
+
+          instant.utc.iso8601(3)
+        end
+
+        def local_instant(zone, raw, boundary)
+          if DATE_ONLY.match?(raw)
+            day = zone.parse(raw)
+            # Bare day → start (00:00:00.000) or end (23:59:59.999) of that local day.
+            boundary == :end ? day.end_of_day : day.beginning_of_day
+          elsif (match = DATE_TIME.match(raw))
+            date, hours, minutes, seconds = match.captures
+            base = zone.parse("#{date}T#{hours}:#{minutes}")
+            if seconds
+              base.change(sec: seconds.to_i, usec: 0)
+            elsif boundary == :end
+              # Minutes-only end boundary stays inclusive to :59.999; start stays at :00.000.
+              base.change(sec: 59, usec: 999_000)
+            else
+              base
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_agent/routes/resources/audit_trail_route.rb

@@ -71,54 +71,31 @@ module ForestAdminAgent
         # merging pages ordered by (timestamp, id). Value hashes keep the keys they were stored with: a record's
         # own column names, or an action answer's camelCase Forest names.
         def serialize_record(record)
-          # `previous_record_id` stays out: it is how the agent follows a record across a rename, not something
-          # the payload contract carries.
-          record.to_h.except(:previous_record_id).transform_keys { |key| key.to_s.camelize(:lower) }
+          record.to_h.transform_keys { |key| key.to_s.camelize(:lower) }
         end
 
         def store
           ::ForestAdminAgent::AuditTrail.store
         end
 
-        # Every id this record has been filed under, each with the moment it stopped being that id. Rows
-        # written before an update moved a writable primary key stay under the id they were true of, so a
-        # history query that asked for the current id alone would start at the rename and call that the whole
-        # story — and one that asked for the bare ids would sweep up whatever record holds an abandoned id now.
-        #
-        # Breadth-first, and no depth limit: every hop adds an id not already seen and there are finitely many
-        # of those, so skipping what we hold is both the cycle guard and the terminator. A cap would have
-        # truncated a record renamed often enough, which reads exactly like missing history.
-        def record_segments(collection, packed_id)
-          segments = [{ id: packed_id, until: nil, until_row: nil }]
-          queue = segments.dup
-
-          until queue.empty?
-            segment = queue.shift
-
-            store.renamed_from(collection: collection.name, record_id: segment[:id]).each do |previous|
-              next if segments.any? { |seen| seen[:id] == previous[:id] }
-
-              # Bounded by its own rename and by everything walked through to reach it: an id abandoned twice
-              # only belongs to this record up to the earlier of them.
-              found = earlier_bound(previous, segment).merge(id: previous[:id])
-              segments << found
-              queue << found
-            end
-          end
-
-          segments
-        end
+        # How to withhold the rows served for this id. A record gone at either look has all its rows tested
+        # against the caller's scope. A live one in scope still has the rows filed before it took the id: a
+        # delete frees an id, and a confirmed `create` marks where a record took one freed without a confirmed
+        # delete — a primary-key move, or a delete that never confirmed. Those rows are another record's, which
+        # the current one's scope says nothing about.
+        def withholding_of(context, collection, packed_id, gone_at_check)
+          gone_scope = withholding_scope_for(context, collection, packed_id, gone_at_check)
+          return Withholding.new(collection, gone_scope, context.caller.timezone) if gone_scope
 
-        # Bounds compare as the trail orders, (timestamp, row id); nil is "no bound yet", which is later than
-        # any of them. Through `<=>`, since Array is not Comparable and `<=` on one raises.
-        def earlier_bound(one, other)
-          return other.slice(:until, :until_row) if one[:until].nil?
-          return one.slice(:until, :until_row) if other[:until].nil?
+          scope = context.permissions.get_scope(collection)
+          boundary = scope && store.life_boundary_of(collection: collection.name, record_id: packed_id)
 
-          pair = ->(bound) { [bound[:until], bound[:until_row].to_i] }
-          earlier = (pair[one] <=> pair[other]) <= 0 ? one : other
+          Withholding.new(collection, boundary && scope, context.caller.timezone, boundary)
+        end
 
-          earlier.slice(:until, :until_row)
+        def available_user(author)
+          { id: author[:user_id], firstName: author[:user_first_name],
+            lastName: author[:user_last_name], email: author[:user_email] }
         end
 
         # What the audit trail actually records: primary keys, so a state can be identified, plus the writable

data/lib/forest_admin_agent/routes/resources/audit_trail_timeline.rb

@@ -0,0 +1,96 @@
+module ForestAdminAgent
+  module Routes
+    module Resources
+      # The project-level timeline, mirroring the Node agent's `GET /_audit-trail`: every readable collection's
+      # audit rows in one walk, paged by an inclusive cursor rather than by page number, since the front merges
+      # it with the activity logs and no count spans both.
+      #
+      # Values are served as on the per-record history: a caller who can read a collection reads its rows'
+      # values. Who may open the project's Activity Logs page at all is Forest's to decide, not the agent's.
+      class AuditTrailTimeline < AbstractAuthenticatedRoute
+        include AuditTrailRoute
+        include AuditTrailQueryParams
+
+        def setup_routes
+          return self unless store
+
+          add_route('forest_audit_trail_timeline', 'get', '/_audit-trail', ->(args) { handle_request(args) })
+
+          self
+        end
+
+        def handle_request(args = {})
+          context = build(args)
+          order = args.dig(:params, 'sort').to_s == 'timestamp' ? 'asc' : 'desc'
+          limit = parse_page_size(args)
+          cursor = parse_cursor(args, order)
+          # Parsed before the permission sweep, so a malformed filter reads as a 400 whatever the caller may
+          # see. No `fields`: a column name means nothing across collections.
+          filters = parse_filters(args).except(:fields)
+          collections = readable_collections(context).map(&:name)
+
+          # One row over the page: the only way to know whether a further page exists without a count.
+          fetched = store.list_timeline(**filters, **cursor, order: order, collections: collections,
+                                                             limit: limit + 1)
+          page = fetched.first(limit)
+          meta = { cursor: fetched.size > limit ? next_cursor(page, cursor, order) : nil }
+          # Authors on the first page only, like the per-record route: they do not change along the walk, and
+          # later pages omit the key rather than send `[]`.
+          if cursor[:before].nil? && cursor[:after].nil?
+            meta[:availableUsers] = store.timeline_users(**filters, collections: collections)
+                                         .map { |author| available_user(author) }
+          end
+
+          { content: { data: page.map { |record| serialize_record(record) }, meta: meta } }
+        end
+
+        private
+
+        # A record-level scope cannot be evaluated across a whole timeline without fetching every record it
+        # mentions, so a collection the caller only sees through one is left out entirely rather than served
+        # unfiltered: the row alone would say that a record they cannot read exists and was touched.
+        def readable_collections(context)
+          context.permissions.allowed_collections(:read, context.datasource.collections.values)
+                 .select { |collection| context.permissions.get_scope(collection).nil? }
+        end
+
+        # `before` (`after` oldest first) is an inclusive bound, so the rows sharing the last row's timestamp are
+        # carried as `excludeIds` rather than skipped. When the previous page ended on the same timestamp its
+        # exclusions still apply, so a timestamp holding more rows than one page walks on instead of looping.
+        # Nil when the walk would not progress: staying on the same timestamp must exclude at least one more id.
+        def next_cursor(page, previous, order)
+          bound = order == 'asc' ? :after : :before
+          last = page.last
+          same_boundary = previous[bound] && same_instant?(previous[bound], last.timestamp)
+          carried = same_boundary ? previous[:exclude_ids] : []
+          tied = page.select { |row| same_instant?(row.timestamp, last.timestamp) }.map(&:id)
+          exclude_ids = (carried + tied).uniq
+
+          return nil if same_boundary && exclude_ids.size == carried.size
+
+          { bound => last.timestamp, excludeIds: exclude_ids }
+        end
+
+        def same_instant?(one, other)
+          Time.iso8601(one.to_s) == Time.iso8601(other.to_s)
+        end
+
+        # The bound is the timestamp of a row this route served, so it is an ISO instant; only the one for the
+        # walk's direction is read.
+        def parse_cursor(args, order)
+          bound = order == 'asc' ? :after : :before
+          raw = args.dig(:params, bound.to_s).to_s
+          exclude_ids = args.dig(:params, 'excludeIds').to_s.split(',').map(&:strip).grep(/\A\d+\z/).map(&:to_i)
+
+          { bound => raw.empty? ? nil : parse_instant(raw), exclude_ids: exclude_ids }
+        end
+
+        def parse_instant(raw)
+          Time.iso8601(raw).utc.iso8601(3)
+        rescue ArgumentError
+          raise Http::Exceptions::ValidationError, "Invalid cursor: \"#{raw}\" (expected an ISO 8601 instant)"
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_agent/routes/resources/audit_trail_withholding.rb

@@ -7,9 +7,10 @@ module ForestAdminAgent
       # since a rule only one of them applies is one lookup away from being no rule at all.
       module AuditTrailWithholding
         # Everything a withholding decision needs, and nothing a request context would drag along: the
-        # collection the rows belong to, the scope to test them against, and the timezone its date
-        # comparisons read in.
-        Withholding = Struct.new(:collection, :scope, :timezone)
+        # collection the rows belong to, the scope to test them against, the timezone its date comparisons read
+        # in, and — for a live record whose id another record held before — the row where its own life began,
+        # so only the rows before it are tested. No boundary means every row is.
+        Withholding = Struct.new(:collection, :scope, :timezone, :boundary)
 
         NULL_EXCLUDING_OPERATORS = [
           ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Operators::NOT_EQUAL,
@@ -24,7 +25,16 @@ module ForestAdminAgent
         def withhold_out_of_scope_values(entries, withholding)
           return entries if withholding.scope.nil?
 
-          entries.map { |entry| withhold(entry, withholding) }
+          entries.map { |entry| of_withheld_life?(entry, withholding.boundary) ? withhold(entry, withholding) : entry }
+        end
+
+        # A boundary `delete` is the earlier record's last row, a boundary `create` the current record's first.
+        def of_withheld_life?(entry, boundary)
+          return true if boundary.nil?
+          return boundary.operation == 'delete' if entry.id == boundary.id
+
+          ([::Time.iso8601(entry.timestamp.to_s), entry.id.to_i] <=>
+            [::Time.iso8601(boundary.timestamp.to_s), boundary.id.to_i]).negative?
         end
 
         def withhold(entry, withholding)
@@ -48,11 +58,15 @@ module ForestAdminAgent
         # separately releases the ones that can be proven in scope — "it used to be X" can't escape through a
         # row whose new value is out of scope, since that side is tested on its own.
         def withhold_each_side(entry, withholding)
-          # An update that moved a writable primary key files its row under the id the record ended up with,
-          # and keeps the one it had on `previous_record_id`. Each side is tested against the id it was true
-          # of, or the new state's id would decide whether the old state is in scope.
-          before = entry.previous_record_id || entry.record_id
-          kept = in_scope?(entry.previous_values, before, withholding) ? entry : blank(entry, :previous_values)
+          # The row is filed under the id the record ended up with, which says nothing about a writable key the
+          # update may have moved: on the previous side the id answers only for a key never captured, read-only
+          # and so unmoved. A redacted key stays unanswered, which over-withholds an update that kept its key —
+          # the safe side of a move the trail cannot see.
+          kept = if in_scope?(entry.previous_values, entry.record_id, withholding, id_answers_for_keys: false)
+                   entry
+                 else
+                   blank(entry, :previous_values)
+                 end
 
           in_scope?(kept.new_values, after_id(kept), withholding) ? kept : blank(kept, :new_values)
         end

data/lib/forest_admin_agent/services/permissions.rb

@@ -92,6 +92,20 @@ module ForestAdminAgent
         is_allowed
       end
 
+      # The collections the caller may perform +action+ on, without raising. A sweep over every collection
+      # meets a denial for most roles, so a denial is retried against fresh permissions only when
+      # {#refetch_denied_reads?} says staleness could explain it, and then once for all of them together.
+      def allowed_collections(action, collections)
+        return collections unless permission_system?
+
+        allowed = select_allowed(action, collections, reload: false)
+        return allowed if allowed.size == collections.size
+        return allowed unless refetch_denied_reads?(collections.map(&:name), get_collections_permissions_data)
+
+        @read_permissions_refetched = true
+        select_allowed(action, collections, reload: true)
+      end
+
       # +root_collection_name+ is pinned to readable and never looked up: +browse+ already gates a
       # listing, +read+ a get, and the signed hash a chart.
       #
@@ -456,6 +470,13 @@ module ForestAdminAgent
               'is not exposed by this agent.'
       end
 
+      def select_allowed(action, collections, reload:)
+        user_data = get_user_data(caller.id, reload: reload)
+        collections_data = get_collections_permissions_data(force_fetch: reload)
+
+        collections.select { |collection| permission_allowed?(collections_data, collection, action, user_data) }
+      end
+
       def permission_allowed?(collections_data, collection, action, user_data)
         return false unless user_data_valid?(user_data)
 

data/lib/forest_admin_agent/utils/schema/schema_emitter.rb

@@ -6,7 +6,7 @@ module ForestAdminAgent
     module Schema
       class SchemaEmitter
         LIANA_NAME = "agent-ruby"
-        LIANA_VERSION = "1.45.2"
+        LIANA_VERSION = "1.46.1"
 
         def self.generate(datasource)
           datasource.collections

data/lib/forest_admin_agent/version.rb

@@ -1,3 +1,3 @@
 module ForestAdminAgent
-  VERSION = "1.45.2"
+  VERSION = "1.46.1"
 end

data/lib/forest_admin_agent.rb

@@ -6,8 +6,8 @@ loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect('oauth2' => 'OAuth2')
 loader.inflector.inflect('sql' => 'Sql')
 loader.inflector.inflect('sse_cache_invalidation' => 'SSECacheInvalidation')
-# ActiveRecord is only needed by agents configuring an audit-trail database, and Rails eager loads
-# every gem loader (Zeitwerk::Loader.eager_load_all), so these files must stay strictly autoloaded.
+# Rails eager loads every gem loader (Zeitwerk::Loader.eager_load_all): kept autoloaded so ActiveRecord is only
+# required once an audit-trail database is configured.
 loader.do_not_eager_load("#{__dir__}/forest_admin_agent/audit_trail/sql")
 loader.setup
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forest_admin_agent
 version: !ruby/object:Gem::Version
-  version: 1.45.2
+  version: 1.46.1
 platform: ruby
 authors:
 - Matthieu
@@ -9,8 +9,22 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-14 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -277,6 +291,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -378,7 +406,9 @@ files:
 - lib/forest_admin_agent/routes/request_context.rb
 - lib/forest_admin_agent/routes/resources/audit_trail.rb
 - lib/forest_admin_agent/routes/resources/audit_trail_correlation.rb
+- lib/forest_admin_agent/routes/resources/audit_trail_query_params.rb
 - lib/forest_admin_agent/routes/resources/audit_trail_route.rb
+- lib/forest_admin_agent/routes/resources/audit_trail_timeline.rb
 - lib/forest_admin_agent/routes/resources/audit_trail_withholding.rb
 - lib/forest_admin_agent/routes/resources/count.rb
 - lib/forest_admin_agent/routes/resources/csv.rb