forest_admin_agent 1.38.3 → 1.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8240dc695f68ad1315a072be614a48151c0f52a0a35596500face2c12bdc3847
-  data.tar.gz: 267ec0985751c7c86e5df4c426862063bf1b5e41e06ba24d7ee14bf1a80ecf69
+  metadata.gz: 6d8e421dc1033f0430516e5bb4d8b6393d1d8a8b9c0d396db8ea8dfa942984c3
+  data.tar.gz: ec2f491f596a6eef622817e3cd687d83bd9f555dbefc7418121e5f41c64bb4df
 SHA512:
-  metadata.gz: 2966283a4f8b14022cdd74a54c6e366cdfae74314cd64d77fafbb8c7c258fa860dcacafc0e1dcd842d7d590ed63884a2550aa16066696d8313d0427fa552ad3b
-  data.tar.gz: c943da4d2edf12f3e4f2b34d10ee70184befe11fe276cb246f785051cb7b7fcfb6e885459c9e5431e0351c6621db30ee6e2cab5ad93ee5c9ed3b8cf152ce63cc
+  metadata.gz: 5f822cf9a20bf034e51ea355cde7a894d904214e095dabec83952d95ae2856cc8a79de43713a48e6914d046c52a2bc271d91ffe762bfdb833fe2fe790584a08c
+  data.tar.gz: ff1bb212d93c979e0ab69a802f8da3e839cc350b6e29cbfb08706e65d01882048266f44eb8d3c235db3e1af6f1df2efd0e4bde42509af6f3618a76a7a4a8ea58

data/AUDIT_TRAIL.md

