📝 Fix policy test and doc

2026-07-24 00:42:18 +00:00 · 2026-07-07 10:28:16 +08:00
parent 46e87403bf
commit 0e02f3d2cf
20 changed files with 844 additions and 60 deletions
@@ -2,7 +2,7 @@
 name: configured-logger-file-available
 group: api
 category: runtime
-update-time: 20260512
+update-time: 20260707
 description: Read whether the configured runtime logger currently has an available file sink behind its runtime sink shape.
 key-word:
    - logger
@@ -36,6 +36,8 @@ Detailed rules explaining key parameters and behaviors
 - File-backed runtime sinks report actual file availability through the wrapped `RuntimeSink`.
 - Queued file sinks still expose the availability of their wrapped inner file sink.
 - Non-file sinks report `false`.
+- This means `false` currently merges two different situations: “not file-backed” and “file-backed but currently unavailable”.
+- Use `file_path_or_none()`, `file_policy_or_none()`, `file_default_policy_or_none()`, `file_state_or_none()`, or `file_runtime_state()` when callers need truthful file-semantics detection.
 - This helper delegates to the runtime sink and does not mutate logger state.

 ### How to Use
@@ -67,10 +69,12 @@ In this example, callers can decide whether a recovery action is needed.
 e.g.:
 - If the configured sink is not file-backed, the method returns `false`.

- If callers need detailed failure counters rather than a simple availability flag, `file_state()` or `file_runtime_state()` is the better API.
+- If callers need to distinguish “not file-backed” from “file-backed but unavailable”, use one of the truthful `*_or_none()` helpers or `file_runtime_state()`.
+
+- If callers need detailed failure counters rather than a simple availability flag, `file_state_or_none()` or `file_runtime_state()` is the better API.

 ### Notes

 1. Use this helper for lightweight file sink health checks.

