forest_admin_agent 1.38.2 → 1.39.0

data/lib/forest_admin_agent/http/correlation_id.rb

@@ -0,0 +1,37 @@
+require 'securerandom'
+
+module ForestAdminAgent
+  module Http
+    # Per-request correlation id, generated by the agent. Shared between the caller (so the audit
+    # trail can group every change made within one request) and the response header echoed back to
+    # the client. Mirrors the Node agent's `context.state.requestId` + `x-forest-correlation-id`
+    # header: the agent generates the id, never reads it from the incoming request.
+    #
+    # Stored thread-locally and generated lazily on first read (e.g. when the caller is parsed). The
+    # host resets it at the start of each request so a pooled thread never reuses a previous id.
+    module CorrelationId
+      HEADER = 'x-forest-correlation-id'.freeze
+      KEY = :forest_admin_correlation_id
+
+      module_function
+
+      # Lazily generate and memoize the id for the current request/thread.
+      def current
+        Thread.current[KEY] ||= SecureRandom.uuid
+      end
+
+      # The id if one was generated during this request, otherwise nil (does not generate one).
+      def current?
+        Thread.current[KEY]
+      end
+
+      def current=(value)
+        Thread.current[KEY] = value
+      end
+
+      def reset!
+        Thread.current[KEY] = nil
+      end
+    end
+  end
+end

data/lib/forest_admin_agent/http/correlation_id_middleware.rb

@@ -0,0 +1,29 @@
+module ForestAdminAgent
+  module Http
+    # Rack middleware echoing the agent-generated correlation id back to the client, mirroring the
+    # Node agent's `correlationIdMiddleware` (`router.use(...)`). Hosts mount it in their middleware
+    # stack; CORS exposure of the header is handled by the host's CORS config (see the Rails engine).
+    #
+    # The id itself is generated lazily by the agent during the request (see CorrelationId, called
+    # from CallerParser). This middleware only resets the thread-local around the request — so a
+    # pooled thread never reuses a previous id — and sets the response header when one was generated.
+    class CorrelationIdMiddleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        CorrelationId.reset!
+
+        status, headers, body = @app.call(env)
+
+        id = CorrelationId.current?
+        headers[CorrelationId::HEADER] = id if id
+
+        [status, headers, body]
+      ensure
+        CorrelationId.reset!
+      end
+    end
+  end
+end

data/lib/forest_admin_agent/http/router.rb

@@ -50,6 +50,12 @@ 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
+          # 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
+          # `/_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: '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/action/actions.rb

@@ -75,7 +75,7 @@ module ForestAdminAgent
             fields.reject { |field| field.type == 'Layout' }
           )
 
-          result = context.collection.execute(context.caller, @action_name, data, filter_for_caller)
+          result = execute_and_audit(context, args, data, filter_for_caller)
 
           { content: ForestAdminAgent::Utils::ActionResult.parse(result) }
         end
@@ -117,6 +117,81 @@ module ForestAdminAgent
 
         private
 
+        # Recorded as pending before the action runs and confirmed after, so an action that takes the process
+        # down with it still leaves evidence that it started. A failed run is worth recording too — "who tried
+        # to run this" is usually the interesting part — and an action answering with an Error result failed
+        # just as much as one that raised, it simply said so through `result_builder.error`.
+        def execute_and_audit(context, _args, data, filter)
+          pending = audit_pending(context, data, filter)
+
+          begin
+            result = context.collection.execute(context.caller, @action_name, data, filter)
+          rescue StandardError
+            audit_confirm(pending, failed: true)
+            raise
+          end
+
+          audit_confirm(pending, result: result, failed: error_result?(result))
+
+          result
+        end
+
+        def error_result?(result)
+          result.is_a?(Hash) && result[:type] == 'Error'
+        end
+
+        # Everything audit-related sits inside the gate, the record selection included: without an audit
+        # database none of it runs at all, and a failure refuses the action only under `critical: true` — which
+        # is safe here, since the action has not run yet.
+        def audit_pending(context, data, filter)
+          store = ForestAdminAgent::AuditTrail.store
+          return [] unless store
+
+          ForestAdminAgent::AuditTrail.gate do
+            action_capture(store).pending(
+              caller: context.caller,
+              collection: context.collection.name,
+              action_name: @action_name,
+              form_values: data,
+              record_ids: audited_record_ids(context, filter)
+            )
+          end || []
+        end
+
+        def audit_confirm(pending, result: nil, failed: false)
+          store = ForestAdminAgent::AuditTrail.store
+
+          action_capture(store).confirm(pending, result: result, failed: failed) if store && pending.any?
+        end
+
+        def action_capture(store)
+          ForestAdminAgent::AuditTrail::ActionCapture.new(store, ForestAdminAgent::AuditTrail.options[:redact])
+        end
+
+        # Packed ids, the form the audit store keys on — read back through the caller's own filter rather than
+        # taken from the request. The ids a client sends are a claim: in a compliance record, asserting that an
+        # operator acted on a record their scope excludes is worse than a missing row. A global action targets
+        # no record, and a selection wider than the cap is recorded as one row attached to none.
+        def audited_record_ids(context, filter)
+          return [] if context.collection.schema[:actions][@action_name].scope == Types::ActionScope::GLOBAL
+
+          cap = ForestAdminAgent::AuditTrail::MAX_RECORDS_PER_OPERATION
+          primary_keys = ForestAdminDatasourceToolkit::Utils::Schema.primary_keys(context.collection)
+          records = context.collection.list(
+            context.caller, filter.override(page: Page.new(offset: 0, limit: cap + 1)), Projection.new(primary_keys)
+          )
+
+          return records.map { |record| Utils::Id.pack_id(context.collection, record) } if records.size <= cap
+
+          # Same rule as a bulk write: recording one unattached row for a run that touched more records than
+          # the cap is a partial audit, which `critical` exists to refuse. Nothing has run yet — the gate is
+          # ahead of `execute` — so refusing costs nothing to repair.
+          ForestAdminAgent::AuditTrail.refuse_over_cap! if ForestAdminAgent::AuditTrail.critical?
+
+          ForestAdminAgent::AuditTrail.log_truncation(0, nil)
+          []
+        end
+
         def middleware_custom_action_approval_request_data(args)
           raise Http::Exceptions::UnprocessableError if args.dig(:params, :data, :attributes, :requester_id)
 

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

