forest_admin_agent 1.38.2 → 1.39.0

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

@@ -0,0 +1,58 @@
+module ForestAdminAgent
+  module AuditTrail
+    module Sql
+      # SQL keeping only the audit entries whose diff touched one of the given fields. Both JSON columns are
+      # searched: a field the change added exists in `new_values` only, one it removed in `previous_values`
+      # only.
+      #
+      # The test is per adapter, and a field name is always a whole key — never a path — so a name holding a
+      # dot (`address.city`) has to be quoted or the database reads it as a traversal.
+      class FieldFilter
+        COLUMNS = %w[previous_values new_values].freeze
+
+        def initialize(connection)
+          @connection = connection
+        end
+
+        def condition(fields)
+          adapter = @connection.adapter_name.downcase
+
+          case adapter
+          when /postgres/ then COLUMNS.map { |column| postgres_has_key(column, fields) }.join(' OR ')
+          when /sqlite/ then json_paths(fields) { |column, path| "json_type(#{column}, #{path}) IS NOT NULL" }
+          when /mysql|maria/ then mysql_has_keys(fields)
+          else
+            raise ForestAdminDatasourceToolkit::Exceptions::ForestException,
+                  "Filtering the audit trail by field is not supported on #{adapter}"
+          end
+        end
+
+        private
+
+        # `jsonb_object_keys` rather than the `?|` operator: `?` is a bind placeholder for ActiveRecord and
+        # the function form needs no escaping. The column is `json`, hence the cast.
+        def postgres_has_key(column, fields)
+          list = fields.map { |field| @connection.quote(field) }.join(', ')
+
+          "EXISTS (SELECT 1 FROM jsonb_object_keys(#{column}::jsonb) AS key WHERE key IN (#{list}))"
+        end
+
+        # `json_type` and not `json_extract`: a key holding a JSON null extracts as SQL NULL, which would
+        # read as "no such key".
+        def json_paths(fields)
+          COLUMNS.flat_map { |column| fields.map { |field| yield(column, json_path(field)) } }.join(' OR ')
+        end
+
+        def mysql_has_keys(fields)
+          paths = fields.map { |field| json_path(field) }.join(', ')
+
+          COLUMNS.map { |column| "JSON_CONTAINS_PATH(#{column}, 'one', #{paths})" }.join(' OR ')
+        end
+
+        def json_path(field)
+          @connection.quote(%($."#{field.to_s.gsub(/["\\]/) { |char| "\\#{char}" }}"))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+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.
+      module Migrations
+        ALL = [
+          {
+            name: '001-create-audit-logs',
+            up: lambda do |connection, table|
+              # if_not_exists: a non-PG race (no advisory lock) can let two instances both reach here.
+              connection.create_table(table, if_not_exists: true) do |t|
+                t.datetime :timestamp, null: false
+                t.string :operation, null: false
+                t.string :collection, null: false
+                # Nullable, because a create's pending row has no id yet; text, because a packed composite id
+                # outgrows a varchar.
+                t.text :record_id
+                # No default on purpose: every write sets it, so a row arriving without one is a bug worth
+                # hearing about rather than a row that quietly claims to be done.
+                t.string :status, null: false
+                t.integer :user_id
+                # Denormalised from the caller at write time: who acted then, not whoever holds that id today.
+                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.
+                t.text :previous_record_id
+                # Smart-action rows only.
+                t.text :action_name
+                t.string :correlation_key
+                t.json :previous_values
+                t.json :new_values
+              end
+
+              base = table.split('.').last
+              # MySQL cannot index unbounded TEXT, so that one index needs a length prefix.
+              record_id_index = { name: "#{base}_record_id", if_not_exists: true }
+              record_id_index[:length] = 255 if connection.adapter_name.downcase.match?(/mysql|maria/)
+
+              connection.add_index(table, :record_id, **record_id_index)
+              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
+          }
+        ].freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+module ForestAdminAgent
+  module AuditTrail
+    module Sql
+      # Applies {Migrations::ALL} to the audit table, tracking what has run in a companion table named after
+      # it — `audit_logs_migration` beside `audit_logs` (both namespaced in the `forest` schema on Postgres).
+      # One tracker per audited table, so two stores configured with different `table_name`s each get their
+      # own schema history instead of reading each other's as done.
+      #
+      # On Postgres the migrations run inside a transaction-scoped advisory lock, so several agent
+      # instances booting at once apply them one after another instead of racing on the same DDL. The
+      # schema is created (and committed) first, made idempotent (CREATE SCHEMA IF NOT EXISTS +
+      # tolerating a concurrent create), because the lock cannot cover a not-yet-existing schema.
+      class Migrator
+        # Arbitrary but stable key pair identifying the audit-trail migration critical section.
+        ADVISORY_LOCK = [0x464f, 0x5254].freeze # "FO", "RT"
+        # duplicate_schema, and the unique violation on pg_namespace the same race can raise instead.
+        DUPLICATE_SCHEMA_STATES = %w[42P06 23505].freeze
+
+        def initialize(connection, schema:, table_name:)
+          @connection = connection
+          @schema = schema # nil on adapters without schema support
+          @table_name = table_name
+        end
+
+        def run
+          ensure_schema
+
+          if postgres?
+            @connection.transaction do
+              @connection.execute("SELECT pg_advisory_xact_lock(#{ADVISORY_LOCK[0]}, #{ADVISORY_LOCK[1]})")
+              apply_pending
+            end
+          else
+            apply_pending
+          end
+        end
+
+        private
+
+        def postgres?
+          @connection.adapter_name.downcase.include?('postgres')
+        end
+
+        def schema?
+          postgres? && @schema.present?
+        end
+
+        def qualified(name)
+          schema? ? "#{@schema}.#{name}" : name
+        end
+
+        # Create the schema first and commit it: the migrations open DDL on the same connection, and a
+        # CREATE SCHEMA still pending in the lock transaction would not be visible to them.
+        def ensure_schema
+          return unless schema?
+
+          @connection.execute("CREATE SCHEMA IF NOT EXISTS #{@connection.quote_schema_name(@schema)}")
+        rescue ActiveRecord::RecordNotUnique
+          # 23505 on pg_namespace, already mapped to its own class by ActiveRecord: another instance
+          # created the schema between our IF NOT EXISTS check and the create itself.
+          nil
+        rescue ActiveRecord::StatementInvalid => e
+          raise unless duplicate_schema?(e)
+        end
+
+        # By SQLSTATE where the adapter exposes one, so an unrelated failure (no permission to create a
+        # schema, say) is not read as a lost race just because its message says "exists".
+        def duplicate_schema?(error)
+          state = sql_state(error)
+          return DUPLICATE_SCHEMA_STATES.include?(state) if state
+
+          /already exists|duplicate/i.match?(error.message)
+        end
+
+        def sql_state(error)
+          cause = error.cause
+          return nil unless cause.respond_to?(:result) && defined?(PG::Result)
+
+          cause.result.error_field(PG::Result::PG_DIAG_SQLSTATE)
+        rescue StandardError
+          nil
+        end
+
+        def apply_pending
+          done = applied_migrations
+          table = qualified(@table_name)
+
+          Migrations::ALL.each do |migration|
+            next if done.include?(migration[:name])
+
+            migration[:up].call(@connection, table)
+            @connection.execute(
+              "INSERT INTO #{@connection.quote_table_name(migrations_table)} (name) " \
+              "VALUES (#{@connection.quote(migration[:name])})"
+            )
+          end
+        end
+
+        def applied_migrations
+          ensure_migrations_table
+
+          @connection.select_values("SELECT name FROM #{@connection.quote_table_name(migrations_table)}")
+        end
+
+        def ensure_migrations_table
+          @connection.create_table(migrations_table, id: false, if_not_exists: true) do |t|
+            t.string :name, null: false
+          end
+        end
+
+        def migrations_table
+          qualified("#{@table_name}_migration")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+require 'json'
+
+module ForestAdminAgent
+  module AuditTrail
+    module Sql
+      # SQL keeping only the audit entries a free-text term matches, case-insensitively and as a substring:
+      # the action's name, who acted, and the keys and values recorded on both sides of the change — at any
+      # depth, since only the changed leaves of a JSON column are stored and the term has to reach them.
+      #
+      # Deliberately not searched: operation, correlation_key, record_id, collection, status and timestamp.
+      # Machine identifiers nobody searches for, and matching them turns one term into a pile of confusing
+      # hits.
+      #
+      # The values are matched against the JSON document as text, which is what lets one condition reach any
+      # depth and compose with pagination and the count. It cannot use an index, which is affordable here
+      # because a history query is already narrowed to one record.
+      class TextSearch
+        TEXT_COLUMNS = %w[action_name user_first_name user_last_name user_email].freeze
+        JSON_COLUMNS = %w[previous_values new_values].freeze
+        # `!` rather than a backslash: MySQL treats a backslash as an escape inside string literals too, so
+        # `ESCAPE '\'` needs doubling there and nowhere else.
+        ESCAPE = '!'.freeze
+        # A masked value is stored as this. It is removed before matching, so a search for "redacted" cannot
+        # hit it — and since the real value was never recorded, searching that finds nothing either. A search
+        # must never confirm a value the trail refused to keep.
+        REDACTED = Recording::REDACTED
+
+        def initialize(connection)
+          @connection = connection
+        end
+
+        def condition(term)
+          text = term.to_s.downcase
+          # The value objects are matched as serialized JSON, where a quote, a backslash or a newline is
+          # escaped — so `15" monitor` sits in the document as `15\" monitor` and the raw term would never
+          # find it. Escaping the term the same way makes it match, and stops a bare quote from matching the
+          # document's own structure.
+          clauses = TEXT_COLUMNS.map { |column| like(column, text) }
+          clauses += JSON_COLUMNS.map { |column| like(searchable_json(column), json_escaped(text)) }
+
+          clauses.join(' OR ')
+        end
+
+        private
+
+        def like(expression, text)
+          "LOWER(#{expression}) LIKE #{@connection.quote("%#{escape(text)}%")} ESCAPE '#{ESCAPE}'"
+        end
+
+        # What JSON generation would have done to the term: `to_json` on the string, minus its own quotes.
+        def json_escaped(text)
+          text.to_json[1..-2]
+        end
+
+        def searchable_json(column)
+          "REPLACE(#{as_text(column)}, #{@connection.quote(REDACTED)}, '')"
+        end
+
+        def as_text(column)
+          adapter = @connection.adapter_name.downcase
+
+          case adapter
+          when /postgres/ then "#{column}::text"
+          when /sqlite/ then column
+          when /mysql|maria/ then "CAST(#{column} AS CHAR)"
+          else
+            raise ForestAdminDatasourceToolkit::Exceptions::ForestException,
+                  "Searching the audit trail is not supported on #{adapter}"
+          end
+        end
+
+        def escape(term)
+          term.gsub(/[!%_]/) { |char| "#{ESCAPE}#{char}" }
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_agent/audit_trail/store.rb

