✨ Add file sink rotation and retention

docs/README-en.md

@@ -24,7 +24,7 @@ BitLogger currently provides:
 - bounded backlog with `QueueOverflowPolicy::DropNewest` and `QueueOverflowPolicy::DropOldest`
 - configurable text formatting via `text_formatter(...)`, `format_text(...)`, `text_console_sink(...)`, and template-driven `template` output
 - formatter-based callback integration via `formatted_callback_sink(...)`
-- native-only file output via `file_sink(...)`
+- native-only file output via `file_sink(...)`, with basic size rotation and backup retention
 - `native_files_supported()` for backend capability detection
 - default global logger helpers
 
@@ -151,7 +151,10 @@ Native file sink:
 
 ```moonbit
 if native_files_supported() {
-  let logger = Logger::new(file_sink("bitlogger.log"), target="file")
+  let logger = Logger::new(
+    file_sink("bitlogger.log", rotation=Some(file_rotation(128, max_backups=2))),
+    target="file",
+  )
   logger.info("hello", fields=[field("kind", "file")])
   ignore(logger.sink.flush())
   ignore(logger.sink.close())
@@ -171,7 +174,8 @@ if native_files_supported() {
 ## Config Notes
 
 - BitLogger now includes a JSON config layer via `parse_logger_config_text(...)`, `stringify_logger_config(...)`, and `build_logger(...)`.
-- Supported keys include `min_level`, `target`, `timestamp`, `sink.kind`, `sink.path`, `sink.append`, `sink.auto_flush`, `sink.text_formatter`, and `queue`.
+- Supported keys include `min_level`, `target`, `timestamp`, `sink.kind`, `sink.path`, `sink.append`, `sink.auto_flush`, `sink.rotation`, `sink.text_formatter`, and `queue`.
+- `sink.rotation` currently supports `max_bytes` and `max_backups` for basic size-based rotation and backup retention.
 - `sink.text_formatter.template` currently supports fixed tokens: `{timestamp}`, `{timestamp_ms}`, `{level}`, `{target}`, `{message}`, and `{fields}`.
 - Config-driven sink assembly currently supports `console`, `json_console`, `text_console`, and `file`.
 - `queue` remains a synchronous bounded wrapper around the final sink, not an async runtime.

docs/changes/0.3.0.md

@@ -27,6 +27,8 @@ version 0.3.0
 - feat: use `maria/json_parser` as the first external dependency for practical config loading
 - feat: add `TextFormatter.template` and `TextFormatterConfig.template` for template-driven text rendering
 - feat: support formatter tokens `{timestamp}`, `{timestamp_ms}`, `{level}`, `{target}`, `{message}`, and `{fields}` in both runtime and JSON config paths
+- feat: add `FileRotation`, `file_rotation(...)`, and size-based file rotation with retained backups for `file_sink(...)`
+- feat: support `sink.rotation.max_bytes` and `sink.rotation.max_backups` in JSON logger config
 
 ### Test
 
@@ -37,6 +39,7 @@ version 0.3.0
 - test: cover partial drain behavior for config-built queued logger
 - test: cover dropped-count reporting for bounded config-built queue
 - test: cover template-based formatter rendering and disabled token behavior
+- test: cover file rotation config parsing, config roundtrip, and native rotation behavior
 - test: add async logger lifecycle, config roundtrip, and batching/flush policy test seeds
 - build: verify `bitlogger_async --target native` and `examples/async_basic --target native` compile successfully
 
@@ -48,6 +51,7 @@ version 0.3.0
 - docs: update `examples/async_basic` to use unified JSON-driven async logger config
 - docs: update root README, English README, and Mooncake README with config usage notes
 - docs: update formatter examples to demonstrate template-based text rendering
+- docs: update file sink examples to demonstrate rotation and backup retention
 - docs: update root README and English README with async adapter notes and current scope
 - chore: ignore local `.mooncakes/` cache directory in git
 
@@ -55,5 +59,6 @@ version 0.3.0
 
 - current config scope is still intentionally constrained to stable built-in sink shapes
 - formatter templates are intentionally limited to simple token replacement and do not yet include conditional blocks or alignment/padding controls
+- current file rotation scope is intentionally limited to size-based rename retention and does not yet include time rotation or compression
 - queue wrapping remains synchronous drain-based delivery, not async runtime scheduling
 - async logging remains an isolated adapter layer and currently targets `native/llvm` only