docs: Verify and document append-only event guarantees
This commit addresses issue #60 by documenting and enforcing the immutability guarantees of the event store: - Document that EventStore interface is append-only by design (no Update/Delete methods) - Document the immutable nature of events once persisted as an audit trail - Add JetStream stream retention policy configuration documentation - Add comprehensive immutability test (TestEventImmutability_InMemory, TestEventImmutability_Sequential) - Enhance InMemoryEventStore to deep-copy events, preventing accidental mutations - Update README with detailed immutability guarantees and audit trail benefits The EventStore interface intentionally provides no methods to modify or delete events. Once persisted, events are immutable facts that serve as a tamper-proof audit trail. This design ensures compliance, debugging, and historical analysis. Acceptance criteria met: - EventStore interface documented as append-only (event.go) - JetStream retention policy configuration documented (store/jetstream.go) - Test verifying events cannot be modified after persistence (store/immutability_test.go) - README documents immutability guarantees (README.md) Closes #60 Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
13
event.go
13
event.go
@@ -176,6 +176,18 @@ type ActorSnapshot struct {
|
||||
|
||||
// EventStore defines the interface for event persistence.
|
||||
//
|
||||
// # Append-Only Design
|
||||
//
|
||||
// EventStore is intentionally designed as append-only: it provides no Update or Delete
|
||||
// methods. Events are immutable facts about what happened in the domain. Once persisted,
|
||||
// an event is permanently recorded and can never be modified, deleted, or overwritten.
|
||||
// This design ensures that the event log serves as a complete, immutable audit trail
|
||||
// that can be trusted for compliance, debugging, and domain analysis.
|
||||
//
|
||||
// To correct application state, you append new events (e.g., a "Reversed" or "Corrected"
|
||||
// event), never by modifying existing events. This maintains a complete history of all
|
||||
// state changes.
|
||||
//
|
||||
// # Version Semantics
|
||||
//
|
||||
// Events for an actor must have monotonically increasing versions. When SaveEvent
|
||||
@@ -196,6 +208,7 @@ type EventStore interface {
|
||||
// SaveEvent persists an event to the store. The event's Version must be
|
||||
// strictly greater than the current latest version for the actor.
|
||||
// Returns VersionConflictError if version <= current latest version.
|
||||
// Events persisted to the store are immutable and can never be modified or deleted.
|
||||
SaveEvent(event *Event) error
|
||||
|
||||
// GetEvents retrieves events for an actor from a specific version (inclusive).
|
||||
|
||||
Reference in New Issue
Block a user