Add confirmed audit reversals

docs/architecture.md

@@ -83,3 +83,33 @@ The restore operation refuses to import into any database containing records.
 This guard prevents accidental merging or overwriting of contributor data.
 Stop the application before backup or restore so the embedded database file is
 not locked by another process.
+
+# ISAC audit and compensating reversals
+
+Every successful ISAC mutation appends an event to `audit_log` through the
+shared server audit utility. Events identify the operator, operational category,
+specific action, target entity, timestamp, and useful before/after evidence.
+The audit registry is read-only and requires `audit.view`; the seeded Auditor
+role grants that permission without granting mutation capabilities.
+
+Audit history is immutable. “Revert” is implemented as a new compensating
+mutation rather than deletion or modification of the original event:
+
+1. The operator must independently hold `audit.revert`.
+2. The original action must be explicitly supported and contain a usable
+   before-snapshot.
+3. The UI requires a second, explicit confirmation.
+4. The server reloads the target and compares it with the original
+   after-snapshot, ignoring bookkeeping timestamps. A mismatch means newer work
+   exists and blocks automatic compensation.
+5. Referenced roles, permissions, and relationships are revalidated before
+   restoration. Restoring administrator authority additionally requires full
+   administrative access.
+6. The server restores the previous state and appends an `audit.reverted` event
+   whose target is the original audit-event ID.
+7. A successfully reverted event cannot be reverted again.
+
+Unsupported destructive identity operations, account deletion, incomplete
+snapshots, stale targets, and events whose dependencies no longer exist are
+marked non-reversible or rejected. Recovery for those cases requires a
+specialized workflow rather than inferred database writes.