📝 Add configured logger runtime control API docs

docs/api/configured-logger-close.md

@@ -0,0 +1,74 @@
+---
+name: configured-logger-close
+group: api
+category: runtime
+update-time: 20260512
+description: Close the configured runtime logger sink and return whether the underlying sink reported a close action.
+key-word:
+    - logger
+    - runtime
+    - lifecycle
+    - public
+---
+
+## Configured-logger-close
+
+Close the sink behind a `ConfiguredLogger`. This helper is the config-driven runtime close surface for queue-backed or file-backed sinks.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::close(self : ConfiguredLogger) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose sink should be closed.
+
+#### output
+
+- `Bool` - Whether the underlying runtime sink reported a successful close action.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Queue-backed file sinks close the wrapped file sink.
+- Plain file sinks forward directly to file close behavior.
+- Console-style sinks usually report `true` because they do not have a meaningful close step.
+- This helper delegates to `RuntimeSink::close(...)` through the configured logger wrapper.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Config-driven Runtime Teardown
+
+When a config-built logger should release its sink resources:
+```moonbit
+ignore(logger.close())
+```
+
+In this example, sink teardown happens through the configured logger facade.
+
+#### When Need To Observe Close Outcome
+
+When application code wants a success flag from runtime close behavior:
+```moonbit
+let closed = logger.close()
+```
+
+In this example, callers can branch on the reported close result.
+
+### Error Case
+
+e.g.:
+- If the runtime sink has no real close action, the helper may still return `true` as a no-op success.
+
+- If callers need a file-specific close path with queue flush nuances, `file_close()` may be the better API.
+
+### Notes
+
+1. This is the generic configured runtime close helper.
+
+2. Prefer file-specific helpers when the sink shape is known to be file-backed.

docs/api/configured-logger-drain.md

