📝 document remaining sink root types

docs/api/context-sink-type.md

@@ -0,0 +1,75 @@
+---
+name: context-sink-type
+group: api
+category: sink
+update-time: 20260613
+description: Public context sink type used for prepending shared structured fields to records before forwarding.
+key-word:
+    - sink
+    - context
+    - type
+    - public
+---
+
+## Context-sink-type
+
+`ContextSink[S]` is the public context wrapper sink type used for prepending shared structured fields to records before forwarding them to another sink. It is the concrete sink type introduced by logger helpers such as `with_context_fields(...)` and `bind(...)`, and it preserves the wrapped sink type in its type parameter.
+
+### Interface
+
+```moonbit
+pub struct ContextSink[S] {
+  sink : S
+  context_fields : Array[Field]
+}
+```
+
+#### output
+
+- `ContextSink[S]` - Public synchronous sink type that merges shared fields into each record before forwarding it to the wrapped sink.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a public root struct, not a type alias.
+- The current fields are `sink : S` and `context_fields : Array[Field]`.
+- `Logger::with_context_fields(...)` and `Logger::bind(...)` produce logger values whose sink type becomes `ContextSink[S]`.
+- The sink preserves the wrapped sink type `S`, which is useful when typed composition still matters after shared-field injection is introduced.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Context-wrapping Logger
+
+When logging should preserve the shared-field wrapper sink type in the logger:
+```moonbit
+let logger : Logger[ContextSink[ConsoleSink]] = Logger::new(console_sink())
+  .with_context_fields([field("service", "billing")])
+```
+
+In this example, the concrete context wrapper sink remains part of the logger type.
+
+#### When Need Stable Shared Metadata On A Wrapped Sink
+
+When code should keep sink typing explicit after field binding:
+```moonbit
+let worker = Logger::new(console_sink(), target="app")
+  .with_context_fields([field("component", "worker")])
+```
+
+In this example, shared metadata is injected through the context wrapper instead of being repeated on each write call.
+
+### Error Case
+
+e.g.:
+- `ContextSink[S]` itself does not have a runtime failure mode.
+
+- Actual write behavior still depends on the wrapped sink `S`, and duplicate or empty context fields are still forwarded as structured data.
+
+### Notes
+
+1. Use logger helpers such as `with_context_fields(...)` or `bind(...)` when you need a value whose sink type is `ContextSink[S]`.
+
+2. Use the logger-level APIs rather than constructing this sink shape manually in normal calling code.

docs/api/file-sink-type.md

@@ -0,0 +1,84 @@
+---
+name: file-sink-type
+group: api
+category: sink
+update-time: 20260613
+description: Public native file sink type used for file-backed synchronous logging with runtime policy and failure tracking.
+key-word:
+    - sink
+    - file
+    - type
+    - public
+---
+
+## File-sink-type
+
+`FileSink` is the public native file sink type used for file-backed synchronous logging. It is the concrete sink type returned by `file_sink(...)`, and it stores runtime file policy, availability state, formatter behavior, and failure counters.
+
+### Interface
+
+```moonbit
+pub struct FileSink {
+  path : String
+  append : Ref[Bool]
+  default_append : Bool
+  handle : Ref[FileHandle?]
+  formatter : RecordFormatter
+  auto_flush : Ref[Bool]
+  default_auto_flush : Bool
+  rotation : Ref[FileRotation?]
+  default_rotation : FileRotation?
+  open_failures : Ref[Int]
+  write_failures : Ref[Int]
+  flush_failures : Ref[Int]
+  rotation_failures : Ref[Int]
+}
+```
+
+#### output
+
+- `FileSink` - Public native file sink type with runtime policy, state, and failure tracking.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a public root struct, not a type alias.
+- The current fields cover path, append mode, handle state, formatter, auto-flush policy, optional rotation policy, and failure counters.
+- `file_sink(...)` constructs this type directly from path and policy inputs.
+- The type exposes runtime helpers such as `flush()`, `close()`, `reopen()`, `policy()`, `state()`, and failure-counter accessors.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Native File Sink Value
+
+When code should keep the concrete file sink type visible:
+```moonbit
+let sink : FileSink = file_sink("app.log")
+```
+
+In this example, the sink value stays explicit and keeps the file-backed runtime controls available.
+
+#### When Need A Typed File-backed Logger
+
+When logging should preserve the native file sink type in the logger:
+```moonbit
+let logger : Logger[FileSink] = Logger::new(file_sink("app.log"), target="file")
+```
+
+In this example, the concrete file sink remains part of the logger type.
+
+### Error Case
+
+e.g.:
+- `FileSink` itself does not have a runtime failure mode.
+
+- Actual file availability, writes, flushes, and reopen behavior still depend on backend support and filesystem state.
+
+### Notes
+
+1. Use `file_sink(...)` when you need a value of this type.
+
+2. Use `FileSinkState`, `FileSinkPolicy`, and `RuntimeFileState` when you need exported snapshots or higher-level diagnostics rather than the live sink type itself.

docs/api/index.md

@@ -99,6 +99,7 @@ BitLogger API navigation.
 
 ## Sink and file
 
+- [context-sink-type.md](./context-sink-type.md)
 - [console-sink.md](./console-sink.md)
 - [console-sink-type.md](./console-sink-type.md)
 - [json-console-sink.md](./json-console-sink.md)
@@ -126,6 +127,7 @@ BitLogger API navigation.
 - [patch-sink.md](./patch-sink.md)
 - [patch-sink-type.md](./patch-sink-type.md)
 - [file-sink.md](./file-sink.md)
+- [file-sink-type.md](./file-sink-type.md)
 - [native-files-supported.md](./native-files-supported.md)
 - [file-rotation.md](./file-rotation.md)
 - [file-rotation-type.md](./file-rotation-type.md)