📝 补充runtime文档

docs/api/runtime-sink-close.md

@@ -2,8 +2,8 @@
 name: runtime-sink-close
 group: api
 category: runtime
-update-time: 20260613
-description: Close a RuntimeSink and report whether the underlying sink performed a successful close action.
+update-time: 20260707
+description: Close a RuntimeSink and report whether the concrete close path succeeded.
 key-word:
     - runtime
     - sink
@@ -27,7 +27,7 @@ pub fn RuntimeSink::close(self : RuntimeSink) -> Bool {
 
 #### output
 
-- `Bool` - Whether the concrete runtime sink reported a successful close action.
+- `Bool` - Whether the concrete runtime sink reported a successful close path.
 
 ### Explanation
 
@@ -35,9 +35,11 @@ Detailed rules explaining key parameters and behaviors
 
 - Plain console-style runtime sinks return `true` because they do not have a meaningful close step here.
 - Plain file runtime sinks forward directly to `FileSink::close()`.
-- Queued file runtime sinks close the wrapped file sink rather than only the queue wrapper.
-- Generic `close()` on `QueuedFile` does not drain or flush queued records first; it closes the inner file sink directly.
-- Queue-wrapped console-style runtime sinks return `true` as a no-op success.
+- Queued file runtime sinks now follow the same safe teardown path as `file_close()`: they first try to drain the queue, then flush the wrapped file sink, then close it.
+- On `QueuedFile`, the returned `Bool` is `true` only when that whole teardown path succeeds without introducing new file failures.
+- Queue-wrapped console-style runtime sinks also use drain-first teardown.
+- For `QueuedConsole`, `QueuedJsonConsole`, and `QueuedTextConsole`, `close()` consumes pending queue items before reporting success.
+- Because these wrapped console-style sinks do not expose an additional close-failure channel, success for these variants means the backlog was drained to zero.
 - This method is the direct sink-level API used by `ConfiguredLogger::close(...)`.
 - For file-backed runtime sinks, later `close()` calls return `false` after the handle has already been cleared.
 
@@ -72,10 +74,14 @@ e.g.:
 
 - If callers know they are working with a direct `FileSink`, `FileSink::close()` is the narrower API.
 
+- On queued file sinks, `true` still does not mean the records are guaranteed to be durable beyond what the current backend can report; it means the queue-drain, file-flush, and file-close path completed without a newly observed file failure.
+
+- On queued non-file sinks, `true` means the queued backlog was consumed before teardown completed.
+
 ### Notes
 
 1. Use this helper when code is managing a `RuntimeSink` value directly.
 
-2. Use `file_close()` instead of generic `close()` when queued file sinks should flush pending records before file teardown.
+2. Generic `close()` is now safe for queue-backed runtime sinks and no longer skips queued records silently.
 
 3. `ConfiguredLogger::close(...)` is the higher-level wrapper for config-built loggers.