diff --git a/docs/api/library-logger-to-logger.md b/docs/api/library-logger-to-logger.md index b34cbb3..88d3b82 100644 --- a/docs/api/library-logger-to-logger.md +++ b/docs/api/library-logger-to-logger.md @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - Sink wiring, target, min level, timestamp behavior, and attached wrappers remain the same. - Use this when code needs full-surface APIs such as `with_timestamp(...)`, `with_filter(...)`, or `with_patch(...)`. - When the wrapped sink is `RuntimeSink`, unwrapping preserves that runtime sink value, but the result type is still `Logger[RuntimeSink]` rather than the `ConfiguredLogger` alias. Runtime-specific operations remain available through `full.sink` or by keeping a `ConfiguredLogger` value directly. +- That same unwrap also preserves queued runtime state and file-backed helper behavior exactly as they existed behind the facade, including drain or flush results, file state snapshots, and file control methods. ### How to Use @@ -71,6 +72,8 @@ e.g.: - Recovering the full logger does not rebuild or reset the existing sink wrappers. +- Recovering the full logger does not translate configured runtime state into a simpler snapshot; queued counts, 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 facade is no longer sufficient. diff --git a/docs/api/library-logger.md b/docs/api/library-logger.md index 78b081a..964dec6 100644 --- a/docs/api/library-logger.md +++ b/docs/api/library-logger.md @@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors - It does not expose the wider `Logger[S]` composition surface or `ConfiguredLogger` runtime helper methods directly. - Most facade reshaping helpers keep the same visible sink type, but `with_context_fields(...)` and `bind(...)` intentionally return `LibraryLogger[ContextSink[S]]` because they extend the sink pipeline. - Call `to_logger()` when later code must recover the full underlying `Logger[S]` surface. +- 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_logger()` is used. ### How to Use diff --git a/docs/api/logger-to-library-logger.md b/docs/api/logger-to-library-logger.md index db48ec9..9bf043f 100644 --- a/docs/api/logger-to-library-logger.md +++ b/docs/api/logger-to-library-logger.md @@ -37,6 +37,8 @@ Detailed rules explaining key parameters and behaviors - Target, min level, timestamp behavior, and sink wiring are preserved because the same underlying logger value is wrapped. - The returned facade keeps library-oriented write APIs such as `info(...)`, `warn(...)`, and `error(...)`. - Broader sync composition helpers remain on the underlying `Logger[S]` and are intentionally hidden until `to_logger()` is used again. +- 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_logger()` therefore exposes the same pending counts, drain or flush results, file state, and runtime file controls that the original logger already carried. ### How to Use @@ -71,6 +73,8 @@ e.g.: - If callers later need composition helpers such as `with_timestamp(...)`, `with_filter(...)`, or `with_patch(...)`, they must unwrap again with `to_logger()`. +- Projection does not normalize configured runtime state; if the original 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 library boundaries should avoid exposing the full sync logger surface.