-2. Pair it with reopen and failure-counter APIs when diagnosing file sink problems.
+2. Pair it with reopen and failure-counter APIs when diagnosing file sink problems, but prefer the truthful `*_or_none()` helpers when file semantics themselves must be checked.
@@ -0,0 +1,79 @@
+---
+name: configured-logger-file-default-policy-or-none
+group: api
+category: runtime
+update-time: 20260707
+description: Read the default runtime file policy from a ConfiguredLogger only when it is actually file-backed.
+key-word:
+    - logger
+    - runtime
+    - file
+    - truthful
+---
+
+## Configured-logger-file-default-policy-or-none
+
+Read the default runtime file policy from a `ConfiguredLogger` only when it is actually file-backed.
+
+This is the truthful companion to `file_default_policy()`. Prefer it when default-policy inspection should not fabricate a fallback object on non-file sinks.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_default_policy_or_none(self : ConfiguredLogger) -> FileSinkPolicy? {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose default file policy should be inspected.
+
+#### output
+
+- `FileSinkPolicy?` - `Some(policy)` when the configured sink is file-backed, otherwise `None`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks return `Some(default_policy)` through the wrapped `RuntimeSink`.
+- Queued file sinks forward the wrapped inner file sink default policy as `Some(default_policy)`.
+- Non-file sinks return `None`.
+- This helper is useful when callers need to compare runtime drift or restore defaults without fabricating file semantics.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Truthful Baseline Policy Visibility
+
+When tooling should inspect defaults only for real file-backed sinks:
+```moonbit
+let defaults = logger.file_default_policy_or_none()
+```
+
+In this example, `None` means the configured logger has no file default policy.
+
+#### When Compare Current And Default Policy Truthfully
+
+When diagnostics should avoid fallback policy objects:
+```moonbit
+match (logger.file_policy_or_none(), logger.file_default_policy_or_none()) {
+  (Some(current), Some(defaults)) => ignore((current, defaults))
+  _ => ()
+}
+```
+
+In this example, comparisons happen only when real file semantics exist.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `None`.
+
+- If callers only need a drift boolean, `file_policy_matches_default()` remains simpler.
+
+### Notes
+
+1. Prefer this helper over `file_default_policy()` for truthful runtime diagnostics.
+
+2. `file_default_policy()` remains available as the compatibility fallback API.
@@ -2,8 +2,8 @@
 name: configured-logger-file-default-policy
 group: api
 category: runtime
-update-time: 20260512
-description: Read the initial default file policy associated with a configured file-backed logger.
+update-time: 20260707
+description: Read the initial default file policy associated with a configured logger, with a compatibility fallback for non-file sinks.
 key-word:
    - logger
    - runtime
@@ -15,6 +15,8 @@ key-word:

 Read the initial default file policy associated with a `ConfiguredLogger`. This helper exposes the baseline file policy captured when the runtime sink was created.

+`file_default_policy()` is the compatibility form. For truthful file-semantics detection, prefer `file_default_policy_or_none()`.
+
 ### Interface

 ```moonbit
@@ -36,6 +38,8 @@ Detailed rules explaining key parameters and behaviors
 - File-backed sinks return the default policy captured at creation time through the wrapped `RuntimeSink`.
 - Queued file sinks forward the default policy from the wrapped inner file sink.
 - Non-file sinks return the same neutral fallback policy value produced by `RuntimeSink::file_default_policy()`.
+- This fallback keeps older callers source-compatible, but it is not a real file default policy.
+- New diagnostic or recovery code should prefer `file_default_policy_or_none()`.
 - This helper is useful when callers need to compare runtime drift or restore defaults later.

 ### How to Use
@@ -65,10 +69,12 @@ In this example, callers can reason about “factory” file policy separately f
 e.g.:
 - If the configured sink is not file-backed, the return value is a neutral fallback policy.

+- If callers need a truthful file-semantics check, use `file_default_policy_or_none()`.
+
 - If callers only need to know whether runtime drift exists, `file_policy_matches_default()` is the simpler API.

 ### Notes

 1. Use this helper when the original file policy matters operationally.

-2. It complements `file_policy()` and `file_reset_policy()`.
+2. It complements `file_policy()` and `file_reset_policy()`, while `file_default_policy_or_none()` is the truthful diagnostic form.
@@ -0,0 +1,79 @@
+---
+name: configured-logger-file-path-or-none
+group: api
+category: runtime
+update-time: 20260707
+description: Read the effective file path from a ConfiguredLogger only when it is actually file-backed.
+key-word:
+    - logger
+    - runtime
+    - file
+    - truthful
+---
+
+## Configured-logger-file-path-or-none
+
+Read the effective file path from a `ConfiguredLogger` only when it is actually file-backed.
+
+This is the truthful companion to `file_path()`. Prefer it for diagnostics, branching, and recovery logic that must distinguish “not file-backed” from compatibility fallbacks.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_path_or_none(self : ConfiguredLogger) -> String? {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file path should be inspected.
+
+#### output
+
+- `String?` - `Some(path)` when the configured sink is file-backed, otherwise `None`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks return `Some(path)` through the wrapped `RuntimeSink`.
+- Queued file sinks forward the wrapped inner file sink path as `Some(path)`.
+- Non-file sinks return `None`.
+- This helper is observation-only and does not mutate logger state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Truthful File-backed Detection
+
+When code should branch only if file semantics really exist:
+```moonbit
+match logger.file_path_or_none() {
+  Some(path) => println(path)
+  None => ()
+}
+```
+
+In this example, `None` means the configured logger is not file-backed.
+
+#### When Need Path Diagnostics Without Fallback Values
+
+When support output should avoid compatibility placeholders:
+```moonbit
+let maybe_path = logger.file_path_or_none()
+```
+
+In this example, callers can keep “no file semantics” distinct from a real path.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `None`.
+
+- If callers need the broader file snapshot or queue context, prefer `file_state_or_none()` or `file_runtime_state()`.
+
+### Notes
+
+1. Prefer this helper over `file_path()` for truthful runtime diagnostics.
+
+2. `file_path()` remains available as the compatibility fallback API.
@@ -2,8 +2,8 @@
 name: configured-logger-file-path
 group: api
 category: runtime
-update-time: 20260512
-description: Read the effective file path used by the configured runtime logger when it is file-backed.
+update-time: 20260707
+description: Read the effective file path used by the configured runtime logger, with a compatibility fallback for non-file sinks.
 key-word:
    - logger
    - runtime
@@ -15,6 +15,8 @@ key-word:

 Read the effective file path used by a `ConfiguredLogger`. This helper is useful for diagnostics, support output, and confirming which file-backed runtime sink is active.

+`file_path()` is the compatibility form. For truthful file-semantics detection, prefer `file_path_or_none()`.
+
 ### Interface

 ```moonbit
@@ -36,6 +38,8 @@ Detailed rules explaining key parameters and behaviors
 - File-backed sinks return their current file path through the wrapped `RuntimeSink`.
 - Queued file sinks forward the wrapped inner file sink path.
 - Non-file sinks return an empty string.
+- This fallback keeps older callers source-compatible, but it does not truthfully express whether file semantics exist.
+- New diagnostic code should prefer `file_path_or_none()`.
 - This helper is observation-only and does not modify file state.

 ### How to Use
@@ -65,10 +69,12 @@ In this example, the path can be surfaced without reading broader runtime state.
 e.g.:
 - If the configured sink is not file-backed, the method returns an empty string.

- If callers need richer file status than just the path, `file_state()` or `file_runtime_state()` is the better API.
+- If callers need a truthful file-semantics check, use `file_path_or_none()`.
+
+- If callers need richer file status than just the path, `file_state_or_none()` or `file_runtime_state()` is the better API.

 ### Notes

 1. Use this helper for direct runtime path visibility.

-2. Empty string usually means the configured sink is not file-backed.
+2. Empty string is a compatibility fallback; `file_path_or_none()` is the recommended truthful API.
@@ -0,0 +1,79 @@
+---
+name: configured-logger-file-policy-or-none
+group: api
+category: runtime
+update-time: 20260707
+description: Read the current runtime file policy from a ConfiguredLogger only when it is actually file-backed.
+key-word:
+    - logger
+    - runtime
+    - file
+    - truthful
+---
+
+## Configured-logger-file-policy-or-none
+
+Read the current runtime file policy from a `ConfiguredLogger` only when it is actually file-backed.
+
+This is the truthful companion to `file_policy()`. Prefer it for diagnostics and recovery logic that must avoid fallback policy objects.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_policy_or_none(self : ConfiguredLogger) -> FileSinkPolicy? {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose current file policy should be inspected.
+
+#### output
+
+- `FileSinkPolicy?` - `Some(policy)` when the configured sink is file-backed, otherwise `None`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks return `Some(current_policy)` through the wrapped `RuntimeSink`.
+- Queued file sinks forward the wrapped inner file sink policy as `Some(current_policy)`.
+- Non-file sinks return `None`.
+- This helper is broader than `file_append_mode()` or `file_auto_flush()` because it returns the whole policy object without fallback synthesis.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Truthful Policy Diagnostics
+
+When diagnostics should inspect file policy only if file semantics exist:
+```moonbit
+match logger.file_policy_or_none() {
+  Some(policy) => ignore(policy)
+  None => ()
+}
+```
+
+In this example, `None` means there is no real file policy to inspect.
+
+#### When Need Compatibility-free Recovery Decisions
+
+When recovery logic should not treat a fallback object as real state:
+```moonbit
+let maybe_policy = logger.file_policy_or_none()
+```
+
+In this example, callers can distinguish missing file semantics from a live policy snapshot.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `None`.
+
+- If callers need default-policy comparison, pair it with `file_default_policy_or_none()`.
+
+### Notes
+
+1. Prefer this helper over `file_policy()` for truthful runtime diagnostics.
+
+2. `file_policy()` remains available as the compatibility fallback API.
@@ -2,8 +2,8 @@
 name: configured-logger-file-policy
 group: api
 category: runtime
-update-time: 20260512
-description: Read the current runtime file policy from a configured file-backed logger.
+update-time: 20260707
+description: Read the current runtime file policy from a configured logger, with a compatibility fallback for non-file sinks.
 key-word:
    - logger
    - runtime
@@ -15,6 +15,8 @@ key-word:

 Read the current runtime file policy from a `ConfiguredLogger`. This helper exposes the active append, auto-flush, and rotation settings as one policy object.

+`file_policy()` is the compatibility form. For truthful file-semantics detection, prefer `file_policy_or_none()`.
+
 ### Interface

 ```moonbit
@@ -36,6 +38,8 @@ Detailed rules explaining key parameters and behaviors
 - File-backed sinks return their current runtime file policy through the wrapped `RuntimeSink`.
 - Queued file sinks forward the policy from the wrapped inner file sink.
 - Non-file sinks return the same neutral fallback policy value produced by `RuntimeSink::file_policy()`.
+- This fallback keeps older callers source-compatible, but it is not a real file policy.
+- New diagnostic or recovery code should prefer `file_policy_or_none()`.
 - This helper is broader than `file_append_mode()` or `file_auto_flush()` because it returns the whole policy object.

 ### How to Use
@@ -66,10 +70,12 @@ In this example, callers can compare current runtime settings with the initial p
 e.g.:
 - If the configured sink is not file-backed, the return value is a neutral fallback policy rather than a real active file policy.

+- If callers need a truthful file-semantics check, use `file_policy_or_none()`.
+
 - If callers only need one field from the policy, a narrower helper may be simpler.

 ### Notes

 1. Use this helper when file policy should be handled as one object.

-2. Pair it with `file_set_policy(...)` for roundtrip-style policy management.
+2. Pair it with `file_set_policy(...)` for roundtrip-style policy management, or prefer `file_policy_or_none()` for truthful diagnostics.
@@ -0,0 +1,79 @@
+---
+name: configured-logger-file-state-or-none
+group: api
+category: runtime
+update-time: 20260707
+description: Read the current file sink snapshot from a ConfiguredLogger only when it is actually file-backed.
+key-word:
+    - logger
+    - runtime
+    - file
+    - truthful
+---
+
+## Configured-logger-file-state-or-none
+
+Read the current file sink snapshot from a `ConfiguredLogger` only when it is actually file-backed.
+
+This is the truthful companion to `file_state()`. Prefer it when diagnostics or recovery logic must not confuse fallback snapshots with real file state.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_state_or_none(self : ConfiguredLogger) -> FileSinkState? {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file state snapshot should be inspected.
+
+#### output
+
+- `FileSinkState?` - `Some(snapshot)` when the configured sink is file-backed, otherwise `None`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks return `Some(live_snapshot)` through the wrapped `RuntimeSink`.
+- Queued file sinks forward the wrapped inner file sink snapshot as `Some(live_snapshot)`.
+- Non-file sinks return `None`.
+- This helper is broader than individual counters or policy reads because it returns the aggregated file snapshot without fallback synthesis.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Truthful File Health Diagnostics
+
+When support output should include file state only for real file-backed sinks:
+```moonbit
+match logger.file_state_or_none() {
+  Some(state) => println(stringify_file_sink_state(state, pretty=true))
+  None => ()
+}
+```
+
+In this example, no compatibility snapshot is fabricated for non-file sinks.
+
+#### When Need State Without Queue Expansion
+
+When code only needs the file snapshot and not queue metadata:
+```moonbit
+let maybe_state = logger.file_state_or_none()
+```
+
+In this example, `None` cleanly signals missing file semantics.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `None`.
+
+- If callers also need queue metrics for queued file sinks, prefer `file_runtime_state()`.
+
+### Notes
+
+1. Prefer this helper over `file_state()` for truthful runtime diagnostics.
+
+2. `file_state()` remains available as the compatibility fallback API.
@@ -2,8 +2,8 @@
 name: configured-logger-file-state
 group: api
 category: runtime
-update-time: 20260512
-description: Read the current file sink snapshot from a configured runtime logger.
+update-time: 20260707
+description: Read the current file sink snapshot from a configured runtime logger, with a compatibility fallback for non-file sinks.
 key-word:
    - logger
    - runtime
@@ -15,6 +15,8 @@ key-word:

 Read the current file sink snapshot from a `ConfiguredLogger`. This helper exposes path, availability, policy flags, rotation config, and failure counters as one object.

+`file_state()` is the compatibility form. For truthful file-semantics detection, prefer `file_state_or_none()`.
+
 ### Interface

 ```moonbit
@@ -36,6 +38,8 @@ Detailed rules explaining key parameters and behaviors
 - File-backed sinks return a live snapshot of file state.
 - Queued file sinks forward the snapshot from the wrapped inner file sink.
 - Non-file sinks return the same fallback empty-style state produced by `RuntimeSink::file_state()`, with an empty path, disabled policy flags, no rotation, and zeroed counters.
+- This fallback keeps older callers source-compatible, but it is not a live file-backed snapshot.
+- New diagnostic or recovery code should prefer `file_state_or_none()`.
 - This helper is broader than individual file counters or policy accessors because it aggregates core file status into one read.

 ### How to Use
@@ -65,10 +69,12 @@ In this example, the configured logger snapshot can be exported directly through
 e.g.:
 - If the configured sink is not file-backed, the returned snapshot is a fallback empty-style state rather than a live file view.

+- If callers need a truthful file-semantics check, use `file_state_or_none()`.
+
 - If callers also need queue context for queued file sinks, `file_runtime_state()` is the richer API.

 ### Notes

 1. Use this helper for the main one-shot file status snapshot.

-2. Prefer it over individual counters when broader file diagnostics are needed.
+2. Prefer `file_state_or_none()` or `file_runtime_state()` when broader truthful diagnostics are needed.
@@ -366,6 +366,7 @@ BitLogger API navigation.
 - [runtime-sink-pending-count.md](./runtime-sink-pending-count.md)
 - [runtime-sink-dropped-count.md](./runtime-sink-dropped-count.md)
 - [runtime-sink-file-path.md](./runtime-sink-file-path.md)
+- [runtime-sink-file-path-or-none.md](./runtime-sink-file-path-or-none.md)
 - [runtime-sink-file-available.md](./runtime-sink-file-available.md)
 - [runtime-sink-file-reopen.md](./runtime-sink-file-reopen.md)
 - [runtime-sink-file-reopen-with-current-policy.md](./runtime-sink-file-reopen-with-current-policy.md)
@@ -389,9 +390,12 @@ BitLogger API navigation.
 - [runtime-sink-file-reset-failure-counters.md](./runtime-sink-file-reset-failure-counters.md)
 - [runtime-sink-file-reset-policy.md](./runtime-sink-file-reset-policy.md)
 - [runtime-sink-file-policy.md](./runtime-sink-file-policy.md)
+- [runtime-sink-file-policy-or-none.md](./runtime-sink-file-policy-or-none.md)
 - [runtime-sink-file-default-policy.md](./runtime-sink-file-default-policy.md)
+- [runtime-sink-file-default-policy-or-none.md](./runtime-sink-file-default-policy-or-none.md)
 - [runtime-sink-file-policy-matches-default.md](./runtime-sink-file-policy-matches-default.md)
 - [runtime-sink-file-state.md](./runtime-sink-file-state.md)
+- [runtime-sink-file-state-or-none.md](./runtime-sink-file-state-or-none.md)
 - [runtime-sink-file-runtime-state.md](./runtime-sink-file-runtime-state.md)
 - [configured-logger.md](./configured-logger.md)
 - [configured-logger-flush.md](./configured-logger-flush.md)
@@ -404,10 +408,14 @@ BitLogger API navigation.

 - [configured-logger-file-available.md](./configured-logger-file-available.md)
 - [configured-logger-file-path.md](./configured-logger-file-path.md)
+- [configured-logger-file-path-or-none.md](./configured-logger-file-path-or-none.md)
 - [configured-logger-file-state.md](./configured-logger-file-state.md)
+- [configured-logger-file-state-or-none.md](./configured-logger-file-state-or-none.md)
 - [configured-logger-file-runtime-state.md](./configured-logger-file-runtime-state.md)
 - [configured-logger-file-policy.md](./configured-logger-file-policy.md)
+- [configured-logger-file-policy-or-none.md](./configured-logger-file-policy-or-none.md)
 - [configured-logger-file-default-policy.md](./configured-logger-file-default-policy.md)
+- [configured-logger-file-default-policy-or-none.md](./configured-logger-file-default-policy-or-none.md)
 - [configured-logger-file-policy-matches-default.md](./configured-logger-file-policy-matches-default.md)
 - [configured-logger-file-rotation-config.md](./configured-logger-file-rotation-config.md)
 - [configured-logger-file-rotation-enabled.md](./configured-logger-file-rotation-enabled.md)
@@ -2,7 +2,7 @@
 name: runtime-sink-file-available
 group: api
 category: runtime
-update-time: 20260613
+update-time: 20260707
 description: Read whether a RuntimeSink currently has an available file sink behind its runtime sink shape.
 key-word:
    - runtime
@@ -36,6 +36,8 @@ Detailed rules explaining key parameters and behaviors
 - Plain `File` runtime variants report actual file availability.
 - `QueuedFile` runtime variants expose the availability of their wrapped inner file sink.
 - Non-file runtime variants return `false`.
+- This means `false` currently merges two different situations: “not file-backed” and “file-backed but currently unavailable”.
+- Use `file_path_or_none()`, `file_policy_or_none()`, `file_default_policy_or_none()`, `file_state_or_none()`, or `file_runtime_state()` when callers need truthful file-semantics detection.
 - This helper does not mutate runtime sink state.

 ### How to Use
@@ -67,10 +69,12 @@ In this example, callers can decide whether a recovery action is needed.
 e.g.:
 - If the runtime sink is not file-backed, the method returns `false`.

- If callers need detailed failure counters rather than a simple availability flag, `file_state()` or `file_runtime_state()` is the better API.
+- If callers need to distinguish “not file-backed” from “file-backed but unavailable”, use one of the truthful `*_or_none()` helpers or `file_runtime_state()`.
+
+- If callers need detailed failure counters rather than a simple availability flag, `file_state_or_none()` or `file_runtime_state()` is the better API.

 ### Notes

 1. Use this helper for lightweight file sink health checks on direct `RuntimeSink` values.

-2. Pair it with reopen and failure-counter APIs when diagnosing file sink problems.
+2. Pair it with reopen and failure-counter APIs when diagnosing file sink problems, but prefer the truthful `*_or_none()` helpers when file semantics themselves must be checked.
@@ -0,0 +1,79 @@
+---
+name: runtime-sink-file-default-policy-or-none
+group: api
+category: runtime
+update-time: 20260707
+description: Read the default runtime file policy from a RuntimeSink only when it is actually file-backed.
+key-word:
+    - runtime
+    - sink
+    - file
+    - truthful
+---
+
+## Runtime-sink-file-default-policy-or-none
+
+Read the default runtime file policy from a `RuntimeSink` only when it is actually file-backed.
+
+This is the truthful companion to `file_default_policy()`. Prefer it when default-policy inspection should not fabricate a fallback object on non-file sinks.
+
+### Interface
+
+```moonbit
+pub fn RuntimeSink::file_default_policy_or_none(self : RuntimeSink) -> FileSinkPolicy? {
+```
+
+#### input
+
+- `self : RuntimeSink` - Runtime sink whose default file policy should be inspected.
+
+#### output
+
+- `FileSinkPolicy?` - `Some(policy)` when the runtime sink is file-backed, otherwise `None`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain `File` runtime variants return `Some(default_policy)`.
+- `QueuedFile` runtime variants forward the wrapped inner file sink default policy as `Some(default_policy)`.
+- Non-file runtime variants return `None`.
+- This helper is useful when callers need to compare runtime drift or restore defaults without fabricating file semantics.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Truthful Baseline Policy Visibility
+
+When tooling should inspect defaults only for real file-backed sinks:
+```moonbit
+let defaults = sink.file_default_policy_or_none()
+```
+
+In this example, `None` means the runtime sink has no file default policy.
+
+#### When Compare Current And Default Policy Truthfully
+
+When diagnostics should avoid fallback policy objects:
+```moonbit
+match (sink.file_policy_or_none(), sink.file_default_policy_or_none()) {
+  (Some(current), Some(defaults)) => ignore((current, defaults))
+  _ => ()
+}
+```
+
+In this example, comparisons happen only when real file semantics exist.
+
+### Error Case
+
+e.g.:
+- If the runtime sink is not file-backed, the method returns `None`.
+
+- If callers only need a drift boolean, `file_policy_matches_default()` remains simpler.
+
+### Notes
+
+1. Prefer this helper over `file_default_policy()` for truthful runtime diagnostics.
+
+2. `file_default_policy()` remains available as the compatibility fallback API.
@@ -0,0 +1,79 @@
+---
+name: runtime-sink-file-path-or-none
+group: api
+category: runtime
+update-time: 20260707
+description: Read the effective file path from a RuntimeSink only when it is actually file-backed.
+key-word:
+    - runtime
+    - sink
+    - file
+    - truthful
+---
+
+## Runtime-sink-file-path-or-none
+
+Read the effective file path from a `RuntimeSink` only when it is actually file-backed.
+
+This is the truthful companion to `file_path()`. Prefer it for diagnostics, branching, and recovery logic that must distinguish “not file-backed” from compatibility fallbacks.
+
+### Interface
+
+```moonbit
+pub fn RuntimeSink::file_path_or_none(self : RuntimeSink) -> String? {
+```
+
+#### input
+
+- `self : RuntimeSink` - Runtime sink whose file path should be inspected.
+
+#### output
+
+- `String?` - `Some(path)` when the runtime sink is file-backed, otherwise `None`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain `File` runtime variants return `Some(path)`.
+- `QueuedFile` runtime variants forward the wrapped inner file sink path as `Some(path)`.
+- Non-file runtime variants return `None`.
+- This helper is observation-only and does not mutate runtime state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Truthful File-backed Detection
+
+When code should branch only if file semantics really exist:
+```moonbit
+match sink.file_path_or_none() {
+  Some(path) => println(path)
+  None => ()
+}
+```
+
+In this example, `None` means the runtime sink is not file-backed.
+
+#### When Need Path Diagnostics Without Fallback Values
+
+When support output should avoid compatibility placeholders:
+```moonbit
+let maybe_path = sink.file_path_or_none()
+```
+
+In this example, callers can keep “no file semantics” distinct from a real path.
+
+### Error Case
+
+e.g.:
+- If the runtime sink is not file-backed, the method returns `None`.
+
+- If callers need the broader file snapshot or queue context, prefer `file_state_or_none()` or `file_runtime_state()`.
+
+### Notes
+
+1. Prefer this helper over `file_path()` for truthful runtime diagnostics.
+
+2. `file_path()` remains available as the compatibility fallback API.
@@ -2,8 +2,8 @@
 name: runtime-sink-file-path
 group: api
 category: runtime
-update-time: 20260613
-description: Read the effective file path used by a file-backed RuntimeSink.
+update-time: 20260707
+description: Read the effective file path used by a file-backed RuntimeSink, with a compatibility fallback for non-file sinks.
 key-word:
    - runtime
    - sink
@@ -15,6 +15,8 @@ key-word:

 Read the effective file path used by a file-backed `RuntimeSink`. This helper is useful for diagnostics, support output, and confirming which direct runtime file sink is active.

+`file_path()` is the compatibility form. For truthful file-semantics detection, prefer `file_path_or_none()`.
+
 ### Interface

 ```moonbit
@@ -36,6 +38,8 @@ Detailed rules explaining key parameters and behaviors
 - Plain `File` runtime variants return their current file path.
 - `QueuedFile` runtime variants forward the wrapped inner file sink path.
 - Non-file runtime variants return an empty string.
+- This fallback keeps older callers source-compatible, but it does not distinguish “not file-backed” from “file-backed with an empty-looking value”.
+- New diagnostic code should prefer `file_path_or_none()` when it must avoid fallback values.
 - This helper is observation-only and does not modify file state.

 ### How to Use
@@ -65,10 +69,12 @@ In this example, the path can be surfaced without reading broader runtime state.
 e.g.:
 - If the runtime sink is not file-backed, the method returns an empty string.

- If callers need richer file status than just the path, `file_state()` or `file_runtime_state()` is the better API.
+- If callers need a truthful file-semantics check, use `file_path_or_none()`.
+
+- If callers need richer file status than just the path, `file_state_or_none()` or `file_runtime_state()` is the better API.

 ### Notes

 1. Use this helper for direct runtime path visibility on `RuntimeSink` values.

-2. Empty string usually means the runtime sink is not file-backed.
+2. Empty string is a compatibility fallback; `file_path_or_none()` is the recommended truthful API.
@@ -0,0 +1,79 @@
+---
+name: runtime-sink-file-policy-or-none
+group: api
+category: runtime
+update-time: 20260707
+description: Read the current runtime file policy from a RuntimeSink only when it is actually file-backed.
+key-word:
+    - runtime
+    - sink
+    - file
+    - truthful
+---
+
+## Runtime-sink-file-policy-or-none
+
+Read the current runtime file policy from a `RuntimeSink` only when it is actually file-backed.
+
+This is the truthful companion to `file_policy()`. Prefer it for diagnostics and recovery logic that must avoid fallback policy objects.
+
+### Interface
+
+```moonbit
+pub fn RuntimeSink::file_policy_or_none(self : RuntimeSink) -> FileSinkPolicy? {
+```
+
+#### input
+
+- `self : RuntimeSink` - Runtime sink whose current file policy should be inspected.
+
+#### output
+
+- `FileSinkPolicy?` - `Some(policy)` when the runtime sink is file-backed, otherwise `None`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain `File` runtime variants return `Some(current_policy)`.
+- `QueuedFile` runtime variants forward the wrapped inner file sink policy as `Some(current_policy)`.
+- Non-file runtime variants return `None`.
+- This helper is broader than `file_append_mode()` or `file_auto_flush()` because it returns the whole policy object without fallback synthesis.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Truthful Policy Diagnostics
+
+When diagnostics should inspect file policy only if file semantics exist:
+```moonbit
+match sink.file_policy_or_none() {
+  Some(policy) => ignore(policy)
+  None => ()
+}
+```
+
+In this example, `None` means there is no real file policy to inspect.
+
+#### When Need Compatibility-free Recovery Decisions
+
+When recovery logic should not treat a fallback object as real state:
+```moonbit
+let maybe_policy = sink.file_policy_or_none()
+```
+
+In this example, callers can distinguish missing file semantics from a live policy snapshot.
+
+### Error Case
+
+e.g.:
+- If the runtime sink is not file-backed, the method returns `None`.
+
+- If callers need default-policy comparison, pair it with `file_default_policy_or_none()`.
+
+### Notes
+
+1. Prefer this helper over `file_policy()` for truthful runtime diagnostics.
+
+2. `file_policy()` remains available as the compatibility fallback API.
@@ -2,8 +2,8 @@
 name: runtime-sink-file-policy
 group: api
 category: runtime
-update-time: 20260613
-description: Read the current runtime file policy from a RuntimeSink.
+update-time: 20260707
+description: Read the current runtime file policy from a RuntimeSink, with a compatibility fallback for non-file sinks.
 key-word:
    - runtime
    - sink
@@ -15,6 +15,8 @@ key-word:

 Read the current runtime file policy from a `RuntimeSink`. This helper exposes the active append, auto-flush, and rotation settings as one policy object.

+`file_policy()` is the compatibility form. For truthful file-semantics detection, prefer `file_policy_or_none()`.
+
 ### Interface

 ```moonbit
@@ -36,6 +38,8 @@ Detailed rules explaining key parameters and behaviors
 - Plain `File` runtime variants return the current policy from the wrapped `FileSink`.
 - `QueuedFile` runtime variants forward the policy from the wrapped inner `FileSink`.
 - Non-file runtime variants return the neutral fallback policy `FileSinkPolicy::new(append=false, auto_flush=false, rotation=None)`.
+- This fallback keeps older callers source-compatible, but it is not a real file policy.
+- New diagnostic or recovery code should prefer `file_policy_or_none()`.
 - This helper is broader than `file_append_mode()` or `file_auto_flush()` because it returns the whole policy object.

 ### How to Use
@@ -66,10 +70,12 @@ In this example, callers can compare current runtime settings with the initial p
 e.g.:
 - If the runtime sink is not file-backed, the return value is a neutral fallback policy rather than a real active file policy.

+- If callers need a truthful file-semantics check, use `file_policy_or_none()`.
+
 - If callers only need one field from the policy, a narrower helper may be simpler.

 ### Notes

 1. Use this helper when file policy should be handled as one object.

-2. Pair it with `file_set_policy(...)` for roundtrip-style policy management.
+2. Pair it with `file_set_policy(...)` for roundtrip-style policy management, or prefer `file_policy_or_none()` for truthful diagnostics.
@@ -0,0 +1,79 @@
+---
+name: runtime-sink-file-state-or-none
+group: api
+category: runtime
+update-time: 20260707
+description: Read the current file sink snapshot from a RuntimeSink only when it is actually file-backed.
+key-word:
+    - runtime
+    - sink
+    - file
+    - truthful
+---
+
+## Runtime-sink-file-state-or-none
+
+Read the current file sink snapshot from a `RuntimeSink` only when it is actually file-backed.
+
+This is the truthful companion to `file_state()`. Prefer it when diagnostics or recovery logic must not confuse fallback snapshots with real file state.
+
+### Interface
+
+```moonbit
+pub fn RuntimeSink::file_state_or_none(self : RuntimeSink) -> FileSinkState? {
+```
+
+#### input
+
+- `self : RuntimeSink` - Runtime sink whose file state snapshot should be inspected.
+
+#### output
+
+- `FileSinkState?` - `Some(snapshot)` when the runtime sink is file-backed, otherwise `None`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain `File` runtime variants return `Some(live_snapshot)`.
+- `QueuedFile` runtime variants forward the wrapped inner file sink snapshot as `Some(live_snapshot)`.
+- Non-file runtime variants return `None`.
+- This helper is broader than individual counters or policy reads because it returns the aggregated file snapshot without fallback synthesis.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Truthful File Health Diagnostics
+
+When support output should include file state only for real file-backed sinks:
+```moonbit
+match sink.file_state_or_none() {
+  Some(state) => println(stringify_file_sink_state(state, pretty=true))
+  None => ()
+}
+```
+
+In this example, no compatibility snapshot is fabricated for non-file sinks.
+
+#### When Need State Without Queue Expansion
+
+When code only needs the file snapshot and not queue metadata:
+```moonbit
+let maybe_state = sink.file_state_or_none()
+```
+
+In this example, `None` cleanly signals missing file semantics.
+
+### Error Case
+
+e.g.:
+- If the runtime sink is not file-backed, the method returns `None`.
+
+- If callers also need queue metrics for queued file sinks, prefer `file_runtime_state()`.
+
+### Notes
+
+1. Prefer this helper over `file_state()` for truthful runtime diagnostics.
+
+2. `file_state()` remains available as the compatibility fallback API.
@@ -2,8 +2,8 @@
 name: runtime-sink-file-state
 group: api
 category: runtime
-update-time: 20260613
-description: Read the current file sink snapshot from a RuntimeSink.
+update-time: 20260707
+description: Read the current file sink snapshot from a RuntimeSink, with a compatibility fallback for non-file sinks.
 key-word:
    - runtime
    - sink
@@ -15,6 +15,8 @@ key-word:

 Read the current file sink snapshot from a `RuntimeSink`. This helper exposes path, availability, policy flags, rotation config, and failure counters as one object.

+`file_state()` is the compatibility form. For truthful file-semantics detection, prefer `file_state_or_none()`.
+
 ### Interface

 ```moonbit
@@ -36,6 +38,8 @@ Detailed rules explaining key parameters and behaviors
 - Plain `File` runtime variants return a live snapshot from the wrapped `FileSink`.
 - `QueuedFile` runtime variants forward the snapshot from the wrapped inner `FileSink`.
 - Non-file runtime variants return a fallback empty-style state with `path=""`, `available=false`, `append=false`, `auto_flush=false`, `rotation=None`, and all failure counters set to `0`.
+- This fallback keeps older callers source-compatible, but it is not a live file-backed snapshot.
+- New diagnostic or recovery code should prefer `file_state_or_none()`.
 - This helper is broader than individual file counters or policy accessors because it aggregates core file status into one read.

 ### How to Use
@@ -65,10 +69,12 @@ In this example, the runtime sink snapshot can be exported directly through exis
 e.g.:
 - If the runtime sink is not file-backed, the returned snapshot is a fallback empty-style state rather than a live file view.

+- If callers need a truthful file-semantics check, use `file_state_or_none()`.
+
 - If callers also need queue context for queued file sinks, `file_runtime_state()` is the richer API.

 ### Notes

 1. Use this helper for the main one-shot file status snapshot.

-2. Prefer it over individual counters when broader file diagnostics are needed.
+2. Prefer `file_state_or_none()` or `file_runtime_state()` when broader truthful diagnostics are needed.
@@ -1034,6 +1034,7 @@ test "runtime sink plain variants use documented fallback counts" {
 test "runtime sink non-file variants expose documented file fallbacks" {
  let sink = RuntimeSink::Console(console_sink())
  inspect(sink.file_available(), content="false")
+  inspect(sink.file_path_or_none() is None, content="true")
  inspect(sink.file_path(), content="")
  inspect(sink.file_append_mode(), content="false")
  inspect(sink.file_auto_flush(), content="false")
@@ -1059,8 +1060,11 @@ test "runtime sink non-file variants expose documented file fallbacks" {
  inspect(sink.file_reset_policy(), content="false")
  inspect(sink.file_flush(), content="false")
  inspect(sink.file_close(), content="false")
+  inspect(sink.file_policy_or_none() is None, content="true")
+  inspect(sink.file_default_policy_or_none() is None, content="true")
  let policy = sink.file_policy()
  let defaults = sink.file_default_policy()
+  inspect(sink.file_state_or_none() is None, content="true")
  let state = sink.file_state()
  inspect(policy.append, content="false")
  inspect(policy.auto_flush, content="false")
@@ -1091,10 +1095,28 @@ test "runtime sink plain file helpers expose direct file state and policy" {
    ),
  )
  inspect(sink.file_available() == native_files_supported(), content="true")
+  match sink.file_path_or_none() {
+    Some(path) => inspect(path, content="runtime-file-helpers.log")
+    None => inspect(false, content="true")
+  }
  inspect(sink.file_path(), content="runtime-file-helpers.log")
  inspect(sink.file_append_mode(), content="true")
  inspect(sink.file_auto_flush(), content="false")
  inspect(sink.file_rotation_enabled(), content="true")
+  match sink.file_default_policy_or_none() {
+    Some(policy) => {
+      inspect(policy.append, content="true")
+      inspect(policy.auto_flush, content="false")
+    }
+    None => inspect(false, content="true")
+  }
+  match sink.file_policy_or_none() {
+    Some(policy) => {
+      inspect(policy.append, content="true")
+      inspect(policy.auto_flush, content="false")
+    }
+    None => inspect(false, content="true")
+  }
  let defaults = sink.file_default_policy()
  let policy = sink.file_policy()
  inspect(defaults.append, content="true")
@@ -1109,6 +1131,14 @@ test "runtime sink plain file helpers expose direct file state and policy" {
    }
    None => inspect(false, content="true")
  }
+  match sink.file_state_or_none() {
+    Some(snapshot) => {
+      inspect(snapshot.path, content="runtime-file-helpers.log")
+      inspect(snapshot.append, content="true")
+      inspect(snapshot.auto_flush, content="false")
+    }
+    None => inspect(false, content="true")
+  }
  let state = sink.file_state()
  inspect(state.path, content="runtime-file-helpers.log")
  inspect(state.available == sink.file_available(), content="true")
@@ -1162,7 +1192,14 @@ test "runtime sink queued file helpers preserve queue-aware file runtime state"
  logger.info("two")
  logger.info("three")
  inspect(sink.file_available() == native_files_supported(), content="true")
+  match sink.file_path_or_none() {
+    Some(path) => inspect(path, content="runtime-queued-file.log")
+    None => inspect(false, content="true")
+  }
  inspect(sink.file_path(), content="runtime-queued-file.log")
+  inspect(sink.file_policy_or_none() is None, content="false")
+  inspect(sink.file_default_policy_or_none() is None, content="false")
+  inspect(sink.file_state_or_none() is None, content="false")
  inspect(sink.pending_count(), content="2")
  inspect(sink.dropped_count(), content="1")
  match sink.file_runtime_state() {
@@ -2034,6 +2071,10 @@ test "configured non-file logger has no file runtime state" {
  let logger = build_logger(
    LoggerConfig::new(sink=SinkConfig::new(kind=SinkKind::Console)),
  )
+  inspect(logger.file_path_or_none() is None, content="true")
+  inspect(logger.file_policy_or_none() is None, content="true")
+  inspect(logger.file_default_policy_or_none() is None, content="true")
+  inspect(logger.file_state_or_none() is None, content="true")
  inspect(logger.file_runtime_state() is None, content="true")
 }

@@ -2045,6 +2086,13 @@ test "configured file logger mirrors backend file capability" {
    ),
  )
  inspect(logger.file_available() == native_files_supported(), content="true")
+  match logger.file_path_or_none() {
+    Some(path) => inspect(path, content="config-capability.log")
+    None => inspect(false, content="true")
+  }
+  inspect(logger.file_policy_or_none() is None, content="false")
+  inspect(logger.file_default_policy_or_none() is None, content="false")
+  inspect(logger.file_state_or_none() is None, content="false")
  if logger.file_available() {
    inspect(logger.file_state().available, content="true")
    ignore(logger.close())
@@ -1,3 +1,12 @@
+///|
+fn runtime_file_sink_internal(sink : RuntimeSink) -> FileSink? {
+  match sink {
+    File(sink) => Some(sink)
+    QueuedFile(sink) => Some(sink.sink)
+    _ => None
+  }
+}
+
 ///|
 pub fn RuntimeSink::file_available(self : RuntimeSink) -> Bool {
  match self {
@@ -73,13 +82,14 @@ pub fn RuntimeSink::file_set_append_mode(
  }
 }

+///|
+pub fn RuntimeSink::file_path_or_none(self : RuntimeSink) -> String? {
+  runtime_file_sink_internal(self).map(fn(sink) { sink.path() })
+}
+
 ///|
 pub fn RuntimeSink::file_path(self : RuntimeSink) -> String {
-  match self {
-    File(sink) => sink.path()
-    QueuedFile(sink) => sink.sink.path()
-    _ => ""
-  }
+  self.file_path_or_none().unwrap_or("")
 }

 ///|
@@ -268,22 +278,30 @@ pub fn RuntimeSink::file_reset_policy(self : RuntimeSink) -> Bool {
  }
 }

+///|
+pub fn RuntimeSink::file_policy_or_none(self : RuntimeSink) -> FileSinkPolicy? {
+  runtime_file_sink_internal(self).map(fn(sink) { sink.policy() })
+}
+
 ///|
 pub fn RuntimeSink::file_policy(self : RuntimeSink) -> FileSinkPolicy {
-  match self {
-    File(sink) => sink.policy()
-    QueuedFile(sink) => sink.sink.policy()
-    _ => FileSinkPolicy::new(append=false, auto_flush=false, rotation=None)
-  }
+  self.file_policy_or_none().unwrap_or(
+    FileSinkPolicy::new(append=false, auto_flush=false, rotation=None),
+  )
+}
+
+///|
+pub fn RuntimeSink::file_default_policy_or_none(
+  self : RuntimeSink,
+) -> FileSinkPolicy? {
+  runtime_file_sink_internal(self).map(fn(sink) { sink.default_policy() })
 }

 ///|
 pub fn RuntimeSink::file_default_policy(self : RuntimeSink) -> FileSinkPolicy {
-  match self {
-    File(sink) => sink.default_policy()
-    QueuedFile(sink) => sink.sink.default_policy()
-    _ => FileSinkPolicy::new(append=false, auto_flush=false, rotation=None)
-  }
+  self.file_default_policy_or_none().unwrap_or(
+    FileSinkPolicy::new(append=false, auto_flush=false, rotation=None),
+  )
 }

 ///|
@@ -295,24 +313,26 @@ pub fn RuntimeSink::file_policy_matches_default(self : RuntimeSink) -> Bool {
  }
 }

+///|
+pub fn RuntimeSink::file_state_or_none(self : RuntimeSink) -> FileSinkState? {
+  runtime_file_sink_internal(self).map(fn(sink) { sink.state() })
+}
+
 ///|
 pub fn RuntimeSink::file_state(self : RuntimeSink) -> FileSinkState {
-  match self {
-    File(sink) => sink.state()
-    QueuedFile(sink) => sink.sink.state()
-    _ =>
-      FileSinkState::new(
-        "",
-        available=false,
-        append=false,
-        auto_flush=false,
-        rotation=None,
-        open_failures=0,
-        write_failures=0,
-        flush_failures=0,
-        rotation_failures=0,
-      )
-  }
+  self.file_state_or_none().unwrap_or(
+    FileSinkState::new(
+      "",
+      available=false,
+      append=false,
+      auto_flush=false,
+      rotation=None,
+      open_failures=0,
+      write_failures=0,
+      flush_failures=0,
+      rotation_failures=0,
+    ),
+  )
 }

 ///|
@@ -375,6 +395,11 @@ pub fn ConfiguredLogger::file_set_append_mode(
  self.sink.file_set_append_mode(append)
 }

+///|
+pub fn ConfiguredLogger::file_path_or_none(self : ConfiguredLogger) -> String? {
+  self.sink.file_path_or_none()
+}
+
 ///|
 pub fn ConfiguredLogger::file_path(self : ConfiguredLogger) -> String {
  self.sink.file_path()
@@ -468,11 +493,25 @@ pub fn ConfiguredLogger::file_reset_policy(self : ConfiguredLogger) -> Bool {
  self.sink.file_reset_policy()
 }

+///|
+pub fn ConfiguredLogger::file_policy_or_none(
+  self : ConfiguredLogger,
+) -> FileSinkPolicy? {
+  self.sink.file_policy_or_none()
+}
+
 ///|
 pub fn ConfiguredLogger::file_policy(self : ConfiguredLogger) -> FileSinkPolicy {
  self.sink.file_policy()
 }

+///|
+pub fn ConfiguredLogger::file_default_policy_or_none(
+  self : ConfiguredLogger,
+) -> FileSinkPolicy? {
+  self.sink.file_default_policy_or_none()
+}
+
 ///|
 pub fn ConfiguredLogger::file_default_policy(
  self : ConfiguredLogger,
@@ -487,6 +526,13 @@ pub fn ConfiguredLogger::file_policy_matches_default(
  self.sink.file_policy_matches_default()
 }

+///|
+pub fn ConfiguredLogger::file_state_or_none(
+  self : ConfiguredLogger,
+) -> FileSinkState? {
+  self.sink.file_state_or_none()
+}
+
 ///|
 pub fn ConfiguredLogger::file_state(self : ConfiguredLogger) -> FileSinkState {
  self.sink.file_state()