ShrubberyDocs
Sign in

Audit Trail

Definition

The immutable, chronological event log that records every state change on a Shrubbery row, along with the actor who caused it and the time it occurred. The Audit Trail is the record of the act — the Handshake, the Renegotiation, the Completion — not the state itself.

Avoid: history, log, changelog.

Role

The Audit Trail is the source of truth for everything that happened to a Shrubbery. It backs the timeline view in the Detail Sheet, the actor attribution on the Dossier, and any compliance or accountability review.

Each event captures:

  • event_type — the action that occurred: created, handshake_accepted, handshake_refused, renegotiated, edited, completed, status_synced.
  • actor_id — the user who acted, if the actor was a human.
  • actor_kind — user for in-app actions, api_token for actions via the Sync API or Inbox API.
  • created_at — the timestamp of the event.
  • metadata — a JSON blob for event-specific context (e.g. which fields changed in a Renegotiation, the old and new deadline).

Events are append-only — no event is ever deleted or modified. A soft-deleted Shrubbery retains its audit events.

Lifecycle

Not a stateful concept. The Audit Trail is an append-only log; it does not have states.

Events are written synchronously with each state transition. There is no background queue — if the state transition commits, the audit event is present.

Last updated: 22 June 2026