📝 clarify async config docs

docs/api/async-logger-config-to-json.md

@@ -2,8 +2,8 @@
 name: async-logger-config-to-json
 group: api
 category: async
-update-time: 20260512
-description: Convert AsyncLoggerConfig into a JSON value for export, persistence, or generated async config output.
+update-time: 20260614
+description: Convert AsyncLoggerConfig into a JSON value for export, persistence, or generated async config output using the stable serialized policy labels.
 key-word:
     - async
     - config
@@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors
 - The output includes `max_pending`, `max_batch`, `linger_ms`, `overflow`, and `flush`.
 - Policy fields are serialized using the stable labels accepted by the config parser.
 - This helper exports effective typed config after constructor normalization has already happened.
+- If `max_pending` is negative in the config object, the exported JSON preserves that negative value because runtime queue clamping happens later, not during serialization.
 - The JSON shape matches the `async_config` section used by async build config parsing.
 
 ### How to Use
@@ -67,5 +68,13 @@ In this example, the exported JSON stays aligned with parser expectations.
 e.g.:
 - If `max_batch` or `linger_ms` were normalized during construction, the exported JSON reflects the normalized values rather than the original invalid inputs.
 
+- If callers need to understand runtime queue behavior for negative `max_pending`, they should document that separately because serialization preserves the config value rather than the later queue-kind clamp.
+
 - If callers want direct text output instead of a JSON value, they should use `stringify_async_logger_config(...)` instead.
 
+### Notes
+
+1. Serialized policy labels round-trip through `parse_async_logger_config_text(...)`.
+
+2. The serializer emits canonical labels like `DropNewest` and `Never`, even though the parser also accepts compatibility aliases such as `DropLatest` and `None`.
+

docs/api/async-logger-config-type.md

@@ -2,8 +2,8 @@
 name: async-logger-config-type
 group: api
 category: async
-update-time: 20260613
-description: Public async logger config alias used for queue, batching, linger, and flush settings.
+update-time: 20260614
+description: Public async logger config alias used for async queue interpretation, batching, linger, and flush settings.
 key-word:
     - async
     - config
@@ -31,8 +31,10 @@ Detailed rules explaining key parameters and behaviors
 
 - This is a type alias, not a runtime logger handle.
 - The current fields are `max_pending : Int`, `overflow : AsyncOverflowPolicy`, `max_batch : Int`, `linger_ms : Int`, and `flush : AsyncFlushPolicy`.
-- `AsyncLoggerConfig::new(...)` constructs this type with the same normalization rules used by the runtime.
+- `AsyncLoggerConfig::new(...)` normalizes `max_batch` and `linger_ms`, but it preserves the provided `max_pending` value.
+- Runtime queue creation later interprets negative `max_pending` as `0` when choosing the internal queue kind.
 - `parse_async_logger_config_text(...)`, `async_logger_config_to_json(...)`, and `stringify_async_logger_config(...)` all operate on this same public config shape.
+- The parser accepts the stable serialized labels such as `DropNewest` and `Never`, plus compatibility aliases such as `DropLatest` and `None`.
 
 ### How to Use
 
@@ -65,10 +67,14 @@ In this example, the same public config object supports both inspection and late
 e.g.:
 - `AsyncLoggerConfig` itself does not have a runtime failure mode.
 
-- Constructor normalization still applies when the value is created through `AsyncLoggerConfig::new(...)`, so very small or negative timing and batch inputs may be adjusted before later serialization or use.
+- Constructor normalization still applies when the value is created through `AsyncLoggerConfig::new(...)`, so very small batch sizes and negative linger values may be adjusted before later serialization or use.
+
+- Negative `max_pending` is not rewritten inside the config object itself; it is only clamped later when the async queue kind is derived at runtime.
 
 ### Notes
 
 1. Use `AsyncLoggerConfig::new(...)` when you need a value of this type in code.
 
 2. Use `AsyncLoggerBuildConfig` when the async config should travel together with the base synchronous `LoggerConfig`.
+
+3. Use `parse_async_logger_config_text(...)` when the same shape should come from JSON text, including accepted aliases like `DropLatest` and `None`.

docs/api/async-logger-config.md

@@ -2,8 +2,8 @@
 name: async-logger-config
 group: api
 category: async
-update-time: 20260512
-description: Create the queue, batching, linger, and flush policy config used by async loggers.
+update-time: 20260614
+description: Create the async queue, batching, linger, and flush policy config used by async loggers.
 key-word:
     - async
     - config
