📝 Add configured logger file runtime API docs

docs/api/configured-logger-file-available.md

@@ -0,0 +1,76 @@
+---
+name: configured-logger-file-available
+group: api
+category: runtime
+update-time: 20260512
+description: Read whether the configured runtime logger currently has an available file sink behind its runtime sink shape.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-available
+
+Read whether a `ConfiguredLogger` currently has an available file sink. This helper is useful for runtime diagnostics and recovery checks after config-driven file logger construction.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_available(self : ConfiguredLogger) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink availability should be inspected.
+
+#### output
+
+- `Bool` - Whether an underlying file sink is available.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed runtime sinks report actual file availability.
+- Non-file sinks report `false`.
+- Queued file sinks still expose the availability of their wrapped file sink.
+- This helper delegates to the runtime sink and does not mutate logger state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Runtime File Health Checks
+
+When operators or code should check file sink readiness:
+```moonbit
+if !logger.file_available() {
+  println("file sink unavailable")
+}
+```
+
+In this example, the configured logger exposes file health directly.
+
+#### When Gate Recovery Logic
+
+When reopen or fallback behavior depends on file availability:
+```moonbit
+let ok = logger.file_available()
+```
+
+In this example, callers can decide whether a recovery action is needed.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers need detailed failure counters rather than a simple availability flag, `file_state()` or `file_runtime_state()` is the better API.
+
+### Notes
+
+1. Use this helper for lightweight file sink health checks.
+
+2. Pair it with reopen and failure-counter APIs when diagnosing file sink problems.

docs/api/configured-logger-file-close.md

@@ -0,0 +1,74 @@
+---
+name: configured-logger-file-close
+group: api
+category: runtime
+update-time: 20260512
+description: Close the file sink behind a configured runtime logger when one is present.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-close
+
+Close the file sink behind a `ConfiguredLogger`. This helper is the file-specific runtime close surface for config-built file loggers.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_close(self : ConfiguredLogger) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink should be closed.
+
+#### output
+
+- `Bool` - Whether the underlying file close succeeded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain file sinks forward directly to file close behavior.
+- Queued file sinks flush queue work before closing the wrapped file sink.
+- Non-file sinks return `false`.
+- This helper is narrower than generic `close()` because it specifically targets file sink shutdown.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need File-specific Runtime Teardown
+
+When a config-built file logger should close its file handle explicitly:
+```moonbit
+ignore(logger.file_close())
+```
+
+In this example, file teardown happens through the configured logger facade.
+
+#### When Need A File-specific Close Result
+
+When application code wants the file close outcome directly:
+```moonbit
+let closed = logger.file_close()
+```
+
+In this example, the result describes file close behavior rather than generic sink close behavior.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers only need generic sink teardown, `close()` is the broader API.
+
+### Notes
+
+1. Prefer this helper when file-backed runtime behavior matters specifically.
+
+2. Queued file sinks may flush pending records before closing the file.

docs/api/configured-logger-file-flush.md

@@ -0,0 +1,74 @@
+---
+name: configured-logger-file-flush
+group: api
+category: runtime
+update-time: 20260512
+description: Flush the file sink behind a configured runtime logger when one is present.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-flush
+
+Flush the file sink behind a `ConfiguredLogger`. This helper is the file-specific runtime flush surface for config-built file loggers.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_flush(self : ConfiguredLogger) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink should be flushed.
+
+#### output
+
+- `Bool` - Whether the underlying file flush succeeded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain file sinks forward directly to file flush behavior.
+- Queued file sinks first flush queued records, then flush the wrapped file sink.
+- Non-file sinks return `false`.
+- This helper is narrower than generic `flush()` because it targets file sink behavior specifically.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Explicit File Durability Steps
+
+When a config-built file logger should flush to disk explicitly:
+```moonbit
+ignore(logger.file_flush())
+```
+
+In this example, the file-backed runtime sink is flushed directly through the configured logger.
+
+#### When Need A File-specific Success Flag
+
+When code should branch on the outcome of a file flush:
+```moonbit
+let ok = logger.file_flush()
+```
+
+In this example, callers can distinguish file flush success from a non-file sink shape.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers want generic queue or sink advancement instead of file-specific behavior, `flush()` is the broader API.
+
+### Notes
+
+1. Prefer this helper when the configured sink is known to be file-backed.
+
+2. Queued file sinks may perform both queue flush and file flush work here.

docs/api/configured-logger-file-path.md

