docs: Verify and document append-only immutability guarantees
Document that EventStore interface has no Update/Delete methods, enforcing append-only semantics by design. Events are immutable once persisted. Changes: - Update EventStore interface documentation in event.go to explicitly state immutability guarantee and explain why Update/Delete methods are absent - Add detailed retention policy documentation to JetStreamConfig showing how MaxAge limits enforce automatic expiration without manual deletion - Document JetStreamEventStore's immutability guarantee with storage-level explanation of file-based storage and limits-based retention - Add comprehensive immutability tests verifying: - Events cannot be modified after persistence - No Update or Delete methods exist on EventStore interface - Versions are monotonically increasing - Events cannot be deleted through the API - Update README with detailed immutability section explaining: - Interface-level append-only guarantee - Storage-level immutability through JetStream configuration - Audit trail reliability - Pattern for handling corrections (append new event) Closes #60 Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
29
README.md
29
README.md
@@ -107,7 +107,34 @@ Order state after replaying 2 events:
|
||||
|
||||
### Events are immutable
|
||||
|
||||
Events represent facts about what happened. Once saved, they are never modified - you only append new events.
|
||||
Events represent facts about what happened. Once saved, they are never modified or deleted - you only append new events. This immutability guarantee is enforced at multiple levels:
|
||||
|
||||
**Interface Design**: The `EventStore` interface provides no Update or Delete methods. Only `SaveEvent` (append), `GetEvents` (read), and `GetLatestVersion` (read) are available.
|
||||
|
||||
**JetStream Storage**: When using `JetStreamEventStore`, events are stored in a NATS JetStream stream configured with:
|
||||
- File-based storage (durable)
|
||||
- Limits-based retention policy (events expire after configured duration, not before)
|
||||
- No mechanism to modify or delete individual events during their lifetime
|
||||
|
||||
**Audit Trail Guarantee**: Because events are immutable once persisted, they serve as a trustworthy audit trail. You can rely on the fact that historical events won't change, enabling compliance and forensics.
|
||||
|
||||
To correct a mistake, append a new event that expresses the correction rather than modifying history:
|
||||
|
||||
```go
|
||||
// Wrong: Cannot update an event
|
||||
// store.UpdateEvent(eventID, newData) // This method doesn't exist
|
||||
|
||||
// Right: Append a new event that corrects the record
|
||||
correctionEvent := &aether.Event{
|
||||
ID: uuid.New().String(),
|
||||
EventType: "OrderCorrected",
|
||||
ActorID: orderID,
|
||||
Version: currentVersion + 1,
|
||||
Data: map[string]interface{}{"reason": "price adjustment"},
|
||||
Timestamp: time.Now(),
|
||||
}
|
||||
err := store.SaveEvent(correctionEvent)
|
||||
```
|
||||
|
||||
### State is derived
|
||||
|
||||
|
||||
Reference in New Issue
Block a user