diff --git a/docs/api/file-sink-flush-failures.md b/docs/api/file-sink-flush-failures.md
new file mode 100644
index 0000000..c857f85
--- /dev/null
+++ b/docs/api/file-sink-flush-failures.md
@@ -0,0 +1,73 @@
+---
+name: file-sink-flush-failures
+group: api
+category: sink
+update-time: 20260613
+description: Read the number of flush failures recorded by a FileSink.
+key-word:
+    - file
+    - sink
+    - flush
+    - public
+---
+
+## File-sink-flush-failures
+
+Read the number of flush failures recorded by a `FileSink`. This helper is useful for diagnosing durability-path problems on the direct file sink.
+
+### Interface
+
+```moonbit
+pub fn FileSink::flush_failures(self : FileSink) -> Int {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose flush-failure counter should be inspected.
+
+#### output
+
+- `Int` - Number of recorded flush failures.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The sink reports its recorded flush-failure count directly.
+- The counter is cumulative until reset.
+- This helper is observation-only and does not mutate sink state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Durability-path Diagnostics
+
+When support output should show direct flush-path instability:
+```moonbit
+let count = sink.flush_failures()
+```
+
+In this example, the direct file sink exposes whether flush attempts have been failing.
+
+#### When Inspect Effects Of Auto-flush Policy
+
+When runtime durability tuning should be inspected operationally:
+```moonbit
+ignore(sink.flush_failures())
+```
+
+In this example, callers can correlate flush failures with direct file policy choices.
+
+### Error Case
+
+e.g.:
+- If callers need current policy and counters together, `state()` is the better API.
+
+- This counter does not itself say whether the sink is open right now.
+
+### Notes
+
+1. Use this helper when direct flush-path reliability matters.
+
+2. Pair it with `auto_flush_enabled()` and `flush()` when diagnosing durability behavior.
diff --git a/docs/api/file-sink-open-failures.md b/docs/api/file-sink-open-failures.md
new file mode 100644
index 0000000..21f77c7
--- /dev/null
+++ b/docs/api/file-sink-open-failures.md
@@ -0,0 +1,73 @@
+---
+name: file-sink-open-failures
+group: api
+category: sink
+update-time: 20260613
+description: Read the number of open failures recorded by a FileSink.
+key-word:
+    - file
+    - sink
+    - open
+    - public
+---
+
+## File-sink-open-failures
+
+Read the number of open failures recorded by a `FileSink`. This helper is useful for diagnosing direct file-availability or reopen problems.
+
+### Interface
+
+```moonbit
+pub fn FileSink::open_failures(self : FileSink) -> Int {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose open-failure counter should be inspected.
+
+#### output
+
+- `Int` - Number of recorded open failures.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The sink reports its recorded open-failure count directly.
+- The counter is cumulative until reset.
+- This helper is observation-only and does not mutate sink state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need File Availability Diagnostics
+
+When operators should see whether file open or reopen failed:
+```moonbit
+let count = sink.open_failures()
+```
+
+In this example, the direct sink exposes the open-failure metric directly.
+
+#### When Validate Recovery Logic
+
+When tests or support code should inspect whether reopen attempts failed:
+```moonbit
+ignore(sink.open_failures())
+```
+
+In this example, the counter helps confirm whether file-open problems occurred during runtime.
+
+### Error Case
+
+e.g.:
+- If callers need the full file status snapshot rather than one counter, `state()` is the better API.
+
+- This counter does not tell you which particular reopen attempt failed.
+
+### Notes
+
+1. Use this helper for focused direct file-open diagnostics.
+
+2. Pair it with `reopen(...)` and `is_available()` during recovery analysis.
diff --git a/docs/api/file-sink-reset-failure-counters.md b/docs/api/file-sink-reset-failure-counters.md
new file mode 100644
index 0000000..0595a1b
--- /dev/null
+++ b/docs/api/file-sink-reset-failure-counters.md
@@ -0,0 +1,70 @@
+---
+name: file-sink-reset-failure-counters
+group: api
+category: sink
+update-time: 20260613
+description: Reset the file failure counters recorded by a FileSink.
+key-word:
+    - file
+    - sink
+    - reset
+    - public
+---
+
+## File-sink-reset-failure-counters
+
+Reset the file failure counters recorded by a `FileSink`. This helper clears open, write, flush, and rotation failure metrics together on the direct sink.
+
+### Interface
+
+```moonbit
+pub fn FileSink::reset_failure_counters(self : FileSink) -> Unit {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose file failure counters should be cleared.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper clears open, write, flush, and rotation failure counters together.
+- It is useful after diagnostics, recovery, or controlled tests.
+- It does not reopen the sink or change file policy.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Fresh Diagnostics Baseline
+
+When previous failure history should be cleared before a new observation window:
+```moonbit
+sink.reset_failure_counters()
+```
+
+In this example, future failures can be measured from a clean baseline.
+
+#### When Validate Post-recovery Behavior
+
+When recovery logic should clear old counters before rechecking health:
+```moonbit
+sink.reset_failure_counters()
+ignore(sink.open_failures())
+```
+
+In this example, the direct sink starts a new diagnostics window after reset.
+
+### Error Case
+
+e.g.:
+- If callers need the current values before clearing them, they should read the counters or `state()` first.
+
+- This helper resets metrics only; it does not fix the underlying cause of past failures.
+
+### Notes
+
+1. Use this helper after diagnostics or recovery, not before capturing needed evidence.
+
+2. It is the reset companion for the direct file failure-counter helpers.
diff --git a/docs/api/file-sink-reset-policy.md b/docs/api/file-sink-reset-policy.md
new file mode 100644
index 0000000..c4573cb
--- /dev/null
+++ b/docs/api/file-sink-reset-policy.md
@@ -0,0 +1,71 @@
+---
+name: file-sink-reset-policy
+group: api
+category: sink
+update-time: 20260613
+description: Reset the runtime file policy of a FileSink back to its original defaults.
+key-word:
+    - file
+    - sink
+    - reset
+    - public
+---
+
+## File-sink-reset-policy
+
+Reset the runtime file policy of a `FileSink` back to its original defaults. This helper restores append, auto-flush, and rotation policy together on the direct sink.
+
+### Interface
+
+```moonbit
+pub fn FileSink::reset_policy(self : FileSink) -> Unit {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose file policy should be restored.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper restores the sink's stored default append, auto-flush, and rotation settings.
+- It is the inverse of runtime policy drift, not a generic reopen or flush action.
+- It changes policy only and does not reopen the sink automatically.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Undo Runtime Policy Changes
+
+When direct file policy should return to the original configured defaults:
+```moonbit
+sink.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.policy_matches_default() {
+  sink.reset_policy()
+}
+```
+
+In this example, reset is only applied when runtime policy has diverged.
+
+### Error Case
+
+e.g.:
+- If callers need to restore only one setting, a narrower setter may be more appropriate than a full policy reset.
+
+- This helper does not reopen the file or prove current availability.
+
+### Notes
+
+1. Use this helper when the original bundled file policy should be restored intact.
+
+2. It pairs naturally with `policy_matches_default()` and `default_policy()`.
diff --git a/docs/api/file-sink-rotation-failures.md b/docs/api/file-sink-rotation-failures.md
new file mode 100644
index 0000000..ef30ed7
--- /dev/null
+++ b/docs/api/file-sink-rotation-failures.md
@@ -0,0 +1,73 @@
+---
+name: file-sink-rotation-failures
+group: api
+category: sink
+update-time: 20260613
+description: Read the number of rotation failures recorded by a FileSink.
+key-word:
+    - file
+    - sink
+    - rotation
+    - public
+---
+
+## 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.
+
+### Interface
+
+```moonbit
+pub fn FileSink::rotation_failures(self : FileSink) -> Int {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose rotation-failure counter should be inspected.
+
+#### output
+
+- `Int` - Number of recorded rotation failures.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The sink reports its recorded rotation-failure count directly.
+- The counter is cumulative until reset.
+- This helper is observation-only and does not mutate sink state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Rotation-specific Diagnostics
+
+When support output should reveal whether direct sink rotation is failing:
+```moonbit
+let count = sink.rotation_failures()
+```
+
+In this example, the concrete file sink exposes a focused metric for rotation-path health.
+
+#### When Validate Runtime Rotation Tuning
+
+When changed rotation settings should be checked in operation:
+```moonbit
+ignore(sink.rotation_failures())
+```
+
+In this example, callers can observe whether runtime rotation changes introduced problems.
+
+### 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 say whether the sink is currently available.
+
+### Notes
+
+1. Use this helper when diagnosing direct file rotation reliability.
+
+2. It is especially relevant when runtime rotation policy can change after startup.
diff --git a/docs/api/file-sink-write-failures.md b/docs/api/file-sink-write-failures.md
new file mode 100644
index 0000000..0d7cbd7
--- /dev/null
+++ b/docs/api/file-sink-write-failures.md
@@ -0,0 +1,73 @@
+---
+name: file-sink-write-failures
+group: api
+category: sink
+update-time: 20260613
+description: Read the number of write failures recorded by a FileSink.
+key-word:
+    - file
+    - sink
+    - write
+    - public
+---
+
+## File-sink-write-failures
+
+Read the number of write failures recorded by a `FileSink`. This helper is useful for diagnosing direct runtime write-path problems.
+
+### Interface
+
+```moonbit
+pub fn FileSink::write_failures(self : FileSink) -> Int {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose write-failure counter should be inspected.
+
+#### output
+
+- `Int` - Number of recorded write failures.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The sink reports its recorded write-failure count directly.
+- The counter is cumulative until reset.
+- This helper is observation-only and does not mutate sink state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Runtime Write-path Diagnostics
+
+When support output should show whether direct writes have been failing:
+```moonbit
+let count = sink.write_failures()
+```
+
+In this example, callers get a focused signal for direct file write-path health.
+
+#### When Compare Sink Health After Recovery
+
+When recovery logic should verify whether new failures still occur:
+```moonbit
+ignore(sink.write_failures())
+```
+
+In this example, the metric helps measure whether runtime writes improved after intervention.
+
+### Error Case
+
+e.g.:
+- If callers need a fuller view of file health, `state()` may be a better API.
+
+- This counter does not itself distinguish open-path issues from write-path issues.
+
+### Notes
+
+1. Use this helper for focused write-failure visibility.
+
+2. Pair it with `flush_failures()` when diagnosing direct output-path instability.
diff --git a/docs/api/index.md b/docs/api/index.md
index fcaf72f..76d6bb6 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -154,6 +154,12 @@ BitLogger API navigation.
 - [file-sink-default-policy.md](./file-sink-default-policy.md)
 - [file-sink-policy-matches-default.md](./file-sink-policy-matches-default.md)
 - [file-sink-state-method.md](./file-sink-state-method.md)
+- [file-sink-rotation-failures.md](./file-sink-rotation-failures.md)
+- [file-sink-open-failures.md](./file-sink-open-failures.md)
+- [file-sink-write-failures.md](./file-sink-write-failures.md)
+- [file-sink-flush-failures.md](./file-sink-flush-failures.md)
+- [file-sink-reset-failure-counters.md](./file-sink-reset-failure-counters.md)
+- [file-sink-reset-policy.md](./file-sink-reset-policy.md)
 - [file-sink-reopen.md](./file-sink-reopen.md)
 - [file-sink-reopen-with-current-policy.md](./file-sink-reopen-with-current-policy.md)
 - [file-sink-reopen-append.md](./file-sink-reopen-append.md)