📝 document library facade conversion apis

docs/api/async-logger-to-library-async-logger.md

@@ -0,0 +1,65 @@
+---
+name: async-logger-to-library-async-logger
+group: api
+category: facade
+update-time: 20260613
+description: Convert a full async logger into the narrower library-facing async facade.
+key-word:
+    - async
+    - library
+    - facade
+    - public
+---
+
+## Async-logger-to-library-async-logger
+
+Convert `AsyncLogger[S]` into `LibraryAsyncLogger[S]`. This keeps the same async queue and sink behavior while projecting the value onto the smaller library-facing async surface.
+
+### Interface
+
+```moonbit
+pub fn[S] AsyncLogger::to_library_async_logger(self : AsyncLogger[S]) -> LibraryAsyncLogger[S] {}
+```
+
+#### input
+
+- `self : AsyncLogger[S]` - Full async logger to project into the library facade.
+
+#### output
+
+- `LibraryAsyncLogger[S]` - Narrower library-facing wrapper over the same async logger state.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This conversion does not rebuild the queue, sink, or runtime state.
+- Target, min level, async config, and flush behavior are preserved.
+- The returned facade keeps library-facing async operations including `log(...)`, `run()`, and `shutdown(...)`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Expose A Narrower Async Type
+
+When internal setup uses the full async logger API but public library code should return a smaller facade:
+```moonbit
+let logger = async_logger(console_sink(), target="lib.async")
+let public_logger = logger.to_library_async_logger()
+```
+
+In this example, `public_logger` keeps the same async behavior but exposes the library-facing facade.
+
+### Error Case
+
+e.g.:
+- If callers later need APIs outside the library facade, they must unwrap with `to_async_logger()`.
+
+- The conversion does not clear pending items or reset runtime state.
+
+### Notes
+
+1. Use this when package boundaries should avoid exposing the full async logger type.
+
+2. This is a projection API, not a reconfiguration step.

docs/api/index.md

@@ -205,11 +205,15 @@ BitLogger API navigation.
 
 ## Application and library facades
 
+- [logger-to-library-logger.md](./logger-to-library-logger.md)
+- [library-logger-to-logger.md](./library-logger-to-logger.md)
 - [build-application-logger.md](./build-application-logger.md)
 - [parse-and-build-application-logger.md](./parse-and-build-application-logger.md)
 - [build-library-logger.md](./build-library-logger.md)
 - [parse-and-build-library-logger.md](./parse-and-build-library-logger.md)
 - [default-library-logger.md](./default-library-logger.md)
+- [async-logger-to-library-async-logger.md](./async-logger-to-library-async-logger.md)
+- [library-async-logger-to-async-logger.md](./library-async-logger-to-async-logger.md)
 - [build-application-async-logger.md](./build-application-async-logger.md)
 - [build-application-text-async-logger.md](./build-application-text-async-logger.md)
 - [parse-and-build-application-async-logger.md](./parse-and-build-application-async-logger.md)

docs/api/library-async-logger-to-async-logger.md

@@ -0,0 +1,65 @@
+---
+name: library-async-logger-to-async-logger
+group: api
+category: facade
+update-time: 20260613
+description: Recover the underlying full async logger from the library-facing async facade.
+key-word:
+    - async
+    - library
+    - facade
+    - public
+---
+
+## Library-async-logger-to-async-logger
+
+Recover `AsyncLogger[S]` from `LibraryAsyncLogger[S]`. This unwraps the library-facing async facade when code needs methods that are only available on the full async logger type.
+
+### Interface
+
+```moonbit
+pub fn[S] LibraryAsyncLogger::to_async_logger(self : LibraryAsyncLogger[S]) -> AsyncLogger[S] {}
+```
+
+#### input
+
+- `self : LibraryAsyncLogger[S]` - Library-facing async logger facade.
+
+#### output
+
+- `AsyncLogger[S]` - The underlying full async logger.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This conversion unwraps the existing async logger instead of rebuilding it.
+- Queue state, sink wiring, target, and flush policy remain the same.
+- Use this when code needs wider async logger APIs outside the library facade.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Full Async Logger-only APIs
+
+When a library-facing async logger must be widened for additional async logger composition:
+```moonbit
+let library_logger = LibraryAsyncLogger::new(console_sink(), target="lib.async")
+let full_logger = library_logger.to_async_logger().with_timestamp()
+```
+
+In this example, the facade is unwrapped so the caller can access the full async logger API again.
+
+### Error Case
+
+e.g.:
+- If callers only need library-facing async write or lifecycle APIs, unwrapping is unnecessary.
+
+- Unwrapping does not start or stop the background runtime by itself.
+
+### Notes
+
+1. Use this only when the narrower async facade is no longer sufficient.
+
+2. This is the inverse projection of `AsyncLogger::to_library_async_logger()`.

