From 0877ab02c7ad153ceca0a379452289a4f53bcc2b Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sun, 10 May 2026 13:33:59 +0800
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Add=20file=20policy=20drift=20check?=
 =?UTF-8?q?s?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                      |  2 ++
 bitlogger/BitLogger_test.mbt   |  7 +++++++
 bitlogger/BitLogger_wbtest.mbt |  6 ++++++
 bitlogger/README.mbt.md        |  2 ++
 bitlogger/config.mbt           | 12 ++++++++++++
 bitlogger/sinks.mbt            | 16 ++++++++++++++++
 docs/README-en.md              |  2 ++
 docs/changes/0.3.0.md          |  1 +
 8 files changed, 48 insertions(+)

diff --git a/README.md b/README.md
index 3ee2bf3..44e9312 100644
--- a/README.md
+++ b/README.md
@@ -247,6 +247,7 @@ match logger.file_runtime_state() {
 - `file_sink(...)` 还提供 `rotation_enabled()` 与 `rotation_config()`，可直接查询当前 rotation 策略是否启用及其参数
 - `file_sink(...)` 还提供 `state()`，可一次性读取 path、available、append、auto_flush、rotation 与各类 failure counter 快照
 - `file_sink(...)` 还提供 `policy()` 与 `default_policy()`，可分别读取当前策略与创建时默认策略
+- `file_sink(...)` 还提供 `policy_matches_default()`，可显式判断当前运行期策略是否已偏离默认策略
 - `file_sink(...)` 也支持 `set_policy(...)`，可一次性写回 append/auto_flush/rotation 这组三元策略
 - `file_sink(...)` 还提供 `reset_failure_counters()`，可在完成排障后清空 open/write/flush/rotation 失败计数
 - `file_sink(...)` 还提供 `reset_policy()`，可将 append/auto_flush/rotation 恢复到创建 sink 时的默认策略
@@ -254,6 +255,7 @@ match logger.file_runtime_state() {
 - `build_logger(...)` 产出的 `ConfiguredLogger` 同样提供 `file_reopen()`、`file_reopen_with_current_policy()`、`file_reopen_append()`、`file_reopen_truncate()`、`file_flush()`、`file_close()`、`file_append_mode()`、`file_path()`、`file_auto_flush()`、`file_rotation_enabled()`、`file_rotation_config()`、`file_state()`，以及 `file_set_append_mode(...)`、`file_set_auto_flush(...)`、`file_set_rotation(...)`、`file_clear_rotation()` 与对应 file failure 计数访问器，便于配置式接入后继续运维控制
 - `ConfiguredLogger` 还提供 `file_runtime_state()`，可在 file sink 外层包了 queue 时同时读取底层 file 快照、是否 queue 包装、当前 pending 与 dropped 计数
 - `ConfiguredLogger` 还提供 `file_policy()` 与 `file_default_policy()`，可分别读取当前 file 策略与初始配置策略
+- `ConfiguredLogger` 还提供 `file_policy_matches_default()`，可显式判断当前配置式 file 策略是否偏离默认值
 - `ConfiguredLogger` 也支持 `file_set_policy(...)`，可一次性改写配置式 file sink 的当前运行期策略
 - `ConfiguredLogger` 也支持 `file_reset_failure_counters()`，可在配置式 file sink 上统一清空失败计数
 - `ConfiguredLogger` 也支持 `file_reset_policy()`，可将配置式 file sink 的运行期策略恢复到初始配置
diff --git a/bitlogger/BitLogger_test.mbt b/bitlogger/BitLogger_test.mbt
index aa5c0cb..a827ecc 100644
--- a/bitlogger/BitLogger_test.mbt
+++ b/bitlogger/BitLogger_test.mbt
@@ -337,6 +337,7 @@ test "configured logger file setters update file sink policy state" {
   inspect(default_policy.append, content="true")
   inspect(default_policy.auto_flush, content="true")
   inspect(default_policy.rotation is None, content="true")
+  inspect(logger.file_policy_matches_default(), content="true")
   inspect(logger.file_set_append_mode(false), content="true")
   inspect(logger.file_append_mode(), content="false")
   inspect(logger.file_set_auto_flush(false), content="true")
@@ -363,10 +364,12 @@ test "configured logger file setters update file sink policy state" {
   inspect(policy.append, content="false")
   inspect(policy.auto_flush, content="false")
   inspect(policy.rotation is None, content="true")
+  inspect(logger.file_policy_matches_default(), content="false")
   inspect(logger.file_reset_policy(), content="true")
   inspect(logger.file_append_mode(), content="true")
   inspect(logger.file_auto_flush(), content="true")
   inspect(logger.file_rotation_config() is None, content="true")
+  inspect(logger.file_policy_matches_default(), content="true")
   ignore(logger.close())
 }
 
@@ -385,12 +388,14 @@ test "configured logger reset policy restores configured file defaults" {
   let default_policy = logger.file_default_policy()
   inspect(default_policy.append, content="false")
   inspect(default_policy.auto_flush, content="false")
+  inspect(logger.file_policy_matches_default(), content="true")
   inspect(logger.file_set_append_mode(true), content="true")
   inspect(logger.file_set_auto_flush(true), content="true")
   inspect(logger.file_clear_rotation(), content="true")
   inspect(logger.file_reset_policy(), content="true")
   inspect(logger.file_append_mode(), content="false")
   inspect(logger.file_auto_flush(), content="false")
+  inspect(logger.file_policy_matches_default(), content="true")
   match logger.file_rotation_config() {
     Some(rotation) => {
       inspect(rotation.max_bytes, content="36")
@@ -431,6 +436,7 @@ test "configured logger set policy applies bundled runtime file policy" {
   inspect(default_policy.append, content="true")
   inspect(default_policy.auto_flush, content="true")
   inspect(default_policy.rotation is None, content="true")
+  inspect(logger.file_policy_matches_default(), content="false")
   ignore(logger.close())
 }
 
@@ -440,6 +446,7 @@ test "configured non-file logger cannot reset file policy" {
   inspect(logger.file_policy().append, content="false")
   inspect(logger.file_default_policy().append, content="false")
   inspect(logger.file_set_policy(FileSinkPolicy::new()), content="false")
+  inspect(logger.file_policy_matches_default(), content="false")
 }
 
 test "configured logger can reopen built file sink" {
diff --git a/bitlogger/BitLogger_wbtest.mbt b/bitlogger/BitLogger_wbtest.mbt
index d281ffe..9676298 100644
--- a/bitlogger/BitLogger_wbtest.mbt
+++ b/bitlogger/BitLogger_wbtest.mbt
@@ -137,6 +137,7 @@ test "file sink setters update auto flush and rotation state" {
   inspect(default_policy.append, content="true")
   inspect(default_policy.auto_flush, content="true")
   inspect(default_policy.rotation is None, content="true")
+  inspect(sink.policy_matches_default(), content="true")
   sink.set_append_mode(false)
   inspect(sink.append_mode(), content="false")
   sink.set_auto_flush(false)
@@ -163,10 +164,12 @@ test "file sink setters update auto flush and rotation state" {
   inspect(policy.append, content="false")
   inspect(policy.auto_flush, content="false")
   inspect(policy.rotation is None, content="true")
+  inspect(sink.policy_matches_default(), content="false")
   sink.reset_policy()
   inspect(sink.append_mode(), content="true")
   inspect(sink.auto_flush_enabled(), content="true")
   inspect(sink.rotation_config() is None, content="true")
+  inspect(sink.policy_matches_default(), content="true")
 }
 
 test "file sink reset policy restores configured defaults" {
@@ -182,9 +185,11 @@ test "file sink reset policy restores configured defaults" {
   let default_policy = sink.default_policy()
   inspect(default_policy.append, content="false")
   inspect(default_policy.auto_flush, content="false")
+  inspect(sink.policy_matches_default(), content="false")
   sink.reset_policy()
   inspect(sink.append_mode(), content="false")
   inspect(sink.auto_flush_enabled(), content="false")
+  inspect(sink.policy_matches_default(), content="true")
   match sink.rotation_config() {
     Some(rotation) => {
       inspect(rotation.max_bytes, content="24")
@@ -217,6 +222,7 @@ test "file sink set policy applies bundled runtime policy" {
   inspect(default_policy.append, content="true")
   inspect(default_policy.auto_flush, content="true")
   inspect(default_policy.rotation is None, content="true")
+  inspect(sink.policy_matches_default(), content="false")
 }
 
 test "file sink tracks rotation failures on unavailable backend" {
diff --git a/bitlogger/README.mbt.md b/bitlogger/README.mbt.md
index 093d88f..ced5a41 100644
--- a/bitlogger/README.mbt.md
+++ b/bitlogger/README.mbt.md
@@ -243,6 +243,7 @@ test {
 - `rotation_enabled()` and `rotation_config()` expose whether rotation is active and which settings are currently applied / `rotation_enabled()` 与 `rotation_config()` 可读取 rotation 是否启用及当前配置参数
 - `state()` exposes a single file-sink snapshot including path, availability, append policy, auto-flush, rotation config, and failure counters / `state()` 可一次性读取包含 path、availability、append、auto-flush、rotation 配置与失败计数的 file sink 快照
 - `policy()` and `default_policy()` expose the current runtime policy and the sink's original defaults separately / `policy()` 与 `default_policy()` 可分别读取当前运行期策略与 sink 初始默认策略
+- `policy_matches_default()` explicitly tells whether the current runtime policy has drifted from the defaults / `policy_matches_default()` 可显式判断当前运行期策略是否已偏离默认策略
 - `set_policy(...)` applies append, auto-flush, and rotation as a bundled runtime update / `set_policy(...)` 可将 append、auto-flush、rotation 作为一组运行期策略一次性写回
 - `reset_failure_counters()` clears the open/write/flush/rotation counters after diagnostics or recovery / `reset_failure_counters()` 可在排障或恢复后清空 open/write/flush/rotation 失败计数
 - `reset_policy()` restores append, auto-flush, and rotation back to the sink's original defaults / `reset_policy()` 可将 append、auto-flush、rotation 恢复到 sink 初始默认策略
@@ -252,6 +253,7 @@ test {
 - `ConfiguredLogger` also forwards file reopen, flush, close, append-mode, path, auto-flush, rotation-config, state snapshot, append setter, policy setter, and failure-counter helpers for config-built file sinks / `ConfiguredLogger` 也会为配置生成的 file sink 转发 reopen、flush、close、append-mode、path、auto-flush、rotation 配置、state 快照、append setter、策略 setter 与失败计数访问器
 - `ConfiguredLogger::file_runtime_state()` also reports whether a file sink is queue-wrapped and exposes the outer queue pending/drop counters together with the inner file snapshot / `ConfiguredLogger::file_runtime_state()` 还可报告 file sink 是否被 queue 包装，并将外层 queue 的 pending/drop 计数与内层 file 快照一起返回
 - `ConfiguredLogger::file_policy()` and `ConfiguredLogger::file_default_policy()` also expose current runtime policy and initial config policy separately / `ConfiguredLogger::file_policy()` 与 `ConfiguredLogger::file_default_policy()` 也可分别读取当前运行期策略与初始配置策略
+- `ConfiguredLogger::file_policy_matches_default()` also tells whether the current runtime file policy has drifted from the default config / `ConfiguredLogger::file_policy_matches_default()` 也可显式判断当前运行期 file 策略是否已偏离默认配置
 - `ConfiguredLogger::file_set_policy()` also applies a bundled runtime file policy through the config-built control surface / `ConfiguredLogger::file_set_policy()` 也可通过配置式控制面一次性写回 bundled file 策略
 - `ConfiguredLogger::file_reset_failure_counters()` also clears file failure counters through the config-built control surface / `ConfiguredLogger::file_reset_failure_counters()` 也可通过配置式控制面清空 file 失败计数
 - `ConfiguredLogger::file_reset_policy()` also restores runtime file policy back to the initial config values / `ConfiguredLogger::file_reset_policy()` 也可将运行期 file 策略恢复到初始配置值
diff --git a/bitlogger/config.mbt b/bitlogger/config.mbt
index faba432..4097c60 100644
--- a/bitlogger/config.mbt
+++ b/bitlogger/config.mbt
@@ -528,6 +528,14 @@ pub fn RuntimeSink::file_default_policy(self : RuntimeSink) -> FileSinkPolicy {
   }
 }
 
+pub fn RuntimeSink::file_policy_matches_default(self : RuntimeSink) -> Bool {
+  match self {
+    File(sink) => sink.policy_matches_default()
+    QueuedFile(sink) => sink.sink.policy_matches_default()
+    _ => false
+  }
+}
+
 pub fn RuntimeSink::file_state(self : RuntimeSink) -> FileSinkState {
   match self {
     File(sink) => sink.state()
@@ -686,6 +694,10 @@ pub fn ConfiguredLogger::file_default_policy(self : ConfiguredLogger) -> FileSin
   self.sink.file_default_policy()
 }
 
+pub fn ConfiguredLogger::file_policy_matches_default(self : ConfiguredLogger) -> Bool {
+  self.sink.file_policy_matches_default()
+}
+
 pub fn ConfiguredLogger::file_state(self : ConfiguredLogger) -> FileSinkState {
   self.sink.file_state()
 }
diff --git a/bitlogger/sinks.mbt b/bitlogger/sinks.mbt
index a8976bc..657c2cc 100644
--- a/bitlogger/sinks.mbt
+++ b/bitlogger/sinks.mbt
@@ -268,6 +268,22 @@ pub fn FileSink::default_policy(self : FileSink) -> FileSinkPolicy {
   )
 }
 
+pub fn FileSink::policy_matches_default(self : FileSink) -> Bool {
+  let current = self.policy()
+  let default = self.default_policy()
+  current.append == default.append &&
+  current.auto_flush == default.auto_flush &&
+  policy_rotation_equals_internal(current.rotation, default.rotation)
+}
+
+fn policy_rotation_equals_internal(left : FileRotation?, right : FileRotation?) -> Bool {
+  match (left, right) {
+    (None, None) => true
+    (Some(a), Some(b)) => a.max_bytes == b.max_bytes && a.max_backups == b.max_backups
+    _ => false
+  }
+}
+
 pub fn FileSink::state(self : FileSink) -> FileSinkState {
   {
     path: self.path,
diff --git a/docs/README-en.md b/docs/README-en.md
index b026e3c..e8406ca 100644
--- a/docs/README-en.md
+++ b/docs/README-en.md
@@ -231,6 +231,7 @@ match logger.file_runtime_state() {
 - `file_sink(...)` also exposes `rotation_enabled()` and `rotation_config()` for reading whether rotation is active and which parameters are currently in effect.
 - `file_sink(...)` also exposes `state()` for reading a single snapshot that includes path, availability, append policy, auto-flush flag, rotation config, and all current failure counters.
 - `file_sink(...)` also exposes `policy()` and `default_policy()` for reading the current runtime policy and the sink's original default policy separately.
+- `file_sink(...)` also exposes `policy_matches_default()` for explicitly checking whether the current runtime policy has drifted from the original defaults.
 - `file_sink(...)` also exposes `set_policy(...)` for applying append, auto-flush, and rotation as a single bundled runtime policy update.
 - `file_sink(...)` also exposes `reset_failure_counters()` so open/write/flush/rotation failure counters can be cleared after diagnostics or recovery handling.
 - `file_sink(...)` also exposes `reset_policy()` so append, auto-flush, and rotation settings can be restored to the sink's original defaults.
@@ -238,6 +239,7 @@ match logger.file_runtime_state() {
 - `ConfiguredLogger` built through `build_logger(...)` also exposes `file_reopen()`, `file_reopen_with_current_policy()`, `file_reopen_append()`, `file_reopen_truncate()`, `file_flush()`, `file_close()`, `file_append_mode()`, `file_path()`, `file_auto_flush()`, `file_rotation_enabled()`, `file_rotation_config()`, `file_state()`, plus `file_set_append_mode(...)`, `file_set_auto_flush(...)`, `file_set_rotation(...)`, `file_clear_rotation()`, and the corresponding file failure counters, so config-driven file logging keeps a usable control surface.
 - `ConfiguredLogger` also exposes `file_runtime_state()` so queued file loggers can report both the underlying file snapshot and the outer queue backlog/drop state in one read.
 - `ConfiguredLogger` also exposes `file_policy()` and `file_default_policy()` for reading current runtime file policy and initial config policy separately.
+- `ConfiguredLogger` also exposes `file_policy_matches_default()` for explicitly checking whether the current runtime file policy differs from its default config.
 - `ConfiguredLogger` also exposes `file_set_policy(...)` for applying a bundled runtime file policy through the config-built control surface.
 - `ConfiguredLogger` also exposes `file_reset_failure_counters()` for clearing file failure counters through the config-built control surface.
 - `ConfiguredLogger` also exposes `file_reset_policy()` for restoring runtime file policy back to the initial config values.
diff --git a/docs/changes/0.3.0.md b/docs/changes/0.3.0.md
index 240bbc6..806b03d 100644
--- a/docs/changes/0.3.0.md
+++ b/docs/changes/0.3.0.md
@@ -46,6 +46,7 @@ version 0.3.0
 - feat: add `reset_policy()` / `file_reset_policy()` so runtime append, auto-flush, and rotation settings can be restored to their initial defaults
 - feat: add `policy()` / `default_policy()` and configured-logger forwarding helpers so current runtime file policy and original defaults can be read explicitly
 - feat: add `set_policy()` / `file_set_policy()` so bundled append, auto-flush, and rotation policy can be applied in one runtime operation
+- feat: add `policy_matches_default()` / `file_policy_matches_default()` so runtime file policy drift can be checked explicitly
 - feat: add `SplitSink`, `split_sink(...)`, and `split_by_level(...)` for routing records into different sinks by predicate or level
 - feat: add `Logger::bind(...)` as an ergonomic context-binding alias and `fields(...)` helper for tuple-based field construction