✨ add bounded history sink (#1)

docs/api/history-sink-capacity.md

@@ -0,0 +1,19 @@
+---
+name: history-sink-capacity
+group: api
+category: sink
+update-time: 20260811
+description: Read the normalized retention capacity of a HistorySink.
+key-word:
+    - sink
+    - history
+    - capacity
+---
+
+## History-sink-capacity
+
+```moonbit
+pub fn HistorySink::capacity(self : HistorySink) -> Int
+```
+
+Returns the positive retention limit selected when the sink was constructed.

docs/api/history-sink-clear.md

@@ -0,0 +1,20 @@
+---
+name: history-sink-clear
+group: api
+category: sink
+update-time: 20260811
+description: Clear a HistorySink and reset its eviction counter.
+key-word:
+    - sink
+    - history
+    - clear
+---
+
+## History-sink-clear
+
+```moonbit
+pub fn HistorySink::clear(self : HistorySink) -> Unit
+```
+
+Clears all retained records and resets `dropped_count()` to zero. It does not
+close the sink; subsequent records begin a new history session.

docs/api/history-sink-count.md

@@ -0,0 +1,19 @@
+---
+name: history-sink-count
+group: api
+category: sink
+update-time: 20260811
+description: Read the number of records currently retained by a HistorySink.
+key-word:
+    - sink
+    - history
+    - count
+---
+
+## History-sink-count
+
+```moonbit
+pub fn HistorySink::count(self : HistorySink) -> Int
+```
+
+Returns the current retained-record count, which never exceeds `capacity()`.

docs/api/history-sink-dropped-count.md

@@ -0,0 +1,20 @@
+---
+name: history-sink-dropped-count
+group: api
+category: sink
+update-time: 20260811
+description: Read the number of oldest records evicted from a HistorySink.
+key-word:
+    - sink
+    - history
+    - dropped
+---
+
+## History-sink-dropped-count
+
+```moonbit
+pub fn HistorySink::dropped_count(self : HistorySink) -> Int
+```
+
+Returns the cumulative number of records evicted because the bounded history was
+full. `clear()` resets this count for the new history session.

docs/api/history-sink-snapshot.md

@@ -0,0 +1,20 @@
+---
+name: history-sink-snapshot
+group: api
+category: sink
+update-time: 20260811
+description: Copy the retained records from a HistorySink in chronological order.
+key-word:
+    - sink
+    - history
+    - snapshot
+---
+
+## History-sink-snapshot
+
+```moonbit
+pub fn HistorySink::snapshot(self : HistorySink) -> Array[Record]
+```
+
+Returns copied records ordered from oldest to newest. Later writes and mutation
+of the returned array do not change the retained history.

docs/api/history-sink-type.md

@@ -0,0 +1,31 @@
+---
+name: history-sink-type
+group: api
+category: sink
+update-time: 20260811
+description: Public bounded in-memory record sink used for diagnostic history.
+key-word:
+    - sink
+    - history
+    - type
+---
+
+## History-sink-type
+
+`HistorySink` is the concrete synchronous sink returned by `history_sink(...)`.
+It retains copied `Record` values in memory and implements `Sink`.
+
+### Interface
+
+```moonbit
+pub struct HistorySink {
+  records : Ref[Array[Record]]
+  capacity : Int
+  dropped_count : Ref[Int]
+}
+```
+
+### Notes
+
+Use `snapshot()` for retained records and the count helpers for bounded-history
+observability. The type does not perform persistence or background work.

docs/api/history-sink.md

@@ -0,0 +1,45 @@
+---
+name: history-sink
+group: api
+category: sink
+update-time: 20260811
+description: Create a bounded in-memory sink that retains the latest structured records.
+key-word:
+    - sink
+    - history
+    - memory
+    - diagnostics
+---
+
+## History-sink
+
+Create a synchronous in-memory sink for bounded diagnostic history. It retains
+the newest records and does not write to a file, console, or network endpoint.
+
+### Interface
+
+```moonbit
+pub fn history_sink(capacity? : Int = 128) -> HistorySink
+```
+
+### Explanation
+
+- `capacity` is normalized to at least `1`; the default keeps the latest `128`
+  records.
+- When full, the oldest record is evicted and `dropped_count()` increases.
+- `snapshot()` returns records ordered from oldest to newest. `clear()` starts a
+  new in-memory history session.
+
+### How to Use
+
+```moonbit
+let history = history_sink(capacity=64)
+let logger = Logger::new(history, target="desktop")
+logger.info("runtime ready")
+let records = history.snapshot()
+```
+
+### Notes
+
+`HistorySink` is synchronous and application-owned. Serialize or persist a
+snapshot explicitly when needed.