📝 refine async state snapshot docs

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

@@ -55,6 +55,7 @@ Detailed rules explaining key parameters and behaviors
 - It also does not validate whether the supplied fields represent a combination that could come from one real logger instant.
 - 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.
 
 ### How to Use
 

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

@@ -13,7 +13,7 @@ key-word:
 
 ## Async-logger-state-to-json
 
-Convert `AsyncLoggerState` into a `JsonValue`. This helper is the structured export path for async logger runtime snapshots when callers want machine-readable diagnostics instead of a plain string.
+Convert `AsyncLoggerState` into a `JsonValue`. This helper is the structured export path for async logger runtime snapshots or manually constructed state values when callers want machine-readable diagnostics instead of a plain string.
 
 ### Interface
 
@@ -23,7 +23,7 @@ pub fn async_logger_state_to_json(state : AsyncLoggerState) -> @json_parser.Json
 
 #### input
 
-- `state : AsyncLoggerState` - Snapshot produced by `AsyncLogger::state()`.
+- `state : AsyncLoggerState` - Snapshot produced by `AsyncLogger::state()` or any manually constructed `AsyncLoggerState` value.
 
 #### output
 
@@ -39,7 +39,7 @@ Detailed rules explaining key parameters and behaviors
 - The public helper returns the same internal JSON snapshot shape used by `stringify_async_logger_state(...)`, so both export paths stay aligned without duplicate field assembly logic.
 - 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 before serialization.
+- The state must already have been captured or constructed before serialization.
 
 ### How to Use
 
@@ -79,5 +79,5 @@ e.g.:
 
 3. Use this API when downstream code wants a JSON value rather than a ready-made string.
 
-4. Pair it with `AsyncLogger::state()` to capture the snapshot first.
+4. Pair it with `AsyncLogger::state()` when you want current logger data, or with `AsyncLoggerState::new(...)` when tests or adapters are exporting a synthetic snapshot.
 

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

@@ -34,6 +34,7 @@ Detailed rules explaining key parameters and behaviors
 - The remaining fields capture queue counts, lifecycle status, failure state, last error text, and active flush policy.
 - `AsyncLogger::state()` returns this type directly, while `async_logger_state_to_json(...)` and `stringify_async_logger_state(...)` export the same data shape for diagnostics.
 - `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.
 
 ### How to Use

docs/api/async-logger-state.md

@@ -34,11 +34,12 @@ pub fn[S] AsyncLogger::state(self : AsyncLogger[S]) -> AsyncLoggerState {}
 Detailed rules explaining key parameters and behaviors
 
 - `AsyncLoggerState` includes `runtime`, `pending_count`, `dropped_count`, `is_closed`, `is_running`, `has_failed`, `last_error`, and `flush_policy`.
-- `state()` returns a point-in-time snapshot rather than a live handle.
+- `state()` returns a value snapshot rather than a live handle.
 - This helper is equivalent to `AsyncLoggerState::new(async_runtime_state(), self.pending_count(), self.dropped_count(), self.is_closed(), self.is_running(), self.has_failed(), self.last_error(), self.flush_policy())`.
 - `async_logger_state_to_json(...)` and `stringify_async_logger_state(...)` convert the snapshot to stable diagnostic output.
 - `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.
 
 ### How to Use
 
@@ -77,6 +78,8 @@ e.g.:
 
 - `flush_policy` reports the logger's configured async flush mode, not whether a flush has already happened.
 
+- 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.
+
 ### Notes
 
 1. Prefer this API over manually combining `pending_count()`, `dropped_count()`, and runtime-mode helpers.
@@ -84,3 +87,5 @@ e.g.:
 2. Use `pretty=true` when emitting logs for humans and the compact form for machine-oriented payloads.
 
 3. Use `AsyncLoggerState::new(...)` only when tests or adapters need to construct a manual snapshot instead of reading one directly from a logger instance.
+
+4. If consumers need stronger cross-field consistency than a diagnostic snapshot, they should not assume `state()` provides an atomic read barrier.

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

@@ -13,7 +13,7 @@ key-word:
 
 ## Stringify-async-logger-state
 
-Serialize `AsyncLoggerState` into JSON text. This is the highest-level diagnostic export helper for async logger snapshots when callers want immediate text output.
+Serialize `AsyncLoggerState` into JSON text. This is the highest-level diagnostic export helper for async logger snapshots or manually constructed state values when callers want immediate text output.
 
 ### Interface
 
@@ -26,7 +26,7 @@ pub fn stringify_async_logger_state(
 
 #### input
 
-- `state : AsyncLoggerState` - Snapshot produced by `AsyncLogger::state()`.
+- `state : AsyncLoggerState` - Snapshot produced by `AsyncLogger::state()` or any manually constructed `AsyncLoggerState` value.
 - `pretty : Bool` - Whether JSON should be pretty-printed.
 
 #### output
@@ -43,6 +43,7 @@ Detailed rules explaining key parameters and behaviors
 - Internally it stringifies the same JSON snapshot shape returned by the public export helper, using `@json_parser.stringify(...)` or `@json_parser.stringify_pretty(value, 2)`.
 - 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.
 
 ### How to Use
 
@@ -81,3 +82,5 @@ e.g.:
 
 3. Use `async_logger_state_to_json(...)` when the next consumer still needs a `JsonValue` for composition before final stringification.
 
+4. Pair it with `AsyncLogger::state()` for current logger diagnostics, or with `AsyncLoggerState::new(...)` when exporting a manual snapshot built by tests or adapters.
+