📝 align sync API docs with owner packages

docs/api/file-sink-rotation-failures.md

@@ -2,7 +2,7 @@
 name: file-sink-rotation-failures
 group: api
 category: sink
-update-time: 20260613
+update-time: 20260707
 description: Read the number of rotation failures recorded by a FileSink.
 key-word:
     - file
@@ -13,7 +13,7 @@ key-word:
 
 ## File-sink-rotation-failures
 
-Read the number of rotation failures recorded by a `FileSink`. This helper is useful when direct runtime rotation behavior should be observed operationally.
+Read the number of rotation attempts whose critical file-rotation steps failed for a `FileSink`.
 
 ### Interface
 
@@ -34,6 +34,8 @@ pub fn FileSink::rotation_failures(self : FileSink) -> Int {
 Detailed rules explaining key parameters and behaviors
 
 - The sink reports its recorded rotation-failure count directly.
+- The counter increases when a rotation attempt cannot complete its critical file steps, such as removing the active file with zero backups, renaming a live file into `.1`, shifting an existing backup to a higher slot, or reopening the fresh active file afterward.
+- Missing optional backup slots do not count by themselves; only steps that fail while their source path still exists are treated as rotation failures.
 - The counter is cumulative until reset.
 - This helper is observation-only and does not mutate sink state.
 
@@ -48,7 +50,7 @@ When support output should reveal whether direct sink rotation is failing:
 let count = sink.rotation_failures()
 ```
 
-In this example, the concrete file sink exposes a focused metric for rotation-path health.
+In this example, the concrete file sink exposes whether a rotation attempt hit a critical file-step failure.
 
 #### When Validate Runtime Rotation Tuning
 
@@ -57,17 +59,19 @@ When changed rotation settings should be checked in operation:
 ignore(sink.rotation_failures())
 ```
 
-In this example, callers can observe whether runtime rotation changes introduced problems.
+In this example, callers can observe whether runtime rotation changes started producing incomplete rotations.
 
 ### Error Case
 
 e.g.:
 - If callers need both rotation config and failure metrics, they should combine this helper with `rotation_config()` or `state()`.
 
+- This counter alone does not identify which rename/remove/reopen step failed.
+
 - This counter alone does not say whether the sink is currently available.
 
 ### Notes
 
-1. Use this helper when diagnosing direct file rotation reliability.
+1. Use this helper when diagnosing incomplete direct file rotations.
 
 2. It is especially relevant when runtime rotation policy can change after startup.