📝 补充runtime文档

docs/api/runtime-sink-file-set-rotation.md

@@ -2,8 +2,8 @@
 name: runtime-sink-file-set-rotation
 group: api
 category: runtime
-update-time: 20260613
-description: Update the rotation configuration used by a file-backed RuntimeSink.
+update-time: 20260707
+description: Update the rotation policy used by a file-backed RuntimeSink.
 key-word:
     - runtime
     - sink
@@ -13,7 +13,7 @@ key-word:
 
 ## Runtime-sink-file-set-rotation
 
-Update the rotation configuration used by a file-backed `RuntimeSink`. This helper changes direct runtime file rotation behavior without rebuilding or rewrapping the sink.
+Update the rotation policy used by a file-backed `RuntimeSink`.
 
 ### Interface
 
@@ -23,8 +23,8 @@ pub fn RuntimeSink::file_set_rotation(self : RuntimeSink, rotation : FileRotatio
 
 #### input
 
-- `self : RuntimeSink` - Runtime sink whose rotation policy should change.
-- `rotation : FileRotation?` - New rotation config, or `None` to disable rotation.
+- `self : RuntimeSink` - Runtime sink whose file rotation policy should change.
+- `rotation : FileRotation?` - New runtime rotation policy.
 
 #### output
 
@@ -35,41 +35,20 @@ pub fn RuntimeSink::file_set_rotation(self : RuntimeSink, rotation : FileRotatio
 Detailed rules explaining key parameters and behaviors
 
 - Plain `File` runtime variants update the wrapped `FileSink` rotation policy and return `true`.
-- `QueuedFile` runtime variants forward the update to the wrapped inner `FileSink` and return `true`.
-- Passing `None` disables rotation.
+- `QueuedFile` runtime variants forward the update to the wrapped inner `FileSink` only when no queued records are pending.
 - Non-file runtime variants return `false`.
-
-### How to Use
-
-Here are some specific examples provided.
-
-#### When Need Direct Runtime Rotation Tuning
-
-When a file-backed runtime sink should enable or change rotation dynamically:
-```moonbit
-ignore(sink.file_set_rotation(Some(file_rotation(1024, max_backups=3))))
-```
-
-In this example, runtime rotation behavior is updated without rebuilding the sink.
-
-#### When Need To Disable Rotation Through The Setter
-
-When the file sink should stop rotating through one general update path:
-```moonbit
-let ok = sink.file_set_rotation(None)
-```
-
-In this example, the direct runtime file sink has its rotation policy cleared explicitly.
+- This helper changes policy only; it does not itself rotate or flush pending data.
+- If a queued file sink still has pending records, the update is rejected and returns `false` so already queued records are not later written under a different rotation policy than the one they were queued under.
 
 ### Error Case
 
 e.g.:
 - If the runtime sink is not file-backed, the method returns `false`.
 
-- If callers only want to remove rotation, `file_clear_rotation()` is the more direct API.
+- If a queued file sink still has pending records, callers should flush or close it first before changing rotation policy.
 
 ### Notes
 
-1. Use this helper when setting a full direct runtime rotation config.
+1. Use this helper when runtime rotation policy should change without rebuilding the sink.
 
-2. It is useful for operational tuning without rebuilding the sink.
+2. On queued file sinks, clear pending records first so policy mutation does not retroactively affect already queued writes.