Add event versioning validation

- Add ErrVersionConflict error type and VersionConflictError for detailed
  conflict information
- Implement version validation in InMemoryEventStore.SaveEvent that rejects
  events with version <= current latest version
- Implement version validation in JetStreamEventStore.SaveEvent with version
  caching for performance
- Add comprehensive tests for version conflict detection including concurrent
  writes to same actor
- Document versioning semantics in EventStore interface and CLAUDE.md

This ensures events have monotonically increasing versions per actor and
provides clear error messages for version conflicts, enabling optimistic
concurrency control patterns.

Closes #6

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

event.go

@@ -1,9 +1,33 @@
 package aether
 
 import (
+	"errors"
+	"fmt"
 	"time"
 )
 
+// ErrVersionConflict is returned when attempting to save an event with a version
+// that is not strictly greater than the current latest version for an actor.
+// This ensures events have monotonically increasing versions per actor.
+var ErrVersionConflict = errors.New("version conflict")
+
+// VersionConflictError provides details about a version conflict.
+// It is returned when SaveEvent is called with a version <= the current latest version.
+type VersionConflictError struct {
+	ActorID          string
+	AttemptedVersion int64
+	CurrentVersion   int64
+}
+
+func (e *VersionConflictError) Error() string {
+	return fmt.Sprintf("%s: actor %q has version %d, cannot save version %d",
+		ErrVersionConflict, e.ActorID, e.CurrentVersion, e.AttemptedVersion)
+}
+
+func (e *VersionConflictError) Unwrap() error {
+	return ErrVersionConflict
+}
+
 // Event represents a domain event in the system
 type Event struct {
 	ID        string                 `json:"id"`
@@ -23,10 +47,36 @@ type ActorSnapshot struct {
 	Timestamp time.Time              `json:"timestamp"`
 }
 
-// EventStore defines the interface for event persistence
+// EventStore defines the interface for event persistence.
+//
+// # Version Semantics
+//
+// Events for an actor must have monotonically increasing versions. When SaveEvent
+// is called, the implementation must validate that the event's version is strictly
+// greater than the current latest version for that actor. If the version is less
+// than or equal to the current version, SaveEvent must return a VersionConflictError
+// (which wraps ErrVersionConflict).
+//
+// This validation ensures event stream integrity and enables optimistic concurrency
+// control. Clients should:
+//  1. Call GetLatestVersion to get the current version for an actor
+//  2. Set the new event's version to currentVersion + 1
+//  3. Call SaveEvent - if it returns ErrVersionConflict, another writer won
+//  4. On conflict, reload the latest version and retry if appropriate
+//
+// For new actors (no existing events), version 1 is expected for the first event.
 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.
 	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.
 	GetEvents(actorID string, fromVersion int64) ([]*Event, error)
+
+	// GetLatestVersion returns the latest version for an actor.
+	// Returns 0 if no events exist for the actor.
 	GetLatestVersion(actorID string) (int64, error)
 }