📝 clarify api target verification status

docs/api/async-logger.md

@@ -45,6 +45,8 @@ Detailed rules explaining key parameters and behaviors
 
 - `async_logger(...)` only builds the logger. Actual background draining is started by `run()`.
 - In non-native targets, the implementation uses compatibility behavior while keeping the same public surface.
+- `src-async` is designed for `native / llvm / js / wasm / wasm-gc`, but current release-facing local verification is stronger for `native / js / wasm / wasm-gc` than for `llvm`.
+- `llvm` should currently be read as experimental and locally unverified in this environment rather than as a stable checked target.
 - `flush` is used only when batch or shutdown policy wants explicit flushing.
 - Queue overflow behavior depends on `AsyncOverflowPolicy`.
 
@@ -98,3 +100,6 @@ e.g.:
 
 2. Use `state()`, `pending_count()`, and `dropped_count()` for runtime diagnostics.
 
+3. Example entrypoint limitations such as `async fn main` support are separate from the library-level portability of this API.
+
+4. See [target-verification.md](./target-verification.md) for the current local verification matrix.

docs/api/async-runtime-mode.md

@@ -34,9 +34,11 @@ pub fn async_runtime_mode() -> AsyncRuntimeMode {}
 Detailed rules explaining key parameters and behaviors
 
 - The return value is determined by the active backend implementation.
