📝 clarify async library facade scope

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

@@ -2,8 +2,8 @@
 name: build-library-async-logger
 group: api
 category: facade
-update-time: 20260520
+update-time: 20260614
-description: Build the library-facing async logger facade from an AsyncLoggerBuildConfig.
+description: Build the library-facing async logger facade from an AsyncLoggerBuildConfig while intentionally hiding direct async state helpers.
 key-word:
     - library
     - async
@@ -35,8 +35,9 @@ pub fn build_library_async_logger(
 
 Detailed rules explaining key parameters and behaviors
 
-- This API builds the general async runtime logger and then wraps it in the narrower `LibraryAsyncLogger` facade.
+- This API builds the general async runtime logger and then wraps it in the narrower `LibraryAsyncLogger[@bitlogger.RuntimeSink]` facade.
 - The result keeps async lifecycle operations such as `run()` and `shutdown()` while narrowing the public shape.
+- 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.
 
 ### How to Use
@@ -57,12 +58,23 @@ let logger = build_library_async_logger(
 
 In this example, async runtime construction is hidden behind the library facade.
 
+#### When Need Async State Helpers After Library-oriented Construction
+
+When config-built async state inspection is still needed internally:
+```moonbit
+let logger = build_library_async_logger(config)
+let full = logger.to_async_logger()
+ignore(full.pending_count())
+```
+
+In this example, the library async facade is unwrapped before using async state helpers.
+
 ### Error Case
 
 e.g.:
 - If backend-specific sink limitations exist, they still apply under the facade.
 
-- If callers need methods outside the library facade, they must unwrap with `to_async_logger()`.
+- If callers need async state, failure-status, or idle-wait helpers outside the library facade, they must unwrap with `to_async_logger()`.
 
 ### Notes
 

docs/api/library-async-logger.md

@@ -2,8 +2,8 @@
 name: library-async-logger
 group: api
 category: facade
-update-time: 20260613
+update-time: 20260614
-description: Public library-facing async logger facade type used to expose a narrower surface than AsyncLogger.
+description: Public library-facing async logger facade type used to expose a narrower surface than AsyncLogger while preserving sink typing.
 key-word:
     - library
     - async
@@ -33,7 +33,8 @@ Detailed rules explaining key parameters and behaviors
 
 - This is a public facade struct, not a type alias.
 - The wrapped sink type `S` is preserved, so sink-specific typing remains available through the facade type parameter.
-- The facade keeps common library-safe async operations such as `new(...)`, `with_target(...)`, `child(...)`, `bind(...)`, `is_enabled(...)`, `run()`, `shutdown()`, and the main async write methods.
+- The facade keeps common library-safe async operations such as `new(...)`, `with_target(...)`, `child(...)`, `bind(...)`, `is_enabled(...)`, `run()`, `shutdown()`, and the main async write methods `log(...)`, `info(...)`, `warn(...)`, and `error(...)`.
+- 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.
 
 ### How to Use
@@ -69,6 +70,8 @@ e.g.:
 
 - Runtime behavior still depends on the wrapped sink `S` and async runtime support, so sink-specific or target-specific limitations remain unchanged behind the facade.
 
+- 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
 
 1. Use `LibraryAsyncLogger::new(...)`, `build_library_async_logger(...)`, or `parse_and_build_library_async_logger(...)` when you need a value of this type.

docs/api/parse-and-build-library-async-logger.md

@@ -2,8 +2,8 @@
 name: parse-and-build-library-async-logger
 group: api
 category: facade
-update-time: 20260520
+update-time: 20260614
-description: Parse JSON async build config text and build the library-facing async logger facade.
+description: Parse JSON async build config text and build the library-facing async logger facade while intentionally hiding direct async state helpers.
 key-word:
     - library
     - async
@@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors
 
 - This API parses async build config text, validates it, builds the async runtime logger, and narrows it to the library facade.
 - The resulting facade keeps async lifecycle helpers while exposing a smaller public surface.
+- 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.
 
 ### How to Use
@@ -54,6 +55,19 @@ let logger = parse_and_build_library_async_logger(
 
 In this example, parsing and library-facade construction happen together.
 
+#### When Need Async State Helpers After Text-driven Library Bootstrapping
+
+When JSON-driven construction should still allow internal async state inspection later:
+```moonbit
+let logger = parse_and_build_library_async_logger(raw) catch {
+  err => return
+}
+let full = logger.to_async_logger()
+ignore(full.pending_count())
+```
+
+In this example, the caller unwraps the library async facade before using async state helpers.
+
 ### Error Case
 
 e.g.:
@@ -61,6 +75,8 @@ e.g.:
 
 - If the embedded config is invalid, parsing raises before the library facade is returned.
 
+- If callers assume async state or idle-wait helpers are available directly on the returned facade, they must unwrap first with `to_async_logger()`.
+
 ### Notes
 
 1. This is the narrow async library parse-and-build facade.