@@ -0,0 +1,253 @@
+require 'time'
+
+module ForestAdminAgent
+  module AuditTrail
+    # SQL-backed storage that both writes every audited change and reads the per-record history back.
+    #
+    # {#connect!} opens the connection and migrates; the agent factory calls it at boot rather than leaving it
+    # to the first write, so a database the agent cannot reach is a startup failure instead of an agent that
+    # looks healthy while recording nothing — and, under `critical: true`, instead of one that refuses every
+    # write the moment somebody first tries to save something.
+    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
+                   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
+
+      def initialize(database:, schema: DEFAULT_SCHEMA, table_name: DEFAULT_TABLE)
+        @database = database
+        @schema = schema
+        @table_name = table_name
+        @mutex = Mutex.new
+        @ready = false
+      end
+
+      def connect!
+        ensure_ready
+
+        self
+      end
+
+      def append(record)
+        append_all([record]).first
+      end
+
+      # Inserts rows and returns their ids, in the order given. Batched, because a "delete all" snapshot can
+      # be thousands of records and the pending/confirm protocol writes each of them twice.
+      #
+      # The ids are matched to their rows by `record_id` rather than by the order RETURNING happens to come
+      # back in, which Postgres does not promise: pairing them positionally would confirm each pending row with
+      # another record's diff. One row per record per operation, so that key is unique within a batch — bar a
+      # pending create, which has no id yet and is always a batch of one.
+      def append_all(records)
+        return [] if records.empty?
+
+        rows = records.map { |record| to_row(record) }
+        return rows.map { |row| model.create!(row).id } unless batch_returning?(rows)
+
+        returned = model.insert_all(rows, returning: %i[id record_id]).rows.to_h { |id, key| [key, id] }
+
+        rows.map { |row| returned[row[:record_id]] }
+      end
+
+      # One insert per row when the ids cannot be matched back: no RETURNING on this adapter (MySQL), or a
+      # batch whose record ids are not distinct enough to pair on.
+      def batch_returning?(rows)
+        return false unless model.connection.supports_insert_returning?
+
+        keys = rows.map { |row| row[:record_id] }
+
+        keys.none?(&:nil?) && keys.uniq.size == keys.size
+      end
+
+      def confirm(id, attributes)
+        row = model.find_by(id: id)
+
+        row&.update!(**attributes, status: Recording::DONE)
+      end
+
+      # A write that turned out to change nothing leaves no trace: the pending row goes rather than sitting
+      # there implying the write is unaccounted for.
+      def discard(ids)
+        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')
+        # `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)
+                   .order(timestamp: order.to_s == 'desc' ? :desc : :asc, id: :asc)
+                   .offset(skip || 0)
+        relation = relation.limit(limit) unless limit.nil?
+
+        relation.map { |row| from_row(row) }
+      end
+
+      def count_by_record(collection:, record_id:, user_ids: 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).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,
+                            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] }
+      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
+      end
+
+      # Entries recorded strictly after `timestamp`, newest first: what a state reconstruction has to undo.
+      # Strictly after, so an entry stamped exactly at the requested instant counts as part of that state
+      # instead of being reverted out of it.
+      # Confirmed rows only: a pending one records an attempt whose outcome is unknown, and undoing a change
+      # that may never have happened would invent a state the record was never in. The history reads keep
+      # pending rows — they are evidence, and `status` tells the reader what they are — but a reconstruction
+      # cannot act on them.
+      def list_since(collection:, record_id:, timestamp:)
+        model.where(collection: collection, status: Recording::DONE)
+             .where(*segments_condition(record_id))
+             .where('timestamp > ?', as_time(timestamp))
+             .order(timestamp: :desc, id: :desc)
+             .map { |row| from_row(row) }
+      end
+
+      def list_by_correlation(collection:, record_id:, correlation_key:)
+        list_by_correlations(collection: collection, record_id: record_id, correlation_keys: [correlation_key])
+      end
+
+      def list_by_correlations(collection:, record_id:, correlation_keys:)
+        return [] if correlation_keys.empty?
+
+        model.where(collection: collection, record_id: record_id, correlation_key: correlation_keys)
+             .order(:timestamp, :id)
+             .map { |row| from_row(row) }
+      end
+
+      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
+        relation = relation.where(Sql::FieldFilter.new(model.connection).condition(fields)) if fields&.any?
+        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).
+        relation = relation.where('timestamp >= ?', as_time(start_timestamp)) if start_timestamp
+        relation = relation.where('timestamp <= ?', as_time(end_timestamp)) if end_timestamp
+        relation
+      end
+
+      def as_time(value)
+        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
+      end
+
+      def ensure_ready
+        return if @ready
+
+        @mutex.synchronize do
+          return if @ready
+
+          Sql::AuditConnectionBase.connect_to(@database)
+          connection = Sql::AuditConnectionBase.connection
+          Sql::Migrator.new(connection, schema: schema_for(connection), table_name: @table_name).run
+          @model = build_model(qualified(connection))
+          @ready = true
+        end
+      end
+
+      # A per-instance concrete subclass bound to this store's own table, so distinct stores can't
+      # clobber each other's table name. reset_column_information drops stale metadata for the table
+      # the migration just created/evolved.
+      def build_model(table)
+        Class.new(Sql::AuditLog) { self.table_name = table }.tap(&:reset_column_information)
+      end
+
+      def schema_for(connection)
+        connection.adapter_name.downcase.include?('postgres') ? @schema : nil
+      end
+
+      def qualified(connection)
+        schema = schema_for(connection)
+        schema ? "#{schema}.#{@table_name}" : @table_name
+      end
+
+      # An AuditRecord is a Struct and a row answers to `[]` too, so the mapping is the column list itself.
+      def to_row(record)
+        COLUMNS.to_h { |column| [column, record[column]] }
+      end
+
+      def from_row(row)
+        values = COLUMNS.to_h { |column| [column, row[column]] }
+        values[:id] = row.id
+        values[:timestamp] = row.timestamp.respond_to?(:iso8601) ? row.timestamp.iso8601(3) : row.timestamp.to_s
+        values[:previous_values] ||= {}
+        values[:new_values] ||= {}
+
+        AuditRecord.new(**values)
+      end
+    end
+  end
+end

