📝 align async state serializer docs

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

@@ -40,6 +40,7 @@ Detailed rules explaining key parameters and behaviors
 - This helper is suitable for health endpoints, diagnostics payloads, and custom serialization flows.
 - It shares the same stable field names used by `stringify_async_logger_state(...)`.
 - The state must already have been captured or constructed before serialization.
+- Serialization preserves whatever snapshot combination it receives, including failure flags together with remaining backlog counts.
 
 ### How to Use
 
@@ -71,6 +72,8 @@ e.g.:
 
 - If the queue is empty, `pending_count` and `dropped_count` are still serialized normally as numeric values.
 
+- If `has_failed` is `true`, serialization does not force `pending_count` to `0` or clear `last_error`; it reports the snapshot exactly as provided.
+
 ### Notes
 
 1. This helper preserves the nested runtime snapshot instead of flattening `mode` and `background_worker` onto the top level.

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

@@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors
 - `AsyncLogger::state()` currently builds this snapshot from `async_runtime_state()` plus the logger's current counters, lifecycle flags, last error, and flush policy.
 - When the value comes from `AsyncLogger::state()`, the fields are read one by one rather than through a transactional snapshot primitive.
 - `AsyncLoggerState::new(...)` can also construct this type manually, but manual construction is synthetic snapshot data and does not read one live logger instant by itself.
+- When a live snapshot is taken after worker failure, `has_failed=true`, a retained `last_error`, and non-zero `pending_count` may legitimately coexist until later cleanup or restart.
 
 ### How to Use
 
@@ -71,6 +72,8 @@ e.g.:
 
 - Because this is just a data shape, manual construction can represent combinations that do not come from a live logger at one exact instant.
 
+- This type does not imply cleanup semantics by itself; values only report the supplied or captured fields and do not drain backlog or clear recorded failure state.
+
 ### Notes
 
 1. Use `AsyncLogger::state()` when you need a value of this type from one logger instance.

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

@@ -44,6 +44,7 @@ Detailed rules explaining key parameters and behaviors
 - The compact form matches snapshots such as `{"runtime":{"mode":"native_worker","background_worker":true},"pending_count":0,...}`.
 - String output is convenient for logs, CLI output, and startup diagnostics.
 - The serializer does not care whether the input came from a live logger read or a synthetic `AsyncLoggerState::new(...)` call.
+- It also preserves mixed diagnostic states exactly as provided, such as a failure flag together with non-zero backlog.
 
 ### How to Use
 
@@ -74,6 +75,8 @@ e.g.:
 
 - If callers need a JSON value instead of text, they should use `async_logger_state_to_json(...)` instead.
 
+- Stringification does not apply cleanup behavior; it only formats the supplied snapshot fields.
+
 ### Notes
 
 1. The nested `runtime` section uses the same canonical mode labels as `stringify_async_runtime_state(...)`.