From 11b49208b245546b19bc35ab51d364a0eb176d24 Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sun, 14 Jun 2026 11:44:54 +0800
Subject: [PATCH] :memo: clarify async patch derivation

---
 docs/api/async-logger-with-patch.md | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/docs/api/async-logger-with-patch.md b/docs/api/async-logger-with-patch.md
index c084226..1548dbb 100644
--- a/docs/api/async-logger-with-patch.md
+++ b/docs/api/async-logger-with-patch.md
@@ -31,7 +31,7 @@ pub fn[S] AsyncLogger::with_patch(
 
 #### output
 
-- `AsyncLogger[S]` - A new async logger that rewrites each record before filtering and queue insertion.
+- `AsyncLogger[S]` - A new async logger value that rewrites each record before filtering and queue insertion.
 
 ### Explanation
 
@@ -39,7 +39,8 @@ Detailed rules explaining key parameters and behaviors
 
 - Patch logic runs after record creation and field merging but before filtering and enqueue.
 - Existing patch logic is preserved and composed so the new patch wraps the current one.
-- The original async logger is not mutated.
+- The returned logger is derived from `self`; the original async logger value is not mutated.
+- Only the stored patch pipeline changes. Target, minimum level, queue configuration, and lifecycle/failure state stay on the same `AsyncLogger[S]` surface.
 - Patching can normalize, redact, or enrich records before they consume queue capacity.
 - In the current direct async coverage, patched target/message/field changes are visible to later filter logic, and the original async logger still emits unpatched records when used separately.
 
@@ -59,6 +60,8 @@ let logger = async_logger(console_sink())
 
 In this example, the added fields are part of the record before filtering and queue insertion.
 
+And the returned async logger still keeps the same queue-facing API surface as the source logger.
+
 #### When Need Redaction Before Queueing
 
 When sensitive fields should be removed early:
@@ -82,4 +85,6 @@ e.g.:
 
 2. Redaction before enqueue helps keep sensitive data out of the queued pipeline.
 
-3. Derive a patched logger when one path needs rewritten records and another should keep the original async record shape.
+3. State helpers such as `pending_count()`, `dropped_count()`, `is_closed()`, and `has_failed()` remain available on the returned logger because the visible async logger surface is preserved.
+
+4. Derive a patched logger when one path needs rewritten records and another should keep the original async record shape.