📝 consolidate logger API and async lifecycle guidance

docs/api/async-logger-log.md

@@ -2,7 +2,7 @@
 name: async-logger-log
 group: api
 category: async
-update-time: 20260512
+update-time: 20260614
 description: Enqueue a record into the async logger with an explicit level, message, optional fields, and optional target override.
 key-word:
     - async
@@ -13,7 +13,7 @@ key-word:
 
 ## Async-logger-log
 
-Enqueue a record into the async logger with an explicit level and message. This is the core write API behind all async level-specific convenience methods.
+Enqueue a record into the async logger with an explicit level and message. This is the core write API behind all async level-specific convenience methods and the only built-in async write API that accepts a per-call target override.
 
 ### Interface
 
@@ -43,10 +43,14 @@ pub async fn[S] AsyncLogger::log(
 
 Detailed rules explaining key parameters and behaviors
 
-- The logger checks `is_enabled(level)` before building a record.
+- Compatibility runtimes that guard closed writes first can return immediately when `is_closed()` is already `true`, before level checks, record construction, patch logic, filter logic, or queue work.
+- Otherwise the logger checks `is_enabled(level)` before building a record.
+- If `target` is empty, the logger uses its stored default target. If `target` is non-empty, that value overrides the stored target for this call only.
 - Context fields, patch logic, and filter logic are applied before enqueue.
 - If timestamping is enabled, `@env.now()` is captured before the record enters the queue.
 - Overflow behavior depends on the configured `AsyncOverflowPolicy`.
+- Closed-on-log behavior is runtime-dependent: compatibility runtimes short-circuit before record-building work, while native-worker runtimes may still build, patch, and filter the record before queue operations treat a closed queue as a non-accepted write.
+- In the tested blocking-policy path, a late write against an already closed logger does not become a newly accepted pending record and does not add another dropped record; it simply fails to enter the queue after any runtime-specific pre-queue work finishes.
 
 ### How to Use
 
@@ -56,7 +60,7 @@ Here are some specific examples provided.
 
 When code should choose level, fields, and target per event:
 ```moonbit
-await logger.log(
+logger.log(
   @bitlogger.Level::Info,
   "worker started",
   fields=[@bitlogger.field("job", "sync")],
@@ -64,13 +68,22 @@ await logger.log(
 )
 ```
 
-In this example, all per-record inputs are supplied explicitly.
+In this example, the record overrides the logger's stored target only for this call.
+
+#### When Reuse The Stored Async Target
+
+When a call should keep the logger's existing target:
+```moonbit
+logger.log(@bitlogger.Level::Warn, "slow request")
+```
+
+In this example, the logger falls back to its stored target because no `target=` override is provided.
 
 #### When Build Higher-level Async Logging Helpers
 
 When application code wants a custom wrapper around the base API:
 ```moonbit
-await logger.log(@bitlogger.Level::Warn, "slow request")
+logger.log(@bitlogger.Level::Warn, "slow request")
 ```
 
 In this example, `log(...)` acts as the common primitive under custom wrappers or convenience methods.
@@ -82,8 +95,14 @@ e.g.:
 
 - If the logger is closed or overflow policy rejects the record, enqueue may not proceed as a normal accepted write.
 
+- A closed queue does not count as a newly accepted pending record.
+
+- On compatibility runtimes, a late call after close can be skipped before patch or filter logic runs at all.
+
+- On native-worker runtimes, a late call after close can still execute patch and filter logic before the queue rejects the write.
+
 ### Notes
 
 1. Use this API when the call site needs full control instead of a fixed severity helper.
 
-2. Prefer `info()`, `warn()`, and the other shortcuts when only the level differs.
+2. Prefer `info()`, `warn()`, and the other shortcuts when only the level differs and no per-call target override is needed.