📝 补充runtime文档

docs/api/runtime-sink-progress.md

@@ -0,0 +1,85 @@
+---
+name: runtime-sink-progress
+group: api
+category: runtime
+update-time: 20260707
+description: Public structured generic progress snapshot used by RuntimeSink and ConfiguredLogger flush or drain helpers.
+key-word:
+    - runtime
+    - progress
+    - flush
+    - public
+---
+
+## Runtime-sink-progress
+
+`RuntimeSinkProgress` is the public structured progress snapshot returned by the truthful generic `flush_progress(...)` and `drain_progress(...)` helpers. It separates queue advancement from plain file flush fallback steps so callers do not have to infer mixed `Int` semantics from `flush()` or `drain()` alone.
+
+### Interface
+
+```moonbit
+pub struct RuntimeSinkProgress {
+  queue_advanced_count : Int
+  file_flush_step_count : Int
+  queue_backed : Bool
+  file_backed : Bool
+}
+```
+
+#### output
+
+- `RuntimeSinkProgress` - Public generic progress snapshot containing queue advancement count, plain-file flush fallback count, and runtime-shape flags.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a public root struct, not a type alias.
+- `queue_advanced_count` reports how many queued records were consumed by a queue-backed runtime helper call.
+- `file_flush_step_count` reports the plain-file fallback step count used by generic helpers on non-queued file sinks, currently `1` for a successful `FileSink::flush()` and `0` otherwise.
+- `queue_backed` reports whether the runtime sink shape was queue-backed during the helper call.
+- `file_backed` reports whether the runtime sink shape was file-backed during the helper call.
+- For queued file sinks, `queue_advanced_count` may be positive while `file_flush_step_count` stays `0`; delayed file failures still belong to `file_flush()` and failure-counter inspection rather than to this generic progress snapshot.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Truthful Generic Runtime Progress
+
+When code should inspect generic flush or drain work without guessing what one `Int` means:
+```moonbit
+let progress = sink.flush_progress()
+if progress.queue_backed {
+  println(progress.queue_advanced_count)
+}
+```
+
+In this example, queue progress stays explicit instead of being folded into a compatibility count.
+
+#### When Need To Distinguish Plain File Fallback From Queue Work
+
+When generic runtime support code should tell plain-file fallback apart from queued advancement:
+```moonbit
+let progress = logger.drain_progress()
+if progress.file_backed && !progress.queue_backed {
+  println(progress.file_flush_step_count)
+}
+```
+
+In this example, the caller can recognize the plain-file generic fallback path directly.
+
+### Error Case
+
+e.g.:
+- `RuntimeSinkProgress` itself does not have a runtime failure mode.
+
+- This type reports generic progress only; it does not prove durable file delivery.
+
+- If callers need file-specific success semantics, `file_flush()` is still the narrower API.
+
+### Notes
+
+1. Prefer this structured result over the legacy `Int` returned by `flush()` and `drain()` when new code can choose.
+
+2. For queued file sinks, combine this snapshot with `file_flush()`, `file_runtime_state()`, or file failure counters when file outcome matters.