📝 clarify async facade projection docs

docs/api/async-logger-to-library-async-logger.md

@@ -37,6 +37,8 @@ Detailed rules explaining key parameters and behaviors
 - Target, min level, async config, flush behavior, pending counts, and failure state are preserved because the same underlying async logger value is wrapped.
 - The returned facade keeps library-facing async operations including `log(...)`, `run()`, and `shutdown(...)`.
 - Async inspection helpers and broader composition APIs remain on the underlying `AsyncLogger[S]` and are intentionally hidden until `to_async_logger()` is used again.
+- If later facade-level `run()` or `shutdown()` calls record worker failure, leave backlog behind, or follow runtime-dependent shutdown cleanup rules, unwrapping later still exposes that same post-call state instead of a translated facade copy.
+- When `S` itself exposes richer runtime helpers, projecting to the library facade does not strip those capabilities from the wrapped logger; they are still reachable after `to_async_logger()`.
 
 ### How to Use
 
@@ -72,6 +74,8 @@ e.g.:
 
 - If callers later need state helpers such as `pending_count()` or `state()`, they must unwrap again with `to_async_logger()`.
 
+- Projection does not normalize failure snapshots; a later unwrap can still show combinations such as retained `last_error()` with remaining `pending_count()` when the wrapped async logger really ended up in that state.
+
 ### Notes
 
 1. Use this when package boundaries should avoid exposing the full async logger type.

docs/api/library-async-logger-to-async-logger.md

@@ -38,6 +38,8 @@ Detailed rules explaining key parameters and behaviors
 - Use this when code needs wider async logger APIs outside the library facade.
 - This is the step required for helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, `has_failed()`, `last_error()`, or broader composition methods that are intentionally hidden by `LibraryAsyncLogger[S]`.
 - It is also the step that exposes the real post-run or post-shutdown state after facade-level lifecycle calls, because those calls delegated to this same wrapped logger all along.
+- That includes failure/backlog combinations and runtime-dependent shutdown results exactly as they accumulated behind the facade.
+- If the wrapped sink type has richer helper APIs, unwrapping also restores access to that same sink helper surface through the original `AsyncLogger[S]` value.
 
 ### How to Use
 
@@ -73,6 +75,8 @@ e.g.:
 
 - Recovering the full async logger does not clear queue contents or reset failure state.
 
+- Unwrapping does not convert facade lifecycle history into a simplified snapshot; any retained `last_error()`, pending backlog, dropped counts, or sink runtime details stay exactly as they were on the wrapped logger.
+
 ### Notes
 
 1. Use this only when the narrower async facade is no longer sufficient.

docs/api/library-async-logger.md

@@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors
 - `LibraryAsyncLogger::new(...)` delegates to `async_logger(...)`, so the same async queue, raising flush callback, and runtime-dependent lifecycle behavior still exist behind the narrower facade.
 - It does not expose the wider `AsyncLogger[S]` composition surface or the async state and lifecycle inspection helpers directly.
 - Call `to_async_logger()` when later code must recover the full underlying `AsyncLogger[S]` surface.
+- That recovered logger is the same live async value, so queue counters, retained failure state, runtime-dependent shutdown outcomes, and sink helper access are preserved rather than recomputed.
 
 ### How to Use
 
@@ -73,6 +74,8 @@ e.g.:
 
 - Post-close logging behavior, queue state, and failure-state behavior remain those of the wrapped `AsyncLogger[S]`; the facade only narrows what is directly exposed.
 
+- If the wrapped async logger later ends in a mixed diagnostic state such as `has_failed=true` with retained backlog, unwrapping exposes that exact state instead of a library-specific translation.
+
 - Helpers such as `pending_count()`, `dropped_count()`, `is_closed()`, `is_running()`, `has_failed()`, `last_error()`, `flush_policy()`, `state()`, and `wait_idle()` remain on the underlying `AsyncLogger[S]` and require `to_async_logger()` first.
 
 ### Notes