@@ -67,12 +67,22 @@ module ForestAdminAgent
                 canUseProjectionOnGetOne: true,
                 canUseProjectionViaHeader: true,
                 canUseProjectionViaHeaderOnList: true,
-                canUseMultipleFieldsProjectionOnRelation: true
+                canUseMultipleFieldsProjectionOnRelation: true,
+                canUseAuditTrail: audit_trail_enabled?
               }
             },
             status: 200
           }
         end
+
+        private
+
+        # True only where the store the record-history route reads from exists — the same lookup that route
+        # mounts itself on, so the capability cannot drift from what the routes actually serve. The front gates
+        # its History tab on this.
+        def audit_trail_enabled?
+          !::ForestAdminAgent::AuditTrail.store.nil?
+        end
       end
     end
   end

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

@@ -0,0 +1,237 @@
+require 'active_support/time'
+
+module ForestAdminAgent
+  module Routes
+    module Resources
+      # Record-history route, mirroring the Node agent's `/_audit-trail/{collection}/:id`.
+      #
+      # Registered only when `config.audit_trail[:database]` is set, in which case the agent factory
+      # built the store the capture layer writes to.
+      class AuditTrail < AbstractAuthenticatedRoute
+        include ForestAdminAgent::Utils
+        include AuditTrailRoute
+
+        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/
+
+        def setup_routes
+          return self unless store
+
+          add_route(
+            'forest_audit_trail',
+            'get',
+            '/_audit-trail/:collection_name/:id',
+            ->(args) { handle_request(args) }
+          )
+          add_route(
+            'forest_audit_trail_state',
+            'get',
+            '/_audit-trail/:collection_name/:id/state',
+            ->(args) { handle_state(args) }
+          )
+
+          self
+        end
+
+        def handle_request(args = {})
+          context = build(args)
+          context.permissions.can?(:read, context.collection)
+          assert_record_in_scope(context, context.collection, args[:params]['id'])
+
+          skip, limit = parse_pagination(args)
+          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']),
+            **parse_filters(args)
+          }
+
+          history = store.list_by_record(**filters, skip: skip, limit: limit, order: parse_sort(args))
+          # `count` reflects the active filters (not the absolute total) and is independent of the page.
+          count = store.count_by_record(**filters)
+
+          {
+            name: args[:params]['collection_name'],
+            content: { data: history.map { |record| serialize_record(record) }, meta: meta(args, filters, count) }
+          }
+        end
+
+        # Record as it stood at `timestamp`: the current record with every later entry undone. `data` is
+        # null when the record did not exist yet (or not any more) at that instant. Shape matches the Node
+        # agent's handleStateAt — `data` and nothing else.
+        def handle_state(args = {})
+          context = build(args)
+          context.permissions.can?(:read, context.collection)
+          # Authorizes and reads in one query: the record it hands back is the one the scope covered.
+          current = scoped_record(
+            context, context.collection, args[:params]['id'], audited_projection(context.collection)
+          )
+
+          timestamp = parse_state_timestamp(args)
+          entries = store.list_since(
+            collection: context.collection.name,
+            record_id: record_segments(context.collection, args[:params]['id']),
+            timestamp: timestamp
+          )
+          # Fully qualified: inside this class, `AuditTrail` is the route itself.
+          state = ::ForestAdminAgent::AuditTrail::RecordState.at(current, entries)
+
+          { name: args[:params]['collection_name'], content: { data: state } }
+        end
+
+        private
+
+        # `availableUsers` rides along on the first fetch only — the front keeps the list it saw — and lists the
+        # distinct authors of the entries the current filters match, whatever page was asked for. The identity
+        # comes from the rows, so someone since renamed or removed still reads as they were when they acted.
+        def meta(args, filters, count)
+          return { count: count } unless first_fetch?(args)
+
+          { count: count, availableUsers: available_users(filters) }
+        end
+
+        def first_fetch?(args)
+          page = args.dig(:params, 'page')
+
+          (page.is_a?(Hash) ? page['number'].to_i : 0) <= 1
+        end
+
+        def available_users(filters)
+          store.authors_by_record(**filters).map do |author|
+            { id: author[:user_id], firstName: author[:user_first_name],
+              lastName: author[:user_last_name], email: author[:user_email] }
+          end
+        end
+
+        # An ISO-8601 instant, or the same wall-clock forms the history filters accept, read in the request
+        # timezone.
+        def parse_state_timestamp(args)
+          raw = args.dig(:params, 'timestamp').to_s
+          raise Http::Exceptions::ValidationError, 'Missing timestamp' if raw.empty?
+          # A wall-clock value carries no offset, so it belongs to the request timezone. Handing it to
+          # Time.iso8601 would read it in the server's instead — silently, since it parses just fine.
+          return parse_date_boundary(raw, request_timezone(args), :start) if wall_clock?(raw)
+
+          begin
+            Time.iso8601(raw).utc.iso8601(3)
+          rescue ArgumentError
+            parse_date_boundary(raw, request_timezone(args), :start)
+          end
+        end
+
+        def wall_clock?(raw)
+          DATE_ONLY.match?(raw) || DATE_TIME.match?(raw)
+        end
+
+        # JSON:API `sort`: `timestamp` → oldest first, anything else (absent/unsupported) → newest first.
+        def parse_sort(args)
+          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.
+        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
+          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
+end

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

