From 1c83cf2ba1885fa5241842f229839a586a951156 Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sat, 13 Jun 2026 22:52:29 +0800
Subject: [PATCH] :memo: document runtime file state constructor

---
 docs/api/index.md                  |  1 +
 docs/api/runtime-file-state-new.md | 92 ++++++++++++++++++++++++++++++
 2 files changed, 93 insertions(+)
 create mode 100644 docs/api/runtime-file-state-new.md

diff --git a/docs/api/index.md b/docs/api/index.md
index ac1b958..8e061f7 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -184,6 +184,7 @@ BitLogger API navigation.
 - [file-sink-state-to-json.md](./file-sink-state-to-json.md)
 - [file-sink-state.md](./file-sink-state.md)
 - [stringify-file-sink-state.md](./stringify-file-sink-state.md)
+- [runtime-file-state-new.md](./runtime-file-state-new.md)
 - [runtime-file-state-to-json.md](./runtime-file-state-to-json.md)
 - [runtime-file-state.md](./runtime-file-state.md)
 - [stringify-runtime-file-state.md](./stringify-runtime-file-state.md)
diff --git a/docs/api/runtime-file-state-new.md b/docs/api/runtime-file-state-new.md
new file mode 100644
index 0000000..40b1863
--- /dev/null
+++ b/docs/api/runtime-file-state-new.md
@@ -0,0 +1,92 @@
+---
+name: runtime-file-state-new
+group: api
+category: runtime
+update-time: 20260613
+description: Construct a RuntimeFileState snapshot from explicit file state and queue-runtime values.
+key-word:
+    - runtime
+    - file
+    - state
+    - public
+---
+
+## Runtime-file-state-new
+
+Construct a `RuntimeFileState` snapshot from explicit file state and queue-runtime values. This is the low-level constructor behind the public combined file-and-queue runtime state shape used in diagnostics.
+
+### Interface
+
+```moonbit
+pub fn RuntimeFileState::new(
+  file : FileSinkState,
+  queued~ : Bool = false,
+  pending_count~ : Int = 0,
+  dropped_count~ : Int = 0,
+) -> RuntimeFileState {
+```
+
+#### input
+
+- `file : FileSinkState` - Embedded file sink snapshot.
+- `queued : Bool` - Whether queue wrapping is involved for the runtime file sink.
+- `pending_count : Int` - Current queued backlog count.
+- `dropped_count : Int` - Current dropped-record count.
+
+#### output
+
+- `RuntimeFileState` - Combined runtime snapshot containing the supplied file snapshot plus queue metadata.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Omitting optional arguments builds a non-queued baseline around the supplied file snapshot.
+- This constructor simply packages the supplied fields into one public runtime snapshot value.
+- It does not inspect a live configured logger by itself.
+- `ConfiguredLogger::file_runtime_state()` is the higher-level API that reads these values from concrete runtime objects.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Hand-built Combined File And Queue Snapshot
+
+When tests or adapters should construct runtime file diagnostics explicitly:
+```moonbit
+let snapshot = RuntimeFileState::new(
+  FileSinkState::new("app.log", available=true),
+  queued=true,
+  pending_count=3,
+  dropped_count=1,
+)
+```
+
+In this example, the runtime file snapshot is built directly without querying a live configured logger.
+
+#### When Need Structured Runtime Diagnostics Input Before Serialization
+
+When code should prepare a typed runtime file state value for later export:
+```moonbit
+let snapshot = RuntimeFileState::new(
+  logger.file_state(),
+  queued=true,
+  pending_count=logger.pending_count(),
+  dropped_count=logger.dropped_count(),
+)
+```
+
+In this example, callers still use the direct constructor while making each queue-related input explicit.
+
+### Error Case
+
+e.g.:
+- This constructor itself does not have a normal failure mode; it only packages the provided values.
+
+- If callers want a snapshot directly from a live configured logger, `file_runtime_state()` is the simpler API.
+
+### Notes
+
+1. Use this helper when code should construct a `RuntimeFileState` value explicitly.
+
+2. Pair it with `runtime_file_state_to_json(...)` or `stringify_runtime_file_state(...)` when the snapshot should be exported.