📝 clarify async shutdown runtime docs

docs/api/async-logger-shutdown.md

@@ -2,8 +2,8 @@
 name: async-logger-shutdown
 group: api
 category: async
-update-time: 20260512
+update-time: 20260614
-description: Gracefully stop an async logger by waiting for idle or clearing queued work, then waiting for the worker to finish.
+description: Gracefully stop an async logger by waiting for idle or clearing queued work, with worker-wait behavior depending on the active async runtime.
 key-word:
     - async
     - logger
@@ -35,9 +35,9 @@ pub async fn[S] AsyncLogger::shutdown(self : AsyncLogger[S], clear? : Bool = fal
 Detailed rules explaining key parameters and behaviors
 
 - `clear=false` first waits for idle, then closes the logger.
-- If backlog still remains after waiting, shutdown falls back to `close(clear=true)`.
+- In runtimes where shutdown clearing after idle is enabled, remaining backlog after `wait_idle()` triggers a fallback `close(clear=true)`.
 - `clear=true` immediately closes and abandons pending records.
-- The method waits until `is_running()` becomes `false` before returning.
+- In runtimes where shutdown waits for workers, the method then waits until `is_running()` becomes `false` before returning.
 
 ### How to Use
 
@@ -66,10 +66,14 @@ In this example, pending work is abandoned intentionally so shutdown can complet
 e.g.:
 - If `clear=true`, pending records are intentionally dropped rather than drained.
 
+- In compatibility-style runtimes without background-worker waiting, shutdown still closes the logger but may not perform the extra wait-for-worker phase described for native-worker runtimes.
+
 - If callers skip `shutdown()` and only inspect flags manually, it is easier to leave the worker lifecycle in an unclear state.
 
 ### Notes
 
 1. Prefer this API over raw `close()` in normal application shutdown paths.
 
-2. Choose `clear=true` only when loss of queued records is acceptable.
+2. Exact post-close waiting behavior depends on the active async runtime mode.
+
+3. Choose `clear=true` only when loss of queued records is acceptable.

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

@@ -2,8 +2,8 @@
 name: library-async-logger-shutdown
 group: api
 category: facade
-update-time: 20260613
+update-time: 20260614
-description: Gracefully stop a LibraryAsyncLogger by draining or clearing queued work, then waiting for the worker to finish.
+description: Gracefully stop a LibraryAsyncLogger by draining or clearing queued work, with worker-wait behavior depending on the active async runtime.
 key-word:
     - async
     - library
@@ -39,8 +39,9 @@ Detailed rules explaining key parameters and behaviors
 
 - This method delegates directly to the wrapped async logger's `shutdown(...)` behavior.
 - `clear=false` first waits for idle, then closes the logger.
+- If the active async runtime uses shutdown clearing after idle and backlog still remains, the wrapped logger falls back to `close(clear=true)`.
 - `clear=true` immediately closes and abandons pending records.
-- The method waits until the worker is no longer running before returning.
+- In runtimes where shutdown waits for workers, the method then waits until the worker is no longer running before returning.
 
 ### How to Use
 
@@ -69,10 +70,14 @@ In this example, pending work is abandoned intentionally so shutdown can complet
 e.g.:
 - If `clear=true`, pending records are intentionally dropped rather than drained.
 
+- In compatibility-style runtimes without background-worker waiting, shutdown still closes the logger but may not perform the extra wait-for-worker phase described for native-worker runtimes.
+
 - If callers skip `shutdown()` and only inspect flags manually, it is easier to leave the worker lifecycle in an unclear state.
 
 ### Notes
 
 1. Prefer this API over low-level closure control in normal library shutdown paths.
 
-2. Choose `clear=true` only when loss of queued records is acceptable.
+2. Exact post-close waiting behavior depends on the active async runtime mode.
+
+3. Choose `clear=true` only when loss of queued records is acceptable.