@@ -0,0 +1,101 @@
+module ForestAdminAgent
+  module Routes
+    module Resources
+      # Correlation-scoped record-history routes, mirroring the Node agent's
+      # `/_audit-trail/correlation/:key` and `/_audit-trail/correlations`. Registered only when
+      # `config.audit_trail[:database]` is set. All three routes are scoped to a single record through the
+      # `collection`/`recordId` query (GET) or body (POST) params and share the per-record auth.
+      class AuditTrailCorrelation < AbstractAuthenticatedRoute
+        include AuditTrailRoute
+
+        def setup_routes
+          return self unless store
+
+          add_route(
+            'forest_audit_trail_correlation',
+            'get',
+            '/_audit-trail/correlation/:correlation_key',
+            ->(args) { handle_history(args) }
+          )
+          # GET carries the keys in `correlationKeys`; POST accepts a body list to dodge URL limits.
+          add_route(
+            'forest_audit_trail_correlations',
+            'get',
+            '/_audit-trail/correlations',
+            ->(args) { handle_batch(args) }
+          )
+          add_route(
+            'forest_audit_trail_correlations_batch',
+            'post',
+            '/_audit-trail/correlations',
+            ->(args) { handle_batch(args) }
+          )
+
+          self
+        end
+
+        def handle_history(args = {})
+          collection, record_id = assert_scope(args)
+
+          history = store.list_by_correlation(
+            collection: collection.name,
+            record_id: record_id,
+            correlation_key: args[:params]['correlation_key']
+          )
+
+          { name: collection.name, content: { data: history.map { |record| serialize_record(record) } } }
+        end
+
+        def handle_batch(args = {})
+          collection, record_id = assert_scope(args)
+          correlation_keys = parse_correlation_keys(args)
+
+          history = if correlation_keys.empty?
+                      []
+                    else
+                      store.list_by_correlations(
+                        collection: collection.name,
+                        record_id: record_id,
+                        correlation_keys: correlation_keys
+                      )
+                    end
+
+          { name: collection.name, content: { data: history.map { |record| serialize_record(record) } } }
+        end
+
+        private
+
+        def assert_scope(args)
+          context = build(args)
+          name = args.dig(:params, 'collection').to_s
+          record_id = args.dig(:params, 'recordId').to_s
+
+          raise Http::Exceptions::ValidationError, 'Missing collection' if name.empty?
+          raise Http::Exceptions::ValidationError, 'Missing recordId' if record_id.empty?
+
+          collection = get_collection(context, name)
+          context.permissions.can?(:read, collection)
+          assert_record_in_scope(context, collection, record_id)
+
+          [collection, record_id]
+        end
+
+        def get_collection(context, name)
+          context.datasource.get_collection(name)
+        rescue ForestAdminDatasourceToolkit::Exceptions::ForestException => e
+          raise Http::Exceptions::NotFoundError, e.message if e.message.include?('not found')
+
+          raise
+        end
+
+        # Body array (POST) takes precedence, otherwise the comma-separated query param (GET).
+        def parse_correlation_keys(args)
+          raw = args.dig(:params, 'correlationKeys')
+          keys = raw.is_a?(Array) ? raw : raw.to_s.split(',')
+
+          keys.map { |key| key.to_s.strip }.reject(&:empty?)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+module ForestAdminAgent
+  module Routes
+    module Resources
+      # Behaviour shared by every audit-trail route: they all take a packed record id straight from the
+      # request, so the caller's permission scope has to be checked against that record before any
+      # history is returned (`can?(:read, collection)` alone only proves access to the collection — a
+      # role restricted to a subset of the records would otherwise read the history of any of them),
+      # and they all serialize audit records the same way.
+      module AuditTrailRoute
+        include ForestAdminDatasourceToolkit::Components::Query
+
+        def assert_record_in_scope(context, collection, packed_id)
+          scoped_record(context, collection, packed_id)
+
+          nil
+        end
+
+        # The record as it stands, read through the caller's permission scope. nil when it no longer exists
+        # — a deleted record keeps its history readable, which is much of the point of an audit trail — and
+        # a 404 when it does exist outside that scope.
+        #
+        # Authorizing and reading are the same query on purpose: a scoped check followed by an unscoped read
+        # would hand back a row the check never covered, the moment the two drifted apart.
+        def scoped_record(context, collection, packed_id, projection = nil)
+          condition = ConditionTree::ConditionTreeFactory.match_records(
+            collection, [Utils::Id.unpack_id(collection, packed_id, with_key: true)]
+          )
+          scope = context.permissions.get_scope(collection)
+          in_scope = ConditionTree::ConditionTreeFactory.intersect([condition, scope])
+          record = first_record(context, collection, in_scope, projection || key_projection(collection))
+
+          return record if record
+          # Nothing in scope: either gone for good, or someone else's record. Without a scope the query
+          # above already answered the question.
+          return nil if scope.nil? || first_record(context, collection, condition, key_projection(collection)).nil?
+
+          raise Http::Exceptions::NotFoundError, 'Record does not exists'
+        end
+
+        # Camelize only the top-level keys — the row `id` included, which the front uses as the tiebreaker when
+        # 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) }
+        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
+
+        # 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?
+
+          pair = ->(bound) { [bound[:until], bound[:until_row].to_i] }
+          earlier = (pair[one] <=> pair[other]) <= 0 ? one : other
+
+          earlier.slice(:until, :until_row)
+        end
+
+        # What the audit trail actually records: primary keys, so a state can be identified, plus the writable
+        # columns. Reading read-only ones would hand them back at their present value inside an answer that
+        # claims to describe a past instant.
+        def audited_projection(collection)
+          writable = collection.schema[:fields].select do |_name, field|
+            field.type == 'Column' && !field.is_read_only
+          end.keys
+
+          Projection.new((ForestAdminDatasourceToolkit::Utils::Schema.primary_keys(collection) + writable).uniq)
+        end
+
+        def key_projection(collection)
+          Projection.new(ForestAdminDatasourceToolkit::Utils::Schema.primary_keys(collection))
+        end
+
+        def first_record(context, collection, condition_tree, projection)
+          collection.list(context.caller, Filter.new(condition_tree: condition_tree), projection).first
+        end
+      end
+    end
+  end
+end

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

@@ -43,7 +43,7 @@ module ForestAdminAgent
               class_name: context.collection.name,
               is_collection: true,
               serializer: Serializer::ForestSerializer,
-              include: projection.relations(only_keys: true),
+              include: projection.relation_include_paths,
               meta: handle_search_decorator(args[:params]['search'], records, context.collection)
             )
           }

data/lib/forest_admin_agent/routes/resources/related/list_related.rb

@@ -53,7 +53,7 @@ module ForestAdminAgent
                 is_collection: true,
                 class_name: context.child_collection.name,
                 serializer: Serializer::ForestSerializer,
-                include: projection.relations.keys
+                include: projection.relation_include_paths
               )
             }
           end

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

@@ -38,7 +38,7 @@ module ForestAdminAgent
               class_name: context.collection.name,
               is_collection: false,
               serializer: Serializer::ForestSerializer,
-              include: projection.relations(only_keys: true)
+              include: projection.relation_include_paths
             )
           }
         end