feat: add state package implementing Durable Streams State Protocol (#50

)

* feat: add state package implementing Durable Streams State Protocol

Add an optional `state/` package that provides database-style state synchronization semantics on top of ebu's event bus. This enables interoperability with the durable-streams ecosystem while keeping core ebu unchanged.

Key features:
- Type-safe helpers (Insert, Update, Delete) using Go generics
- Options pattern for message configuration (TxID, timestamps)
- Materializer that builds typed state from events
- Full JSON interoperability with State Protocol spec
- 100% test coverage

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* fix: add mutex protection for lastOffset in Materializer

Fixes a potential race condition where lastOffset was being written in
Apply() and read in LastOffset() without synchronization. Now both
reads and writes are protected by the RWMutex.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* fix: handle nil entity in EntityType() to prevent panic

Add nil check in EntityType() to return "nil" string instead of
panicking when reflect.TypeOf(nil).String() is called.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* docs: add State Protocol section to README

Document the new optional state package that implements the Durable
Streams State Protocol for database-style state synchronization.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

---------

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Release v0.10.0

BREAKING CHANGES:

EventStore Interface Redesign (#43):
- Replaced int64 positions with opaque Offset type (string)
- New constants: OffsetOldest (""), OffsetNewest ("$")
- EventStore reduced to 2 core methods: Append and Read
- New optional interfaces: EventStoreStreamer, EventStoreSubscriber
- Separate SubscriptionStore interface for position tracking
- SubscribeWithReplay now requires context.Context as first parameter
- New options: WithSubscriptionStore, WithReplayBatchSize

SQLite Store Updates (#45):
- Method renames: Save→Append, Load→Read, LoadStream→ReadStream
- Subscription methods renamed: SaveSubscriptionPosition→SaveOffset, etc.
- Removed GetPosition method
- Updated MetricsHook interface

Durable-Streams Store Rewrite (#48):
- New signature: New(baseURL, streamPath, opts...) instead of New(streamURL)
- Removed WithRetry() option (handled by underlying client library)
- Now uses conformance-tested ahimsalabs/durable-streams-go client

This release enables support for remote storage backends like durable-streams
that use opaque string offsets rather than sequential integers.

perf: optimize streaming with filtered snapshots and boundary check (#36

)

* feat: add streaming/iterator support to EventStore

Add EventStoreStreamer interface for memory-efficient event streaming using
Go 1.23+ iter.Seq2. This allows loading large event ranges without loading
all events into memory at once.

Changes:
- Add EventStoreStreamer interface with LoadStream(ctx, from, to) method
- Add LoadStream to MemoryStore using snapshot-based iteration
- Update Replay to auto-detect and use streaming when available
- Add WithStreamBatchSize option for SQLite cursor-based pagination
- Add comprehensive tests for both stores

Closes #32

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* test: achieve 100% test coverage for streaming functionality

- Add tests for Replay handler errors (streaming and non-streaming paths)
- Add tests for Load error in non-streaming stores
- Refactor LoadStream to use extracted streamRows helper for testability
- Add StreamRows to export_test.go for testing error paths
- Add tests for streamRows scan errors, iteration errors, and context cancellation
- Remove redundant rows.Err() check in streamBatched (SQLite never returns these errors)

Coverage is now 100% for both main package and SQLite store.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* fix: check rows.Close() error and document memory trade-off

- Check rows.Close() error in streamBatched to handle rare SQLite close
  failures
- Add implementation notes to EventStoreStreamer interface documenting
  the memory/deadlock trade-off for in-memory stores

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* test: add test for rows.Close() error in streamBatched

- Refactor streamBatched to extract streamBatch helper using rowScanner interface
- Add closeErr field to mockRows for testing Close() error path
- Add TestStreamBatchCloseErr test to cover the rows.Close() error handling
- Achieve 100% test coverage for SQLite store

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* perf: optimize streaming with filtered snapshots and boundary check

- MemoryStore.LoadStream: Filter events during snapshot creation instead
  of copy-all-then-filter, reducing memory for range queries
- streamBatched: Add upper bound check to avoid unnecessary query when
  batch ends exactly at the upper bound
- Add test case for batch boundary optimization

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

fix: propagate context to persistence for proper trace hierarchy

Adds PublishHookContext type that receives context, fixing issue #33 where
persistence spans were disconnected from parent trace context. WithStore
now uses context-aware hooks so persistence inherits the publish context.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

fix: improve SpanAttributer test coverage

- Fix without_interface test to verify event.type attribute exists
- Fix empty_attributes test to actually implement SpanAttributer interface
- Add compile-time verification for emptyAttributedEvent

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

fix: improve SpanAttributer test coverage

- Fix without_interface test to verify event.type attribute exists
- Fix empty_attributes test to actually implement SpanAttributer interface
- Add compile-time verification for emptyAttributedEvent

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

feat: call store.Close() in Shutdown if available (#27)

* feat: call store.Close() in Shutdown if available

- EventBus.Shutdown() now calls Close() on store if it implements io.Closer
- maintains 100% test coverage
- enables stores to flush buffers on graceful shutdown

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* fix: improve error handling in store Close()

Address code review feedback:

- Wrap Close() errors with context for better debugging
- Add test case for Close() returning an error
- Verify error wrapping with errors.Is()
- Check error message contains expected context

Maintains 100% test coverage.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Release v0.8.5: Critical improvements and cleanup

This release addresses critical issues identified in comprehensive code review:

Critical Fixes:
- Remove empty event processor goroutine that was causing resource leaks
- Add graceful Shutdown method with context support for clean application termination
- Comprehensive test coverage for shutdown behavior

Features:
- New Shutdown(context.Context) method for graceful shutdown
- Waits for all async handlers to complete
- Respects context timeout and cancellation
- Enables clean integration with standard Go shutdown patterns

Improvements:
- Eliminated unnecessary goroutine overhead
- Better resource cleanup patterns
- Enhanced documentation with shutdown examples
- Maintained 100% test coverage

Breaking Changes: None - fully backward compatible

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

feat: add Store interface for event sourcing patterns (#24)

Add Store interface designed for CQRS/ES patterns with stream-based
event storage. Unlike EventStore which handles event bus persistence,
Store provides:

- Stream-based organization with version control
- ReadAll capability for event replay across streams
- Event struct with stream metadata and versioning

This interface enables building event-sourced systems and remote
storage implementations while maintaining type safety and idiomatic
Go patterns.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>

Release v0.8.3: OpenTelemetry observability support

This release adds comprehensive OpenTelemetry observability support with metrics and distributed tracing:

Features:
- OpenTelemetry metrics for event publish, handler execution, and persistence
- Distributed tracing with context propagation across async handlers
- Per-event-type metric labeling for detailed performance analysis
- Comprehensive example with Docker Compose, Prometheus, Grafana, and Jaeger
- Enhanced Grafana dashboard with per-event-type performance breakdown
- 100% test coverage for observability package

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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