@@ -0,0 +1,347 @@
+# Audit trail
+
+Capture who changed what (before/after) for every change Forest performs through its data layer, and
+persist it into a SQL database. Built into the agent: it turns on as soon as an audit-trail **database
+is configured**, and stays completely off otherwise.
+
+Two parts, both internal:
+
+- **Capture** (`ForestAdminAgent::AuditTrail::Capture`) — datasource-agnostic. It instruments every
+  collection through the customizer hooks, so it behaves the same whether the audited datasource is
+  ActiveRecord, Mongoid, etc.
+- **Storage** (`ForestAdminAgent::AuditTrail::Store`) — ActiveRecord-backed. It creates the `forest`
+  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.
+
+## Turn it on
+
+### Rails (forest_admin_rails)
+
+```ruby
+# config/initializers/forest_admin_rails.rb
+ForestAdminRails.configure do |config|
+  config.auth_secret = ENV['FOREST_AUTH_SECRET']
+  config.env_secret  = ENV['FOREST_ENV_SECRET']
+
+  config.audit_trail = {
+    database: { # or an ActiveRecord URL: ENV['AUDIT_TRAIL_DATABASE_URL']
+      adapter: 'postgresql', host: ENV['AUDIT_DB_HOST'], port: ENV['AUDIT_DB_PORT'],
+      username: ENV['AUDIT_DB_USER'], password: ENV['AUDIT_DB_PASSWORD'], database: ENV['AUDIT_DB_NAME']
+    }
+  }
+end
+```
+
+### Plain agent (no Rails)
+
+```ruby
+ForestAdminAgent::Builder::AgentFactory.instance.setup(
+  auth_secret: ENV['FOREST_AUTH_SECRET'],
+  env_secret: ENV['FOREST_ENV_SECRET'],
+  # ...usual options...
+  audit_trail: { database: ENV['AUDIT_TRAIL_DATABASE_URL'] }
+)
+```
+
+| option       | description                                                                          |
+| ------------ | ------------------------------------------------------------------------------------ |
+| `database`   | ActiveRecord URL or config hash. **Setting it activates the audit trail.**           |
+| `schema`     | Postgres schema holding the table (default `forest`; ignored on other adapters)      |
+| `table_name` | default `audit_logs`                                                                 |
+| `redact`     | `{ 'collection_name' => ['field', ...] }` — values masked while recording the change |
+| `critical`   | default `false`. `true` refuses an operation the audit trail cannot record — see below |
+
+The store connects and migrates **at boot**, not on the first write: an audit database the agent cannot
+reach stops it starting, rather than leaving it looking healthy while recording nothing. Every create /
+update / delete performed through Forest then writes one row per record, and the **Historic** tab in the UI
+reads from the same table.
+
+## The write protocol, and `critical`
+
+Every operation is recorded twice: a `pending` row **before** the write, confirmed `done` **after** it. One
+code path either way, so `status` always means the same thing.
+
+| `critical` | a pending row that cannot be written                                                       |
+| ---------- | ------------------------------------------------------------------------------------------ |
+| `false`    | is logged and dropped; the operation goes ahead unaudited (the default, today's behaviour)   |
+| `true`     | **refuses the operation**. Nothing was written, so there is nothing to repair and no compensating write ever happens |
+
+What this buys is **no unaudited write** — not that every row holds exact after-values. A row left `pending`
+means the write may or may not have landed: that residue is evidence, and it is the point. Everything after
+the pending insert stays best-effort in both modes, because by then the write has happened and raising would
+report a failure for an operation that succeeded.
+
+> **The guarantee is opt-in.** `critical` defaults to `false`, so on a default configuration a write can
+> succeed with no audit row at all — an unreachable audit database costs rows, not writes. Configuring the
+> database gets you a best-effort trail; `critical: true` is what makes "no unaudited write" true. The Node
+> agent defaults the same way, so the two agree.
+
+Consequences worth knowing:
+
+- A write that turns out to change nothing has its pending row **discarded** rather than confirmed, so no-op
+  updates leave no trace.
+- A record the agent cannot read back after the write keeps its row **pending**. Confirming from the patch
+  would claim values that may never have been written.
+- A write nested inside another that fails and is rescued keeps its row **pending** too. Each snapshot is
+  matched to its own operation by the object the hook decorator hands to both of its hooks, so the outer write
+  settles its own rows rather than the failed inner one's. Where a customization replaced that object there is
+  nothing to match on: with one operation in flight it still pairs, with several the rows stay pending rather
+  than the wrong ones being marked done.
+- One operation audits at most **1000** records — the same number as the Node agent's `MAX_SNAPSHOT_RECORDS`,
+  so a bulk operation is not audited on one agent and truncated on the other. Under `critical: false` a wider
+  selection is truncated, with `N records audited, M skipped` logged at `Warn`; a smart action over the cap is
+  recorded as one row attached to no record. Under `critical: true` both are **refused**: auditing a subset
+  while the operation touches every match is precisely the invariant that mode exists for.
+- Pending rows stay visible in the history — they are evidence of an attempt, and `status` says so — but the
+  state reconstruction ignores them, since undoing a change that may never have happened would invent a state
+  the record was never in.
+
+## Routes
+
+All routes live under `/forest/_audit-trail`, are registered only when `audit_trail[:database]` is
+set, and require read permission on the target collection (`can?(:read, collection)`).
+
+### Record-history route
+
+`GET /forest/_audit-trail/{collection}/{recordId}` returns the current page of history (newest first
+by default) together with the filtered total:
+
+```json
+{ "data": [ /* current page rows */ ], "meta": { "count": 137 } }
+```
+
+`meta.count` is the number of rows matching the active filters (not the absolute total) and is independent of
+the page. `meta.availableUsers` rides along **on the first fetch only** — the front keeps the list it saw —
+and holds the distinct authors of the entries the current filters match, as `{ id, firstName, lastName,
+email }`, whatever page was asked for. The identity comes from the rows themselves, so someone since renamed
+or removed still reads as they were when they acted. Optional filters (all combine with `AND`; omit them for the full history):
+
+| query param | format                           | effect                                          |
+| ----------- | -------------------------------- | ----------------------------------------------- |
+| `userIds`   | comma-separated integers `12,45` | keep only entries whose `user_id` is in the list |
+| `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 |
+| `search`    | free text, trimmed               | keep only entries the term matches               |
+
+`search` is matched case-insensitively, as a substring, against the action's name, the actor's first name,
+last name and email, and the **keys and values of both value objects at any depth** — searching `Lyon` finds
+`{"address": {"city": "Lyon"}}`, which is what only the agent can answer, since it is the only side holding
+the recorded values. It is matched in SQL, not in memory, so it composes with pagination and `meta.count`
+like every other filter.
+
+It deliberately does **not** match `operation`, `correlationKey`, `recordId`, `collection`, `status` or
+`timestamp`: machine identifiers nobody searches for, whose matches read as noise.
+
+A field masked by `redact` never matches — neither by its `[redacted]` mask nor by the value it hid, which
+was never recorded. A search must not confirm a value the trail refused to keep.
+
+`fields` matches whole keys, never paths, so a name holding a dot (`address.city`) is quoted before it
+reaches SQL. Both sides of the diff are searched, since a field the change added exists in `newValues`
+only and one it removed in `previousValues` only. The JSON test is per adapter (Postgres, SQLite, MySQL /
+MariaDB); on any other adapter the filter raises rather than silently returning everything.
+
+`startDate` / `endDate` are read as **local wall-clock time** in the request `timezone` query param
+(e.g. `Europe/Paris`, default `UTC`) and converted to a UTC instant before querying, so filtering
+happens in SQL. Two shapes are accepted:
+
+- **Bare day** `YYYY-MM-DD` — `startDate` snaps to `00:00:00.000`, `endDate` to `23:59:59.999`.
+- **Datetime** `YYYY-MM-DD[T| ]HH:mm[:ss]` — `T` or space separator, seconds optional; when seconds
+  are omitted `endDate` is completed to `:59.999` and `startDate` stays at `:00.000`.
+
+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**.
+
+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
+erroring. Sorting follows JSON:API `sort` on `timestamp`: `sort=-timestamp` (or absent/unrecognized)
+is newest first, `sort=timestamp` is oldest first. Ties on equal timestamps fall back to insertion
+order (the auto-increment `id`), so paging is deterministic in either direction.
+
+All routes serialize audit records the same way: top-level keys are camelCased — `id`, `recordId`, `userId`,
+`userFirstName`, `userLastName`, `userEmail`, `actionName`, `status`, `correlationKey`, `previousValues`,
+`newValues`. The row `id` is exposed because both agents order by `(timestamp, id)` and the front uses it as
+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 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
+audit trail, and the delete event itself is the last thing recorded.
+
+### State route
+
+`GET /forest/_audit-trail/{collection}/{recordId}/state?timestamp=…` returns the record as it stood at
+that instant, rebuilt by taking the record as it stands now and undoing every entry recorded **strictly
+after** the timestamp — an entry stamped exactly at it counts as part of that state:
+
+```json
+{ "data": { "status": "paid", "address": { "city": "Paris" } } }
+```
+
+`timestamp` accepts an ISO-8601 instant, or the same wall-clock forms as the filters above read in the
+request `timezone`; it is required (**400** otherwise). `data` is `null` when the record did not exist at
+that instant — either created later, or deleted and never recreated.
+
+Walking back stops being able to help where the trail stops: only audited (writable) columns are
+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.
+
+### Correlation route
+
+`GET /forest/_audit-trail/correlation/{correlationKey}` returns `{ "data": [...] }` — the
+operation(s) recorded under one `correlation_key` for a single record (usually one), oldest first, or
+an empty array if none. Scoped through query params; same auth and gating as above.
+
+| query param  | required | effect                                                       |
+| ------------ | -------- | ------------------------------------------------------------ |
+| `collection` | yes      | collection the record belongs to (also the permission scope) |
+| `recordId`   | yes      | packed record id to scope the lookup                         |
+
+A missing `collection` or `recordId` returns **HTTP 400** (`ValidationError`).
+
+### Batch correlation route
+
+`GET /forest/_audit-trail/correlations` returns `{ "data": [...] }` — a **flat** list of every record
+whose `correlation_key` is in `correlationKeys`, scoped to one record (the client groups by
+`correlation_key`). Same auth and gating; empty array when nothing matches.
+
+| query param       | required | effect                                                       |
+| ----------------- | -------- | ------------------------------------------------------------ |
+| `correlationKeys` | yes\*    | comma-separated keys; blank tokens are dropped               |
+| `collection`      | yes      | collection the record belongs to (also the permission scope) |
+| `recordId`        | yes      | packed record id to scope the lookup                         |
+
+\* To dodge any URL length limit, the same path also accepts **`POST`** with a JSON body
+`{ "correlationKeys": [...], "collection": "...", "recordId": "..." }` (the body array takes
+precedence over the query param). An empty/absent key list returns `{ "data": [] }` without hitting
+the store. A missing `collection` or `recordId` returns **HTTP 400** (`ValidationError`).
+
+## Smart actions
+
+Running a smart action writes one row per selected record, in the same table:
+
+| column           | value                                                                      |
+| ---------------- | -------------------------------------------------------------------------- |
+| `operation`      | `action` when it went through, `action_failed` when it raised or answered with an `Error` result |
+| `previousValues` | the submitted form values (redacted with the same `redact` config)          |
+| `newValues`      | what the action answered — an allowlist of the result: `type`, `message`, `name`, `mimeType`, `method`, `url`, `path`. Empty when it raised |
+| `recordId`       | each selected record — empty for a global action or a select-all selection  |
+
+The two value columns carry what went in and what came back, rather than a record's before and after. A
+result also holds the file's contents, a webhook's body and headers, and arbitrary response headers: file
+bytes have no business in an audit table and the other two routinely hold credentials, so the stored answer
+is an allowlist — a field added to a result later is not recorded until someone decides it should be. `html`
+is left out too, being operator-facing markup the message already summarises.
+
+Because these are the same columns the field filter searches, filtering by a field named like a result key
+(`message`, `type`) also matches action rows.
+
+**Which** action ran is not stored: the Forest activity logs already record it, and
+`correlationKey` is the join between the two.
+
+A **global** action targets no record, and a **select-all** selection only tells the agent which ids were
+*excluded*, so naming the targets would mean querying the whole selection: those runs are recorded once,
+attached to no record.
+
+Recording follows the same policy as a write: the row goes in before the action runs, so under
+`critical: false` a failing audit database logs an error and the action goes ahead, while under
+`critical: true` it refuses the run — nothing has happened yet, so there is nothing to repair. Everything
+after that point, the answer included, is best-effort either way.
+
+**A row attached to no record is not readable through any route today.** Every history route is scoped to a
+record id, and the correlation routes reject an empty one, so global and over-cap action runs are recorded but
+cannot be fetched. They are evidence in the table rather than something the UI can show — reaching them needs
+a collection-level endpoint that does not exist yet.
+
+The targeted records are read back through the caller's own filter rather than taken from the request: the ids
+a client sends are a claim, and in a compliance record asserting that an operator acted on a record their
+scope excludes is worse than a missing row.
+
+`url` and `path` are sanitised before storage — credentials in the userinfo and anything in a query string or
+fragment come off, since either can carry a signed one-time token that would otherwise sit permanently in the
+one table nobody deletes from.
+
+> **What an action changes is only audited when it goes through Forest.** `context.collection.update(...)`
+> passes through the same hooks as any other write, so it produces the usual field-level rows sharing the
+> action's `correlationKey`. A direct ORM write (`Customer.find(id).update!(...)`) is invisible to the
+> agent, so nothing is recorded for it beyond the invocation row above.
+
+## What gets stored
+
+`forest.audit_logs`, one row per audited change:
+
+| column            | description                                                 |
+| ----------------- | ----------------------------------------------------------- |
+| `id`              | auto-increment primary key, exposed in the payload           |
+| `status`          | `pending` before the write, `done` once confirmed            |
+| `timestamp`       | when the change happened                                    |
+| `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                                       |
+| `correlation_key` | per-request id; groups every change made within one request. Empty for a write outside any request — inventing one would make the row look like a single-row request of its own |
+| `previous_values` | values before the change (JSON)                             |
+| `new_values`      | values after the change (JSON)                              |
+
+`previous_values` / `new_values` store **only the parts that actually changed**: nested hashes and
+arrays of hashes are diffed structurally, so a single sub-field change records just that leaf. Only
+writable columns are audited — read-only, computed and DB-managed fields are never written by Forest.
+
+The `correlation_key` is the agent's per-request id (`caller.request_id`), generated by the agent and echoed
+back to the client in the `X-Forest-Correlation-Id` response header — so every change made in one request
+shares a key, and the caller can tie it to its own activity log.
+
+Outside Rails, mount `ForestAdminAgent::Http::CorrelationIdMiddleware` yourself: it resets the id at the start
+of each request, and without it a pooled thread would hand its previous request's key to the next one.
+
+The capture layer registers its **after** hooks ahead of any other customization's (`prepend: true`,
+since `execute_after` stops at the first exception, and by then the write has already happened) and its
+**before** hooks after them, so the snapshot sees the filter and patch everyone else has had their say on.
+
+## Concurrent writes to one record
+
+The before/after values are captured around the write, not inside it: the customizer hooks bracket the
+write as separate calls, and the data layer deliberately exposes no lock or transaction primitive since
+it spans ActiveRecord, Mongoid, HTTP APIs and more.
+
+So when two writes race on the same record, both snapshot the same state and the one that lands second
+records a `previousValues` that had already been overwritten. `newValues` is always exact — it is the
+patch that was written — and no row is ever lost; only the prior state of an overlapping write can be
+stale. Exact before-images under concurrency need the database itself (triggers, or CDC), not an agent
+hook.
+
+## Schema migrations & concurrency
+
+The table is created and evolved through an ordered, append-only migration list, tracked in a companion table
+named after the audited one — `forest.audit_logs_migration` beside `forest.audit_logs`. One tracker per audited
+table, so two stores configured with different `table_name`s each keep their own schema history rather than
+reading the other's as done.
+
+On Postgres the migrations run inside a transaction-scoped advisory lock, so several agents booting at once
+apply them one after another; the schema is created (and committed, idempotently) first, since the lock cannot
+cover a schema that does not exist yet.