docs/api/library-logger-to-logger.md

@@ -0,0 +1,65 @@
+---
+name: library-logger-to-logger
+group: api
+category: facade
+update-time: 20260613
+description: Recover the underlying full sync logger from the library-facing sync facade.
+key-word:
+    - logger
+    - library
+    - facade
+    - public
+---
+
+## Library-logger-to-logger
+
+Recover `Logger[S]` from `LibraryLogger[S]`. This unwraps the library-facing sync facade when code needs methods that are only available on the full logger type.
+
+### Interface
+
+```moonbit
+pub fn[S] LibraryLogger::to_logger(self : LibraryLogger[S]) -> Logger[S] {}
+```
+
+#### input
+
+- `self : LibraryLogger[S]` - Library-facing sync logger facade.
+
+#### output
+
+- `Logger[S]` - The underlying full sync logger.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This conversion unwraps the existing logger instead of rebuilding it.
+- Sink wiring, target, min level, and attached wrappers remain the same.
+- Use this when code needs full-surface APIs such as `with_timestamp(...)`, `with_filter(...)`, or `with_patch(...)`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Full Logger-only Composition APIs
+
+When a library-facing logger must be widened temporarily for additional composition:
+```moonbit
+let library_logger = LibraryLogger::new(console_sink(), target="lib")
+let full_logger = library_logger.to_logger().with_timestamp()
+```
+
+In this example, the facade is unwrapped so the caller can access full logger composition APIs again.
+
+### Error Case
+
+e.g.:
+- If callers only need library-oriented write APIs, unwrapping is unnecessary.
+
+- Unwrapping does not change the current target or sink behavior by itself.
+
+### Notes
+
+1. Use this only when the narrower facade is no longer sufficient.
+
+2. This is the inverse projection of `Logger::to_library_logger()`.

docs/api/logger-to-library-logger.md

@@ -0,0 +1,65 @@
+---
+name: logger-to-library-logger
+group: api
+category: facade
+update-time: 20260613
+description: Convert a full sync logger into the narrower library-facing sync facade.
+key-word:
+    - logger
+    - library
+    - facade
+    - public
+---
+
+## Logger-to-library-logger
+
+Convert `Logger[S]` into `LibraryLogger[S]`. This keeps the same sink and logging behavior while projecting the value onto the smaller library-facing sync surface.
+
+### Interface
+
+```moonbit
+pub fn[S] Logger::to_library_logger(self : Logger[S]) -> LibraryLogger[S] {}
+```
+
+#### input
+
+- `self : Logger[S]` - Full sync logger to project into the library facade.
+
+#### output
+
+- `LibraryLogger[S]` - Narrower library-facing wrapper over the same logger state.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This conversion does not rebuild the sink or change the logger configuration.
+- Target, min level, timestamp behavior, and sink wiring are preserved.
+- The returned facade keeps library-oriented write APIs such as `info(...)`, `warn(...)`, and `error(...)`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Return A Narrower Library Type
+
+When internal setup uses the full logger API but the exposed result should stay smaller:
+```moonbit
+let logger = Logger::new(console_sink(), target="lib")
+let public_logger = logger.to_library_logger()
+```
+
+In this example, `public_logger` keeps the same logging behavior but exposes the library facade.
+
+### Error Case
+
+e.g.:
+- If callers later need APIs outside the library facade, they must unwrap with `to_logger()`.
+
+- The conversion does not remove existing target or field bindings from the original logger.
+
+### Notes
+
+1. Use this when library boundaries should avoid exposing the full sync logger surface.
+
+2. This is a projection API, not a copy or rebuild step.