📝 document async state model aliases

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

@@ -0,0 +1,73 @@
+---
+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.
+key-word:
+    - async
+    - logger
+    - state
+    - public
+---
+
+## Async-logger-state-type
+
+`AsyncLoggerState` is the public snapshot type used to describe an async logger's runtime status. It is a direct alias to the async logger state model returned by `AsyncLogger::state()` and used by async diagnostics serializers.
+
+### Interface
+
+```moonbit
+pub type AsyncLoggerState = @utils.AsyncLoggerState
+```
+
+#### output
+
+- `AsyncLoggerState` - Public async logger snapshot containing `runtime`, `pending_count`, `dropped_count`, `is_closed`, `is_running`, `has_failed`, `last_error`, and `flush_policy`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a live logger handle.
+- 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.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Snapshot For Async Diagnostics
+
+When application code should inspect async logger state before deciding how to report it:
+```moonbit
+let state : AsyncLoggerState = logger.state()
+```
+
+In this example, queue, lifecycle, and runtime information stay available as structured data.
+
+#### When Need To Branch On Failure Or Backlog
+
+When code should react to the current async logger condition:
+```moonbit
+let state = logger.state()
+if state.has_failed || state.pending_count > 0 {
+  println(stringify_async_logger_state(state, pretty=true))
+}
+```
+
+In this example, the typed snapshot supports both logic and later export.
+
+### Error Case
+
+e.g.:
+- `AsyncLoggerState` itself does not have a runtime failure mode.
+
+- `last_error` may be an empty string when no failure has occurred, which is normal and not a special error condition by itself.
+
+### 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.

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

@@ -0,0 +1,73 @@
+---
+name: async-runtime-state-type
+group: api
+category: async
+update-time: 20260613
+description: Public async runtime state alias used for backend capability snapshots and diagnostics.
+key-word:
+    - async
+    - runtime
+    - state
+    - public
+---
+
+## Async-runtime-state-type
+
+`AsyncRuntimeState` is the public snapshot type used to describe backend-level async runtime capability. It is a direct alias to the async runtime state model returned by `async_runtime_state()` and used by async diagnostics serializers.
+
+### Interface
+
+```moonbit
+pub type AsyncRuntimeState = @utils.AsyncRuntimeState
+```
+
+#### output
+
+- `AsyncRuntimeState` - Public runtime snapshot containing `mode` and `background_worker`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a live runtime controller.
+- The current fields are `mode : AsyncRuntimeMode` and `background_worker : Bool`.
+- `async_runtime_state()` returns this type directly as an environment-level snapshot.
+- `async_runtime_state_to_json(...)` and `stringify_async_runtime_state(...)` serialize the same snapshot shape for diagnostics.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Backend Capability Snapshot
+
+When startup or diagnostics code should keep the runtime state as structured data:
+```moonbit
+let runtime : AsyncRuntimeState = async_runtime_state()
+```
+
+In this example, the backend capability snapshot stays available as a typed value instead of only as printed text.
+
+#### When Need To Read Runtime Mode And Worker Support Together
+
+When code should inspect both async mode and worker availability from one object:
+```moonbit
+let runtime = async_runtime_state()
+if runtime.background_worker {
+  println(async_runtime_mode_label(runtime.mode))
+}
+```
+
+In this example, both fields are consumed from the same public snapshot type.
+
+### Error Case
+
+e.g.:
+- `AsyncRuntimeState` itself does not have a runtime failure mode.
+
+- The snapshot is point-in-time diagnostic data; it should not be treated as proof that every target was re-verified in the current release cycle.
+
+### Notes
+
+1. Use `async_runtime_state()` when you need a value of this type from the current backend.
+
+2. Use `AsyncLoggerState` when logger-instance queue and lifecycle information is also required.

docs/api/index.md

@@ -190,6 +190,7 @@ BitLogger API navigation.
 
 ## Async lifecycle and state
 
+- [async-logger-state-type.md](./async-logger-state-type.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)
@@ -208,6 +209,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-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)