data/lib/forest_admin_agent/audit_trail/action_capture.rb

@@ -0,0 +1,99 @@
+require 'uri'
+
+module ForestAdminAgent
+  module AuditTrail
+    # Records smart-action runs into the same table as the field-level history: the submitted form on the
+    # `previous_values` side, what the action answered on the `new_values` side.
+    #
+    # {Capture} cannot see them — the customizer has no `Execute` hook — and an action's writes are only
+    # audited when they go through the Forest data layer, so a direct ORM write stays invisible. What lands
+    # here is the run itself: who ran which action, on which records, with which form, and how it ended.
+    #
+    # Same protocol as a write: {#pending} before the action, {#confirm} after. The route owns the gate, so a
+    # pending insert that fails refuses the run under `critical: true`.
+    class ActionCapture
+      include Recording
+
+      EXECUTED = 'action'.freeze
+      FAILED = 'action_failed'.freeze
+      # A global action, and a bulk run over a selection wider than the cap, name no single target: they get
+      # one row attached to no record rather than none at all.
+      NO_RECORD = ''.freeze
+      # What of the action's answer is worth keeping — an allowlist, not a denylist: a result also carries the
+      # file's contents, a webhook's body and headers and arbitrary response headers. File bytes have no
+      # business in an audit table and the other two routinely hold credentials, and an allowlist means a field
+      # added to a result later is not stored until someone decides it should be. `html` is left out too:
+      # operator-facing markup, sometimes large, and the message already says what happened.
+      RESULT_FIELDS = %i[type message name mime_type method url path].freeze
+      # Either can carry userinfo credentials or a signed one-time token, which would then sit permanently in
+      # the one table nobody deletes from.
+      URL_FIELDS = %i[url path].freeze
+
+      def initialize(store, redact = {})
+        @store = store
+        @redact = redact || {}
+      end
+
+      # One row per targeted record, provisionally an `action` — {#confirm} settles which it really was. Returns
+      # the row ids to confirm.
+      def pending(caller:, collection:, action_name:, form_values:, record_ids:)
+        return [] unless @store
+
+        timestamp = now
+        correlation_key = correlation_key_for(caller)
+        identity = identity_of(caller)
+        submitted = redact(form_values || {}, @redact[collection] || [])
+        ids = record_ids.empty? ? [NO_RECORD] : record_ids
+
+        @store.append_all(
+          ids.map do |record_id|
+            AuditRecord.new(
+              timestamp: timestamp, operation: EXECUTED, collection: collection, record_id: record_id,
+              status: PENDING, action_name: action_name, correlation_key: correlation_key,
+              previous_values: submitted, new_values: {}, **identity
+            )
+          end
+        )
+      end
+
+      # Best-effort: the action has already run, so a failure here loses the answer, never the run.
+      def confirm(ids, result: nil, failed: false)
+        return if ids.nil? || ids.empty?
+
+        audit_safely do
+          answer = summarize(result)
+
+          ids.each { |id| @store.confirm(id, operation: failed ? FAILED : EXECUTED, new_values: answer) }
+        end
+      end
+
+      private
+
+      # Keys of an action's answer are Forest's own, so they are camelCase on the wire — unlike a record's
+      # column names, which pass through untouched.
+      def summarize(result)
+        return {} unless result.is_a?(Hash)
+
+        result.slice(*RESULT_FIELDS).compact.to_h do |field, value|
+          [field.to_s.camelize(:lower), URL_FIELDS.include?(field) ? sanitize_url(value) : value]
+        end
+      end
+
+      # `userinfo = nil` is a no-op on URI, so the credentials come off textually; the parser then takes care
+      # of the query and fragment.
+      def sanitize_url(value)
+        # Both `https://user:pass@host` and the scheme-relative `//user:pass@host`, which parses fine and
+        # would otherwise keep its credentials.
+        bare = value.to_s.sub(%r{\A([a-z][a-z0-9+.-]*:)?//[^/@]*@}i, '\1//')
+        uri = URI.parse(bare)
+        uri.query = nil
+        uri.fragment = nil
+
+        uri.to_s
+      rescue StandardError
+        # Not something the parser accepts: keep the shape, drop everything that can carry a secret.
+        bare.to_s.split(/[?#]/).first.to_s
+      end
+    end
+  end
+end

data/lib/forest_admin_agent/audit_trail/audit_record.rb

@@ -0,0 +1,16 @@
+module ForestAdminAgent
+  module AuditTrail
+    # One audited change. Mirrors the columns of `forest.audit_logs`.
+    #
+    # The actor's name and email are denormalised from the caller at write time: the row says who acted then,
+    # not whoever holds that user id today. `action_name` is set on smart-action rows only, and `status`
+    # 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,
+      :user_id, :user_first_name, :user_last_name, :user_email, :action_name,
+      :correlation_key, :previous_values, :new_values,
+      keyword_init: true
+    )
+  end
+end