test(event): Add comprehensive VersionConflictError tests and retry pattern examples

Implement comprehensive tests for VersionConflictError in event_test.go covering:
- Error message formatting with all context fields
- Field accessibility (ActorID, AttemptedVersion, CurrentVersion)
- Unwrap method for error wrapping
- errors.Is sentinel checking
- errors.As type assertion
- Application's ability to read CurrentVersion for retry strategies
- Edge cases including special characters and large version numbers

Add examples/ directory with standard retry patterns:
- SimpleRetryPattern: Basic retry with exponential backoff
- ConflictDetailedRetryPattern: Intelligent retry with conflict analysis
- JitterRetryPattern: Prevent thundering herd with randomized backoff
- AdaptiveRetryPattern: Adjust backoff based on contention level
- EventualConsistencyPattern: Asynchronous retry via queue
- CircuitBreakerPattern: Prevent cascading failures

Includes comprehensive documentation in examples/README.md explaining each
pattern's use cases, performance characteristics, and implementation guidance.

Closes #62

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

event_test.go

@@ -2,6 +2,8 @@ package aether
 
 import (
 	"encoding/json"
+	"errors"
+	"fmt"
 	"strings"
 	"testing"
 	"time"
@@ -1335,3 +1337,190 @@ func TestReplayError_WithLargeRawData(t *testing.T) {
 	// Error() should still work
 	_ = err.Error()
 }
+
+// Tests for VersionConflictError
+
+func TestVersionConflictError_Error(t *testing.T) {
+	err := &VersionConflictError{
+		ActorID:          "order-123",
+		AttemptedVersion: 3,
+		CurrentVersion:   5,
+	}
+
+	errMsg := err.Error()
+
+	// Verify error message contains all context
+	if !strings.Contains(errMsg, "order-123") {
+		t.Errorf("error message should contain ActorID, got: %s", errMsg)
+	}
+	if !strings.Contains(errMsg, "3") {
+		t.Errorf("error message should contain AttemptedVersion, got: %s", errMsg)
+	}
+	if !strings.Contains(errMsg, "5") {
+		t.Errorf("error message should contain CurrentVersion, got: %s", errMsg)
+	}
+	if !strings.Contains(errMsg, "version conflict") {
+		t.Errorf("error message should contain 'version conflict', got: %s", errMsg)
+	}
+}
+
+func TestVersionConflictError_Fields(t *testing.T) {
+	err := &VersionConflictError{
+		ActorID:          "actor-456",
+		AttemptedVersion: 10,
+		CurrentVersion:   8,
+	}
+
+	if err.ActorID != "actor-456" {
+		t.Errorf("ActorID mismatch: got %q, want %q", err.ActorID, "actor-456")
+	}
+	if err.AttemptedVersion != 10 {
+		t.Errorf("AttemptedVersion mismatch: got %d, want %d", err.AttemptedVersion, 10)
+	}
+	if err.CurrentVersion != 8 {
+		t.Errorf("CurrentVersion mismatch: got %d, want %d", err.CurrentVersion, 8)
+	}
+}
+
+func TestVersionConflictError_Unwrap(t *testing.T) {
+	err := &VersionConflictError{
+		ActorID:          "actor-789",
+		AttemptedVersion: 2,
+		CurrentVersion:   1,
+	}
+
+	unwrapped := err.Unwrap()
+	if unwrapped != ErrVersionConflict {
+		t.Errorf("Unwrap should return ErrVersionConflict sentinel")
+	}
+}
+
+func TestVersionConflictError_ErrorsIs(t *testing.T) {
+	err := &VersionConflictError{
+		ActorID:          "test-actor",
+		AttemptedVersion: 5,
+		CurrentVersion:   4,
+	}
+
+	// Test that errors.Is works with sentinel
+	if !errors.Is(err, ErrVersionConflict) {
+		t.Error("errors.Is(err, ErrVersionConflict) should return true")
+	}
+
+	// Test that other errors don't match
+	if errors.Is(err, errors.New("other error")) {
+		t.Error("errors.Is should not match unrelated errors")
+	}
+}
+
+func TestVersionConflictError_ErrorsAs(t *testing.T) {
+	originalErr := &VersionConflictError{
+		ActorID:          "actor-unwrap",
+		AttemptedVersion: 7,
+		CurrentVersion:   6,
+	}
+
+	var versionErr *VersionConflictError
+	if !errors.As(originalErr, &versionErr) {
+		t.Fatalf("errors.As should succeed with VersionConflictError")
+	}
+
+	// Verify fields are accessible through unwrapped error
+	if versionErr.ActorID != "actor-unwrap" {
+		t.Errorf("ActorID mismatch after As: got %q", versionErr.ActorID)
+	}
+	if versionErr.AttemptedVersion != 7 {
+		t.Errorf("AttemptedVersion mismatch after As: got %d", versionErr.AttemptedVersion)
+	}
+	if versionErr.CurrentVersion != 6 {
+		t.Errorf("CurrentVersion mismatch after As: got %d", versionErr.CurrentVersion)
+	}
+}
+
+func TestVersionConflictError_CanReadCurrentVersion(t *testing.T) {
+	// This test verifies that applications can read CurrentVersion for retry strategies
+	err := &VersionConflictError{
+		ActorID:          "order-abc",
+		AttemptedVersion: 2,
+		CurrentVersion:   10,
+	}
+
+	var versionErr *VersionConflictError
+	if !errors.As(err, &versionErr) {
+		t.Fatal("failed to unwrap VersionConflictError")
+	}
+
+	// Application can use CurrentVersion to decide retry strategy
+	nextVersion := versionErr.CurrentVersion + 1
+
+	if nextVersion != 11 {
+		t.Errorf("application should be able to compute next version: got %d, want 11", nextVersion)
+	}
+
+	// Application can log detailed context
+	logMsg := fmt.Sprintf("Version conflict for actor %q: attempted %d, current %d, will retry with %d",
+		versionErr.ActorID, versionErr.AttemptedVersion, versionErr.CurrentVersion, nextVersion)
+
+	if !strings.Contains(logMsg, "order-abc") {
+		t.Errorf("application context logging failed: %s", logMsg)
+	}
+}
+
+func TestVersionConflictError_EdgeCases(t *testing.T) {
+	testCases := []struct {
+		name    string
+		actorID string
+		attemp  int64
+		current int64
+	}{
+		{"zero current", "actor-1", 1, 0},
+		{"large numbers", "actor-2", 1000000, 999999},
+		{"max int64", "actor-3", 9223372036854775807, 9223372036854775806},
+		{"negative attempt", "actor-4", -1, -2},
+		{"empty actor id", "", 1, 0},
+		{"special chars in actor id", "actor@#$%", 2, 1},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := &VersionConflictError{
+				ActorID:          tc.actorID,
+				AttemptedVersion: tc.attemp,
+				CurrentVersion:   tc.current,
+			}
+
+			// Should not panic
+			msg := err.Error()
+			if msg == "" {
+				t.Error("Error() should return non-empty string")
+			}
+
+			// Should be wrapped correctly
+			if err.Unwrap() != ErrVersionConflict {
+				t.Error("Unwrap should return ErrVersionConflict")
+			}
+
+			// errors.Is should work
+			if !errors.Is(err, ErrVersionConflict) {
+				t.Error("errors.Is should work for edge case")
+			}
+		})
+	}
+}
+
+func TestErrVersionConflict_Sentinel(t *testing.T) {
+	// Verify the sentinel error is correctly defined
+	if ErrVersionConflict == nil {
+		t.Fatal("ErrVersionConflict should not be nil")
+	}
+
+	expectedMsg := "version conflict"
+	if ErrVersionConflict.Error() != expectedMsg {
+		t.Errorf("ErrVersionConflict message mismatch: got %q, want %q", ErrVersionConflict.Error(), expectedMsg)
+	}
+
+	// Test that it's usable with errors.Is
+	if !errors.Is(ErrVersionConflict, ErrVersionConflict) {
+		t.Error("ErrVersionConflict should match itself with errors.Is")
+	}
+}