📝 document public config and level aliases

docs/api/queue-overflow-policy.md

@@ -0,0 +1,70 @@
+---
+name: queue-overflow-policy
+group: api
+category: sink
+update-time: 20260613
+description: Public overflow policy alias used by synchronous queued sinks and queue config.
+key-word:
+    - queue
+    - overflow
+    - alias
+    - public
+---
+
+## Queue-overflow-policy
+
+`QueueOverflowPolicy` is the public enum that defines what a synchronous queue should do when it reaches `max_pending`. It is a direct alias to the queue model enum used by both `QueuedSink` and `QueueConfig`.
+
+### Interface
+
+```moonbit
+pub type QueueOverflowPolicy = @utils.QueueOverflowPolicy
+```
+
+#### output
+
+- `QueueOverflowPolicy` - Public synchronous queue overflow enum with the variants `DropNewest` and `DropOldest`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a separate policy wrapper.
+- `QueueOverflowPolicy::DropNewest` keeps the existing queued records and drops the incoming one when the queue is full.
+- `QueueOverflowPolicy::DropOldest` removes one pending record and enqueues the new record instead.
+- The same enum is used by code-side queue composition through `queued_sink(...)` and config-driven queue composition through `QueueConfig::new(...)`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Bounded Queue That Prefers Older Pending Records
+
+When the oldest pending records should be preserved and new bursts can be dropped:
+```moonbit
+let sink = queued_sink(console_sink(), max_pending=32, overflow=QueueOverflowPolicy::DropNewest)
+```
+
+In this example, new records are discarded once the queue is full.
+
+#### When Need To Prefer Fresh Records Over Old Pending Work
+
+When backlog should make room for newer records:
+```moonbit
+let queue = QueueConfig::new(32, overflow=QueueOverflowPolicy::DropOldest)
+```
+
+In this example, the oldest pending record is removed when the queue overflows.
+
+### Error Case
+
+e.g.:
+- If a queue is unbounded or never reaches capacity, the overflow policy has no effect.
+
+- If parsed JSON uses unsupported overflow text, config parsing raises `ConfigError`.
+
+### Notes
+
+1. This policy belongs to synchronous queue wrappers, not `bitlogger_async`.
+
+2. Use `AsyncOverflowPolicy` for the async logger queue behavior.