📝 Document async logger adapter package

README.md

@@ -181,3 +181,11 @@ if native_files_supported() {
 - 已支持字段：`min_level`、`target`、`timestamp`、`sink.kind`、`sink.path`、`sink.append`、`sink.auto_flush`、`sink.text_formatter`、`queue`
 - 当前可由配置直接组装的 sink 类型：`console`、`json_console`、`text_console`、`file`
 - `queue` 会作为显式包装层附着在最终 sink 外侧；这仍然是同步 drain 模型，不是 async runtime
+
+## 🧵 异步层
+
+- 当前已新增独立 package：`bitlogger_async/`
+- 异步层基于 `moonbitlang/async`，提供 `AsyncLogger`、`async_logger(...)`、后台 `run()` worker 与有界 async queue
+- 当前 async API 已支持 `with_context_fields(...)`、`with_filter(...)`、`with_patch(...)`、`with_target(...)`、`child(...)`
+- 推荐启动方式见 [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1)
+- 这层目前仅面向 `native/llvm` backend；它是独立 adapter，不会污染现有同步 core

docs/README-en.md

@@ -170,3 +170,11 @@ if native_files_supported() {
 - Supported keys include `min_level`, `target`, `timestamp`, `sink.kind`, `sink.path`, `sink.append`, `sink.auto_flush`, `sink.text_formatter`, and `queue`.
 - Config-driven sink assembly currently supports `console`, `json_console`, `text_console`, and `file`.
 - `queue` remains a synchronous bounded wrapper around the final sink, not an async runtime.
+
+## Async Layer
+
+- A separate `bitlogger_async/` package is now included.
+- It uses `moonbitlang/async` and provides `AsyncLogger`, `async_logger(...)`, a background `run()` worker, and bounded async queue delivery.
+- The current async API already supports `with_context_fields(...)`, `with_filter(...)`, `with_patch(...)`, `with_target(...)`, and `child(...)`.
+- The recommended startup pattern is shown in [examples/async_basic/main.mbt](/E:/repo/MooLiteyukiBot/examples/async_basic/main.mbt:1).
+- This layer currently targets `native/llvm` only and remains isolated from the synchronous logger core.

docs/changes/0.3.0.md

@@ -13,6 +13,11 @@ version 0.3.0
 - feat: add `logger_config_to_json(...)` and `stringify_logger_config(...)` for config serialization
 - feat: add `RuntimeSink`, `ConfiguredLogger`, `build_logger(...)`, and `parse_and_build_logger(...)` for config-driven logger assembly
 - feat: add `ConfiguredLogger::drain(...)`, `ConfiguredLogger::pending_count()`, and `ConfiguredLogger::dropped_count()` queue observability helpers
+- feat: add `bitlogger_async/` as a separate native-target async adapter package
+- feat: add `AsyncLogger`, `async_logger(...)`, `run()`, `wait_idle()`, `close()`, `pending_count()`, and `dropped_count()` on top of `moonbitlang/async`
+- feat: add async logger composition helpers `with_context_fields(...)`, `with_filter(...)`, `with_patch(...)`, `with_target(...)`, `child(...)`, and `with_timestamp(...)`
+- feat: expose `Record::new(...)` for adapter and integration layers
+- fix: repair native file backend FFI declarations so native target checks succeed again
 - feat: support config keys `min_level`, `target`, `timestamp`, `sink.kind`, `sink.path`, `sink.append`, `sink.auto_flush`, `sink.text_formatter`, and `queue`
 - feat: support config-driven sink assembly for `console`, `json_console`, `text_console`, and `file`
 - feat: use `maria/json_parser` as the first external dependency for practical config loading
@@ -25,15 +30,19 @@ version 0.3.0
 - test: cover config-built queued text logger flushing and pending count behavior
 - test: cover partial drain behavior for config-built queued logger
 - test: cover dropped-count reporting for bounded config-built queue
+- build: verify `bitlogger_async --target native` and `examples/async_basic --target native` compile successfully
 
 ### Example
 
 - docs: update `examples/basic` with JSON config loading example
 - docs: update `examples/basic` to use `parse_and_build_logger(...)` with explicit error handling in `main`
+- docs: add `examples/async_basic` to show async worker startup and queue-backed logging flow
 - docs: update root README, English README, and Mooncake README with config usage notes
+- docs: update root README and English README with async adapter notes and current scope
 - chore: ignore local `.mooncakes/` cache directory in git
 
 ### Notes
 
 - current config scope is still intentionally constrained to stable built-in sink shapes
 - queue wrapping remains synchronous drain-based delivery, not async runtime scheduling
+- async logging remains an isolated adapter layer and currently targets `native/llvm` only