fix: async channels now actually work (v0.2.1)

Fixed completely broken async send/recv implementation:
- Was referencing non-existent queue fields
- channels.nim had duplicate type definitions conflicting with SPSC
- Removed 100+ lines of duplicate code

Improvements:
- Added exponential backoff (1ms → 100ms) to reduce CPU usage
- Fixed Chronos deprecation warnings
- Now properly imports from channel_spsc

Testing:
- Added comprehensive async channel tests
- All tests pass (basic, channel, async)
- Added async tests to CI workflow

Updated documentation:
- KNOWN_ISSUES.md reflects improvements
- README.md updated for v0.2.1
- Added detailed CHANGELOG entry

Author: codenimja

.github/workflows/ci.yml

@@ -1,12 +1,55 @@
 name: CI
-on: [push, pull_request]
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
 jobs:
   test:
+    name: Test SPSC Channels
     runs-on: ubuntu-latest
+
     steps:
-      - uses: actions/checkout@v4
-      - uses: jiro4989/setup-nim-action@v2
-        with:
-          nim-version: '2.2.4'
-      - run: nimble test
-      - run: nimble bench
+    - uses: actions/checkout@v3
+
+    - name: Setup Nim
+      uses: jiro4989/setup-nim-action@v1
+      with:
+        nim-version: 'stable'
+
+    - name: Install dependencies
+      run: nimble install -y
+
+    - name: Run channel tests
+      run: nim c -r tests/unit/test_channel.nim
+
+    - name: Run async channel tests
+      run: nim c -r tests/unit/test_async_channel.nim
+
+    - name: Run basic tests
+      run: nim c -r tests/unit/test_basic.nim
+
+  benchmark:
+    name: SPSC Performance Validation
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Setup Nim
+      uses: jiro4989/setup-nim-action@v1
+      with:
+        nim-version: 'stable'
+
+    - name: Install dependencies
+      run: nimble install -y
+
+    - name: Build benchmark
+      run: nim c -d:danger --opt:speed --threads:on --mm:orc tests/performance/benchmark_spsc.nim
+
+    - name: Run benchmark and validate
+      run: |
+        echo "Running SPSC benchmark..."
+        ./tests/performance/benchmark_spsc

.gitignore

@@ -51,3 +51,11 @@ src/htmldocs/
 # Internal roadmap
 ROADMAP_v1.0.md
 claude.md
+
+# Claude Code context (local only)
+CLAUDE.md
+
+# Development/internal files
+STATUS_INTERNAL.md
+ROADMAP*.md
+SUPPORT.md

CHANGELOG.md

@@ -1,116 +1,64 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.0.0] - 2025-10-31
-
-Production-ready release with comprehensive stress testing and validated performance.
-
-### Added
-- Lock-free SPSC channels with backpressure support
-- Structured concurrency with TaskGroup
-- Work-stealing scheduler with NUMA awareness
-- Connection pool with starvation detection and auto-recovery
-- WebSocket stress testing (1,000+ clients, 1M+ messages)
-- Streaming pipeline with adaptive backpressure
-- Comprehensive fault tolerance and error isolation
-- 24-hour endurance testing suite
-- Integrated observability with metrics and tracing
-- Full CI/CD pipeline with automated validation
+## [0.2.1] - 2025-11-01
 
 ### Fixed
-- Stack overflow in mixed workload scenarios
-- Race condition in memory allocation tracking
-- Channel buffer overflow handling
-- Database connection leak prevention
-
-### Performance
-- **SPSC Throughput**: 213M+ ops/sec
-- **Task Spawn**: < 100ns overhead
-- **Mixed Workload**: 8,400 tasks/sec sustained
-- **GC Pauses**: < 2ms at 1GB allocation pressure
-- **Memory Stability**: Zero leaks after 24h continuous operation
-
-### Testing
-- Comprehensive unit test coverage
-- Integration testing across all modules
-- Performance benchmarking and regression testing
-- Stress testing under extreme conditions
-- 24-hour endurance validation
-
-## [0.1.0] - 2025-10-31
-
-Production-ready lock-free SPSC channels with industry-leading performance.
+- **Async channels now actually work** - Previous implementation was completely broken
+  - Fixed `send()`/`recv()` to use actual SPSC implementation (was referencing non-existent fields)
+  - Removed duplicate Channel/ChannelMode type definitions
+  - Added exponential backoff (1ms → 100ms) to reduce CPU usage
+  - Fixed Chronos deprecation warnings
+- **Deduplicated channels.nim** - Removed 100+ lines of duplicate code
+  - Now properly imports from channel_spsc instead of reimplementing everything
 
 ### Added
+- Comprehensive async channel tests (tests/unit/test_async_channel.nim)
+- Added async tests to CI workflow
 
