📝 document public config and level aliases

docs/api/async-overflow-policy.md

@@ -0,0 +1,71 @@
+---
+name: async-overflow-policy
+group: api
+category: async
+update-time: 20260613
+description: Public overflow policy alias used by AsyncLoggerConfig and async queue behavior.
+key-word:
+    - async
+    - overflow
+    - alias
+    - public
+---
+
+## Async-overflow-policy
+
+`AsyncOverflowPolicy` is the public enum that controls what an `AsyncLogger` should do when its queue cannot accept a record immediately. It is a direct alias to the async model enum used by `AsyncLoggerConfig` and the runtime queue selection logic.
+
+### Interface
+
+```moonbit
+pub type AsyncOverflowPolicy = @utils.AsyncOverflowPolicy
+```
+
+#### output
+
+- `AsyncOverflowPolicy` - Public async queue overflow enum with the variants `Blocking`, `DropOldest`, and `DropNewest`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a separate runtime adapter.
+- `AsyncOverflowPolicy::Blocking` waits for queue space when a non-blocking enqueue does not succeed.
+- `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`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Backpressure Instead Of Silent Dropping
+
+When producers should wait for queue space:
+```moonbit
+let config = AsyncLoggerConfig::new(max_pending=64, overflow=AsyncOverflowPolicy::Blocking)
+```
+
+In this example, logging pressure can slow producers instead of dropping data immediately.
+
+#### When Need Bounded Async Logging With Drop Behavior
+
+When async logging should keep moving under load without blocking callers:
+```moonbit
+let config = AsyncLoggerConfig::new(max_pending=64, overflow=AsyncOverflowPolicy::DropNewest)
+```
+
+In this example, the incoming record is dropped if the queue cannot accept it.
+
+### Error Case
+
+e.g.:
+- If async config text uses unsupported overflow text, async config parsing raises a failure.
+
+- Under drop policies, sustained overload increases `dropped_count()` instead of guaranteeing delivery.
+
+### Notes
+
+1. This policy applies to `bitlogger_async`, not synchronous `QueuedSink`.
+
+2. Choose `Blocking` only when producer-side waiting is acceptable for the caller.