@@ -29,7 +29,7 @@ pub fn AsyncLoggerConfig::new(
 
 #### input
 
-- `max_pending : Int` - Maximum queued records.
+- `max_pending : Int` - Requested maximum queued records before overflow policy matters; negative values are preserved in the config object and later treated as `0` by runtime queue creation.
 - `overflow : AsyncOverflowPolicy` - Queue overflow strategy.
 - `max_batch : Int` - Maximum records drained per batch.
 - `linger_ms : Int` - Optional wait window for batch accumulation.
@@ -45,6 +45,8 @@ Detailed rules explaining key parameters and behaviors
 
 - `max_batch <= 1` is normalized to `1`.
 - `linger_ms < 0` is normalized to `0`.
+- `max_pending` is stored as provided by the constructor.
+- When the async logger runtime later builds its internal queue, negative `max_pending` is interpreted as `0`.
 - `overflow` and `flush` define the most important queue/runtime behavior tradeoffs.
 - This type is used directly by `async_logger(...)` and embedded in `AsyncLoggerBuildConfig`.
 
@@ -79,12 +81,14 @@ In this example, the config becomes a stable JSON payload.
 ### Error Case
 
 e.g.:
-- If `max_batch` is set to `0` or below, runtime config normalizes it to `1`.
+- If `max_batch` is set to `0` or below, constructor normalization changes it to `1`.
 
-- If `linger_ms` is negative, it is normalized to `0`.
+- If `linger_ms` is negative, constructor normalization changes it to `0`.
 
 ### Notes
 
 1. This type controls async runtime behavior, not synchronous queue wrapping.
 
 2. Prefer explicit values for production services so overflow and flush semantics are visible.
+
+3. If queue limit semantics for negative values matter, document that behavior explicitly in calling code because the config object preserves the negative value while the runtime queue later clamps it to `0`.

docs/api/parse-async-logger-config-text.md

@@ -2,8 +2,8 @@
 name: parse-async-logger-config-text
 group: api
 category: async
-update-time: 20260520
-description: Parse JSON text into an AsyncLoggerConfig.
+update-time: 20260614
+description: Parse JSON text into an AsyncLoggerConfig, applying async config defaults and accepted policy aliases.
 key-word:
     - async
     - config
@@ -34,7 +34,10 @@ pub fn parse_async_logger_config_text(input : String) -> AsyncLoggerConfig raise
 Detailed rules explaining key parameters and behaviors
 
 - This helper parses only the async config portion, not the embedded sync `LoggerConfig`.
-- Parsed values follow the same normalization and enum validation rules as other async config helpers.
+- Missing `max_pending`, `overflow`, `max_batch`, `linger_ms`, and `flush` fields fall back to the same defaults used by `AsyncLoggerConfig::new(...)`.
+- Parsed values then flow through `AsyncLoggerConfig::new(...)`, so `max_batch` and `linger_ms` receive the same constructor normalization.
+- Overflow parsing accepts both `DropNewest` and the compatibility alias `DropLatest`.
+- Flush parsing accepts both `Never` and the compatibility alias `None`.
 - Use this API when async policy comes from config text but sink choice is still assembled elsewhere.
 
 ### How to Use
@@ -52,6 +55,17 @@ let config = parse_async_logger_config_text(
 
 In this example, async queue and flush policy are parsed from text into a typed config object.
 
+#### When Need Alias-friendly Async Policy Parsing
+
+When external config may use compatibility labels:
+```moonbit
+let config = parse_async_logger_config_text(
+  "{\"overflow\":\"DropLatest\",\"flush\":\"None\"}",
+)
+```
+
+In this example, parser aliases are accepted and normalized into the public enum values.
+
 ### Error Case
 
 e.g.:
@@ -59,8 +73,12 @@ e.g.:
 
 - If enum names such as `overflow` or `flush` are unsupported, parsing raises an error.
 
+- If a field is present with the wrong JSON type, parsing raises an error instead of silently coercing it.
+
 ### Notes
 
 1. Use this helper when only async policy is text-driven.
 
 2. Use `parse_async_logger_build_config_text(...)` when both sync logger config and async config come from the same JSON payload.
+
+3. Omitted fields fall back to the default async config values rather than causing a missing-field error.

docs/api/stringify-async-logger-config.md

@@ -2,8 +2,8 @@
 name: stringify-async-logger-config
 group: api
 category: async
-update-time: 20260512
-description: Serialize AsyncLoggerConfig into compact or pretty JSON text for export and diagnostics.
+update-time: 20260614
+description: Serialize AsyncLoggerConfig into compact or pretty JSON text for export and diagnostics using the canonical async policy labels.
 key-word:
     - async
     - config
@@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors
 - `pretty=true` returns indented JSON for humans.
 - This helper is built on top of `async_logger_config_to_json(...)`.
 - The exported text follows the supported async config schema rather than internal queue implementation details.
+- Canonical policy labels such as `DropNewest` and `Never` are emitted even though the parser also accepts aliases like `DropLatest` and `None`.
 
 ### How to Use
 
@@ -70,3 +71,9 @@ e.g.:
 
 - If invalid constructor inputs were normalized earlier, the resulting text contains the normalized config values.
 
+### Notes
+
+1. Use this helper when async policy should be copied or logged as text directly.
+
+2. If negative `max_pending` semantics matter, remember that the serialized text preserves the config value while runtime queue creation later clamps the queue limit to `0`.
+