docs: Verify and document append-only immutability guarantees
Some checks failed
CI / build (pull_request) Successful in 22s
CI / build (push) Successful in 21s
CI / integration (pull_request) Failing after 1m59s
CI / integration (push) Failing after 2m0s

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 was merged in pull request #136.
This commit is contained in:
Claude Code
2026-01-13 21:45:26 +01:00
committed by Hugo Nijhuis
parent 464fed67ec
commit 6549125f3d
4 changed files with 280 additions and 8 deletions

View File

@@ -184,6 +184,17 @@ type ActorSnapshot struct {
// EventStore defines the interface for event persistence.
//
// # Immutability Guarantee
//
// EventStore is append-only. Once an event is persisted via SaveEvent, it is never
// modified or deleted. The interface intentionally provides no Update or Delete methods.
// This ensures:
// - Events serve as an immutable audit trail
// - State can be safely derived by replaying events
// - Concurrent reads are always safe (events never change)
//
// To correct a mistake, append a new event that expresses the correction.
//
// # Version Semantics
//
// Events for an actor must have monotonically increasing versions. When SaveEvent
@@ -204,10 +215,13 @@ 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.
// Once saved, the event is immutable and can never be modified or deleted.
SaveEvent(event *Event) error
// GetEvents retrieves events for an actor from a specific version (inclusive).
// Returns an empty slice if no events exist for the actor.
// The returned events are guaranteed to be immutable - they will never be
// modified or deleted from the store.
GetEvents(actorID string, fromVersion int64) ([]*Event, error)
// GetLatestVersion returns the latest version for an actor.