data/lib/forest_admin_agent/audit_trail.rb

@@ -0,0 +1,68 @@
+module ForestAdminAgent
+  # The audit trail is inert unless `config.audit_trail[:database]` was set: the agent factory builds the
+  # store during setup — connecting and migrating there rather than on first write — and everything (capture
+  # layers and routes) resolves it from here.
+  module AuditTrail
+    # One operation must not materialise an unbounded number of records: a "delete all" would otherwise read
+    # every matched row and, with the pending/confirm protocol, write each of them twice. Truncation is logged,
+    # never silent.
+    #
+    # Matches the Node agent's `MAX_SNAPSHOT_RECORDS`: the same feature behind the same config key, so a bulk
+    # operation must not be audited on one agent and truncated on the other. Change it in both or neither.
+    MAX_RECORDS_PER_OPERATION = 1000
+
+    # Auditing a subset while the write touches every match is the one thing `critical` exists to prevent, so
+    # over the cap the operation is refused instead — before anything is written, in both the write and the
+    # action path, which is why the message lives here rather than in either of them.
+    def self.refuse_over_cap!
+      raise ForestAdminDatasourceToolkit::Exceptions::ForestException,
+            'The audit trail is configured as critical and cannot record an operation touching more than ' \
+            "#{MAX_RECORDS_PER_OPERATION} records at once. Narrow the selection."
+    end
+
+    def self.log_truncation(kept, total)
+      skipped = total ? total - kept : 'further'
+
+      Facades::Container.logger.log(
+        'Warn',
+        "[ForestAdmin] Audit trail: #{kept} records audited, #{skipped} skipped " \
+        "(cap #{MAX_RECORDS_PER_OPERATION} per operation)"
+      )
+    end
+
+    def self.options
+      config = Facades::Container.config_from_cache
+
+      (config && config[:audit_trail]) || {}
+    end
+
+    def self.store
+      options[:store]
+    end
+
+    # `critical: true` makes the pending insert a precondition of the write: if the audit trail cannot record
+    # that an operation is about to happen, the operation is refused. Nothing was written, so there is nothing
+    # to repair and no compensating write ever happens. Default false keeps today's behaviour, where a broken
+    # audit database costs rows rather than writes.
+    def self.critical?
+      options[:critical] == true
+    end
+
+    def self.log_failure(error)
+      Facades::Container.logger.log('Error', "[ForestAdmin] Audit trail unavailable, skipping: #{error.message}")
+    end
+
+    # Runs the pending insert under the configured policy: refusing the operation when critical, logging and
+    # carrying on otherwise.
+    def self.gate
+      return yield if critical?
+
+      begin
+        yield
+      rescue StandardError => e
+        log_failure(e)
+        nil
+      end
+    end
+  end
+end

