📝 clarify async runtime snapshots

docs/api/async-runtime-mode.md

@@ -2,8 +2,8 @@
 name: async-runtime-mode
 group: api
 category: async
-update-time: 20260512
-description: Read the current async runtime mode and distinguish native worker behavior from compatibility behavior.
+update-time: 20260614
+description: Read the current async runtime mode and distinguish native-worker behavior from compatibility behavior using the same mode contract exposed through async runtime snapshots.
 key-word:
     - async
     - runtime
@@ -37,6 +37,8 @@ Detailed rules explaining key parameters and behaviors
 - `NativeWorker` is the expected mode on native-style backends, while `Compatibility` is the expected mode on targets without native background-worker semantics.
 - `async_runtime_mode_label(...)` converts the enum into a stable string value.
 - `async_runtime_supports_background_worker()` is a narrower boolean probe built on the same idea.
+- `async_runtime_state()` packages this mode together with the current background-worker capability into one `AsyncRuntimeState` snapshot.
+- In the current backend implementations, `NativeWorker` pairs with `background_worker=true` and `Compatibility` pairs with `background_worker=false`.
 - This API is intentionally small and useful for lightweight branching.
 - The mode result describes runtime behavior only; it should not be read as proof that every backend has been equally re-verified in the current release cycle.
 
@@ -78,6 +80,8 @@ e.g.:
 
 2. Use `async_runtime_state()` when you also want worker support packaged into one object.
 
-3. This mode distinction is about runtime behavior, not whether `src-async` itself is expected to compile for the target.
+3. Use `async_runtime_mode_label(...)` when the result should leave enum space and become stable text such as `native_worker` or `compatibility`.
 
-4. See [target-verification.md](./target-verification.md) for the current verification status of individual targets.
+4. This mode distinction is about runtime behavior, not whether `src-async` itself is expected to compile for the target.
+
+5. See [target-verification.md](./target-verification.md) for the current verification status of individual targets.

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

@@ -2,8 +2,8 @@
 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.
+update-time: 20260614
+description: Construct an AsyncRuntimeState snapshot from explicit runtime mode and worker-support values without probing or validating the live backend.
 key-word:
     - async
     - runtime
@@ -40,6 +40,7 @@ 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.
+- It also does not validate whether the supplied pair matches the current backend contract.
 - The constructed value matches the same public shape used by async runtime serializers.
 
 ### How to Use
@@ -73,8 +74,12 @@ e.g.:
 
 - If callers want the current backend snapshot directly, `async_runtime_state()` is the simpler API.
 
+- If callers manually pair `NativeWorker` with `false` or `Compatibility` with `true`, the constructor still accepts that snapshot because it does not enforce backend consistency.
+
 ### 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.
+
+3. Prefer `async_runtime_state()` when the goal is to report the actual current backend pair rather than an arbitrary constructed snapshot.

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

@@ -2,8 +2,8 @@
 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.
+update-time: 20260614
+description: Public async runtime state alias used for backend capability snapshots and diagnostics, pairing runtime mode with background-worker support.
 key-word:
     - async
     - runtime
@@ -32,6 +32,7 @@ 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()` currently builds that snapshot from `async_runtime_mode()` and `async_runtime_supports_background_worker()`.
 - `async_runtime_state_to_json(...)` and `stringify_async_runtime_state(...)` serialize the same snapshot shape for diagnostics.
 
 ### How to Use
@@ -66,8 +67,12 @@ e.g.:
 
 - 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.
 
+- Because this is just a data shape, manual construction can represent combinations that do not come from the current backend probe.
+
 ### 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.
+
+3. Use `async_runtime_mode_label(...)` when the `mode` field should be rendered as stable text such as `native_worker` or `compatibility`.

docs/api/async-runtime-state.md

@@ -2,8 +2,8 @@
 name: async-runtime-state
 group: api
 category: async
-update-time: 20260512
-description: Read the current backend-specific async runtime mode and worker capability.
+update-time: 20260614
+description: Read the current backend-specific async runtime snapshot as the paired result of runtime mode and background-worker capability.
 key-word:
     - async
     - runtime
@@ -35,6 +35,8 @@ Detailed rules explaining key parameters and behaviors
 
 - `mode` is derived from the active backend implementation.
 - `background_worker` tells callers whether native worker semantics are available.
+- This helper is equivalent to `AsyncRuntimeState::new(async_runtime_mode(), async_runtime_supports_background_worker())`.
+- In the current backend implementations, the resulting pair is `NativeWorker + true` or `Compatibility + false`.
 - `async_runtime_state_to_json(...)` and `stringify_async_runtime_state(...)` serialize this state.
 - This API is environment-scoped and does not depend on a particular `AsyncLogger` instance.
 
@@ -75,3 +77,5 @@ e.g.:
 1. Use this API for environment-level diagnostics.
 
 2. Use `AsyncLogger::state()` for logger-instance diagnostics.
+
+3. Use `AsyncRuntimeState::new(...)` only when code or tests need to construct a manual snapshot instead of probing the current backend.