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>

store/memory.go

@@ -1,6 +1,7 @@
 package store
 
 import (
+	"encoding/json"
 	"sync"
 
 	"git.flowmade.one/flowmade-one/aether"
@@ -21,9 +22,32 @@ func NewInMemoryEventStore() *InMemoryEventStore {
 	}
 }
 
+// deepCopyEvent creates a deep copy of an event to ensure immutability.
+// This prevents modifications to the event after it's been persisted.
+func deepCopyEvent(event *aether.Event) *aether.Event {
+	// Use JSON marshaling/unmarshaling for a complete deep copy
+	// This ensures all nested structures (maps, slices) are copied
+	data, _ := json.Marshal(event)
+	var copy aether.Event
+	json.Unmarshal(data, &copy)
+
+	// Preserve empty metadata maps (JSON unmarshal converts empty map to nil)
+	if event.Metadata != nil && len(event.Metadata) == 0 && copy.Metadata == nil {
+		copy.Metadata = make(map[string]string)
+	}
+
+	// Preserve empty data maps
+	if event.Data != nil && len(event.Data) == 0 && copy.Data == nil {
+		copy.Data = make(map[string]interface{})
+	}
+
+	return &copy
+}
+
 // SaveEvent saves an event to the in-memory store.
 // Returns VersionConflictError if the event's version is not strictly greater
 // than the current latest version for the actor.
+// The event is deep-copied before storage to ensure immutability.
 func (es *InMemoryEventStore) SaveEvent(event *aether.Event) error {
 	es.mu.Lock()
 	defer es.mu.Unlock()
@@ -50,11 +74,15 @@ func (es *InMemoryEventStore) SaveEvent(event *aether.Event) error {
 	if _, exists := es.events[event.ActorID]; !exists {
 		es.events[event.ActorID] = make([]*aether.Event, 0)
 	}
-	es.events[event.ActorID] = append(es.events[event.ActorID], event)
+
+	// Deep copy the event before storing to ensure immutability
+	storedEvent := deepCopyEvent(event)
+	es.events[event.ActorID] = append(es.events[event.ActorID], storedEvent)
 	return nil
 }
 
 // GetEvents retrieves events for an actor from a specific version
+// Returns deep copies of events to ensure immutability
 func (es *InMemoryEventStore) GetEvents(actorID string, fromVersion int64) ([]*aether.Event, error) {
 	es.mu.RLock()
 	defer es.mu.RUnlock()
@@ -67,7 +95,8 @@ func (es *InMemoryEventStore) GetEvents(actorID string, fromVersion int64) ([]*a
 	var filteredEvents []*aether.Event
 	for _, event := range events {
 		if event.Version >= fromVersion {
-			filteredEvents = append(filteredEvents, event)
+			// Return a deep copy to ensure immutability
+			filteredEvents = append(filteredEvents, deepCopyEvent(event))
 		}
 	}