📝 clarify queued file failure docs

docs/api/configured-logger-file-flush.md

@@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors
 
 - Plain file sinks forward directly to file flush behavior through the wrapped `RuntimeSink`.
 - Queued file sinks first flush queued records, then flush the wrapped inner file sink.
+- For queued file sinks, this step may also be the point where queued records finally hit the inner file sink, so write-failure counters can change here even if earlier log calls only queued records.
 - Non-file sinks return `false`.
 - This helper is narrower than generic `flush()` because it targets file sink behavior specifically.
 
@@ -71,4 +72,4 @@ e.g.:
 
 1. Prefer this helper when the configured sink is known to be file-backed.
 
-2. Queued file sinks may perform both queue flush and file flush work here.
+2. Queued file sinks may perform both queue flush and file flush work here, including surfacing delayed write failures from previously queued records.

docs/api/configured-logger-file-reset-failure-counters.md

@@ -72,4 +72,4 @@ e.g.:
 
 1. Use this helper after diagnostics or recovery, not before capturing needed evidence.
 
-2. It is the reset companion for the file failure-counter helpers.
+2. For queued file sinks, it resets the inner file counters only; it does not clear still-pending queued records that may produce new failures on a later `file_flush()`.

docs/api/configured-logger-file-write-failures.md

@@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors
 
 - File-backed sinks report their recorded write-failure count through the wrapped `RuntimeSink`.
 - Queued file sinks forward the metric from the wrapped inner file sink.
+- For queued file sinks, enqueueing a record does not increment this counter by itself. The counter changes only when queued records are drained into the inner file sink, such as through `file_flush()`.
 - Non-file sinks return `0`.
 - The counter is cumulative until reset.
 
@@ -71,4 +72,4 @@ e.g.:
 
 1. Use this helper for focused write-failure visibility.
 
-2. Pair it with `file_flush_failures()` when diagnosing output-path instability.
+2. Pair it with `file_flush()` and `file_flush_failures()` when diagnosing queued output-path instability.

docs/api/runtime-sink-file-flush.md

@@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors
 - Plain `File` runtime variants forward directly to `FileSink::flush()`.
 - `QueuedFile` runtime variants first attempt `sink.flush()` on the queue wrapper, then call `sink.sink.flush()` on the wrapped file sink.
 - For `QueuedFile`, the queue flush result is ignored and the returned `Bool` comes from the inner file flush.
+- For `QueuedFile`, this step may also be the point where queued records finally reach the inner file sink, so write-failure counters can change here even if earlier `log(...)` calls only enqueued records.
 - Non-file runtime variants return `false`.
 
 ### How to Use
@@ -71,4 +72,4 @@ e.g.:
 
 1. Prefer this helper when direct runtime code specifically cares about file flush behavior.
 
-2. Queued file sinks may perform both queue flush work and file flush work here.
+2. Queued file sinks may perform both queue flush work and file flush work here, including surfacing delayed write failures from previously queued records.

docs/api/runtime-sink-file-reset-failure-counters.md

@@ -72,4 +72,4 @@ e.g.:
 
 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.
+2. For queued file sinks, it resets the inner file counters only; it does not clear still-pending queued records that may produce new failures on a later `file_flush()`.

docs/api/runtime-sink-file-write-failures.md

@@ -35,6 +35,7 @@ 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`.
+- For `QueuedFile`, enqueueing a record does not increment this counter by itself. The counter changes only when queued records are actually drained into the inner file sink, such as through `file_flush()`.
 - Non-file runtime variants return `0`.
 - The counter is cumulative until `file_reset_failure_counters()` clears it.
 
@@ -71,4 +72,4 @@ e.g.:
 
 1. Use this helper for focused direct runtime write-failure visibility.
 
-2. Pair it with `file_flush_failures()` when diagnosing output-path instability.
+2. Pair it with `file_flush()` and `file_flush_failures()` when diagnosing queued output-path instability.