+- `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.
 - 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.
 
 ### How to Use
 
@@ -76,3 +78,6 @@ 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.
+
+4. See [target-verification.md](./target-verification.md) for the current verification status of individual targets.

docs/api/async-runtime-supports-background-worker.md

@@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors
 - `true` indicates native worker capability.
 - `false` indicates compatibility-mode behavior.
 - This helper is derived from backend-specific async runtime implementation choice.
+- The async library still targets multiple backends even when this helper returns `false`.
 - Use it when an enum branch is unnecessary and a boolean capability check is enough.
 
 ### How to Use
@@ -75,3 +76,6 @@ e.g.:
 
 2. Prefer `async_runtime_state()` when you want the same information in a richer object.
 
+3. A `false` result should be read as "compatibility-mode runtime behavior" rather than "async library unsupported on this target".
+
+4. This helper does not by itself imply that every non-worker backend has been equally re-verified for the current release; see [target-verification.md](./target-verification.md).

docs/api/build-async-logger.md

@@ -37,6 +37,10 @@ Detailed rules explaining key parameters and behaviors
 - The resulting async logger inherits `min_level`, `target`, and timestamp behavior from the built synchronous logger.
 - File, queue, and formatter choices all come from config rather than direct code-side sink wiring.
 - The returned sink type is `RuntimeSink`, which keeps configured control helpers available where relevant.
+- The `src-async` library is designed to compile on `native / llvm / js / wasm / wasm-gc`, but runtime mode differs by backend.
+- Current local release-facing verification is explicit for `native / js / wasm / wasm-gc`.
+- `llvm` remains experimental and did not complete local verification in this environment.
+- On non-native targets, the async library still compiles and exposes the same public surface through compatibility-mode behavior rather than native background-worker semantics.
 
 ### How to Use
 
@@ -79,3 +83,6 @@ e.g.:
 
 2. Use `async_logger(...)` directly when you want explicit code-defined sink wiring.
 
+3. Library portability is broader than example portability: a runnable `async fn main` example may still be target-limited even when the async library itself compiles for that backend.
+
+4. See [target-verification.md](./target-verification.md) for the current verification boundary.

docs/api/build-async-text-logger.md

@@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors
 - This builder converts `config.logger.sink.text_formatter` into a runtime `TextFormatter` and wires it into `text_console_sink(...)`.
 - The returned logger inherits `min_level`, `target`, and timestamp behavior from `config.logger`.
 - This helper is best suited to text-console output paths where callers want the concrete formatted sink type instead of `RuntimeSink`.
+- This async text path follows the same target story as the broader async library: `native / js / wasm / wasm-gc` have stronger local verification, while `llvm` remains experimental and locally unverified in this environment.
 
 ### How to Use
 
@@ -67,3 +68,5 @@ e.g.:
 1. This API is narrower than `build_async_logger(...)` because it preserves a concrete text sink type.
 
 2. It is the base builder used by the application and library async text facades.
+
+3. See [target-verification.md](./target-verification.md) for the current local verification matrix.

docs/api/file-sink.md

@@ -43,7 +43,9 @@ pub fn file_sink(
 
 Detailed rules explaining key parameters and behaviors
 
-- This sink is only available on `native/llvm`; use `native_files_supported()` for capability detection.
+- This sink is designed for host-file capable backends, with current local verification centered on `native`.
+- `llvm` should be treated as experimental in the current release context and was not successfully re-verified in this environment.
+- The `src` library is still designed for multi-target compilation, but file sink availability remains backend-sensitive inside that broader portable surface.
 - `append` is persistent policy state and also affects later reopen behavior.
 - `auto_flush` trades durability for more flush work per record.
 - Rotation is currently size-based and rename-retention-oriented, not time-based.
@@ -91,3 +93,6 @@ e.g.:
 
 2. Prefer `state()`, `policy()`, and failure counters when integrating diagnostics.
 
+3. Non-native targets can still compile code referencing this API, but callers should treat actual file availability and successful writes as target-sensitive runtime behavior.
+
+4. See [target-verification.md](./target-verification.md) for the current verification boundary between design intent and locally re-checked targets.

docs/api/index.md

@@ -15,6 +15,10 @@ key-word:
 
 BitLogger API navigation.
 
+## Target and verification
+
+- [target-verification.md](./target-verification.md)
+
 ## Core logger
 
 - [logger-new.md](./logger-new.md)

docs/api/target-verification.md

@@ -0,0 +1,63 @@
+---
+name: target-verification
+group: api
+category: verification
+update-time: 20260521
+description: Current release-facing local verification boundary for BitLogger multi-target support claims.
+key-word:
+    - target
+    - verification
+    - matrix
+    - public
+---
+
+## Target-verification
+
+This note records the current release-facing local verification boundary for BitLogger's multi-target claims. It is intentionally small: the goal is to separate design intent from what was actually re-checked in the current environment.
+
+### Verification Matrix
+
+| Area | native | js | wasm | wasm-gc | llvm |
+| --- | --- | --- | --- | --- | --- |
+| `src` compile check | verified | verified | verified | verified | not locally verified |
+| `src-async` compile check | verified | verified | verified | verified | not locally verified |
+| `moon test` | verified in current local environment | not separately re-run | not separately re-run | not separately re-run | not run |
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `verified` here means a local verification command was re-run successfully in the current environment.
+- `not locally verified` means the release should not imply fresh local confirmation even if the package is still designed for that target.
+- `llvm` is currently experimental in practice for this release context and did not complete local verification in this environment.
+- `wasm` has been re-checked and should be distinguished from the earlier state where only `wasm-gc` and `js` had been explicitly re-confirmed.
+- Example-level limitations, such as `async fn main` entry support, are separate from the library-level compile matrix above.
+
+### Commands Used
+
+The current local verification evidence for this note is based on commands such as:
+
+```text
+moon test
+moon check --target native
+moon check --target js
+moon check --target wasm
+moon check --target wasm-gc
+moon check src-async --target native
+moon check src-async --target js
+moon check src-async --target wasm
+moon check src-async --target wasm-gc
+```
+
+### Error Case
+
+e.g.:
+- If a target is described as part of the design intent but not locally re-verified here, readers should not treat it as freshly confirmed release evidence.
+
+- If `llvm` toolchain support changes later, this page should be updated together with the relevant verification commands rather than silently relying on old wording.
+
+### Notes
+
+1. This page is a release-facing verification note, not a portability promise by itself.
+
+2. API pages that mention target-sensitive behavior should defer to this page when readers need the current verification boundary.