From 419b79ac50cbde4d33630b5778305995b60cffdc Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sat, 13 Jun 2026 23:14:22 +0800
Subject: [PATCH] :memo: document runtime sink failure counters

---
 docs/api/index.md                             |  5 ++
 docs/api/runtime-sink-file-flush-failures.md  | 74 ++++++++++++++++++
 docs/api/runtime-sink-file-open-failures.md   | 74 ++++++++++++++++++
 ...untime-sink-file-reset-failure-counters.md | 75 +++++++++++++++++++
 .../runtime-sink-file-rotation-failures.md    | 74 ++++++++++++++++++
 docs/api/runtime-sink-file-write-failures.md  | 74 ++++++++++++++++++
 6 files changed, 376 insertions(+)
 create mode 100644 docs/api/runtime-sink-file-flush-failures.md
 create mode 100644 docs/api/runtime-sink-file-open-failures.md
 create mode 100644 docs/api/runtime-sink-file-reset-failure-counters.md
 create mode 100644 docs/api/runtime-sink-file-rotation-failures.md
 create mode 100644 docs/api/runtime-sink-file-write-failures.md

diff --git a/docs/api/index.md b/docs/api/index.md
index 901ed75..7581237 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -377,6 +377,11 @@ BitLogger API navigation.
 - [runtime-sink-file-clear-rotation.md](./runtime-sink-file-clear-rotation.md)
 - [runtime-sink-file-flush.md](./runtime-sink-file-flush.md)
 - [runtime-sink-file-close.md](./runtime-sink-file-close.md)
+- [runtime-sink-file-open-failures.md](./runtime-sink-file-open-failures.md)
+- [runtime-sink-file-write-failures.md](./runtime-sink-file-write-failures.md)
+- [runtime-sink-file-flush-failures.md](./runtime-sink-file-flush-failures.md)
+- [runtime-sink-file-rotation-failures.md](./runtime-sink-file-rotation-failures.md)
+- [runtime-sink-file-reset-failure-counters.md](./runtime-sink-file-reset-failure-counters.md)
 - [configured-logger.md](./configured-logger.md)
 - [configured-logger-flush.md](./configured-logger-flush.md)
 - [configured-logger-drain.md](./configured-logger-drain.md)
