📝 refine configured runtime docs

docs/api/configured-logger-close.md

@@ -2,8 +2,8 @@
 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.
+update-time: 20260613
+description: Close the configured runtime logger sink and return whether the wrapped RuntimeSink reported a successful close action.
 key-word:
     - logger
     - runtime
@@ -13,7 +13,7 @@ key-word:
 
 ## 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.
+Close the sink behind a `ConfiguredLogger`. This helper is the configured logger wrapper over `RuntimeSink::close(...)` for config-driven runtime teardown.
 
 ### Interface
 
@@ -27,16 +27,16 @@ pub fn ConfiguredLogger::close(self : ConfiguredLogger) -> Bool {}
 
 #### output
 
-- `Bool` - Whether the underlying runtime sink reported a successful close action.
+- `Bool` - Whether the wrapped `RuntimeSink::close(...)` call 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.
+- This helper delegates directly to `self.sink.close()`.
+- Plain file sinks forward to `FileSink::close()` through `RuntimeSink`.
+- Queue-backed file sinks close the wrapped file sink instead of only the queue wrapper.
+- Console-style sinks and queue-wrapped console-style sinks return `true` as a no-op success because they do not expose a meaningful close step here.
 
 ### How to Use
 
@@ -63,7 +63,7 @@ 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 the configured runtime sink shape 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.
 
@@ -71,4 +71,4 @@ e.g.:
 
 1. This is the generic configured runtime close helper.
 
-2. Prefer file-specific helpers when the sink shape is known to be file-backed.
+2. Prefer file-specific helpers when the configured sink shape is known to be file-backed.

docs/api/configured-logger-drain.md

@@ -2,8 +2,8 @@
 name: configured-logger-drain
 group: api
 category: runtime
-update-time: 20260512
-description: Drain queued work from a configured runtime logger with optional item limits.
+update-time: 20260613
+description: Drain queued work from a configured runtime logger with optional item limits through RuntimeSink.
 key-word:
     - logger
     - runtime
@@ -13,7 +13,7 @@ key-word:
 
 ## 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.
+Drain queued work from a `ConfiguredLogger`. This helper is the configured logger wrapper over `RuntimeSink::drain(...)` when config-driven queue wrapping should be advanced in a controlled, bounded way.
 
 ### Interface
 
@@ -28,16 +28,16 @@ pub fn ConfiguredLogger::drain(self : ConfiguredLogger, max_items~ : Int = -1) -
 
 #### output
 
-- `Int` - Number of drained items.
+- `Int` - Count returned by the wrapped `RuntimeSink::drain(...)` call.
 
 ### 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.
+- This helper delegates directly to `self.sink.drain(max_items=max_items)`.
+- Queue-wrapped sinks forward to the concrete queue sink's `drain(...)` behavior and may drain up to `max_items` records.
+- Plain file sinks fall back to `FileSink::flush()` behavior through `RuntimeSink` and return `1` or `0`.
+- Plain console-style sinks return `0` because they do not own a drainable queue here.
 
 ### How to Use
 
@@ -64,7 +64,7 @@ In this example, the configured runtime logger drains without imposing an item c
 ### Error Case
 
 e.g.:
-- If the runtime sink is not queue-backed, draining may return `0` or follow fallback flush behavior.
+- If the configured runtime sink is not queue-backed, draining may return `0` or follow the plain-file flush fallback.
 
 - If callers only need generic flush semantics, `flush()` may be the simpler API.
 
@@ -72,4 +72,4 @@ e.g.:
 
 1. Prefer this helper when queue progress should be bounded or observable.
 
-2. Use `pending_count()` to inspect remaining backlog after the drain call.
+2. Use `pending_count()` to inspect remaining backlog after the drain call when the configured sink is queue-backed.

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

@@ -2,8 +2,8 @@
 name: configured-logger-dropped-count
 group: api
 category: runtime
-update-time: 20260512
-description: Read the cumulative dropped-record count from a configured runtime logger.
+update-time: 20260613
+description: Read the cumulative dropped-record count from a configured runtime logger through RuntimeSink.
 key-word:
     - logger
     - runtime
@@ -13,7 +13,7 @@ key-word:
 
 ## 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.
+Read the cumulative dropped-record count from a `ConfiguredLogger`. This helper is the configured logger wrapper over `RuntimeSink::dropped_count(...)` when config-driven queue wrapping may discard records under pressure.
 
 ### Interface
 
