📝 Add file state export API docs

docs/api/file-sink-policy-to-json.md

@@ -0,0 +1,74 @@
+---
+name: file-sink-policy-to-json
+group: api
+category: runtime
+update-time: 20260512
+description: Convert FileSinkPolicy into a JSON value for runtime diagnostics, policy snapshots, or transport.
+key-word:
+    - file
+    - policy
+    - json
+    - public
+---
+
+## File-sink-policy-to-json
+
+Convert `FileSinkPolicy` into a `JsonValue`. This helper exports append mode, auto-flush, and optional rotation as a structured runtime policy snapshot.
+
+### Interface
+
+```moonbit
+pub fn file_sink_policy_to_json(policy : FileSinkPolicy) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `policy : FileSinkPolicy` - File sink runtime policy to export.
+
+#### output
+
+- `JsonValue` - Structured JSON representation of the file policy.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output includes `append`, `auto_flush`, and `rotation`.
+- `rotation` is exported as `null` when rotation is disabled.
+- This helper exports runtime file policy, not current file health counters or availability.
+- The JSON value is useful for policy snapshots, comparisons, and diagnostics payloads.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Structured Policy Snapshots
+
+When file sink policy should be embedded into a larger JSON payload:
+```moonbit
+let value = file_sink_policy_to_json(sink.policy())
+```
+
+In this example, the runtime file policy becomes a reusable structured value.
+
+#### When Need Policy Comparison Data
+
+When current and default policy should be exported separately:
+```moonbit
+let current = file_sink_policy_to_json(sink.policy())
+```
+
+In this example, callers can compare policy snapshots without formatting text first.
+
+### Error Case
+
+e.g.:
+- If rotation is disabled, the exported `rotation` field is `null` rather than omitted.
+
+- If callers need direct text output, `stringify_file_sink_policy(...)` is the better API.
+
+### Notes
+
+1. Use this helper when downstream code expects `JsonValue` rather than text.
+
+2. It pairs naturally with `policy()` and `default_policy()` runtime accessors.

docs/api/file-sink-state-to-json.md

@@ -0,0 +1,74 @@
+---
+name: file-sink-state-to-json
+group: api
+category: runtime
+update-time: 20260512
+description: Convert FileSinkState into a JSON value for file sink diagnostics and state transport.
+key-word:
+    - file
+    - state
+    - json
+    - public
+---
+
+## File-sink-state-to-json
+
+Convert `FileSinkState` into a `JsonValue`. This helper exports file path, availability, policy flags, rotation config, and failure counters in a structured form.
+
+### Interface
+
+```moonbit
+pub fn file_sink_state_to_json(state : FileSinkState) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `state : FileSinkState` - File sink state snapshot to export.
+
+#### output
+
+- `JsonValue` - Structured JSON representation of the file sink state.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output includes `path`, `available`, `append`, `auto_flush`, failure counters, and `rotation`.
+- `rotation` is exported as `null` when rotation is disabled.
+- This helper exports state snapshots, not mutable runtime control handles.
+- It is useful when file sink state should be embedded into larger diagnostics payloads.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Structured File Diagnostics
+
+When file sink status should be composed into a larger JSON object:
+```moonbit
+let value = file_sink_state_to_json(sink.state())
+```
+
+In this example, callers receive a structured file-state snapshot instead of plain text.
+
+#### When Need Runtime State Snapshots For Tooling
+
+When support tooling should ingest file sink state programmatically:
+```moonbit
+let snapshot = file_sink_state_to_json(state)
+```
+
+In this example, the helper exposes all major file-state fields in machine-readable form.
+
+### Error Case
+
+e.g.:
+- If the file is unavailable, the exported snapshot still serializes normally with `available=false`.
+
+- If callers need direct text output, `stringify_file_sink_state(...)` is the better API.
+
+### Notes
+
+1. Use this helper when diagnostics consumers expect `JsonValue`.
+
+2. It pairs naturally with `FileSink::state()` and `ConfiguredLogger::file_state()`.

