gram-audit-logging
Audit logging is how Gram records who did what to which resource. Every meaningful mutation on a project- or org-scoped resource is expected to produce one audit entry per affected row, written inside the same database transaction as the mutation so events can't drift from the state they describe. Entries are exposed to Gram users through the auditlogs management API.
Concepts and terminology
Actor. The principal that caused the event — a urn.Principal carrying a type (user, role, service account) and an id, with optional display name and slug for human rendering.
Subject. The resource the event is about — identified by a subject type (e.g. remote_mcp_server, access_role) and a subject id.
Action. What happened to the subject. Each subject declares its own set of actions, typically one per mutating verb on the subject's life cycle.
Before/after snapshot. Optional opaque JSON payloads describing the subject's state. Populated on updates, left empty on creates and deletes unless the snapshot is independently useful.
Metadata. Optional JSON bag for contextual fields that are not part of the subject's state.
Scoping. Every entry belongs to exactly one organization and zero or one projects. Org-scoped subjects (roles, members) carry no project id; project-scoped subjects carry the project UUID.
Atomicity. Audit entries are written inside the same database transaction as the mutation they describe, so the state and the record of the state commit together or not at all.