@@ -27,16 +27,16 @@ pub fn ConfiguredLogger::dropped_count(self : ConfiguredLogger) -> Int {}
 
 #### output
 
-- `Int` - Number of dropped records reported by the runtime sink.
+- `Int` - Number returned by the wrapped `RuntimeSink::dropped_count()` call.
 
 ### 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.
+- This helper delegates directly to `self.sink.dropped_count()`.
+- Queue-backed runtime sink variants return their live dropped-count metric.
+- Plain console and plain file runtime sink variants return `0` because they do not track queued record drops.
+- The counter is cumulative for the lifetime of the concrete runtime sink value owned by the configured logger.
 
 ### How to Use
 
@@ -65,7 +65,7 @@ In this example, the helper exposes the metric needed to compare runtime queue t
 ### Error Case
 
 e.g.:
-- If the logger is not queue-backed, the method simply returns `0`.
+- If the configured 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.
 

docs/api/configured-logger-flush.md

@@ -2,8 +2,8 @@
 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.
+update-time: 20260613
+description: Flush a configured runtime logger and return how many queued or file-backed operations were advanced through RuntimeSink.
 key-word:
     - logger
     - runtime
@@ -13,7 +13,7 @@ key-word:
 
 ## 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.
+Flush a `ConfiguredLogger` and return how much work was advanced. This is the configured logger wrapper over `RuntimeSink::flush(...)` for forcing queued or file-backed output to move forward after config-driven construction.
 
 ### Interface
 
@@ -27,16 +27,16 @@ pub fn ConfiguredLogger::flush(self : ConfiguredLogger) -> Int {}
 
 #### output
 
-- `Int` - Count of flushed or drained items as reported by the runtime sink.
+- `Int` - Count returned by the wrapped `RuntimeSink::flush(...)` call.
 
 ### 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.
+- This helper delegates directly to `self.sink.flush()`.
+- Queue-wrapped sinks forward to the concrete queue sink's `flush()` behavior.
+- Plain file sinks call `FileSink::flush()` through `RuntimeSink` and convert the boolean result into `1` or `0`.
+- Plain console-style sinks return `0` because they do not expose a meaningful buffered flush step here.
 
 ### How to Use
 
@@ -63,7 +63,7 @@ In this example, callers can observe how much work was advanced by the flush req
 ### Error Case
 
 e.g.:
-- If the configured sink has no flushable buffering, the method may simply return `0`.
+- If the configured runtime sink shape has no flushable state, the method may simply return `0`.
 
 - If callers need bounded manual draining rather than generic flush behavior, `drain(...)` is the better API.
 
@@ -71,4 +71,4 @@ e.g.:
 
 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.
+2. The exact return value depends on which `RuntimeSink` variant the configured logger owns.

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

@@ -2,8 +2,8 @@
 name: configured-logger-pending-count
 group: api
 category: runtime
-update-time: 20260512
-description: Read the current queued backlog count from a configured runtime logger.
+update-time: 20260613
+description: Read the current queued backlog count from a configured runtime logger through RuntimeSink.
 key-word:
     - logger
     - runtime
@@ -13,7 +13,7 @@ key-word:
 
 ## Configured-logger-pending-count
 
-Read the current queued backlog count from a `ConfiguredLogger`. This is the direct runtime metric for config-driven queue wrapping.
+Read the current queued backlog count from a `ConfiguredLogger`. This is the configured logger wrapper over `RuntimeSink::pending_count(...)` for config-driven queue metrics.
 
 ### Interface
 
@@ -27,16 +27,16 @@ pub fn ConfiguredLogger::pending_count(self : ConfiguredLogger) -> Int {}
 
 #### output
 
-- `Int` - Current number of pending queued records.
+- `Int` - Current number returned by the wrapped `RuntimeSink::pending_count()` call.
 
 ### Explanation
 
 Detailed rules explaining key parameters and behaviors
 
-- Queue-backed sinks return their live pending count.
-- Non-queued sinks report `0`.
+- This helper delegates directly to `self.sink.pending_count()`.
+- Queue-backed runtime sink variants return their live pending count.
+- Plain console and plain file runtime sink variants return `0` because they do not own a pending queue here.
 - 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
 
@@ -64,7 +64,7 @@ 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 the configured 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.