📝 consolidate logger API and async lifecycle guidance

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

@@ -2,8 +2,8 @@
 name: async-logger-state-new
 group: api
 category: async
-update-time: 20260613
-description: Construct an AsyncLoggerState snapshot from explicit runtime, queue, lifecycle, and failure values.
+update-time: 20260614
+description: Construct an AsyncLoggerState snapshot from explicit runtime, queue, lifecycle, failure, and flush-policy values without probing a live logger.
 key-word:
     - async
     - logger
@@ -52,7 +52,12 @@ Detailed rules explaining key parameters and behaviors
 - This constructor simply packages the supplied fields into one public snapshot value.
 - It does not inspect a live logger instance by itself.
 - `AsyncLogger::state()` is the higher-level API that reads these values from a concrete logger.
+- It also does not validate whether the supplied fields represent a combination that could come from one real logger instant.
+- The supplied `runtime : AsyncRuntimeState` is stored exactly as provided; this constructor does not recompute `mode` or `background_worker` from the active backend.
 - The constructed value matches the same public shape used by async logger serializers.
+- Because `AsyncLoggerState` is only a data snapshot type, this constructor is mainly useful for tests, adapters, and synthetic diagnostics rather than ordinary logger inspection.
+- Serialization helpers accept any `AsyncLoggerState` value, including hand-built ones from this constructor.
+- That includes combinations such as `has_failed=true` together with non-zero `pending_count` or a retained `last_error`, and even a manually chosen runtime snapshot that does not match the current backend, all of which are valid for diagnostic snapshots and test fixtures.
 
 ### How to Use
 
@@ -101,8 +106,16 @@ e.g.:
 
 - If callers want a snapshot directly from one live logger instance, `AsyncLogger::state()` is the simpler API.
 
+- If callers manually combine a runtime snapshot, counters, or flush policy that do not actually belong together, the constructor still accepts that synthetic snapshot.
+
+- If callers want the current backend-derived runtime pair instead of a synthetic one, they must pass `async_runtime_state()` explicitly or use `AsyncLogger::state()`.
+
+- This constructor does not apply cleanup semantics such as clearing `last_error` on restart or draining pending records; callers must provide those fields exactly as they want them represented.
+
 ### Notes
 
 1. Use this helper when code should construct an `AsyncLoggerState` value explicitly.
 
 2. Pair it with `async_logger_state_to_json(...)` or `stringify_async_logger_state(...)` when the snapshot should be exported.
+
+3. Prefer `AsyncLogger::state()` when the goal is to report the actual current state of one live logger instance.