📝 clarify async state snapshot docs

docs/api/async-logger-last-error.md

@@ -33,12 +33,12 @@ pub fn[S] AsyncLogger::last_error(self : AsyncLogger[S]) -> String {}
 
 Detailed rules explaining key parameters and behaviors
 
-- `run()` resets the stored error string when the worker starts.
+- A later `run()` clears the stored error string only after that run has actually started.
 - If the worker loop fails, the error text is captured from the raised exception.
 - An empty string normally means no failure has been recorded.
 - Once a failure string is recorded, it stays in place until a later `run()` invocation actually starts and clears it.
 - This helper reports worker execution errors, not ordinary overflow or backpressure conditions.
-- A new successful `run()` attempt clears any previously stored error text before drain work begins again.
+- That reset happens before the restarted worker resumes drain work.
 
 ### How to Use
 
@@ -73,7 +73,7 @@ e.g.:
 
 - If callers need broader context than just the error text, they should use `state()`.
 
-- `close()` or `shutdown()` do not clear a previously recorded error string by themselves; the reset happens when a later `run()` has already started.
+- `close()` or `shutdown()` do not clear a previously recorded error string by themselves; the reset happens only after a later `run()` has already started.
 
 ### Notes
 
@@ -81,4 +81,4 @@ e.g.:
 
 2. The stored value is a diagnostic string, not a typed error object.
 
-3. Pair it with `is_running()` or `pending_count()` when you need to know whether failure left the logger with unfinished backlog.
+3. Pair it with `is_running()` or `pending_count()` when you need to know whether failure left the logger with unfinished backlog, because the previous error string can coexist with remaining pending records until later cleanup or restart.

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

@@ -56,6 +56,7 @@ Detailed rules explaining key parameters and behaviors
 - 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`, which are valid for diagnostic snapshots and test fixtures.
 
 ### How to Use
 
@@ -106,6 +107,8 @@ e.g.:
 
 - If callers manually combine a runtime snapshot, counters, or flush policy that do not actually belong together, the constructor still accepts that synthetic snapshot.
 
+- 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.

docs/api/async-logger-state.md

@@ -40,6 +40,8 @@ Detailed rules explaining key parameters and behaviors
 - `runtime` embeds the result of `async_runtime_state()` so callers do not need to join separate helpers manually.
 - Because the snapshot is assembled field by field when `state()` is called, later logger changes require calling `state()` again rather than reusing an older `AsyncLoggerState` value as if it refreshed itself.
 - That field-by-field assembly also means this helper is not an atomic freeze across all refs; under concurrent logger activity, neighboring fields can reflect slightly different instants.
+- After a worker failure, `has_failed=true`, a non-empty `last_error`, and `pending_count>0` can legitimately appear together in one snapshot until later cleanup or a later started `run()` changes them.
+- `state()` only reports the current field values; it does not clear failure state, drain backlog, or synchronize pending work by itself.
 
 ### How to Use
 
@@ -69,6 +71,8 @@ if state.has_failed {
 
 In this example, the same snapshot object works for conditional diagnostics and serialization.
 
+And the reported failure fields can still appear together with non-zero backlog when a worker stopped early.
+
 ### Error Case
 
 e.g.:
@@ -80,6 +84,8 @@ e.g.:
 
 - If concurrent logger activity is still changing counters or flags while `state()` runs, the returned value is still useful for diagnostics but should not be treated as a transactional snapshot.
 
+- A snapshot showing `has_failed=true` does not imply `pending_count` is already `0`; remaining queued records may still be visible until later cleanup or restart.
+
 ### Notes
 
 1. Prefer this API over manually combining `pending_count()`, `dropped_count()`, and runtime-mode helpers.