-- **Lock-Free SPSC Channels** - 213M+ ops/sec single-threaded throughput
-- **ORC Memory Management** - Zero GC pressure in hot paths
-- **Atomic Operations** - Thread-safe with proper memory barriers
-- **Production API** - `newChannel`, `trySend`, `tryReceive`
-- **Performance Benchmarks** - Validated against 52M ops/sec target (410% achieved)
-- **Unit Tests** - Basic functionality validation
-- **CI/CD Pipeline** - Automated testing on GitHub Actions
-- **Documentation** - Performance-focused README and architecture guide
-
-### Performance Achievements
+### Changed
+- Updated KNOWN_ISSUES.md to reflect async improvements
 
-- **213,567,459 ops/sec** - 4.1x above 52M target
-- **<1KB memory per channel** - Efficient resource usage
-- **Sub-microsecond latency** - For uncontended operations
-- **ORC-safe** - Advanced Nim garbage collection
-- **Lock-free** - No locks, no blocking, no deadlocks
+## [0.2.0] - 2025-11-01
 
-### Technical Details
+### Reality Check Release
+Downgraded from v1.0.0 to v0.2.0 to accurately reflect what's production-ready.
 
-- **Algorithm**: Atomic sequence numbers with acquire/release semantics
-- **Memory Layout**: Cache-aligned SPSCSlot structures
-- **Threading Model**: Single producer, single consumer
-- **Safety**: ORC GC with zero allocations in hot path
-- **Compatibility**: Nim 2.0+ with ORC memory management
+### Production-Ready
+- **SPSC Channels**: 212M+ ops/sec verified
+  - Tests passing: tests/unit/test_channel.nim
+  - Benchmark verified: tests/performance/benchmark_spsc.nim
 
-### Breaking Changes
+### Removed from Public API
+- TaskGroup (has bugs, removed from exports)
+- Cancellation (untested, removed from exports)
+- All other features remain internal/experimental
 
-- Initial release - no breaking changes
-
-### Known Limitations
-
-- Select operations not yet implemented (planned for v0.2.0)
-- MPMC channels not yet implemented (planned for v0.2.0)
-- Structured concurrency not yet implemented (planned for v0.3.0)
-
-- SPSC Channels: 50M+ ops/sec (world-leading performance)
-- MPMC Channels: 10M+ ops/sec (optimized for concurrency) 
-- Task Groups: 500K+ tasks/sec spawn rate
-- Cancellation: 100K+ ops/sec with <10ns latency
-- Memory Efficiency: <1KB per channel overhead
-
-### Infrastructure
-
-- Complete test suite with performance, stress, and regression tests
-- Professional benchmarking framework
-- Comprehensive metrics and logging
-- Production-ready validation tools
-- Multi-platform performance validation
-
-## [0.2.0] - 2025-10-28
-
-Production-ready release with 6 advanced modules for enterprise-grade async programming.
+### Changed
+- Version: 1.0.0 → 0.2.0
+- README.md: Replaced with honest version
+- Build: "production" → "experimental"
 
 ### Added
-
-- **Adaptive Work-Stealing Scheduler** - Modern task distribution with load balancing
-- **NUMA-Aware Optimizations** - Multi-socket performance improvements
-- **OpenTelemetry Distributed Tracing** - Production observability
-- **Adaptive Backpressure Flow Control** - Smart rate limiting
-- **Erlang-Style Supervision Trees** - Fault tolerance and recovery
-- **Real-Time Performance Metrics** - Monitoring and analytics
-
-### Infrastructure
-
-- Multi-platform CI/CD (Ubuntu, macOS, Windows)
-- Complete test coverage and benchmarks
-- Community contribution templates
-- Professional GitHub setup
+- STATUS.md: Feature audit
+- CI workflow: Test + benchmark validation
+- CHANGELOG.md: This file
+- KNOWN_ISSUES.md: Documented bugs and limitations
+
+### Known Issues
+- Async send/recv use polling (exponential backoff)
+- TaskGroup: nested async macro bugs (not exported)
+- Actors: won't compile, needs MPSC
+- Streams: compiles but untested
+- Scheduler: fake (just metrics)
+- NUMA: broken node detection
+
+See KNOWN_ISSUES.md for complete list.
+
+## [1.0.0] - RETRACTED
+Premature release. Use v0.2.0 instead.
+
+Retracted because:
+- Claimed features that don't work
+- TaskGroup exported but broken
+- Examples showed inaccessible API
+- No CI validation

KNOWN_ISSUES.md