docs/api/runtime-file-state-to-json.md

@@ -0,0 +1,74 @@
+---
+name: runtime-file-state-to-json
+group: api
+category: runtime
+update-time: 20260512
+description: Convert RuntimeFileState into a JSON value that combines file status with outer queue runtime metrics.
+key-word:
+    - runtime
+    - file
+    - state
+    - public
+---
+
+## Runtime-file-state-to-json
+
+Convert `RuntimeFileState` into a `JsonValue`. This helper exports both file sink status and outer queue metrics for queued file runtime diagnostics.
+
+### Interface
+
+```moonbit
+pub fn runtime_file_state_to_json(state : RuntimeFileState) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `state : RuntimeFileState` - Combined file and queue runtime snapshot.
+
+#### output
+
+- `JsonValue` - Structured JSON representation of the runtime file state.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output includes `file`, `queued`, `pending_count`, and `dropped_count`.
+- `file` is itself exported as a nested file sink state object.
+- This helper is richer than `file_sink_state_to_json(...)` because it also carries queue wrapping context.
+- It is useful for `ConfiguredLogger::file_runtime_state()` and similar queued-file diagnostics flows.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Structured Queued-file Diagnostics
+
+When file and queue status should be exported together:
+```moonbit
+let value = runtime_file_state_to_json(snapshot)
+```
+
+In this example, callers receive a machine-readable combined runtime snapshot.
+
+#### When Need Support Payload Composition
+
+When queued file runtime data should be embedded into a larger JSON object:
+```moonbit
+let payload = runtime_file_state_to_json(state)
+```
+
+In this example, the helper keeps file-plus-queue diagnostics in one reusable JSON value.
+
+### Error Case
+
+e.g.:
+- If `queued=false`, the state still serializes normally with queue counters present.
+
+- If callers need direct text output, `stringify_runtime_file_state(...)` is the better API.
+
+### Notes
+
+1. Use this helper when file and queue runtime context should stay together.
+
+2. It is especially useful for configured queued file loggers.

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

@@ -0,0 +1,75 @@
+---
+name: stringify-file-sink-policy
+group: api
+category: runtime
+update-time: 20260512
+description: Serialize FileSinkPolicy into compact or pretty JSON text for diagnostics and policy snapshots.
+key-word:
+    - file
+    - policy
+    - stringify
+    - public
+---
+
+## Stringify-file-sink-policy
+
+Serialize `FileSinkPolicy` into JSON text. This helper is the most direct export path for runtime file policy snapshots.
+
+### Interface
+
+```moonbit
+pub fn stringify_file_sink_policy(policy : FileSinkPolicy, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `policy : FileSinkPolicy` - File sink runtime policy to serialize.
+- `pretty : Bool` - Whether JSON should be pretty-printed.
+
+#### output
+
+- `String` - Serialized JSON text for the file policy.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `pretty=false` returns compact JSON.
+- `pretty=true` returns indented JSON for human inspection.
+- This helper builds on top of `file_sink_policy_to_json(...)`.
+- The output is suited for support dumps, policy snapshots, and generated diagnostics text.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Human-readable Policy Output
+
+When current file policy should be printed for diagnostics:
+```moonbit
+println(stringify_file_sink_policy(sink.policy(), pretty=true))
+```
+
+In this example, the runtime file policy is rendered in readable JSON.
+
+#### When Need Compact Policy Export
+
+When a file policy snapshot should stay small:
+```moonbit
+let text = stringify_file_sink_policy(sink.policy())
+```
+
+In this example, compact JSON is produced without extra formatting logic.
+
+### Error Case
+
+e.g.:
+- If callers need a `JsonValue` for composition rather than text, `file_sink_policy_to_json(...)` is the better API.
+
+- If rotation is disabled, the output still includes `rotation` as `null`.
+
+### Notes
+
+1. Use this helper for direct textual policy snapshots.
+
+2. `pretty=true` is useful when operators or support tooling are the audience.

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

@@ -0,0 +1,75 @@
+---
+name: stringify-file-sink-state
+group: api
+category: runtime
+update-time: 20260512
+description: Serialize FileSinkState into compact or pretty JSON text for diagnostics and support output.
+key-word:
+    - file
+    - state
+    - stringify
+    - public
+---
+
+## Stringify-file-sink-state
+
+Serialize `FileSinkState` into JSON text. This helper is the most direct export path for file sink diagnostics snapshots.
+
+### Interface
+
+```moonbit
+pub fn stringify_file_sink_state(state : FileSinkState, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `state : FileSinkState` - File sink state snapshot to serialize.
+- `pretty : Bool` - Whether JSON should be pretty-printed.
+
+#### output
+
+- `String` - Serialized JSON text for the file sink state.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `pretty=false` returns compact JSON.
+- `pretty=true` returns indented JSON for human diagnostics.
+- This helper builds on top of `file_sink_state_to_json(...)`.
+- The output is well-suited for support dumps, incident reports, and log snapshots.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Human-readable File Diagnostics
+
+When file sink status should be printed for operators:
+```moonbit
+println(stringify_file_sink_state(sink.state(), pretty=true))
+```
+
+In this example, the full file-state snapshot is rendered in readable JSON.
+
+#### When Need Compact State Export
+
+When a snapshot should stay small:
+```moonbit
+let text = stringify_file_sink_state(sink.state())
+```
+
+In this example, compact JSON is returned without extra formatting logic.
+
+### Error Case
+
+e.g.:
+- If the file is unavailable, the output still serializes normally with `available=false`.
+
+- If callers need structured composition instead of text, `file_sink_state_to_json(...)` is the better API.
+
+### Notes
+
+1. Use this helper for direct textual file-state snapshots.
+
+2. `pretty=true` is useful for operator-facing diagnostics and support output.

docs/api/stringify-runtime-file-state.md

@@ -0,0 +1,75 @@
+---
+name: stringify-runtime-file-state
+group: api
+category: runtime
+update-time: 20260512
+description: Serialize RuntimeFileState into compact or pretty JSON text for queued-file diagnostics and support output.
+key-word:
+    - runtime
+    - file
+    - state
+    - public
+---
+
+## Stringify-runtime-file-state
+
+Serialize `RuntimeFileState` into JSON text. This helper is the most direct export path for combined file-and-queue runtime diagnostics.
+
+### Interface
+
+```moonbit
+pub fn stringify_runtime_file_state(state : RuntimeFileState, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `state : RuntimeFileState` - Combined file and queue runtime snapshot to serialize.
+- `pretty : Bool` - Whether JSON should be pretty-printed.
+
+#### output
+
+- `String` - Serialized JSON text for the runtime file state.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `pretty=false` returns compact JSON.
+- `pretty=true` returns indented JSON for human diagnostics.
+- This helper builds on top of `runtime_file_state_to_json(...)`.
+- The output is useful when queued file runtime state should be printed directly during support or incident handling.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Human-readable Queued-file Diagnostics
+
+When a queued file runtime snapshot should be printed directly:
+```moonbit
+println(stringify_runtime_file_state(snapshot, pretty=true))
+```
+
+In this example, both file state and queue metrics are shown in one readable JSON payload.
+
+#### When Need Compact Runtime Snapshot Export
+
+When a combined file-and-queue snapshot should stay small:
+```moonbit
+let text = stringify_runtime_file_state(snapshot)
+```
+
+In this example, compact JSON is returned without extra formatting logic.
+
+### Error Case
+
+e.g.:
+- If callers need a `JsonValue` rather than text, `runtime_file_state_to_json(...)` is the better API.
+
+- If queue wrapping is not relevant, `stringify_file_sink_state(...)` may be the simpler API.
+
+### Notes
+
+1. Use this helper when queued-file diagnostics should be emitted as one JSON string.
+
+2. `pretty=true` is useful for support output and manual inspection.