feat(async): add flush semantics and enhanced test utilities

Implement comprehensive shutdown patterns and flush semantics for the
functional async logging backend. This update introduces the
shutdown_async_backend utility to

Co-authored-by: gitbot <gitbot@gossorg.in>

Author: IntegerAlex

.gitignore

@@ -167,4 +167,5 @@ logs/
 # Documentation build
 documentation/build/
 documentation/.docusaurus/
-documentation/node_modules/
+documentation/node_modules/
+.gitbotrc.json

CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Async logging flush semantics documentation and shutdown patterns guide.
+- New guides: `testing-patterns.md` (async logger testing), `common-pitfalls.md`.
+- `AsyncConfig` validation with helpful error messages.
+- Async logger test utilities: `wait_for_async_queue_drain`, `async_logger_with_teardown` fixture.
+- Export of `shutdown_async_backend` from main `kakashi` package.
+
+### Changed
+- README license reference corrected to LGPL-2.1.
+- Expanded async-backends documentation with flush semantics and shutdown patterns.
+- Deprecated legacy `AsyncLogger` (removal planned for v0.4.0); use `kakashi.core.async_interface.get_async_logger`.
+- Type hints completed in `logger.py`, `async_interface.py`.
+- Deprecations doc now documents dual async systems and migration path.
+
+### Fixed
+- Session test teardown now shuts down both legacy and functional async backends.
+
 ## [0.2.1] - 2026-02-05
 
 ### Changed

README.md

@@ -72,6 +72,14 @@ kakashi/
 
 ### Basic Usage
 
+**Tip:** For production apps using async logging, register shutdown at startup to prevent message loss:
+
+```python
+import atexit
+from kakashi import shutdown_async_logging, shutdown_async_backend
+atexit.register(shutdown_async_backend)  # For functional async; use shutdown_async_logging for legacy
+```
+
 ```python
 from kakashi import get_logger, get_async_logger
 
@@ -235,7 +243,7 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the LGPL-2.1 License - see the [LICENSE](LICENSE) file for details.
 
 ## ⚖️ Legal Disclaimers
 
@@ -262,4 +270,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**Kakashi v0.2.0** - Professional High-Performance Logging for Python
+**Kakashi v0.2.1** - Professional High-Performance Logging for Python

performance_tests/conftest.py

@@ -22,6 +22,11 @@ def cleanup_async_logging():
     yield
     from kakashi import shutdown_async_logging
     shutdown_async_logging()
+    try:
+        from kakashi.core.async_interface import shutdown_async_backend
+        shutdown_async_backend(timeout=2.0)
+    except ImportError:
+        pass
 
 @pytest.fixture(scope="session")
 def temp_test_dir() -> Generator[Path, None, None]:
@@ -137,3 +142,53 @@ def kakashi_structured_logger():
     """Create a fresh Kakashi structured logger for each test."""
     from kakashi.core import create_structured_logger
     return create_structured_logger("test_structured_logger")
+
+
+# =============================================================================
+# Async logger test utilities
+# =============================================================================
+
+def wait_for_async_queue_drain(
+    timeout: float = 5.0,
+    poll_interval: float = 0.05,
+) -> bool:
+    """
+    Wait until the functional async backend queue is empty or timeout.
+
+    Use before asserting on log output when using async loggers.
+
+    Returns:
+        True if queue drained, False if timeout reached.
+    """
+    import time
+    try:
+        from kakashi.core.async_interface import get_async_stats
+    except ImportError:
+        return False
+    start = time.time()
+    while time.time() - start < timeout:
+        stats = get_async_stats()
+        if stats.get("queue_size", 0) == 0:
+            return True
+        time.sleep(poll_interval)
+    return False
+
+
+@pytest.fixture
+def async_logger_with_teardown():
+    """
+    Functional async logger that shuts down cleanly after each test.
+
+    Use for tests that need async logging and must drain the queue
+    before asserting on output.
+    """
+    try:
+        from kakashi.core.async_interface import (
+            get_async_logger,
+            shutdown_async_backend,
+        )
+    except ImportError:
+        pytest.skip("kakashi.core.async_interface not available")
+    logger = get_async_logger("test.async_teardown")
+    yield logger
+    shutdown_async_backend(timeout=2.0)