diff --git a/docs/api/runtime-sink-file-flush-failures.md b/docs/api/runtime-sink-file-flush-failures.md
new file mode 100644
index 0000000..1d912b0
--- /dev/null
+++ b/docs/api/runtime-sink-file-flush-failures.md
@@ -0,0 +1,74 @@
+---
+name: runtime-sink-file-flush-failures
+group: api
+category: runtime
+update-time: 20260613
+description: Read the number of flush failures recorded by a file-backed RuntimeSink.
+key-word:
+    - runtime
+    - sink
+    - file
+    - public
+---
+
+## Runtime-sink-file-flush-failures
+
+Read the number of flush failures recorded by a file-backed `RuntimeSink`. This helper is useful for direct runtime diagnostics around durability-path problems.
+
+### Interface
+
+```moonbit
+pub fn RuntimeSink::file_flush_failures(self : RuntimeSink) -> Int {
+```
+
+#### input
+
+- `self : RuntimeSink` - Runtime sink whose flush-failure counter should be inspected.
+
+#### output
+
+- `Int` - Number of recorded flush failures.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain `File` runtime variants report the wrapped `FileSink` flush-failure count.
+- `QueuedFile` runtime variants forward the metric from the wrapped inner `FileSink`.
+- Non-file runtime variants return `0`.
+- The counter is cumulative until `file_reset_failure_counters()` clears it.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Durability-path Diagnostics
+
+When support output should show flush-path instability:
+```moonbit
+let count = sink.file_flush_failures()
+```
+
+In this example, the runtime sink exposes whether file flush attempts have been failing.
+
+#### When Inspect Effects Of Auto-flush Policy
+
+When runtime durability tuning should be inspected operationally:
+```moonbit
+ignore(sink.file_flush_failures())
+```
+
+In this example, callers can correlate flush failures with direct runtime file policy choices.
+
+### Error Case
+
+e.g.:
+- If the runtime sink is not file-backed, the method returns `0`.
+
+- If callers need current policy and counters together, `file_state()` is the better API.
+
+### Notes
+
+1. Use this helper when direct runtime flush-path reliability matters.
+
+2. Pair it with `file_auto_flush()` and `file_flush()` when diagnosing durability behavior.
diff --git a/docs/api/runtime-sink-file-open-failures.md b/docs/api/runtime-sink-file-open-failures.md
new file mode 100644
index 0000000..3db2b1b
--- /dev/null
+++ b/docs/api/runtime-sink-file-open-failures.md
@@ -0,0 +1,74 @@
+---
+name: runtime-sink-file-open-failures
+group: api
+category: runtime
+update-time: 20260613
+description: Read the number of open failures recorded by a file-backed RuntimeSink.
+key-word:
+    - runtime
+    - sink
+    - file
+    - public
+---
+
+## Runtime-sink-file-open-failures
+
+Read the number of open failures recorded by a file-backed `RuntimeSink`. This helper is useful for direct runtime diagnostics around file availability and reopen behavior.
+
+### Interface
+
+```moonbit
+pub fn RuntimeSink::file_open_failures(self : RuntimeSink) -> Int {
+```
+
+#### input
+
+- `self : RuntimeSink` - Runtime sink whose open-failure counter should be inspected.
+
+#### output
+
+- `Int` - Number of recorded open failures.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain `File` runtime variants report the wrapped `FileSink` open-failure count.
+- `QueuedFile` runtime variants forward the metric from the wrapped inner `FileSink`.
+- Non-file runtime variants return `0`.
+- The counter is cumulative until `file_reset_failure_counters()` clears it.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need File Availability Diagnostics
+
+When direct runtime support output should show whether file open or reopen failed:
+```moonbit
+let count = sink.file_open_failures()
+```
+
+In this example, the runtime sink exposes the open-failure metric directly.
+
+#### When Validate Recovery Logic
+
+When recovery code should inspect whether reopen attempts failed:
+```moonbit
+ignore(sink.file_open_failures())
+```
+
+In this example, the counter helps confirm whether file-open problems occurred during runtime.
+
+### Error Case
+
+e.g.:
+- If the runtime sink is not file-backed, the method returns `0`.
+
+- If callers need the full file status snapshot rather than one counter, `file_state()` is the better API.
+
+### Notes
+
+1. Use this helper for focused direct runtime file-open diagnostics.
+
+2. Pair it with `file_reopen(...)` and `file_available()` during recovery analysis.
diff --git a/docs/api/runtime-sink-file-reset-failure-counters.md b/docs/api/runtime-sink-file-reset-failure-counters.md
new file mode 100644
index 0000000..838547d
--- /dev/null
+++ b/docs/api/runtime-sink-file-reset-failure-counters.md
@@ -0,0 +1,75 @@
+---
+name: runtime-sink-file-reset-failure-counters
+group: api
+category: runtime
+update-time: 20260613
+description: Reset the file failure counters recorded by a file-backed RuntimeSink.
+key-word:
+    - runtime
+    - sink
+    - file
+    - public
+---
+
+## Runtime-sink-file-reset-failure-counters
+
+Reset the file failure counters recorded by a file-backed `RuntimeSink`. This helper clears open, write, flush, and rotation failure metrics together.
+
+### Interface
+
+```moonbit
+pub fn RuntimeSink::file_reset_failure_counters(self : RuntimeSink) -> Bool {
+```
+
+#### input
+
+- `self : RuntimeSink` - Runtime sink whose file failure counters should be cleared.
+
+#### output
+
+- `Bool` - Whether the reset was applied.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain `File` runtime variants clear all file failure counters together and return `true`.
+- `QueuedFile` runtime variants forward the reset behavior to the wrapped inner `FileSink` and return `true`.
+- Non-file runtime variants return `false`.
+- This helper is useful after diagnostics, recovery, or controlled tests.
+
+### 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
+ignore(sink.file_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
+ignore(sink.file_reset_failure_counters())
+ignore(sink.file_open_failures())
+```
+
+In this example, the runtime sink starts a new diagnostics window after reset.
+
+### Error Case
+
+e.g.:
+- If the runtime sink is not file-backed, the method returns `false`.
+
+- If callers need the current values before clearing them, they should read the counters or `file_state()` first.
+
+### Notes
+
+1. Use this helper after diagnostics or recovery, not before capturing needed evidence.
+
+2. It is the reset companion for the direct runtime file failure-counter helpers.
diff --git a/docs/api/runtime-sink-file-rotation-failures.md b/docs/api/runtime-sink-file-rotation-failures.md
new file mode 100644
index 0000000..aa0ff01
--- /dev/null
+++ b/docs/api/runtime-sink-file-rotation-failures.md
@@ -0,0 +1,74 @@
+---
+name: runtime-sink-file-rotation-failures
+group: api
+category: runtime
+update-time: 20260613
+description: Read the number of rotation failures recorded by a file-backed RuntimeSink.
+key-word:
+    - runtime
+    - sink
+    - file
+    - public
+---
+
+## Runtime-sink-file-rotation-failures
+
+Read the number of rotation failures recorded by a file-backed `RuntimeSink`. This helper is useful when direct runtime rotation behavior should be observed operationally.
+
+### Interface
+
+```moonbit
+pub fn RuntimeSink::file_rotation_failures(self : RuntimeSink) -> Int {
+```
+
+#### input
+
+- `self : RuntimeSink` - Runtime sink whose rotation-failure counter should be inspected.
+
+#### output
+
+- `Int` - Number of recorded rotation failures.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain `File` runtime variants report the wrapped `FileSink` rotation-failure count.
+- `QueuedFile` runtime variants forward the metric from the wrapped inner `FileSink`.
+- Non-file runtime variants return `0`.
+- The counter is cumulative until `file_reset_failure_counters()` clears it.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Rotation-specific Diagnostics
+
+When support output should reveal whether rotation is failing:
+```moonbit
+let count = sink.file_rotation_failures()
+```
+
+In this example, the runtime sink exposes a focused metric for direct rotation-path health.
+
+#### When Validate Runtime Rotation Tuning
+
+When changed rotation settings should be checked in operation:
+```moonbit
+ignore(sink.file_rotation_failures())
+```
+
+In this example, callers can observe whether runtime rotation changes introduced problems.
+
+### Error Case
+
+e.g.:
+- If the runtime sink is not file-backed, the method returns `0`.
+
+- If callers need both rotation config and failure metrics, they should combine this helper with `file_rotation_config()` or `file_state()`.
+
+### Notes
+
+1. Use this helper when diagnosing direct runtime file rotation reliability.
+
+2. It is especially relevant when runtime rotation policy can change after startup.
diff --git a/docs/api/runtime-sink-file-write-failures.md b/docs/api/runtime-sink-file-write-failures.md
new file mode 100644
index 0000000..da965fb
--- /dev/null
+++ b/docs/api/runtime-sink-file-write-failures.md
@@ -0,0 +1,74 @@
+---
+name: runtime-sink-file-write-failures
+group: api
+category: runtime
+update-time: 20260613
+description: Read the number of write failures recorded by a file-backed RuntimeSink.
+key-word:
+    - runtime
+    - sink
+    - file
+    - public
+---
+
+## Runtime-sink-file-write-failures
+
+Read the number of write failures recorded by a file-backed `RuntimeSink`. This helper is useful for direct runtime diagnostics around the file write path.
+
+### Interface
+
+```moonbit
+pub fn RuntimeSink::file_write_failures(self : RuntimeSink) -> Int {
+```
+
+#### input
+
+- `self : RuntimeSink` - Runtime sink whose write-failure counter should be inspected.
+
+#### output
+
+- `Int` - Number of recorded write failures.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain `File` runtime variants report the wrapped `FileSink` write-failure count.
+- `QueuedFile` runtime variants forward the metric from the wrapped inner `FileSink`.
+- Non-file runtime variants return `0`.
+- The counter is cumulative until `file_reset_failure_counters()` clears it.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Runtime Write-path Diagnostics
+
+When support output should show whether file writes have been failing:
+```moonbit
+let count = sink.file_write_failures()
+```
+
+In this example, callers get a focused signal for direct runtime file write-path health.
+
+#### When Compare Sink Health After Recovery
+
+When recovery logic should verify whether new failures still occur:
+```moonbit
+ignore(sink.file_write_failures())
+```
+
+In this example, the metric helps measure whether runtime writes improved after intervention.
+
+### Error Case
+
+e.g.:
+- If the runtime sink is not file-backed, the method returns `0`.
+
+- If callers need a fuller view of file health, `file_state()` or `file_runtime_state()` may be better APIs.
+
+### Notes
+
+1. Use this helper for focused direct runtime write-failure visibility.
+
+2. Pair it with `file_flush_failures()` when diagnosing output-path instability.