📝 refine async policy docs

docs/api/async-flush-policy.md

@@ -2,8 +2,8 @@
 name: async-flush-policy
 group: api
 category: async
-update-time: 20260613
-description: Public flush policy alias used by AsyncLoggerConfig and async worker flushing.
+update-time: 20260614
+description: Public flush policy alias used by AsyncLoggerConfig, async parser labels, and async worker flushing.
 key-word:
     - async
     - flush
@@ -34,6 +34,8 @@ Detailed rules explaining key parameters and behaviors
 - `AsyncFlushPolicy::Batch` calls the configured flush function after each processed batch.
 - `AsyncFlushPolicy::Shutdown` calls the configured flush function once after the worker loop exits.
 - The current flush policy is also exposed through `AsyncLogger::flush_policy()` and included in `AsyncLoggerState`.
+- Async config parsing accepts the canonical label `Never` and also the compatibility alias `None`, both mapping to the same public enum variant.
+- `Batch` flushing happens after the worker finishes one drained batch, not after every individual record write.
 
 ### How to Use
 
@@ -64,8 +66,12 @@ e.g.:
 
 - If a sink never needs explicit flushing, `Batch` or `Shutdown` can add unnecessary work without changing output.
 
+- If the configured flush callback raises, the worker records failure state and stops instead of silently hiding the error.
+
 ### Notes
 
 1. This policy only affects the async logger path and only matters when the configured sink has a meaningful flush function.
 
 2. `AsyncFlushPolicy::Never` is the default in `AsyncLoggerConfig::new(...)`.
+
+3. Serialized config uses the canonical `Never` label even though the parser also accepts `None`.

docs/api/async-logger-flush-policy.md

@@ -2,8 +2,8 @@
 name: async-logger-flush-policy
 group: api
 category: async
-update-time: 20260512
-description: Read the async logger flush policy currently governing batch and shutdown flushing behavior.
+update-time: 20260614
+description: Read the async logger flush policy currently governing batch-end and shutdown-end flushing behavior.
 key-word:
     - async
     - logger
@@ -34,8 +34,8 @@ pub fn[S] AsyncLogger::flush_policy(self : AsyncLogger[S]) -> AsyncFlushPolicy {
 Detailed rules explaining key parameters and behaviors
 
 - The returned value reflects the policy captured when the async logger was created.
-- `Batch` causes explicit flush calls after worker batch processing.
-- `Shutdown` causes explicit flush calls at worker shutdown.
+- `Batch` causes explicit flush calls after each completed drained batch, not after every individual record write.
+- `Shutdown` causes one explicit flush call after the worker loop exits.
 - `Never` leaves flushing entirely to sink behavior or external control.
 
 ### How to Use

docs/api/async-overflow-policy.md

@@ -2,8 +2,8 @@
 name: async-overflow-policy
 group: api
 category: async
-update-time: 20260613
-description: Public overflow policy alias used by AsyncLoggerConfig and async queue behavior.
+update-time: 20260614
+description: Public overflow policy alias used by AsyncLoggerConfig, async parser labels, and runtime queue behavior.
 key-word:
     - async
     - overflow
@@ -34,6 +34,8 @@ Detailed rules explaining key parameters and behaviors
 - `AsyncOverflowPolicy::DropOldest` lets the underlying async queue discard older pending records when capacity is limited.
 - `AsyncOverflowPolicy::DropNewest` discards the incoming record instead of blocking.
 - The same enum is used by `AsyncLoggerConfig::new(...)`, async config parsing, and the queue-kind mapping inside `AsyncLogger`.
+- Async config parsing accepts the canonical label `DropNewest` and also the compatibility alias `DropLatest`, both mapping to the same public enum variant.
+- When `try_put(...)` reports that a record was not accepted under a drop policy, `dropped_count()` increases for that rejected enqueue.
 
 ### How to Use
 
@@ -64,8 +66,12 @@ e.g.:
 
 - Under drop policies, sustained overload increases `dropped_count()` instead of guaranteeing delivery.
 
+- The precise record discarded by the underlying queue behavior depends on the selected policy and queue implementation, so callers should not assume `dropped_count()` alone identifies which message was lost.
+
 ### Notes
 
 1. This policy applies to `bitlogger_async`, not synchronous `QueuedSink`.
 
 2. Choose `Blocking` only when producer-side waiting is acceptable for the caller.
+
+3. Serialized config uses the canonical `DropNewest` label even though the parser also accepts `DropLatest`.