diff --git a/docs/api/async-logger-to-library-async-logger.md b/docs/api/async-logger-to-library-async-logger.md index 705a6ca..7f07993 100644 --- a/docs/api/async-logger-to-library-async-logger.md +++ b/docs/api/async-logger-to-library-async-logger.md @@ -39,6 +39,8 @@ Detailed rules explaining key parameters and behaviors - 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()`. +- When `S` is `RuntimeSink`, projection also preserves queued runtime state and file-backed runtime helper behavior behind the facade instead of replacing them with a library-specific copy. +- Unwrapping later with `to_async_logger()` therefore exposes the same queue counters, failure snapshots, file state, and runtime file controls that the original async logger already carried. ### How to Use @@ -76,6 +78,8 @@ e.g.: - 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. +- Projection also does not normalize richer runtime sink state; if the original async logger already carried queued runtime data or file-backed helper state, a later unwrap still exposes that same live state. + ### Notes 1. Use this when package boundaries should avoid exposing the full async logger type. diff --git a/docs/api/library-async-logger-to-async-logger.md b/docs/api/library-async-logger-to-async-logger.md index 63a86b8..26657bf 100644 --- a/docs/api/library-async-logger-to-async-logger.md +++ b/docs/api/library-async-logger-to-async-logger.md @@ -40,6 +40,7 @@ Detailed rules explaining key parameters and behaviors - 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. +- When the wrapped sink is `RuntimeSink`, that same unwrap also preserves queued runtime state and file-backed helper behavior exactly as they existed behind the facade, including runtime file state snapshots and file control methods. ### How to Use @@ -77,6 +78,8 @@ e.g.: - 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. +- Recovering the full async logger also does not translate runtime sink helper state into a simpler snapshot; queue counters, file availability, file failure counters, and runtime file controls stay exactly as they were on the wrapped logger. + ### Notes 1. Use this only when the narrower async facade is no longer sufficient. diff --git a/docs/api/library-async-logger.md b/docs/api/library-async-logger.md index e0e4e0f..cc66c1e 100644 --- a/docs/api/library-async-logger.md +++ b/docs/api/library-async-logger.md @@ -40,6 +40,7 @@ Detailed rules explaining key parameters and behaviors - 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. +- If `S` is `RuntimeSink`, queued runtime state and file-backed helper behavior also stay on that same wrapped logger value; the facade only hides direct access until `to_async_logger()` is used. ### How to Use