@@ -0,0 +1,74 @@
+---
+name: configured-logger-file-path
+group: api
+category: runtime
+update-time: 20260512
+description: Read the effective file path used by the configured runtime logger when it is file-backed.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-path
+
+Read the effective file path used by a `ConfiguredLogger`. This helper is useful for diagnostics, support output, and confirming which file-backed runtime sink is active.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_path(self : ConfiguredLogger) -> String {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file path should be inspected.
+
+#### output
+
+- `String` - Effective runtime file path, or an empty string for non-file sinks.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks return their current file path.
+- Queued file sinks forward the wrapped file sink path.
+- Non-file sinks return an empty string.
+- This helper is observation-only and does not modify file state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Runtime Path Diagnostics
+
+When diagnostics should show which file is active:
+```moonbit
+println(logger.file_path())
+```
+
+In this example, operators can verify the effective destination path directly.
+
+#### When Build Support Output
+
+When application state dumps should include file destination info:
+```moonbit
+let path = logger.file_path()
+```
+
+In this example, the path can be surfaced without reading broader runtime state.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns an empty string.
+
+- If callers need richer file status than just the path, `file_state()` or `file_runtime_state()` is the better API.
+
+### Notes
+
+1. Use this helper for direct runtime path visibility.
+
+2. Empty string usually means the configured sink is not file-backed.

docs/api/configured-logger-file-reopen.md

@@ -0,0 +1,75 @@
+---
+name: configured-logger-file-reopen
+group: api
+category: runtime
+update-time: 20260512
+description: Reopen the file sink behind a configured runtime logger with an optional append-mode override.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-reopen
+
+Reopen the file sink behind a `ConfiguredLogger`. This helper is useful for recovery flows after file unavailability or policy changes.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_reopen(self : ConfiguredLogger, append~ : Bool? = None) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink 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
+
+- Plain file sinks reopen directly.
+- Queued file sinks forward reopen behavior to the wrapped file sink.
+- `append=None` preserves current reopen policy, while `Some(true/false)` overrides append mode.
+- Non-file sinks return `false`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Recovery After File Failure
+
+When application code should attempt to restore file logging:
+```moonbit
+ignore(logger.file_reopen())
+```
+
+In this example, the configured logger tries to reopen its runtime file sink using current policy.
+
+#### When Need Explicit Append-mode Reopen
+
+When recovery should choose append or truncate behavior explicitly:
+```moonbit
+let ok = logger.file_reopen(append=Some(true))
+```
+
+In this example, reopen behavior is directed by the call site.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers only need the current configured policy, `file_reopen_with_current_policy()` may be the clearer API.
+
+### Notes
+
+1. Use this helper for explicit recovery flows.
+
+2. Pair it with `file_available()` and failure counters when diagnosing reopen behavior.

docs/api/configured-logger-file-runtime-state.md

@@ -0,0 +1,77 @@
+---
+name: configured-logger-file-runtime-state
+group: api
+category: runtime
+update-time: 20260512
+description: Read combined file and queue runtime state from a configured logger when it is backed by a file sink.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-runtime-state
+
+Read combined file and queue runtime state from a `ConfiguredLogger`. This helper is the richest file-specific diagnostics API on config-built runtime loggers.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_runtime_state(self : ConfiguredLogger) -> RuntimeFileState? {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file runtime state should be inspected.
+
+#### output
+
+- `RuntimeFileState?` - Combined file and queue diagnostics when the runtime sink is file-backed, otherwise `None`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks return `Some(RuntimeFileState)`.
+- Queued file sinks include both file status and queue metrics in the returned state.
+- Non-file sinks return `None`.
+- This helper is richer than `file_state()` because it can also surface queued backlog and dropped counts.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Rich File Runtime Diagnostics
+
+When support output should include both file and queue state:
+```moonbit
+let state = logger.file_runtime_state()
+```
+
+In this example, callers can inspect availability, failure counters, and queue metrics together.
+
+#### When Need To Branch On File-backed Runtime Shape
+
+When code should behave differently for file-backed config-built loggers:
+```moonbit
+match logger.file_runtime_state() {
+  Some(state) => ignore(state)
+  None => ()
+}
+```
+
+In this example, the optional return value reflects whether the runtime sink is file-backed.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `None`.
+
+- If callers only need raw file status without queue context, `file_state()` may be the simpler API.
+
+### Notes
+
+1. Use this helper for the richest file-backed runtime diagnostics on config-built loggers.
+
+2. It is especially useful for queued file sinks where file health and queue state both matter.