📝 align async logger state docs

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,6 +52,7 @@ 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 constructed value matches the same public shape used by async logger serializers.
 
 ### How to Use
@@ -101,8 +102,12 @@ 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.
+
 ### 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.

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

@@ -2,8 +2,8 @@
 name: async-logger-state-to-json
 group: api
 category: async
-update-time: 20260512
-description: Convert an AsyncLoggerState snapshot into a JSON value for diagnostics and transport.
+update-time: 20260614
+description: Convert an AsyncLoggerState snapshot into a JSON value for diagnostics and transport using the canonical nested runtime shape and flush-policy labels.
 key-word:
     - async
     - state
@@ -34,6 +34,8 @@ pub fn async_logger_state_to_json(state : AsyncLoggerState) -> @json_parser.Json
 Detailed rules explaining key parameters and behaviors
 
 - The JSON includes runtime mode, worker support, queue counters, lifecycle flags, last error, and flush policy.
+- The top-level fields are `runtime`, `pending_count`, `dropped_count`, `is_closed`, `is_running`, `has_failed`, `last_error`, and `flush_policy`.
+- The nested `runtime` field reuses `async_runtime_state_to_json(...)`, and `flush_policy` is serialized with the canonical labels `Never`, `Batch`, or `Shutdown`.
 - 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.
@@ -70,7 +72,11 @@ e.g.:
 
 ### Notes
 
-1. Use this API when downstream code wants a JSON value rather than a ready-made string.
+1. This helper preserves the nested runtime snapshot instead of flattening `mode` and `background_worker` onto the top level.
 
-2. Pair it with `AsyncLogger::state()` to capture the snapshot first.
+2. The resulting object matches the compact string form produced by `stringify_async_logger_state(...)` after JSON stringification.
+
+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.
 

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

@@ -2,8 +2,8 @@
 name: async-logger-state-type
 group: api
 category: async
-update-time: 20260613
-description: Public async logger state alias used for queue, lifecycle, and runtime diagnostics.
+update-time: 20260614
+description: Public async logger state alias used for queue, lifecycle, runtime, and flush-policy diagnostics.
 key-word:
     - async
     - logger
@@ -33,6 +33,7 @@ Detailed rules explaining key parameters and behaviors
 - The `runtime` field embeds an `AsyncRuntimeState` snapshot.
 - 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.
 
 ### How to Use
 
@@ -66,8 +67,12 @@ e.g.:
 
 - `last_error` may be an empty string when no failure has occurred, which is normal and not a special error condition by itself.
 
+- Because this is just a data shape, manual construction can represent combinations that do not come from a live logger at one exact instant.
+
 ### Notes
 
 1. Use `AsyncLogger::state()` when you need a value of this type from one logger instance.
 
 2. Use `AsyncRuntimeState` when only backend-level capability information is needed and logger-instance state is unnecessary.
+
+3. Use `async_logger_state_to_json(...)` or `stringify_async_logger_state(...)` when this snapshot should leave typed space and become stable diagnostic output.

docs/api/async-logger-state.md

@@ -2,8 +2,8 @@
 name: async-logger-state
 group: api
 category: async
-update-time: 20260512
-description: Read a full async logger runtime snapshot including queue counters, lifecycle flags, and runtime mode.
+update-time: 20260614
+description: Read a full async logger runtime snapshot including the embedded runtime snapshot, queue counters, lifecycle flags, last error, and flush policy.
 key-word:
     - async
     - state
@@ -35,6 +35,7 @@ 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.
+- 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.
 
@@ -73,8 +74,12 @@ e.g.:
 
 - If the queue is empty, `pending_count` is `0`; this is normal and not a special error condition.
 
+- `flush_policy` reports the logger's configured async flush mode, not whether a flush has already happened.
+
 ### Notes
 
 1. Prefer this API over manually combining `pending_count()`, `dropped_count()`, and runtime-mode helpers.
 
 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.

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

@@ -2,8 +2,8 @@
 name: stringify-async-logger-state
 group: api
 category: async
-update-time: 20260512
-description: Serialize AsyncLoggerState into compact or pretty JSON text for logs and diagnostics.
+update-time: 20260614
+description: Serialize AsyncLoggerState into compact or pretty JSON text for logs and diagnostics using the canonical nested runtime snapshot shape.
 key-word:
     - async
     - stringify
@@ -40,6 +40,7 @@ Detailed rules explaining key parameters and behaviors
 - `pretty=false` returns compact JSON.
 - `pretty=true` returns indented JSON suitable for human diagnostics.
 - This helper is built on top of `async_logger_state_to_json(...)`.
+- 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.
 
 ### How to Use
@@ -71,3 +72,9 @@ e.g.:
 
 - If callers need a JSON value instead of text, they should use `async_logger_state_to_json(...)` instead.
 
+### Notes
+
+1. The nested `runtime` section uses the same canonical mode labels as `stringify_async_runtime_state(...)`.
+
+2. The compact output shape is already locked by the async runtime snapshot tests, so it is suitable for stable diagnostics and assertions.
+