✨ add bounded history sink (#1)

docs/README-en.md

@@ -18,7 +18,7 @@ The documentation is organized around complete usage flows. Start with an execut
 ```bash
 moon new log-demo
 cd log-demo
-moon add Nanaloveyuki/BitLogger@0.7.3
+moon add Nanaloveyuki/BitLogger@0.8.0
 ```
 
 ### 2. Import And Log

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.

docs/changes/1.2.0(0.8.0).md

@@ -0,0 +1,15 @@
+## BitLogger Update Changes
+
+version 1.2.0(0.8.0)
+
+### Changes
+
+- Add a bounded in-memory HistorySink for retaining the latest structured records.
+
+### Verification
+
+- Run formatting, warning-denied checks and tests, API generation, documentation build, and packaged-output validation.
+
+### Notes
+
+- HistorySink is synchronous and memory-only; persistence and export remain application-owned.

docs/changes/index.md

@@ -2,6 +2,7 @@
 
 Versioned BitLogger change summaries.
 
+- [1.2.0](./1.2.0(0.8.0).md)
 - [1.1.3](./1.1.3(0.7.3).md)
 - [1.1.2](./1.1.2(0.7.2).md)
 - [1.1.1](./1.1.1(0.7.1).md)

docs/examples/console.md

@@ -5,7 +5,7 @@ Use this flow for command-line tools and services that need a human-readable sta
 ## Install And Import
 
 ```bash
-moon add Nanaloveyuki/BitLogger@0.7.3
+moon add Nanaloveyuki/BitLogger@0.8.0
 ```
 
 ```moonbit

docs/zh/examples/console.md

@@ -7,7 +7,7 @@
 ```bash
 moon new log-demo
 cd log-demo
-moon add Nanaloveyuki/BitLogger@0.7.3
+moon add Nanaloveyuki/BitLogger@0.8.0
 ```
 
 在应用的 `moon.pkg` 中加入：