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

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:
Claude Code
2026-01-13 21:26:16 +01:00
parent bcbec9ab94
commit 69da1d800e
5 changed files with 276 additions and 3 deletions

View File

@@ -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).