📝 document file sink reopen methods

docs/api/file-sink-reopen-append.md

@@ -0,0 +1,74 @@
+---
+name: file-sink-reopen-append
+group: api
+category: sink
+update-time: 20260613
+description: Reopen a FileSink in append mode.
+key-word:
+    - file
+    - sink
+    - reopen
+    - public
+---
+
+## File-sink-reopen-append
+
+Reopen a `FileSink` in append mode. This helper is the explicit append-oriented recovery shortcut on the direct sink.
+
+### Interface
+
+```moonbit
+pub fn FileSink::reopen_append(self : FileSink) -> Bool {
+```
+
+#### input
+
+- `self : FileSink` - File sink that should be reopened in append mode.
+
+#### output
+
+- `Bool` - Whether reopen succeeded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper is a specialized shortcut over `reopen(append=Some(true))`.
+- Reopen behavior is fixed to append mode.
+- The stored append policy is updated to `true` as part of the reopen path.
+- On failure, the sink remains unavailable and `open_failures` is incremented.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Append-preserving Recovery
+
+When file logging should continue appending after a reopen:
+```moonbit
+ignore(sink.reopen_append())
+```
+
+In this example, reopen behavior is fixed to append mode.
+
+#### When Want An Explicit Append Shortcut
+
+When code should avoid manually setting append overrides:
+```moonbit
+let ok = sink.reopen_append()
+```
+
+In this example, the call site states append intent directly.
+
+### Error Case
+
+e.g.:
+- If callers need truncate behavior instead, `reopen_truncate()` is the correct API.
+
+- If reopen fails, the helper returns `false` and the sink stays unavailable.
+
+### Notes
+
+1. Use this helper for explicit append-mode reopen flows.
+
+2. It is especially useful after transient file availability issues.

docs/api/file-sink-reopen-truncate.md

@@ -0,0 +1,74 @@
+---
+name: file-sink-reopen-truncate
+group: api
+category: sink
+update-time: 20260613
+description: Reopen a FileSink in truncate mode.
+key-word:
+    - file
+    - sink
+    - reopen
+    - public
+---
+
+## File-sink-reopen-truncate
+
+Reopen a `FileSink` in truncate mode. This helper is the explicit truncate-oriented recovery or reset shortcut on the direct sink.
+
+### Interface
+
+```moonbit
+pub fn FileSink::reopen_truncate(self : FileSink) -> Bool {
+```
+
+#### input
+
+- `self : FileSink` - File sink that should be reopened in truncate mode.
+
+#### output
+
+- `Bool` - Whether reopen succeeded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper is a specialized shortcut over `reopen(append=Some(false))`.
+- Reopen behavior is fixed to truncate mode.
+- The stored append policy is updated to `false` as part of the reopen path.
+- On failure, the sink remains unavailable and `open_failures` is incremented.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Fresh Output File
+
+When a direct runtime file should be reopened from an empty state:
+```moonbit
+ignore(sink.reopen_truncate())
+```
+
+In this example, reopen behavior truncates the file before future writes continue.
+
+#### When Want An Explicit Truncate Shortcut
+
+When code should make destructive reopen intent obvious:
+```moonbit
+let ok = sink.reopen_truncate()
+```
+
+In this example, the call site expresses reset-style reopen behavior directly.
+
+### Error Case
+
+e.g.:
+- If callers want to preserve existing file content, `reopen_append()` is the correct API.
+
+- If reopen fails, the helper returns `false` and the sink stays unavailable.
+
+### Notes
+
+1. Use this helper when starting from a fresh file is intentional.
+
+2. Truncate-mode reopen is a stronger action than generic reopen recovery.

docs/api/file-sink-reopen-with-current-policy.md

