📝 document async state constructors

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

@@ -0,0 +1,108 @@
+---
+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.
+key-word:
+    - async
+    - logger
+    - state
+    - public
+---
+
+## Async-logger-state-new
+
+Construct an `AsyncLoggerState` snapshot from explicit runtime, queue, lifecycle, and failure values. This is the low-level constructor behind the public async logger state shape used in diagnostics.
+
+### Interface
+
+```moonbit
+pub fn AsyncLoggerState::new(
+  runtime : AsyncRuntimeState,
+  pending_count : Int,
+  dropped_count : Int,
+  is_closed : Bool,
+  is_running : Bool,
+  has_failed : Bool,
+  last_error : String,
+  flush_policy : AsyncFlushPolicy,
+) -> AsyncLoggerState {
+```
+
+#### input
+
+- `runtime : AsyncRuntimeState` - Embedded backend-level runtime snapshot.
+- `pending_count : Int` - Current async queue backlog.
+- `dropped_count : Int` - Current dropped-record count.
+- `is_closed : Bool` - Whether the logger has been closed.
+- `is_running : Bool` - Whether the logger worker loop is currently running.
+- `has_failed : Bool` - Whether the logger has recorded a runtime failure state.
+- `last_error : String` - Latest error text, or an empty string when no failure has been recorded.
+- `flush_policy : AsyncFlushPolicy` - Active async flush policy for the logger.
+
+#### output
+
+- `AsyncLoggerState` - Full async logger snapshot containing the supplied runtime, queue, lifecycle, and failure values.
+
+### Explanation
+
+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.
+- The constructed value matches the same public shape used by async logger serializers.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Hand-built Async Logger Snapshot
+
+When tests or adapters should construct a full async logger state explicitly:
+```moonbit
+let state = AsyncLoggerState::new(
+  runtime=AsyncRuntimeState::new(AsyncRuntimeMode::Compatibility, false),
+  pending_count=0,
+  dropped_count=0,
+  is_closed=false,
+  is_running=true,
+  has_failed=false,
+  last_error="",
+  flush_policy=AsyncFlushPolicy::Never,
+)
+```
+
+In this example, a complete async logger snapshot is assembled directly without querying a live logger instance.
+
+#### When Need Structured Diagnostics Input Before Serialization
+
+When code should prepare a typed logger state value for later export:
+```moonbit
+let state = AsyncLoggerState::new(
+  runtime=async_runtime_state(),
+  pending_count=logger.pending_count(),
+  dropped_count=logger.dropped_count(),
+  is_closed=logger.is_closed(),
+  is_running=logger.is_running(),
+  has_failed=logger.has_failed(),
+  last_error=logger.last_error(),
+  flush_policy=logger.flush_policy(),
+)
+```
+
+In this example, callers still use the direct constructor while making each diagnostic input explicit.
+
+### Error Case
+
+e.g.:
+- This constructor itself does not have a normal failure mode; it only packages the provided values.
+
+- If callers want a snapshot directly from one live logger instance, `AsyncLogger::state()` is the simpler API.
+
+### 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.

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

@@ -0,0 +1,80 @@
+---
+name: async-runtime-state-new
+group: api
+category: async
+update-time: 20260613
+description: Construct an AsyncRuntimeState snapshot from explicit runtime mode and worker-support values.
+key-word:
+    - async
+    - runtime
+    - state
+    - public
+---
+
+## Async-runtime-state-new
+
+Construct an `AsyncRuntimeState` snapshot from explicit runtime mode and worker-support values. This is the low-level constructor behind the public async runtime state shape used in diagnostics.
+
+### Interface
+
+```moonbit
+pub fn AsyncRuntimeState::new(
+  mode : AsyncRuntimeMode,
+  background_worker : Bool,
+) -> AsyncRuntimeState {
+```
+
+#### input
+
+- `mode : AsyncRuntimeMode` - Backend-specific async runtime mode such as `NativeWorker` or `Compatibility`.
+- `background_worker : Bool` - Whether native-style background-worker support is available.
+
+#### output
+
+- `AsyncRuntimeState` - Runtime state snapshot containing the supplied mode and worker-support flag.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This constructor simply packages `mode` and `background_worker` into one public snapshot value.
+- It does not query the current backend automatically.
+- `async_runtime_state()` is the higher-level API that reads these values from the live runtime environment.
+- The constructed value matches the same public shape used by async runtime serializers.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Hand-built Runtime Snapshot
+
+When tests or adapters should construct a runtime state explicitly:
+```moonbit
+let runtime = AsyncRuntimeState::new(
+  AsyncRuntimeMode::Compatibility,
+  false,
+)
+```
+
+In this example, the runtime snapshot is built directly without probing the active backend.
+
+#### When Need Structured Runtime Diagnostics Input
+
+When code should prepare a runtime state value before serialization:
+```moonbit
+let runtime = AsyncRuntimeState::new(async_runtime_mode(), async_runtime_supports_background_worker())
+```
+In this example, callers still use the direct constructor while keeping the data source explicit.
+
+### Error Case
+
+e.g.:
+- This constructor itself does not have a normal failure mode; it only packages the provided values.
+
+- If callers want the current backend snapshot directly, `async_runtime_state()` is the simpler API.
+
+### Notes
+
+1. Use this helper when code should construct an `AsyncRuntimeState` value explicitly.
+
+2. Pair it with `AsyncLoggerState::new(...)` when assembling a full async logger snapshot by hand.

docs/api/index.md

@@ -264,6 +264,7 @@ BitLogger API navigation.
 ## Async lifecycle and state
 
 - [async-logger-state-type.md](./async-logger-state-type.md)
+- [async-logger-state-new.md](./async-logger-state-new.md)
 - [async-logger-pending-count.md](./async-logger-pending-count.md)
 - [async-logger-dropped-count.md](./async-logger-dropped-count.md)
 - [async-logger-is-closed.md](./async-logger-is-closed.md)
@@ -283,6 +284,7 @@ BitLogger API navigation.
 - [async-overflow-policy.md](./async-overflow-policy.md)
 - [async-flush-policy.md](./async-flush-policy.md)
 - [async-runtime-state-type.md](./async-runtime-state-type.md)
+- [async-runtime-state-new.md](./async-runtime-state-new.md)
 - [async-runtime-mode.md](./async-runtime-mode.md)
 - [async-runtime-mode-label.md](./async-runtime-mode-label.md)
 - [async-runtime-supports-background-worker.md](./async-runtime-supports-background-worker.md)