📝 document file sink lifecycle methods

docs/api/file-sink-available.md

@@ -0,0 +1,76 @@
+---
+name: file-sink-available
+group: api
+category: sink
+update-time: 20260613
+description: Read whether a FileSink currently has an available underlying file handle.
+key-word:
+    - file
+    - sink
+    - available
+    - public
+---
+
+## File-sink-available
+
+Read whether a `FileSink` currently has an available underlying file handle. This helper is useful for runtime diagnostics and for deciding whether reopen or fallback behavior is needed.
+
+### Interface
+
+```moonbit
+pub fn FileSink::is_available(self : FileSink) -> Bool {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose current availability should be inspected.
+
+#### output
+
+- `Bool` - Whether the sink currently holds an active file handle.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This method reports whether `self.handle` is currently `Some(_)`.
+- A sink can become unavailable after open failure or after an explicit `close()`.
+- This helper does not mutate sink state.
+- It is the direct `FileSink` counterpart to configured-logger file availability checks.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Direct Sink Health Checks
+
+When code works with a concrete file sink and should verify handle readiness:
+```moonbit
+if !sink.is_available() {
+  println("file sink unavailable")
+}
+```
+
+In this example, the caller can detect whether the sink currently has an active file handle.
+
+#### When Gate Recovery Or Reopen Logic
+
+When a reopen step should only run after loss of availability:
+```moonbit
+let ok = sink.is_available()
+```
+
+In this example, the boolean result can drive later recovery behavior.
+
+### Error Case
+
+e.g.:
+- If the sink failed to open initially, this method returns `false`.
+
+- If callers need failure counters or a richer state snapshot rather than a yes-or-no result, `state()` is the better API.
+
+### Notes
+
+1. Use this helper for lightweight file sink health checks.
+
+2. Pair it with `reopen(...)`, `state()`, or failure-counter APIs when diagnosing file sink problems.

docs/api/file-sink-close.md

@@ -0,0 +1,74 @@
+---
+name: file-sink-close
+group: api
+category: sink
+update-time: 20260613
+description: Close a FileSink and drop its current file handle.
+key-word:
+    - file
+    - sink
+    - close
+    - public
+---
+
+## File-sink-close
+
+Close a `FileSink` and drop its current file handle. This helper is the direct file-sink shutdown surface when code manages a concrete `FileSink` value.
+
+### Interface
+
+```moonbit
+pub fn FileSink::close(self : FileSink) -> Bool {
+```
+
+#### input
+
+- `self : FileSink` - File sink to close.
+
+#### output
+
+- `Bool` - Whether closing the current handle succeeded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- If the sink currently has no file handle, the method returns `false`.
+- When a handle exists, the method attempts to close it and then sets the stored handle to `None`.
+- After a successful or failed close attempt on an existing handle, the sink becomes unavailable until reopened.
+- This helper does not automatically reopen the sink.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Direct File Teardown
+
+When code owns a concrete file sink and wants to release its file handle explicitly:
+```moonbit
+ignore(sink.close())
+```
+
+In this example, the sink closes its current file handle directly.
+
+#### When Need To Check Close Outcome Before Reopen
+
+When code should observe whether a shutdown step succeeded:
+```moonbit
+let closed = sink.close()
+```
+
+In this example, the result can be used before a later `reopen(...)` step.
+
+### Error Case
+
+e.g.:
+- If the sink is already unavailable, the method returns `false`.
+
+- If callers only want to inspect whether the sink still has a handle, `is_available()` is the simpler API.
+
+### Notes
+
+1. This method changes sink availability by clearing the current handle.
+
+2. It is commonly paired with `reopen(...)` when file lifecycle should be controlled explicitly.

docs/api/file-sink-flush.md

@@ -0,0 +1,74 @@
+---
+name: file-sink-flush
+group: api
+category: sink
+update-time: 20260613
+description: Flush a FileSink when it currently has an available file handle.
+key-word:
+    - file
+    - sink
+    - flush
+    - public
+---
+
+## File-sink-flush
+
+Flush a `FileSink` directly. This helper is the concrete file-sink flush surface when code is working with a `FileSink` value instead of a configured runtime wrapper.
+
+### Interface
+
+```moonbit
+pub fn FileSink::flush(self : FileSink) -> Bool {
+```
+
+#### input
+
+- `self : FileSink` - File sink to flush.
+
+#### output
+
+- `Bool` - Whether the flush operation succeeded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- If the sink currently has no file handle, the method returns `false`.
+- On flush failure, `flush_failures` is incremented.
+- On success, failure counters are left unchanged.
+- This helper does not reopen the sink automatically.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Explicit File Durability Steps
+
+When a concrete file sink should flush buffered file output explicitly:
+```moonbit
+ignore(sink.flush())
+```
+
+In this example, the caller requests a direct file flush on the sink value itself.
+
+#### When Need A Flush Success Flag
+
+When code should branch on the outcome of a direct file flush:
+```moonbit
+let ok = sink.flush()
+```
+
+In this example, the result tells the caller whether the current flush succeeded.
+
+### Error Case
+
+e.g.:
+- If the sink is unavailable, the method returns `false`.
+
+- If repeated flush failures matter operationally, inspect `flush_failures()` or `state()` instead of ignoring the result forever.
+
+### Notes
+
+1. Prefer this helper when you are working with a `FileSink` directly rather than through `ConfiguredLogger`.
+
+2. This method is narrower than automatic per-write flushing controlled by `auto_flush` policy.

docs/api/index.md

@@ -139,6 +139,9 @@ BitLogger API navigation.
 - [patch-sink.md](./patch-sink.md)
 - [patch-sink-type.md](./patch-sink-type.md)
 - [file-sink.md](./file-sink.md)
+- [file-sink-available.md](./file-sink-available.md)
+- [file-sink-flush.md](./file-sink-flush.md)
+- [file-sink-close.md](./file-sink-close.md)
 - [file-sink-type.md](./file-sink-type.md)
 - [native-files-supported.md](./native-files-supported.md)
 - [file-rotation.md](./file-rotation.md)