📝 document file sink policy state methods

docs/api/file-sink-default-policy.md

@@ -0,0 +1,73 @@
+---
+name: file-sink-default-policy
+group: api
+category: sink
+update-time: 20260613
+description: Read the initial default file policy captured by a FileSink.
+key-word:
+    - file
+    - sink
+    - policy
+    - public
+---
+
+## File-sink-default-policy
+
+Read the initial default file policy captured by a `FileSink`. This helper exposes the baseline file policy recorded when the sink was created.
+
+### Interface
+
+```moonbit
+pub fn FileSink::default_policy(self : FileSink) -> FileSinkPolicy {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose default file policy should be inspected.
+
+#### output
+
+- `FileSinkPolicy` - Initial default file policy.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The returned policy is built from the sink's stored default append, auto-flush, and rotation values.
+- This helper is useful when callers need to compare runtime drift or restore defaults later.
+- It is observation-only and does not mutate sink state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Baseline Policy Visibility
+
+When diagnostics should show the original file policy separately from the live one:
+```moonbit
+let defaults = sink.default_policy()
+```
+
+In this example, the direct file sink exposes its original file policy snapshot.
+
+#### When Prepare For Policy Reset Logic
+
+When tooling should capture or compare default settings explicitly:
+```moonbit
+let original = sink.default_policy()
+```
+
+In this example, callers can reason about factory policy separately from runtime changes.
+
+### Error Case
+
+e.g.:
+- If callers only need to know whether runtime drift exists, `policy_matches_default()` is the simpler API.
+
+- This helper does not say whether the current sink handle is available.
+
+### Notes
+
+1. Use this helper when the original file policy matters operationally.
+
+2. It complements `policy()` and `reset_policy()`.

docs/api/file-sink-policy-matches-default.md

@@ -0,0 +1,76 @@
+---
+name: file-sink-policy-matches-default
+group: api
+category: sink
+update-time: 20260613
+description: Read whether the current FileSink policy still matches its default policy.
+key-word:
+    - file
+    - sink
+    - policy
+    - public
+---
+
+## File-sink-policy-matches-default
+
+Read whether the current runtime file policy of a `FileSink` still matches its default policy. This helper is useful for detecting direct policy drift on the sink.
+
+### Interface
+
+```moonbit
+pub fn FileSink::policy_matches_default(self : FileSink) -> Bool {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose runtime policy drift should be checked.
+
+#### output
+
+- `Bool` - Whether the current runtime file policy still matches the default.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The method compares current append and auto-flush settings directly.
+- Rotation drift is checked structurally, comparing `max_bytes` and `max_backups` when both sides are present.
+- This helper is a compact drift signal when callers do not need to compare full policy objects directly.
+- It does not mutate sink state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Drift Detection
+
+When diagnostics should report whether file policy changed after startup:
+```moonbit
+let unchanged = sink.policy_matches_default()
+```
+
+In this example, the direct sink exposes whether runtime file policy still matches the baseline.
+
+#### When Gate Reset Logic
+
+When code should only reset policy if drift exists:
+```moonbit
+if !sink.policy_matches_default() {
+  sink.reset_policy()
+}
+```
+
+In this example, policy reset only happens when runtime state diverged from defaults.
+
+### Error Case
+
+e.g.:
+- If callers need the exact differences instead of a boolean drift signal, they should inspect both `policy()` and `default_policy()`.
+
+- This helper only compares policy state; it does not report open, write, or flush failures.
+
+### Notes
+
+1. Use this helper for compact direct policy drift checks.
+
+2. It is especially useful before calling reset-style operations.

docs/api/file-sink-policy-method.md

@@ -0,0 +1,74 @@
+---
+name: file-sink-policy-method
+group: api
+category: sink
+update-time: 20260613
+description: Read the current runtime file policy from a FileSink.
+key-word:
+    - file
+    - sink
+    - policy
+    - public
+---
+
+## File-sink-policy-method
+
+Read the current runtime file policy from a `FileSink`. This helper exposes the active append, auto-flush, and rotation settings as one policy object on the concrete sink.
+
+### Interface
+
+```moonbit
+pub fn FileSink::policy(self : FileSink) -> FileSinkPolicy {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose current file policy should be inspected.
+
+#### output
+
+- `FileSinkPolicy` - Current runtime file policy.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The returned policy is constructed from the sink's current append, auto-flush, and rotation settings.
+- This helper is broader than `append_mode()` or `auto_flush_enabled()` because it returns the whole policy object.
+- It is observation-only and does not mutate sink state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Full Runtime Policy Visibility
+
+When diagnostics should inspect the active file policy as one object:
+```moonbit
+let policy = sink.policy()
+```
+
+In this example, append, flush, and rotation settings are read together from the direct sink.
+
+#### When Compare Current And Default Policy
+
+When runtime drift from defaults should be inspected explicitly:
+```moonbit
+let current = sink.policy()
+let defaults = sink.default_policy()
+```
+
+In this example, callers can compare current runtime settings with the initial policy snapshot.
+
+### Error Case
+
+e.g.:
+- If callers only need one field from the policy, a narrower helper may be simpler.
+
+- This helper describes policy state, not whether the sink is currently available.
+
+### Notes
+
+1. Use this helper when file policy should be handled as one object.
+
+2. Pair it with `set_policy(...)` for roundtrip-style policy management.

docs/api/file-sink-set-rotation.md

@@ -0,0 +1,71 @@
+---
+name: file-sink-set-rotation
+group: api
+category: sink
+update-time: 20260613
+description: Update the rotation configuration used by a FileSink.
+key-word:
+    - file
+    - sink
+    - rotation
+    - public
+---
+
+## File-sink-set-rotation
+
+Update the rotation configuration used by a `FileSink`. This helper changes direct runtime file rotation behavior without rebuilding or reopening the sink.
+
+### Interface
+
+```moonbit
+pub fn FileSink::set_rotation(self : FileSink, rotation : FileRotation?) -> Unit {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose rotation policy should change.
+- `rotation : FileRotation?` - New rotation config, or `None` to disable rotation.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This method updates runtime rotation policy only.
+- Passing `None` disables rotation.
+- It does not reopen the sink or rotate immediately by itself.
+- Append and auto-flush settings are left unchanged.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Runtime Rotation Tuning
+
+When a concrete file sink should enable or change rotation dynamically:
+```moonbit
+sink.set_rotation(Some(file_rotation(1024, max_backups=3)))
+```
+
+In this example, direct runtime rotation behavior is updated without rebuilding the sink.
+
+#### When Need To Disable Rotation
+
+When the file sink should stop rotating:
+```moonbit
+sink.set_rotation(None)
+```
+
+In this example, the sink has its rotation policy cleared explicitly.
+
+### Error Case
+
+e.g.:
+- If callers only want to remove rotation, `clear_rotation()` is the more direct API.
+
+- This helper does not report past rotation failures; use `rotation_failures()` or `state()` for diagnostics.
+
+### Notes
+
+1. Use this helper when setting a full runtime rotation config.
+
+2. It is useful for operational tuning on a concrete file sink without rebuilding it.

docs/api/file-sink-state-method.md

@@ -0,0 +1,74 @@
+---
+name: file-sink-state-method
+group: api
+category: sink
+update-time: 20260613
+description: Read the current file sink snapshot from a FileSink.
+key-word:
+    - file
+    - sink
+    - state
+    - public
+---
+
+## File-sink-state-method
+
+Read the current file sink snapshot from a `FileSink`. This helper exposes path, availability, policy flags, rotation config, and failure counters as one object on the direct sink.
+
+### Interface
+
+```moonbit
+pub fn FileSink::state(self : FileSink) -> FileSinkState {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose file state snapshot should be inspected.
+
+#### output
+
+- `FileSinkState` - Current file sink snapshot.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The snapshot includes path, availability, append policy, auto-flush policy, rotation config, and failure counters.
+- `available` is derived from `is_available()`.
+- This helper is broader than individual counters or policy accessors because it aggregates core file status into one read.
+- It does not mutate sink state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Full File Health Snapshot
+
+When diagnostics should inspect direct file state as one object:
+```moonbit
+let state = sink.state()
+```
+
+In this example, callers receive a single file-state snapshot instead of querying each property separately.
+
+#### When Need To Export File Diagnostics
+
+When a support path should serialize current file state:
+```moonbit
+println(stringify_file_sink_state(sink.state(), pretty=true))
+```
+
+In this example, the direct sink snapshot can be exported through the existing JSON helpers.
+
+### Error Case
+
+e.g.:
+- If callers only need one small part of direct file state, a narrower accessor may be simpler.
+
+- This helper is a snapshot read, not an operational repair action.
+
+### Notes
+
+1. Use this helper for the main one-shot file status snapshot.
+
+2. Prefer it over individual counters when broader direct file diagnostics are needed.

docs/api/index.md

@@ -149,6 +149,11 @@ BitLogger API navigation.
 - [file-sink-set-append-mode.md](./file-sink-set-append-mode.md)
 - [file-sink-set-auto-flush.md](./file-sink-set-auto-flush.md)
 - [file-sink-clear-rotation.md](./file-sink-clear-rotation.md)
+- [file-sink-set-rotation.md](./file-sink-set-rotation.md)
+- [file-sink-policy-method.md](./file-sink-policy-method.md)
+- [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-type.md](./file-sink-type.md)
 - [native-files-supported.md](./native-files-supported.md)
 - [file-rotation.md](./file-rotation.md)