📝 refresh runtime file model docs

docs/api/file-sink-policy.md

@@ -3,7 +3,7 @@ name: file-sink-policy
 group: api
 category: sink
 update-time: 20260613
-description: Public file policy alias used by file sinks and configured runtime file controls.
+description: Public file policy alias used by file sinks and runtime file-control APIs.
 key-word:
     - file
     - policy
@@ -13,7 +13,7 @@ key-word:
 
 ## File-sink-policy
 
-`FileSinkPolicy` is the public policy object used to describe file append mode, auto-flush behavior, and optional rotation settings together. It is a direct alias to the file policy model shared by `FileSink`, `ConfiguredLogger`, and file policy JSON helpers.
+`FileSinkPolicy` is the public policy object used to describe file append mode, auto-flush behavior, and optional rotation settings together. It is a direct alias to the file policy model shared by `FileSink`, `RuntimeSink`, `ConfiguredLogger`, and file policy JSON helpers.
 
 ### Interface
 
@@ -31,8 +31,8 @@ Detailed rules explaining key parameters and behaviors
 
 - This is a type alias, not a separate runtime wrapper.
 - The current policy fields are `append : Bool`, `auto_flush : Bool`, and `rotation : FileRotation?`.
-- The same policy object is returned by `FileSink::policy()` and `ConfiguredLogger::file_policy()`.
+- The same policy object is returned by `FileSink::policy()`, `RuntimeSink::file_policy()`, and `ConfiguredLogger::file_policy()`.
-- It is also accepted by `FileSink::set_policy(...)` and `ConfiguredLogger::file_set_policy(...)`.
+- It is also accepted by `FileSink::set_policy(...)`, `RuntimeSink::file_set_policy(...)`, and `ConfiguredLogger::file_set_policy(...)`.
 
 ### How to Use
 
@@ -55,7 +55,7 @@ In this example, the file policy can be passed around as one typed value instead
 
 When current file behavior should be read, adjusted, and written back:
 ```moonbit
-let policy = logger.file_policy()
+let policy = sink.file_policy()
 let next = FileSinkPolicy::new(
   append=policy.append,
   auto_flush=false,
@@ -63,7 +63,7 @@ let next = FileSinkPolicy::new(
 )
 ```
 
-In this example, the policy object is the handoff boundary for runtime file control.
+In this example, the policy object is the handoff boundary for direct runtime file control.
 
 ### Error Case
 

docs/api/file-sink-state.md

@@ -13,7 +13,7 @@ key-word:
 
 ## File-sink-state
 
-`FileSinkState` is the public snapshot object used to describe the current state of a file sink. It is a direct alias to the file state model returned by `FileSink::state()` and configured runtime file inspection helpers.
+`FileSinkState` is the public snapshot object used to describe the current state of a file sink. It is a direct alias to the file state model returned by `FileSink::state()` and by higher-level runtime file inspection helpers.
 
 ### Interface
 
@@ -32,7 +32,8 @@ Detailed rules explaining key parameters and behaviors
 - This is a type alias, not a live file handle wrapper.
 - The current snapshot fields are `path`, `available`, `append`, `auto_flush`, `rotation`, `open_failures`, `write_failures`, `flush_failures`, and `rotation_failures`.
 - `FileSink::state()` returns this object directly for a concrete file sink.
-- `ConfiguredLogger::file_state()` also returns this type, including fallback snapshots for non-file runtime sinks.
+- `RuntimeSink::file_state()` also returns this type, including fallback snapshots for non-file runtime sinks.
+- `ConfiguredLogger::file_state()` returns the same snapshot type through the config-built runtime wrapper.
 
 ### How to Use
 

docs/api/runtime-file-state.md

@@ -3,7 +3,7 @@ name: runtime-file-state
 group: api
 category: runtime
 update-time: 20260613
-description: Public combined file-and-queue runtime state alias used by configured logger diagnostics.
+description: Public combined file-and-queue runtime state alias used by runtime file diagnostics.
 key-word:
     - runtime
     - file
@@ -13,7 +13,7 @@ key-word:
 
 ## Runtime-file-state
 
-`RuntimeFileState` is the public snapshot object that combines file state with queue runtime context for configured loggers. It is a direct alias to the runtime model used by configured file diagnostics and JSON export helpers.
+`RuntimeFileState` is the public snapshot object that combines file state with queue runtime context for file-backed runtime diagnostics. It is a direct alias to the runtime model used by `RuntimeSink`, `ConfiguredLogger`, and JSON export helpers.
 
 ### Interface
 
@@ -31,7 +31,7 @@ Detailed rules explaining key parameters and behaviors
 
 - This is a type alias, not a live runtime controller.
 - The current fields are `file : FileSinkState`, `queued : Bool`, `pending_count : Int`, and `dropped_count : Int`.
-- This type is returned by `ConfiguredLogger::file_runtime_state()` when the configured sink can expose file runtime context.
+- This type is returned by `RuntimeSink::file_runtime_state()` and by `ConfiguredLogger::file_runtime_state()` when file runtime context is available.
 - It is broader than `FileSinkState` because it also reports whether queue wrapping is involved and how the queue is behaving.
 
 ### How to Use
@@ -40,9 +40,9 @@ Here are some specific examples provided.
 
 #### When Need Combined File And Queue Diagnostics
 
-When a configured logger may wrap a file sink in a queue:
+When a direct runtime sink may wrap a file sink in a queue:
 ```moonbit
-match logger.file_runtime_state() {
+match sink.file_runtime_state() {
   Some(snapshot) => println(snapshot.pending_count)
   None => ()
 }
@@ -54,7 +54,7 @@ In this example, queue backlog can be inspected alongside the embedded file stat
 
 When runtime support output should include both file and queue context:
 ```moonbit
-match logger.file_runtime_state() {
+match sink.file_runtime_state() {
   Some(snapshot) => println(stringify_runtime_file_state(snapshot, pretty=true))
   None => ()
 }
@@ -67,7 +67,7 @@ In this example, one typed object covers both the file snapshot and queue counte
 e.g.:
 - `RuntimeFileState` itself does not have a runtime failure mode.
 
-- If the configured logger is not file-backed, `file_runtime_state()` may return `None` instead of producing this snapshot.
+- If the runtime sink is not file-backed, `file_runtime_state()` may return `None` instead of producing this snapshot.
 
 ### Notes