@@ -0,0 +1,75 @@
+---
+name: configured-logger-drain
+group: api
+category: runtime
+update-time: 20260512
+description: Drain queued work from a configured runtime logger with optional item limits.
+key-word:
+    - logger
+    - runtime
+    - queue
+    - public
+---
+
+## Configured-logger-drain
+
+Drain queued work from a `ConfiguredLogger`. This helper is useful when config-driven queue wrapping should be advanced in a controlled, bounded way.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::drain(self : ConfiguredLogger, max_items~ : Int = -1) -> Int {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose queued work should be drained.
+- `max_items : Int` - Optional upper bound on how many queued items to drain. Negative values mean no explicit bound.
+
+#### output
+
+- `Int` - Number of drained items.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Queue-wrapped sinks may drain up to `max_items` records.
+- For plain file sinks, the runtime falls back to file flush behavior instead of queue draining.
+- For sinks without queue semantics, the result is typically `0`.
+- This helper delegates to `RuntimeSink::drain(...)` through the configured logger wrapper.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Bounded Queue Progress
+
+When queued output should be advanced in chunks:
+```moonbit
+let drained = logger.drain(max_items=16)
+```
+
+In this example, callers limit how much queued work is processed in one step.
+
+#### When Need Full Manual Drain
+
+When the configured queue should be emptied explicitly:
+```moonbit
+ignore(logger.drain())
+```
+
+In this example, the configured runtime logger drains without imposing an item cap.
+
+### Error Case
+
+e.g.:
+- If the runtime sink is not queue-backed, draining may return `0` or follow fallback flush behavior.
+
+- If callers only need generic flush semantics, `flush()` may be the simpler API.
+
+### Notes
+
+1. Prefer this helper when queue progress should be bounded or observable.
+
+2. Use `pending_count()` to inspect remaining backlog after the drain call.

docs/api/configured-logger-dropped-count.md

@@ -0,0 +1,76 @@
+---
+name: configured-logger-dropped-count
+group: api
+category: runtime
+update-time: 20260512
+description: Read the cumulative dropped-record count from a configured runtime logger.
+key-word:
+    - logger
+    - runtime
+    - queue
+    - public
+---
+
+## Configured-logger-dropped-count
+
+Read the cumulative dropped-record count from a `ConfiguredLogger`. This helper is useful when config-driven queue wrapping may discard records under pressure.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::dropped_count(self : ConfiguredLogger) -> Int {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose dropped-record metric should be inspected.
+
+#### output
+
+- `Int` - Number of dropped records reported by the runtime sink.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Queue-backed sinks return their live dropped-count metric.
+- Non-queued sinks report `0`.
+- The counter is cumulative for the runtime sink lifetime.
+- This helper delegates to `RuntimeSink::dropped_count(...)` through the configured logger wrapper.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Loss Visibility On Config-built Queues
+
+When a config-driven queue may discard records:
+```moonbit
+if logger.dropped_count() > 0 {
+  println("configured logger dropped records")
+}
+```
+
+In this example, the runtime logger exposes queue loss without manual sink inspection.
+
+#### When Compare Queue Tuning Changes
+
+When queue overflow policy should be validated operationally:
+```moonbit
+ignore(logger.dropped_count())
+```
+
+In this example, the helper exposes the metric needed to compare runtime queue tuning.
+
+### Error Case
+
+e.g.:
+- If the logger is not queue-backed, the method simply returns `0`.
+
+- If callers need queue shape and file status together, `file_runtime_state()` may carry more useful context for file sinks.
+
+### Notes
+
+1. This helper reports cumulative loss, not the reason for that loss.
+
+2. Pair it with `pending_count()` and queue configuration when investigating pressure.

docs/api/configured-logger-flush.md

@@ -0,0 +1,74 @@
+---
+name: configured-logger-flush
+group: api
+category: runtime
+update-time: 20260512
+description: Flush a configured runtime logger and return how many queued or file-backed operations were advanced.
+key-word:
+    - logger
+    - runtime
+    - flush
+    - public
+---
+
+## Configured-logger-flush
+
+Flush a `ConfiguredLogger` and return how much work was advanced. This is the main runtime helper for forcing queued or file-backed logger output to move forward after config-driven construction.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::flush(self : ConfiguredLogger) -> Int {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose sink should be flushed.
+
+#### output
+
+- `Int` - Count of flushed or drained items as reported by the runtime sink.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- For queue-wrapped sinks, this forwards to the queue drain/flush behavior.
+- For plain file sinks, the return value reflects whether a file flush happened.
+- For plain console-style sinks, the result is typically `0` because there is no meaningful buffered flush step.
+- This helper delegates to `RuntimeSink::flush(...)` through the configured logger wrapper.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Explicit Queue Progress
+
+When config-built queue output should be advanced manually:
+```moonbit
+ignore(logger.flush())
+```
+
+In this example, the configured runtime logger is flushed without reaching into the sink directly.
+
+#### When Need A Post-write Flush Barrier
+
+When a service wants stronger delivery behavior after a burst of writes:
+```moonbit
+let flushed = logger.flush()
+```
+
+In this example, callers can observe how much work was advanced by the flush request.
+
+### Error Case
+
+e.g.:
+- If the configured sink has no flushable buffering, the method may simply return `0`.
+
+- If callers need bounded manual draining rather than generic flush behavior, `drain(...)` is the better API.
+
+### Notes
+
+1. Use this helper after config-driven logger construction when explicit runtime flushing matters.
+
+2. The exact return value depends on the underlying runtime sink shape.

docs/api/configured-logger-pending-count.md

@@ -0,0 +1,75 @@
+---
+name: configured-logger-pending-count
+group: api
+category: runtime
+update-time: 20260512
+description: Read the current queued backlog count from a configured runtime logger.
+key-word:
+    - logger
+    - runtime
+    - queue
+    - public
+---
+
+## Configured-logger-pending-count
+
+Read the current queued backlog count from a `ConfiguredLogger`. This is the direct runtime metric for config-driven queue wrapping.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::pending_count(self : ConfiguredLogger) -> Int {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose queue backlog should be inspected.
+
+#### output
+
+- `Int` - Current number of pending queued records.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Queue-backed sinks return their live pending count.
+- Non-queued sinks report `0`.
+- This is a point-in-time metric and may change immediately after it is read.
+- This helper delegates to `RuntimeSink::pending_count(...)` through the configured logger wrapper.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Configured Queue Backlog Visibility
+
+When a config-built logger should expose queue pressure:
+```moonbit
+let pending = logger.pending_count()
+```
+
+In this example, queue backlog is observed without reaching into the sink internals.
+
+#### When Verify Manual Drain Progress
+
+When drain loops should observe remaining backlog:
+```moonbit
+ignore(logger.drain(max_items=8))
+ignore(logger.pending_count())
+```
+
+In this example, the queue metric helps verify manual drain progress.
+
+### Error Case
+
+e.g.:
+- If the logger is not queue-backed, the method simply returns `0`.
+
+- If callers need richer file-plus-queue state for file sinks, `file_runtime_state()` is the better API.
+
+### Notes
+
+1. Use this helper for simple queue visibility on config-built loggers.
+
+2. Pair it with `dropped_count()` when investigating loss behavior.