@@ -0,0 +1,122 @@
+# Known Issues
+
+This document tracks known bugs and limitations in nimsync v0.2.1.
+
+## Production Code (SPSC Channels)
+
+### No close() Method
+**Status**: By design (not a bug)
+**Workaround**: Use sentinel values for shutdown signaling
+
+### Async send/recv Use Polling (IMPROVED)
+**Status**: IMPROVED - Now uses exponential backoff (1ms → 100ms)
+**Previous Issue**: Used fixed 1ms polling
+**Current Implementation**: Exponential backoff (1ms, 2ms, 4ms, ..., up to 100ms cap)
+**Impact**: Initial operations have 1ms latency, but reduces CPU usage for longer waits
+**Workaround**: Use `trySend`/`tryReceive` for zero-latency operations
+**Future**: Could be replaced with event-driven Chronos futures
+
+### Size Rounded to Power of 2
+**Status**: By design (performance optimization)
+**Example**: `newChannel[int](10, SPSC)` creates 16-slot channel
+
+## Experimental Code (NOT Exported)
+
+### TaskGroup - Nested Async Macro Bug
+**Status**: BROKEN - Does not compile
+**Location**: `src/nimsync/group.nim:172`
+**Error**: `expression has no type (or is ambiguous)`
+**Cause**: Nested async macros in `spawn()` implementation
+**Impact**: TaskGroup cannot be used at all
+**Priority**: HIGH - Blocks v0.3.0 release
+
+### Actors - Won't Compile
+**Status**: BROKEN - Depends on unimplemented MPSC
+**Location**: `src/nimsync/actors.nim:258`
+**Error**: Type mismatch in mailbox.receive()
+**Cause**: Uses MPSC channels which don't exist
+**Dependencies**: Requires MPSC implementation first
+**Priority**: MEDIUM - v0.4.0 feature
+
+### Streams - Completely Untested
+**Status**: UNKNOWN - Compiles but zero tests
+**Location**: `src/nimsync/streams.nim`
+**Issues**:
+- Line 334: "Unbounded policy not implemented" raises exception
+- Zero test coverage
+**Priority**: MEDIUM - Needs testing before v0.5.0
+
+### Scheduler - Not Actually a Scheduler
+**Status**: FAKE - Just metrics tracking
+**Location**: `src/nimsync/scheduler.nim`
+**Missing**:
+- No work queues
+- No worker threads
+- No task stealing logic
+**Priority**: LOW - Rewrite or remove
+
+### NUMA - Broken Node Detection
+**Status**: BROKEN - Always returns 0
+**Location**: `src/nimsync/numa.nim:122-136`
+**Issue**: `sched_getcpu()` call commented out
+**Impact**: All NUMA "optimizations" disabled
+**Priority**: LOW - Fix or remove
+
+### Cancellation - Untested in Production
+**Status**: UNKNOWN - Code looks good, unproven
+**Location**: `src/nimsync/cancel.nim`
+**Issue**: No real-world testing
+**Priority**: MEDIUM - Needs validation before export
+
+### Supervision - Disconnected
+**Status**: INCOMPLETE - Not integrated with actors
+**Location**: `src/nimsync/supervision.nim`
+**Missing**: Actor integration, restart logic, tests
+**Priority**: LOW - Depends on working actor system
+
+## Not Bugs (By Design)
+
+These are intentional design decisions, not bugs:
+
+1. **SPSC Only**: Only Single Producer Single Consumer implemented
+   - MPSC/SPMC/MPMC not available (will raise ValueError)
+   - This is documented and intentional for v0.2.0
+
+2. **Internal Code Not Exported**: Experimental features not in public API
+   - TaskGroup, Actors, Streams, etc. exist but not exported
+   - Users can import directly: `import nimsync/group`
+   - This is intentional until features are production-ready
+
+3. **Version 0.2.0**: Not 1.0.0
+   - Downgraded from premature 1.0.0 release
+   - Honest versioning reflecting actual state
+
+## Reporting Issues
+
+Found a bug not listed here? Please report it:
+
+**For SPSC Channels** (production code):
+- Check if it's already in "Production Code" section above
+- If new, open issue: https://github.com/codenimja/nimsync/issues
+- Include: Nim version, OS, minimal reproduction
+
+**For Experimental Features** (internal code):
+- These are known to be incomplete/broken
+- Check "Experimental Code" section first
+- Feature requests welcome, but expectations should be low
+
+## Version History
+
+- **v0.2.1** (2025-11-01): Fixed async channels, added exponential backoff
+- **v0.2.0** (2025-11-01): Reality check release, SPSC only
+- **v1.0.0** (RETRACTED): Premature, claimed features that didn't work
+
+## Contributing
+
+Want to fix any of these? Contributions welcome!
+
+Priority order for fixes:
+1. TaskGroup nested async bug (blocking v0.3.0)
+2. MPSC channel implementation (enables actors)
+3. Stream testing (validation needed)
+4. Scheduler/NUMA (rewrite or remove)