@@ -0,0 +1,74 @@
+---
+name: file-sink-reopen-with-current-policy
+group: api
+category: sink
+update-time: 20260613
+description: Reopen a FileSink using its currently stored runtime policy.
+key-word:
+    - file
+    - sink
+    - reopen
+    - public
+---
+
+## File-sink-reopen-with-current-policy
+
+Reopen a `FileSink` using the currently stored runtime policy. This helper is useful when direct recovery should happen without supplying a one-off append override.
+
+### Interface
+
+```moonbit
+pub fn FileSink::reopen_with_current_policy(self : FileSink) -> Bool {
+```
+
+#### input
+
+- `self : FileSink` - File sink that should be reopened with current policy.
+
+#### output
+
+- `Bool` - Whether reopen succeeded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper reuses the sink's currently stored append policy.
+- It differs from `reopen(...)` because it does not accept a per-call append override.
+- Existing handle state is handled through the underlying `reopen(...)` behavior.
+- On failure, the sink remains unavailable and `open_failures` is updated by the reopen path.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Policy-preserving Recovery
+
+When a file sink should be reopened without changing runtime append behavior:
+```moonbit
+ignore(sink.reopen_with_current_policy())
+```
+
+In this example, recovery reuses the runtime policy already stored on the sink.
+
+#### When Separate Recovery From Policy Mutation
+
+When append mode should be controlled elsewhere:
+```moonbit
+let ok = sink.reopen_with_current_policy()
+```
+
+In this example, reopen is explicit while policy mutation stays separate.
+
+### Error Case
+
+e.g.:
+- If callers want to change append behavior during reopen, `reopen(...)`, `reopen_append()`, or `reopen_truncate()` are better APIs.
+
+- This helper still depends on the underlying file backend being able to reopen the path successfully.
+
+### Notes
+
+1. Use this helper when recovery should respect the currently stored runtime policy.
+
+2. It is clearer than passing no override through a more general reopen API.

docs/api/file-sink-reopen.md

@@ -0,0 +1,75 @@
+---
+name: file-sink-reopen
+group: api
+category: sink
+update-time: 20260613
+description: Reopen a FileSink with an optional append-mode override.
+key-word:
+    - file
+    - sink
+    - reopen
+    - public
+---
+
+## File-sink-reopen
+
+Reopen a `FileSink`. This helper is useful for direct recovery flows after file unavailability or after file policy changes.
+
+### Interface
+
+```moonbit
+pub fn FileSink::reopen(self : FileSink, append~ : Bool? = None) -> Bool {
+```
+
+#### input
+
+- `self : FileSink` - File sink that should be reopened.
+- `append : Bool?` - Optional append-mode override used for reopen behavior.
+
+#### output
+
+- `Bool` - Whether reopen succeeded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `append=None` preserves the sink's current append policy.
+- `Some(true/false)` overrides append mode for this reopen and updates the stored append policy.
+- If a handle is currently open, the method closes it before attempting reopen.
+- On reopen failure, `open_failures` is incremented and the sink remains unavailable.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Recovery After File Failure
+
+When direct file logging code should attempt to restore sink availability:
+```moonbit
+ignore(sink.reopen())
+```
+
+In this example, the sink tries to reopen using its current append policy.
+
+#### When Need Explicit Append-mode Reopen
+
+When recovery should choose append or truncate behavior explicitly:
+```moonbit
+let ok = sink.reopen(append=Some(true))
+```
+
+In this example, reopen behavior is directed by the call site.
+
+### Error Case
+
+e.g.:
+- If reopen fails, the method returns `false` and increments `open_failures()`.
+
+- If callers only need the current configured policy with no one-off override, `reopen_with_current_policy()` may be the clearer API.
+
+### Notes
+
+1. Use this helper for direct recovery flows.
+
+2. Pair it with `is_available()` and failure counters when diagnosing reopen behavior.

docs/api/index.md

@@ -154,6 +154,10 @@ 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-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)
+- [file-sink-reopen-truncate.md](./file-sink-reopen-truncate.md)
 - [file-sink-type.md](./file-sink-type.md)
 - [native-files-supported.md](./native-files-supported.md)
 - [file-rotation.md](./file-rotation.md)