The Event Chain — Every Write, Recorded Forever

The event chain is an immutable audit log of every mutation in your pod. Every entity creation, every property update, every AI action — recorded, reviewable, and reversible. Trust by architecture, not by policy.

Why an event chain?

Traditional apps trust their own code. If a bug corrupts data, you hope a backup exists. If an AI hallucinates and writes garbage, you may never know what changed. Synap takes a different approach: every write operation is recorded as an immutable event before it takes effect. This means you always have a complete history of what happened, who did it, when, and why.

The event chain is not a feature you opt into — it is the foundation of every write path in Synap. User actions, AI mutations, and connector syncs all flow through it. There is no way to write data without creating an event.

What gets recorded

Every mutation to your data pod generates an event with a timestamp, the actor (user ID, agent ID, or connector ID), the operation type (create, update, delete), the target entity or resource, and a snapshot of what changed — both the previous and new values. Events are append-only. They cannot be edited or deleted.

• User writes — Direct mutations through the UI or API. Creating an entity, updating a property, deleting a view.
• AI mutations — Everything the AI does: creating entities from captures, updating properties based on conversation, linking related entities.
• Connector syncs — Data pulled from external services like Google Calendar, GitHub, or email. Each synced item produces an event.

The proposal system

Not all writes are equal. Direct user actions — clicking a button, typing in a field — go through the standard tRPC/Drizzle write path and are recorded immediately. But AI agent mutations and external connector syncs go through a different gate: checkPermissionOrPropose().

This function checks whether the action is auto-approved (based on RBAC roles and a configurable whitelist) or requires human review. If review is needed, the action becomes a proposal — a pending mutation that sits in your proposals queue until you approve, reject, or edit it.

The proposal flow

• AI agent decides to create or modify an entity
• The backend checks checkPermissionOrPropose()
• If auto-approved: the mutation executes immediately and an event is recorded
• If not: a proposal is created with the full mutation payload
• You see the proposal in your queue (badge in the sidebar)
• You approve (mutation executes), reject (nothing happens), or edit (modify then execute)
• The final action and your decision are both recorded as events

What the event chain enables

• Undo and redo — Every mutation has a before-state snapshot. Reversing an action means applying the previous state.
• Time travel — Browse the state of any entity at any point in time. See what a task looked like last Tuesday or who changed a deal's stage.
• Audit trail — Complete accountability for every change. Essential for compliance, debugging, and understanding how your data evolved.
• Rollback — Undo an entire sequence of changes. If an AI agent made a series of bad updates, roll them all back in one action.
• Conflict resolution — When multiple actors modify the same entity, the event chain provides the authoritative sequence of operations.

Event chain vs. git

If you are familiar with git, the event chain might sound similar — and the concepts do overlap. But there are key differences. The event chain is real-time (events are recorded as they happen, not in batches), automatic (no manual commits), and per-mutation (each property change is its own event, not grouped into files). You do not need to "save" or "commit" — every action is captured the moment it occurs.

Permission configuration

The auto-approve behavior is configurable per workspace. A DEFAULT_AUTO_APPROVE whitelist defines which operations are safe enough to skip review (for example, AI reading data is always approved, while AI deleting entities always requires review). Workspace admins can override these defaults to be more permissive or more restrictive based on their needs.

Related guides