📝 补充runtime文档

docs/api/runtime-sink-file-reset-policy.md

@@ -2,8 +2,8 @@
 name: runtime-sink-file-reset-policy
 group: api
 category: runtime
-update-time: 20260613
-description: Reset the runtime file policy of a file-backed RuntimeSink back to its original defaults.
+update-time: 20260707
+description: Reset the runtime file policy of a RuntimeSink back to its captured defaults.
 key-word:
     - runtime
     - sink
@@ -13,7 +13,7 @@ key-word:
 
 ## Runtime-sink-file-reset-policy
 
-Reset the runtime file policy of a `RuntimeSink` back to its original defaults. This helper restores append, auto-flush, and rotation policy together on direct sink values.
+Reset the runtime file policy of a `RuntimeSink` back to its captured defaults.
 
 ### Interface
 
@@ -21,56 +21,17 @@ Reset the runtime file policy of a `RuntimeSink` back to its original defaults.
 pub fn RuntimeSink::file_reset_policy(self : RuntimeSink) -> Bool {
 ```
 
-#### input
-
-- `self : RuntimeSink` - Runtime sink whose file policy should be restored.
-
-#### output
-
-- `Bool` - Whether the reset was applied.
-
 ### Explanation
 
 Detailed rules explaining key parameters and behaviors
 
-- Plain `File` runtime variants restore their stored default file policy and return `true`.
-- `QueuedFile` runtime variants forward the reset behavior to the wrapped inner `FileSink` and return `true`.
+- Plain `File` runtime variants restore the wrapped `FileSink` default policy and return `true`.
+- `QueuedFile` runtime variants restore the wrapped inner `FileSink` default policy only when no queued records are pending.
 - Non-file runtime variants return `false`.
-- This helper is the inverse of runtime policy drift, not a generic reopen or flush action.
-
-### How to Use
-
-Here are some specific examples provided.
-
-#### When Need To Undo Runtime Policy Changes
-
-When file policy should return to the original defaults captured by the runtime sink:
-```moonbit
-ignore(sink.file_reset_policy())
-```
-
-In this example, append, auto-flush, and rotation settings are restored together.
-
-#### When Use Drift-aware Recovery
-
-When reset should only happen after runtime changes:
-```moonbit
-if !sink.file_policy_matches_default() {
-  ignore(sink.file_reset_policy())
-}
-```
-
-In this example, reset is only applied when runtime policy has diverged.
-
-### Error Case
-
-e.g.:
-- If the runtime sink is not file-backed, the method returns `false`.
-
-- If callers need to restore only one setting, a narrower setter may be more appropriate than a full policy reset.
+- If a queued file sink still has pending records, the reset is rejected and returns `false` so already queued records are not later written under a different policy than the one they were queued under.
 
 ### Notes
 
-1. Use this helper when the original bundled file policy should be restored intact.
+1. Use this helper when runtime file policy should return to its captured defaults.
 
-2. It pairs naturally with `file_policy_matches_default()` and `file_default_policy()`.
+2. On queued file sinks, clear pending records first so policy mutation does not retroactively affect already queued writes.