data/lib/forest_admin_agent/builder/agent_factory.rb

@@ -58,6 +58,7 @@ module ForestAdminAgent
       end
 
       def build
+        install_audit_trail
         @container.register(:datasource, @customizer.datasource(@logger))
 
         # Reset route cache to ensure routes are computed with all customizations
@@ -289,12 +290,31 @@ module ForestAdminAgent
         @options[:customize_error_message] =
           clean_option_value(@options[:customize_error_message], 'config.customize_error_message =')
         @options[:logger] = clean_option_value(@options[:logger], 'config.logger =')
+        build_audit_trail_store
 
         @container.register(:config, @options.to_h)
 
         configure_rpc_polling_pool if @options[:rpc_max_polling_threads]
       end
 
+      # The audit trail switches on as soon as a database is configured. The store connects and migrates here,
+      # at boot, rather than on the first write: an audit database the agent cannot reach should stop it
+      # starting, not leave it looking healthy while recording nothing — and under `critical: true` it would
+      # otherwise refuse every write from the moment somebody first tried to save something.
+      def build_audit_trail_store
+        options = @options[:audit_trail]
+        return unless options && options[:database]
+
+        options[:store] = AuditTrail::Store.new(**options.slice(:database, :schema, :table_name).compact).connect!
+      end
+
+      def install_audit_trail
+        options = @options[:audit_trail]
+        return if options.nil? || options[:store].nil?
+
+        @customizer.use(AuditTrail::Capture, { store: options[:store], redact: options[:redact] })
+      end
+
       def configure_rpc_polling_pool
         max_threads = @options[:rpc_max_polling_threads].to_i
         return unless max_threads.positive?