================================================================================
JAEB INTEGRATION TESTS & BENCHMARKS - EXPLORATION COMPLETE
================================================================================

SUMMARY STATISTICS:
- Total Test Files: 18
- Total Benchmark Files: 1
- Total Lines of Test Code: ~3,500+
- Total Lines of Benchmark Code: 380

TEST FILE LOCATIONS:
/home/linket/Development/Private/jaeb/tests/

DETAILED BREAKDOWN:

CORE DISPATCH & HANDLERS (Foundation):
  1. dispatch.rs (159 lines)
     - Basic async/sync handler execution
     - Multi-handler fanout
     - Type-based routing

  2. closure_handlers.rs (213 lines)
     - Closure-based subscriptions (sync & async)
     - Failure policies with closures
     - Mixed handler types

  3. builder_validation.rs (43 lines)
     - Configuration validation
     - Error checking

FLOW CONTROL & RESOURCE MANAGEMENT:
  4. backpressure.rs (81 lines)
     - Non-blocking try_publish
     - Blocking publish with capacity waiting
     - ChannelFull error handling

  5. semaphore.rs (76 lines)
     - Bounded async concurrency
     - Semaphore-based limiting

  6. clone.rs (45 lines)
     - Arc-based bus cloning
     - Shared state across clones

ERROR HANDLING & RESILIENCE:
  7. retry.rs (343 lines) - LARGEST TEST FILE
     - Fixed/Exponential/Jitter retry strategies
     - Timing validation for backoff
     - Multiple retry attempts

  8. dead_letter.rs (301 lines)
     - Dead-letter queue pattern
     - Failure metadata tracking
     - Recursion prevention
     - Event downcasting

  9. panic_safety.rs (96 lines)
     - Handler panic isolation
     - Bus recovery after panic

ADVANCED FEATURES:
  10. middleware.rs (474 lines) - MOST COMPLEX TEST FILE
      - Global and typed middleware
      - Sync and async middleware
      - FIFO ordering guarantees
      - Event rejection capability

  11. snapshot.rs (283 lines)
      - Per-event-type slot architecture
      - Type-based parallelism
      - FIFO within type
      - Lazy slot registration

LIFECYCLE & SUBSCRIPTION MANAGEMENT:
  12. shutdown.rs (169 lines)
      - Graceful termination
      - Queue draining
      - In-flight task waiting
      - Configurable timeouts

  13. once.rs (176 lines)
      - Single-fire subscriptions
      - Auto-removal on trigger
      - Dead letter emission on failure

  14. unsubscribe.rs (145 lines)
      - Dynamic listener removal
      - ID-based unsubscribe
      - Concurrent safety

  15. subscription_guard.rs (119 lines)
      - RAII-based cleanup
      - Guard disarm mechanism

OBSERVABILITY & DEBUGGING:
  16. introspection.rs (169 lines)
      - Runtime statistics
      - Handler name tracking
      - In-flight async count
      - Per-event-type metrics

  17. named_subscriptions.rs (140 lines)
      - Named handler correlation
      - Dead-letter identification

TESTING UTILITIES:
  18. test_utils.rs (114 lines)
      - Feature-gated test helpers
      - Event capture mechanism
      - Assertion utilities

BENCHMARKS:
/home/linket/Development/Private/jaeb/benches/throughput.rs (380 lines)
  - publish_sync, publish_async baselines
  - fanout_sync (1-50 handlers)
  - mixed_sync_async workload
  - contention (4 publishers)
  - middleware overhead scaling
  - event size scaling (8B, 256B, 4KB)
  - baseline_mpsc (reference point)

================================================================================
KEY USAGE PATTERNS IDENTIFIED
================================================================================

1. HANDLER TRAITS:
   - EventHandler<E>: async dispatch
   - SyncEventHandler<E>: sync dispatch
   - Both implement handle(&self, event) -> HandlerResult

2. SUBSCRIPTION METHODS:
   - subscribe(handler): standard subscription
   - subscribe_once(handler): single-fire
   - subscribe_with_policy(handler, policy): with failure handling
   - subscribe_dead_letters(handler): dead-letter listener
   - subscribe_once_with_policy: single-fire + failure handling

3. PUBLISHING METHODS:
   - publish(event).await: blocking, waits for capacity
   - try_publish(event): non-blocking, returns ChannelFull error

4. FAILURE HANDLING:
   - FailurePolicy: max_retries, retry_strategy, dead_letter flag
   - RetryStrategy: Fixed, Exponential, ExponentialWithJitter
   - DeadLetter events emitted on exhaustion

5. MIDDLEWARE:
   - Sync middleware: immediate processing
   - Async middleware: async processing with await
   - Typed middleware: specific event types only
   - Decision: Continue or Reject(reason)

6. LIFECYCLE:
   - EventBus::builder() or EventBus::new()
   - .shutdown().await: graceful termination
   - Configurable shutdown_timeout

7. CONCURRENCY:
   - max_concurrent_async: limit async handler parallelism
   - buffer_size: dispatch queue capacity
   - Per-type parallelism: different event types run concurrently

8. OBSERVABILITY:
   - stats().await: get bus metrics
   - handler.name(): optional handler identification
   - SubscriptionInfo tracking

================================================================================
FEATURES TESTED BUT NOT OBVIOUS FROM API
================================================================================

1. Per-Event-Type Slot Architecture
   - Different event types dispatch independently
   - Same-type handlers maintain FIFO order
   - Not exposed in public API (internal detail)

2. Copy-On-Write Listener Snapshots
   - Publish takes snapshot of listener list
   - Concurrent subscribe/unsubscribe safe
   - No lock contention during dispatch

3. Lazy Type Slot Registration
   - Type slots only created on first subscription
   - Automatically cleaned up when last listener removed
   - Reduces memory for unsubscribed types

4. Panic Isolation
   - Sync panics caught via catch_unwind
   - Async panics caught via JoinSet
   - Bus remains operational

5. Dead-Letter Recursion Guard
   - Dead-letter listener failures do NOT emit new dead letters
   - Explicit check to prevent infinite recursion
   - Graceful failure handling

6. Shutdown Drain Path
   - In-flight async tasks delivered dead-letters directly
   - Bypass channel during shutdown drain
   - Ensures diagnostics even on force-abort

7. Jitter Randomness
   - ExponentialWithJitter uses bounded randomness
   - Still capped at exponential max
   - Deterministic upper bound for testing

================================================================================
RECOMMENDED EXAMPLE TOPICS (FROM TEST COVERAGE)
================================================================================

1. hello-world.rs: dispatch.rs pattern
   - Create bus, subscribe handler, publish, shutdown

2. closures.rs: closure_handlers.rs pattern
   - Using lambdas instead of struct handlers

3. error-handling.rs: retry.rs + dead_letter.rs patterns
   - Failure policies, retry strategies, dead-letter queue

4. middleware-pipeline.rs: middleware.rs pattern
   - Global middleware, typed middleware, rejections

5. graceful-shutdown.rs: shutdown.rs pattern
   - Timeout configuration, task draining

6. testing-events.rs: test_utils.rs pattern
   - TestBus for verifying event bus usage

7. backpressure-handling.rs: backpressure.rs pattern
   - try_publish vs publish, error handling

8. load-limiting.rs: semaphore.rs pattern
   - max_concurrent_async configuration

================================================================================
FILE LOCATIONS
================================================================================

Tests: /home/linket/Development/Private/jaeb/tests/*.rs
Benchmarks: /home/linket/Development/Private/jaeb/benches/throughput.rs

All files follow established patterns from AGENTS.md and RUST_GUIDE.md
