diff --git a/docs/api/build-application-async-logger.md b/docs/api/build-application-async-logger.md index ad004ed..913390a 100644 --- a/docs/api/build-application-async-logger.md +++ b/docs/api/build-application-async-logger.md @@ -42,6 +42,8 @@ Detailed rules explaining key parameters and behaviors - Because the result is only the `ApplicationAsyncLogger` alias over `AsyncLogger[@bitlogger.RuntimeSink]`, this builder does not hide any async helpers or introduce a wrapper layer. - The returned logger keeps the full async lifecycle and state helper surface directly, including helpers such as `run()`, `shutdown()`, `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, `has_failed()`, and `last_error()`. - It also keeps the same queue counters, failure state, sink shape, and runtime-dependent post-close behavior as the underlying runtime-sink async logger. +- In the current direct builder coverage, this alias matches `build_async_logger(config)` all the way through serialized state snapshots, runtime-sink variant choice, queue counters, lifecycle flags, and later failure fields after `run()` or `shutdown()`. +- File-backed runtime helpers on the returned `RuntimeSink` also stay aligned with the direct builder result instead of being hidden behind a separate application-layer wrapper. - Use this alias-oriented builder when application code wants the standard runtime-sink async shape without narrowing the public surface. ### How to Use @@ -82,6 +84,8 @@ e.g.: - If the logger is never `run()`, enqueue behavior and lifecycle state still follow the normal async logger rules. +- If callers rely on file-backed runtime helpers, they should treat this builder as the same runtime-sink result as `build_async_logger(config)`, not as a reduced alias with different helper behavior. + ### Notes 1. This is a facade over the existing async runtime logger builder. diff --git a/docs/api/build-library-async-logger.md b/docs/api/build-library-async-logger.md index b59e0e6..3252a05 100644 --- a/docs/api/build-library-async-logger.md +++ b/docs/api/build-library-async-logger.md @@ -40,6 +40,8 @@ Detailed rules explaining key parameters and behaviors - The returned facade wraps the same underlying `AsyncLogger[@bitlogger.RuntimeSink]` value that `build_async_logger(...)` would produce directly. - The result keeps async lifecycle operations such as `run()` and `shutdown()` while narrowing the public shape. - The narrower facade does not change the underlying runtime-sink queue counters, failure state, sink shape, or runtime-dependent post-close behavior; it only hides the broader helper surface until `to_async_logger()` is used. +- In the current direct builder coverage, unwrapping this facade produces the same async state snapshot, runtime-sink variant, queue counters, lifecycle flags, and failure fields as calling `build_async_logger(config)` directly. +- That same unwrap also preserves file-backed runtime helpers on `RuntimeSink` values rather than replacing them with facade-specific behavior. - Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, and failure-status inspection remain on the underlying `AsyncLogger`, not on the returned facade itself. - `to_async_logger()` can be used to recover the underlying full async logger. - Use this builder when the boundary should preserve the runtime-sink async build path but still hide broader async inspection helpers from downstream callers. @@ -80,6 +82,8 @@ e.g.: - If callers need async state, failure-status, or idle-wait helpers outside the library facade, they must unwrap with `to_async_logger()`. +- If callers need file-backed runtime helpers such as file-state or queued runtime inspection, they must unwrap first, but the helper behavior itself stays aligned with the direct `build_async_logger(config)` result. + ### Notes 1. Prefer this API when library boundaries should stay narrow. diff --git a/docs/api/parse-and-build-application-async-logger.md b/docs/api/parse-and-build-application-async-logger.md index 558a3d5..0129a37 100644 --- a/docs/api/parse-and-build-application-async-logger.md +++ b/docs/api/parse-and-build-application-async-logger.md @@ -42,6 +42,8 @@ Detailed rules explaining key parameters and behaviors - That includes preserving a parsed sync queue configuration inside the resulting `RuntimeSink` variant rather than collapsing it away during application-alias construction. - Because the result is the `ApplicationAsyncLogger` alias over `AsyncLogger[@bitlogger.RuntimeSink]`, this parse-and-build path returns the same underlying async logger value that `parse_async_logger_build_config_text(...)` plus `build_async_logger(...)` would produce, without narrowing the helper surface. - The returned logger keeps the full async lifecycle and state helpers directly. +- In the current parsed-builder coverage, that direct equivalence also holds for serialized async state snapshots, runtime-sink variant choice, queue counters, lifecycle flags, and later failure fields after worker execution. +- Parsed file-backed runtime helpers remain available on the returned logger with the same behavior as the direct `build_async_logger(parse_async_logger_build_config_text(input))` path. - Use `parse_and_build_library_async_logger(...)` instead when the same parsed runtime-sink result should be wrapped and narrowed for a library boundary. ### How to Use @@ -81,6 +83,8 @@ e.g.: - If the embedded config is invalid, parsing raises before the async facade is returned. +- If callers depend on file-backed runtime helpers, they can use them directly on the returned logger because this parse/build alias does not replace the underlying runtime-sink helper surface. + ### Notes 1. Use this facade when application boot starts from JSON text. diff --git a/docs/api/parse-and-build-library-async-logger.md b/docs/api/parse-and-build-library-async-logger.md index 47a0731..2405e27 100644 --- a/docs/api/parse-and-build-library-async-logger.md +++ b/docs/api/parse-and-build-library-async-logger.md @@ -41,6 +41,8 @@ Detailed rules explaining key parameters and behaviors - The returned facade wraps the same underlying `AsyncLogger[@bitlogger.RuntimeSink]` value that `parse_async_logger_build_config_text(...)` plus `build_async_logger(...)` would produce directly. - The resulting facade keeps library-facing async operations such as `run()` and `shutdown()` while exposing a smaller public surface. - The narrower facade does not change the underlying runtime-sink queue counters, failure state, sink shape, or runtime-dependent post-close behavior; it only hides the broader helper surface until `to_async_logger()` is used. +- In the current parsed-builder coverage, unwrapping this facade yields the same async state snapshot, runtime-sink variant, queue counters, lifecycle flags, and failure fields as `build_async_logger(parse_async_logger_build_config_text(input))`. +- Parsed file-backed runtime helpers also remain aligned after unwrap instead of being rebuilt into a different facade-specific sink state. - Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, and failure-status inspection stay on the underlying `AsyncLogger`, not on the returned facade itself. - `to_async_logger()` can recover the underlying async logger when a wider API is required. - Use this parse/build facade when text-driven construction should preserve the runtime-sink build path but still hide broader async inspection helpers at the package boundary. @@ -84,6 +86,8 @@ e.g.: - If callers assume async state or idle-wait helpers are available directly on the returned facade, they must unwrap first with `to_async_logger()`. +- If callers need file-backed runtime helpers after parse/build, they must unwrap first, but the resulting helper surface still matches the parsed direct builder path. + ### Notes 1. This is the narrow async library parse-and-build facade.